
Q-DXL - DXLink interface for the Q programming language
===== = ====== ========= === === = =========== ========

This module implements an interface to Open Data Explorer (DX), IBM's
comprehensive data visualization software available from www.opendx.org. It
utilizes the DXLink API which allows you to connect to the DX executive and
user interface, and execute commands, macros and visual programs written in
the DX scripting language.

The "stub" script is in dxl.q, dxl.c contains the actual C code for the
module. A description of the available functions can be found in dxl.q.

Documentation is rather rudimentary right now, but I hope that you'll find
your way by taking a look at dxl.q and the provided examples. To give you an
idea how to start, a simplistic script for firing up the server, loading a
visual program and executing it, might look as follows:

include dxl;

image            = dxl_load H PROG || dxl_exec_once H ||
                   writes "Hit Return to quit: " || reads || ()
		   where H:DXLHandle = dxl_start "dx -image",
		   PROG = writes "Name of visual program to run: " || reads;

		 = writes "Error starting DX server\n" otherwise;

Here is a slightly more substantial example, which employs execute-on-change
mode, and also feeds an "in_filename" DXLInput module and monitors an
"out_value" DXLOutput variable (cf. the DX user manual for information on how
to use DXLInput and DXLOutput in a visual DX program):

include dxl;

// load a visual program and set up input and output channels

image            = dxl_load H "my_dx_prog.net" ||
		   dxl_input H "in_filename" (str "my_data_file.dx") ||
		   dxl_output H "out_value" ||
		   dxl_exec_on_change H ||
		   poll H
		   where H:DXLHandle = dxl_start "dx -image";

		 = writes "Error starting DX server\n" otherwise;

// keep polling for results until the user terminates the application by
// closing the anchor window

poll H:DXLHandle = printf "%s = %s\n" (dxl_read H) || poll H if dxl_ready H;
	         = () otherwise;

// catch error messages returned by dxl_read

dxl_error MSG    = printf "DXL error: %s\n" MSG;


CAVEATS AND BUGS

Here are some peculiarities in the inner workings of DXLink (as of DX 4.1.0)
which you probably should know about, since they also affect the behavior of
the Q-DXL interface:

- When using dxl_exit with a server running in UI mode, make sure
  you invoke the server with the -noExitOptions option. (The DXLink library has
  a bug which causes it to segfault when invoking the DXLExitDX() routine on a
  DX application which has already been terminated by the user.)

- When the server is exited it will leave a zombie process. You can remove
  the process by checking its exit value with the wait function from the clib
  module.

- Don't pass large data sets using dxl_input, use a temporary data file
  instead. (See sombrero.q for an example showing how to do this.) DX
  apparently has a relatively small internal limit on the size of a DXLInput
  value, and dumps core if those limits are exceeded.

I also noticed that with more recent OpenDX versions (4.2) the DX executive
sometimes hangs when exiting a Tk-based OpenDX application which uses hardware
rendering on a window embedded in the Tk application. (At least this happens
on my Linux system, YMMV.) If you run into this problem, make sure you exit
the DXL connection with dxl_exit before exiting the Tk application, that seems
to cure the problem.


Enjoy! :)

November 24 2002
Albert Graef
ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de
http://www.musikwissenschaft.uni-mainz.de/~ag
