; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019 PAGE 1 Programmable Command Language Page 1 This defines the stored command language which will completely replace the current CMU Command Generator language; any suggestions should be sent to DK32 on any Computation Center system, or to KING at ARPANET site CMUC, or to David King at the Carnegie-Mellon University Computation Center, Pittsburgh, 15213. The system as it is currently implemented does not include all of the features described here, those features not currently available are indicated NYI (not yet implemented). This is NOT intended to be a general user document; it was originally the designer's own notes on what he was making, and it grew into something which could be read by the initiated. Accordingly, complaints and recommendations for this document of a stylistic nature (not concerned with technical correctness) would be a waste of time. User documentation is being written. ^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019 PAGE 2 CHAPTER 1 EXEC COMMANDS RELATING TO THE COMMAND LANGUAGE 1.1 DECLARE COMMAND DECLARE (for PCL) [switches] object-type names DECLARE (for PCL) PCL-ROUTINES (from files) [filespec,filespec,...] DECLARE (for PCL) INTEGER-VARIABLE (named) name DECLARE (for PCL) STRING-VARIABLE (named) name DECLARE (for PCL) SYNONYM (to new name) NEWNAME (old command named) OLDNAME DECLARE (for PCL) ENVIRONMENT (from files) filespec,filespec,... switches: /CONFIRM /NOCONFIRM This command defines for the Exec a global variable, any number of PCL Commands or Procedures, a Synonym, or an entire Exec environment containing a collection of such objects. For a variable the variable is immediately defined; PCL variable names are alphanumeric strings, including the underscore character. For a PCL-routine the Exec reads the files provided and converts them into an internal representation; if no files are specified the Exec reads the source from the terminal (this last feature is not yet implemented). If the PCL routine file contains any command definitions, the name of the commands as given in the source file COMMAND statements are entered in the Exec's standard command table. If the command name in the source file contains any underscores, they are turned into hyphens before being placed in the command table. A PCL source file may also contain definitions for global variables; a line containing simply INTEGER or STRING will result in that variable being defined, the same as if a Declare Integer or Declare String command had been issued. It can also contain synonym definitions, and can remove original Exec commands, with lines like SYNONYM K LOGOUT; NOORIGINAL PLOT; ^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019 PAGE 3 EXEC COMMANDS RELATING TO THE COMMAND LANGUAGE Page 1-2 The Declare command, by default, confirms its actions. The /NOCONFIRM switch suppresses this, as does the Set Default Declare /NoConfirm command. The /CONFIRM switch enables confirmation, even when confirmation has been turned off by a Set command. In the case of a procedure the program consists of a procedure declaration in the form of a , as given below (see section 2.1), page 2-1). In the case of a command declaration, the first line contains the keyword COMMAND and the name of the command, in the same fashion as a procedure source file; similarly, it may be followed by an optional parameter list, which may be used to enter the parameters from the terminal without the need to use the complex PARSE statement (described below in section 2.3 on page 2-3). There are two ways to deal with the parameters to a command: 1. You can parse them with the PARSE statement. In this case you leave out the parameter list and have the first thing in your definition be the BEGIN to start the command program. (see PARSE example in section 2.3 page 2-5). 2. You can accept a less flexible mechanism and provide, in parentheses, a brief description of each parameter: What type, default, guide word, and the name of a variable into which the value will be stored. Then, in the text of the command program, you do no Parses but only reference the variables. Each parameter description looks like this: ParameterType [(Options)] : VariableName where the parameter typed on the command line is placed in VariableName before the command program starts. The type of the variable will be appropriate to the type of the parameter. The ParameterTypes are as described below (see section 2.3 on page 2-3) in the definition of the Parse statement, as are the options available. Note that EOL is not a valid Field-type in this context; command arguments are terminated by carriage return by default. Also, there may be no variable or system procedure references in the field-type or field-options; for instance, the option 'HELP "repeat count"' is legal, but 'HELP HelpString' is not. One additional Parse-option is available in this context: the option "ERROR " will cause the command text to be started at that label if the argument does not match the Field-type specified; if no ERROR option is provided (which we expect to be the usual case) then a standard fatal error message appropriate to the Field-type will be issued if the field does not match. For example, a primitive form of the DECLARE command might be defined like this: ^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019 PAGE 4 EXEC COMMANDS RELATING TO THE COMMAND LANGUAGE Page 1-3 COMMAND DECLARE( NOISE "for PCL"; KEYWORD (WORDS(VARIABLE:1,PCL_ROUTINES:2, TAKE_FILE:3)):OptionSelect; NOISE "Source file"; INPUTFILE:InFile); BEGIN STRING TEMP; ...etc You must use one of these two mechanisms in your command definition; if a command contains neither command arguments nor Parse statements, then PCL compiles it as if it started off with an end-of-line Parse. A Synonym is a way of making a new name for an existing command. It adds an entry to the command keyword table with the given new name as its name, which when executed runs the given old command. If, however, the new command name is a simple abbreviation of the old command name, an invisible abbreviation entry is created instead; this allows you to define, for instance, the string DI to be an abbreviation for the DIRECTORY command. 1.2 SAVE COMMAND SAVE /ENVIRONMENT (on file) filename SAVE/EXEC (on file) filename To define the entire Exec environment of variables, procedures, and commands, you may specify the ENVIRONMENT type along with the specification FileName, to load into the Exec a file previously created by the command SAVE/ENVIRONMENT. This allows a user's standard set of commands and procedures to be loaded into the Exec in internal form, without having to compile the procedures and commands again. I had originally intended that DECLARE ENVIRONMENT would completely replace the Exec's data areas; now it appears that the general desire is that it merge sets of objects. SAVE/ENVIRONMENT saves all the global variables, procedures, and user-defined commands in the file specified, in an internal format suitable for use by a later DECLARE ENVIRONMENT command. To allow for the possibility of the format of environment files changing from year to year, the file contains a version number, which must match the environment file format version number in use at the time the Declare Environment command is issued. On the installation LEVEL, a complete locally-customized Exec containing all of the installation's command definitions (commands, procedures, etc) can be produced by running a standard Exec, making the desired changes, and saving the image with the SAVE/EXEC command. This generates an EXE file which can then be placed on SYSTEM: as EXEC.EXE, ^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019 PAGE 5 EXEC COMMANDS RELATING TO THE COMMAND LANGUAGE Page 1-4 so that all users automatically get that Exec when they log in. Commands so defined are regarded as "preserved" commands, which to the user are nearly part of the original system; a user can not use any command other than those defined by this local environment. Within the context of these commands, a reference to an "original" command (through DoCommand Original) obtains the original Digital command. Note that this saves the entire Exec image, containing all the defaults and variables in existence at the time of the Save command, including, for instance, the default load-class command string and the last Edit string. 1.3 UNDECLARE COMMAND UNDECLARE [switches] (from PCL) (name) name UNDECLARE (from PCL) ALL (customizations) where is COMMAND, ORIGINAL-COMMAND, PROCEDURE, SYNONYM, or VARIABLE, and the available switches are Confirm and NoConfirm. To forget the declarations of various commands, procedures, original Exec commands, synonyms, and variables, freeing the program space of commands and procedures, and removing command names from Exec's command table. Note that the Original-Command option is the only way to remove a standard Exec command; Undeclare Command is not appropriate. Undeclare ALL removes all definitions and reinitializes the Exec to its original state as much as possible. 1.4 ORIGINAL COMMAND ORIGINAL (EXEC COMMAND) command To execute a standard Exec command according to the standard definition; the text after the guide word is parsed and executed without reference to the user-defined commands. 1.5 INFORMATION VARIABLE COMMAND INFORMATION VARIABLE variable-name This prints out the current value of the global integer or string variable. ^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019 PAGE 6 EXEC COMMANDS RELATING TO THE COMMAND LANGUAGE Page 1-5 1.6 INFORMATION PCL-OBJECTS COMMAND INFORMATION PCL-OBJECTS This gives a list of the commands, procedures, synonyms, and variables defined. Those which are "preserved" by being part of the installation's environment are marked with a dollar sign; those which have been superceded by user definitions are also marked with an asterisk. 1.7 SET COMMAND SET INTEGER-VARIABLE (named) variable-name (to) integer-constant SET STRING-VARIABLE (named) variable-name (to) This sets a global variable to the given value. There is a problem with COMND which currently prevents variable names used in the SET command from containing underscores. SET COMMAND-TRACE I don't know what this will do, but I'm sure it will be needed. It may just print out a trace of the DOCOMMAND statements and the program-control statements as they are executed. SET DEFAULT DECLARE /NOCONFIRM SET DEFAULT DECLARE /CONFIRM This enables or suppresses confirmation of Declare commands. INFORMATION DEFAULT DECLARE This shows the current setting of the Declare confirmation switch. ^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019 PAGE 7 CHAPTER 2 THE PROGRAM LANGUAGE 2.1 PROCEDURE BNF ::= ;

