TOPS-20
Extended PROGRAMMABLE COMMAND LANGUAGE
USER'S GUIDE
AND
REFERENCE MANUAL
Ray SCOTT
Extensions by Michel E. DEBAR
12 January 1983
Copyright (C) 1983 Carnegie Mellon University Computation Center
FNDP Computing Centre, Namur Belgium
1. INTRODUCTION
1.1. Programmable Command Language
The PCL Extension to the TOPS-20 EXEC puts a language and executor into the
TOPS-20 EXEC. With this high level language and its extensions, users can
easily to write their own PCL programs which will will look like existing TOPS
commands complete with parameter substitution and TOPS-20 style recognition.
PCL is due to Ray SCOTT from Carnegie Mellon University Computation Center:
Carnegie-Mellon University,
Computation Center,
Schenley Park
5000 Forbes Avenue,
Pittsburgh PA 15213 (phone +1.412.578-26-42).
This manual describes an extended version of PCL, with extensions by Michel E
Debar: FNDP Computing Centre, Rue Grandgagnage, 21 B-5000 Namur Belgium (phone
+32.81.22-06-31, telex 59.222 Fac.Nam. B. Belgium).
You should consult the "TOPS-20 PROGRAMMABLE COMMAND LANGUAGE - User's Guide
and Reference Manual" from CMU for the complete documentation of the official
(non extended) version of PCL. (That manual is on our distribution tape in
<pcl5.doc>pcl.lpt. The present manual is in <pcl5.x-doc>pclx.lpt. )
1.2. PCL Uses
PCL may be used in a variety of different ways. Users might write friendly
front ends to existing programs. The command parsing with recognition makes a
very easy way to do parameter passing to a program. Periodic or repetitive
tasks can be coded in PCL routines which would reduce the amount of typing
needed to accurately execute all the steps necessary to complete a piece of
production.
PCL also will provide a means for implementing completely new functions which
are not possible in the current EXEC. For example, if the user has a graphics
terminal which takes special support then PCL can be used to provide new
support commands.
System administrators can tailor their EXEC to provide local commands that
override the function of standard commands. An administrator may wish to
eliminate the PLOT command if there is no plotter on the system.
1.3. PCL Features
The main features of PCL are:
- ALGOL-like language constructs
- string manipulation
- callable procedures with parameters
- system services
- flexible user interface
- program interface
- input/output capabilities
1.4. Notational conventions
In this document the format of commands is given using simple conventions:
- [...] is used to denote an optional item.
- "integer1 [,integer2 ...]" denotes one more integers, separated by
commas.
- {option1 | option2} denotes alternative items.
2. EXEC INTERFACE
PCL commands can be written with any text editor. The source for these
commands is stored in files with the default type PCL. Source files are
compiled into a command by the new EXEC command DECLARE . Once the command is
successfully compiled, it is stored in the EXEC and becomes a part of the list
of commands that the user has available during that job. If the DECLARE
command detects an error in the PCL source, an error message will be typed on
the terminal along with the line in error and a pointer indicating about where
the error occurred. Once an error is detected the compilation stops at that
point.
Any user command which has the same name as an existing command overlays the
existing command. The new EXEC command ORIGINAL may be used to execute any of
the standard EXEC commands. Commands may be removed with the UNDECLARE
command.
In addition to declaring PCL commands, the user may use the DECLARE command
to declare procedures which may be called from user commands, string variables,
and integer variables. One PCL source file may contain many command,
procedure, and variable declarations. The variables may be given values by
using the SET command with the new options STRING-VARIABLE or INTEGER-VARIABLE.
For example:
@SET STRING-VARIABLE myname (TO) scott
The string variable MYNAME may be accessed from any declared command or
procedure.
A new option to the INFORMATION command, the PCL-OBJECTS option, will show
the user all user defined commands, procedures, and variables.
@INFORMATION (ABOUT) PCL-OBJECTS
Commands: DRP, REMIND, NETMAILCHECK, DIALUPLINE, COURIER
Procedures: MATCH
Variables: String MYNAME, Integer MYJOB
Once the user has a set of procedures and commands defined, these may be
saved in an ENVIRONMENT using the ENVIRONMENT option to the new PRESERVE
command. To recall an environment, use the DECLARE command with the
ENVIRONMENT option. Commands and procedures in environment files are stored in
an internal format, so they are not recompiled when declared. The user may
declare multiple ENVIRONMENT files and the commands from each environment will
be added to the user's EXEC command list. Commands (re)defined are listed on
the user terminal unless you use the /NOCONFIRM option of DECLARE.
3. THE PCL LANGUAGE
3.1. General Command Format
The formal definition of a command is :
COMMAND name;
PCL statement
A simple example would be:
COMMAND simple;
Display "This is a simple command";
If the above 2 lines were in the file simple.pcl then
@DECLARE PCL simple.pcl
would enter the command simple into the users EXEC. If the user types:
@SIMPLE
at the "@" prompt then
This is a simple command
would be typed on the user's terminal.
The most general (and useful) simple definition of a command is:
COMMAND name;
Begin
[INTEGER, STRING and EXTERNAL declarations]
PCL-Statement;
[...;]
End
where any number of PCL statements separated by semi-colons may be between the
BEGIN-END pair. Note that all Integer, String and External statements must
appear before any other PCL statement.
Begin...End may be used to group any number of PCL statements into a single
statement. Note that braces {...} may be used in lieu of Begin..End:
if i > 100 then begin
display "Out of Range";
i = 50;
end;
Statement labels may be up to 40 characters long and are terminated with a
colon. Labels are used by the GOTO statement (see page 32) and by the parse
error handler (see page 11):
if i gtr 100 then goto horror;
...
Horror:
display "Can't proceed";
exit;
Comments may be placed anywhere in PCL source files.
Simple comments start with an exclamation mark and extend to the end of the
current line:
Display "Hi" + !This is a comment
" Mate";
Inline Comments are enclosed between !{...}!. They may appear in the middle
of a line, they may extend over several lines and they may be nested. Inline
comments are useful for commenting out large sections of code, long comments,
and in-line commenting:
!{ Ring the
terminal Bell }!
call $Jsys1 ( 8%74 !{pbout}!, 8%7);
3.2. PCL Constants
PCL knows of only two types of constants: integers and strings.
Integers are signed integers (expressed as 36 bit quantities). Integer
constants are of the form:
Format 1.
number
Format 2.
base%number
The first form is a number in base 10. The second form allows to enter numbers
in any base from 2 to 36. For bases higher than 10 the letters "a" through "z"
are used to enter the digits 10 through 35:
12 (decimal)
8%14 (octal)
16%C (hexadecimal)
8%777777777777 (actually -1)
The system procedures $string and $integer are used to convert numbers to
strings and back, with an optional radix.
Strings are of the form "string". They may be freely concatenated using the
"+" operator. Presently string constants are limited to 512 characters. String
variables do not have that restriction.
3.3. PCL Variables
PCL has two types of variables: string and integer variables. Variables may
be either local to a procedure or global.
Variables to be used in PCL commands must be declared at the beginning of the
command. For example:
COMMAND simple;
BEGIN
STRING name_in_full;
INTEGER count;
EXTERNAL INTEGER screen_size;
...
END
would define the local variables name_in_full (string) and count (integer), and
give the procedure access to a global variable screen_size (integer). Variable
names may be any combination of letters, numbers, and the under-score
character. Names may be up to 40 characters in length.
Variables may be assigned values using a simple assign statement.
COMMAND simple;
BEGIN
STRING name_in_full;
INTEGER count;
count = 3;
name_in_full = "J. Ray Scott";
...
END
Local variables are known only within the command or procedure in which they
are declared.
Global variables are known to any procedure which declares them external.
They may be manipulated either by PCL commands, or by the Exec commands:
@DECLARE INTEGER-VARIABLE or
@DECLARE STRING-VARIABLE (see page 25)
@SET INTEGER-VARIABLE or
@SET STRING-VARIABLE (see page 51)
@INFORMATION (about) VARIABLE variable_name
(see page 35)
If they are to be used by a specific set of library routines, it is best to
declare them as global variables in the PCL source file:
integer screen_size ! global variable
command set-screen;
begin
external integer screen_size;
...
end
3.4. Reserved names
PCL uses a number of reserved names which you may not use outside of their
normal context. For instance, you may not use them as variable names:
ABORT INPUT SYNONYM
ALWAYS INRANGE THEN
BEGIN INTEGER TIME
BINARY INVISIBLE TO
CALL INVOKE TOPROGRAM
CASE KILLPROGRAM TYPEIN
CLEARTYPEOUT LEQ UNTIL
COMMAND LET WHILE
DATE LSS WILD
DCM NEQ WORDS
DEFAULT NOECHO
DEFAULT_DEV NOHELP
DEFAULT_DIR NOINDIRECT
DEFAULT_EXT NOORIGINAL
DEFAULT_GEN NOP
DEFAULT_NAM NORETURN
DELETED OF
DISPLAY ORIGINAL
DO OTHERWISE
DOCOMMAND OUTPUT
ELSE PARSE
END PARSEONLY
EQL PASO
EXIT PASSOUTPUT
EXTERNAL PROCEDURE
FROM PROMPT
GEQ RADIX
GETTYPEOUT RETURN
GOTO SAVE
GTR SELECT
GUIDE SELECTALL
HELP STDHELP
IF STRING
3.5. String Manipulation
Strings may be concatenated using simple addition statements.
conc_string = "Welcome " + name_in_full
other_string = other_string + "appended text."
Substrings may be extracted from strings:
extr_string = conc_string[n:m]
where n is the starting character number and m is the number of characters to
extract. The leftmost character is character position 1. The user may use
th
[n:*] to extract from the n character to the end of the string.
The length of a string may be obtained using the $LENGTH system service.
count = $LENGTH(conc_string)
would assign the length of the string conc_string to the integer variable
count.
A PCL routine may search for a substring of a string by using the $SEARCH
system service:
count = $SEARCH(conc_string,"SCOTT")
would assign the starting location of the string SCOTT to count if it was found
in the string conc_string. If no match is found $search returns 0.
3.6. Logical expressions
Several PCL statements use logical expressions comparing integers or strings.
String comparison is based on the Ascii character sequence. So that "ABC" is
less than "ABD" for instance.
The syntax of a logical expression is:
operand1 logical-operator operand2
where:
operand1,operand2
are both integer expressions or both string expressions
operator
is one of:
- LSS or <
- LEQ or <=
- EQL or =
- NEQ or <>
- GEQ or >=
- GTR or >
3.7. Procedures
The format of a procedure definition in a source file is the same at that of
a command definition except that the word COMMAND is replaced with the word
PROCEDURE. A RETURN statement will return to the calling PCL routine.
PROCEDURE doit;
Begin
...
Return
End
To use the procedure DOIT in a command it must be declared and then called.
COMMAND callit;
Begin
EXTERNAL PROCEDURE doit;
...
CALL doit;
...
End
Parameters to procedures are declared by placing the list of parameters in
parenthesis after the procedure name. The parameters must be typed, i.e., they
must be specified as being either integers or strings.
PROCEDURE doit (INTEGER para_1,para_2; STRING para_1);
Procedures may have a type and thus return a value. To have a typed
procedure the word INTEGER or STRING is placed in front of the PROCEDURE
keyword in the source file. The value to be returned is placed after the
RETURN. This may be any expression of the appropriate type.
INTEGER PROCEDURE upone (INTEGER in);
RETURN in+1
Procedures may modify their arguments (they are Input and Output formals):
PROCEDURE CAT (string s1,s2,s3);
s3 = s1 +s2;
3.8. PCL Flow Control
PCL provides several ways to control the sequence of execution:
- ABORT
- EXIT
- RETURN
- DO, WHILE, UNTIL
- IF ... THEN ... ELSE ...
- CASE
- SELECT
- GOTO
3.8.1. ABORT
Abort stops the execution of a PCL command and returns at Exec command level
after printing an error message preceded by "?". See page 18.
3.8.2. EXIT
Exit stops the execution of a PCL command without printing any message. see
page 29.
3.8.3. RETURN
Return exits from the current PCL procedure and returns to its caller. If
used in a command RETURN acts as EXIT.
3.8.4. DO, WHILE, UNTIL
DO, WHILE, and UNTIL are available for program loops. These may be used in
the following combinations:
1. DO PCL statement WHILE logical expression
2. DO PCL statement UNTIL logical expression
3. WHILE logical expression DO PCL statement
4. UNTIL logical expression DO PCL statement
...
i = 3;
do begin
display i;
i = i - 1;
end
until
i eql 0;
3.8.5. IF
The IF statement will execute a PCL statement if the condition is true. IF
may have an ELSE clause.
IF str_val = "xyz" THEN
PCL statement
ELSE
PCL statement
3.8.6. CASE
The case statement provides a method of selectively executing PCL statements
depending on the value of an integer variable. The variable value is tested for
a match with specified constants. If a match is found the corresponding PCL
statement is executed:
CASE count FROM 1 to 10 of BEGIN
1,2 : BEGIN ... END;
3 TO 6, 10 : BEGIN ... END;
5 : BEGIN ... END;
INRANGE : BEGIN ... END
OUTRANGE : BEGIN ... END
END
3.8.7. SELECT
The SELECT statement is similar to the CASE statement. Instead of choosing
among a set of integer values in a range, SELECT chooses among arbitrary
expressions. The expression and the test values must be of the same type,
either integer or string.
SELECT str_var of BEGIN
"abc" : BEGIN ... END;
"xyz" : BEGIN ... END;
OTHERWISE : Display "Not found"
END
In the above example. If str_var contains the string abc then the statements
in the BEGIN-END pair after "abc": will be executed. If str_var is neither abc
nor xyz then the OTHERWISE clause will be executed, in this case it will
display
Not found
on the terminal and proceed to the next PCL statement after the SELECT
statement.
3.8.8. SELECTALL
The SelectAll statements is basically similar to Select, except that after
executing one case it goes on to try to find more matches:
SELECTALL int_var of begin
1,3 : display "1 or 3";
2,4 : display "2 or 4";
1 TO 2 : display "1 or 2";
ALWAYS : display "Always";
OTHERWISE : display "Neither 1,2,3,4";
end;
If Int_var is 2, this will display "2 or 4", then "1 or 2" and "always".
ALWAYS always gives a match, OTHERWISE matches only if no previous case matched
(for instance if int_var is 5).
3.8.9. GOTO
The GOTO PCL statement causes an unconditional transfer to a label.
COMMAND xfer;
BEGIN
...;
loop1:
...;
GOTO loop1;
...
END
4. SYSTEM SERVICES
Various system services are provided to return specific system information or
perform system functions.
4.1. System Constants
PCL provides pre-defined constants that are useful in writing PCL routines,
or necessary to specify the arguments to some PCL system procedures.
$Append INTEGER - An option to $OPEN for append mode.
$Cr STRING - Contains just a carriage return.
$Crlf STRING - Contains a carriage return and a line feed.
$Input INTEGER - An option to $OPEN for input mode.
$Lf STRING - A string containing a line feed.
$Nul STRING - Read/write string like NUL:, returns a null string.
$Output INTEGER - An option to $OPEN for output mode.
$Parse INTEGER - Specifies the file currently parsed for the
$File_Dev, $File_Dir, $File_Dir, $File_Nam, $File_Typ,
$File_Gen, $Fileinfo_I, $FileInfo_S and $FileSet system
procedures (see page 8).
$Quote STRING - A string containing a double quote character.
Other constants are provided by PCL specifically to ease the use of certain
system procedures: see pages 8, 8.
4.2. System Variables
Some system procedures look like variables and may be used in most statements
where PCL allows to use a variable. Some of these variables may be changed by
the user (eg the prompts).
The restrictions on the use of system variables are:
- they may not be used as the arguments to PARSE options:
PARSE (KEYWORD (WORDS(...),
DEFAULT $ConnectedDirectory ));
is wrong and must be replaced by
mydir = $ConnectedDirectory;
PARSE (KEYWORD (WORDS(...),
DEFAULT mydir));
- a string system variable may not be used as argument to $Strloc.
Most of these restrictions are NOT detected when you declare a PCL statement,
but their violation leads to wrong behaviour when executing the command.
The system service variables are:
$Ac1, $Ac2, $Ac3, $ac4
INTEGER - Contain the first four register values after the last
$Jsys executed.
$Account STRING - The account of the current job.
$ARPAnet_Node STRING - The system's ARPAnet node name. This is a null string
if the system is not on the ARPAnet.
$Atom STRING - After a PARSE statement, contains the text typed in
for most parse types (all but Noise, EOL, Comma, and Token.)
$Batch_Job INTEGER - Non-zero if the job is a batch job.
$Command STRING - Contains the complete text of the last command parsed,
or of the current command up to the last field parsed with a
PARSE PCL statement.
$ConnectedDirectory
STRING - The name of the currently connected directory
$Curtad INTEGER - The current date and time in system internal format.
(Date and Time: Tops 20 stores dates and time internally in a
single integer with in the left half the day counted since the
18th of November 1858, and in the right half the fraction of
the day elapsed since midnight. The fraction is the numerator
of a fraction that has a denominator of 2**18. When entering a
date and time into Tops 20, all usual formats are valid: 3-DEC-
83, 03/DEC/83, 08:51, 16:50, 4:50PM, etc. The system routines
$Curtad, $Date, $InputTad, $OutputTad, $ExpandTad and $MergeTad
deal with dates and times. )
$Date STRING - Current date in DD-MON-YY format
$DECnet_Node STRING - The system's DECnet node name. This is a null string
if the system is not on a DECnet.
$Directory STRING - After executing a parse of Directory(ies) with PARSE
DIRECTORY or DIRECTORYLIST, contains the name of the current
directory parsed, including the angle brackets ("<...>"). (see
page 10).
$EMACSTerminal INTEGER - Returns a 1 if the current terminal can be
"effectively" used by EMACS, 0 if not. [CMU and sites who
customize PCL only].
$FileL STRING - After executing a PARSE FILE statement or some similar
PARSE (INPUTFILE, OUTPUTFILE, FILELIST), this contains the file
name entered in the longest form,
DEV:<DIRECTORY>FILE.EXT.VERSION
$FileN STRING - After parsing a filename this contains the file name
entered in the normal form, FILE.EXT.VERSION
$FileS STRING - After parsing a filename this contains the file name
entered in the form FILE.EXT. It will contain device: and
<directory> if they are different from the connected device and
directory.
$FileV INTEGER - After parsing a filename this contains contains just
the generation number as an integer variable
$JobNo INTEGER - The number of the current job
$JsysOk INTEGER - Set to 1 when $Jsys succeeds, to 0 when it fails.
$LastErrCode INTEGER - The number of the last JSYS error
$LastError STRING - The text of the last JSYS error
$PromptEnb STRING - The standard enabled prompt string, may be changed.
$PromptEnbSub STRING - The standard enabled subcommand prompt string, may be
changed.
$PromptReg STRING - The standard prompt string, which may be changed if
the usual "@" is not suitable:
$PromptReg = "Tops20>";
$PromptSub STRING - The standard subcommand prompt string, may also be
changed.
$TermNumber INTEGER - The number of the controlling terminal
$TermWidth INTEGER - The terminal width of the controlling terminal.
$TermLength INTEGER - The terminal length of the controlling terminal.
$Time STRING - Current time in HH:MM:SS format.
$TType INTEGER - The terminal type index (GTTYP%) of the controlling
terminal.
$Typeahead_Count
INTEGER - The number of characters which have been typed-ahead
on the controlling terminal.
$User STRING - After parsing a user name with PARSE USER or USERLIST
this contains the current User Name parsed, (without angle
brackets "<...>"). (see page 10).
$UserName STRING - The user name of the current job
$Value INTEGER - Contains a number returned by a Parse: The number
typed in for a Number field, the value for a Keyword or Switch,
or the internal date and time for a DayTime.
$Xatom STRING - Contains the atom parsed by the last PARSE statement.
Note that when parsing a Filelist, DirectoryList or UserList,
this does not contain the whole field but only the last atom
actually parsed by the Comnd JSYS.
4.3. System Procedures
PCL provides pre-defined procedures. Some are typed procedures and therefore
may be used like variables in PCL statements. Others return their results in
parameters. In the following list of system procedures, if a procedure returns
a value then STRING or INTEGER precedes the description, otherwise we indicate
PROCEDURE. A simple procedure that does not return a value must be called:
CH = $OPEN ("TEST.DAT", $INPUT);
...
CALL $CLOSE (CH);
$And (int1, int2)
INTEGER - Returns the bitwise AND of the integers int1 and
int2.
$Close (channel)
PROCEDURE - Closes the file that is open on Channel.
$CvItC (integer)
STRING - Returns the character whose value is equal the
Integer. This is useful for manipulating control characters.
$CvCtI (string) INTEGER - Converts the first character in String into an
integer. This is useful for control character manipulation.
$DirectoryInfo_I (directory, code)
INTEGER -
$DirectoryInfo_S (directory, code)
STRING - $DirectoryInfo_I and $DirectoryInfo_S return integer
or string information that may be obtained using the GTDIR or
GTDAL JSYS's (refer to the Tops 20 Monitor Calls Reference
Manual for more details). Directory is the directory name
(string). The CRDIR directory block layout is reproduced in
appendix II.
$DirectoryInfo_I returns an integer. It admits the following
values for Code:
$CDDFE default off-line expunge date and time (-- not
yet implemented in tops20 v5 --)
$CDDNE -- not yet implemented in tops20 v5 --
$CDDPT directory protection
$CDFPT default file protection
$CDLEN default on-line expiration date (-- not yet
implemented in Tops 20 V5 --)
$CDLIQ working disk quota
$CDLLD date last login
$CDLOQ permanent disk quota
$CDMOD directory mode word
$CDNUM directory number
$CDPRV capabilities word
$CDRET default number of generations to keep
$CDSDQ maximum number of subdirectories
$CDUSD Disk space used (as returned by the GTDAL Jsys,
and usually not correct under Tops20 V5).
$DirectoryInfo_S returns a string. It admits the following
values of Code:
$CDCUG subdirectory groups
$CDDAC default account string
$CDDGP directory groups
$CDPSW password string
$CDUGP user groups
The user/directory groups and the subdirectory groups are
returned as a string with all the group numbers separated by
commas. For example:
! User groups
display $directoryinfo_s ("<DOE>", $CDUGP);
! Default account
display $directoryinfo_s ("<DOE>", $CDDAC);
! Protection
display $string ( $Directoryinfo_I("<DOE>", $CDDPT), 8);
Presently there is no $DirectorySet function in PCL.
$Eof (channel) INTEGER - Set to -1 if a $READ reaches an end of file on
Channel, otherwise returns 0.
$ExpandTad (idate, year, month, day of month, day of week, hour, minute)
PROCEDURE - Converts the date and time held in internal format
in Idate into 6 integers representing the year, month, day of
month, day of week, hour and minute. The converse is done by
$MERGETAD.
$File_Dev (fil) STRING
$File_Dir (fil) STRING
$File_Nam (fil) STRING
$File_Typ (fil) STRING
$File_Gen (fil) STRING - $File_Dev through $File_Gen return the part of the
file name of Fil expressing respectively the Device, Directory,
Name, Type and Generation. Fil may be either $parse, or a
channel number, or a file name (see $FileInfo_S 8).
$FileInfo_I (fil, code)
INTEGER
$FileInfo_S (fil, code [,format])
STRING - $FileInfo_I and $FileInfo_S return information about
a file. The file is selected by Fil and the information to
return is selected by Code.
Fil may be:
$Parse the file currently being parsed by a PARSE FILE
or PARSE FILELIST,
a channel number
for a file currently opened by a call to $open,
a filename The filename is given as a string. If some
parts of the file name are omitted they default
to the connected device and directory, null
file type, and highest existing generation. The
name itself may not be defaulted.
$FileInfo_I returns an integer from the file FDB (File
Descriptor Block). For $FileInfo_I code is the index of the
word requested in the FDB (File Descriptor Block). See the
Tops20 Monitor Calls Reference Manual for details. Appendix I
gives the layout of the FDB. PCL constants are provided for
all permissible codes:
$FBADR disk address of file index block
$FileAddress idem
$FBBBT size file had when deleted from disk (in pages)
$FBBK0
$FBBYV file i/o information
$FBCNT count of read/write of the file
$FBCRE date last written either by user or system
("system" write date)
$FileCreation idem
$FBCRV creation date
$FBCTL control word
$FileControl idem
$FBFET off-line expiration date
$FBGEN generation and directory numbers
$FBNET on-line expiration date and time
$FBPRT file access codes
$FileProtection idem
$FBREF date last read
$FileRead idem
$FBSIZ number of bytes in file
$FileSize idem
$FBTDT date file was last written to tape (archiving)
$FBUSW user settable word
$FBWRT date last written by the user
$FileWrite idem
$FileInfo_S returns a string from information pointed to by the
FDB, or the result of a JFNS Jsys call, with specific
formatting bits given by Format (Refer to the Tops 20 Monitor
Call Reference Manual for details): The values of Code for
$FileInfo_S are either FDB offsets, or special values
requesting a specific function):
$FBACT file account
$FileAccount idem
$FBAUT file author
$Author idem
$FBFMT specifies that $FileInfo_s must return the
result of a JFNS Jsys, using the format bits
specified in Format. (An obsolete format of
$FileInfo_S specified that if code was an
integer greater than 63 the result was the
string returned by a JFNS Jsys with the
formatting parameter set to the field code
minus 64.)
$FBLWR last writer of file
$Writer idem
$FileSet allows to change the information read by $FileInfo_I
and $FileInfo_S.
$FileSet (fil, code, mask, value)
PROCEDURE - $FileSet allows to set the information contained in
the FDB (for a complete explanation of the File Descriptor
Block, refer to the Tops20 Monitor Calls Reference Manual).
Presently, features relating to the Archiving system are not
implemented.
Fil is selected as for $FileInfo: $Parse, or channel number, or
filename (see page 8).
Code defines which entry of the FDB we want to change.
Permissible values are the same as for $FileInfo (see page 8).
It is the FDB offset of the entry that we want to modify (see
the list of codes page 8, and appendix I for a description of
the FDB). If the entry is a pointer to a string, the
information to be changed is the string itself, not the
pointer.
Mask is an integer indicating the bit positions that we want to
change. It must contain ones in all positions to be changed. If
the information to be changed is a string, this argument is
ignored.
Value is either an integer or a string, depending on the
information to be changed.
For example:
! Change account
call $FileSet ($parse, $FBACT, -1, "OVERHEAD");
! Zero Read count of File
call $FileSet ("test.pcl", $FBCNT, 8%777777, 0);
$FileInfo_I and $FileInfo_S read the information that may be
changed with $FileSet.
Several fields of the FDB may not be changed, or only
with certain capabilities.
The information in the FDB that is modified by the ARCF
and SFTAD Jsys's is not currently changeable with
$FileSet.
$GetField (ival, pos, wid)
INTEGER - Returns the Wid bits found at bit positions Pos+1 to
Pos+Wid in ival (numbered 0..35 from right to left), stored
right justified in an integer and filled with zeroes to the
left. For example, $Getfield(ival,18,18) returns the left half
of ival. Ival, Pos and Wid are integers. See $SetField for
the reverse operation.
$InputTad (string)
INTEGER - Converts a string time and date into internal format.
The converse is done by $OutputTad.
$Integer (string [,radix])
INTEGER - Converts decimal number in string into an integer.
An optional second argument (integer) gives the radix to be
used (2 to 10). Returns 0 on an error.
$IsFile (fil) INTEGER - Returns 1 if the file specified by Fil exists,
otherwise returns 0. Fil is specified as for $FileInfo:
$Parse, or a channel number, or the file name.
$Length (string)
INTEGER - Returns the length of string
$MergeTad (year,month,day of month,hour,minute)
INTEGER - Returns the conversion to internal date and time
format of the date expressed by the five integers Year, Month,
Day of month, Hour, Minutes. The converse is done by
$ExpandTad.
$NextDirectory INTEGER - Used to step to the next directory when parsing a
DirectoryList or Directory with Wild turned on. Returns zero at
the end of the list, and nonzero otherwise. (see page 10).
$NextFile INTEGER - Used to step to the next file when parsing a FileList
or File with Wild turned on. Returns zero at the end of the
list, and nonzero otherwise.
$NextUser INTEGER - Used to step to the next User when parsing a UserList
or UserName with Wild turned on. Returns zero at the end of the
list, and nonzero otherwise. (see page 10).
$Open (string, mode)
INTEGER - Opens the file named in the string for I/O, in the
mode specified by the integer mode (either $Input, $Output, or
$Append). Returns the PCL channel number assigned, or zero if
the open could not be done.
$Or (int1,int2) INTEGER - Returns the bitwise OR of the integers int1 and int2.
$OutputTad (integer)
STRING - Convert internal date and time to string. The
converse is done by $InputTad.
$Read (channel) STRING - Reads a record from the file opened for input on
Channel.
$ReadBinary (max, string [,timeout])
STRING - Reads from the terminal, in binary, up to Max
characters or until the character specified in String is read.
This will time out and return an empty string if nothing is
typed within a second. The optional integer argument Timeout
can be used to provide the number of milliseconds to use for
the timeout period. This is useful for reading control
information transmitted by the VT100 terminal in response to
requests such as "send terminal model ID" and "send cursor
position."
$Search (string1, string2 [,start])
INTEGER - Searches the String1 for String2 and returns the
position in String1 of the first character of the first
occurence of String2. If not found, returns 0. The optional
integer argument Start gives the character position at which
the search starts.
$SearchRaised (string1, string2 [,integer])
INTEGER - Same as $SEARCH except lower case alphabetics are
raised to upper case.
$SetField (field, word, pos, wid)
INTEGER - Returns the integer Word with the rightmost Wid bits
of Field stored in the bit positions Pos+1 to Pos+wid (numbered
0..35 from right to left). For example:
I = $SETFIELD(123,8%777777777777,3,9)
returns 777777771237 (displayed in octal)
$String (integer [,radix])
STRING - Converts the integer into a string. Radix is
optional. It gives the radix to be used (2 to 10). If omitted
the integer is expressed in decimal. If the radix is other
than 10, the number is output as unsigned:
display $String(-1) displays -1
display $String(-1,8) displays 777777777777
$Wait (integer) PROCEDURE - Waits the specified number of milliseconds, or
forever if zero.
$Write (channel,record)
PROCEDURE - Writes the string Record into the output file
opened on Channel.
4.4. System Procedures specific to $Jsys Interface, memory management
A JSYS interface is provided in PCL extended. It gives facilities to set/read
the registers, set/read argument blocks. The routines in this section should be
considered provisional; there will be changes for instance if vectors are
implemented.
$Get_Mem (size) INTEGER - Acquires Size words from dynamic memory (actually PCL
string space), and returns the address of the first word. When
referencing dynamic memory with $Iget, $Iput, $Sget and $Sput
the first word has index zero, not one. The memory is zeroed
before you get it.
$Ret_mem (address, size)
PROCEDURE - Frees the memory at Address. Size should be the
same as given when the memory was acquired by "address =
$get_mem (size)".
$Iput (value, address [,index [,count]])
PROCEDURE - Sets count words starting at Address+Index to the
integer Value. This is used to store integers in dynamic memory
acquired through $Get_Mem. Index starts at 0 and defaults to
0. Count defaults to 1.
$Iget (address, [,index])
INTEGER - Returns the value stored at Address+Index. Index is
expressed with zero base, and defaults to 0.
$Sput (string, address [,index [,charpos]])
PROCEDURE - Stores the asciz String starting at the character
in char position Charpos (counted from 0) in the word at
Address+Index (Note that Index starts at zero). If Charpos, or
both Charpos and Index, are omitted, they default to zero.
$Sget (address, [,index[,charpos]])
STRING - Returns the asciz string starting at the character in
position Charpos (counted from zero) in the word at
Address+Index. If Charpos, or both Charpos and Index are
omitted, they default to zero.
$Jfn (channel) INTEGER - If Channel is > 0 and a file is currently associated
with that channel ( see page 13), return the jfn associated
with it.
If Channel is < 0 return the Indexable File Handle associated
with the current parse: if the PARSE used the WILD option the
flag bits are returned in the left half, and the jfn in the
right half, otherwise only the JFN is returned.
$Jsys (jsys [,ac1 [,ac2 [,ac3[,ac4]]]])
INTEGER - Executes the jsys number Jsys with the contents of
the registers defined by the optional arguments Ac1 through
Ac4. Returns 1 for success, and 0 for failure. The success
indicator is also stored in the system variable $Jsysok. After
execution, the registers 1 through 4 are stored in the system
variables $Ac1 through $ac4.
$Jsys1 (jsys [,ac1 [,ac2 [,ac3[,ac4]]]])
PROCEDURE - Totally similar to $Jsys, except does not return a
value.
$Strloc (string)
INTEGER - Returns the actual memory address of a string primary
(ie a string constant or a string variable). This may not be
used with string expressions or with strings returned by a
system procedure:
mydir = $connectedDirectory;
i = $strloc (mydir); ! Is Legal
i = $strloc ($ConnectedDirectory); ! Is Wrong
5. USER INTERFACE
Parameters are often passed to commands from the terminal, just like normal
Exec commands. PCL allows the user to specify such parameter parsing using the
same monitor call as the Exec uses, so the user is able to write commands which
look like standard Exec commands.
When creating commands, it is easiest first to parse all the parameters and
to store them in appropriate variables, then to parse the end of the line to
allow the user to confirm the command, and only then to perform the actions
which comprise the command. It is possible, using the COMND% JSYS, to make
programs which parse a few arguments, do some irreversible action (such as
deleting a file), and then parse a few more arguments; such programs upset
users who, for instance, type ^U while entering those last parameters, since
the program has already deleted the file. PCL enforces and encourages the more
desirable mode of operation, in part by performing an assumed End-of-line Parse
before performing major actions such as DoCommand.
Command parsing is done a line at a time, where the user types a line and the
program parses it. This means that once a line has been confirmed with an End-
of-line Parse, no more fields can be parsed with the Parse statement, since
there is no command line to parse from. The Prompt statement can be used to
allow the user to enter another line to be parsed; see Prompt on page 47.
If a PCL command contains none of the three forms of command parsing, it is
built as if it started off with an End-of-line Parse.
The Complete description of the PARSE statement is given page 42.
5.1. Parse Formats
There are three ways to cause PCL to parse such parameters; in each case the
user specifies what type of parameter is expected, and PCL parses it from the
command line and delivers it to the PCL command.
5.1.1. Simple PARSE
The simple PARSE statement may be placed anywhere within the command.
COMMAND getarg;
BEGIN
INTEGER repeat_count;
...;
PARSE NUMBER;
repeat_count = $VALUE;
...;
PARSE EOL;
...
END
would parse for a number, store it in a variable for use, execute some more PCL
statements, and then parse for a carriage return. The PARSE statement would
store the value that the user entered in the system variable $VALUE.
5.1.2. Complex PARSE
The complex parse provides a way for one PARSE statement to parse for any one
of several parse types. The syntax of this form of PARSE looks very much like
the SELECT verb.
COMMAND CMPLX;
BEGIN
...;
PARSE
BEGIN
NUMBER: BEGIN ... END;
EOL : BEGIN ... END
END;
...
END
This would allow the user to enter either a number or a carriage return; the
corresponding statements (enclosed in BEGIN - END) would be executed depending
on which field type matched the user's input. In either case more information
would be available from variables like $VALUE.
5.1.3. Command Arguments
An easy way to specify the arguments is to use command arguments. These must
be specified in the command declaration (the statement with the keyword COMMAND
and the name of the command). The user specifies the type of parameter to be
parsed and the variable to store the result into (see page 24 for details).
The variable must not be declared later; the use in the command arguments
completely declares the variable.
COMMAND AllAtOnce (NUMBER:count);
BEGIN
!No INTEGER declaration necessary
DISPLAY $STRING(count)
END
5.2. Parse Options
In each of these 3 methods, the user may specify options to the parse type.
Parse options are enclosed in parentheses immediately after the parse type.
There are many options that the user can specify, e.g. the default value to
use if the user skips this parameter or a help message to type if the user
enters a question mark at the parameter. The parse options available vary with
the parse type.
COMMAND optn
BEGIN
...;
PARSE NUMBER (Help "Value of count", Default "2");
| | |
| ----> Parse options <----
--> Field type
...
END
If the user DECLARES this command and then types:
@optn ?
at the "@" prompt, the system will respond:
Value of count
as it would in any EXEC command. If the user skips the field by typing:
@optn<return>
at the "@" prompt or if the user uses ESCAPE to complete the command then the
PARSE will return the default value, in this case 2.
5.3. Parse Results
The results of each Parse are returned by PCL in several system variables:
$Xatom returns exactly the Atom parsed (i.e. what the user typed,
eventually completed by the user hitting the ESCape key). This
field is not correct for the parsing of field types FileList,
DirectoryList and Userlist.
$Command holds the text of the complete command up to the point reached
in the current parse.
$Value returns an integer result if necessary, for example after
parsing a number or a keyword (see page 42).
$Atom returns a string result if necessary, for example after parsing
a token (see page 42).
5.4. FILELIST
One powerful extension to PARSE is the FILELIST option. This allows the user
to parse for file names which may contain wild cards, be separated by commas,
or both. The name of the first file which matches the specification that the
user entered is returned in the system variables $FileL, $FileN, $FileS,
$FileV. Successive file names may be returned by using the $NEXTFILE system
service procedure: $NextFile returns zero when the list of files has been
exhausted, and returns nonzero otherwise.
COMMAND ALLFILES;
BEGIN
GUIDE "Files";
PARSE FILELIST;
DO
DISPLAY $FILEL
UNTIL $NEXTFILE EQL 0;
END
The user may type:
@allfiles ABC.*,XYZ%Y.*,A.Z
The first file that matches the specification of ABC.* will be returned. For
each call to $NEXTFILE the system will return file names that match the wild
cards until all that match ABC.* have been exhausted . Next, it will look for
files that match XYZ%Y.*. Finally, it will return the file name A.Z.
FILELIST may only be specified once per command and it may only be in a
simple parse.
Note that the same effect may be achieved by using the WILD option when
parsing a FILE field type, with the restriction that only one specification
(containing wildcards) may be given. In the above example, "PARSE FILELIST"
would be replaced by "PARSE (FILE (WILD))".
5.5. DIRECTORYLIST, USERLIST
DIRECTORYLIST and USERLIST are extensions allowing to parse lists of
Directories of lists of Users (login directories), using wildcard input in the
way of FILELIST. The successive Directories or Users are returned in the
variables $DIRECTORY and $USER . Successive directories or users are returned
by using the $NEXTDIRECTORY or $NEXTUSER integer system procedures. When the
list has been exhausted these return 0, otherwise they return nonzero.
COMMAND ALLUSERS;
BEGIN
PARSE USERLIST;
DO
DISPLAY $USER
UNTIL $NEXTUSER EQL 0;
END;
The user might type in:
@allusers info.1lic.*,info.2lic.*
or
@alldirectories <info.1lic.*>,<info.2lic.*>
Directory names must be given with the "<...>" (angle brackets), while user
names may not include them.
Only one of either DirectoryList or UserList may be specified per command,
and it must be in a simple parse.
Note also that a similar effect may be achieved by using the wild option when
parsing a field of type DIRECTORY or USERNAME. However, in this case, only one
specification with wildcards may be entered:
COMMAND ALLDIRECTORIES;
BEGIN
PARSE (DIRECTORY (WILD));
DO
DISPLAY $DIRECTORY;
UNTIL $NEXTDIRECTORY EQL 0;
END;
5.6. Parse error handling
Errors found during parsing are handled differently depending on which type
of parse was executed. In command arguments, the user can specify a label to
branch to by using the ERROR parse option. This is only available for command
arguments. The command will begin execution at that label if the user entered
something which was not legal for the specified parse type.
COMMAND oops (NUMBER(ERROR notnum) : count)
...;
notnum:
...
In simple parsing, the command is terminated and the standard error message
for that parse type is displayed at the terminal. In complex parsing, the user
may have an OTHERWISE parse option which will be executed if the parse fails.
COMMAND CMPLX;
BEGIN
...
PARSE BEGIN
NUMBER: BEGIN ... END;
EOL: BEGIN ... END;
OTHERWISE: BEGIN
Display "Error in parameter";
Exit
END
END;
...
END
6. PROGRAM AND COMMAND INTERFACE
6.1. Running Programs
The INVOKE PCL statement runs a program much like the EXEC run command does
now. The PCL command continues to execute when the program has started. If
the PCL routine exits, the program is left in a ^C state. INVOKE takes a
string argument which contains the name of the program to run. The TYPEIN PCL
statement "types" characters into the program. When a TYPEIN is executed, the
PCL command will wait until the program goes into terminal input wait. It will
then send the characters to the program and continue to execute PCL statements.
The GETTYPEOUT statement is used to return the data that the program would have
typed on the terminal, placing it in the string that the user specifies.
GETTYPEOUT will get all characters since the INVOKE or since the last
GETTYPEOUT. The PASSOUTPUT option to the INVOKE statement causes all of the
data from the program to go to the controlling terminal. The CLEARTYPEOUT
command will throw away all the program type out that has accumulated. This
may be used in place of a GETTYPEOUT to get rid of unwanted startup messages
from programs.
COMMAND prog;
BEGIN
STRING prog_data;
...;
INVOKE "payrol.exe";
CLEARTYPEOUT;
TYPEIN $DATE; $DATE is a system service
GETTYPEOUT prog_data;
DISPLAY prog_data;
...
END
6.2. Executing EXEC Commands
The DOCOMMAND PCL statement takes a string argument and performs the EXEC
command that is in the string.
COMMAND whome;
DOCOMMAND "systat " + $UserName;
After typing whome at the "@" prompt the user would see:
Job Line Program User
30* 44 SYSTAT JS5A
at the terminal. The output from the command is displayed on the terminal
unless the optional TO parameter is specified. In this case the type out from
the command is placed in a string specified by the user:
DOCOMMAND "systat all" TO exec_string
To execute a command and ignore the output, do:
DOCOMMAND command TO $NUL;
7. INPUT/OUTPUT
PCL provides simple file manipulation facilities. Up to 36 files may be
opened in input, output, or append mode. Only record level reads and writes
are possible. A record is terminated by a carriage return/line feed pair. The
$OPEN system service takes the name of the file and whether it is to be opened
for input, output, or append access. $OPEN returns the PCL channel number to
be associated with the file. If the file does not exist and you open it for
Input, $open returns 0 for the channel number; otherwise the channel is a
positive integer.
channel = $OPEN("mail.txt",$INPUT)
The string procedure $READ takes a channel number as argument and returns the
next record in the file. $WRITE takes a channel number as the first argument
and a string as the second argument, and writes the string to the file.
In_record = $READ(channel1);
Call $WRITE(channel2,in_record);
The user may test for end of file by calling the $EOF system procedure. If a
$READ reaches the end of file, then $EOF will return -1, otherwise it returns
zero. $EOF takes the channel number of the file as an argument.
Files may be closed with the $CLOSE call. $CLOSE takes the channel number of
the file to close. It may not be necessary to close files open for input, as
they will be closed automatically at the end of the PCL command.
8. REFERENCE
EXPRESSIONS
8.1. EXPRESSIONS
Expressions are the fundamental arithmetic, string, and logical entities of
the PCL language.
8.1.1. Integer expressions
Integer expressions are composed of integer constants, integer variables, and
integer procedure calls, operated on by arithmetic operators. PCL has the
usual operators for addition, subtraction, multiplication, and division, with
the usual precedence rules, and allowing the use of parentheses to add to the
default precedence.
count*(shift+1) + offset(commandstring)
8.1.2. String expressions
String expressions and likewise composed of string variables, string
constants, and string procedure calls, operated on by operators. The string
operators are concatenation (indicated by the "+" symbol) and substring
extraction (indicated by square brackets). Concatenation takes two strings and
generates a new string from them. Substring extraction looks like
substring = str[start:count]
where start is the location of the first character to extract, and count is the
number of characters to extract. An asterisk can be used for the count to
extract to the end of the string.
8.1.3. Logical expressions
Logical expressions are only used to control conditional statements; there
are no logical variables. Logical expressions are generated from typed
variables, constants, or procedure calls (either integer or string), compared
with relational operators: "<", "<=", "=", "<>", ">=", and ">". The
relationals "lss", "leq", "eql", "neq", "geq" and "gtr" may be used
alternatively.
if my_dir eql $connectedDirectory
...
if count <= 20
...
STATEMENTS
8.2. STATEMENTS
Statements are the fundamental execution entities of the PCL language. They
may be grouped together to form a compound statement, by enclosing them in a
BEGIN/END pair, and separating them by semicolons. Anywhere that the
documentation for a statement says that a statement may be used, a compound
statement may be used just as well.
IF i EQL 0
THEN
BEGIN
j=6;
k=10
END
ELSE
j=0
Braces may be substituted for BEGIN ... END:
if i eql 0 then {
begin
j=6;
k=10
}
else
j=0
PCL FILES
8.3. PCL files
A PCL file contains PCL declarations for commands, procedures and variables,
as well as PCL statements like NOORIGINAL and SYNONYM. PCL files are compiled
using the Exec DECLARE PCL-ROUTINES command.
The structure of a PCL file is:
declaration [; declaration ...]
where:
declaration is:
command-declaration or
procedure-declaration or
variable-declaration or
NOORIGINAL command or
SYNONYM command
A command declaration declares a PCL command. It is described in 8.10, page
24. Within a command declaration, we find declarations of local variables and
the code to execute the command.
A procedure declaration declares a PCL procedure for use by other PCL
commands and procedures (see page 46). Its contents are similar to those of a
command.
A variable declaration declares global PCL variables, either integers or
strings. These variables will be available to all PCL commands and procedures,
with the EXTERNAL declaration.
The NOORIGINAL command removes an original Exec command (see page 40).
The SYNONYM command declares a synonym to an existing command (see page 52).
ABORT
8.4. ABORT
Function
The ABORT PCL statement will abort a PCL execution with an error message
typed to the user.
Format
ABORT string
Notes
1. The string error message will be typed on the terminal, preceded by
"?".
Example
COMMAND ohdear;
BEGIN
...;
IF $LENGTH(input_line) > 120 then ABORT "Line too long";
...
END
Related
EXIT - page 29
RETURN - page 48
ASSIGNMENT
8.5. ASSIGNMENT
Function
The assignment statement generates a value and deposits it in a variable.
Format
variable name = expression
Notes
1. The expression must be either integer or string, depending on the
type of the variable.
Example
COMMAND look;
BEGIN
...;
target_user = $Atom;
...
END
Related
Expressions - page 15
BEGIN - END
8.6. BEGIN - END
Function
BEGIN is paired with an END to group several PCL statements into one
statement.
Format
BEGIN
PCL statement;
...
END
or
{ PCL statement;
...
}
Notes
1. Every BEGIN must have a corresponding END.
2. A BEGIN/END pair may enclose any number of PCL statements. Anywhere
a PCL statement is called for, a BEGIN/END grouping may be
substituted.
3. It is not necessary to have a semicolon following the final PCL
statement before the END. If present, a null statement is formed
which will not affect the execution of the PCL command.
4. Begin...End may be replaced by {...}.
Example
If $JOBNO > 6 then BEGIN
Display "Job number greater than 6";
A = 5;
name = "Scott";
END
Related
CALL
8.7. CALL
Function
The CALL PCL statement will call a previously declared procedure.
Format
CALL procedure [ (arguments) ]
arguments is:
parameter1 [ ,parameter2... ]
parameter is:
integer-expression or
string expression
Notes
1. CALL may call system procedures or user declared procedures.
2. If the procedure expects arguments they must be provided in the
call.
3. Note that typed procedures are not exactly referenced using the same
form without the call.
4. Arguments are expressions, either integer or string as expected by
the called procedure. Those arguments which are to be modified by
the procedure must be simple variables.
5. Parameters are always passed by reference; all accesses made by the
called procedure are actually made to the caller's variables.
Example
COMMAND a_rtn;
BEGIN
EXTERNAL PROCEDURE match;
EXTERNAL INTEGER PROCEDURE drop;
...
IF drop ("abc") eql 1 then
CALL match ("abc");
...
END
Related
EXTERNAL - page 30
PROCEDURE - page 46
CASE
8.8. CASE
Function
The CASE statement provides an orderly way of choosing one of several paths
to take based on the current value of an integer expression. The statement
tagged with the current value is executed, and all others are ignored.
Format
CASE integer_expression FROM low TO high OF BEGIN
test : PCL-statement;
test : PCL-statement;
...
END;
low, high are:
integer constants
test is:
tag1 [ ,tag2 ... ]
tag is:
constant or
constant1 TO constant2 or
INRANGE or
OUTRANGE
Notes
1. The integer expression is tested against each test for a match
against any of the tags expressed in it. When a match is found, the
statement corresponding to the test is executed. The FROM and TO
keywords precede integers defining the lowest and highest
permissible value of the expression. If the expression is outside
the limits and an OUTRANGE tag was specified, the statement labelled
by the OUTRANGE tag is executed. If the expression is outside the
limits and no OUTRANGE tag was specified, PCL issues an error.
2. After a sucessful match, and execution of the corresponding code,
execution proceeds after the CASE.
3. The INRANGE keyword indicates that the tagged statement is to be
executed if the integer expression is within the range allowed, but
is not explicitly provided for by any of the other integer constant
tags. The INRANGE tag must be the last in the list.
4. If the integer expression is within the FROM-TO limits, but there is
no statement tagged with that value, and there is no INRANGE tag,
then nothing is done and execution continues with the statement
following the CASE.
5. The CASE statement should be used when the values to be tested are
very thightly packed (eg most numbers between 1 and 10). It should
never be used to test on a wide range like 1,2,100 (Use a Select
Instead).
6. The CASE tests against integer constants. For testing agains values
that are known only when executing the command or against strings
use SELECT or SELECTALL.
Example
...
CASE $Value FROM 1 to 7 OF BEGIN
1 TO 3, 5 : {executed if $value
is between 1 and 3, or 5};
6,9 : {executed if $value is 6 or 9};
INRANGE : {executed if $value is 4, 7, 8 or 10}
END;
Related
IF - page 34
SELECT - page 49
SELECTALL - page 50
CLEARTYPEOUT
8.9. CLEARTYPEOUT
Function
The CLEARTYPEOUT PCL statement will discard the output typed out from an
INVOKED program.
Format
CLEARTYPEOUT
Notes
1. The CLEARTYPEOUT PCL statement is useful for getting rid of unwanted
text from a program such as startup messages.
2. CLEARTYPEOUT is more efficient than doing a GETTYPEOUT and then not
using the returned data.
Example
COMMAND runprog (text (help "program to run"):prog_to_run);
BEGIN
...
INVOKE prog_to_run;
...
CLEARTYPEOUT;
...
TYPEIN "week";
...
END
Related
GETTYPEOUT - page 31
INVOKE - page 37
KILLPROGRAM - page 38
TYPEIN - page 53
COMMAND
8.10. COMMAND
Function
The COMMAND PCL statement keyword indicates the beginning of a command
definition.
Format
Format 1.
COMMAND name [ (command-arguments) ]
PCL Statement;
Format 2.
COMMAND name [ (command-arguments) ]
BEGIN
[ declarations ]
PCL Statement;
PCL Statement;
...
PCL Statement
END
command-arguments is:
field-type [ (options) ] : variable-name;
...;
field-type [ (options) ] : variable-name
field-type, options:
are defined as for PARSE (see page 42,
and page 43)
declarations is:
type name1,name2,...;
Declaring Local variables
EXTERNAL type name1, name2,...;
Declaring Global variables that will be used.
EXTERNAL [ type ] PROCEDURE name1, name2,...;
Declaring external procedures that will be called.
...
type is:
INTEGER or
STRING
Notes
1. The COMMAND keyword must be the first word in a command definition.
2. Format 2 allows to declare local variables, references to global
variables, and references to other PCL procedures.
3. The command will be called name. It may contain any alphanumeric
characters, including the underscore which will be converted to a
hyphen when it is entered into the Exec's command table.
4. The commands arguments are optional. If given, the parameters to the
command are specified on the command declaration line, avoiding the
use of PARSE. The command may not do any explicit PARSE statement
unless it uses subcommands with PROMPT (see page 47). For each
field parsed, the variable associated with the command is
automatically declared INTEGER or STRING and is set to $VALUE or
$Atom, depending on the type of field parsed:
integer for KEYWORD, NUMBER, SWITCH
string for INPUTFILE, OUTPUTFILE, FILE, FIELD, DIRECTORY,
USERNAME, DEVICE, TEXT, DAYTIME, QUOTEDSTRING,
TOKEN, NODE.
5. For example:
COMMAND TRY (NOISE "Number";
NUMBER (Default "10") : number);
begin
display $string(number);
end;
6. More than one command declaration may appear in a source file.
Example
COMMAND newone;
...
COMMAND more (number:job_val;text:entry_type);
...
Related
PROCEDURE - page 46
PROMPT - page 47
DECLARE
8.11. DECLARE
Function
EXEC command to merge user written commands, procedures, or variables into
the EXEC.
Format
@DECLARE (for PCL) [ cfm ] option
cfm is:
/Confirm or
/NoConfirm
option is:
ENVIRONMENT (from file) FileName1 [ ,filename2 ... ] or
INTEGER-VARIABLE (named) integer-name or
PCL-ROUTINES (from file) FileName1 [ ,filename2 ... ] or
STRING-VARIABLE (named) string-name or
SYNONYM (to new name) new-name
(to old command named) command-name
Notes
1. The DECLARE command will confirm its action with a message typed to
the user's terminal. The user may alter this default on a permanent
basis with a SET DEFAULT command. To override the default or the
SET status the user may specify the Confirm or NoConfirm switches.
2. To DECLARE PCL routines the source files are specified by a list of
files specification separated by commas, each specification may
contain wildcards. Each file specified is read, compiled into an
internal format, and stored in the EXEC. The source file may
contain any combination of procedures, commands, and variable
declarations. If the user does not specify any file name then the
source input is read from the terminal. For procedures which will
be used often, the EXEC environment should be saved using the
ENVIRONMENT option of the Exec @PRESERVE command. This environment
may then be recalled with the DECLARE ENVIRONMENT command. The user
may declare a command with the same name as a predefined command.
If the user wishes to execute the predefined command then the
ORIGINAL command should be used.
3. The PCL environment is the entire collection of user defined
objects, which must have unique names. This includes commands and
variables. The user may save the PCL environment at any time using
the exec PRESERVE command. To re-establish a previous environment
use the ENVIRONMENT option of the DECLARE command. The environments
to DECLARE are specified by a list of file specifications, each
specification may contain wild cards. The default file name is
EXEC.ENV. The requested environments are merged into the existing
environment so all commands and variables already declared will
remain.
4. The INTEGER-VARIABLE and STRING-VARIABLE options to the DECLARE
command will create variables in the EXEC which may be referenced by
user written commands or procedures. This provides a mechanism for
one command to pass data to another command or for one global value
that many commands may reference. These variables may be assigned
values by using the SET (see page 51) command if at the EXEC level
or by a simple assignment statement if in a command. The user may
view the current value of these global variables by using the
INFORMATION VARIABLE command.
5. The SYNONYM option declares a synonym name to an existing command
(Exec or PCL) .
Example
@DECLARE PCL-ROUTINE new-commands.pcl
[Command GIGI defined]
[Command GAPL defined]
[Command GTYPE defined]
[Command SAVE defined, old definition replaced]
[Command GCOLOR defined]
@DECLARE STRING-VARIABLE message
Related
INFORMATION - page 35
ORIGINAL - page 41
SAVE - page 45
SET - page 51
UNDECLARE - page 54
DISPLAY
8.12. DISPLAY
Function
The DISPLAY PCL statement will type its argument on the terminal.
Format
DISPLAY [ option ] expression
option is:
NORETURN or
BINARY
expression is:
an integer or string expression
Notes
1. By default, DISPLAY will type out the string or number in ordinary
character mode with a carriage return added.
2. The NORETURN option will not type out the carriage return.
3. The BINARY option is used to display without any character
conversion. This is useful for controlling display or graphics
terminals. It will not add a carriage return to the string.
4. To concatenate strings and numbers in DISPLAY use the $String
procedure:
DISPLAY "Terminal length : " + $STRING($termlength);
Example
COMMAND showoff;
BEGIN
STRING status;
INTEGER value;
...;
DISPLAY "starting";
...;
DISPLAY "Status : " + status;
...
DISPLAY value * 37;
...;
DISPLAY BINARY "$H$J";
...
END
DO
8.13. DO
Function
The DO PCL statement provides loop control within PCL commands.
Format
Format 1.
DO PCL statement WHILE logical expression
Format 2.
DO PCL statement UNTIL logical expression
Notes
1. PCL statement may be any legal PCL statement or a BEGIN/END grouping
of PCL statements.
2. Format 1 will loop as long as the logical expression is true.
Presumably some statement in the PCL statement will alter something
that is being tested in the logical expression. Otherwise the DO
may loop forever. There is no ENDLOOP or ESCAPE command. The user
may wish to GOTO out of the loop but this is not recommended.
3. Format 2 will loop as long as the logical expression is false. Once
the test becomes true the loop terminates.
4. Both formats will execute at least once. The logical expressions
are not checked until after the PCL statements have been executed.
Example
command DoWhile;
begin integer i;
i = 5;
DO begin display $string(i);i = i - 1 end WHILE i > 0;
end
Execution:
@DoWhile
5
4
3
2
1
Related
WHILE - page 56
UNTIL - page 55
DOCOMMAND
8.14. DOCOMMAND
Function
The DOCOMMAND PCL statement passes commands to the EXEC.
Format
DOCOMMAND [ ORIGINAL ] string1 [ TO string2 ]
Notes
1. The optional keyword ORIGINAL causes the DOCOMMAND to execute the
EXEC's original definition of a command and not the user's declared
command.
2. Normally, Docommand types the results of the command on the
terminal.
3. If the optional TO string2 is specified docommand places the results
of the command in String2. The output will be formatted as if the
Exec were typing to a terminal with a width of zero, since this is
most easily parsed by programs.
4. A carriage return will be added to the end of the string containing
the command.
5. The DoCommand statement can be abbreviated DCM .
6. A Docommand terminates any PARSE currently in progress. The best
rule is not to use any Docommand before a PARSE EOL has been
executed.
Example
COMMAND bigeez;
DOCOMMAND "vdir,
larger 100
"
EXIT
8.15. EXIT
Function
The EXIT PCL statement will cause the PCL command to return to the EXEC.
Format
EXIT [ option ]
option is:
SAVE or
TOPROGRAM
Notes
1. EXIT will always go back to the EXEC even if executed within a
procedure.
2. If the PCL command executes to the END of the command, an EXIT will
be simulated.
3. It is permissible to have more than one exit in a PCL command or
procedure.
4. When a PCL command exits, any invoked programs are killed during the
cleanup. The SAVE option will prevent the invoked program from
being killed, and leaves it as if a ^C had been typed.
5. The TOPROGRAM option acts as if the command was exited totally and a
@continue was typed to the Exec for the invoked program.
Example
COMMAND checkvalue;
BEGIN
INTEGER count;
...;
IF count > 6 THEN EXIT;
...;
EXIT
END
Related
ABORT - page 18
RETURN - page 48
INVOKE - page 37
EXTERNAL
8.16. EXTERNAL
Function
The EXTERNAL PCL statement allows commands to use externally defined
procedures and global variables.
Format
EXTERNAL type name1 [ ,name2 ... ] or
EXTERNAL [ type ] PROCEDURE name1 [ ,name2 ... ]
type is:
INTEGER or
STRING
Notes
1. The "EXTERNAL type name" form allows a PCL command or procedure to
reference global variables (defined by INTEGER or STRING in a PCL
source file, or by the Exec @Declare command).
2. The "EXTERNAL [type] PROCEDURE name" form allows a PCL command or
procedure to reference externally defined procedures (typed or
untyped). If the type is not specified the procedure is referenced
by "CALL name", otherwise its name may be used as a variable name.
Example
COMMAND outside;
BEGIN
INTEGER int;
EXTERNAL STRING message;
EXTERNAL INTEGER PROCEDURE finger;
EXTERNAL PROCEDURE mark;
...
display message;
int = finger;
call mark;
...
END
Related
CALL - page 21
DECLARE - page 25
PROCEDURE - page 46
GETTYPEOUT
8.17. GETTYPEOUT
Function
The PCL statement GETTYPEOUT will place the terminal output from an invoked
program into a string.
Format
GETTYPEOUT string
Notes
1. When a GETTYPEOUT statement is executed, PCL will gather all
terminal output from the invoked program since the INVOKE or since
the last GETTYPEOUT and put it in the string. When the invoked
program goes into terminal input wait, the GETTYPEOUT will return
with the type out in the string.
2. A CLEARTYPEOUT PCL statement is more efficient that doing a
GETTYPEOUT and then not using the returned data.
Example
COMMAND runprog (text (help "program to run"):prog_to_run);
BEGIN
STRING program_text;
...;
INVOKE prog_to_run;
...;
GETTYPEOUT program_text;
...
END
Related
INVOKE - page 37
TYPEIN - page 53
CLEARTYPEOUT - page 23
KILLPROGRAM - page 38
GOTO
8.18. GOTO
Function
The GOTO statement alters the flow of execution of PCL. It causes execution
to jump directly to a labeled statement (see page 4). Its use should be
minimized because of the great possibility of confusion, but at times it may be
essential.
Format
GOTO label
Notes
1. The label must be defined somewhere in the command or procedure.
Example
COMMAND xfer;
BEGIN
...;
loop1:
...;
GOTO loop1;
...
END
Related
PCL Labels - see page 4
GUIDE
8.19. GUIDE
Function
The GUIDE statement can be used in conjunction with the PARSE statement to
provide a pleasing user interface. It tells the system that a particular guide
word is to be displayed if the user requests it by hitting the Escape key. It
is equivalent to PARSE NOISE.
Format
GUIDE string-constant
Notes
1. The GUIDE statement has the same restrictions as the PARSE
statement: It can not be used except where a command line is being
parsed.
2. The GUIDE statement is actually a PARSE statement with the NOISE
field-type.
Example
GUIDE "Input File";
PARSE FILE (INPUT);
Related
PARSE - page 42
IF ... ELSE
8.20. IF ... ELSE
Function
IF ... ELSE provides the conditional execution of PCL statements depending on
testing integer or string expressions.
Format
IF logical-expression THEN
PCL-statement
[ ELSE
PCL-statement ]
Notes
1. If the expression is true then the statement after THEN is executed;
otherwise the ELSE statement is executed.
2. The ELSE part is optional. If omitted it corresponds to a Null ELSE
(ie if the test fails then nothing is executed).
3. IF ... ELSE may be cascaded (although CASE or SELECT might be more
appropriate if the cascade is lengthy).
Example
IF $value < 10 then display "less than 10"
ELSE IF $value <100 then display "more than 9 but less than 100"
ELSE display "More than 99";
Related
CASE - page 22
SELECT - page 49
SELECTALL - page 50
INFORMATION
8.21. INFORMATION
Function
New options to the EXEC INFORMATION command give information about the
current PCL environment.
Format
INFORMATION (About) DEFAULTS (For) DECLARE
INFORMATION (About) PCL-OBJECTS
INFORMATION (About) VARIABLE string
Notes
1. The DEFAULTS DECLARE option lists the defaults for the DECLARE
command. The defaults for the DECLARE command are also listed by
INFORMATION DEFAULTS ALL.
2. The PCL-OBJECTS option lists the names of all the commands,
procedures, and variables that are currently declared in the user's
EXEC. This provides a way for the user to see exactly what commands
have been established and avoid any confusion about redefined
commands.
3. The VARIABLE option will display the current value of a string or
integer variable which was declared by the DECLARE STRING-VARIABLE
or the DECLARE INTEGER-VARIABLE commands. It does not display
values for variables declared inside commands or procedures.
Example
@INFORMATION (ABOUT) PCL
Commands: DRP, REMIND, NETMAILCHECK, DIALUPLINE, COURIER
Procedures: MATCH
Variables: String MESSAGE
@
@set string message (TO) grades are due today
@info var message
grades are due today
Related
DECLARE - page 25
SET - page 51
UNDECLARE - page 54
INTEGER - STRING
8.22. INTEGER - STRING
Function
The INTEGER (STRING) statement declares variables to be of type integer
(String). If inside a command it defines it as a variable local to the
procedure; otherwise it defines a global variable.
Format
INTEGER var1 [ , var2... ] or
STRING var1 [ , var2... ]
Notes
1. In PCL every variable must be declared by a type statement.
2. If a global variable is referenced in a command or procedure it must
be declared with an EXTERNAL statement.
Example
INTEGER today,tomorrow; ! dates in internal format
STRING mydir; ! current directory
Related
EXTERNAL - page 30
INVOKE
8.23. INVOKE
Function
The PCL statement INVOKE will start a program running in a lower fork. This
provides the program with only a simple form of terminal I/O; it is possible to
make programs which expect more advanced terminal control than PCL can provide.
Format
INVOKE [PASSOUTPUT] string
Notes
1. INVOKE should be used when the user wishes to control the type in
and type out of the invoked program.
2. After PCL starts the program, it waits for the program to either
halt or wait for terminal input.
3. If the PCL command exits before the program completes, the invoked
program will be left in a ^C state.
4. Data may be sent to the invoked program using the TYPEIN command.
Type out from the program may be retrieved with the GETTYPEOUT
command.
5. If the PASSOUTPUT option is used all output from the program is sent
directly to the terminal. This eliminates the need to do a
GETTYPEOUT and a DISPLAY.
6. The PASSOUTPUT option can be abbreviated PASO.
Example
COMMAND runprog (text (help "program to run"):prog_to_run);
BEGIN
...;
INVOKE prog_to_run;
...
END
Related
GETTYPEOUT - page 31
CLEARTYPEOUT - page 23
TYPEIN - page 53
KILLPROGRAM - page 38
KILLPROGRAM
8.24. KILLPROGRAM
Function
The KILLPROGRAM PCL statement will terminate an invoked program.
Format
KILLPROGRAM
Notes
1. KILLPROGRAM will ^C the invoked program and then do a RESET on the
fork.
Example
COMMAND runprog (text (help "program to run"):prog_to_run);
BEGIN
STRING program_text;
...;
INVOKE prog_to_run;
...;
GETTYPEOUT program_text;
...;
KILLPROGRAM;
...
END
Related
INVOKE - page 37
GETTYPEOUT - page 31
TYPEIN - page 53
CLEARTYPEOUT - page 23
NOP
8.25. NOP
Function
The NOP statement performs exactly Nothing.
Format
NOP
Notes
1. NOP may be used to clarify the intent of a procedure.
Example
CASE $value FROM 1 TO 6 OF BEGIN
1 TO 3 : {some code};
4 : NOP; !If 4, do exactly nothing
INRANGE : {code if 5 or 6};
END;
Related
NOORIGINAL
8.26. NOORIGINAL
Function
The NOORIGINAL PCL statement undeclares an original exec command.
Format
NOORIGINAL command-name
Notes
1. This command is placed in PCL source files, but may not be used
inside a command or procedure. Its use is equivalent to the Exec
"@UNDECLARE ORIGINAL-COMMAND" command.
2. The command thus undeclared does not appear when querying the
available commands with "?" but it may still be invoked with the
"@ORIGINAL" Exec command (see page 41).
Example
NOORIGINAL ARCHIVE;
Related
UNDECLARE - page 54
ORIGINAL
8.27. ORIGINAL
Function
The Exec @Original command allows to run an original command even if PCL has
defined an other command by the same name, or if it has been undeclared by the
Exec "@UNDECLARE ORIGINAL-COMMAND" command or by the PCL "NOORIGINAL"
declaration.
Format
@ORIGINAL (Exec Command) command-name command-arguments
Example
@ORIGINAL Systat Debar
Related
DECLARE - page 25
NOORIGINAL - page 40
UNDECLARE - page 54
PARSE
8.28. PARSE
Function
The PARSE PCL statement is used to read command input parameters from the
terminal. Specific types of parameters may be requested such as numbers or
input file specifications. Refer to the parse introduction page 10 for an
introduction to the working of PARSE.
Format
Format 1.
PARSE field-type [ (field-option; ... ) ]
Format 2.
PARSE
BEGIN
field-type [ (field-option; ... ) ] [ : PCL statement ];
field-type [ (field-option; ... ) ] [ : PCL statement ];
. . .
END
field-type is:
the type of atom parsed, cfr infra
field-option is:
options modifying the parse, cfr infra
Format 1 is called a simple parse. Format 2 is a complex parse,
allowing to parse one of several possible field types.
Example
COMMAND getinfo;
BEGIN
STRING type_in;
PARSE text;
type_in = $ATOM;
DISPLAY "You entered>> " + type_in;
PARSE EOL;
...
END
COMMAND choice;
BEGIN
STRING a_user; INTEGER the_job;
PARSE BEGIN
username :
BEGIN
a_user = $ATOM;
DOCOMMAND "systat " + a_user
END;
number :
BEGIN
the_job = $VALUE;
DOCOMMAND "systat " + $string(the_job)
END
END
;
...
END
To the user, the above command choice would look like:
@decl pcl choice
[Command CHOICE defined]
@
@choice ? user name
or decimal number
@choice te04
14 42 EMACS TE04
@choice 10
10 13 OPR IO00
@
The following command defines a keyword to be parsed.
COMMAND keywd;
BEGIN
...;
PARSE KEYWORD ( WORDS("day":1, "week":2, "year":3) );
...
END
To the user, the keywd command would look like:
@keywd ? one of the following:
DAY WEEK YEAR
@keywd day
Notes
1. The parse field types are a subset of the COMND JSYS Function codes
for the expected field to be parsed. For a complete description of
the actions of these fields, see their corresponding description in
the TOPS-20 MONITOR CALLS manual. The legal field types are listed
page 42.
2. The last atom typed by the user is returned in $xatom (except for
FileList, DirectoryList and UserList). The complete command up to
the last atom parsed is in $command.
3. The values for NUMBER, the integer-constant in a KEYWORD or SWITCH
(see below), and the internal date and time for DAYTIME are returned
in $VALUE.
4. The value for file parses is returned in system variables $Parse
(see page 7), and $filen, $FileL, $FileS and $FileV (see page 7).
5. The text typed in for NUMBER, FIELD, DEVICE, TEXT, TOKEN,
QUOTEDSTRING, DIRECTORY, USERNAME, KEYWORD, SWITCH, and NODE is
returned in $ATOM.
6. Each Field type may have optional Field Options enclosed in
parentheses and separated by commas. These options modify or extend
the parse type of the field; they are closely Related to the COMAND
JSYS. The parse field options are described page 43.
7. PARSE takes care of re-parsing and redisplay if the user corrects
the command line. The PCL author should code the command as though
the user will never make a mistake or change what was typed in.
8. Once an EOL has been parsed, no more PARSE statements may be
executed without first doing a PROMPT statement to reinitialize the
parsing system. Reparsing will occur only back to the last executed
prompt statement.
9. A DoCommand statement generates an implicit Parse EOL statement, to
require that commands first parse their parameters and then perform
their actions. Subsequent PARSE must thus be preceded by a PROMPT.
If you fail to follow this rule, stange failures may happen,
including falling back in the standard exec if you delete too far
back, etc.
10. The GUIDE statement is equivalent to PARSE NOISE;
8.28.1. Parse Field Types
The legal parse field types are:
COMMA parses a comma. Spaces may appear on either side of the comma.
DAYTIME inputs a date and time field. The format is any general
date/time format. Both date and time must be entered unless
the date or time parse options are specified. The date is
returned in internal form in $Value, and in expanded form in
$atom.
DEVICE parses a device name, including the closing ":". Returned in
$atom (without the closing ":").
DIRECTORY parses a directory name, including the angle brackets.
Returned in $atom, fully expanded as device:<directory>.
DIRECTORYLIST allows the user to enter a list of directories separated by
commas. Each directory specification may contain wildcards. The
$NEXTDIRECTORY system procedure allows to loop through the list
of directories matching the list. The current directory name is
returned in the $Directory system variable. (See page 10). The
system variable $xatom does not work for this field type.
EOL is used to parse a carriage return. If the user is doing simple
parses then the command will continue to execute after each
parse. Once a PARSE EOL has been executed the PCL command
cannot do any more PARSE statements. See the PROMPT PCL
statement on page 47. It is not necessary, nor is it
permitted, to specify a EOL when using command arguments.
FIELD parses an arbitrary parameter delimited by a nonalphanumeric
character. No standard help message is available. (See the
HELP field option, page 43). Returned in $atom.
FILE is more general than INPUTFILE and OUTPUTFILE (cfr infra).
This field type has many more options available. Defaults may
be specified for any of the file specification fields. The
user may specify that the field is to be "parse only" which
merely checks for a valid file specification. (See field
options DEFAULT_DEV, DEFAULT_DIR, DEFAULT_EXT, DEFAULT_GEN,
DEFAULT_NAM, INPUT, OUTPUT, and WILD.) It is not possible to
have more than one FILE field in a single Parse statement. The
file name is returned under various forms in the $File* system
variables (see page 7) and $parse (see page 7).
FILELIST allows the user to enter a list of files separated by commas.
Each file specification may contain wildcards. The $NEXTFILE
system procedure allows to loop through the files that match
the list. The current file is returned in the same way as for
the FILE field type (cfr supra). The system variable $xatom
does not work for this field type.
INPUTFILE allows the user to specify a file that already exists. This
field type does not allow any fields of the file specification
to be defaulted. (See FILE and FILELIST field types. The file
is returned in the same way as for the FILE field type (cfr
supra).
KEYWORD allows a list of keywords to be specified. The user may select
one of the keywords in the list. The list is defined by using
the WORDS field option (see page 43). The keyword string is
returned in $atom, and the value associated with it is returned
in $value.
NODE parses a network node name. This must be an available node,
unless the PARSEONLY option is specified. Returned in $atom.
NOISE string-constant
mostly used for command arguments. This field type will cause
the text in the string to be typed out in parentheses if the
user types an escape. The command GUIDE "text" is equivalent to
PARSE NOISE "text".
NUMBER parses an integer input field. The RADIX field option allows
for numbers in some radix other than 10 (see page 43). The
value is returned in $value, and the string in $atom.
OTHERWISE is a special field-type which is meaningful only in the complex
Parse (see page 10). If specified, it must be the last field
in the Parse statement. The Otherwise case will be taken if
the input available matches none of the field types provided.
The otherwise field type does not consume any of the input; it
only indicates that it was not recognizable.
OUTPUTFILE causes the system to parse for a file name that does not exist.
This field type does not allow any fields of the file
specification to be defaulted. Wild cards may not be
specified. The file is returned in the same way as for the
FILE field type (cfr supra).
QUOTEDSTRING parses a field contained in double quotes. The field is
returned in $ATOM without the quotes.
SWITCH is similar to KEYWORD except that a list of switches (i.e.
KEYWORDS preceded by a slash) is parsed. The list is defined
by using the WORDS field option (see page 43). The switch
string is returned in $atom, and the associated value in
$value.
TEXT parses all the input up to the carriage return. Returned in
$ATOM.
TOKEN string-constant
parses a field that exactly matches the string. Returned in
$atom.
USERLIST allows the user to enter a list of directories separated by
commas. Each user specification may contain wildcards. The
$NEXTUSER system procedure allows to loop through the list of
users matching the list. The current user name is returned in
the $USER system variable. (See page 10). The system variable
$xatom does not work for this field type.
USERNAME parses a username (without angle brackets). Returned in $atom.
8.28.2. Parse Field Options
The Field options directly related to parsing file names (File, InputFile,
OutputFile, and FileList) are:
DEFAULT_DEV string
For FILE and FILELIST fields, specify the default device. The
string may be a string constant or a user string variable. It
may not include the field delimiters (: for device, <..> for
the directory, etc). The string given may not be a string
expression (eg formed by concatenation), nor a string system
variable:
mydir = $ConnectedDirectory;
PARSE (FILE (DEFAULT_DEV "DSK",
DEFAULT_DIR mydir));
DEFAULT_DIR string
For FILE and FILELIST fields, specify the default directory.
The allowed forms of String are the same as for Default_dev.
DEFAULT_NAM string
For FILE and FILELIST fields, specify the default file name.
The allowed forms of String are the same as for Default_dev.
DEFAULT_EXT string
For FILE and FILELIST fields, specify the default extension.
The allowed forms of String are the same as for Default_dev.
DEFAULT_GEN code
For FILE and FILELIST fields, specify the default generation.
The codes are 0 (highest generation), + (next generation), -
(first generation), * (all generations), or a generation
number:
PARSE (FILE (DEFAULT_GEN 0));
PARSE (FILE (DEFAULT_GEN +));
DELETED For field types FILE and FILELIST, parses for a deleted file.
Turns on COMAND JSYS bit GJ%DEL.
INPUT For field types FILE and FILELIST, parses for an existing file.
Turns on COMAND JSYS bit GJ%OLD.
INVISIBLE For field types FILE and FILELIST, parses for an invisible
file. Turns on COMAND JSYS bit GJ%IIN.
OUTPUT For field types FILE and FILELIST, parses for a new file.
Turns on COMAND JSYS bit GJ%FOU.
PARSEONLY For file parses, allows the command to parse for a validly
formatted file specification without requiring that the file
actually exist. For Node parses, allows the node not to exist;
similarly for Device, Directory, and User. The string that the
user enters for this field will be returned in $ATOM.
WILD For FILE field type, allows the user to specify a wild card.
This allows to step through the files matching the
specification in the same way as for a FILELIST. See the
FILELIST field option for the most general file wild card
parsing method.
The Fields options not directly related to file name parsing are:
DATE Parse only the date for field type DAYTIME.
DEFAULT string Specifies that the field may be skipped and that the default
value should be string. String may be either a string constant
or a user string variable. It may not be a string expression
(eg formed by concatenation) nor a string PCL variable (like
$ConnectedDirectory).
ERROR For command arguments only, branch to label on a parse error.
In complex parse use the OTHERWISE field-type.
HELP string If the user enters a ? at the field prompt, the help message in
string is displayed. String may be either a string constant or
a user string variable. It may not be a string expression (eg
formed by concatenation) nor a string PCL variable (like
$ConnectedDirectory). By default the use of this option turns
off the system default help. If you wish to append the default
help message, give the STDHELP option after the HELP option:
PARSE KEYWORD (WORDS ("Usage":1, "Days_unreferenced":2),
HELP "Next Field for Sorting", STDHELP ) ;
Will give the ? help:
?Next field for sorting, one of the following:
Days-Unreferenced Usage
NOHELP Suppresses the default system help. This is the default if you
use the HELP option.
NOINDIRECT Specifies that an indirect command file may not be used at this
field. Turns on bit CM%XIF in the COMAND JSYS.
RADIX Integer-constant
For field type NUMBER, specifies that the number typed in is in
radix integer constant.
STDHELP Use the standard help message provided by Tops20, eventually
appending it to the HELP option help text (in this case STDHELP
must be given after the HELP option. Not applicable for the
field type FIELD.
TIME Parse only the time for field type DAYTIME.
WILD For the DIRECTORY and USERNAME field types, allows the user to
specify a wild card. This allows to step through the
directories or users matching the specification in the same way
as for a DIRECTORYLIST or USERLIST. See these field-types for
the most general wild card parsing method.
WORDS (word1 : int1 [,word2 : int2 ...])
or
WORDS (word1 :: int1 [,word2 :: int2 ...])
For the field types KEYWORD and SWITCH, the WORDS option gives
the list of keywords (or switches). Each word may be:
a string enclosed in double quotes
for example "68_cobol". This is the Preferred
syntax; it is needed for words which start with
a digit.
a number an integer number like 123.
a word an alphanumeric string beginning by a letter,
like a13.
The integer after the ":" will be stored in $value. The second
form of the WORDS option, wich uses "::" is reserved for
parsing SWITCHes of the form: "/delete:"; it may not be used in
command arguments, but only in PARSE statements.
If an underscore ("_") appears within a word it is converted
into a hyphen ("-").
For example:
PARSE BEGIN
KEYWORD (WORDS ("blue":1, "red":2),
HELP "Select Colour", STDHELP)
: colour = $value;
OTHERWISE: display "Invalid colour";
END;
Related
GUIDE - page 33
PROMPT - page 47
PRESERVE
8.29. PRESERVE
Function
The PRESERVE command allows the user to save the current PCL environment for
later recall. It allows system administrators to modify the Exec with PCL and
then save the entire Exec for use at his or her site.
Format
PRESERVE option file-name
option is:
ENVIRONMENT
EXEC
Notes
1. An ENVIRONMENT is all the PCL commands, procedures, and variables
that the user has defined.
2. The ENVIRONMENT file contains the internal, compiled version of the
PCL objects. It will not be recompiled when declared.
3. The default file name for environments is EXEC.ENV.
4. Format 2 is for system administrators. The EXEC that is written may
be placed on <SYSTEM> for use by the installation. All commands
that have been defined may not be un-declared by the users.
5. The default file name for PRESERVE EXEC is EXEC.EXE.
Example
PRESERVE ENVIRONMENT payroll.env
PRESERVE EXEC exec.exe
Related
DECLARE - page 25
UNDECLARE - page 54
PROCEDURE
8.30. PROCEDURE
Function
A PROCEDURE definition in a PCL source file creates a procedure. All
procedures are declared globally and on the "top level;" there are no inner
procedures.
Format
[ type ] PROCEDURE name [ (arguments) ]
arguments is:
arglist [ ; arglist ... ]
arglist is:
type param1 [ ,param2... ]
type is:
INTEGER or
STRING
Notes
1. A PROCEDURE need not have arguments; if it has none then the
parentheses are not necessary.
2. A PROCEDURE, may have either INTEGER arguments, STRING arguments, or
both. The string and integer arguments may appear in any order in
the arguments list.
3. The procedure may change the value of its arguments. The modified
value is returned to the caller. In this case the argument must be a
variable.
4. If the type is not given the procedure is untyped and must be CALLed
(see page 21).
5. If type is given the procedure is typed. The type may be either
INTEGER or STRING. The procedure must return a result of that type
(see the RETURN statement on page 48). A typed procedure may be
used in place of a variable in PCL statements.
6. Specifying the names of the parameters in the argument list defines
them for all purposes; they need not be declared again within the
body of the procedure.
Example
PROCEDURE match (string input_string,str_match;
integer start_point);
BEGIN
...;
RETURN
END
If a user has an integer procedure called finger that looks at a SYSTAT and
returns the job number of the requested user, that procedure could be used:
COMMAND findem (username:guy);
BEGIN
EXTERNAL INTEGER PROCEDURE finger;
IF finger(guy) neq -1 THEN
DISPLAY guy + " is at " + $string(finger(guy))
ELSE
DISPLAY guy + "not on";
EXIT
END
The procedure finger would look like:
INTEGER PROCEDURE FINGER (STRING name);
BEGIN
STRING gotem;
DOCOMMAND "systat " + name TO gotem;
IF $length(gotem) = 0 THEN return -1
ELSE return $integer(gotem[3:2])
END
Related
CALL - page 21
EXTERNAL - page 30
RETURN - page 48
PROMPT
8.31. PROMPT
Function
When using PARSE to parse parameters, it only permits you to parse one
command line; once the line has been completely parsed, with PARSE EOL, you can
not use PARSE again, without causing PCL to obtain and begin parsing a new
command line. The PROMPT PCL statement allows the PCL command to prompt for
more input parameters after a PARSE EOL has been executed.
Format
PROMPT [ NOECHO ] string
Notes
1. The PROMPT statement allows the user to have subcommands to
commands.
2. After a PROMPT statement, the user may again do PARSE statements.
3. The NOECHO option turns off echoing for that entire line of command
typein; this must be done at the Prompt because of the way command
typein and echoing is done.
4. In command parsing, it is permissible for the user to type in a
field and have it recognized by PCL and then to type enough rubouts
or ^W to make the entire field invalid, or even an earlier, already
parsed field. When this happens, the system signals to the Exec
that a "reparse" occurred, and that the system will now reset its
internal pointer to the beginning of the command line and start
again. When a reparse happens during basic command line parsing,
PCL aborts the executing command completely and restarts the command
program from the beginning. During subcommand parsing, this is
undesirable. Instead, when a reparse occurs during subcommand
parsing (properly identified as such by a PROMPT statement), PCL
jumps back to the last-executed Prompt statement as if a GoTo had
been performed and resumes execution of the PCL program from that
point. Then, when the user's Parse statements re-execute, they will
match the fields which the system will re-present to the program.
Example
COMMAND subcomm;
BEGIN INTEGER a_value;
PARSE NUMBER;
a_value = $VALUE
...;
PARSE EOL;
...;
PROMPT "@@";
PARSE KEYWORD ( Words("first":1, "last":2, "all":3));
...;
PARSE EOL;
PROMPT NOECHO "Please enter your password: "
PARSE TEXT;
...
END
Related
PARSE - page 42
RETURN
8.32. RETURN
Function
The RETURN PCL statement causes a procedure to return to the calling routine.
Format
RETURN [ expression ]
Notes
1. A RETURN always returns to the calling routine. If in a command,
the command returns to the EXEC.
2. The optional expression must be provided if within a typed
procedure, and must be of the same type as the procedure. It
defines the value returned by the procedure (see page 46).
Example
PROCEDURE show;
BEGIN
display $jobno + " " + $username;
RETURN
END
INTEGER PROCEDURE calc;
BEGIN
INTEGER total;
...;
RETURN total + 5
END
Related
ABORT - page 18
PROCEDURE - page 46
SELECT
8.33. SELECT
Function
The SELECT statement provides an orderly way of choosing one of several paths
to take based on the current value of an integer or string expression. The
statement tagged with the expression having the same value is executed, and all
others are ignored.
Format
SELECT test_expression OF BEGIN
test : PCL-statement;
test : PCL-statement;
..
END;
test is:
tag1 [ , tag2 ... ]
tag is:
expression or
expression1 TO expression2 or
OTHERWISE
Notes
1. All the tags expressions must be of the same type as the test
expression (ie integer or string).
2. Unlike the CASE statement, the tags may be complex expressions
instead of constants. After evaluating the select expression, PCL
will evaluate each tagging expression in turn and compare the value
to the value of the select expression. If they are equal, the
corresponding statement will be executed. Execution will then
proceed after the SELECT statement.
3. The OTHERWISE keyword indicates that the tagged statement is to be
executed if all the preceding tests fail. If present, the OTHERWISE
must be the only tag in a test, and should be the last test given.
4. If all the tests fail, and there is no OTHERWISE, then execution
continues following the SELECT statement.
5. The intent of providing SELECT in addition to CASE is that CASE is
implemented with a table of statement addresses, making it
appropriate for small ranges of the selection expression, say from 1
to 10, whereas SELECT is implemented by a series of tests which
might as well have been coded by user statements like:
IF x=1 THEN s1
ELSE IF x=58 THEN s2
ELSE IF x=101 THEN s3
ELSE ...
This form is suitable for a large range in the selection range.
Example
...
SELECT $Value OF BEGIN
1 TO 3, 100 : {executed if $value
is between 1 and 3, or 100};
6,9 : {executed if $value is 6 or 9};
OTHERWISE : {executed if none of the above};
END;
...
COMMAND seltest(USERNAME:unam);
...
SELECT unam OF
BEGIN
"OPERATOR": display "the operator";
"DIAGNOSTICS": display "the engineers"
END
END
Related
IF - page 34
CASE - page 22
SELECTALL - page 50
SELECTALL
8.34. SELECTALL
Function
The SELECTALL statement is very similar to the SELECT statement except that
after a match has been found, the testing continues ("falls through the
SelectAll" so that multiple PCL statements may be selected one after the other.
Format
SELECTALL test_expression OF BEGIN
test : PCL-statement;
test : PCL-statement;
..
END;
test is:
tag1 [ , tag2 ... ]
tag is:
expression or
expression1 TO expression2 or
ALWAYS or
OTHERWISE
Notes
1. All the tags expressions must be of the same type as the test
expression (ie integer or string).
2. Unlike the CASE statement, the tags may be complex expressions
instead of constants. After evaluating the select expression, PCL
will evaluate each tagging expression in turn and compare the value
to the value of the select expression. If they are equal, the
corresponding statement will be executed. After that the execution
proceeds by testing against the next tests in the SELECTALL, until
all tests have been made.
3. The OTHERWISE tag matches if no previous test matched. Within a
test, it must be the only tag.
4. The ALWAYS tag matches any expression. For this reason, OTHERWISE
should always precede any ALWAYS. If present ALWAYS must the only
tag in a test.
5. SELECTALL must be used where a SELECT would be used and multiple
successive selections are needed.
Example
SELECTALL $value OF BEGIN
1 TO 3 : {executed if $value is between 1 and 3}
1, 5 : {executed if $value is 1 or 5}
OTHERWISE : {executed if $value is not 1, 2, 3 or 5}
ALWAYS : {executed whatever the value of $value}
END;
Related
CASE - page 22
IF - page 34
SELECT - page 49
SET
8.35. SET
Function
New options to the EXEC SET command will set the values of global variables
declared by the DECLARE command.
Format
SET INTEGER-VARIABLE (named) variable (to) value
SET STRING-VARIABLE (named) variable (to) value
SET [ NO ] COMMAND-TRACE (OF GENERATED COMMANDS)
SET DEFAULT DECLARE /CONFIRM
/NOCONFIRM
Notes
1. The variable must have been previously declared by a DECLARE
command. see page 25.
2. The INFORMATION command may be used to display the setting of a
global variable. see page 35.
3. Setting COMMAND-TRACE causes PCL to display at the terminal all
DoCommand statements as they are executed.
4. Setting the default for DECLARE allows you to say whether the
DECLARE command should, by default, confirm its actions.
Example
@SET integer-variable doneflag 0
@SET string host TOPS-A
Related
INFORMATION - page 35
DECLARE - page 25
UNDECLARE - page 54
SYNONYM
8.36. SYNONYM
Function
The SYNONYM command defines a synonym to an original Exec command.
Format
SYNONYM new-name original-name
Notes
1. The SYNONYM command may not be given inside a command or procedure.
It is used in PCL source files in the same way as the Exec "@DECLARE
SYNONYM" command (see page 25).
Example
SYNONYM AuRevoir LOGOUT
Related
DECLARE - page 25
TYPEIN
8.37. TYPEIN
Function
The TYPEIN PCL statement will send a character string to an invoked program.
Format
TYPEIN [ NORETURN ] string
Notes
1. TYPEIN will send string to the invoked program as though it had been
typed on the controlling terminal. A carriage return will be added
to string, unless the NORETURN option is specified.
2. Several lines may be sent to the invoked program with one TYPEIN
statement. PCL will strip the extra line feeds from the string
before sending it, because programs normally expect their terminal
input to be terminated by carriage returns only.
TYPEIN "tape copytp:
density 1600
ssname area backup"
3. After the string has been passed to the program, PCL waits until the
program either halts or waits for more terminal input.
Example
COMMAND runprog (text (help "program to run"):prog_to_run);
BEGIN
STRING program_text;
...;
INVOKE prog_to_run;
...;
GETTYPEOUT program_text;
...;
TYPEIN "week";
...
END
@
Related
INVOKE - page 37
GETTYPEOUT - page 31
CLEARTYPEOUT - page 23
KILLPROGRAM - page 38
UNDECLARE
8.38. UNDECLARE
Function
The Exec UNDECLARE command removes PCL customizations (and even original Exec
commands from the Exec.
Format
@UNDECLARE (from PCL) [ cfm ] option
cfm is:
/Confirm or
/NoConfirm
option is:
ALL (Customizations) or
COMMAND (Named) PCL-command-name or
ORIGINAL-COMMAND (Named) Exec-command-name or
PROCEDURE (Named) PCL-procedure-name or
SYNONYM (Named) synonym-name or
VARIABLE (Named) PCL-variable-name
Example
@Undeclare (from PCL) variable Term_typ;
Related
DECLARE - page 25
INFORMATION - page 35
NOORIGINAL - page 40
UNTIL
8.39. UNTIL
Function
The UNTIL PCL statement provides loop control for PCL routines.
Format
UNTIL condition DO PCL statement
Notes
1. As long as the condition is not true, the PCL statement is
repeatedly executed.
Example
Related
DO - page 27
WHILE - page 56
WHILE
8.40. WHILE
Function
The WHILE PCL statement provides loop control for PCL routines.
Format
WHILE condition DO PCL statement
Notes
1. As long as the condition is true the PCL statement is repeatedly
executed.
Example
Related
DO - page 27
UNTIL - page 55
I. FDB Codes
II. CRDIR/GTDIR Directory Argument Block
III. Facilities specific to the FNDP version of PCL
I have introduced several extensions to the standard version of PCL. These
extensions are listed briefly here (their documentation is in the main body of
the manual). If you are interested in these extensions, contact:
Michel E Debar
FNDP Computing Centre
Rue Grandgagnage, 21
B-5000 Namur
Belgium
Phone: +32.81.22-06-31
Telex: 59.222 Fac.Nam.B. (Belgium)
WILD option allowed for FILE, DIRECTORY and USERNAME parse field types.
$NEXTFILE working after PARSE (FILE (WILD)).
DIRECTORYLIST and USERLIST parse field type, with associated variables and
procedures $DIRECTORY, $USER, $NEXTDIRECTORY and $NEXTUSER.
Based numbers of the form base%number.
$Getfield and $Setfield to manipulate bit fields within integers.
$and and $or to provide logical and/or of integers.
$DirectoryInfo_I and $DirectoryInfo_s read the information returned by the
GTDIR and GTDAL JSYS's.
$FileInfo_I, $FileInfo_S, $FileSet accept mnemonic codes for the information
desired. They also accept the file name as a string argument in addition to the
usual $parse or channel number.
$FileSet sets individual entries in the FDB.
$xatom and $command, return the last atom parsed and the last command parsed.
$termlength returns the length of the controlling terminal.
A jsys interface is provided with the routines:
$get_men and $Ret_mem
to acquire and release memory
$iput and $iget to set/read integers in memory
$sput and $sget do the same for strings
$jfn returns the jfn associated with a channel
$strloc returns the address in memory of a string
$jsys, $Jsys1 execute a Jsys
$ac1 to $ac4 return the accumulators 1 to 4 after $jsys or $jsys1
$jsysok indicates the success or failure of the last $jsys or $jsys1
Inline comments of the form !{...}! are allowed. They may span several lines
and may be nested.
{...} may serve as a substitute to Begin...End.
Case and Select may have multiple tags in each case; each tag may be of the
form Value1 TO Value2.
The SelectAll statement implements a select that "falls through" and goes on
matching (it is to Select in PCL as Select is to Selectone in Bliss).
The WORDS option allows quoted strings:
(WORDS ("68_cobol":1, ...))
$Isfile (Filename) returns 1 if a file exists, else 0.
In $string if the radix is other than 10 the number is output in magnitude
form, ignoring the sign bit.
Index
$Ac1 7
$Account 7
$and 7
$Append 7
$ARPAnet_Node 7
$Atom 7, 10
$Batch_Job 7
$Close 7, 13
$Command 7, 10
$ConnectedDirectory 7
$Cr 7
$Crlf 7
$Curtad 7
$Date 7
$DECnet_Node 7
$Directory 7
$DirectoryInfo_I 7
$DirectoryInfo_S 7
$EMACSTerminal 7
$EOF 13
$ExpandTad 8
$FileInfo_I 8
$FileInfo_S 8
$FileL 7
$FileN 7
$FileS 7
$FileSet 8
$FileV 7
$File_Dev 8
$File_Dir 8
$File_Gen 8
$File_Nam 8
$File_Typ 8
$GetField 8
$Get_Mem 9
$Iget 9
$Input 7
$InputTad 9
$Integer 9
$Iput 9
$IsFile 9
$Jfn 9
$JobNo 7
$jsys 9
$Jsys1 9
$JsysOk 7
$LastErrCode 7
$LastError 7
$Length 9
$Lf 7
$MergeTad 9
$NextDirectory 9
$NextFile 9
$NextUser 9
$Nul 7
$Open 9, 13
$Or 9
$Output 7
$OutputTad 9
$parse 7, 8
$PromptEnb 7
$PromptEnbSub 7
$PromptReg 7
$PromptSub 7
$Quote 7
$Read 9, 13
$ReadBinary 9
$Ret_mem 9
$SEARCH 5, 9
$SearchRaised 9
$SetField 9
$Sget 9
$Sput 9
$String 9
$Strloc 9
$TermNumber 7
$TermWidth 7
$Time 7
$TType 7
$Typeahead 7
$User 7
$UserName 7
$Value 7, 10
$Wait 9
$Write 9, 13
$Xatom 7, 10
< 5
<= 5
<> 5
= 5
> 5
ABORT 5, 18
ALWAYS 50
ASSIGNMENT 19
Base 4
BEGIN 20
BINARY 26
CALL 21
CASE 5, 22
Channel 13
CLEARTYPEOUT 12, 23
COMMA 42
COMMAND 24
Command arguments 10
Comment 4
Complex parse 10
Concatenate 5
Constants 7
CvCtI 7
CvItC 7
Date 7, 43
DAYTIME 42
DCM 28
DECLARE 3, 25
DEFAULT 43
DEFAULT_DIR 43
DEFAULT_EXT 43
DEFAULT_GEN 43
DEFAULT_NAM 43
DELETED 43
DEVICE 42
DIRECTORY 42
Directorylist 10, 42
DISPLAY 26
DO 5, 27
DOCOMMAND 12, 28
ELSE 5, 34
END 20
Environment 3
Eof 8
EOL 42
EQL 5
Error 11, 43
Exec commands 12
EXIT 5, 29
EXPRESSIONS 15
EXTERNAL 30
FIELD 42
File 13, 17, 42
FILELIST 10, 42
Format 4
FROM 22
GEQ 5
GETTYPEOUT 12, 31
GOTO 6, 32
GTR 5
GUIDE 33, 43
HELP 43
IF 5, 34
INFORMATION 3, 35
Input 13, 43
INPUTFILE 42
INRANGE 22
INTEGER 36
INVISIBLE 43
INVOKE 12, 37
Jfn 9
KEYWORD 42
KILLPROGRAM 38
Label 4
Length 5
LEQ 5
Logical expression 5
LSS 5
NEQ 5
NODE 43
NOHELP 43
NOINDIRECT 43
NOISE 43
NOORIGINAL 40
NOP 39
NORETURN 26
NUMBER 43
Octal 4
ORIGINAL 3, 12, 41
OTHERWISE 43, 50
Output 13, 43
OUTPUTFILE 43
Parameter 5
Parse 10, 42
Parse error 11
Parse options 10
PARSEONLY 43
PASALL 12
PASO 37
PASSOUTPUT 37
PCL File 17
PRESERVE 45
Procedure 5, 7, 46
Prompt 7, 42, 47
QUOTEDSTRING 43
Radix 4, 43
RETURN 5, 48
Routine 5
SAVE 29
SELECT 5, 49
SELECTALL 50
SET 3, 51
Simple parse 10
STATEMENTS 16
STDHELP 43
String 5
Substring 5
SWITCH 43
SYNONYM 52
Syntax 4
TEXT 43
Time 7, 43
TO 22
TOKEN 43
TOPROGRAM 29
TYPEIN 12, 53
UNDECLARE 54
UNTIL 5, 55
Userlist 10, 43
USERNAME 43
Variable 7
Variables 4
WHILE 5, 56
WILD 43
WORDS 43
Table of Contents
1. INTRODUCTION 1
1.1. Programmable Command Language 1
1.2. PCL Uses 1
1.3. PCL Features 2
1.4. Notational conventions 2
2. EXEC INTERFACE 3
3. THE PCL LANGUAGE 4
3.1. General Command Format 4
3.2. PCL Constants 4
3.3. PCL Variables 4
3.4. Reserved names 4
3.5. String Manipulation 5
3.6. Logical expressions 5
3.7. Procedures 5
3.8. PCL Flow Control 5
3.8.1. ABORT 5
3.8.2. EXIT 5
3.8.3. RETURN 5
3.8.4. DO, WHILE, UNTIL 5
3.8.5. IF 5
3.8.6. CASE 5
3.8.7. SELECT 5
3.8.8. SELECTALL 6
3.8.9. GOTO 6
4. SYSTEM SERVICES 7
4.1. System Constants 7
4.2. System Variables 7
4.3. System Procedures 7
4.4. System Procedures specific to $Jsys Interface, memory management 9
5. USER INTERFACE 10
5.1. Parse Formats 10
5.1.1. Simple PARSE 10
5.1.2. Complex PARSE 10
5.1.3. Command Arguments 10
5.2. Parse Options 10
5.3. Parse Results 10
5.4. FILELIST 10
5.5. DIRECTORYLIST, USERLIST 10
5.6. Parse error handling 11
6. PROGRAM AND COMMAND INTERFACE 12
6.1. Running Programs 12
6.2. Executing EXEC Commands 12
7. INPUT/OUTPUT 13
8. REFERENCE 14
8.1. EXPRESSIONS 15
8.1.1. Integer expressions 15
8.1.2. String expressions 15
8.1.3. Logical expressions 15
8.2. STATEMENTS 16
8.3. PCL files 17
8.4. ABORT 18
8.5. ASSIGNMENT 19
8.6. BEGIN - END 20
8.7. CALL 21
8.8. CASE 22
8.9. CLEARTYPEOUT 23
8.10. COMMAND 24
8.11. DECLARE 25
8.12. DISPLAY 26
8.13. DO 27
8.14. DOCOMMAND 28
8.15. EXIT 29
8.16. EXTERNAL 30
8.17. GETTYPEOUT 31
8.18. GOTO 32
8.19. GUIDE 33
8.20. IF ... ELSE 34
8.21. INFORMATION 35
8.22. INTEGER - STRING 36
8.23. INVOKE 37
8.24. KILLPROGRAM 38
8.25. NOP 39
8.26. NOORIGINAL 40
8.27. ORIGINAL 41
8.28. PARSE 42
8.28.1. Parse Field Types 42
8.28.2. Parse Field Options 43
8.29. PRESERVE 45
8.30. PROCEDURE 46
8.31. PROMPT 47
8.32. RETURN 48
8.33. SELECT 49
8.34. SELECTALL 50
8.35. SET 51
8.36. SYNONYM 52
8.37. TYPEIN 53
8.38. UNDECLARE 54
8.39. UNTIL 55
8.40. WHILE 56
I. FDB Codes 57
II. CRDIR/GTDIR Directory Argument Block 67
III. Facilities specific to the FNDP version of PCL 71
Index 72
