DPS Script Language Syntax 1. General The DPS command script language can be used with those DPS applications which allow command line input (this means virtually all; most applications use the powerful "menu" plm function). Interactive applications can be started, operated and terminated from the same script. Access to DPS global objects is also possible via the 'make' and 'do' statements. The following description implies the DPS "command_script" global type (used by shell, nuvi etc.) unless otherwise noted. Examples imply starting the program as a shell script. 2. Operation A script runs in two phases - compilation and subsequent interpretation. When a script is started, the source file (with default .bat suffix) is compiled into an intermediate one. The latter takes the name of the source file, but has the suffix '.nnnn' where nnnn stands for the hex. representation of the script nesting level, thus allowing recursion depths (theoretically) up to 2^16. If the global variable 'shellwd' is not defined, the intermediate file is created in the task's current directory; otherwise, 'shellwd' is expected to define a valid, r/w accessible path where the file is placed. Upon successfull script termination, the intermediate file is deleted; if execution is aborted due to errors, the script can be continued using the 'retry' or 'resume' commands referring to that intermediate file (or using the @r and @g comands which refer to the latest intermediate file). 3. Syntax All command lines to be interpreted start with a '@' ($40) character. Lines, starting with an asterisk, are treated as comment lines and are not compiled into the intermediate file (unlike the 'rem' command, which is diplayed at runtime). Null lines are compiled (and echoed). The interpretation of other lines is application specific; that is, they are passed as standard input to the application currently running. During compilation, command line (from the line which started the script) variables are processed as following: `var_name - replaced with the command line related variable. During execution, the following rules apply to all lines: ]var_name - is replaced with its respective local variable, [var_name - replaced with the respective global variable. In all cases, variables are space or CR terminated; the terminating character is not part of the variable replacement (it is lost). Variable names are recursively processed; that is, if we have the variable var1 defined as "var" and the variable ix defined as, say, "5", then ]var]ix will be replaced by the value of the variable var5. Undefined variables result in null text. {numeric expression} - replaced with the text representing the result from the evaluation of the numeric expression between the { and } characters (see 4. Expressions). A character, preceeded by the ~ ($7e) character is never interpreted, but passed unchanged instead; the ~ character itself is lost (unless preceeded by a ~ character itself). Local variables are available to the application which started the script and every application which is part of this script; global variables are system-wide accessible. Commands, as well as variable names, are not case sensitive. Variables are reproduced case unmodified. 3.1. Command line Command line is the line which started the script. There are two ways to pass data from the command line to the script - as named command line variables and/or as sole words. In addition, a command line variable (named w@) passes the number of sole words present in the command line. Named variables are passed in the form: var_name%some text to replace it%. The % signs are stripped; any text netween the % signs is allowed. Accessing a command line variable from the script is done by writing the variable name preceeded by a ` ($60) character and terminated by a space or CR (like all variables). The following sole word command line variables are always generated: w@x - where x is a decimal number (no leading zeroes) corresponding to the position of the word in the command line, 0 being the left most, and named variables being not counted, passes a sole word (space separated) from the command line. To put the left most sole word from the command line (excluding the command itself) somewhere in your script, write "`w@0 " at this position (the "" marks not included), w@l - the whole command line (excluding the command word and its following delimiter), w@ - the number of sole words in the command line. In addition, a variable named 'formstdi' is always present to allow return from script nesting. It contains the complete path of the stdi of the starting task prior to the start (during execution it is the intermediate script file itself). 3.2. INPUT statement Interactive user input. Input is done from the input nexus, which was active at the point where the script nesting level was 0 (usually the console). The prompt string (if some) is passed to the output nexus active at the same time. Syntax: [prompting text] Exit conditions: The follwing local variables are updated/created: i@t - the textual hex. representation of the terminating character, i@ - the number of space separated words entered from the user, as decimal text, i@l - the whole line entered, i@x where x is a decimal number - the corresponding word from the line just input. Counted left to right, left most being 0. Caution: existing i@x variables of older "INPUT" statements are not updated nor deleted if there was no input for them. 3.3. INLINE statement Input a line from a specified I/O nexus. If position is specified but the nexus is not randomly accessible, position is set to 0; otherwise, if position is beyond eof, error occurs. Syntax: [-p position] [-t terminator list] [-a abort character] Notice that terminator list must be the last option on the line. If no terminator list is specified, CR will be the only terminator. No character will abort input, unless specified (as an expression). Only one abort character will be active (the last at te line, if > 1). Exit conditions: same as after INPUT statement, plus i@p - file position reached during input. If input was not from a randomly accessible device (such files do not exist), the value is impredictable. Returned as decimal text. 3.4. SETL statement Set a local variable to a value. The text assigned is space or CR terminated; the line obeys the common line processing rules (see 3. Syntax and 4. Expressions). Syntax: [text_to_assign_"to the variable"] 3.5. SETG statement Set a global variable to a value. The text assigned is space or CR terminated; the line obeys the common line processing rules (see 3. Syntax and 4. Expressions). Syntax: [text_to_assign_"to the variable"] 3.6 MAKE statement Make an object of the specified type. An object header with the specified name and size 0 is used to do the 'create' action. The 'something' type 'create' action interprets the first word of the passed text as desired object size to allocate; if not specified, 1 memory cluster is allocated to an object_segment type, and the new object is placed into it so that it fills it. Syntax: [text passed to the 'create' action code] Exit conditions: The follwing local variables are updated/created (numbers returned as expression compatible text, mostly as hex. numbers): i@0 - object address, i@1 - object actual size (the number that was written at XO$NEXT). i@ is always returned and specifies the number of words (numbers, here) returned in i@x - in this case it is "2". 3.7 DO statement Do the specified action with the specified object. Syntax: [text to pass] Exit conditions: Same as from INPUT statement. Notice that the only variables known to be affected are i@ and i@l - i@x will be not affected if x <= {i@} . If i@=0, i@0 is not affected and i@l is a null line (just a CR). The 'do' call is passed the local variable area; it is possible that during execution it will create/modify local variables, depending on the action related code. 3.8. IFcc statements Conditional execution statements. Syntax: [statement] If statement is specified at the same line, then: If the condition is true the statement is processed as such (e.g. goto, setl etc.). If the condition is false, the line is ignored. In either case, this line has no effect on subsequent program flow. If statement is not specified at the same line, then: If the condition is true, continue execution normally and ignore the first endc statement. If the condition is false, ignore all lines until after the first endc statement. 3.8.1. Conditions The following conditions are evaluated (shown here with the IF prefix): ifc - if strings compare (case sensitive). Syntax: Both strings may contain any ASCII printable characters other than the separator. Any printable character may be the separator, the | ($7c) and , ($2c) being most popular in TGI's scripts. Example: "ifc ,one,two," - false, "ifc ,one,one," - true. - if strings do not compare. Syntax same as ifc. - same as ifc, but case insensitive. - same as ifnc, but case insensitive. - if local variable defined, - reverse of the above, - if global variable defined, - reverse of the above, - if command line variable defined, - reverse of the above, The following are numerical (evaluate the text passed as a numerical expression and interprete the result of it). - if expression=0 - if expression <> 0 - if expression >= 0 - if expression > 0 - if expression <=0 - if expression < 0 3.9. LBL statment Define a program location. Processed during compilation phase, not echoed during execution; must obey the variable name syntax. Syntax: 3.10. GOTO statement Go to a program location (specified via the LBL statement). Syntax: 3.11. ABORT statement. Abort script execution with error status. Syntax: 3.12. END statement Terminate script execution. Has the same effect like reaching the script end; returns to previous level, which continues execution, if it was not 0. 3.13. EOFF statement Turn echo off. Suppress echoing script lines to the stdo which was there at level 0 (when starting the script). The eoff line itself is not echoed. Syntax: 3.14. EON statement Turn echo on. Begin script line echoing to stdo which was there at level 0 (when starting the script). Syntax: [number of lines to stay off after this line] If there is no number of lines specified, the first line echoed as a result of the EON command will be the line immediately after it. 3.15. SHOWL statement Show a local variable. If the variable contents is text, it is output at a new line. If the echoing is to a DPS window, any object sequence is shown (using the XWSEQ$ call). Syntax: 3.16. SHOWG statement Show a global variable. If the variable contents is text, it is output at a new line. If the echoing is to a DPS window, any object sequence is shown (using the XWSEQ$ call). Syntax: 3.17. EXIT statement Abort execution and exit the application which started the script. Syntax: Note: If this is executed by the shell and there is no other shell running, there may be no way except rebooting to gain access to the system, though it is completely intact. 3.18. RETRY statement Restart execution from the point where the error occured (retrying the line that caused the error). Syntax: