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