*
* Architecture independent README for IBM Visualization Data Explorer
* and IBM Visualization Data Explorer for Symmetric Multiprocessing (SMP)
*
* For architecture dependent information, see 'Platform-Specific
* Considerations' in the on-line help, or see /usr/lpp/dx/README_"arch"
* where arch is one of ibm6000, hp700, sun4, aviion, alphax,
* solaris, or sgi.
*
*
The information contained in this file consists of hints for using the
system, help with functions that may not be apparent, and last minute updates
to the existing documentation. It is advisable to review this file any time
Data Explorer updates are applied. This README file is applicable to
Data Explorer Version 3.1.4b.
If you need assistance installing or using a purchased copy of Data Explorer,
send email to dxsupp@watson.ibm.com, or call Data Explorer Support
at 800-435-6813.
========================================================================
CONTENTS
To go directly to an item, search for the item number beginning
at the left margin.
1. Installation Notes
A. The Configure Script
B. The DX Installation directory (DXROOT)
C. NetLS Licensing Problems
2. Getting Started
A. Tutorial
B. Sample Visual Programs and Scripts
3. Important Features not otherwise documented
A. Requirements on how Loops are used in Distributed Mode
B. Problems with F1 key and on-line help
4. Differences from version 3.1.4a of Data Explorer
A. Ten new fonts
B. New module: Pie
C. New runtime-loadable module: BSpline
D. New samples in samples/callmodule and samples/dxlink directories
E. New member, kstate, of events structure for Supervise modules
F. A fix for the SGI architecture for users with lots of memory
G. A fix to Histogram for partitioned data
H. A fix to the licensing code for runtime users
I. Hardware rendering fixes
5. Differences from version 3.1.4 of Data Explorer
A. Streakline has an additional undocumented parameter
B. A new module, DXLOutputNamed, has been added
C. Fix in MapToPlane for handling of invalidity for regular data
D. Fix in Statistics for handling of invalidity
E. Fixes to ChangeGroupMember and ChangeGroupType
F. Fix to Morph when large filter specified
G. Fix for SelectorList interactor
H. Fix to allow dx.h to be used in C++ program
I. Fix for gamma correction in saved miff images
J. Fix for ReadImage on Solaris
K. "All" category has been moved
L. OpenGL and Solaris
6. Differences from version 3.1.2 of Data Explorer
A. New startup behavior
B. New Data Prompter
C. AutoAxes no longer scales the object
D. Images are now gamma corrected by default when written out
E. Get and Set modules replaced by Local and Global versions
F. Behavior of DXSHMEM has changed
G. startup behavior affects DXLink applications
H. Transmitters/Outputs, and Receivers/Inputs cannot share names
I. Changes to ReadImage in how images are stored internally
J. ReadImage stores images as delayed colors if possible by default
7. User Interface Notes
A. Vectors can be float or integer vectors
B. Data-Driven Interactors
C. Misleading warning can appear when writing out PostScript images
8. Running Data Explorer
A. Specifying the Host Name for Remote Execution
B. Environment Variables in Script Mode for Remote Execution
C. Specifying Host Name for Distributed Execution
D. Distributed Execution when a Remote Host is Unavailable
E. Distributed Execution using Data Explorer SMP
F. Possible problem runing Data Explorer remotely
9. System Environment
A. Default Memory Size
B. Paging Space
C. Per Process Limits
10. Notes on the Hardware Rendering Option
A. Rendering shaded surfaces requires z-buffer capabilities
B. Fast mouse button transitions may go unnoticed
C. Arrow keys partially disabled during navigation
D. Button-down interaction disables visual program changes
E. Remote OpenGL
11. Import/Export
A. The External Data Format
12. Module Notes
A. Map Module
B. Grid Module
C. The Display module and the screen-saver
D. Slice Module limitation
E. Transformed Group Members
F. Print Module
G. Morph and Filter Modules
H. Error/Changes in Documentation for SuperviseWindow
I. Error in Documentation for ManageImageWindow
J. New parameter to Streakline, undocumented
K. New module, DXLOutputNamed, undocumented
L. Parameter option for CategoryStatistics, undocumented
M. Additional Control over VRML output using Export
13. X Colormap Interaction
A. 24 Bit Root Windows
14. Scripting Language
15. Hints
A. All of the Execute Options are Greyed Out
B. Faces/Loops/Edges
16. Notes on On-Line Help
17. Adding Modules
A. Building a Custom Executive
B. Outboard Modules
C. Modules written for Version 1
D. Asynchronous Modules
E. Error in documentation for starting sample modules
18. OSF/Motif Warning Messages
========================================================================
1. Installation Notes
For a complete installation of Data Explorer, please use the
installation instructions provided with the Data Explorer media.
However, if you simply wish to install Data Explorer on a new host,
then you need to do the following:
- duplicate (e.g. copy, NFS mount) the /usr/lpp/dx directory on the new host
- use the Configure script to configure the new host
Note that you will need a license to run on the new host. If you
have a floating license and the new host is on the same network as the
license server, then the above procedure will work. However if you have
a node-locked license, you will need to obtain a license for the new
host.
Note that it is important that you be able to start Data Explorer
simply by typing "dx". That is, you should not need to specify any
path name to start Data Explorer. If you cannot start Data Explorer
simply by typing "dx", the User Interface will not be able to start the executive portion of Data Explorer.
A. The Configure Script
The .../dx/bin/Configure script is run as follows,
Configure install
and/or
Configure deinstall
To see a list of options use the following,
Configure -help
It installs/deinstalls (mostly) soft links in standard places (i.e.
/usr/local/bin, /usr/local/lib...) that point back to the DX
installation tree. Generally, Configure must be run on each
workstation from which you expect to run Data Explorer.
If you have problems with your installation, it may be because the file
systems where the soft links are placed are NFS mounted and usually
root is not allowed to write across the NFS mount. Run Configure with
the '-check' option to determine the links that are required on your system.
B. The DX Installation Directory (DXROOT)
Data Explorer is installed as a single directory tree that is referred
to as the DX root directory. As part of configuring Data Explorer,
links are placed in the public filesystem that reference files within
the DX root directory. The default DX root directory is /usr/lpp/dx.
If the root directory is moved after installation, Data Explorer should
be reconfigured to use the new root directory with the following:
Configure -dxroot <new directory>
In a networked environment, it is most convenient for users if all
workstations have Data Explorer available through the same root
directory. This makes it easier to run the User Interface on one
machine and the server on another. However, if in this situation the
two machines do not use the same root directory, the -dxroot option
should be used when starting the remote server from within the User
Interface.
C. NetLS Licensing Problems
1) If you receive the following error after receiving your permanent NetLS
licensing key:
Starting DX user interface
Data Explorer trial password file found
You are running an expired trial version of Data Explorer
- Verify that:
- The environment variables DXTRIALKEY and DXTRIALKEYFILE are not set.
- The file 'expiration' has been deleted from the dx install directory.
2) If you receive the following error:
Starting DX user interface
IBM Visualization Data Explorer : No servers available for this
vendor (network license server/library) [1d020006]
- Verify that:
- the NetLS key been placed in the appropriate directory according
to the directions in the 'IBM Visualization Data Explorer Install-
ation and Configuration' document.
- the key generation report accurately reflects your DataExplorer
configuration. Review the 'Product License Information' (key
generation report from KeyRegs) and verify that the information
it contains matches the output of /usr/lpp/dx/bin/NodeID.
- 'target' should equal the 'PREFERRED NetLS Target ID'
- 'version' should equal 'Version'
- 'license type' should equal 'License Usage'
- If there are inconsistencies in any of the above, a new key
that reflects the corrected information needs to be requested.
- For further diagnostic information, set the environment variable
DXTRACENETLS to 1. This prints information about what type of license
DX is requesting and what type of licenses it finds. For very detailed
diagnostic information at the socket/rpc level (useful for debugging
concurrent licenses) set the DXTRACENETLS variable to the value 2.
3) If root is the only user who can run Data Explorer, and all other users
receive the following error:
IBM Visualization Data Explorer : License not found in database
(network license server/server)
- Ensure that /dev/lan0 and /dev/ls_targetid are writeable by everyone.
2. Getting Started
A. Tutorial
A tutorial is provided to help you get started using Data Explorer.
The tutorial can be found in the Data Explorer Quick Start Guide.
It can also be found on-line, either by
typing
dx -tutor
choosing the "Tutorial" option of the Help menu of any
Data Explorer window
or from the "Tutorial" button of the Data Explorer startup window
B. Sample Visual Programs and Scripts
In the directory /usr/lpp/dx/samples/programs you will find a number
of example visual programs which illustrate various aspects of Data Explorer.
Each sample visual program has a comment associated with it which describes
how to use the program. You can access the comment either from the Open
File dialog (use the "Comments" button), or, once the Visual Program is
opened, from the "Help on Visual Program" option in the Help menu.
The samples are easily accessed from the "Samples" button of the Data
Explorer startup window.
There are a number of subdirectories in /usr/lpp/dx/samples/programs which
contain subsets of the sample visual programs organized by topic. So, for
example, in /usr/lpp/dx/samples/programs/2D_DATA, you will find a number of
sample visual programs which visualize two dimensional data. When the
filter for the Open dialog box of the Visual Program Editor is set to
the directory /usr/lpp/dx/samples/programs, these subdirectories will
appear on the left hand side of the dialog, under "Directories". Simply
click on one and then press the Filter button to see the example programs
in that directory.
In the directory /usr/lpp/dx/samples/macros you will find a number of
useful macros.
In the directory /usr/lpp/dx/samples/tutorial you will find a number of
example visual programs which are designed to be used with the Data Explorer
tutorial.
In the directory /usr/lpp/dx/samples/scripts you will find a number of
example script files which illustrate the use of each module in script mode.
In the directory /usr/lpp/dx/samples/program_guide you will find a number of
example .c files which will help you in writing your own modules. These
samples are designed to be used with the Programmer's Reference.
In the directory /usr/lpp/dx/samples/dxlink you will find a number of
example programs which illustrate the use of DXLink.
In the directory /usr/lpp/dx/samples/callmodule you will find a number of
example programs which illustrate the use of the DXCallModule interface to
call Data Explorer modules from an external program.
In the directory /usr/lpp/dx/samples/user you will find a number of
example programs which illustrate how to compile your own module as
runtime-loadable, inboard, or outboard.
In the directory /usr/lpp/dx/samples/outboard you will find a number of
example outboard modules.
In the directory /usr/lpp/dx/samples/supervise you will find examples of
custom user interactors for use with SuperviseWindow and SuperviseState
3. Important Features not otherwise documented
A. Requirements on how Loops are used in Distributed Mode
There are limitations on how you can use looping in distributed mode.
The entire contents of a loop must run on the same machine. This means
that if you want to distribute a loop to a machine other than
the master, you *must* put that loop in a macro, and place the macro
in an execution group assigned to the other machine.
B. Problems with F1 key and on-line help
If the F1 key does not work for obtaining help-on-context in the User
Interface, you may need to put the following line in your .motifbind
file in your home directory:
osfHelp :<Key>F1
4. Differences from version 3.1.4a of Data Explorer
A. Ten new fonts
In /usr/lpp/dx/fonts are 10 new fonts, all filled fonts, rather
than line fonts. These include a variety of "swiss style" fonts
(san-serif), italic, plain, bold, and condensed (thinner), an
italic and plain "dutch style" (similar to Times Roman), a
monospace font, a symbol font, and a "casual" font (dom). These
fonts can be specified for any module for which a font may be
specified (AutoAxes, Caption, Plot, etc.)
B. New module: Pie
A new module has been added to this release of Data Explorer. This module
does not have a manual page in the User Reference. See Pie.man in this
directory. See also /usr/lpp/dx/samples/programs/ExamplePieChart.net.
C. New runtime-loadable module: BSpline
You can find a runtime-loadable module BSpline in /usr/lpp/dx/bin_arch,
where arch is one of ibm6000, hp700, solaris, sgi, or alphax. The
mdf file for bspline can be found in /usr/lpp/dx/lib. See the
comments in bspline.mdf for more information.
D. New samples in samples/callmodule and samples/dxlink directories
Several new samples of example applications built using dxlink
and dxcallmodule have been added to these directories. See the
Readme files in the respective directories for more information.
Also check our home page (http://www.almaden.ibm.com/dx) for
extensive new documentation on the subject of application building.
This documentation discusses the samples in the callmodule
and dxlink directories.
E. New member, kstate, of events structure for Supervise modules
See item 12H for more information.
F. A fix for the SGI architecture for users with lots of memory
SGI users with large amounts of memory were sometimes having difficulty
starting dx. This has been fixed.
G. A fix to Histogram for partitioned data
The "sum" output was being incorrectly computed for partitioned data.
H. A fix to the licensing code for runtime users
Runtime dx users can now start up a dx session from the startup ui menu.
I. Hardware rendering fixes
There is a fix in OpenGL to fix a problem with getting a depth buffer.
This solves a problem with getting "bad triangles" in your image.
There is also a fix in GL for drawing points.
5. Differences from version 3.1.4 of Data Explorer
A. Streakline has an additional undocumented parameter
See 12 J below.
B. A new module, DXLOutputNamed, has been added
See 12 K below.
C. Fix in MapToPlane for handling of invalidity for regular data
In certain situations, MapToPlane was incorrectly handling regular/regular
data which contained invalid data. This has been fixed.
D. Fix in Statistics for handling of invalidity
In certain unusual situations, Statistics was not handling invalid
data correctly. This has been fixed.
E. Fixes to ChangeGroupMember and ChangeGroupType
ChangeGroupMember was sometimes incorrectly inserting/replacing
objects into groups. ChangeGroupType was not correctly maintaining
attributes at the top level object when changing the group type.
These problems have been fixed.
F. Fix to Morph when large filter specified
If an especially large filter was specified to Morph, Morph could
segfault. This has been fixed.
G. Fix for SelectorList interactor
Under certain circumstances the UI could segfault if particular
entries were made in the SetAttributes dialog of the SelectorList
interactor. This has been fixed.
H. Fix to allow dx.h to be used in C++ program
Necessary "extern C" lines added to certain .h files to allow
dx.h to be used in C++ program
I. Fix for gamma correction in saved miff images
Images saved in miff format now correctly use specified gamma correction.
J. Fix for ReadImage on Solaris
There was a bug in reading gif format images on solaris. This has
been fixed.
K. "All" category has been moved
The "All" category in the Visual Program Editor has been moved from the
end of the list of categories to the beginning. This is to ensure that
as more categories of modules are added (by Data Explorer development
or by users), the "All" category always remains easily visible for
new users.
L. OpenGL and Solaris
If you are interested in using OpenGL on the Solaris architecture,
please contact Data Explorer support: dxsupp@watson.ibm.com or
1-800-435-6813 (US and Canada), or 914-784-5142.
6. Differences from version 3.1.2 of Data Explorer
A. New startup behavior
Simply typing the command "dx" will start the Data Explorer
startup window, which allows you to perform a number of different
tasks, such as running a sample program, starting the data prompter,
starting the tutorial, etc. To simply start the Data Explorer
visual program editor (the previous default behavior) type dx -edit.
B. New Data Prompter
The Data Prompter now supports formats other than the General Array
format, and provides a set of general purpose programs to reduce the
"time to first picture"
C. AutoAxes no longer scales the object
In releases of Data Explorer prior to 3.1.4, AutoAxes reduced the
size of the object to 85% of it's original size. This scaling
has been removed
D. Images are now gamma corrected by default when written out
A gamma correction factor of 2 is applied to images by default
when they are written out. Note that if you are writing out images
for later use within Data Explorer, you should write out images
with gamma=1 (see WriteImage, or the SaveImage dialog box) so that
they are not doubly gamma-corrected when displayed.
E. Get and Set modules replaced by Local and Global versions
The Get and Set modules have been replaced by GetLocal and GetGlobal
and SetLocal and SetGlobal. Visual programs which use Get and Set
can still be run; Data Explorer will automatically use GetGlobal
and SetGlobal instead. However, performance advantages may be possible
by using GetLocal and SetLocal instead; please see the manual pages
for these modules in the Data Explorer User Reference. The Visual
Program Editor will help you change your networks; see the Edit
menu Assign Get/Set scope option.
F. Behavior of DXSHMEM has changed
In versions of Data Explorer prior to 3.1.4, DXSHMEM, if set to
anything, would force shared memory to be used. In version 3.1.4,
DXSHMEM must be set to anything other than -1 for shared
memory to be used; if set to -1, then the data segment will be
extended, for architectures for which this is permissible.
G. startup behavior affects DXLink applications
Because the command "dx" now starts the Data Explorer startup window,
DXLink applications will need to use either -image or -edit in
the DXLStartDX command string.
H. Transmitters/Outputs, and Receivers/Inputs cannot share names
Version 3.1.4 prevents Transmitter and Output nodes, and Receiver and
Input nodes from sharing names. These name collisions were permitted
in earlier versions and could lead to incorrect code generation. Now
an offending node will be renamed automatically and the user notified.
I. Changes to ReadImage in how images are stored internally
By default, all images read in by ReadImage are stored internally
in bytes, rather than floating point. This will only affect visual
programs in which you are manipulating colors and expect them to
be floating point colors. You can use the "colortype" parameter to
ReadImage or the DXPIXELTYPE environment variable to change the
default behavior. See the ReadImage manual page.
J. ReadImage stores images as delayed colors if possible by default
For images in delayed color format (gif, some tiff and some miff),
ReadImage will by default store the image with delayed colors. You
can override this default behavior by using the "delayed" parameter
to ReadImage or the DXDELAYEDCOLORS environment variable. See the
ReadImage manual page.
7. User Interface Notes
A. Vectors can be float or integer vectors
If you specify integral values for vector, either using a vector interactor
or using a configuration dialog, an integer vector will be produced.
Otherwise, the vector will be a floating point vector.
B. Data-Driven Interactors
Changing an interactor from data-driven to non-data-driven, and
then back to data-driven may not result in the proper updating and execution
of the visual program. After switching back to data-driven mode,
you should reset the server (using "Reset Server" in the Connection menu)
to enable proper execution of the visual program.
C. Misleading warning can appear when writing out PostScript images
Occasionally you may see a warning when writing out PostScript images
that the image will not fit on the page, even though the page size
as specified is correct. Ignore the warning. Apparently this only
occurs if you have modified the PPI setting in the Save Image or
Print Image dialog. Note that it is not typically necessary to set
this field; it is typically better to just set the overall resolution
of the image using the Input Image size field. Note that it is NOT
necessary to set PPI to match the DPI of the printer.
8. Running Data Explorer
A. Specifying the Host Name for Remote Execution
Be sure to specify the host name of the remote host as what is returned
by "uname -n" on the remote host. This ensures that Data Explorer
finds the host correctly.
B. Environment Variables in Script Mode for Remote Execution
When running Data Explorer remotely in script mode using the command "dx
-host hostname -script", local environment variables, such as DISPLAY,
are not passed to the remote host.
C. Specifying Host Name for Distributed Execution
Distributed execution does not handle network addresses like 9.2.37.10. Specify
the host name as what is returned by "uname -n" on the machine
you wish to run on.
D. Distributed Execution when a Remote Host is Unavailable
If, from the Execution Group Assignment menu, you are trying to
connect to a remote host and the connection times out, you may
need to reread the visual program into the user interface in
order to retry the connection. The connection may time
out if, for example, the remote machine was down when you tried
to connect, or you did not have your .rhosts file set up
properly to allow remote shells to be executed.
However, if you make any changes to the Execution Group
Assignment menu, then the user interface will retry the
connections. In this case, it is not necessary to reread the
visual program.
E. Distributed Execution using Data Explorer SMP
When using both distributed execution and Data Explorer SMP, it is
recommended that a single processor host be connected to by the
User Interface, i.e. be used as the master.
F. If you start the user interface on a machine with DX installed for a
given architecture or version of DX, and then try to start an executive
using the Start Server dialog box on a remote system that does not have
DX installed in the same place as the local machine, then the executive
will not be able to start on the remote machine. This is because
bin_$arch (where $arch is the architecture of the system the user
interface is running on) is not present remotely. This problem
is much more subtle when you are starting up your own exec on
the remote system. The exec may start, but will not be able to
execute bin_$arch/dxshadow.
9. System Environment
A. Default Memory Size
Except where noted in the architecture specific README, by default,
Data Explorer will be allowed to grow to use all but 8 megabytes of
the physical memory when there is less than 64 megabytes of physical memory.
If there is more than 64 megabytes of physical memory, then Data Explorer
will, by default, be allowed to grow to 7/8 of the amount of physical
memory. Users may wish to alter this default amount of memory by using the
"-memory" parameter to the dx command, or the "Memory" field of the Connect
to Server--Options dialog.
B. Paging Space
Since it is possible for DX to use a large amount of virtual memory,
users should configure systems with paging space at least two or three times
the total physical memory in their system. If you do not have enough
paging space, the operating system may kill Data Explorer (or other
processes), sometimes without warning, depending on the architecture.
Run /etc/lsps -a to list all paging space. If you have N megabytes of
physical memory, (on most architectures) the first N megabytes of page space
are reserved to back that, so the available page space is the total listed
with lsps minus the physical you have.
C. Per Process Limits
Some systems may enforce per process limits on such things as
data segment size, stack size and so forth. These may need to be
adjusted to run Data Explorer with large amounts of memory to avoid
paging.
10. Notes on the Hardware Rendering Option
The behavior of Data Explorer differs in a few ways when using the
hardware rendering option.
A. Hardware rendering requires z-buffer capabilities. If hardware
rendering is attempted without a z-buffer card, a warning will
be given and the results are unpredictable unless otherwise specified
in the architecture specific README files.
B. Fast mouse button transitions may go unnoticed
When mouse button interactions are used in the image window to
perform rotate, navigate or roam, the image should be allowed to update
before the next mouse interaction is performed. Failure to do so may
cause the interaction to be ignored. This also means that when using
direct interaction in hardware rendering mode with `Execute-on-Change'
enabled, a change in the view (with mouse button depressed) is not
accepted until the current image is rendered. Thus, when rotating
complex objects cursor movements must be commensurate with rendering speed.
Rendering approximation can be used to increase the effective rendering speed.
C. Arrow keys partially disabled during navigation
During navigate mode, the use of the arrow keys to change the
'Motion' and 'Pivot' speeds is ignored until the mouse button is
released.
D. Button-down interaction disables visual program changes
When using hardware rendering with direct interactors in execute-on-change
mode, updates are ignored until the mouse button is released. This
is noticeable when rotating a scene which contains axes from AutoAxes.
The axes in the scene will not reflect the new camera position until the
mouse button is released and the AutoAxes module is allowed to re-run.
E. Remote OpenGL
Remote OpenGL can be run from an architecture on which Data Explorer
supports OpenGL (ibm6000, alpha, sgi) to another OpenGL capable
architecture (ibm6000, alpha, sgi), assuming the following conditions
are met:
The machine that the Data Explorer executive is running on must
have OpenGL support installed (i.e., /usr/lib/libGL.a is installed)
The machine the executive is displaying to must have OpenGL
suport installed (i.e., /usr/lib/libGL.a is installed) and the
X server must be configured to support OpenGL (i.e., the X server
must be started with the GLX extension).
11. Import/Export
A. The External Data Format
When using the Data Explorer external data format as described in
the User Guide, you must define an object before you
reference that object. For example, you must define an array before
you define the field in which the array will be placed, and you must
define a field before you define the group in which the field will
be placed.
12. Module Notes
A. Map Module
Map invalidates points outside of the domain of the map. Since Map is
also called internally by Color, points with corresponding data values
outside of the range of the colormap will be marked invalid. Similarly, when
an explicit gradient field is passed to the Isosurface module, the
gradient field must completely encompass the resulting isosurface.
B. Grid Module
Grid method "ellipse" assumes that the two given vectors in "shape"
are orthogonal.
C. The Display module and the screen-saver
If the screen-saver is on, Data Explorer will wait to display an image.
D. Slice Module limitation
The Slice module takes a slice from a grid, reducing the grid's
dimensionality by 1. This is in contrast to the Slab module which takes
a slice without reducing the dimensionality.
The Slice module will produce correct results only when the data form
an orthogonal grid with the first coordinate (x) varying the slowest,
and the last coordinate (z in a three-dimensional coordinate system)
varying the fastest. For regular grids, the delta vectors must be
a 0 0
0 b 0
0 0 c
for any a, b, and c. For data which do not fit this description, you
can use the Slab module instead to take a subset of the data, and then
use Mark(object,"positions"), Compute, and Unmark(object,"positions")
to remove the desired dimension from the object.
E. Transformed Group Members
It is recommended not to apply transforms to individual MultiGrid or Series
group members. In limited cases, this can cause abnormal termination.
F. Print Module
All values are printed in decimal format except for byte array data
which is printed in hexadecimal.
G. Morph and Filter Modules
Morph and Filter replicate the boundary cells into the overlap
region necessary to apply the filter.
H. Error/Changes in Documentation for SuperviseWindow
The manual page for SuperviseWindow indicates that the events output
is an array of integer 4-vectors. It is in fact an array of
integer 8-vectors. The first 4 integers in the 8-vector
are as discussed in the documentation; the last three integers
in the 8-vector are unused, and are reserved for future use.
The fifth integer is described as follows (this was recently
added, so the definition of the events structure differs from
what is in the documentation):
The handling of keypress events has been altered to make it possible
to handle modifier keys correctly. In this version, pressing the control,
shift or alt keys will no longer trigger an event. Instead, the state of
these keys affects other events that occur while these keys are pressed.
Thus, when the user presses the control key and, while it is being held,
strikes another key, a single event will be triggered. (In the past,
pressing the control key would have triggered its own event, returning a
character code of 0.) The character code generated for the event will be
the control version of the pressed key - eg. control-k or capital-K,
when the k key is pressed with the control key or shift key.
In addition, a field has been added to each DXEvent structure that contains
information about the current mouse and button state at the time of the event.
By looking at this structure element the user can determine whether the
modifier keys are being held down when the event is generated, thereby
differentiating between mouse interactions that occur with or without
these modifiers. This enables the user to implement a much wider range of
interactions within a single interaction mode.
In each DXEvent structure, the additional field occupies a place that was
previously reserved; therefore, the structure size does not change, nor does
the width of the event tuples produced by the events outputs of SuperviseWindow
and SuperviseState. The structures are currently:
typedef struct { typedef struct {
int event; int event;
int x; int x;
int y; int y;
int state; int key;
int kstate; int kstate;
} DXMouseEvent; } DXKeyPressEvent;
The event tuples are integer 8-vectors, with the above structures occupying
the first 5 positions. The kstate fields contain the following bit flags:
ShiftMask 0x0001
LockMask 0x0002
ControlMask 0x0004
Mod1Mask 0x0008
Mod2Mask 0x0010
Mod3Mask 0x0020
Mod4Mask 0x0040
Mod5Mask 0x0080
Button1Mask 0x0100
Button2Mask 0x0200
Button3Mask 0x0400
Button4Mask 0x0800
Button5Mask 0x1000
For more information regarding these state flags, see the Xlib documentation.
I. Error in Documentation for ManageImageWindow
The manual page for ManageImageWindow says that you can pass
the "window" (e.g. the "window" output of the Image tool)
of the window to be managed to the "name" parameter
of ManageImageWindow, if "how" is specified as "window". This is
incorrect. "how" must be either "title" or "label".
J. New parameter to Streakline, undocumented
An undocumented parameter has been added to the Streakline module.
Its name is "hold", and it defaults to 0 (false). If "hold" is set
to 1 (true), then Streakline uses the starting information (i.e.
the starting points and times) ONLY for frame=0. Streakline
will continue to use the values passed in for frame=0 for all
other frames. This simplifies the use of Streakline for the
case when vector fields are passed in one at a time, rather than
as a series group all at once; you can be sure that each frame will
use the same starting points and times, even if the values passed
in to those parameters happen to change due to other changes in the
visual program as the sequencer runs.
K. New module, DXLOutputNamed, undocumented
A new module has been added which is not included in the documentation.
Its name is DXLOutputNamed, and it differs from DXLOutput in three
ways. The first difference is that the name associated with the variable to be
passed to a DXLink application can be specified via a direct
input to the module, rather than by using the Notation field of
the configuration dialog box as with DXLOutput. The second difference
is that DXLOutputNamed can be placed inside a macro, while DXLOutput can not.
The third difference is that the User Interface
will not store the last value sent into/from DXLOutputNamed in the
.net file, as it does with DXLOutput. This means that you cannot
run the .net file without a DXLink connection and expect to see the
same result, which you could if you were using DXLOutput.
L. Parameter option for CategoryStatistics, undocumented
In addition to the documented options for the "operation" parameter,
"accum" is a valid option. The meanings of the various options are as
follows: "count" determines the number of items in each
category. "mean" determines the mean of the data values associated with
each category. "sd" determines the standard deviation of the data
values associated with each category. "var" determines the
variance of the data values associated with each category. "min"
and "max" determine the minimum and maximum respectively of the
data values associated with each category. "accum" determines the
accumulated value of all the data values associated with each
category.
M. Additional Control over VRML output using Export
There are a set of attributes which can be attached to an object to
control aspects of the vrml export of that object. These attributes
are the following:
"VRML Insert First Child Node" (Specifies a string which will be placed
into the VRML file as the first child Node of the overall group.
This attribute must be placed at the top level of the exported object.
For example, you may want to insert a TouchSensor to detect mouse
clicks. See the VRML specification for more information.),
"VRML Set NavigationInfo type" (Specifies a string which will be
inserted into the vrml object as the type field of the NavigationInfo node.
See the VRML specification for more information.),
"VRML use data as height" (Specifies a floating point value. If
specified, an ElevationGrid node will be created in the VRML output
instead of an IndexFaceSet. The "data" component is used as the
height field in the ElevationGrid node. The value of the
attribute is multiplied by each data value. This attribute must be
attached to the 2D regular field.),
"VRML font style" (the font style for the object. This can be applied
either to the entire object or to a field within an object. If you
set FontStyle for a field within a larger object, the field-level
font style overrides the object-level font style. If you do not
specify a font style, a default style will be used. See the VRML
specification for more information.).
"VRML text as string" (By default, labels on autoaxes and plots,
as well as text glyphs using AutoGlyph and Glyph, are
exported as geometry. This can amount to a large amount of data.
You can specify that labels and text glyphs be exported as
strings instead by setting this attribute to 1.)
A macro (ExportVRML.net) is provided in /usr/lpp/dx/samples/macros to
make setting these attributes easier.
Captions exported in VRML must be viewport relative.
13. X Colormap Interaction
A. 24 Bit Root Windows
By default, Data Explorer creates Image and Display windows of the same
depth as the root window, and the depth of the window is stored when
the visual program is saved. Because many visual programs, including
the supplied samples, are stored with 8 bit windows you may need to use
the mouse to point to the image in order to see the correct colors.
You can avoid this by using the Image Window Options menu to choose
"Image Depth" and to select 24 bits.
14. Scripting Language Lists cannot contain variables.
All items in lists must be constants.
15. Hints
A. All of the Execute Options are Greyed Out
This means that you are not connected to a Data Explorer executive.
Go to the Connection menu on either the image window or the editor
window. Choose "Start Server...". Type in the name of the machine
on which you are running the executive software, if it's not already there.
Press "Ok".
B. Faces/Loops/Edges
Some tools do not support faces, loops, and edges data. If you wish to use
more tools on this type of data, then convert it to triangles using Refine.
16. Notes on On-Line Help
Figures have been omitted from On-Line Help. Users are directed to the
hard copy manual at appropriate points in the On-Line Help. Alternatively,
you can use the html documentation available in /usr/lpp/dx/html.
17. Adding Modules
A. Building a Custom Executive
The Makefiles in /usr/lpp/dx/samples/user provides an example of how to
build a customized executive. Compiling a user defined module will
require an ANSI compliant C compiler which can support function prototypes
and the ellipsis notation (...) used in function declarations.
B. Outboard Modules
All outboard modules should link with the libraries "-lDXlite -lm".
A number of examples of outboard modules, along with makefiles for
each architecture and a README with more detailed information about
outboard modules may be found in the directory
/usr/lpp/dx/samples/outboard.
C. Modules written for Version 1
In order to compile a module written for Version 1 you need to include
#include <dx/rel_1_bc.h>
in your module.
D. Asynchronous Modules
By default, asynchronous modules by default are given a
CACHE_LAST attribute for outputs. This means that only the last
output of the module is cached. You can override this by
specifying CACHE_NONE (this is done either in the configuration
dialog box for the module or by using the Edit menu Output
Cacheability option). If you set the output to
CACHE_ALL, it will be reset to CACHE_LAST, since there is
no value to specifying CACHE_ALL for an asynchronous module.
It would be of value for users to also set the cacheability
of all outputs of modules downstream of the asynchronous module
to CACHE_LAST or CACHE_NONE.
E. Error in documentation for starting sample modules
The documentation tells you to start your custom module using
a command such as
dx -mdf ./showpick.mdf -exec ./dxexec
Because the default command dx now starts the startup ui, you
must instead include -edit, -menubar, or -image in the startup line,
for example
dx -edit -mdf ./showpick.mdf -exec ./dxexec
18. OSF/Motif Warning Messages
There are 3 groups of warning messages a user might see when Data Explorer
starts. Many of them appear when starting any OSF/Motif application.
G R O U P I:
These messages will appear only from Data Explorer. No other
OSF/Motif program will make these.
XtWarning:
Name: vpeDeleteOption
Class: XmPushButton
Illegal mnemonic character; Could not convert X KEYSYM to a keycode
XtWarning:
Name: endExecutionOption
Class: XmPushButton
Illegal mnemonic character; Could not convert X KEYSYM to a keycode
S O L U T I O N:
The Edit/Delete and Execute/End Execution options on the menubar in
Data Explorer require Delete and End keys respectively.
After you make the following modifications to $HOME/.motifbind,
restart your window manager if you're using mwm (or one of its cousins
like vuewm or 4Dwm), otherwise run xmbind.
For vpeDeleteOption add a line like this:
osfDelete :<Key>Delete
For endExecutionOption add a line like this:
osfEndLine :<Key>End
The 2 example lines above work for most machines although they
depend on the configuration of the machine at which you sit.
For hp700 workstations running hpux version 8 substitute
DeleteChar for Delete. For hp700 workstations running hpux version 9
substitute hpDeleteChar for Delete.
G R O U P II:
These messages are not specific to Data Explorer.
Those in Part A are common when displaying on an hp700 running hpux
version 9 or later. Those in Part B usually come from a system running
hpux 8 or earlier. You would also see messages like these if you had
a typographical error in $HOME/.motifbind.
Part A:
Warning: Cannot convert string "<Key>InsertChar" to type VirtualBinding
Warning: Cannot convert string "<Key>DeleteChar" to type VirtualBinding
Part B:
Warning: Cannot convert string "<Key>hpInsertChar" to type VirtualBinding
Warning: Cannot convert string "<Key>hpDeleteChar" to type VirtualBinding
S O L U T I O N:
Examine /usr/lib/X11/XKeysymDB on the machine
on which you are executing (which may not be the machine at which you
are sitting). The key name in the error message is not in that file.
Either modify the file, or find a substitute key to use in your
$HOME/.motifbind.
G R O U P III:
These messages are not specific to Data Explorer. They will appear
when running any OSF/Motif program.
XtWarning: translation table syntax error: Unknown keysym name: osfActivate
XtWarning: ... found while parsing '<Key>osfActivate:ManagerParentActivate()'
XtWarning: translation table syntax error: Unknown keysym name: osfCancel
XtWarning: ... found while parsing '<Key>osfCancel:ManagerParentCancel()'
XtWarning: translation table syntax error: Unknown keysym name: osfSelect
XtWarning: ... found while parsing '<Key>osfSelect:ManagerGadgetSelect()'
S O L U T I O N:
You must have a recent version of the file /usr/lib/X11/XKeysymDB in
order to run OSF/Motif programs. Most manufacturers provide one
but older versions of SunOS with OpenWindows, machines
with custom installations, and possibly a few other workstations
will not have one. With some releases of the X Window System it
is acceptable to set the environment variable XKEYSYMDB to the
path name of a valid XKeysymDB file. (There is no way to tell
if yours is among them other than to try it.)
You could also add the following entries to your /usr/lib/X11/XKeysymDB:
osfCopy :1004FF02
osfCut :1004FF03
osfPaste :1004FF04
osfBackTab :1004FF07
osfBackSpace :1004FF08
osfClear :1004FF0B
osfEscape :1004FF1B
osfAddMode :1004FF31
osfPrimaryPaste :1004FF32
osfQuickPaste :1004FF33
osfPageLeft :1004FF40
osfPageUp :1004FF41
osfPageDown :1004FF42
osfPageRight :1004FF43
osfActivate :1004FF44
osfMenuBar :1004FF45
osfLeft :1004FF51
osfUp :1004FF52
osfRight :1004FF53
osfDown :1004FF54
osfEndLine :1004FF57
osfBeginLine :1004FF58
osfEndData :1004FF59
osfBeginData :1004FF5A
osfPrevMenu :1004FF5B
osfNextMenu :1004FF5C
osfPrevField :1004FF5D
osfNextField :1004FF5E
osfSelect :1004FF60
osfInsert :1004FF63
osfUndo :1004FF65
osfMenu :1004FF67
osfCancel :1004FF69
osfHelp :1004FF6A
osfSelectAll :1004FF71
osfDeselectAll :1004FF72
osfReselect :1004FF73
osfExtend :1004FF74
osfRestore :1004FF78
osfDelete :1004FFFF
----------------------------------------------------------------------
The following trademarks apply to this information:
IBM is a registered trademark of International Business Machines Corporation.
IBM Visualization Data Explorer is a trademark of International
Business Machines Corporation.
Motif is a trademark of Open Software Foundation, Inc.
OSF and OSF/Motif are trademarks of Open Software Foundation, Inc.
Sun is a registered trademark of Sun Microsystems, Inc.
HP is a registered trademark of Hewlett-Packard Company.
NFS is a registered trademark of Sun Microsystems, Inc.
X Window System is a trademark of Massachusetts Institute of Technology.
DGC is a trademark of the Data General Corporation.
DEC 3000 APX is a registered trademark of Digital Equipment Corp.