* * 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. * * (C) COPYRIGHT International Business Machines Corp. 1991-1997 * All Rights Reserved. * Licensed Materials - Property of IBM * * US Government Users Restricted Rights - Use, duplication or * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. * * 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 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 :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 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 :Delete For endExecutionOption add a line like this: osfEndLine :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 "InsertChar" to type VirtualBinding Warning: Cannot convert string "DeleteChar" to type VirtualBinding Part B: Warning: Cannot convert string "hpInsertChar" to type VirtualBinding Warning: Cannot convert string "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 'osfActivate:ManagerParentActivate()' XtWarning: translation table syntax error: Unknown keysym name: osfCancel XtWarning: ... found while parsing 'osfCancel:ManagerParentCancel()' XtWarning: translation table syntax error: Unknown keysym name: osfSelect XtWarning: ... found while parsing '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.