Retro1.org codex

SPECIAL VARIABLES                                        EXEC special variables

Special variable are variable symbols that are assigned values by the EXEC
interpreter, and that you can test or display in your EXEC procedures.  In some
cases, you may assign your own values to EXEC special variables; these cases
are noted in the descriptions below.

&n        The &n special variable represents the numeric variables &1 through
          &30.  When an EXEC is invoked, the numeric variables from &1 through
          &30 are initialized according to the arguments that are passed to the
          EXEC file (if any).

          The numeric variables can be reset by either an &ARGS or &READ ARGS
          control statement; when fewer than 30 arguments are set or reset, the
          remainder of the &n variables are set to blanks.

          A particular argument can be set to blanks by assigning it a percent
          sign (%) when invoking the EXEC procedure, in an &ARGS control
          statement, or in an &READ ARGS control statement.  An argument is
          also set to blanks if it begins with the character X'FF' and is
          specified when invoking the EXEC procedure or in an &READ ARGS
          control statement.  You may set the values of specific arguments
          using assignment statements.  Any value of n, however, that is
          greater than 30 or less than 0 is rejected by the EXEC interpreter.

&* and &$ These variables can be used to perform a collective test on all of
          the arguments passed to the EXEC procedure.  &* and &$ may only be
          used in the &IF and &LOOP control statements and are described under
          the description of the &IF control statement.  You may not assign
          values to the special variables &* and &$.

&0        The &0 special variable contains the filename of the EXEC file.  You
          may test and manipulate this variable.

&DISKx    You can use the &DISKx special variable to determine whether a disk
          is an OS, DOS, or CMS disk.  x represents the mode letter at which
          the disk is accessed.  For example, if you access an OS disk with a
          mode letter of C, then the special variable &DISKC has a value of OS.
          The possible values for the &DISKx special variable are OS (for an OS
          disk), DOS (for a DOS disk), CMS (for a CMS disk), and NA (when the
          disk is not accessed).

          You may set or change the values of an &DISKx special variable.  If
          you do so, you are no longer able to test the status of the disk at
          mode x.

&DISK*    The &DISK* special variable contains the one-character mode letter of
          the first read/write disk in the CMS search order.  If you have no
          read/write disks accessed, this special variable contains the value
          NONE.

          You may assign a value to the &DISK* special variable for your own
          use; if you do so, however, you will not be able to use it to obtain
          the filemode letter of a read/write disk.

&DISK?    You can use the &DISK? special variable in an EXEC to determine which
          read/write disk that you have accessed has the most space on it.  If
          you have no read/write disks accessed or if the accessed disk is
          full, &DISK? contains the value NONE.

          You may assign a value to the &DISK? special variable for your own
          use; if you do so, however, you will no longer be able to locate the
          read/write disk with the most space.

&DOS      The &DOS special variable contains one of the two character values ON
          or OFF, depending on whether the CMS/DOS environment is active.  If
          you have issued the command:
             SET DOS ON
          then the &DOS special variable contains the value ON.

          You may set or change the value of the &DOS special variable for your
          own use; if you do so, however, you will not be able to test whether
          the CMS/DOS environment is active.

&EXEC     The &EXEC special variable is the filename of the EXEC file.  You
          cannot set this variable explicitly but you can examine and test it.

&GLOBAL   The &GLOBAL special variable contains the recursion level of the EXEC
          currently executing.  Since the EXEC interpreter can handle up to 199
          levels of recursion, the value of &GLOBAL ranges from 1 to 199.  You
          cannot set this variable explicitly, but you can examine and test it.

&GLOBALN  The &GLOBALn special variable represents the variables &GLOBAL0
          through &GLOBAL9.  You can set these variables only to integral
          numeric values.  They are all initially set to 1.  Unlike other EXEC
          variables, these can be used to communicate between different
          recursion levels of the EXEC interpreter.

&INDEX    The &INDEX special variable contains the number of arguments passed
          to the EXEC procedure.  Since up to 30 arguments can be passed to an
          EXEC procedure, the value of &INDEX  can range from 0 through 30.

          Although you cannot set this variable explicitly, it is reset by an
          &ARGS or &READ ARGS control statement.  &INDEX can be examined to
          determine the number of active arguments in the EXEC procedure.

&LINENUM  The &LINENUM special variable contains the current line number in the
          EXEC file.  You cannot explicitly set this variable but you can
          examine and test it.

&READFLAG The &READFLAG special variable contains one of two literal values:
          CONSOLE or STACK.  If there are stacked lines in the program stack or
          terminal input buffer &READFLAG contains the value STACK and the next
          read request results in a line being read from the stack.  If not,
          then the next read request results in a physical read to the
          terminal, and the value of &READFLAG is CONSOLE.  You cannot
          explicitly set this variable but you can examine and test it.

&RETCODE  The &RETCODE special variable contains the return code from the most
          recently executed command.  &RETCODE can contain only integral
          numeric values (positive or negative), and is set after each CMS
          command is executed.  You can examine, test, and change this variable
          but changing it is not recommended.

&TYPEFLAG The &TYPEFLAG special variable contains one of two literal values: RT
          (resume typing) or HT (halt typing).  It contains the value HT when
          terminal display has been suppressed by the Immediate command HT.  It
          contains the value RT when the terminal is displaying output.  You
          cannot explicitly set this variable, but you can examine and test it.