::= COMMAND ::= COMMAND ( ) ::= { ; } ::= ::= :

::=

::= PROCEDURE ::= PROCEDURE ( ) ::=

::=

{;

} I wish there was a way to say this in BNF, but there isn't: You can put in comments by starting a line with an exclamation mark. All this is as usual in a traditional language. Procedures may have parameters, which are always passed by reference, so that references to the formals within the parameter are direct references to the actual parameters. Procedures themselves may have types, which causes them to return values through the RETURN statement. You can't declare a procedure inside another declaration; all procedures are global and should be declared at the top (Exec) level. Procedures, like all other things, must be declared before they are referenced; to call one you must provide an EXTERNAL declaration. 2.2 STATEMENT BNF A lot of the language is completely traditional: ::= ::= ::= ::= ::= ::= ^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019 PAGE 8 THE PROGRAM LANGUAGE Page 2-2 ::= ::= ::= ::= ::= ::= ::= ::= ::= ::= ::= : ::= ::= ;

::= BEGIN { } ::= { ; } ::= BEGIN

::= { ; } END ::= ::= ::= EXTERNAL

::=

::= INTEGER ::= STRING ::= { , } ::= EXTERNAL PROCEDURE ::= EXTERNAL PROCEDURE This is not a block-structured language; all variables are declared on the command/procedure level. ::= LET = ::= =

