# IBM Visualization Data Explorer Programmer's Reference

[ Bottom of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]

## 17.8 Program Control

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.

### Loading programs and macros

`DXLError exDXLBeginMacroDefinition(DXLConnection *conn, const char *mhdr)`
  Defines the beginning of a macro definition. The macro header `*mhdr` specifies the macro name, inputs, and outputs. For example:

      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).

`DXLError exDXLEndMacroDefinition(DXLConnection *conn)`
  Defines the end of a macro definition.

`DXLError DXLLoadVisualProgram(DXLConnection *conn, const char *file)`
  Loads the visual program specified by the file name `*file`. The path to this file is relative to the startup directory of the server. Returns OK or ERROR.

  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.

`DXLError DXLLoadMacroFile(DXLConnection *conn, const char *file);`
  Causes Data Explorer to load the macro contained in file 'file'.

`DXLError DXLLoadMacroDirectory(DXLConnection *conn, const char *dir);`
  Causes Data Explorer to load all macros contained in directory 'dir'.

`DXLError exDXLLoadScript(DXLConnection *conn, const char *file)`
  Loads the specified script (`*file`) and executes it immediately. The path to this file is relative to the startup directory of the server. Returns OK or ERROR.

`DXLError uiDXLLoadConfig(DXLConnection *conn, const char *file)`
  Opens the configuration file specified by its file name (`*file`). The path to this file is relative to the startup directory of the user interface. Returns OK or ERROR.

### Setting Variables

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).

`DXLError DXLSetValue(DXLConnection *conn, const char *varname, const char *value)`
  Sets the global variable specified by `*varname` to the value given in `*value` (double quotation marks--for strings and string lists-- must be escaped with a backslash (\), as in the example below.) Returns OK or ERROR.

  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.

### Retrieving Values Sent From Data Explorer

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.

[ Top of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]
[Data Explorer Documentation | QuickStart Guide | User's Guide | User's Reference | Programmer's Reference | Installation and Configuration Guide ]

[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]

[IBM Home Page | Order | Search | Contact IBM | Legal ]