"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "q-7.11/modules/dxl/README-DXL" of archive q-7.11.tar.gz:

    1 
    2 Q-DXL - DXLink interface for the Q programming language
    3 ===== = ====== ========= === === = =========== ========
    4 
    5 This module implements an interface to Open Data Explorer (DX), IBM's
    6 comprehensive data visualization software available from www.opendx.org. It
    7 utilizes the DXLink API which allows you to connect to the DX executive and
    8 user interface, and execute commands, macros and visual programs written in
    9 the DX scripting language.
   10 
   11 The "stub" script is in dxl.q, dxl.c contains the actual C code for the
   12 module. A description of the available functions can be found in dxl.q.
   13 
   14 Documentation is rather rudimentary right now, but I hope that you'll find
   15 your way by taking a look at dxl.q and the provided examples. To give you an
   16 idea how to start, a simplistic script for firing up the server, loading a
   17 visual program and executing it, might look as follows:
   18 
   19 include dxl;
   20 
   21 image            = dxl_load H PROG || dxl_exec_once H ||
   22                    writes "Hit Return to quit: " || reads || ()
   23 		   where H:DXLHandle = dxl_start "dx -image",
   24 		   PROG = writes "Name of visual program to run: " || reads;
   25 
   26 		 = writes "Error starting DX server\n" otherwise;
   27 
   28 Here is a slightly more substantial example, which employs execute-on-change
   29 mode, and also feeds an "in_filename" DXLInput module and monitors an
   30 "out_value" DXLOutput variable (cf. the DX user manual for information on how
   31 to use DXLInput and DXLOutput in a visual DX program):
   32 
   33 include dxl;
   34 
   35 // load a visual program and set up input and output channels
   36 
   37 image            = dxl_load H "my_dx_prog.net" ||
   38 		   dxl_input H "in_filename" (str "my_data_file.dx") ||
   39 		   dxl_output H "out_value" ||
   40 		   dxl_exec_on_change H ||
   41 		   poll H
   42 		   where H:DXLHandle = dxl_start "dx -image";
   43 
   44 		 = writes "Error starting DX server\n" otherwise;
   45 
   46 // keep polling for results until the user terminates the application by
   47 // closing the anchor window
   48 
   49 poll H:DXLHandle = printf "%s = %s\n" (dxl_read H) || poll H if dxl_ready H;
   50 	         = () otherwise;
   51 
   52 // catch error messages returned by dxl_read
   53 
   54 dxl_error MSG    = printf "DXL error: %s\n" MSG;
   55 
   56 
   57 CAVEATS AND BUGS
   58 
   59 Here are some peculiarities in the inner workings of DXLink (as of DX 4.1.0)
   60 which you probably should know about, since they also affect the behavior of
   61 the Q-DXL interface:
   62 
   63 - When using dxl_exit with a server running in UI mode, make sure
   64   you invoke the server with the -noExitOptions option. (The DXLink library has
   65   a bug which causes it to segfault when invoking the DXLExitDX() routine on a
   66   DX application which has already been terminated by the user.)
   67 
   68 - When the server is exited it will leave a zombie process. You can remove
   69   the process by checking its exit value with the wait function from the clib
   70   module.
   71 
   72 - Don't pass large data sets using dxl_input, use a temporary data file
   73   instead. (See sombrero.q for an example showing how to do this.) DX
   74   apparently has a relatively small internal limit on the size of a DXLInput
   75   value, and dumps core if those limits are exceeded.
   76 
   77 I also noticed that with more recent OpenDX versions (4.2) the DX executive
   78 sometimes hangs when exiting a Tk-based OpenDX application which uses hardware
   79 rendering on a window embedded in the Tk application. (At least this happens
   80 on my Linux system, YMMV.) If you run into this problem, make sure you exit
   81 the DXL connection with dxl_exit before exiting the Tk application, that seems
   82 to cure the problem.
   83 
   84 
   85 Enjoy! :)
   86 
   87 November 24 2002
   88 Albert Graef
   89 ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de
   90 http://www.musikwissenschaft.uni-mainz.de/~ag