DPS Script Language Syntax

 1. General
 The DPS command script language is the language which can be
used to write programs for all 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 zcript 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 recoursion 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.

 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 recoursively 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.

   [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.

   [-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).

   [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).

   [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.

   [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.

    [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.


 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).


 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.



 3.10. GOTO statement

 Go to a program location (specified via the LBL statement).


 3.11. ABORT statement.

 Abort script execution with  error status.


 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.


 3.14. EON statement

 Turn echo on. Begin script line echoing to stdo which was there at
level 0 (when starting the script).

  [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).


 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).


 3.17. EXIT statement

 Abort execution and exit the application which started the script.


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).