NAME
dx - start the Data Explorer visualization system. Optionally directly
start the User Interface (dxui), the executive (dxexec), the Data
Prompter, the Module Builder or the Tutorial.
SYNOPSIS
dx [ -8bitcmap < private | shared | 0-1 > ]
[ -builder ]
[ -cache < on | off > ]
[ -colors < colors file > ]
[ -connect < host:port > ]
[ -data < path list > ]
[ -directory < dir > ]
[ -display < display name > ]
[ -dxroot < dir > ]
[ -echo ]
[ -edit ]
[ -encode ]
[ -exec < executable > ]
[ -execonly ]
[ -execute ]
[ -execute_on_change ]
[ -full ]
[ -file < filename > ]
[ -help ]
[ -highlight < on | off > ]
[ -host < host name > ]
[ -hwrender < gl | opengl > ]
[ -image ]
[ -include < path list > ]
[ -key < 64bit hex > ]
[ -license < type > ]
[ -local ]
[ -log < on | off > ]
[ -macros < path list > ]
[ -mdf < filename > ]
[ -memory < # of Mbytes > ]
[ -menubar ]
[ -metric ]
[ -modules < path list > ]
[ -morehelp ]
[ -nodeid ]
[ -optimize < memory | precision > ]
[ -outboarddebug ]
[ -processors ]
[ -program < filename > ]
[ -prompter ]
[ -readahead < on | off > ]
[ -script [ < script file > ] ]
[ -startup ]
[ -suppress ]
[ -timing < on | off >]
[ -trace < on | off > ]
[ -trialkey ]
[ -tutor ]
[ -uionly | -execonly ]
[ -verbose ]
[ -version]
dx -prompter ( start the Data Prompter )
[ -full ]
[ -file ] [ < header file name > ]
dx -builder ( start the Module Builder )
[-file ] [ < .mb file name > ]
DESCRIPTION
dx is the command that starts the Data Explorer Startup Window, and
optionally starts the Data Explorer User Interface, Data Explorer
Executive, Data Explorer Data Prompter, Data Explorer Module Builder or
the Data Explorer Tutorial.
The Data Explorer Startup Window is an X windows/Motif based
application which allows easy access to the other subsystemes of the
Data Explorer visualization system.
The Data Explorer User Interface is an X windows/Motif based
application that provides a visual programming environment and an
interface to the executive. The executive provides the computational
tools and mechanisms to create data visualizations. The
Data Explorer Data Prompter is an X windows/Motif based application
that helps users import data in a variety of formats, and provides
general purpose visual programs to visual imported data, leading to a
shortened "time to first picture".
The Data Explorer Module Builder is an X windows/Motif based
application that helps users build their own modules to be included in
a custom version of Data Explorer.
The Data Explorer Tutorial is an application that helps users learn to
use Data Explorer by leading them through a sequence of tasks. Users
can easily skip around in the tutorial in order to concentrate on tasks
of most use to their work.
For a more complete description of the Data Explorer User Interface and
Executive see the IBM Visualization Data Explorer User’s Guide. For a
more complete description of the Data Explorer Data Prompter see the
IBM Visualization Data Explorer QuickStart Guide. For a more thorough
description of the Data Explorer Module Builder see the IBM
Visualization Data Explorer Programmer’s Reference.
OPTIONS
With no options the dx command starts the Startup Window, an X
windows/Motif program from which the other parts of the Data Explorer
system can be started. The various command line options and
environment variables listed below can be specified to change the
default behavior.
Options set by including them in the DXARGS environment variable are
placed at the start of the command line, followed by any options set by
environment variables, followed by explicit command line arguments.
When conflicting options are given, the last option has precedence.
-8bitcmap < private | shared | 0-1 | -1 >
Overrides the DX8BITCMAP environment variable (see ENVIRONMENT
VARIABLES below).
-cache < on | off >
Turn on or off the executive caching system. When the Data
Explorer caching mechanism is enabled the Data Explorer
executive automatically caches the intermediate results
generated during its visualization computations. Unlike
standard caching mechanisms, these results are accessed by means
of their functional derivation. This allows for automatic graph
optimization and helps to avoid the recomputation of previously
utilized intermediates, especially when the Data Explorer
sequencer is being used. In certain rare instances, a machine
with a small amount of memory may want to disable this caching
to conserve memory and reduce paging. Default = on.
-colors < colors file >
Override DXCOLORS environment variable (see ENVIRONMENT
VARIABLES below).
-connect < host:port >
Start a distributed executive only (no user interface).
-data < path list >
Override DXDATA environment variable (see ENVIRONMENT VARIABLES
below).
-directory < dir >
Cause the executive to be run in the given directory.
-display < display name >
Set the name of the X display to be used by the user interface
and the executive.
-dxroot < dir >
Overrides the default dx root directory.
-echo < dir >
Echo the command lines without executing them.
-edit Cause the user interface to be started with the Visual Program
Editor (VPE) window as the top level window of the user
interface (the top level window is denoted by an anchor in the
upper left hand corner). Also see -image, -startup, and
-menubar.
-encode < filename >
Encode the given file into a binary format with a key (which
must be specified with the -key option). For example
dx -encode -key 1234567890abcdef foo.net The resulting file
can only be encoded by the DX user interface when the same key
is used. For example
dx -image -key 1234567890abcdef foo-e.net
-exec < executive executable >
Use the given file as a replacement for the executive. This
option allows a user to build and use his/her own custom
executive.
-execonly
Start the executive in remote mode in which it will then await a
connection from the user interface. The user interface is not
started with this option. Also see -script.
-execute
Execute once after the user interface has made a connection with
the executive.
-execute_on_change
Cause Data Explorer to go into execute-on-change mode at start
up. Execute-on-change mode causes the Visual Program to be
executed any time any of the values (i.e. module inupts,
interactor values...) in the program change.
-file < filename >
Start the Data Prompter, Module Builder, or Data Explorer User
Interface with the header file filename.
-full When used with -prompter, starts the full Data Prompter.
-help Print a brief listing of options and usage for dx.
-highlight < on | off >
Turn on or off module execution highlighting. If highlighting
is turned on, the user interface will highlight each module as
it is executed. Default = on.
-host < host name >
Override DXHOST environment variable (see ENVIRONMENT VARIABLES
below).
-hwrender < gl | opengl >
Override the default hardware rendering choice on platforms
where both are supported. Default is opengl. Sets the DXHWMOD
environment variable to either DXhwdd.o or DXhwddOGL.o.
-image Cause the user interface to be started with the image window as
the top level window of the user interface. Also, control
panels that are configured to open automatically are opened.
Also see -edit, -startup and -menubar.
-include < path list >
Override DXINCLUDE environment variable (see ENVIRONMENT
VARIABLES below).
-key < 64bit hex >
16 character hexidecimal (64bit) number that is used to encode
and decode .net files. See -encode.
-license < type >
Force a specific license for either the user interface or
executive. The following are valid values for type:
runtime: forces a run-time license (UI or executive).
timed: forces a timed (limited function) license (UI only).
develop: forces a developer license (UI or executive).
-local Override the DXHOST environment variable (if set) and cause the
executive to be run on the local host. In the absence of the
DXHOST environment variable, this is the default.
-log < on | off >
Turn on or off executive logging. If logging is on then the
executive logs output to the file dx.log in the directory where
the executive is executing. Default = off.
-macros < path list >
Override the DXMACROS environment variable (see ENVIRONMENT
VARIABLES below).
-menubar
Start Data Explorer with a menubar as the anchor window. Also,
control panels that are configured to open automatically are
opened. See also -image, -edit, and -startup.
-mdf < mdf file >
Override the DXMDF environment variable (see ENVIRONMENT
VARIABLES below).
-memory < # of MB >
Set the maximum amount of memory, in megabytes rounded up to a
two megabyte boundary, that the executive is able to allocate.
Default = the amount of physical memory minus 8 MB.
-metric
Have the ui use metric units when possible, for example for
setting the image size for printing postscript images.
-modules < pathlist >
Set the list of directories to be searched for outboard modules.
-morehelp
Displays this information
-nodeid
print out the node id of the machine that the command is run on.
The node id is used when generating a license.
-optimize < memory | precision >
Select whether to minimize memory usage or produce more color-
accurate images. When memory is optimized, image objects are
generated with 24 bits/pixel instead of 96, and ReadImage will
produce delayed color images if supported by the format. The
default is precision.
-outboarddebug
Enable user to start outboard modules manually for debugging
when they are called in a visual program.
-processors
For Data Explorer SMP, sets the number of processors to use.
-program < programname >
Start the user interface with the visual program filename.
-prompter
Start the data prompter.
-readahead < on | off >
Specify whether or not the executive reads ahead in its input
stream before executing the commands it receives from the
stream. If this is turned off, then the executive will execute
each command line as it is received. This is useful for certain
debugging purposes, such as memory leak detection. Default =
on.
-script [ < script file > ]
Run just the executive in script mode. If a file name is
provided then the executive reads and executes commands from the
given script and then terminates. If a file is not provided
then when the executive starts up it enters interactive mode
where it waits for script commands. Also see -execonly.
-startup
Start Data Explorer with the startup window as the initial
window. This is the default. See also -image, -edit, and
-menubar.
-suppress
Do not open any control panels at start-up. This is used in
-image mode and -menubar mode only.
-timed Start DX using a timed license.
-timing < on | off >
Turn on or off the executive timing mechanism. If enabled, then
when the executive exits it will list on standard output or the
logging file timing statistics for each module that was used
during the course of execution. Default = off.
-trace < on | off >
Turn on or off the executive trace mechanism. When tracing is
enabled the executive displays informative messages about the
execution sequence on either standard output or the log file if
logging is enabled. Default = off.
-trialkey
Determines the information necessary for generating a trialkey.
-tutor Start the Data Explorer tutorial.
-uionly
Cause the user interface to be started without making a
connection to an executive.
-verbose
Echo commands in the dx script as they are executed.
-version
Print version numbers of various executables.
ENVIRONMENT VARIABLES
The following environment variables provide an alternate way to set
certain of the command line options, or alter the default behavior of
Data Explorer in some way. Options set with environment variables are
overridden if the same option is also specified on the command line.
Options set with DXARGS are overridden by both environment variables
and explicit command line options.
DX8BITCMAP
When Data Explorer displays images in 8-bit windows, it makes
every effort to create an accurate representation of the image
using the default colormap shared among applications using 8-bit
windows. If the colors required by Data Explorer are not
present in the colormap and there are not enough free color
cells available in the shared color map for their allocation,
Data Explorer will find approximations among the colors that are
available. However, in certain circumstances, the difference
between the desired color and the approximation is found to be
too great to be acceptable. In such circumstances, DX will
allocate a private colormap for more accurate results. In this
case, depending on your X server, you may need to move the mouse
to select the Image or Display window in order for the correct
colors to appear. The -8bitcmap flag sets the level at which
the change to using a private colormap is made. The value of
this parameter should be a number between 0 and 1, or "private"
or "shared", and it repressents the Euclidean distance in RGB
color space, normalized to 1, for the maximum allowed
discrepancy. If you set this parameter to 1, then a private
colormap will never be used. If you set it to -1, then a private
colormap will always be used. The default is 0.1.
DXARGS This contains the default set of arguments used by the dx
script. The arguments are prepended to those given to dx on the
command line. This variable allows for the dx command to be
easily customized.
DXAXESMAXWIDTH
Sets the number of digits in axes tick labels at which a switch
to scientific notation is made. The default is 7.
DXCOLORS
This contains the name of an alternate file that contains
mappings of color names to red, green, blue triplets in a format
like that of the default color file found in
/usr/lpp/dx/lib/colors.txt.
DXDATA This contains a colon separated list of directories in which the
executive will search for data files. Also see the -data
option.
DXDELAYEDCOLORS
If set to anything other than 0, enables ReadImage to create
delayed color images if the image is a tiff format image saved
in a byte-with-colormap format or a gif image.
DXEXEC Specifies an executive to be run at start-up.
DXFLING
If DXFLING is set to 1, then for hardware-rendered images, in
rotation mode and execute-on-change mode, if you drag the mouse
across the image, and release the mouse button outside the
image, the object in the image will begin to rotate, and will
continue to rotate until you click inside the image. The
direction and speed of the mouse motion before release will
affect the rotation direction and rotation speed of the object
in the window.
DXGAMMA
Sets the gamma correction for software-rendered images displayed
to the screen using the Display and Image tools. The default
value is 2, except for 8-bit windows on the sgi architecture.
DXGAMMA_8BIT,
DXGAMMA_12BIT, DXGAMMA_24BIT sets the gamma correction factor
for software-rendered images for the windows with the indicated
window depth. Overrides the value set by DXGAMMA.
DXHOST This contains the name of the host machine that will run the
executive. If this is not set then a default of "localhost" is
used, unless the local host is a PVS console in which case the
default is to run the executive on the PVS. Also see the -host,
-local and -server options.
DXHWGAMMA
Sets the gamma correction for hardware-rendered images displayed
to the screen using the Display and Image tools. The default
value is 2.
DXHWMOD
Specifies the name of the hardware rendering library to use when
more than one is supported. Should be either DXhwdd.o or
DXhwddOGL.o.
DXINCLUDE
This contains a colon separated list of directories in which the
executive will search for "included" scripts. Also see the
-include option.
DXMACROS
This contains a colon separated list of directories in which the
user interface searches for macros that will be automatically
loaded. When running in script mode one must "include" all the
macros by hand prior to referencing them. Also see the -macros
option.
DXMDF This contains the name of a module description file (mdf) that
contains user defined modules for a customized version of the
executive. Also see the -mdf option.
DXMEMORY
sets the amount of memory (in megabytes) that can be used by the
executive.
DXMODULES
This contains a colon separated list of directories in which the
executive searches for outboard modules. Also see the -modules
option.
DX_NESTED_LOOPS
For faces, loops, and edges data, if set, allows loops other
than the enclosing loop for a face to be listed first. However,
there is a consequent decrease in performance if this
environment variable is set.
DXNO_BACKING_STORE
If set to anything, disables framebuffer readbacks. Setting
this environment variable may improve performance of interaction
with hardware rendered images, especially for machines for which
readback is slow. The default behavior is that framebuffer
readbacks are enabled. If you set this environment variable, not
that some interactions using the Image tool will result in a
black image while interaction is taking place. However, if you
are not using the Image tool, it is strongly recommended that
you set this environment variable.
DXPIXELTYPE
sets the image type to either 24-bit color images or floating-
point-based 96-bit images (the default). This affects the
behavior of Render and ReadImage. This variable can be set to
either DXByte (24 bits) or DXFloat (96 bits). Setting this
variable to DXByte will result in images taking up less memory.
DXPROCESSORS
Sets the number of processors to be used for Data Explorer SMP.
DXRSH Specifies the remote shell command to use when connecting to
other systems (such as those when using distributed execution).
The default is the the path to rsh.
DXRSH_NOENV
Prevents the remote "invoke dxexec" script from being written
with a full carbon copy of the local environment (only DISPLAY
is set).
DXROOT Specifies the top-level directory for all the files and
directories needed by Data Explorer.
DXSHMEM
If set to anything other than -1, forces shared memory to be
used (if allowed by the architecture). If set to -1, (if
allowed by the architecture) will cause the data segment to
simply be extended. Please see Appendix C of the Data Explorer
User Guide for more information.
DX_SOCKET_BUFSIZE
Allows the user to specify the size of the send and recieve
buffers for the socket connection between the UI and the exec.
This value is clamped to the max allowed by the system. This can
fix a problem where the executive and UI hang involving a
deadlock situation in the socket communication. The value
assigned to it is passed as the parameter to setsockopt for
SOL_SNDBUF and SOL_RCVBUF. A typcial increased value may be
262144.
DX_USER_INTERACTOR_FILE
Specifies a file containing user interactors for use by the
SuperviseState and SuperviseWindow modules.
DX_WEB_BROWSER
Under UNIX specifies the web browser to launch for viewing the
HTML documentation. Under Windows and MacOS X setting this
environment variable will launch the systems default web
browser.
EXAMPLES
The next few examples assume that none of the DX environment variables
have been set.
1. To start both the user interface and the executive with the network
named cfd.net:
dx -edit -program cfd
2. To start and execute the visual program cfd.net in image mode with
/usr/users/me and /usr/data as data directories:
dx -image -execute -data ’/usr/users/me:/usr/data’ cfd
3. To run just the executive on the script named f15wing:
dx -script -file f15wing
4. To start the user interface and execute the user customized
executive named mydxexec containing user defined modules described in
custom.mdf:
dx -edit -mdf custom.mdf -exec mydxexec
5. To start the Data Prompter :
dx -prompter
6. To start the Module Builder :
dx -builder
7. To start the Tutorial :
dx -tutorial
SEE ALSO
README* - The README file(s) found in the dx
installation directory are an added source of information.
html/allguide.htm contains html versions of the documentation.