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.
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.
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;
Note: In windowing applications that use DXLInitializeXMainLoop, this function is not needed.
DXLSend(conn, "foo, bar = 1.23, [1 2 3]; \n");
Notes:
DXLError DXLSetErrorHandler(DXLConnection *conn, DXLMessageHandler h,
const void *data);
typedef void
(*DXLMessageHandler)(DXLConnection *conn, const char *msg,
void *data);