IBM Visualization Data Explorer Programmer's Reference

17.5 Initialization and Exit

These routines enable an application to initiate and terminate connections with Data Explorer. DXLStartDX establishes a connection *conn for a Data Explorer instance. It is through this connection that information is sent and received during a Data Explorer session.

void DXLCloseConnection(DXLConnection *conn)

Closes the connection to Data Explorer (*conn) and frees the memory allocated to *conn but does not terminate the Data Explorer session.

DXLConnection *DXLConnectToRunningServer(int port, const char *host)

This routine is used primarily for debugging purposes, to connect to a server (i.e., dxexec or dxui) that has already been started externally and is waiting for a connection (see -exonly and -appPort options). The routine creates a connection between the calling application and Data Explorer at the specified port on the specified host.

The parameter port must be greater than or equal to zero. If host is specified as NULL, the function uses "localhost".

DXLError DXLExitDX(DXLConnection *conn)

Closes the connection to Data Explorer (*conn) and terminates the Data Explorer session. Returns OK or ERROR.

int DXLGetSocket(DXLConnection *conn)

Returns the socket number associated with connection *conn.

DXLError DXLInitializeXMainLoop(XtAppContext app, DXLConnection *conn)

Initializes the X11 window system so that calls to XtAppMainLoop will cause messages to be processed. (See 17.6 , "Messaging System".)

int DXLSetMessageDebugging(DXLConnection *c, int on)

Specifies the on-off status of message debugging. If it is enabled, messages are printed to the terminal window as they are sent or received. The return value identifies the previous state of message debugging.

void DXLSetSynchronization(DXLConnection *conn, const int onoff)

Sets the synchronization status of the connection to Data Explorer. When onoff is set to 1, the connection is synchronized; when set to 0, it is not. With the connection synchronized, routines wait for a response from the "server" (i.e., UI or exec) after a message is sent. For example, if synchronization has been turned on, a call to DXLSetValue will not return until the server has processed the set value.

DXLConnection *DXLStartDX(const char *string, char *host)

Starts Data Explorer and creates a connection to it. The parameter *string is the command that would be used to start Data Explorer at the command line. For example, string could be:

   dx -image -mdf user.mdf

Note that you must specify either -image, -edit, or -menubar in order to bypass the Data Explorer Startup window. It is not possible to use DXLStartDX to start Data Explorer via the Startup window. The parameter *host is the name of the host on which Data Explorer is to be run. If specified as NULL, the local host is assumed.

The routine returns a pointer to a DXLConnection on success or it returns NULL and sets an error code (available in the global variable errno). The connection structure, specified by

   typedef struct DXLConnection DXLConnection;

is the primary structure used by DXLink for maintaining information about the connection to the server. This DXLConnection is passed to most DXLink routines to indicate the relevant server connection.

To start the Data Explorer executive and connect DXLink to it, you might issue the following call:

   DXLStartDX("dx -cache off -exonly");

The -exonly flag causes the executive to start up and to wait for a connection from DXLink. It is therefore required when connecting to the executive. Note that the "-script" option should not be used, as it causes the executive to start up in script mode, which requires commands typed directly at a prompt, bypassing the message system.

Similarly, a connection to the Data Explorer user interface can be initiated with the command:

DXLStartDX("dx -mdf my.mdf -image");

void DXLSetBrokenConnectionCallback(DXLConnection *conn, void (*proc)(DXLConnection *, void *), void *data);

Allows the application to install a routine to be called when the connection to Data Explorer is broken.

[Data Explorer Home Page]