IBM Visualization Data Explorer Programmer's Reference

17.6 Messaging System

The primary functionality provided by DXLink is the sending of messages to the server and the handling of messages from the server. Messages sent to the server include the setting of variable values and the initiation or termination of execution. Messages sent from the server and handled by the DXLink library include errors, warnings, variable values, and execution state. For the most part, the message format is hidden in the programming interface.

Sending Messages to the Server

The function DXLSend (see "Messaging Routines") sends specific messages directly to the server. In general, one needs to be sure that the server will either handle the message properly or ignore it. The user interface will ignore most unrecognized messages, while the executive will accept most legal scripting-language commands. "Setting Variables" discusses how an application program can set the value of variables in a visual program.

Other functions may also result in messages to the server. For example, DXLStartDX initiates the connection to the server and manages all the messaging associated with establishing the connection to Data Explorer.

When a function call results in sending a message to the server, DXLink can either synchronize with the server to ensure that the message has been accepted or it can return without receiving an acknowledgment. By default, DXLink is configured to use the latter (asynchronous) method. DXLSetSynchronous sets the synchronization method to be used. DXLSync allows synchronization at specified points in an application that does not use synchronous mode.

Receiving Messages from the Server

DXLink always uses an asynchronous method of handling messages sent from the server to the DXLink application.

DXLHandlePendingMessages must be called when messages are pending and ready to be processed. This function arranges for message handlers to be called for pending messages and it discards any messages that do not have handlers installed. The function DXLIsMessagePending determines whether DXLHandlePendingMessages needs to be called and allows an application to poll the connection to the server for messages that need to be processed.

The function DXLGetSocket is provided for systems with socket support. The returned socket can be used to arrange for the operating system to perform a blocking select( ) command on the socket to determine when there are messages available. This might be used in a scripting application that uses select( ) on both the DXLink socket and the file descriptor corresponding to the input device.

The DXLOutput module can be used to send Data Explorer values from Data Explorer to a DXLink application. For descriptions of both routines, see IBM Visualization Data Explorer User's Reference. For a discussion of Data Explorer values, see "Setting Variables".

X11 Windows: The function DXLInitForXMainLoop provides support for applications built under the X window system. This function should be called before entering the X main event loop; it arranges for DXLHandlePendingMessages to be called automatically when messages are available. See 17.5 , "Initialization and Exit".

Message handlers are called from DXLHandlePendingMessages when the indicated message is encountered. DXLink installs a number of its own message handlers.

The message handler structure is specified by:

typedef void (*DXLMessageHandler)(DXLConnection *conn, const char *msg, void *data);

The packet types for messages are defined as follows:

enum DXLPacketType {
    PACK_INTERRUPT      = 1,
    PACK_MACRODEF       = 4,
    PACK_FOREGROUND     = 5,
    PACK_BACKGROUND     = 6,
    PACK_ERROR          = 7,
    PACK_MESSAGE        = 8,
    PACK_INFO           = 9,
    PACK_LINQUIRY       = 10,
    PACK_LRESPONSE      = 11,
    PACK_COMPLETE       = 19,
    PACK_LINK           = 22
};
typedef enum DXLPacketType DXLPacketTypeEnum;

Messaging Routines

DXLError DXLSetMessageHandler(DXLConnection *conn, DXLPacketTypeEnum type, const char *matchstr, DXLMessageHandler h, const void *data);

Sets a message handler. This routine allows the user to install a message handler for messages of any type. The handler "h" will be called, receiving the pointer "data", whenever the message handling infrastructure receives a message of type "type" containing a message that matches "matchstr".

DXLError DXLRemoveMessageHandler(DXLConnection *conn, DXLPacketTypeEnum type, const char *matchstr, DXLMessageHandler h);

Removes a message handler. The "h" argument is ignored.

int DXLIsMessagePending(DXLConnection *conn)

Can be used by applications that need to poll the DXLConnection to determine whether there are messages from the server that should be processed with DXLHandlePendingMessages. It returns zero (0) if there are no messages to handle, and a nonzero value otherwise.

Note: In windowing applications that use DXLInitializeXMainLoop, this function is not needed.

DXLError DXLHandlePendingMessages(DXLConnection *conn)

Parses a message that is waiting to be processed. The result is a call to the installed message handlers. This routine is called automatically if DXLInitializeXmainLoop is used.

DXLError DXLSend(DXLConnection *conn, const char *msg)

When the server is the executive, it will accept most one-line scripting-language commands, including assignments and module calls. For example, the following command makes a compound assignment (1.23 to the variable "foo" and [1 2 3] to the vector "bar"):

   DXLSend(conn, "foo, bar = 1.23, [1 2 3]; \n");

Notes:

1. Multiline scripting-language commands (e.g., macro definitions) cannot be sent with this function. Instead see the two ...MacroDefinition routines in 17.8 , "Program Control".

2. When the server is the user interface, it will ignore most commands, and this function should be avoided. Instead see the DXLSetValue functions in "Setting Variables".

DXLError DXLSetErrorHandler(DXLConnection *conn, DXLMessageHandler h,
                                         const void *data);

Sets the message handler (h), which is called when an error occurs. The specified data is passed to the handler. If no error handler is specified, a default handler that prints a message and exits will be used. Returns OK or ERROR. The message handler is defined by

typedef void
         (*DXLMessageHandler)(DXLConnection *conn, const char *msg,
                              void *data);

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