::= ::= ELSE

::= IF THEN

::= GOTO

::= DO UNTIL ::= DO WHILE ::= WHILE DO ::= UNTIL DO

::= OF BEGIN END ::= CASE FROM TO

::= ::= ;

::= [ ] : ::= [ INRANGE ] :

::=

END ::= SELECT OF BEGIN ::= { : } ::= [ ] ::= [ OTHERWISE ] ^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019 PAGE 9 THE PROGRAM LANGUAGE Page 2-3 ::= RETURN ::= RETURN

::= EXIT ::= EXIT SAVE ::= EXIT TOPROGRAM ::= ABORT

::= CALL ::= CALL ( ) ::= NOP These are traditional; RETURN is for procedures and commands, RETURN for typed procedures. A simple EXIT will terminate a command, and ABORT terminates a command with an error message and causes the Exec to do its regular error handling (flush input buffer, force message to left margin, invoke error handler provided by the DOCOMMAND which ran the command, etc.). EXIT SAVE will not kill any program run by INVOKE; EXIT TOPROGRAM will exit PCL and, in effect, perform a Continue command for the current program. These last two options to Exit will work completely with only a few programs, due to context sensitivity in monitor I/O. CASE performs the statement in the list tagged with the current value of the specified expression; the tag INRANGE matches all unspecified values between the FROM and TO limits. If the expression is outside the limits an error is reported. SELECT performs the statement in the statement list "labeled" by an expression equal to the selecting expression; if there is no match, and there is a statement labeled OTHERWISE, that statement is executed. (The intent of providing SELECT in addition to CASE is that CASE will be implemented with a table of statement addresses, making it appropriate for small ranges of the selection expression, say from 1 to 10, whereas SELECT will be 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 ..., suitable for a large range in the selection expression.) The NOP statement is a no-op. 2.3 PARSE BNF ::= GUIDE ::= PROMPT ** ::= PROMPT NOECHO ** ::= PARSE ::= PARSE ( { ; } ) ::= [ : ] ::= OTHERWISE :

