DX(1V)

📦 version 4.4.4, in fedora 43, fedora 44

💖 DX(1V) — the manual page, but make it make sense 💖

okay bestie, sit down, hydrate, because this is the dx page from the DX(1V) manual and it's a whole journey. it's long so we're doing it in three parts, and this is part one. let's get into it 🦋

✨ NAME ✨

dx — start the Data Explorer visualization system. and if you want, you can also just go straight to the User Interface (dxui), the executive (dxexec), the Data Prompter, the Module Builder, or the Tutorial. like, pick your fighter 💅

✨ SYNOPSIS ✨

here's the whole vibe, in one block. copy it, don't retype it, i'm begging you 🙈

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]

and then there's the shortcut era 🎀:

dx   -prompter      ( start the Data Prompter )
     [ -full ]
     [ -file ] [ < header file name > ]
dx   -builder  ( start the Module Builder )
     [-file ] [ < .mb file name > ]

✨ DESCRIPTION ✨

so. dx is the command. it starts the Data Explorer Startup Window, and if you want, it also kicks off the Data Explorer User Interface, the Data Explorer Executive, the Data Explorer Data Prompter, the Data Explorer Module Builder, or the Data Explorer Tutorial. that's a lot of doors and you're holding all the keys, periodt 🔑

the Data Explorer Startup Window is an X windows/Motif based application, and its whole thing is making the other subsystems of the Data Explorer visualization system easy to get to. it's giving helpful front desk energy 🫶

the Data Explorer User Interface is also X windows/Motif based. it hands you a visual programming environment and an interface to the executive. the executive is the one doing the actual work — it's got the computational tools and the mechanisms to create data visualizations. the pipeline girlies know ✨

the Data Explorer Data Prompter is an X windows/Motif based application that helps you import data in a variety of formats, and it comes with general purpose visual programs so you can visualize the data you just imported. the goal? a shortened "time to first picture". honestly iconic, that's the whole dream 🎀

the Data Explorer Module Builder is an X windows/Motif based application that helps you build your own modules so they can live inside a custom version of Data Explorer. main character energy fr 💅

the Data Explorer Tutorial is an application that teaches you Data Explorer by walking you through a sequence of tasks. and the best part? you can skip around super easily so you can focus on the tasks that actually matter for your work. no forced linear grind, we love to see it 🌸

💖 okay so if you want the full lore: 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. and for a more thorough description of the Data Explorer Module Builder, see the IBM Visualization Data Explorer Programmer's Reference. 🫶

more parts incoming, don't go anywhere bestie 💜

✨ OPTIONS ✨

okay so bestie 🫶 if you run dx with no options at all, it just starts the Startup Window — which is this X windows/Motif program that's basically the ✨lobby✨ of the whole Data Explorer system, and it's where you launch all the other parts from. But you can also poke at it with a bunch of command line options and environment variables to change the default behavior. All of them are listed below, obviously 💖

The order situation (important!!): options you put in the DXARGS environment variable get dropped at the start of the command line, then come the ones set by environment variables, and then finally your explicit command line arguments. And when two options are beefing with each other? The last one wins. periodt.

  • -8bitcmap < private | shared | 0-1 | -1 > — Overrides the DX8BITCMAP environment variable (peep the ENVIRONMENT VARIABLES section below for the deets).
  • -cache < on | off > — turns the executive caching system on or off. When the Data Explorer caching mechanism is enabled, the executive automatically caches the intermediate results it generates while doing its visualization computations. And no, it's not like your standard caching — these results are accessed by means of their functional derivation. Which is iconic because it allows automatic graph optimization and helps dodge recomputing stuff you already used before, especially when the Data Explorer sequencer is doing its thing. That said, in certain rare instances a machine with a small amount of memory might wanna disable this to conserve memory and reduce paging. Default = on. 💅
  • -colors < colors file > — Override the DXCOLORS environment variable (see ENVIRONMENT VARIABLES below).
  • -connect < host:port > — starts a distributed executive only, no user interface. Just the executive, main character energy, alone.
  • -data < path list > — Override the DXDATA environment variable (see ENVIRONMENT VARIABLES below).
  • -directory < dir > — makes the executive run in the directory you give it.
  • -display < display name > — sets the name of the X display that the user interface and the executive are gonna use.
  • -dxroot < dir > — Overrides the default dx root directory.
  • -echo < dir > — Echoes the command lines without actually executing them. (all talk no action, relatable 🙈)
  • -edit — makes the user interface start with the Visual Program Editor (VPE) window as the top level window of the UI. Btw the top level window is the one marked by an anchor in the upper left hand corner. Also see -image, -startup, and -menubar.
  • -encode < filename > — Encodes the given file into a binary format with a key (and the key must be specified with the -key option, no key no encode). 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 one's for the DIY girlies: it lets a user build and use their own custom executive. 🛠️
  • -execonly — Starts the executive in remote mode, where it just waits around for a connection from the user interface. The user interface does not start with this option. Also see -script.
  • -execute — Execute once after the user interface has made a connection with the executive.
  • -execute_on_change — Makes Data Explorer go into execute-on-change mode at start up. Execute-on-change mode means the Visual Program gets executed any time any of the values in the program change (like module inupts, interactor values...). 👀
  • -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 — Prints a brief listing of options and usage for dx.
  • -highlight < on | off > — turns module execution highlighting on or off. If highlighting is on, the user interface highlights each module as it's executed (so cute, so satisfying ✨). 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 — makes the user interface start with the image window as the top level window. Also, control panels that are configured to open automatically get opened. Also see -edit, -startup and -menubar.
  • -include < path list > — Override DXINCLUDE environment variable (see ENVIRONMENT VARIABLES below).
  • -key < 64bit hex > — a 16 character hexidecimal (64bit) number that's 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 the 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 it's set) and make the executive run on the local host. And if there's no DXHOST environment variable at all? Then this is already the default, bestie.
  • -log < on | off > — turns executive logging on or off. If logging is on, 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 get 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're 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's 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 > — turns the executive timing mechanism on or off. If enabled, then when the executive exits it will list on standard output or the logging file the timing statistics for each module that was used during the course of execution. Default = off.
  • -trace < on | off > — turns the executive trace mechanism on or off. 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 — makes the user interface start without making a connection to an executive.
  • -verbose — Echo commands in the dx script as they're executed.
  • -version — Print version numbers of various executables.

