CIEX BASE DISTRIBUTION V2.3 Copyright 1993, 1994, New Line Software, Inc. (NLS) APPLICATION NOTES 1.0 INTRODUCTION This file describes the CIEX base distribution disk, Version 2.3. It provides information on how to use CIEX, and on different ways to configure the base distribution demo files. Also included are narratives on the demo programs themselves, to assist a programmer with modifications or experimentation. In particular, Section 5.0 of this file provides a quick reference of all CIEX commands and their usage. For easiest understanding, the user should first execute the CIEX V2.3 demo programs (especially the INTRO.S program) before reading these notes. To execute the CIEX demo program, simply 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 disk file interpreter. It reads commands from a disk file (or from the keyboard) and executes these commands. Its operation is a blend of the MS-DOS COMMAND.COM program and UNIX shell scripts. The CIEX interpreter includes functions needed to support text-graphic screens, mathematical evaluation of equations, multidimensional arrays and data records, and redirection of data to external files and programs. 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 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.) 1.2 CIEX.EXE PROGRAM The CIEX.EXE file is the executable CIEX program. It is the only non-text file that comes with the base CIEX distribution, and is a fully functional, non-crippled version of the CIEX program. 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. 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 the command line similar to that found in the Version 5 MS-DOS, i.e. previous commands can be recalled using the "up" arrow key. Page: 2 To become familiar with CIEX, we suggest that users experiment with commands interactively. In particular, issuing the "echo -on" command at the keyboard causes each subsequent CIEX command to be displayed before it is executed. The complementary "echo -off" command will turn off command echoing. This facility affords a fair amount of debug information when executing scripts. (Note: the optional CIEX Development Environment, not provided as part of the base distribution, includes a much 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 filenames can be entered in either upper or lower case letters.) Normally, CIEX users work with the "Caps Lock" key OFF. 1.3 INSTALL.S SCRIPT When the DEMO.S script is executed, it checks to see if the disk file INSTALL.S is in the local directory. If so, it executes this script to install the CIEX demonstration software in the directory C:\CIEX. The INSTALL.S script may be executed independent of the demo script using the INSTALL.BAT batch file, supplied with the base distribution software. Or, as an alternative to using the INSTALL.S script, a user can simply copy all files from the distribution disk to an arbitrary directory on the hard drive. 1.4 OTHER SCRIPTS Five other scripts are included on the demonstration disk. These scripts are described in detail in section 4.0 of this note, and represent a small subset of the 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 a new user 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 programs. 2.0 SYSTEM REQUIREMENTS 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 to operate. Because CIEX scripts execute DOS internal and external commands, scripts can be particularly sensitive to DOS revision levels. The scripts in this demonstration disk require a DOS version of 3.0 or greater. Page: 3 CIEX scripts can be memory intensive. The scripts in this demonstration disk 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 program 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 DEMO PROGRAM The base CIEX Version 2.3 distribution is intended to supply both an overview of the CIEX interpreter, and also provide useful programs to the user. If a user does not wish to learn how to write CIEX programs at this time, but would still like to continue executing the demonstration programs, we suggest that the "source -bind" command be used to create executable programs from the scripts. The "source -bind" command, when issued at the "ciex>" prompt, accepts as a single argument the name of a CIEX script file. CIEX creates an ".EXE" file from the specified script file, which can then be executed without the interpreter being present. Alternate ways of configuring the demo programs are provided in the sections that follow. 3.1 CONFIGURING FOR A MS-DOS ENVIRONMENT One way to bypass the introductory screens, and access a demo program directly, is to create a simple batch file that changes working directories to the C:\CIEX directory, and then invokes a specified script program with CIEX. For example, to execute the EVAL.S program, use the following batch file: rem : Filename EVAL.BAT rem : Execute the Math Statement Evaluator. cd c:\ciex ciex eval.s Similarly, any of the other demo programs can be executed by replacing the "eval.s" argument above with one of the other script file names. (Note that, because of the way that these demo scripts are written, the "cd" command is required for proper operation. Adventurous programmers can modify the scripts to make them path independent.) The above batch file assumes the demo is installed in the directory C:\CIEX. 3.2 CONFIGURING FOR A MS-DOS WINDOWS ENVIRONMENT CIEX can be executed in a MS-DOS Windows environment, allowing CIEX scripts to be written and accessed from windows. PIF files are supplied for the EVAL.S, ADDR.S, and CALENDAR.S scripts in the directory C:\CIEX\PIF. The user may create PIF files for the other demo programs as well, using the standard Windows PIF editor. Page: 4 Assuming that the DEMO program has been installed in the directory C:\CIEX (as per the supplied installation script INSTALL.S), the EVAL.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 "Evaluator" (or some other title) for the Description. 4. Enter C:\CIEX\PIF\EVAL.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, the other demo scripts can be installed by entering the appropriate PIF file pathname. (The above procedure assumes the demo is installed in the directory C:\CIEX.) 4.0 DESCRIPTION OF DEMONSTRATION SCRIPTS This section describes the demo programs that accompany the CIEX V2.3 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. The user is encouraged to experiment with one or more of the scripts to evaluate the capabilities of the interpreter. Each source file 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 this distribution can also 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, it displays an introductory screen, and executes the INSTALL.S script (if present.) Then, 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 called, which flushes 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 Page: 5 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)". If (filename) is omitted, the screen is saved and restored using the built-in CIEX screen buffer. 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.S), included as part of the optional CIEX Development Environment (but omitted from the base demo distribution). Like the Adobe System PostScript programming language, CIEX is well suited as a presentation-description language. The VGCOMP program generates a CIEX script much the same way that PostScript programs are created for PostScript graphics printers. 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 that contains 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 keys associated with the menu. 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.S program. 4.2.2 MODIFYING INTRO.S Several modifications can be made to INTRO.S by a programmer. The colors used in the program are assigned at the top of the script. A programmer may modify the $titlecolor, and $textcolor assignments to Page: 6 change the way the display looks. A programmer can also easily 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, such as providing the name of the source document. 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 as easy to add or delete paragraphs, or change the paragraph ordering, since these attributes are determined by the VGCOMP.S program. 4.2.3 LISTING THE INTRODUCTION TO A FILE OR SCREEN The source document that was processed by the VGCOMP.S program can be output by the INTRO.S program 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 the DOS prompt. 2. At the "ciex>" prompt, issue the command: "source -calls intro.s" to allow access to the INTRO.S program callpoints from the keyboard. 3. At the "ciex>" prompt, issue the command: "call list_source" to list the source document (including paragraph numbers) 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 keyboard (and other CIEX scripts) using the "source -calls" statement. The names of the callpoints that are currently accessible 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 that 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. The only sophisticated function of the EVAL.S is the PREV RESULT function, which requires that each character in the input window be fetched one at a time (by the "get_equation" callpoint.) Page: 7 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", which is 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 that has a callpoint with the same name, 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.) 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. Page: 8 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 that 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. 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, edit, delete, sort or find records, 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 COM3) is selectable by the user and resides in the $static:comm record, also saved to the "addr.dat" file. 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 Page: 9 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 that incorporates elements to store and access data (like ADDR.S above), and also perform fairly complicated math evaluations. The calendar uses a well known algorithm for determining the starting day of the week for a particular month, given a year. 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 Page: 10 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 that 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.) 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 of the segments 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" function. This function 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. The "trace" callpoint (defined towards the end of the program) keeps track of the current screen number. The user can increment the screen number, decrement the screen number, call the special "help" screen, or exit the program. If the screen number is changed, the particular draw routine is accessed using a "call -goto" command. Page: 11 4.6.2 MODIFYING REACTOR.S The REACTOR.S program is a good place to experiment with the CIEX interpreter text-graphics capabilities. Various obvious changes can be made to the draw routines 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 try adding 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.) 5.0 CIEX V2.3 QUICK HELP REFERENCE The remainder of this note is a guide to using the Version 2.3 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 that may be used as a quick reference. A more detailed description of CIEX, including application notes, is presented in the Version 2.3 CIEX 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 that 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. Page: 12 () Parenthesis are used to denote descriptions of required arguments. Items that 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. 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 loops. The "-next" option causes the program to immediately restart at the top of the current loop. This 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. call -goto (label) Branch the program immediately to the specified label, and resume execution as a main program. Page: 13 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. echo -ascii (integer) Display the ASCII character corresponding to the integer argument. 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 currently executing script. echo -eval (expression) Display the result of a math evaluation given by (expression). 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 Page: 14 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. 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 debug. 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[N] 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 "N". 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. Page: 15 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. 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. 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. 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" and "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" and "endloop" statements. The specified command can be any internal or external (DOS) command. Page: 16 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" and "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" and "endloop" statements. for [ -value | -name ] (var) = (view) Iterate for each variable in the specified 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" and "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. 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. if -eval (expression) Execute a mathematical expression and branch if the result of the expression is zero. 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 Page: 17 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 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 centered on the screen. list [ (view) ] List variable names and values in the current variable view. If "(view)" is specified, list the elements of "(view)" rather than the current working view. 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)". 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. 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 that have been 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. Page: 18 list -system List the names and values of the "$sys" global view. 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. 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). 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 that 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 or 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. 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. Page: 19 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. quit Exit the interpreter and return to DOS. This is the only command with a synonym: "exit". read (var) Read a string from the keyboard, 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 that was entered. (Key names can easily be determined by experimenting using the "read -key" and "echo" commands at the keyboard.) 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 width of the text field, and defaults to the width of the screen. 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 the text under the cursor. The "graph" qualifier is especially useful, and will return any text enclosed within graphic characters, such as a box. 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. Page: 20 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 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 -background | -foreground (color) Change the screen background or foreground color. 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 appear when commanded. Turning screen buffering "on" automatically copies 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 that 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 that use text graphic commands. Page: 21 screen -flush [ (filename) ] Flush the screen buffer to the screen. (The screen buffer is enabled using the "screen -buffer on" statements.) 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 standard output. 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. screen -mode mono | color Change the screen display mode to either monochrome or color. 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 that do not generate output will not scroll the screen, allowing easier experimentation of text graphic commands at the keyboard. 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. Page: 22 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. 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 MSDOS. select -prompt (string) Set the value of the interactive interpreter prompt. select -screen (column) (line) [ (width) height) ] Select a region of the screen. This command works exclusively with the "scroll" and the "screen -list" 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)". Page: 23 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. 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. 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 a view 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)". set -file (var) = (filename) [ (startline) to (endline) ] Assign the contents of the text file given by "(filename)" to the variable specified by "(var)", creating a view 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, but will be a scalar value. set -list (var) = (string) [ by word | char | punct | (sep) ] Split a string into tokens, and create a view where each token is a subscript value of "(var)". The optional "by" qualifier indicates whether the string is divided into a list words (the Page: 24 default), a list of characters, a list of words separated by punctuation characters, or a list of tokens separated by an arbitrary character. 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 WILDCARDS below. 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. 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 "$"), 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 Page: 25 specified view, otherwise variables are created in the current view. One application of this command is to restore a database that was created by issuing the "list -all" command with redirection to a file. sleep (milliseconds) Pause for the specified number of milliseconds. source (filename) [ (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. source -bind (filename) Don't execute "(filename)". Instead, create an "EXE" file from the specified interpreter script, with the same basename as "(filename)". Any existing "EXE" is overwritten. source -calls [ (filename) ] Don't execute "(filename)". 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 callpoints in the currently executing 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 "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. 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. 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 Page: 26 "-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. unset (var) Delete a variable or view from the program. No error is reported if the specified variable is already unset. unset -all | -calls | -system Delete all variables, all callpoints, or all variables defined in the special "$system" view. unset -view Restore the view 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" and "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. 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. 5.2 SPECIAL PROGRAM CHARACTERS The CIEX interpreter defines certain characters which have special significance when found in a program. To escape the meaning of a special character, precede the character with a tilde (~) character. (Note that the tilde character can be escaped using two adjacent tilde characters.) Or, if possible, enclose the special character in single quote marks. ~ (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 that immediately follows. Page: 27 # (Number sign). The comment character. Ignore any characters that 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. $ (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 VARIABLE ATTRIBUTES section.) ' (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 that 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 that contains double quote marks [ (Left bracket). Begin inline evaluation. Assume that the text string that follows (delimited by a right bracket) is a mathematical expression to be passed to the expression evaluator. ] (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. Page: 28 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. 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 a 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 that 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. 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 that is unique to a program segment. 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" command. The "$arg" view contains arguments passed into the program from the command line or "call" statement. Setting the view to the "$arg" view on entry to a source file or callpoint insures that the program segment cannot affect data used by the calling procedure. 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.) Page: 29 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. 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 that 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 that 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)". Page: 30 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)". (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 (number) 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 simple 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 common 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. Page: 31 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.) 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. Page: 32 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. 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: 33 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, that 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 that 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 that 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 that 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 that 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: 34 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 that 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 that 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 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 Page: 35 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 that 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 that 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 callpoint exits. 5.7.2 SPECIAL CALLPOINTS The CIEX interpreter defines three callpoints that provide special functionality. 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). 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: 36 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 that 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 do 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 that 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 that 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 that 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: 37 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 that 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 that 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: 38 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 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 disk. If distributing this disk, NLS respectfully REQUIRES that 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. PostScript is a registered trademark of Adobe Systems, Incorporated. 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