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 pcl.lpt. The present manual is in 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: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 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 ("", $CDUGP); ! Default account display $directoryinfo_s ("", $CDDAC); ! Protection display $string ( $Directoryinfo_I("", $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 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 , 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:. 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 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