🌈 ENVIRONMENT VARIABLES 🌈

okay bestie listen up, these are the little vibe-setters that live in your shell 🫶 They give you an alternate way to set some of the command line options, or to tweak how Data Explorer behaves by default. The override rules are very much a hierarchy, so pay attention 💅:

  • Options set with environment variables get overridden if the same option is also given on the command line.
  • Options set with DXARGS get overridden by both environment variables and explicit command line options. So DXARGS is at the bottom of the pecking order, no cap.
  • DX8BITCMAP — when Data Explorer shows images in 8-bit windows, it tries so hard to make an accurate representation using the default colormap that's shared among applications using 8-bit windows. But if the colors DX needs aren't in the colormap, and there aren't enough free color cells available in the shared colormap to allocate them, DX will go hunting for approximations among the colors that are available. Sometimes though, the difference between the color you wanted and the approximation is just too great to accept 😭. In those situations DX allocates a private colormap for more accurate results. Heads up: depending on your X server, you may need to move the mouse to select the Image or Display window for the correct colors to appear. The -8bitcmap flag sets the level at which the switch to a private colormap happens. The value should be a number between 0 and 1, or "private" or "shared", and it represents the Euclidean distance in RGB color space, normalized to 1, for the maximum allowed discrepancy. Set it to 1 and a private colormap will never be used. Set it to -1 and a private colormap will always be used. Default is 0.1.
  • DXARGS — holds the default set of arguments used by the dx script. These arguments are prepended to the ones you give dx on the command line. It's the cute little customization hook for the dx command. ✨
  • DXAXESMAXWIDTH — sets the number of digits in axes tick labels at which a switch to scientific notation is made. Default is 7.
  • DXCOLORS — the name of an alternate file containing mappings of color names to red, green, blue triplets, in a format like the default color file found in /usr/lpp/dx/lib/colors.txt.
  • DXDATA — a colon separated list of directories where 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 when 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 keep rotating until you click inside the image. The direction and speed of the mouse motion before you release will affect the rotation direction and rotation speed of the object in the window. It's giving physics, honestly.
  • 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. This overrides the value set by DXGAMMA. 👑
  • DXHOST — the name of the host machine that will run the executive. If this isn't set, 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 — a colon separated list of directories in which the executive will search for "included" scripts. Also see the -include option.
  • DXMACROS — a colon separated list of directories in which the user interface searches for macros that will be automatically loaded. When running in script mode you have to "include" all the macros by hand before referencing them, no shortcuts there bestie. Also see the -macros option.
  • DXMDF — 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 — 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. But listen: there's a consequent decrease in performance if this environment variable is set. Trade-off city. 💀
  • DXNO_BACKING_STORE — if set to anything, disables framebuffer readbacks. Setting this may improve performance of interaction with hardware rendered images, especially for machines where readback is slow. Default behavior is that framebuffer readbacks are enabled. If you set this, note that some interactions using the Image tool will result in a black image while the interaction is taking place. However, if you're 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. It can be set to either DXByte (24 bits) or DXFloat (96 bits). Setting it to DXByte means images take 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 (like when you're using distributed execution). The default is 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) it will cause the data segment to simply be extended. Please see Appendix C of the Data Explorer User Guide for more info. 📖
  • DX_SOCKET_BUFSIZE — lets you specify the size of the send and receive buffers for the socket connection between the UI and the exec. This value is clamped to the max allowed by the system. It can fix a problem where the executive and UI hang, involving a deadlock situation in the socket communication. The value you assign gets passed as the parameter to setsockopt for SOL_SNDBUF and SOL_RCVBUF. A typical 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 system's default web browser. 🌐

💖 EXAMPLES 💖

The next few examples assume that none of the DX environment variables have been set. Clean slate, main character energy. ✨

  1. To start both the user interface and the executive with the network named cfd.net:
dx -edit -program cfd
  1. 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
  1. To run just the executive on the script named f15wing:
dx -script -file f15wing
  1. 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
  1. To start the Data Prompter:
dx -prompter
  1. To start the Module Builder:
dx -builder
  1. 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. Go read, bestie, it's free knowledge. 📚

and that's the whole page, babes 🎀 this one came from IBM Visualization Data Explorer, filed as DX(1V) — that's the source and the version label on the footer, and it's lowkey iconic for it. go forth and render something gorgeous. mwah. 💅✨🦋

📦 where this page comes from