





                      THE CIEX COMMAND INTERFACE EXECUTIVE
                            Base Distribution, V2.3.5
               Copyright 1993, 1994, New Line Software, Inc. (NLS)
                      APPLICATION NOTES / COMMAND REFERENCE


                                TABLE OF CONTENTS

   1.0 INTRODUCTION                                      ...............  2

   2.0 SYSTEM REQUIREMENTS                               ...............  3

   3.0 CONFIGURING THE CIEX DEMO SCRIPTS                 ...............  4

   3.1 CONFIGURING FOR AN MS-DOS ENVIRONMENT             ...............  4
   3.2 BINDING SCRIPTS INTO EXECUTABLE PROGRAMS          ...............  5
   3.3 CONFIGURING FOR AN MS-DOS WINDOWS ENVIRONMENT     ...............  5

   4.0 DESCRIPTION OF DEMONSTRATION SCRIPTS              ...............  5

   4.1 THE DEMO.S PROGRAM                                ...............  6
   4.2 THE INTRO.S PROGRAM                               ...............  6
   4.3 THE EVAL.S PROGRAM                                ...............  8
   4.4 THE ADDR.S PROGRAM                                ...............  9
   4.5 THE CALENDAR.S PROGRAM                            ............... 10
   4.6 THE REACTOR.S PROGRAM                             ............... 12

   5.0 CIEX V2.3.5 COMMAND REFERENCE                     ............... 13

   5.1 ALPHABETICAL LISTING OF ALL COMMANDS AND OPTIONS  ............... 13
   5.2 SPECIAL PROGRAM CHARACTERS                        ............... 29
   5.3 VARIABLES                                         ............... 30
   5.4 MATH EXPRESSION EVALUATOR                         ............... 33
   5.5 CONDITIONAL TESTING                               ............... 33
   5.6 WILDCARDS                                         ............... 36
   5.7 CALLPOINTS                                        ............... 37
   5.8 COMMON PROBLEMS                                   ............... 39

   6.0 ADDITIONAL NOTES                                  ............... 40

                                  Page: 2

   1.0 INTRODUCTION

   This manual describes the CIEX Version 2.3.5 Base Distribution. It
   provides details on how to use CIEX, and on different ways to configure
   the base distribution demo files. In particular, section 5.0 of this
   manual presents an explanation of all CIEX commands and their usage.
   Also included are narratives on the demo scripts themselves, to assist a
   programmer with modifications or experimentation.

   For easiest understanding, the user should first execute the CIEX V2.3.5
   demo scripts (especially the INTRO.S script) before reading these notes.
   To execute the main CIEX demo script, change to the disk and directory
   where the CIEX distribution files reside, and type "DEMO" at the DOS
   prompt.

   1.1 DESCRIPTION

   CIEX is a VHLL (Very High Level Language) designed for text and data
   processing. It supports DOS commands, advanced math functions, text
   parsing and replacement using wildcards, multidimensional data arrays
   and records, and screen buffered text-graphic output. CIEX is easy to
   learn, and can readily be used for batch type jobs. But CIEX is also
   intended for use in professional programming activities, including large
   software systems. CIEX incorporates many features to support these
   dissimilar roles, and strives to be at the forefront of VHLL technology,
   which is considered by some to be the long sought cure for many endemic
   problems of software development.

   The CIEX interpreter reads commands from a disk file (or from the
   keyboard), and executes these commands, similar to the way that MS-DOS
   COMMAND.COM and UNIX shell programs operate. CIEX executes in two
   distinct modes: in executive mode, programs are launched by typing
   "ciex (scriptname) (arguments)" at a DOS prompt. In interactive mode,
   CIEX generates its own command prompt, and accepts keyboard commands to
   launch programs or list data. Interactive mode makes the CIEX
   programming language particularly easy to experiment with, since
   commands can be entered at the keyboard without need to create a disk
   file program.

   While CIEX serves as a powerful general purpose programming language, it
   should be noted that CIEX was originally designed to operate as a
   generic command line interface to arbitrary object libraries. This is a
   major precept and constraining influence on the language syntax and
   program architecture. CIEX is intended to be a scaffold upon which more
   advanced and specialized programming languages can be built. CIEX has
   been extended to work as an SNMP network manager, GPIB instrument
   controller, and the front end for various graphic libraries. Using CIEX
   in this manner may well achieve the highest productivity possible from
   any programming system.  While a complete discussion of this topic is
   beyond the scope of this manual, information on extensibility and the
   CIEX Language Development Call Library (LDCL) is available from New Line
   Software, Inc.

                                  Page: 3

   1.2 CIEX.EXE PROGRAM

   The CIEX.EXE file is the executable CIEX interpreter. It is the only
   non-text file that comes with the base CIEX distribution, and is a fully
   functional, non-crippled CIEX interpreter. It is provided to qualified
   users FREE by New Line Software, Inc. to encourage experimentation with
   its many features.

   To use the CIEX interpreter interactively, simply type "ciex" at a DOS
   prompt. At the "ciex>" prompt, users may run CIEX programs using the
   "source" command, enter CIEX commands such as "set", "echo", and "list",
   or execute MS-DOS commands. (See section 5.0.) To return to DOS, type
   "exit". To stop a CIEX script while it is running, use the "Shift-Break"
   key.  CIEX implements a history mechanism at its command line similar to
   that found in MS-DOS Version 5, i.e. previous commands can be recalled
   using the "up" arrow key.

   To become familiar with CIEX, we suggest that new users experiment with
   commands interactively. In particular, issuing the "echo -on" command at
   the "ciex>" prompt causes each subsequent CIEX command to be displayed
   before it is executed. The "echo -off" command will turn off command
   echoing. This facility affords a fair amount of debug information when
   executing scripts. The optional CIEX Development Environment, not
   included as part of the base distribution, provides a more powerful,
   full screen, interactive debugger which can be used to single step and
   modify program data while a CIEX script executes. The "echo -on" command
   provides a useful, if rudimentary, built-in alternative in lieu of the
   CIEX interactive debugger.

   Please note that the most common mistake new CIEX programmers make is to
   forget that CIEX is a CASE-SENSITIVE language; all CIEX commands must be
   entered in lower-case letters (although DOS commands and file names can
   be entered in either upper or lower case letters.) Normally, CIEX users
   work with the "Caps Lock" key OFF. (See section 5.8.)

   1.3 DEMO SCRIPTS

   Five demo scripts are included in the base distribution. These scripts
   are described in detail in section 4.0 of this note, and represent a
   small subset of possible applications of the CIEX interpreter. The
   programs are intended to be typical CIEX scripts, and do not incorporate
   particularly sophisticated algorithms or any special tricks that new
   users might find too clever or overly complicated. In particular, the
   scripts are structured, but are not particularly object-oriented. They
   could be made much more terse and efficient, but only by sacrificing
   some of the readability and understandability of the scripts.

   2.0 SYSTEM REQUIREMENTS

   The CIEX interpreter is specifically designed to operate from a 386 or
   486 PC hard disk. The interpreter will execute from earlier PC models
   and from floppy disk drives, but execution speed will be substantially
   degraded. Note that the CIEX interpreter creates several temporary files

                                  Page: 4

   while it executes, and therefore will not execute on a write protected
   disk. Temporary files are maintained in the directory specified by the
   "TEMP" DOS environmental variable, or in the local directory if the
   "TEMP" variable is not set.

   To execute typical programs, the CIEX interpreter needs FILES=10 and
   BUFFERS=16. Usually, the CIEX interpreter will require no special
   adjustments to a hard disk's CONFIG.SYS file in order to operate.

   Because CIEX scripts execute DOS internal and external commands, scripts
   can be particularly sensitive to DOS revision levels. The scripts in the
   base distribution require a DOS version of 3.0 or greater.

   CIEX scripts can be memory intensive. The scripts in the base
   distribution require at least 512 K Bytes of RAM to execute. Marginal
   performance can be achieved with 256 K Bytes of RAM, but running CIEX in
   this configuration is not recommended.

   CIEX makes use of colors if available, but will execute on monochrome
   displays. Colors in the demonstration programs have been conservatively
   selected to run on a variety of displays. In particular, no filled boxes
   or shadow boxes are used in the demonstration programs, although the
   interpreter fully supports both.

   3.0 CONFIGURING THE CIEX DEMO SCRIPTS

   The base CIEX Version 2.3.5 distribution is intended to supply both an
   overview of the CIEX interpreter, and also provide useful programs. If a
   user does not want to learn how to write CIEX scripts this time, but
   would still like to continue executing the demonstration programs,
   several methods of configuring the demo scripts are possible, as
   described in this section.

   3.1 CONFIGURING FOR AN MS-DOS ENVIRONMENT

   The most obvious way to configure a demo program is to create a simple
   batch file, which changes working directories to the C:\CIEX directory
   (or other directory where the demo script resides), and then executes
   the specified script with CIEX. For example, to execute the EVAL.S
   program, use the following batch file:

           REM : Filename EVAL.BAT
           cd c:\ciex
           ciex eval.s

   The above batch file assumes the base distribution is installed in the
   directory C:\CIEX. Similarly, any of the other demo scripts can be
   executed by replacing the "EVAL.S" argument above with one of the other
   script file names. Note that, because of the way in which demo scripts
   are written, the "cd" command is required for proper operation.
   Adventurous programmers can modify the scripts to make them path
   independent.

                                  Page: 5

   3.2 BINDING SCRIPTS INTO EXECUTABLE PROGRAMS

   A minor inconvenience of the above method is that it requires three
   separate files to execute a CIEX script, specifically the batch file,
   the script file, and the CIEX executable itself. A much better way of
   configuring a script is to bind the script to an executable copy of the
   interpreter. This produces an ".EXE" file from a script which is not
   visibly different from any other ".EXE" file, and promotes ease of
   installation and data privacy.

   To bind a script to a copy of the CIEX interpreter, simply issue the
   command "ciex -bind (scriptname)" at a DOS prompt, or issue the command
   "source -bind (scriptname)" at the "ciex>" prompt. This creates an
   ".EXE" file that has the same basename as the specified script file. The
   resulting file can be executed at a DOS prompt without the CIEX
   interpreter being present.

   Any CIEX script can be bound in this way. Using this technique, systems
   of programs can easily be created which call and are called by other
   bound and non-bound script files. Such systems are very object-oriented,
   easy to maintain and develop, and embody a unique approach to large
   scale software development.

   3.3 CONFIGURING FOR AN MS-DOS WINDOWS ENVIRONMENT

   CIEX can be executed in a MS-DOS Windows environment, allowing CIEX
   scripts to be written and accessed from Windows. A PIF file is supplied
   for the DEMO.S script in the file DEMO.PIF. Users may create PIF files
   for the other demo programs as well, using the standard Windows PIF
   editor.

   Assuming that the distribution files reside in the disk directory
   C:\CIEX, the DEMO.S program can be installed in a Windows environment
   by performing the following steps:

        1. From the Windows Program Manager, choose FILE, and NEW.
        2. In the "New Program Object" window, click on OK.
        3. Enter "CIEX Demo" (or some other title) for the Description.
        4. Enter C:\CIEX\DEMO.PIF for the Command Line.
        5. Enter C:\CIEX for the Working Directory.
        6. Optionally select an ICON using the "Change Icon" button.
        7. Click on OK to close the screen.

   Similarly, other demo scripts can be installed by creating and entering
   the appropriate PIF file pathname. (The above procedure assumes that the
   demo is installed in the directory C:\CIEX.)

   4.0 DESCRIPTION OF DEMONSTRATION SCRIPTS

   This section describes the demo programs which accompany the CIEX V2.3.5
   base distribution, and is intended to provide a cursory explanation of
   how CIEX operates. More detailed information on commands used by the
   demo scripts may be found in section 5.0 of this note, and within the
   CIEX Command Reference Manual, available from New Line Software, Inc.

                                  Page: 6

   Users are encouraged to experiment with one or more of the demo scripts
   to evaluate the capabilities of the interpreter. Each script can be
   edited using any standard text editor, such as "emacs" or the MS-DOS
   "edit" editor. Of course, prior to editing any demo script, backups
   should be made to allow the original scripts to be restored if undue
   problems are encountered with the modified programs.

   4.1 THE DEMO.S PROGRAM

   The DEMO.S program is the top level demo executive script. It can be
   used to run the CIEX demo scripts, and includes explanatory information
   on each script before it is executed. Note that all other scripts in the
   base distribution can be executed directly, and do not depend on the
   DEMO.S script. Users can execute these other demo scripts with the
   "source" command at the "ciex>" prompt, or by typing "ciex (filename)"
   at the DOS prompt.

   DEMO.S a straightforward menu system. On startup, the DEMO.S program
   displays a menu and waits for a selection. The selection is decoded to
   perform a particular action, after which the script returns to wait for
   additional input, redisplaying the menu as needed.

   When the F10 key is selected, the exit screen is displayed by flushing a
   screen dump (included inline) to the screen. This screen dump was
   created using the LIBFONT.S program (provided with the optional CIEX
   Development Environment), which allows block letters to be created of
   the style shown. In general, any screen can be saved to a file with the
   CIEX command "screen -save (filename)" and subsequently restored using
   the CIEX command "screen -flush (filename)".

   4.2 THE INTRO.S PROGRAM

   The INTRO.S program allows the operator to quickly page through a
   document with numbered paragraphs. The INTRO.S program was created
   automatically from another CIEX program (called VGCOMP), included as
   part of the optional CIEX Development Environment, but omitted from the
   base distribution.

   4.2.1 INTRO.S OPERATION

   The INTRO.S program consists of two main parts. The first part of the
   script is the control segment, followed by a lengthy data section
   containing the text information to be displayed.

   On startup, the INTRO.S program draws the initial screen, and then
   enters a service loop. In this loop, the program waits for a key to be
   depressed, and then decodes the key value with an "if-else if" case
   select. If a function key is selected, the appropriate callpoint is
   executed to process the new screen. If the current screen displays a
   menu, special processing is performed to handle the numeric keys
   associated with menu items.

                                  Page: 7

   When the case select is finished, if no match is found for the key, the
   program redraws the control bar and performs no other action. If a match
   is found, the selected screen is drawn.

   The data section of the program consists of various callpoints
   identified as 'A', 'A.1', 'A.1.1' (etc). Each callpoint represents one
   numbered paragraph of the source document. Each callpoint provides a
   title, a page number, a possible menu, and a block of text. The text is
   automatically wrapped to the margin using the "echoblock -wrap" command.
   The particular margin is determined in the main program based upon the
   paragraph nesting level.

   The last part of the data section is a definition of the paragraph
   nesting levels, and other parameters gleaned from the source document
   by the VGCOMP program.

   4.2.2 MODIFYING INTRO.S

   A programmer can make several modifications to INTRO.S. The colors used
   in the program are assigned at the top of the script. A programmer may
   modify the "$titlecolor", and other assignments, to change the way the
   display looks. A programmer can also change the function keys used in
   the program, and modify the "draw_ctrl_bar" callpoint to change the
   appearance of the control bar at the bottom of the screen.

   A programmer may also change the titles and content of the displayed
   paragraphs. Note that the text is automatically wrapped, and multiple
   spaces removed from each block of text, providing a good deal of ease
   and latitude when modifying paragraphs. Unfortunately, it is not easy to
   add or delete paragraphs, or change the paragraph ordering, since these
   attributes are determined by the VGCOMP program.

   4.2.3 LISTING THE INTRODUCTION TO A FILE OR SCREEN

   The source document, which was processed by VGCOMP to create the INTRO.S
   script, can be output in a format suitable for printing using the
   "list_source" callpoint, included in the INTRO.S script. The
   "list_source" callpoint is not used by INTRO.S directly. It is provided
   solely as a convenience for dumping the source document to the screen
   or file. To list the source document, perform the following steps.

        1. Invoke CIEX interactively by typing "ciex.exe" at a DOS prompt.

        2. At the "ciex>" prompt, type: "source -calls intro.s" to allow
           access to the INTRO.S program callpoints from the keyboard, as
           described in section 5.7.

        3. At the "ciex>" prompt, issue the command: "call list_source"
           to list the source document to the screen.

   As with all other CIEX commands, the "call list_source" statement can be
   redirected to a file or printer using the ">" operator. Note that the
   callpoints of any arbitrary program can be made accessible to the

                                  Page: 8

   keyboard (and other CIEX scripts) using the "source -calls" statement.
   The names of the currently accessible callpoints can be determined using
   the "list -calls" statement, and are removed using the "set -clear" or
   "unset -calls" statements.

   4.3 THE EVAL.S PROGRAM

   The EVAL.S program is a simple script which accepts a user equation and
   derives a resulting value. Most of the work is performed by the CIEX
   interpreter's mathematical statement evaluator, which both evaluates the
   equation input by the user, and performs error checking of the input and
   result. (See section 5.4.)

   The largest part of the EVAL.S program is dedicated to displaying help
   screens, which document the various functions of the CIEX evaluator. In
   particular, these help screens provide information on the evaluator
   capabilities not stated elsewhere in the CIEX V2.3.5 base distribution.

   4.3.1 EVAL.S OPERATION

   On startup, the EVAL.S program sets up the screen by calling the
   "setup_screen" callpoint, initializes various parameters, and then
   enters the main service loop of the program. Within this service loop,
   the EVAL.S program gets an equation from the user by executing the
   "get_equation" callpoint. The input equation is assigned to the variable
   "$input:equation", and then post-processed by adding the "fix" operator
   (used by the evaluator to specify the number of decimal places in the
   result). The complete math expression, residing in the variable
   "$temp_eval" is then passed to the evaluator using a "set -eval"
   statement. The result of the evaluation is assigned to the variable
   "$result".

   The "set -eval" statement is executed in an "if -cmd" statement, which
   causes the program to branch if the command fails. If the value of
   "$eval" is calculated with no errors, the "$result" value is further
   tested for validity (to insure that the result is a floating point
   number, and that no overflow has occurred). Lastly, both the result and
   input equation are output to the transcript pad, and optionally to a log
   file.

   Function keys are handled by the "get_equation" callpoint, which reads
   in the equation one key at a time. A series of tests are performed on
   each entered key, and the appropriate action is taken. In particular, if
   a function key is selected with the same name as a callpoint, the
   callpoint is executed. For example, if the "f1" function key is pressed
   (because the user requests help), the callpoint "f1" is executed to
   display the help screen. The "get_equation" callpoint is a rather fancy
   way of getting the input equation. The program could be simplified (by
   sacrificing a small amount of functionality) using the CIEX built-in
   command "read -screen" used in the ADDR.S and CALENDAR.S scripts.

                                  Page: 9

   4.3.2 MODIFYING EVAL.S

   The EVAL.S program can be modified several different ways. Most
   significantly, the program can be condensed into just a few lines and
   still maintain almost all of its functionality as follows:

           loop

           read $equation
           if -cmd; echo -eval $equation
           else; echo $sys:errtxt
           endif

           endloop

   The above is a complete program. It accept a user input equation
   (without a prompt), and display the resulting value or error message.
   The program iterates until a CNTRL-C, or BREAK.

   The EVAL.S program can also be easily modified to display the running
   total of all calculations. This total is calculated, but not used by
   the program. To display the running total instead of the prompt string,
   a programmer can add a statement such as the following:

           set $input:prompt = $total

   The above statement, when inserted at the top of the main control loop
   (immediately following the first "loop" statement of the script) causes
   the prompt to indicate the running total of all values calculated
   subsequent to startup or the "Clear" function key being selected.

   4.4 THE ADDR.S PROGRAM

   ADDR.S is a basic database manager. It is a fairly simple script which
   stores data input by the user in an array of records. This array is read
   from a file on program startup (if a file exists), and stored to the
   file on exit. The program additionally contains features to allow it to
   operate as a phone dialer using a standard modem. Several special
   functions are provided to sort and locate records.

   4.4.1 ADDR.S OPERATION

   The ADDR.S program stores data in the two dimensional array named
   "$static:dbase". This array is a table with 9 elements by "N" records,
   where "N" grows without formal bounds. On startup, the value of
   "$static:dbase" is set from the contents of the file "addr.dat" (if it
   exists). On exit, the value of "$static:dbase" is listed to this same
   file, overwriting it with changed information.

   Once the "$static:dbase" table is initialized, the program draws the
   initial screen by executing the "draw_form" and "update_form"
   callpoints. The program then enters the main service loop. The program
   waits for a key from the user, and decodes the key to perform a specific
   action.

                                  Page: 10

   If the user selects a function key to display the first, next, previous,
   or last data records, the record number is modified, and the
   "update_form" callpoint is executed to display the new record. To add or
   edit a record, the "edit_record" callpoint is executed to accept new
   user information, which is converted to upper case letters using the
   "echo -upper" statement. To delete, sort, or find records, other
   specific callpoints are provided. In particular, the "add", "delete",
   and "sort" functions all use a variation of the "renumber" command,
   which manipulates arrays of records or tables. The "find" function scans
   each element of the table in sequence, starting from the current record,
   until a match is found for the substring or wildcard input by the user.

   When a phone number is dialed, the value of the phone number in the
   database is simply echoed to a COM port using standard output
   redirection. The particular communications port (such as COM1 or COM2)
   is selectable by the user and resides in the $static:comm record, also
   saved to the "addr.dat" file. Special logic is incorporated to handle
   the case of a device error resulting from an illegal communication port
   entry.

   The CIEX "read -scr" command, used at various locations in the script,
   accepts a user input string terminated by an "enter" key or function
   key. If the user inputs a string terminated with an "enter" key, the
   specified variable is assigned the specified string. If a function key
   is entered by a user, the specified variable is assigned the standard
   function key name. This mechanism allows the program to process both
   textual input and function keys.

   4.4.2 MODIFYING ADDR.S

   The ADDR.S program stores all user input fields as text strings. The
   labels for these fields are assigned on program startup to the
   nine-element array "$label", which may be modified by the user. If a
   label is changed, the "sort_record" and "find_record" menus should be
   modified correspondingly, as should the "display_help_screen" callpoint.
   A programmer should find these changes easy to make and fairly obvious.

   In addition to changing the record labels, the user can modify the
   colors of the display, as defined by "$highlight_color", "$box_color",
   "$text_color", and "$background_color." Also, the user can modify the
   value of "$dbfile" to specify an absolute file path. (Unmodified, the
   script checks for the file "addr.dat" first in the directory
   C:\CIEX\DATA, and then in the local directory.)

   4.5 THE CALENDAR.S PROGRAM

   CALENDAR.S is a moderately complicated CIEX script, incorporating
   elements to store and access data (like ADDR.S above), and perform
   fairly complicated math evaluations. The calendar uses a well known
   algorithm for determining the starting week day of a month given a
   particular month and year.

                                  Page: 11

   4.5.1 CALENDAR.S OPERATION

   On startup, the CALENDAR.S program initializes parameters and the
   operating environment. If the file "$appointment_book" is found on the
   disk (by default, a file named "appt.dat"), the file is read to set the
   variable database. Then, a call to "calendar_constants" is made to
   initialize various constant values used by the program.

   To get the current date, a call to "todays_date" is made, which
   initializes a variable array with the current day. To draw the calendar
   outline, a call to "initialize_calendar" is made. To update the calendar
   with values, a call to "update_calendar" is made, which uses the value
   of "todays_date" in conjunction with "calendar_constants" to draw a
   calendar for the current month.

   Once the calendar is displayed on the screen, the program enters its
   main service loop. The program halts and waits for a key from the user.
   When a key is selected, the program continues by decoding the key and
   performing a specific action. These actions include moving the
   highlighted day to the next day, previous day, next week, or previous
   week. Special callpoints are also provided to display the previous or
   next month's calendar.

   If the user input key is the "enter" key, the program runs the
   appointment book screen, which is similar in operation to the "ADDR.S"
   program. If the user input key is the "f5" function key, the utility
   menu is displayed. If the user input key is the "home" key, the current
   date is reset. In these three cases, the calendar is redrawn when the
   key has been processed.

   4.5.2 MODIFYING CALENDAR.S

   A simple change can be implemented by the programmer which greatly
   enhances the utility of the CALENDAR.S program. Specifically, the
   programmer can customize the value of the "$annual" array (assigned
   in the "calendar_constants" callpoint with a "setblock" command) to add
   annual dates, (such as birthdays, annual events, etc.) These annual
   dates are displayed at the top of the menu when a particular day is
   selected. The annual array initially contains a few holidays. It is
   indexed by two integers representing the month and day of an annual
   event. The list of annual days can be augmented to allow one description
   for each day of the year.

   In addition to adding annual event descriptions, the user can easily
   modify the colors of the display defined by "$highlight_color",
   "$box_color", "$text_color", and "$background_color" variables. Also,
   the user can modify the value of "$appointment_book" to specify an
   absolute file path. (Unmodified, the script checks for the file
   "appt.dat" first in the directory C:\CIEX\DATA, and then in the local
   directory.)

                                  Page: 12

   4.6 THE REACTOR.S PROGRAM

   The REACTOR.S program is a fairly simple program. It consists of five
   main segments, each with associated screen-draw and screen-update
   routines. Each segment is overlayed on top of the existing screen. That
   is, each screen is independent of the other screens. Displayed data is
   generated pseudo-randomly from trigonometric functions. The REACTOR.S
   program is typical of scientific displays created by the CIEX
   interpreter.

   4.6.1 REACTOR.S OPERATION

   The REACTOR.S program makes use of the CIEX "trace" facility. This
   facility causes the special "trace" callpoint to be called under certain
   conditions, such as after a program statement is executed, or upon entry
   to a callpoint, or (as in this case) whenever a key is pressed by the
   user. The program therefore continuously updates its screen until a key
   is detected, and then calls the "trace" callpoint. (See section 5.7.2.)

   The "trace" callpoint (defined towards the end of the program) keeps
   track of the current screen number. By entering a function key, the user
   increments or decrements the screen number, calls the special "help"
   screen, or exits the program. If the screen number is changed, the
   particular draw routine is accessed using a "call -goto" command,
   calling the top level screen defined in the "$screen_list" array at the
   top of the script.

   4.6.2 MODIFYING REACTOR.S

   The REACTOR.S program is a good place to experiment with the CIEX
   interpreter's text-graphics capabilities. Various obvious changes can be
   made to draw routines needed to reposition screen elements and change
   colors.

   The REACTOR.S program is not highly parameterized. As an exercise, the
   user can experiment with changing the coordinates of individual screen
   elements (positioned with "move" and "box" commands) and can change the
   position of lines and text. The user may also change the rate of screen
   updates by modifying the arguments of "sleep" commands in each "run"
   callpoint.

   Finally, the user can add new screens to the reactor program using the
   "template" callpoints at the bottom of the program. (These callpoints
   are included for reference only, and are not otherwise used by the
   REACTOR.S program.) To add a new screen, copy and rename the template
   callpoints, and add the new top level screen callpoint name to the
   "$screen_list" array defined at the top of the program.  Adding the new
   top level screen name to the list of screens will make the screen
   accessible to function keys, and no other modifications will usually
   be required to place the new screen under program control.

                                  Page: 13

   5.0 CIEX V2.3.5 COMMAND REFERENCE

   The remainder of this note is a guide to using the Version 2.3.5 CIEX
   interpreter. It contains a complete listing of all commands and their
   options, and provides a brief overview of essential information needed
   to create CIEX scripts. It is intended to be a stand-alone document
   which may be used as a reference. A more detailed description of CIEX,
   including application notes, is presented in the CIEX Version 2.3
   Command Reference, available from New Line Software, Inc.

   5.1 ALPHABETICAL LISTING OF ALL COMMANDS AND OPTIONS

   The following is a list of all command options of the CIEX interpreter
   along with an explanation of each command. Note: each command is
   presented in its most verbose form; frequently a command or option can
   be abbreviated by its first three or four characters.

   5.1.1 COMMAND CONVENTIONS

   CIEX is a case sensitive language. All commands described in this
   section must be used in the lower case letters shown. Each command
   consists of the main command keyword, followed by a maximum of one
   option keyword (designated with a beginning hyphen ("-") character), and
   then followed by special arguments specific to the command and/or
   option. Unless otherwise noted in the command narrative, the following
   special character conventions apply in the command descriptions:

   []      Square brackets are used to denote items in a command which may
           be supplied optionally.

   |       Pipe characters are used to denote items in a list of choices.
           Unless enclosed in brackets, exactly one of the listed choices
           must be supplied when using the command.

   ()      Parenthesis are used to denote descriptions of required
           arguments. Items which are enclosed in parenthesis should be
           substituted (including the parenthesis) by a constant or
           variable argument in the command. The type of argument will
           always be made clear in the context of the command's
           description. (Note that required arguments may precede or
           follow optional choices denoted by pipe characters, but are not
           themselves optional.)

   ...     Ellipses are used to denote a repetition of arguments. The
           argument preceding the ellipse may be repeated. The range or
           usage of arguments will always be made clear in the context of
           the command's description.

                                  Page: 14

   5.1.2 COMMAND SYNTAX

   box [ -clear | -invert ] (column) (line) [ (width) height) ]

           Draw a box on the screen, with upper left corner positioned at
           (line) and (column). If width and height are omitted, center the
           box on the screen. The "-clear" option clears the specified
           region without drawing a box. The "-invert" option inverts the
           colors in the specified region. Otherwise, the box is drawn in
           the foreground and background colors specified by the "screen
           -foreground" and "screen -background" colors.

   box -style single | double | french | roman | clear

           Specify a box style, to be used in future "box" commands.

   break [ -all | -next ]

           Break out of the currently executing loop. The "-all" option
           breaks out of all nested loops. The "-next" option causes the
           script to immediately restart at the top of the current loop.
           The "break" statement can only be used in a program block
           delineated by "loop" and "endloop" keywords.

   call [ -class | -view | -root ] (label) [ (arg) ... ]

           Call the specified label, as marked somewhere in the program by
           a "callpoint:" statement. The "-class", "-view", and "-root"
           options set the variable view before executing the call. Program
           execution branches to the specified label and continues until
           the next "callpoint:" statement, a "return", or the end of file,
           at which point program execution returns to the statement
           immediately following the "call" statement. (See section 5.7.1.)

   call -goto (label)

           Branch the program immediately to the specified label, and
           resume execution as a main program. The program does not return
           to the "call" statement.

   callpoint: (label)

           Mark a program line with a callable label. Note that main
           programs traverse "callpoint:" statements as if they were
           comments, while called subroutines are delimited by "callpoint:"
           statements in the absence of any "return" statements. The colon
           (:) character is a required part of the statement.

   echo (string)

           Display the string, with possible redirection to a file, pipe,
           or variable. The value of "(string)" may be quoted with single
           or double quotes, or with outer "{ }" braces. Outer balanced
           quotes are removed from the string before it is displayed.

                                  Page: 15

   echo -ascii (integer) ...

           Display the ASCII character(s) corresponding to the integer
           argument(s). The terminal carriage return is suppressed.

   echo -screen[N] | -center (string)

           Display a text string at a specific screen location. The text is
           positioned at the column and line specified by the last "move"
           command. The text color is set using the "screen -foreground"
           and "screen -background" commands. The optional "N" qualifier of
           the "-screen" option indicates the number of leading or trailing
           spaces to pad the output. The "-center" option automatically
           centers the text string on the display.

   echo -error (string)

           Display a text string using the CIEX error handler. The
           resulting output includes the file name and line number where
           the statement was executed. This option is useful in terminating
           a script with an error message, or generating an exception to
           be handled by the current script. (See section 5.7.2.)

   echo -eval (expression)

           Display the result of a math evaluation given by "(expression)".
           (See section 5.4.)

   echo -float[N.R] (number)

           Format and display a floating point number. The optional "N.R"
           specification indicates the number of leading or trailing
           spaces, and number of decimal points to display. The terminal
           carriage return is suppressed.

   echo -fmt[N] (string)

           Format and display a string of text, suppressing a carriage
           return. The optional "N" qualifier indicates the number of
           leading or trailing spaces to pad the string (where a positive
           integer number indicates number of leading spaces and a negative
           number indicates the number of leading spaces.) This
           command is commonly used to generate a user prompt, or build
           tables of text values.

   echo -hex[N] | -int[N] | -octal[N] (number)

           Display a number in hexadecimal, integer, or octal format. The
           optional "N" qualifier indicates the number of leading or
           trailing spaces to pad the output. The terminal carriage return
           is suppressed.

                                  Page: 16

   echo -lower | -upper | -title (string)

           Display the string, converting the characters to lower case,
           upper case or capitalizing the first character of each word in
           the string. The terminal carriage return is suppressed.

   echo -on | -off

           Turn on or off the echoing of commands as they execute. This
           command is mainly useful for debugging a script.

   echo -value (string)

           Echo a verbatim string value, including outer quote marks, if
           any.

   echoblock [ -screen[N] | -center ]

           Echo a block of text, delimited by an "endblock" statement by
           itself on a line. The "echoblock" command, with no option
           specified, allows redirection to a file, pipe, or variable. The
           "-screen" option displays a block of text on the screen in the
           colors established with the "screen -foreground" and "screen
           -background" commands, where the first line of text is at the
           line and column established by the last "move" command.  The
           optional "N" qualifier of the "-screen" option indicates the
           number of leading or trailing spaces to pad each line of text.
           The "-center" also updates the screen, centering each line of
           text on the display.

   echoblock -wrap [ (margin) ]

           Echo a block of text (delimited by an "endblock" statement by
           itself on a line). The text is word-wrapped at the column
           specified by the integer value of "(margin)", or at column 72
           if "(margin)" is omitted.

   else [ if (condition) ]

           Delineate the next case in an "if" statement. The "else" command
           must be used at the beginning of a program line, i.e. cannot be
           preceded by a semicolon command separator. The "else" statement
           can include an optional "if" qualifier to continue a case
           select. (See section 5.5.)

   endblock

           Delimit the end of a program block. The "endblock" statement is
           used in conjunction with the "startblock", "setblock" and
           "echoblock" commands. The "endblock" command must be used on a
           line by itself i.e. cannot be preceded or followed by a
           semicolon command separator.

                                  Page: 17

   endif

           Delimit the end of an "if" statement. The "endif" statement must
           be used on a line by itself, i.e. cannot be preceded or followed
           by a semicolon command separator.

   endloop

           Delimit the end of a "loop" statement. The "endloop" statement
           must used on a line by itself, i.e. cannot be preceded or
           followed by a semicolon command separator.

   exec (command)

           Execute a DOS command. This is the default action of the
           interpreter if a command is issued which does not matched one of
           the CIEX commands listed in this section, hence is usually
           superfluous. (DOS commands may be used by themselves without the
           "exec" command.)

   exec -error (command)

           Execute a DOS command with extra exception handling. This allows
           exceptions raised by DOS commands to be handled by a CIEX
           script. (See section 5.7.2.)

   exec -force (command)

           Execute a DOS command with no error checking.

   exit

           Exit the interpreter and return to DOS. This is the only command
           with a synonym: "quit".

   for (var) = (start) to (end) [ by (step) ]

           Iterate a value within a loop. This statement can only be used
           in a program block delineated by "loop" / "endloop" statements.

   for -cmd (var) = (command)

           Execute the specified DOS or CIEX command, iterating for each
           line of output generated by the command. This statement can only
           be used in a program block delineated by "loop" / "endloop"
           statements. The specified command can be any internal or
           external (DOS) command.

                                  Page: 18

   for -file (var) = (file) [ (startline) to (endline) ]

           Iterate for each line in a disk file. The optional line
           specification allows the iterating variable to be limited to a
           particular range of line numbers. This statement can only be
           used in a program block delineated by "loop" / "endloop"
           statements.

   for -list (var) = (string) [ by word | char | punct | (sep) ]

           Iterate for each token within a string. The optional "by"
           qualifier indicates whether the variable iterates for each word
           (the default), each character, each word separated by a
           punctuation character, or each string segment split by an
           arbitrary character separator. The statement can only be used in
           a program block delineated by "loop" / "endloop" statements.

   for [ -value | -name ] (var) = (view)

           Iterate for each variable in the array specified by "(view)".
           The "-value" option is the default, hence can always be
           omitted. The value of "(var)" assumes each value of "(view)" in
           turn. The "-name" option assigns "(var)" the name of each
           variable in "(view)" in turn. The statement can only be used in
           a program block delineated by "loop" / "endloop" statements.

   if [ -test | -not ] (condition)

           Begin a conditional test. The conditional program block is
           executed if the specified condition is true. The "-test" option
           is the default and hence always superfluous. The "-not" option
           checks the negation of the specified condition. Each "if"
           statement must be delimited by an "endif" statement later in the
           program. (See section 5.5.)

   if -cmd

           Execute the next statement in the program (immediately following
           the "if -cmd" statement). If the next command causes an
           exception, suppress the error message and branch to the
           corresponding "else" or "endif" statement. Otherwise, continue
           normal execution. This is an easy way to handle program
           exceptions. (See section 5.7.2.)

   if -eval (expression)

           Execute a mathematical expression and branch if the result of
           the expression is zero. (See section 5.4.)

                                  Page: 19

   if -key

           Determine if a key has been entered. If no key has been entered
           since the last time the statement was executed, skip to the
           next "else" or "endif" statement. Otherwise, execute the
           conditional program block. This command may be used to branch a
           running program on a user keystroke. Note that the statement
           returns true until the key is actually read (such as with a
           "read -key" command.)

   line [ -horizontal | -vertical ] [ (length) ]

           Draw a line on the screen originating at the position specified
           by the last "move" statement, and in the colors specified by
           the last "screen -foreground" and "screen -background"
           statements. The "-horizontal" option is the default (hence is
           always superfluous). The "-vertical" option draws a vertical
           line. The optional "(length)" qualifier specifies the length of
           the line in characters. If the "(length)" qualifier is omitted,
           the length is set so as to center the line horizontally or
           vertically on the display. Connections to other lines on the
           display are automatically made.

   line -clear | -invert [ (length) ]

           Clear or invert a horizontal line on the screen, originating at
           the position specified by the last "move" statement. No line is
           actually drawn. If "(length)" is omitted, the cleared or
           inverted region is horizontally centered on the screen.

   list [ (view) ]

           List variable names and values in the current working view. If
           "(view)" is specified, list the elements of "(view)" rather than
           the current working view. (See section 5.3.1.)

   list -all [ (view) ]

           List variable names and values of the current and all
           subordinate views. If "(view)" is specified, confine the listing
           to the elements and subordinate views of "(view)". (See section
           5.3.1.)

   list -calls

           List currently sourced callpoints. Callpoints are sourced using
           the "source -calls" command, which speeds up access to calls,
           and makes callpoints in external files accessible to a script or
           the keyboard. (See section 5.7.)

                                  Page: 20

   list -history | -locator | -screen | -status

           List specific status of the interpreter, depending upon the
           particular option. The "-history" option lists the last 25
           unique commands which were issued from the keyboard; the
           "-locator" option lists the status and position of the mouse
           locator (if installed); the "-screen" option lists information
           about the text graphics display; the "-status" option lists
           information regarding program resources and state.

   list -system

           List the names and values of the special "$sys" global view.
           (See section 5.3.2.)

   list -value (view) [ (startpos) to (endpos) ]

           List only the values of the specified variable view, and not
           the variable names. The optional position specification
           confines the listing to the value of those variables in the
           indicated range. (See section 5.3.2.)

   list -view

           List the name of the current view. Note: a view may be set with
           the "set -view" or "call -view" commands, or variants thereof.
           (See section 5.3.2.)

   loop

           Loop on a program block. Each "loop" statement must be
           delineated by a corresponding "endloop" statement later in the
           program. The "loop" command is the only command which does not
           require a command delimiter (newline or semicolon) to execute,
           hence can be immediately followed by another statement (such as
           "for" or "while"). Note that "for", "while", and "break"
           statements terminate the current loop (as oppose to defining or
           initiating the loop), and can appear anywhere within the loop
           structure.

   move [ -absolute | -relative ] (column) (line)

           Move the (invisible) screen marker to the specified column and
           line. The "move" command defines the location where text and
           lines originate when added to the display using the "echo
           -screen", "echoblock -screen", "read -screen", and "line"
           commands. The default move option is "-absolute", hence is
           always superfluous. The "-relative" option moves the screen
           marker relative to its current position.

   move -up | -down | -left | -right [ (count) ]

           Move the screen marker up, down, left, or right the specified
           number of counts. If "(count)" is omitted, it defaults to one.

                                  Page: 21

   move -home

           Move the screen marker to the lower left corner of the display.
           The bottom line of the display is reserved for user status
           messages. The screen marker can only be moved to the bottom line
           of the display using the "move -home" command.

   move -locator (xcoord) (ycoord)

           Move the mouse locator position (if installed). Note that the
           mouse cursor only appears during "read -locator" commands or
           during other read commands if the "select -locator on" command
           has been issued. The current locator position can be listed
           using the "list -locator" statement.

   quit

           Exit the interpreter and return to DOS. This is the only command
           with a synonym: "exit".

   read (var)

           Read a string from standard input, and assign it to "(var)".

   read -key (var)

           Read a single key from the keyboard, assigning to "(var)" a
           predefined value corresponding to the name of the key which was
           entered. (Key names can easily be determined by experimenting
           using the "read -key" and "echo" commands at the keyboard.) All
           key names are received in lower case letters, such as "f1", "f2",
           "esc", "enter", etc.

   read -screen[N] (var)

           Read a string from the keyboard and update screen with the
           entered text, in colors assigned with the "screen -foreground"
           and "screen -background" commands. If a function key is entered,
           return the name of the function key instead of any entered text.
           The optional "N" qualifier describes the maximum width of the
           text field, and defaults to the width of the screen. Note that
           characters are echoed to the screen at the position of the last
           "move" command, and the existing text at this location (if any)
           is cleared to a width of "N" when the first keystroke is
           entered. The particular properties of this command make it easy
           to accept both textual input and function key entries.

   read -locator (var) [ by char | word | line | punct | graph | (sep) ]

           Read a value using the mouse locator (if installed). The value
           of "(var)" is assigned the text under the cursor, delimited by
           the optional "by" qualifier. If a function key is entered rather
           than a mouse button, the function key is returned rather than

                                  Page: 22

           the text under the cursor. The "graph" qualifier is especially
           useful, and will return any text enclosed within graphic
           characters, such as a box. While the "read -locator" command
           executes, the mouse locator cursor is automatically turned on.

   renumber (view)

           Renumber the indices of a variable view.

   renumber -insert (member)

           Insert a member value into a variable view and renumber. The
           inserted value is always null, and may later be assigned a
           specific value in the program. This command is useful for
           opening up a position in an array.

   renumber -sort | -nsort | -rsort | -nrsort (view) [ by (member) ]

           Sort and renumber the elements of a variable view. The sort can
           be an alphabetical sort, numerical sort, reverse alphabetical
           sort or reverse numerical sort. If the optional "by" qualifier
           is included, the specified view should contain subviews, each
           subview containing the name specified by "(member)". The "by"
           clause is therefore useful for sorting an array of records by a
           particular record element.

   renumber -unique (view)

           Delete duplicate adjacent values in a view and renumber.

   return [ -all | -entry ]

           Return from a source file or callpoint. The "-all" option
           returns from all nested callpoints and source files. The
           "-entry" option returns from all nested callpoints in the
           current source file, but allows a calling source file to
           continue execution.

   screen -ansi

           List the text values on the screen. By default, the entire
           screen is listed to the console, and includes ANSI escape
           sequences needed to recreate colors. A range of the screen may
           be selected for listing using the "select -screen" command.
           Typically, the output of the "screen -ansi" command should be
           redirected to a file or variable, since the act of displaying
           the screen listing will garble the listing. This command is
           mainly useful for ascertaining the current text and colors
           residing on the screen. (To list only the text on the screen,
           without color information, use the "screen -list" command.)

                                  Page: 23

   screen -background | -foreground (color)

           Change the screen background or foreground colors used by
           "line", "box", and other text graphic commands. Valid colors
           include "red", "green", "blue", "cyan", "magenta", "white",
           "black" and "bold". Colors may also be specified by numeric
           value in the range of (0 - 15). The precise colors displayed are
           system dependent, and do not apply to monochrome displays.

   screen -buffer on | off

           Turn screen buffering on or off. When screen buffering is "on",
           updates to the screen occur only when a "screen -flush" command
           occurs. When screen buffering is "off", updates to the display
           occur immediately. Turning screen buffering "on" will
           automatically copy the current display into the screen buffer.

   screen -clear

           Clear the screen. The screen is updated to be the current
           background color, as set by the last "screen -background"
           command which was issued.

   screen -default

           Set the screen to default values. This command is useful for
           initializing the screen to a known state, hence is often found
           at the start of scripts incorporating text graphic commands.

   screen -flush [ (filename) ]

           Flush the screen buffer to the screen. (The screen buffer is
           enabled using the "screen -buffer on" statement.) If an optional
           filename is specified, flush the contents of the file to the
           screen. The file should have been previously created using the
           "screen -save" command.

   screen -list

           List the text values on the screen. By default, the entire
           screen is listed to the console. A range of the screen may be
           selected for listing using the "select -screen" command.
           Typically, the output of the "screen -list" command should be
           redirected to a file or variable, since the act of displaying
           the screen listing will garble the listing. This command is
           mainly useful for ascertaining the current text residing on
           the screen. (To list both text and color information, use the
           "screen -ansi" command.)

   screen -mode mono | color

           Change the screen display mode to either monochrome or color.

                                  Page: 24

   screen -save [ (filename)  ]

           Save the current screen to the buffer. If an optional filename
           is specified, save the screen to a file for later restoration
           using the "screen -flush (filename)" statement. This provides a
           mechanism for saving static screen displays to the disk.

   scroll [ -up | -down ] [ (count) ]

           Scroll the screen up or down the specified number of lines. If
           no options are specified, the default is to scroll the screen
           upward. If no count is specified, scroll the screen by one line.
           A particular region of the screen can be scrolled (instead of
           the entire screen) using the "select -screen" command.

   scroll -on | -off

           Turn on or off command scrolling of the screen. The default is
           "on". When scrolling is turned off, commands which do not
           generate output will not scroll the screen, allowing easier
           experimentation of text graphic commands at the keyboard. This
           command is useful only when CIEX is executed interactively, and
           has no affect on the execution of a script.

   select -cursor on | off | solid | normal

           Turn the cursor locator on or off, or change the cursor to a
           solid block or normal underline. Note that a cursor is always
           displayed when at the command line.

   select -downcase on | off

           Enable or disable case sensitivity of the interpreter. Note that
           selecting downcase "on" may have unanticipated (but predictable)
           results with regard to executing system commands. The downcasing
           of characters applies to all commands and textual comparisons.

   select -fixvalue (precision)

           Set the precision of the math evaluator. The value of
           "(precision)" must be a positive integer value in the range of
           0 to 9. Default precision is 3 decimal places.

   select -history on | off

           Enable / disable command line history. The command line history
           mechanism emulates most of the functions of the DOSKEY program
           found in version 5.0 MS-DOS.

   select -prompt (string)

           Set the value of the interactive interpreter prompt.

                                  Page: 25

   select -screen (column) (line) [ (width) height) ]

           Select a region of the screen. This command works exclusively
           with the "scroll", "screen -list", and "screen -ansi" commands.
           Note that the coordinate syntax is identical to that of the
           "box" command.

   select -locator on | off

           Enable / disable mouse locator during read commands. Normally,
           the "read -key" and "read -screen" commands do not display the
           mouse locator cursor. This command makes the mouse locator
           cursor visible during these read commands.

   set (var) = (value)

           Assign the variable specified by "(var)" a value specified by
           "(value)".

   set (var) + | - | * | / | % (number)

           Add, subtract, multiply, divide, or mod the values of "(number)"
           and the current value of "(var)". This is one way to perform a
           math operation on a variable. If "(var)" has no current value,
           it is taken as zero prior to performing the math operation.
           Otherwise, the current value of "(var)" must be an integer or
           an error results.

   set (var) & (string)

           Concatenate the current value of "(var)" with the value of
           "(string)".

   set (var) ? (value)

           Assign the variable specified by "(var)" a value specified by
           "(value)" only if "(var)" has not been previously assigned a
           value. This operator is useful for initializing data.

   set (var) < (view)

           Copy one variable into another variable. The right side of the
           operator may be a value, variable view or multidimensioned
           structure. (See section 5.3.1.)

   set -clear

           Clear interpreter memory, except for the "$arg" view. This
           command is useful for initializing the memory to a known state,
           hence is often found at the start of scripts. The command sets
           the current working view to the root view, clears variables,
           and clears sourced callpoints.


                                  Page: 26

   set -cmd (var) = (command)

           Execute the specified DOS or CIEX command, and assign the output
           of the command (if any) to the variable "(var)", creating an
           array where each line of the command's output is assigned an
           integer ascending subscript.

   set -eval (var) = (expression)

           Assign "(var)" the result of a math evaluation given by the
           string value of "(expression)". (See section 5.4.)

   set -file (var) = (filename) [ (startline) to (endline) ]

           Assign the contents of the text file given by "(filename)" to
           the variable specified by "(var)", creating an array where each
           line of the file is assigned an integer ascending subscript. The
           optional line specification allows the assignment to be limited
           to a particular range of line numbers in the file.

   set -head | -tail | -inline (var) = (command)

           Execute the specified DOS or CIEX command, and assign the output
           of the command (if any) to the variable (var). The "-head"
           option assigns the first line in the command's output; the
           "-tail" option assigns the last line in the command's output;
           the "-inline" option is synonymous with the "-head" option. Note
           that the resulting variable will not be subscripted.

   set -list (var) = (string) [ by word | char | punct | (sep) ]

           Split a string into tokens, and create an array where each token
           is a subscript value of "(var)". The optional "by" qualifier
           indicates whether the string is divided into a list of words
           (the default), a list of characters, a list of words separated
           by punctuation characters, or a list of tokens separated by an
           arbitrary character "(sep)".

   set -replace (var) = [ all | first | last ] (patt) [ by (string) ]

           Replace a pattern in a variable value with a string. If the "by"
           clause is omitted, the pattern specified by "(patt)" is removed
           from the current value of "(var)", otherwise, the first, last,
           or all instances of "(patt)" found in the value of "(var)" are
           replaced by "(string)". The default action is to replace only
           the first instance of "(patt)". This powerful command can be
           used to perform global replacements of text, possibly using
           wildcards. (See section 5.6.)

                                  Page: 27

   set -root | -view (var)

           Change the working view of the program to the specified
           variable. The "-root" option sets the working view to the
           specified variable in the root directory. The "-view" option
           sets the working view to the specified variable in the current
           view, creating the view as needed. (See section 5.3.1.)

   set -value (var) = (string)

           Assign a verbatim string value, including outer quote marks, if
           any.

   setblock [ (view) ]

           Set a block of variables (delimited by an "endblock" statement
           by itself on a line). Within the block, variable and value pairs
           are placed (without the assignment operator) one per line, where
           the first token is the variable name (with or without a leading
           "$" character), and the remaining tokens are the variable value
           to be assigned. If the optional "(view)" qualifier is specified,
           variables are created in the specified view, otherwise variables
           are created in the current view.

   setblock -cmd [ (view) ] = (command)

           Execute the specified DOS or CIEX command, and take the output
           of the command (if any) as a list of variable and value pairs.
           If the optional "(view)" qualifier is specified, variables are
           created in the specified view, otherwise variables are created
           in the current view. This command allows a record structure or
           an array to be returned from a DOS or CIEX command.

   setblock -file [ (view) ] = (filename)

           Set a block of variables stored in a file, where the file
           contains a list of variable and value pairs. If the optional
           "(view)" qualifier is specified, variables are created in the
           specified view, otherwise variables are created in the current
           view. One application of this command is to restore a database
           which was created by issuing the "list -all" command with
           redirection to a file.

   sleep (milliseconds)

           Pause for the specified number of milliseconds.

   source (scriptname) [ (arg) ... ]

           Execute an interpreter program file. Command line arguments to
           the script can be specified following the filename, and can be
           accessed by the script in the "$arg:1, $arg:2 ..." variables.

                                  Page: 28

   source -bind (scriptname)

           Don't execute "(scriptname)". Instead, create an "EXE" file from
           the specified interpreter script, with the same basename as
           "(scriptname)". Any existing "EXE" is overwritten.

   source -calls [ (scriptname) ]

           Don't execute "(scriptname)". Instead, scan the specified file
           for callpoints, and load the callpoint locations into memory.
           The resulting callpoints are then accessible from the keyboard
           or other files (and may be listed using the "list -calls"
           command).  If no file is specified, scan the currently opened
           source file for callpoints. This command is useful both for
           making callpoints in other files accessible, and speeding up
           access to the local callpoints in the current source file.

   startblock

           Delineate the start of a program block. The "startblock"
           statement must be followed by an "endblock" statement later in
           the program. The output of the "startblock" command may be
           redirected to a file, pipe, or variable. Within the "startblock"
           construct, the working view of a script cannot be permanently
           changed, and "break -all" commands cannot traverse the block
           structure. This command is often used as the object of a
           "set -cmd", "for -cmd", "if -cmd", "while -cmd" or
           "setblock -cmd" statement.

   test [ -not ] (condition)

           Display the results of a conditional test. This command is
           mainly useful for experimenting with conditional test
           expressions at the keyboard. The "-not" option displays the
           negation of the conditional test. (See section 5.5.)

   trace -on | -off | -key | -entry

           Trace execution of the program. The "-on" option causes the
           special "trace" callpoint, which must be defined somewhere in
           the currently executing source file, to be accessed after each
           regular program statement is executed; the "-key" option causes
           the "trace" callpoint to be accessed after each key stroke; the
           "-entry" option causes the "trace" callpoint to be accessed
           prior to entry into any callpoint or source file; the "-off"
           option disables all tracing. Only one trace option can be
           applied at a time. (See section 5.7.2.)

   unset (var)

           Delete a variable or view from the program. No error is reported
           if the specified variable is already unset.

                                  Page: 29

   unset -all | -calls | -system

           Delete all variables, all callpoints, or all variables defined
           in the special "$system" view.

   unset -view

           Set the working view of the program to the root view.

   while [ -test | -not ] (condition)

           Iterate within a loop while a condition is true. This statement
           can only be used in a program block delineated by "loop" /
           "endloop" statements. The "-test" option is the default, hence
           is usually superfluous. The "-not" option allows iteration to
           continue while a condition is not true. (See section 5.5.)

   while -cmd

           Execute the next statement in the program (immediately following
           the "while -cmd" statement). If the next command causes an
           exception, suppress the error message and branch to the
           corresponding "endloop" statement. Otherwise, continue normal
           execution.

   while -eval (expression)

           Execute a mathematical expression and branch to the
           corresponding "endloop" statement if the result of the
           expression is zero. (See section 5.4.)

   5.2 SPECIAL PROGRAM CHARACTERS

   The CIEX interpreter defines certain characters which have special
   significance when found in a script. To escape the meaning of a special
   character, precede the character with a tilde (~) character, or enclose
   the character in single quote marks. The tilde character itself can be
   escaped using two adjacent tilde characters.

   ~       (Tilde). The escape character. When encountered as the last
           token on the line, continue the next line as part of the
           current command. When encountered elsewhere, ignore any special
           meaning associated with the character which immediately follows.

   #       (Number sign). The comment character. Ignore any characters
           which follow to the end of the line. This allows comments to
           be inserted into the program body.

   ;       (Semicolon). The command separator character. End the current
           command. This allows more than one command to be entered on a
           single line. Note that some commands (in particular the "endif",
           "endloop", and "endblock" commands) must be specifically
           delimited by a terminating "newline", and cannot be followed by
           other characters (except spaces) on the same line.

                                  Page: 30

   $       (Dollar sign). The variable identifier character. When used at
           the start of a token, interpret the token as a variable name.

   ^       (Circumflex). Variable attribute identifier. When used as the
           last character of a variable name, return the adjoining
           variable attribute rather than the variable's value. (See
           section 5.3.3.)

   '       (Single quote). The quoting character. Do not interpret the
           text enclosed in single quotes. All characters lose their
           special meaning until the next single quote or newline.

   "       (Double quote.)  Flexible quoting character. Similar to a single
           quote, except that variable substitution occurs in the quoted
           region. Also, special characters within the double quotes do not
           have their special meaning escaped.

   {       (Left brace.)  Alternate quoting character. Identical to an
           opening double quote. Mainly useful as a way of quoting a text
           string which contains double quote marks.

   }       (Right brace.) If preceded by a left brace, identical to a
           closing double quote mark. Mainly useful as a way of quoting a
           text string which contains double quote marks

   [       (Left bracket). Begin inline evaluation. Assume the text string
           that follows (delimited by a right bracket) is a mathematical
           expression to be passed to the expression evaluator. (See
           section 5.4.)

   ]       (Right bracket). End inline evaluation. If preceded by a left
           bracket, delimit the inline evaluation of a mathematical
           expression to be passed to the expression evaluator.

   >       (Greater than). Output redirection. Instead of displaying the
           results of the command to the screen, send the output to a named
           file. Two adjacent "greater than" characters indicate the
           specified file is to be appended if it already exists.

   |       (Pipe). Pipe redirection. Instead of displaying the results of
           the command to the screen, send the output to a named external
           command.

   5.3 VARIABLES

   All CIEX variables are prefixed by a "$" character regardless of where
   they are found in the program. When a variable is found, its value is
   substituted for the variable name before the command is executed.
   Variables names are case sensitive, and may contain characters, numbers,
   underscore characters, periods, and colon characters.

                                  Page: 31

   The colon character is special in variable names: the value to the right
   of the colon is regarded as a subscript of the variable which may be a
   constant or another variable. Any part of a variable name can be
   substituted by a variable using parenthesis. For example the variable
   "$($varname)" refers to a variable whose name is given by "$varname".

   5.3.1 VARIABLE VIEWS

   In the nomenclature of CIEX, a "view" is simply a subscripted variable
   array or record. Views may be thought of as any variable whose name
   contains colon characters. Views may also be thought of as directories
   of variables which can be traversed by the "set -view" command similar
   to the way in which disk directories of files can be traversed using the
   "cd" command. One important consideration when using views is that once
   a new view is set, it cannot be popped one level; the working view can
   only set back to the root view using the "unset -view" command. This
   behavior is important to insure data privacy needed for object-oriented
   and modular design. Programmers should generally avoid the "unset -view"
   command to insure an object-oriented design.

   5.3.2 SPECIAL VIEWS

   Two special views exist: the "$sys" view is accessible from any view and
   may be used to contain global common data; the "$arg" view is private to
   a callpoint or source file and can be used to contain data which is
   unique to a source file or callpoint.

   The "$sys" view is used by the program to contain error and diagnostic
   information. Programmers can additionally use the "$sys" view to set
   global data needed by other parts of the program regardless of the
   current working view. Note that the "$sys" view may not be the object of
   a "set -view" (and certain other) commands.

   The "$arg" view contains arguments passed into a program segment with
   "source" or "call" statements. The existing "$arg" view (if any) is
   always saved on entry to a source file or callpoint. On exit, the
   original "$arg" view of caller is restored before the program continues.
   Therefore, setting the view to the "$arg" view on entry to a source file
   or callpoint insures that the called routine cannot affect data used by
   the caller.

   5.3.3 VARIABLE ATTRIBUTES

   Variable attributes are values associated with a variable (other than
   its assigned value). Variable attributes include: position of a variable
   in an array, size of a variable's value, number of subscripts of a
   variable, size of a variable's name (etc.)

   To access a variable's attribute, the variable name is appended by the
   "^" character followed by the specified attribute identifier (in the
   form "$var^attrib"). This causes the interpreter to substitute the
   variable's specified attribute instead of the variable's value.

                                  Page: 32

   5.3.3.1 ATTRIBUTE IDENTIFIERS

   range   If the specified variable is a view, substitute the number of
           elements in the view, otherwise substitute a value of "(null)".

   value   If the variable is set, substitute the value of the variable in
           the view, otherwise substitute a value of "(null)". Note that
           this is the similar to the default action if no variable
           attribute is specified, however guarantees the variable name can
           be used without raising an exception because the value is not
           set.

   first   If the variable is a view, substitute the name of the first
           element in the view, otherwise substitute a value of "(null)".

   last    If the variable is a view, substitute the name of the last
           element in the view, otherwise substitute a value of "(null)".

   next    If the variable is set, substitute the name of the next variable
           in the parent view, otherwise substitute a value of "(null)".
           If no next variable is set, substitute a value of "(null)".

   prev    If the variable is set, substitute the name of the previous
           variable in the parent view, otherwise substitute a value of
           "(null)". If no previous variable is set, substitute a value
           of "(null)".

   lexnext Substitute the name of the variable which is the next variable
           in the variable list, i.e. the name of the next variable which
           is lexically greater than the current name. This attribute is
           useful for traversing the program variable hierarchy, as
           listed with a "list -all" command, since all variables are
           stored in lexical order within the program data space.

   head    If the variable is a view, substitute the value of the first
           element in the view, otherwise substitute a value of "(null)".

   tail    If the variable is a view, substitute the value of the last
           element in the view, otherwise substitute a value of "(null)".

   name    If the variable is set, substitute the name of the variable in
           the view, otherwise substitute a value of "(null)".

   size    If the variable is set, substitute the number of characters in
           the variable value, otherwise substitute a value of "(null)".

   namelen If the variable is set, substitute the number of characters in
           the variable name, otherwise substitute a value of "(null)".

   pos     If the variable is set, substitute the position of the variable
           in its parent view, otherwise substitute a value of "(null)".
           The attribute is always a positive integer number, or the
           value "(null)".

                                  Page: 33

   (num)   If a variable with the specified position exists in the parent
           view, substitute the value of the variable. Otherwise,
           substitute a value of "(null)". This attribute is useful for
           accessing variable values by position in the variable list
           rather than by name. Note that "(num)" should be a positive
           integer number.

   5.4 MATH EXPRESSION EVALUATOR

   The math expression evaluator performs math operations on a string
   representation of a math statement. Math operators are documented in the
   help file of the "EVAL.S" program, and consist of standard math
   operators, scientific functions, and logical functions which are
   evaluated in natural math precedence and with full support for
   parenthetical nesting of sub-expressions.

   The math evaluator can be accessed several different ways: The
   "echo -eval", "set -eval", "if -eval", and "while -eval" statements
   each accept a string representation of a math statement as an argument,
   and pass this argument to the math evaluator.

   A more common way of accessing the math evaluator is to enclose a math
   statement in square brackets "[ ]". This causes the input parser to
   evaluate the expression and substitute the resulting value. This is the
   most common and ubiquitous method of accessing the math evaluator from
   within a program since it provides general access to the evaluator at
   any arbitrary program location.

   Note that math statements can also be executed using the set operations
   described in the "set" command narrative. This method of performing math
   calculations is convenient, but limited to a small subset of simple
   operations.

   5.5 CONDITIONAL TESTING

   Two types of conditional evaluators are supported by the interpreter.
   The math expression evaluator allows complex math statements to be
   evaluated, and may be used with the "if -eval" and "while -eval"
   statements. The default conditional evaluator is used with the "if" (or
   "if -test") and "while" (or "while -test") statements, and is described
   herein.

   The default conditional evaluator consists of a list of comparison
   operators with left and right values, possibly conjoined with "and" and
   "or" operators. The condition is evaluated from left to right, first
   evaluating the comparison operators and then the conjunctive operators.
   Quantities (unlike the math expression evaluator) can not contain
   parenthetical nesting.

   5.5.1 COMPARISON OPERATORS

   eq      Equivalence operator. Return true if left and right arguments
           are equal. (This operator is also available as part of the math
           evaluator.)

                                  Page: 34

   lt      Less than operator. Return true if the left argument is
           numerically less than the right argument. (This operator is also
           available as part of the math evaluator.)

   gt      Greater than operator. Return true if the left argument is
           numerically greater than the right argument. (This operator is
           also available as part of the math evaluator.)

   le      Less than or equal operator. Return true if the left argument is
           numerically less than or equal to the right argument. (This
           operator is also available as part of the math evaluator.)

   ge      Greater than or equal to operator. Return true if the left
           argument is numerically greater than or equal to the right
           argument. (This operator is also available as part of the math
           evaluator.)

   ne      Not equal operator. Return true if left and right arguments are
           not equal. (This operator is also available as part of the math
           evaluator.)

   in      Return true if the left argument (patt) matches any portion of
           the right (string). Wildcards are allowed. See WILDCARDS below.

   is      Return true if the left argument contains the property
           specified. See PROPERTY TESTING below.

   is not  Return true if the left argument does not contain the property
           specified. See PROPERTY TESTING below.

   not in  Return true if the left argument (patt) does not match any
           portion of the right (string). Wildcards are allowed. See
           WILDCARDS below.

   llt     Lexical less than operator. Return true if the left string
           argument is lexically (i.e. alphabetically) less than the right
           string argument.

   lgt     Lexical greater than operator. Return true if the left string
           argument is lexically (i.e. alphabetically) greater than the
           right string argument.

   lle     Lexical less than or equal operator. Return true if the left
           string argument is lexically (i.e. alphabetically) less than or
           equal to the right string argument.

   lge     Lexical greater than or equal operator. Return true if the left
           string argument is lexically (i.e. alphabetically) greater than
           or equal to the right string argument.

                                  Page: 35

   5.5.2 CONJUNCTIVE OPERATORS

   and     Return true if the left comparison and the right comparison are
           true. This operator is valid only as a joiner of two conditional
           tests. (This operator is also available as part of the math
           evaluator.)

   or      Return true if the left comparison or the right comparison is
           true. This operator is valid only as a joiner of two conditional
           tests (This operator is also available as part of the math
           evaluator.)

   then    Always optional. Ignore remaining terms in the conditional
           expression (if any). If used, this should be the last operator
           of the conditional expression.

   5.5.3 PROPERTY CONDITIONAL TESTS

   Properties, used with the "is" (and "is not") conditional test
   operators, describe a particular property or attribute of the left
   argument to test for. In the "is" form of the test, the test returns
   true if the argument possesses the specified property, and returns false
   if it does not.

   Property tests are useful for ascertaining system information (such as
   whether a file or directory exists), and for determining the particular
   state of an argument (such as whether a value is numeric or lexical).
   Property tests are also used for tests of special conditions, such as
   whether a callpoint name is valid, or variable is set.

   If the arguments to a property test are numeric, no special handling is
   required. If arguments are text, they should be enclosed in single or
   double quote marks.

   5.5.3.1 PROPERTY DEFINITIONS

   call    Verify the specified argument is (or is not) a sourced callpoint
           label, or the name of a callpoint in the currently executing
           script.

   dir     Verify the specified argument is (or is not) a disk directory
           pathname.

   exec    Verify the specified argument is (or is not) an external DOS
           command, either built-in or in the user's PATH.

   file    Verify the specified argument is (or is not) the path to an
           existing file.

   int     Verify the specified argument is (or is not) an integer value.
           To qualify as an integer, the argument must contain less than
           twelve numeric characters prefixed with an optional sign.

                                  Page: 36

   key     Verify the specified argument is (or is not) the name of a
           function key, as returned by the "read -key" or "read -scr"
           commands. This is useful for determining whether the specified
           entry was a function key or text string input.

   name    Verify the specified argument is (or is not) a valid variable
           name, which can be used as the target of a set command. Note:
           the argument must either be enclosed in SINGLE quotes, or must
           not include the leading "$" dollar sign (to prevent variable
           substitution by in input parser).

   number  Verify the specified argument is (or is not) an integer or
           floating point number.

   float   Identical to the "number" property. (See above)

   null    Verify the specified argument is (or is not) the name of a
           variable which contains a null value, i.e. is either zero, the
           word "(null)", or an empty text string. This property is often
           used to test variable attributes.

   oper    Verify that the specified argument is an evaluation operator
           (such as "+", "*", "%" etc.)

   set     Verify the specified argument is (or is not) the name of a
           variable which is currently set. Note: the argument must either
           be enclosed in SINGLE quotes, or must not include the leading
           "$" dollar sign (to prevent variable substitution). A better way
           to test if a variable is set is to use the "value" variable
           attribute and test for a null value using the "null" property
           test described above.

   view    Verify the specified argument is (or is not) the name of a
           variable which is currently set, and is a variable view  Note:
           the argument must either be enclosed in SINGLE quotes, or must
           not include the leading "$" dollar sign (to prevent variable
           substitution). A better way to test if a variable is a view is
           to use the "range" variable attribute and test for a null value
           using the "null" property test described above.

   5.6 WILDCARDS

   Wildcards, used with the "in" and "not in" operators match strings or
   single characters. Any character which is not a wildcard will match
   itself. Generally, patterns should be enclosed in single quotes to avoid
   conflicts with the input parser (especially with regard to the "$" and
   "~" wildcards.)

   Note that wildcards are also used with the "set -replace" command to
   select and replace strings. (Refer to the explanation of the "set"
   command for more information.)

                                  Page: 37

   5.6.1 WILDCARD DEFINITIONS

   ?       Matches any single character except a newline.

   *       Matches zero or more characters except a newline.

   +       Matches zero or more occurrences of the preceding character in
           the pattern.

   ^       When at the beginning of the pattern, matches the beginning of
           line, otherwise matches a '^' character.

   $       When at the end of the pattern, matches the end of line,
           otherwise matches a '$' character.

   ~       Escapes the meaning of the special character.

   5.7 CALLPOINTS

   CIEX implements subroutines using the "callpoint:" statement and "call"
   command. CIEX allows temporary transfer of a program to any line which
   is labeled with the "callpoint:" statement. CIEX also allows permanent
   transfer to callpoint labels using the "call -goto" command. Called
   subroutines return to the calling program with a "return" statement, or
   when the next "callpoint:" directive is found. Note that the main
   program traverses "callpoint:" statements as if they were comments,
   while subroutines are delimited by the "callpoint:" statement. (This
   unique behavior allows the callpoint statement to both define
   subroutines and labels which a program can "goto".)

   Callpoint names follow the same convention as CIEX variable names. When
   a callpoint is accessed with a "call" command, arguments (if any) are
   passed to the callpoint by value, and are available to the called
   subprogram in the special "$arg" variable view, where the first argument
   is named "$arg:1", the second argument is named "$arg:2" (etc). The
   number of arguments can be determined using the "$arg^last" variable
   attribute. The value of "$arg:0" always contains the name of the
   subroutine called. Passed arguments can be any text string, variable
   value, or variable view.

   To make callpoints accessible to the keyboard, or to allow a script to
   execute callpoints residing in external files, or to speed up access to
   callpoints in the currently executing file, the "source -calls" command
   can be used.

   5.7.1 CALL OPTIONS

   Called routines, by default, share the same name space as the calling
   program. This scope can be changed using the "call -view", "call -root",
   and "call -class" statements as follows: The "call -view" command first
   sets the view of the program to a variable with the same name as the
   callpoint label in the local view, creating the view as needed. The
   "call -root" statement is similar, except the view is set to a variable

                                  Page: 38

   with the same name as the callpoint in the "root" view. The "call -view"
   command is useful for establishing a unique name space for each call
   instance, useful for in recursive (and other) subroutines. The "call
   -root" command is useful for establishing a unique name space for a
   given callpoint (i.e. setting up a private static area for a called
   routine.)

   The "call -class" command is similar to the "call -root" command, except
   that the particular view which is set is given the name of the
   callpoint, delimited by the first colon character in the callpoint name.
   This is useful for setting up a data area which is shared by a common
   class of subroutines. For example, the callpoints "data:incr",
   "data:decr", and "data:clear", if called with the "-class" option, will
   all set the view to the "data" view in the root directory before
   executing any instructions, hence will be able to share data in this
   view.

   Note that called subroutines cannot access data outside their view, nor
   permanently change the view of the calling program. The original view of
   the program (as determined by the "list -view" command) is always
   restored when a source file or callpoint exits.

   5.7.2 SPECIAL CALLPOINTS

   The CIEX interpreter provides special functionality with three
   predefined callpoints. These callpoints, if they exist in a source file,
   are automatically accessed by the CIEX when certain condition occur as
   follows:

   The "interrupt" callpoint, if defined in the currently executing file,
   is automatically called whenever the user enters an CNTRL-C or BREAK
   key, and may be used to handle a keyboard interrupt.

   The "exception"  callpoint, if defined in the currently executing file,
   is automatically called whenever an error is encountered in the program,
   and may be used to handle program exceptions. The error message is
   suppressed (and made available to the executing script) in the special
   "$sys:errtxt" and "$sys:errloc" variables. This is one way of handling
   exceptions and program errors, the other being with the "if -cmd" and
   "while -cmd" statements.

   The "trace" callpoint, if defined in the currently executing file, is
   called as governed by the "trace" command. The "trace" command can
   configure the program to call the "trace" callpoint after each program
   statement, on entry to subroutines, or after every keystroke. This is
   useful for debug, or for handling key strokes entered into a running
   program. This callpoint must be defined in a program in order to use
   the "trace" command.

   Normally, the "interrupt" and "exception" callpoints should redirect the
   program by issuing a "call -goto" or "return -all" command, unless the
   programmer specifically wishes the program continue following the
   interrupt or exception.

                                  Page: 39

   5.8 COMMON PROBLEMS

   The CIEX interpreter is easy to use. However, experience has shown that
   some new users are frustrated by several common problems. This section
   describes these problems, and should be carefully noted by new users.

        1. CIEX is a case sensitive language. All CIEX commands must be
           entered in lower case letters. Generally, the shift-lock key
           should be in the "off" position when using CIEX or developing
           CIEX scripts. This is the most common problem which new users
           experience, one of the hardest for unaware users to figure out
           by themselves, and also one of the easiest to explain.

        2. If an external DOS command or program has the same name as a
           CIEX command, the CIEX command will be executed instead of the
           external command. To specifically execute an external command
           instead of a CIEX command, type the command in upper case
           letters, or use the CIEX "exec" statement. Note that DOS files
           and commands are never case sensitive.

        3. When a variable is set, it persists until specifically unset,
           even after a script terminates. Therefore, it is often a good
           idea to issue a "set -clear" command at the start of most
           scripts to insure that persisting variables are unset, so that
           they will not interfere with the script's normal execution.

        4. CIEX changes the scope and visibility of variables using the
           "set -view" command, "call -view" command, and other related
           commands. CIEX does not otherwise limit visibility of variables
           in callpoints and source files. This can cause problems to
           unaware users when, for example, two subroutines are using the
           same iterative variable. Such problems are avoided by using the
           "call -view", "call -root", and "call -class" statements, which
           change the view of a callpoint before executing it, and thereby
           limit the data which can be affected and used by the subroutine.
           Also, data within the special "$arg" view of each callpoint and
           source file cannot be affected by calling a subroutine or source
           file, hence is a good place to assign data which is to be local
           to a subroutine.

        5. Most commands can be chained together on a single line,
           separated by unquoted semicolons. Several special commands exist
           which CANNOT be arbitrarily chained together with semicolons:
           "endif", "endblock", "endloop" statements must be used by
           themselves on a line with no other statements. Also, the "else"
           command cannot be preceded by a semicolon command. In
           particular, note that "if", "else" and "endif" statements can
           only be used on separate lines.

        6. CIEX allows nesting of redirected output. New users are
           sometimes baffled by why "echo" (and other) commands do not
           display output as suspected. This is probably because the output
           of their program or callpoint is being redirected at a higher
           level. To force the output to the screen (regardless of whether
           the output is redirected at a higher level) simply redirect the

                                  Page: 40

           output of a command to the console "CON" device such as with the
           statement "echo (text) > con". Note that, from an
           object-oriented perspective, this is not always desirable; it is
           usually better to let a calling routine redirect normal screen
           output. However, echoing to the "CON" device is often useful
           when displaying debug information.

        7. If screen buffering is enabled at the keyboard or in a script,
           it will remain enabled while CIEX executes until specifically
           disabled. Therefore graphic commands will not display output if
           screen buffering was enabled by a previously executed script. It
           is usually a good idea to cleanup before exiting a script by
           issuing a "screen -default" command. This command can also be
           issued at the keyboard if text graphic commands are not updating
           the display as expected.

        8. Top level CIEX scripts traverse callpoint statements as if they
           were comments, while CIEX subroutines are delimited by callpoint
           statements. Therefore, the main portion of a CIEX script should
           generally conclude with a "return" statement to prevent the
           execution of subroutines which may reside at the end of the main
           portion of a script.

        9. To execute a script from within a script, and guarantee that the
           second script will not affect data of the first script, simply
           execute a second copy of CIEX, such as with the statement "ciex
           (sourcefile) (args)". On most systems, at least three nested
           copies of CIEX can be executed before running out of memory.

       10. CIEX regards double and single quote marks as special
           characters, used to delimit the start and end of arguments.
           Also, "echo" and "set" commands strip off outer balanced quote
           marks when they completely enclose a text string. Therefore, the
           "set" and "echo" commands can insert spaces in quote marks while
           tokenizing arguments. To avoid this problem, use brace
           characters "{ }" to quote text strings. (Brace characters are
           exactly like double quote marks except they may be nested, and
           are removed by the input parser instead of the command
           processor.) As an alternative, use the special "set -value" and
           "echo -value" commands to process text strings containing outer
           balanced quote marks.

   6.0 ADDITIONAL NOTES

   NLS guarantees that the CIEX.EXE executable and unmodified demo programs
   supplied directly by NLS are free of any intentionally inserted viruses
   or malicious software.

   NLS makes no other warranty of any kind, express or implied, including
   without limitation, any warranties of merchantability and/or fitness of
   this demonstration software for a particular purpose. NLS shall not be
   liable for any damages, whether direct, indirect, special or

                                  Page: 41

   consequential arising from a failure of this demonstration software or
   the CIEX interpreter to operate in the manner desired by the user. NLS
   shall not be liable for any damage to data or property which may be
   caused directly or indirectly by use of the program.

   The CIEX interpreter is protected by United States Copyright Law. All
   rights are reserved. However, the user may make unlimited copies of the
   CIEX V2.3.5 software, and distribute this software, providing that the
   software on disk is UNMODIFIED. No fee, other than a reasonable disk
   duplication fee, may be charged when distributing this CIEX V2.3.5 disk.
   If distributing this disk, NLS respectfully REQUIRES ALL files,
   including the order form provided with the base release, be distributed
   INTACT AND UNMODIFIED.

   6.1 SUPPORT

   New Line Software is interested in your applications, and is happy to
   assist with technical questions. Normally, we prefer questions to be
   sent to our office via FAX (1-303-771-0836) or US mail. If your problem
   is particularly urgent, you can call our offices at the toll free number
   1-800-441-2931 (only in the continental USA). Please note that problems
   usually REQUIRE a listing of the problem script for us to expedite.

   6.2 ASSOCIATION OF SHAREWARE PROFESSIONALS

   New Line Software is a member of the Association of Shareware
   Professionals (ASP). ASP wants to make sure that the shareware principle
   works for you. If you are unable to resolve a shareware-related problem
   with an ASP member by contacting the member directly, ASP may be able to
   help. The ASP Ombudsman can help you resolve a dispute or problem with
   an ASP member, but does not provide technical support for members'
   products. Please write to the ASP Ombudsman at 545 Grover Road,
   Muskegon, MI USA 49442-9427, Fax 616-788-2765, or send a CompuServe
   message via CompuServe Mail to ASP Ombudsman 70007,3536.

   Unix is a registered trademark of AT&T.
   Windows, and MS-DOS are registered trademarks of Microsoft Corporation.

   For more information, please call or write NLS, Inc.

   NLS, Inc. New Line Software
   P.O. Box 3433
   Englewood, CO 80155

   OFFICES AT:
   7348 S. Alton Way, Unit I
   Englewood, CO 80112

   PHONE:
   1-800-441-2931, FAX: 1-303-771-0836
   In Denver, and outside of USA: 1-303-741-6594
