User's Guide - Data Explorer Scripting Language

## Chapter 10. Data Explorer Scripting Language

Partial Table-of-Contents

- 10.1 Starting Data Explorer in Script Mode
- Setting Environment Variables
- 10.2 Understanding the Script Structure
- 10.3 Language Delimiters
- Commenting Scripts
- Naming Variables and Macros
- Specifying Values in a Script
- 10.4 Building Expressions and Statements
- Arithmetic Expressions
- Assignment Statements
- Function Call Assignments
- 10.5 Invoking Data Explorer Macros and Modules
- Function Call Arguments
- Function Call Attributes
- 10.6 Defining Macros
- Macro Header
- Macro Body
- Macro Examples
- 10.7 Using Data Explorer Script Commands
- Sequencer
- File Inclusion
- Prompts
- 10.8 Understanding the Script Execution Model
- Top-level Environment
- Function Execution
- Macro Expansion
- Variables Used in Macros
- Assignment and Function Call Semantics
- Execution Example
- 10.9 Running .net files in script mode

  When you create a visual program with the graphical user interface, Data Explorer saves the program in a `.net` file. This saved version is actually a set of scripting-language commands. You do not need to understand the script language unless you are running Data Explorer in script mode.

  In Data Explorer script mode you can also perform tasks that would be awkward with a visual program (e.g., facilitation of batch processing or debugging of a module).

  ## 10.1 Starting Data Explorer in Script Mode

  To run Data Explorer in script mode on a workstation, you must have an account on that workstation.

  To start Data Explorer, follow these steps:

  1. Start the X Window System session on the workstation.

  2. Type:

         dx -script

     When script mode starts, you will see a prompt symbol (`dx>`), indicating that Data Explorer is ready to accept input. (If you want to change the prompt symbol, see 10.7 , "Using Data Explorer Script Commands".)

  (All of the command line options for Data Explorer are described in C.2 , "Command Line Options".)

  You can type commands directly at the command line, but you may find it more convenient to create a script and submit it to Data Explorer for execution. To submit a script, type:

      include "scriptname"

  at the prompt, where scriptname is the name of the script.

  Once you have submitted a script, Data Explorer will process the commands it contains. Note that none of the direct interactor options are available in script mode: you must use the Image tool in the graphical user interface to take advantage of those options.

  After the included script has been processed, you can include another script. To terminate your Data Explorer session, type:

      quit

  You can also include a script name directly in the script command: add the name of the script after the `-script` option. Data Explorer will terminate automatically when it has executed the script. For example, type:

      include "/usr/local/dx/samples/scripts/scriptexample"

  You will see a sequence of images created with sequencer commands. The directory `/usr/local/dx/samples/scripts` contains examples for many modules. You may find it helpful to experiment with them to learn how they function.

  Note: To ensure that an example program does not exit before you want it to, invoke script mode first and then "include" the program. Otherwise, some programs will execute and disappear so quickly that you won't be able to identify the image.

  ### Setting Environment Variables

  There are several environment variables that you may find useful to customize Data Explorer. These can be set in your login profile.

  ##### DXDATA

  The DXDATA environment variable specifies a list of directories in which Data Explorer will search for data files. If the data you wish to import is in one of the directories specified in the DXDATA environment variable, you do not need to provide the complete path name to the Import tool. Specify the file name, and the Import module will look in the specified directories for the data file. The directories will be searched in the order in which they are listed in the environment variable; and the first occurrence of the data file will be used.

  An example of a statement that sets the DXDATA environment variable (in the C shell environment) is the following:

      setenv DXDATA /usr/mydirectory/mydata:/usr/group/groupdata

  where `/usr/mydirectory/mydata` and `/usr/group/groupdata` are two directories that contain data files. Multiple directories can be listed, with each directory name separated by a colon.

  ##### DXHOST

  The DXHOST environment variable is the initial machine name of the server on which to run the executive. If DXHOST is not specified, then a default of "localhost" is used. See 9.3 , "Connecting to the Server" for more information on how to connect to the server. The host name should be the name that results when you issue the `uname -n` shell command.

  ##### DXINCLUDE

  If this environment variable is set, Data Explorer looks for included scripts first in the current directory, and then in each of the directories specified in the colon-separated list specified by this variable.

  ##### DXMACROS

  The DXMACROS environment variable is a list of the directories in which Data Explorer will look for macros.

  [ OpenDX Home at IBM | OpenDX.org ]