_______________________________________________________________________________
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 bullshit. 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.
_______________________________________________________________________________
$