::= ::= ( ) ::= KEYWORD ::= SWITCH ::= NUMBER ************* DELETION ************* ** ^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019 PAGE 10 THE PROGRAM LANGUAGE Page 2-4 ::= NOISE (mostly for command args;** rarely desirable in Parse statements) ::= INPUTFILE ::= OUTPUTFILE These two do not allow defaults to be provided, such as DEFAULT_NAM. ::= FILE ::= FIELD ::= EOL (not available as command argument) ::= DIRECTORY ::= USERNAME ::= COMMA ::= DEVICE ::= TEXT ::= DAYTIME (date-and-time; options below let you get just one or the other.) ::= QUOTEDSTRING ::= TOKEN ::= NODE ::= FILELIST ::= { , } ::= DEFAULT ::= HELP ::= PARSEONLY (turns on GJ%OFG for FILE, turns on CM%PO for some others, returns contents of atom buffer instead of interpreting a JFN or directory # or whatever) ::= NOHELP (turns on CM%SDH; unnecessary if HELP given) ::= STDHELP (turns off CM%SDH) ::= NOINDIRECT (turns on CM%XIF) ::= INPUT (turns on GJ%OLD for FILE and FILELIST) ::= OUTPUT (turns on GJ%FOU for FILE and FILELIST) ::= INVISIBLE (turns on G1%IIN for FILE and FILELIST) ::= DELETED (turns on GJ%DEL for FILE and FILELIST) ::= WILD (modifies FILE and FILELIST) ::= DEFAULT_DEV (for FILE/FILELIST) ::= DEFAULT_DIR (for FILE/FILELIST) ::= DEFAULT_NAM (for FILE/FILELIST) ::= DEFAULT_EXT (for FILE/FILELIST) ::= DEFAULT_GEN

                  (for FILE/FILELIST)
                        The codes are 0 (highest generation), + (next
                        generation), - (first generation), * (all
                        generations), or a generation number.
                ::= RADIX    (for NUMBER)
                ::= WORDS (  )         (for Keyword/Switch)
                ::= TIME        (for time-only DAYTIME)
                ::= DATE        (for date-only DAYTIME)
                ::= ERROR  (only in COMMAND argument)
             ::=  { ,  }
       ::=  : 
************* DELETION *************                                  **
^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019	PAGE 11



THE PROGRAM LANGUAGE                                            Page 2-5


                        ::=  :    **
                        ::=  :: 
                        ::=  :: 

     A complete Parse statement makes up one COMND Jsys call,  with  the
several  Parse-fields  chained  together.   For descriptions of what the
field-types really are, see the corresponding entries in the  definition
of  the  COMND%  JSYS  in the Monitor Calls Reference Manual.  The first
case listed simply provides a guide word.  The second  case  parses  the
next  field  according to just one possible field description, and if it
matches the input execution continues to  the  statement  following  the
Parse;   if  it doesn't match execution aborts with an appropriate error
message.  In the third case listed, for each field  description  in  the
list  you  may  provide  an arbitrary PCL statement;  if the description
matches the input, that statement will be executed,  and  the  Parse  is
over.  In the statement you can store whatever results the Parse returns
which you think appropriate;  there  are  some  special  reserved  names
defined  which contain the results of the Parse.  You get the results of
the Parse from variables like  $VALUE  (the  value  for  a  Number,  the
  in a Keyword or Switch, or the TOPS-20 internal form
of the date and time for a DAYTIME parse), $FILEN, $FILEL, $FILES (three
varieties of file name), and $ATOM (the atom buffer, just what was typed
in, for NUMBER, FIELD, DEVICE, TEXT, QUOTEDSTRING, DIRECTORY,  USERNAME,
KEYWORD,   SWITCH,  and  NODE).   If  the  input  matches  none  of  the
possibilities, the OTHERWISE statement will be  executed;   if  none  is
provided, PCL will abort with an appropriate error message.

        PARSE ( FILE (Help "File to use") : BEGIN
                                            LET FNAM=$FILEN;
                                            PARSE EOL
                                            END;
                EOL :   LET FNAM = PREVIOUSFILE)


     In this example, the two field descriptors are strung  together  to
make  one COMND call, so a ?  from the terminal gets both help messages;
also, a successful parse, after execution of  the  success-statement  of
the  matching  descriptor, continues with the statement after the Parse;
if neither matches PCL will give the user an error message.

     To  provide  a   guide   word,   the   separate   statement   GUIDE
 can be used;  if the next part of the parameter string
typed in is the guide word, it will be skipped over;  if the  last  part
of the command was terminated by an escape, the guide word will be typed
out.  If you really care whether the guide word is specified  correctly,
use  the Field-type NOISE instead of the separate Guide statement;  this
is the only case where NOISE is desirable in a  Parse  statement,  since
the  COMND  JSYS  does  generally  undesirable things when a NOISE field
descriptor is chained to another field descriptor.

     In the WORDS option, the NAME::VALUE form  is  for  Switch  parsing
only;   it  signifies  a  switch  with  a  following  argument,  such as
/LIMIT:300;  in this case the Parse consumes the  switch  name  and  the
colon,  allowing the user to parse the Number following (or the Keyword,
or Token, or whatever he wishes to follow the colon).
^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019	PAGE 12



THE PROGRAM LANGUAGE                                            Page 2-6


     The FILELIST field-type is a more  high-level  way  to  parse  file
names.   It  parses an entire list of file specifications, each of which
may contain wildcards, with the specifications  separated  by  a  comma;
each  of  the  file  specifications is stored on a list inside the Exec.
After the Parse FileList is complete, information about the  first  file
is  available through $FileN, $FileL, etc.  To get to the next file, use
the function $NextFile;  it steps to the next  file  and  returns  1  if
there  is  a  next  file,  or 0 if you have reached the end of the list.
Since  file  specifications  can   contain   wildcards,   the   typed-in
specification   MYPROG.*   may  refer  to  several  files:   MYPROG.DAT,
MYPROG.PAS, MYPROG.REL, etc.  The file-information services like  $FileN
return   information  for  one  particular  file,  such  as  MYPROG.DAT;
$NextFile will step to MYPROG.PAS, then  MYPROG.REL,  and  then  to  the
specification which was typed in after MYPROG.*.

     A FileList Parse must be the only field specified in a given Parse;
it  can  not  be  fixed  with  other field types.  Also, since the $File
variables ($FileL, etc.) refer only to the last file  parsed,  you  must
retrieve  the  information  from  one Parse before doing another File or
FileList parse.

     A FileList parse accepts options the same as a File parse, since it
is  simply  a  File parse repeated with commas separating the files.  An
additional option, WILD, changes how the specifications are  treated  by
the  various  informational  services.   If  Wild  is  specified, then a
specification with wildcards is regarded as a single specification.  For
instance,  if  MYPROG.* is typed in, then $FileN contains "MYPROG.*" and
$NextFile will step to the next name on  the  list  instead  of  working
through the various files implied by MYPROG.*.

     Wild can also be specified in a File parse;  it merely sets  GJ%IFG
to allow wildcards to be specified.

     The Parse facility was created to allow parsing of the  fundamental
parameters to a command, up until the carriage return which confirms the
command.  However, it may be  desirable  for  a  command  to  read  more
information  from  the  terminal,  in  the  same fashion as subcommands;
Parse can be used in this situation  as  well.   Parse  is  only  valid,
however,  when  you  have  allowed  the Exec to properly (re)-initialize
itself for parsing.  After the basic command  line  has  been  confirmed
(with  an  EOL  Parse),  you  reinitialize  for further input parsing by
giving the Prompt statement, providing a prompt (such  as  "@",  if  you
wished  your  command  to  look  like  a  standard Exec command.  Having
reinitialized, you can then use Parse as you did for the  command  line.**
If  you  wish the information on the line not be echoed, you can specify**
the NoEcho option.                                                    **

     Along with subcommand parsing there comes a  serious  complication:
In  any  sort of command parsing, it is permissible for the user to type
in a field and have it recognized by the system (i.e., your PCL  command
program),  and  then to enough rubouts 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,
************* DELETION *************                                  **
^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019	PAGE 13



THE PROGRAM LANGUAGE                                            Page 2-7


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.



2.4  COMMAND STATEMENT BNF

     ::= DOCOMMAND  
                        ::= DOCOMMAND ORIGINAL 
                                
        ::= 
                        ::= TO  
                        ::= ERROR     NYI

     These pass commands to the regular Exec;  ORIGINAL means to  bypass
the  list  of  user-declared commands.  The TO option means to intercept
all printout and store it in the given variable;   the  string  variable
may  then  be  examined and used in any other fashion.  The ERROR option
specifies the action to be taken  if  the  execution  of  the  Performed
command  string  causes  a ?Error to be reported;  in the event that the
Exec types out an error message  starting  with  a  question  mark,  the
statement  following ERROR will be performed;  perhaps the error message
text should be stored in some system variable.  The string passed to the
Exec is terminated with a carriage-return, free of charge.



2.5  PROGRAM STATEMENT BNF

     ::= INVOKE 
                        ::= INVOKE PASSOUTPUT      **
                        ::= KILLPROGRAM
                        ::= CALL  WITH 
                                 TO           NYI
                        ::= SET ARGUMENT      NYI
                        ::= GET ARGUMENT      NYI
                        ::= TYPEIN 
                        ::= TYPEIN NORETURN 
                        ::= GETTYPEOUT 
                        ::= CLEARTYPEOUT
                        ::= DISPLAY 
                        ::= DISPLAY NORETURN 
                        ::= DISPLAY BINARY 
     ::=  
                        ::=  
                        ::= 
^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019	PAGE 14



THE PROGRAM LANGUAGE                                            Page 2-8**
                                                                      **

     These run programs.  INVOKE does a GET for the  file  given  and  a
START;  it continues execution of the command program when the user fork
either terminates (with HALTF) or hangs waiting  for  "terminal  input."
The  idea  is  that  the  command  program  next does a TYPEIN to feed a
parameter line to the program;  the command program then continues when,
************* DELETION *************                                  **
as  before,  the  user fork halts or needs input.  When run by an INVOKE
statement, everything the fork types out is intercepted  and  stored  in
the  Exec;   if  you  want  to  see  it  you do a GETTYPEOUT and you get
everything from the last  INVOKE  or  TYPEIN  until  now.   CLEARTYPEOUT
throws  away  all  the  accumulated  output that a GETTYPEOUT would have
retrieved;  it is more efficient than doing a  GETTYPEOUT  and  throwing
away  the  output  yourself.   INVOKE  PASSOUTPUT  bypasses  all of this**
buffering, and types it to the terminal  immediately.   TYPEIN  sends  a**
carriage return after your string;  the NORETURN option suppresses that.**
KILLPROGRAM kills the user program fork;  it is  the  same  as  doing  a**
RESET command from the Exec.                                          **

     TYPEIN can be used to send multiple lines of input to  the  program
at  one  time;  just give TYPEIN a string argument consisting of each of
the lines joines by a carriage return ($CR) or a carriage return  and  a
line feed ($CRLF);  either will work, as TYPEIN will strip the linefeeds
from the string before transmitting it.  For instance,

                TYPEIN "TAPE COPYTP:
                        DENSITY 1600
                        SSNAME Distribution tape for PCL
                        FILES"

would be a suitable way to pass several commands to Dumper at once;  the
lines are separated by PCL's standard $CRLF.

     Note that this program fork handling occurs within the  context  of
the  Exec's  fork  handling.   At the completion of the PCL command, any
Invoked program fork will be killed, leaving the  user's  forks  intact.
The  Save  option  to  the  Exit  statement  will cause PCL execution to
complete without killing the Invoked fork;  the ToProgram option to Exit
will  do  the same and then cause the fork to continue, as if a Continue
command had been done from the terminal.  Also, if at the time a  Typein
statement  is  executed  no  program  has been Invoked, the current user
program is selected as if it had been.

     Besides simulating terminal I/O, you can use a  more  sophisticated
method  of  communicating  with  a program suitably coded.  Any fork can
have associated with it a set of 'process arguments', up  to  200  words
long;  they are stored in core owned by the job.  SET ARGUMENT will fill
in the process arguments with  a  list  of  strings  and  integers,  the
program  can read the arguments itself (the command and the program must
cooperate with respect to argument types;   the  monitor  can't  enforce
things like a Procedure call matches formals and actuals), compute as it
wishes, and return another list of strings and integers to be  retrieved
by  GET  ARGUMENT.   Such a program can be used in an entirely different
fashion, by using it as an "active function" through the CALL statement;
this loads the program into a fork separate from the standard user fork,
gives it parameters in the process arguments, lets it run, retrieves the
answers, and discards the fork.
^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019	PAGE 15



THE PROGRAM LANGUAGE                                            Page 2-9**
                                                                      **

     DISPLAY types the string out on  the  real  terminal;   a  carriage
return  is  added  unless the NORETURN option is specified.  since it is
for an arbitrary  string.   DISPLAY  BINARY  types  the  string  to  the
terminal in binary mode, for display terminal control characters.
                                                                      **


2.6  EXPRESSION BNF

    ::= 
 ::=  
                                
                        ::=  
                                
   ::= LSS
                        ::= LEQ
                        ::= EQL
                        ::= NEQ
                        ::= GEQ
                        ::= GTR
                        ::= <           This are
                        ::= =           simply
                        ::= >           equivalents
                        ::= <=          to the
                        ::= <>          standard
                        ::= >=          relationals

  This will get more advanced, with AND, OR, etc.

            ::= 
                        ::= 

    ::= 
                        ::=   
          ::= +
                        ::= -
                  ::= 
                        ::=   
         ::= *
                        ::= /
     ::= 
                        ::=  + 
       ::= 
                        ::= - 
                        ::= 
                        ::= 
                        ::= (  )
        ::= 
                        ::= 
                        ::= 
                        ::= 
                                [  :  ]
                        ::= 
                                [  : * ]
        ::= 
^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019	PAGE 16



THE PROGRAM LANGUAGE                                           Page 2-10**
                                                                      **
                                                                      **
                        ::=  ( Actual-parm-list> )
      ::= 
                        ::=  , 

     As said before, parameters may be  both  passed  by  value  and  by
reference;   they must also match with regard to type (integer, logical,
or string).
************* DELETION *************                                  **

     The String+String construct concatenates the two strings.

     The String[Integer :  Integer] construct extracts  a  substring  of
the  String;   the  value  of  S[I:J]  is  a  string  J characters long,
containing the J characters of S starting with the I'th character (where
the  first  character  of  a  string  has  index  1).   If the requested
substring runs off the end of the string,  as  much  of  the  string  as
possible  is  extracted.   The String[Integer:*] case extracts up to the
end of the string.



2.7  IDENTIFIER BNF

    ::= 
                        ::= 
     ::= 
                        ::= 
  ::= 
      ::=         CURRENTLY LIMITED TO 5 CHARS
            ::= 
                        ::=  
                        ::=  _ 
      ::= 
                        ::=  
       ::= {sequence of characters enclosed by double-quotes;
                             double-quotes may be inserted in the string by
                             doubling them}



2.8  SYSTEM DEFINED VARIABLES

     Available as primaries are the user's declared  variables  and  the
variables  defined  by  the  system  for  various purposes.  Not all are
meaningful in all situations.  All  contain  information  which  can  be
fetched;   some  can  be  stored  into.   Suggestions  for  more will be
welcomed.

    $VALUE      In parsing, the number entered, or the value of a keyword
                or switch
    $FILEL      In parsing, the file name entered in the longest form,
                DEV:FILE.EXT.VERSION
    $FILES      In parsing, the file name entered in the form FILE.EXT;
                it will have device: and  if they are different
                from the connected device and directory.
    $FILEN      In parsing, the file name entered in the intermediate form,
^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019	PAGE 17



THE PROGRAM LANGUAGE                                           Page 2-11**
                                                                      **
                                                                      **
                FILE.EXT.VERSION
    $FILEV      Just the generation number (an integer)
    $ATOM       In parsing, whatever was typed in
    $JOBNO      The number of the current job
    $USERNAME   The user name of the current job
    $CONNECTEDDIRECTORY The name of the currently connected directory
    $TTYPE      The terminal type index (GTTYP%) of the controlling terminal
    $TERMNUMBER The number of the controlling terminal
************* DELETION *************                                  **
    $TERMWIDTH  The terminal width of the controlling terminal
    $CURTAD     The current date and time in system internal format
    $NUL        Read/write string like NUL:, returns a null string.
    $CRLF       A string containing a carriage return and a line feed
    $CR         A string containing just a carriage return
    $QUOTE      A string containing a double quote character
    $LASTERROR  The text of the last JSYS error
    $LASTERRCODE The number of the last JSYS error
    $TIME       Current time in HH:MM:SS format
    $DATE       Current date in DD-MON-YY format
    $PromptReg  The standard prompt string, which can be written if
                the usual "@@" is not suitable.
    $PromptSub  The standard subcommand prompt string, also writeable.
    $PromptEnb  The standard enabled prompt string.                   **
    $PromptEnbSub The standard enabled subcommands prompt string.     **
    $Account    The account of the current job.
    $Typeahead_Count The number of characters which have been typed-ahead
                on the controlling terminal.
    $EMACSTerminal  One if the current terminal can be "effectively"
                used by EMACS, zero if not.  (CMU only)



2.9  SYSTEM DEFINED PROCEDURES

     Also available are system service routines, of which these are  all
I have defined so far.  Please suggest more.  Some have types and return
values, others store all their results in their actual arguments.

    integer $LENGTH (string)    Returns length of string
    integer $SEARCH (string,    Searches first string for second string;
                     string)    returns index within first string, or zero
                                if not found
    integer $SEARCH (string,    The same, with the search starting with the
                     string,    index provided
                     integer)
    integer $SEARCHRAISED       Save as $SEARCH except lower case alphabetics
                   (string,     are raised to upper case
                    string)
    integer $SEARCHRAISED       The same, with the search starting with the
                   (string,     index provided
                    string,
                    integer)
    string $STRING (integer)    Converts integer into string
    string $STRING (integer,    The same, according the radix given
                   integer)
    integer $INTEGER(string)    Converts decimal number in string to integer;
^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019	PAGE 18



THE PROGRAM LANGUAGE                                           Page 2-12**
                                                                      **
                                                                      **
                                currently uses NIN JSYS, returns 0 on error.
    $EXPANDTAD (integer,        Performs an ODCNV% JSYS, expanding the
            6 more integers)    first integer into the other 6 (year, month,
                                day of month, day of week, hour, minute)
    integer $MERGETAD (5 integers)      Performs an IDCNV% JSYS, compacting 5
                                integers (year, month, day of month, hour,
                                minute) into an internal date and time.
    string $OUTPUTTAD (integer) Convert internal date and time to string.
    integer $INPUTTAD(string)   Converts time and date to internal format.
    integer $CVCTI (string)     Converts the first character in the string
                                into an integer; for manipulating control chars**
    string $CVITC (integer)     The reverse of $CVCTI                 **
    string $READBINARY (integer, Reads the from the terminal in binary, up to**
                     string,    the specified number of characters or until**
                     [integer]) the specified character is read.  This will**
                                time out and return an empty string if nothing**
                                appears within a second (an optional third**
                                argument can be used to provide the number of**
                                milliseconds to use for the timeout period.)**
                                This exists only to read cursor information**
                                from VT100's.                         **
    integer $NextFile           Used to step to the next file in a parsed file
                                list; returns zero at the end of the list.
    integer $FileInfo_I (file, field)
    string $FileInfo_S (file, field)
                These two return information about a file, the file selected
                by the first argument and the information to return by the
                second.  Permissible files are presently $Parse for the file
                currently being parsed, or the runtime channel number (see
                below). For $FileInfo_I the field
                code is the name of the index for the GTFDB JSYS to be used,
                such as $FBSIZ and $FBCRV.  For $FileInfo_S the fields are
                $Author, the name of the author of the file, $Writer, the name
                of the file's last writer, $FileAccount, the file's account
                number, or an integer greater than 63 which calls the JFNS
                JSYS with the formatting parameter set to the field index
                minus 64.
    string $File_Dev (file)
    string $File_Dir (file)
    string $File_Nam (file)
    string $File_Typ (file)
                These return just the corresponding part of the name of
                the file specified in the same manner as $File_Info_S.
    $Wait(integer)              This waits the specified number of
                                milliseconds, or forever if zero.



2.10  INPUT/OUTPUT FACILITIES

     Simple input/output services are available,  to  provide  the  user
with  up  to 36 files at a time, on which he can perform record I/O.  To
open a file, call the integer procedure $Open with the name of the  file
as  the  first  parameter,  and the mode as the second parameter (either
$Input, $Output, or $Append);   $Open  will  open  the  file,  assign  a**
^L; PCL.DOC.9 & SNARK:PCL.DOC.7 27-May-81 1019	PAGE 19



THE PROGRAM LANGUAGE                                           Page 2-13**
                                                                      **
                                                                      **
channel  number (an integer from 1 to 35) and return the channel number;**
it will return zero  if  the  open  could  not  be  done.   All  further**
operations take place depending on the channel number.  To close a file,**
call $Close with the channel number as the argument.                  **

     Input/output is performed only on records, terminated  by  carriage
return-line  feed;   the string procedure $Read(channelnumber) returns a
string containing the next record read from the  input  file  (with  the
carriage  return  and line feed removed), and the procedure $Write, when
given a channel number as the first argument and a string as the second,
writes that record to the output file (with a carriage return and a line
feed added).  When the input file becomes empty, $Read returns an  empty
string;   to  determine  whether end-of-file has actually happened, call
the  procedure  $Eof(channelnumber),  which  will  return   nonzero   if
end-of-file has been reached by $Read.

.