The following routines allow an application program to open visual programs and configuration files, set inputs and outputs of tools, and set up handlers for objects and values sent by the server to the calling program.
mhdr = "macro SUM(arg1, arg2) -> (sum)"
This routine should be followed by a series of DXLSend commands that send the macro definition, and finally by exDXLEndMacroDefinition (see following).
If this routine is called when the application is communicating directly with the executive, an execution will occur after the visual program is loaded, because visual programs saved by the user interface include a call to the main macro.
DXLink enables a program to set (and retrieve) Data Explorer values in a visual program or macro. It is important to understand the distinction between a Data Explorer object and a Data Explorer value. A Data Explorer object is the basic data structure of the Data Explorer data model (see Chapter 3. "Understanding the Data Model" in IBM Visualization Data Explorer User's Guide). A Data Explorer value is a character representation of a Data Explorer object (as would be used in the scripting language). The following are common examples of Data Explorer values:
string: "123"
integer: 123
scalar: 1.23
vector: [1 2 3]
string list: { "123", "456" }
integer list: { 123, 456 }
scalar list: { 1.23, 4.56 }
vector list: { [1 2 3 ], [4 5 6] }
Not all Data Explorer objects can be represented by strings (e.g., fields and groups).
This function is used primarily to set global variables in a macro and is the mechanism to set "inputs" to a module in a program.
Global variables are variables that have been assigned or referenced outside a macro (the global scope) or are defined by a reference in a nested scope. Variables assigned with a nested scope are considered local. For example, in the following macro, the variables a and b are local to the macro (their first occurrence is an assignment), while c is a global variable (its first occurrence is a reference).
macro foo( ) -> ( )
{
a = "1";
b = c;
. . . .
}
foo( );
See "Variables Used in Macros" in IBM Visualization Data Explorer User's Guide for the rules of scoping variables.
You might use DXLSetValue to control the name of a data set imported with the Import tool, as in the following Data Explorer macro:
macro main( )
{
object = Import(MyFileNameHere);
....
Display(...)
}
The following C code invokes the main macro to import data from the file foobar.dx and render it:
. . . DXLSetValue(conn, "MyFileNameHere", "\"foobar.dx\""); DXLExecuteOnce(conn); . . .
The Data Explorer user interface provides a convenient mechanism for placing global variables in a visual program. The DXLInput tool (see DXLInput in IBM Visualization Data Explorer User's Reference) implements a global variable inside the macro main( ). By changing the label in the Notation field of the DXLInput tool's configuration dialog box, you can change the name of the global variable. This mechanism provides a clean interface between the visual program and the DXLink application. Named DXLInput tools are simply placed in the program and connected to the module input that needs to be controlled from the application. In the preceding example, a DXLInput tool named MyFileNameHere would be connected to the first input of the Import tool. Then, the same piece of C code could be used to control the program.
DXLError DXLSetInteger(DXLConnection *conn, const char *varname, int value)
DXLError DXLSetScalar(DXLConnection *conn, const char *varname,
const double value)
DXLError DXLSetString(DXLConnection *conn, const char *varname,
const char *value)
Set the variable specified by *varname to value (or *value). These are convenience functions that use DXLSetValue. They return OK or ERROR.
The DXLOutput tool provides the means to retrieve values from Data Explorer asynchronously. This tool is used much like the macro Output tool in the Data Explorer user interface. It has two inputs: the first associates a label with an object or value (much like the name of a global variable); the second is the input object to be sent to the DXLink application. Currently, DXLOutput sends only those values that can be represented as strings.
When the module is executed, it communicates its input values to the DXLink application.
In order to retrieve the values in the application, a function must be defined and installed to accept them when they are available. A function is installed as follows:
DXLError DXLSetValueHandler(DXLConnection *c, const char *label,
DXLValueHandler h, const void *data);
where *label is the value of the first input to the corresponding DXLOutput for which the function is being installed. (In the user interface, the label corresponds to the Notation field in the configuration dialog box.) When the labeled value is received, the function, or handler h, is called as follows:
(*h) (c, label, value, data)
where label and data are the values that were passed to DXLSetValueHandler( ); data is a user-defined value, and value is the value being received for the corresponding label. The handler (like message handlers in general) is called when DXLHandlePendingMessages( ) is called and a corresponding message is pending.
The definition of the value-handler function is:
typedef void (*DXLValueHandler)(DXLConnection *conn, const char *label,
const char *value, void *data);
Note: The same handler can be installed for values with different labels. See also DXLRemoveValueHandler().
DXLError DXLRemoveValueHandler(DXLConnection *c, const char *label);
specifies that the value handler (h) for the value *label is to be removed (*label is the name associated with the value that is to be passed to DXLink). Returns OK or ERROR.