
_______________________________________________________________________________

                  An Introduction to PRIMOS CPL Directives
           Written by Necrovore on 09/02/88 (Revised on 09/10/88)

                 A Telecom Computer Security Bulletin File
_______________________________________________________________________________


PREFACE

This text file is intended to serve as a reference guide for the aspiring CPL
programmer.  It is a full listing of CPL commands and discusses all arguments
rather thoroughly.  The following directives may be used within CPL programs
only (for information on writing CPL programs, see the CPL User's Guide).

This file was to be released in Phrack Issue 20 but certain members of that
organization decided that this information was "too valuable for release to the
general public".  You know what I think of that?  Utter bulls***!.  Sounds more
like a bad case of information hoarding to me.  That is not very cool.  They
appear to be afraid that Primes will be abused by people.  Tell me, is it not
better to teach everyone what CPL is and what it can do and how to PROPERLY use
it?  Thus, this file is not being released in Phrack.  It is being released as
part of TCSB Volume One.


CPL COMMANDS

&ARGS [name[;[type][=default] ]...]~
[name: -control_list [name[;[type][=default] ];...] ]

Defines names (plus types, default values, and keywords, if desired) for arg-
uments to be passed to a CPL program.  Type may be any type shown below.  If
type is not specified the argument defaults to type char.  If default is not
specified, the system defaults are assigned as shown below:

     Argument                                         CPL
       Type              Explanation             Default Value

     CHAR          Any character string up to          "
                   1024 characters long, mapped
                   to upper case (default).
     CHARL         Any character string up to          "
                   1024 characters long, no
                   case shifting.
     TREE          A filename, directory name,         "
                   or pathname, up to 128 char-
                   acters long.  The last element
                   of the pathname (that is, the
                   final file or directory name)
                   may contain wildcard characters.
     ENTRY         A filename up 32 characters         "
                   long; may contain wildcard
                   characters.
     DEC           A decimal integer (A).              0
     OCT           An octal integer (A).               0
     HEX           A hexadecimal integer (A).          0
     PTR           Pointer; a virtual address        7777/0
                   in the format "octal/octal"
                   (segno/wordno) (B).
     DATE          Calendar date in the format         "
                   mm/dd/yy.hh:mm:ss or yy-mm-
                   dd.hh:mm:ss.                        "
     REST          The remainder of the command
                   line.
     UNCL          All tokens not accounted for        "
                   in the &ARGS picture.

     (A)  Numeric arguments must be within the range if -2**31+1...2**331-1
     (B)  User specified default values are not supported for this datatype.


&CALL routine_name

Transfers control of the internal routine designated by routine_name.  See also
&ROUTINE.


&CHECK expression &ROUTINE routine_name

Defines an error condition (expression) and a routine (routine_name) to handle
the condition.  When this directive is present, the CPL interpreter evaluates
expression after executing each PRIMOS command.  If expression is true, control
passes to routine_name.


&DATA statement
 statement1
    .
    .
    .
 statement-n
[&TTY]
&END

Groups of statements to be treated as data or subcommands for user programs or
PRIMOS utilities.  The statement immediately following &DATA must invoke the
program or utility.  All other statements between &DATA and &END are evaluated,
and the results written into a temporary file.  The program (or utility) is
then invoked and information passed to it, a line at a time, when called for.

The &TTY directive may be used as the last statement preceding the &END.  When
it is reached, control passes to the user at the terminal.  When the user exits
from the program or utility, control returns to the CPL program.


&DEBUG [option-list]

Enables debugging for the CPL procedure containing the &DEBUG directive.  If
given without options, &DEBUG is equivalent to &DEBUG NO_EXECUTE &ECGI ALL.
Options are:

         OPTION                      ACTION

     &OFF                            Turns off all debugging options.
                                     Initially all options are off.
     &NO_EXECUTE, &NEX               Suppresses execution of PRIMOS
                                     commands, but interprets CPL
                                     directives.
     &EXECUTE, &EX                   Enables execution of PRIMOS
                                     commands.
           {ALL}                     If ALL is specified, echoes PRIMOS
     &ECHO {COM}                     commands and CPL directives.  If COM
           {DIR}                     is specified, echoes only PRIMOS
                                     commands.  If DIR is specified,
                                     echoes CPL directives.  Default is ALL.
              {ALL}                  ALL cansels all echoing.  COM cancels
     &NO_ECHO {COM}                  echoing of PRIMOS commands.  DIR
              {DIR}                  cancels echoing of CPL directives.
                                     Default is ALL.
     &WATCH                          Adds the specified variables to the
     [var1 var2 ... var16]           watchlist  When the value of a
                                     watched variable is changed using
                                     the &SET_VAR directive (not the &SET_
                                     VAR command), CPL reports this fact
                                     and the new value of the variable.
                                     At most 16 variables can be on the
                                     watchlist.  If no vari are present,
                                     all variables are watched.
     &NO_WATCH                       Removes the specified variable(s)
     [var1 var2 ... var16]           from the watchlist.  If no variables
                                     are specified, watching is turned
                                     off completely.


&DO [iteration]
 statement-1
    .
    .
    .
 statement-n
&END

Allows a group of statements to be used anywhere a single statement can be
used.  If iteration is present, allows conditionally repeated execution of the
statements contained between the &DO and the &END, iteration may be any of:

     1.  null (statement grouping)
     2.  [&WHILE while] [&UNTIL until]
     3.  var := start [&TO to] [&BY by]
            [&WHILE while] [&UNTIL until]
     4.  var &LIST list [&WHILE while] [&UNTIL until]
     5.  var &ITEMS items [&WHILE while]  [&UNTIL until]
     6.  car := start &REPEAT repeat~
            [&WHILE while] [&UNTIL until]


&EXPAND {ON}
        {OFF}

Turns abbreviation expansion on or off.  Default is OFF.


&GOTO label_name

Transfers control to the statement following the &LABEL label_name directive.


&IF expression &THEN true-statement
[&ELSE false-statement]

Evaluates expression.  If expression is true, true-statement is executed.  If
expression is false, then:

     o  If &ELSE is present, false-statement is executed.
     o  If &ELSE is not present, control passes to the next
        statement in the CPL program.


&LABEL label_name
 stateent

Defines a label, label_name to which a &GOTO can go.  (When &GOTO is reached,
control passes to the statement following the &LABEL directive)


&ON condition &ROUTINE routine_label

Defines an internal routine to act as condition-handler (or on-unit) for the
defined condition.  (See the PRIMOS Subroutines Reference Guide for a list of
PRIMOS-defined conditions and an explanation of PRIMOS's Condition Mechanism)


&RESULT expression

Used only in CPL programs designed to invoke via function calls from other CPL
programs.  (For example, "&IF A<50 &THEN &S B := [R program]").

When the &RESULT directive is reached, expression is evaluated and its value
returned as the result of the function call.


&RETURN [severity] [&MESSAGE text]

Halts execution of procedure in which it occurs.  Returns control to procedures
called.

If &MESSAGE is present, prints text on terminal when control returns.  If sev-
erity is present returns its value as a severity code to the procedures caller.
Severity must be an integer.


&REVERT condition

Disables the latest condition handler defibed (via the &ON directive) for the
named condition.


&ROUTINE routine_name

Names and defines entry point for an internal routine.


&SELECT test_expression
 &WHEN expression-1 [,expression-2, ... ,expression-n]
 statement
 &WHEN expression-1 [,expression-2, ... ,expression-n]
 statement
    .
    .
    .
 [&OTHERWISE statement]
&END

Test_expression is evaluated and tested against expression-1, expression-2, and
in turn until expression-n is reached.  When a match for test_expression is
found, the statement following the matching expression is executed.

If no match is found, then:

     o  If an &OTHERWISE directive is present, the statement following
        it is executed.
     o  If no &OTHERWISE directive is present, control passes to the
        statement following the &END of the &SELECT group.


&SET_VAR var-1 [, var-2, ... , var-n] := value

Sets the value of the named variables to value.  The variables need not exist
previously.  May be abbreviated to &S.


&SEVERITY [level] [action]

Checks for severity codes other than 0 (where codes > 0 indicate errors and
codes < 0 indicate warnings) after execution of each PRIMOS command.  If a code
>= level is found, takes the specified action.

     Level may be:

        &ERROR                  Ignore warnings, take action on errors.
        &WARNING                Take action on warnings and errors both.

     Action may be:

        &FAIL                   Halt execution, return a positive severity
                                code to the routine's caller.
        &IGNORE                 Continue execution.
        &ROUTINE routine_name   Pass control to the designated routine.

If neither level nor action is given, all severity codes are ignored.  If no
&SEVERITY directive is given, warnings are ignored and errors halt execution.


&SIGNAL condition [&NO_RETURN]

Raises the condition "condition" and causes the CPL mechanism to search for a
handler for that condition.  If &NO_RETURN is specified, execution of the
error-causing procedure cannot be resumed.


&STOP [severity] [&MESSAGE text]

Halts execution of procedure in which it occurs.  If this procedure is a rout-
ine, &STOP also halts the execution of the program containing the routine and
any of the other routines that program may have active.  Control returns to the
caller of the mail program.

If severity is present, specified severity code is returned to program's
caller.  Severity must be an integer.  If &MESSAGE is present, text is printed
at the caller's terminal.

_______________________________________________________________________________
$ 