Page 2 1 HOUSEKEEPING 1.1 Abstract This paper presents a survey of the basic capabilities of the RSX Indirect Command Processor (ICP). A useful and efficient subset of the ICP directives is presented, some common misconceptions are addressed, and known bugs in the various implementations of the ICP are highlighted. Similarities to and differences from the P/OS and RT-11 ICPs will also be pointed out. 1.2 Goal Introduction to the RSX Indirect Command File Processor The goal of this paper is to help the reader or listener to make efficient use of the RSX Indirect Command File Processor (ICP). 1.3 Caveats - RX009 - The current releases of all the operating systems are assumed. However, this paper should be useful as far back as: RSX-11M V3.2 RSX-11M+ V1.0 VAX-11 RSX V1.0 Thomas R. Wyant, III P/OS V1.0 E. I. DuPont de Nemours RT-11 V5.0 (FB and XM) Richmond, Virginia Where there are differences between the Indirect Command File Processors of these systems (and I am aware of these differences) they are indicated. Command lines in examples are all for RSX MCR. December 10, 1990 I am not the final authority on the ICP in all its multifarious versions. Errors in research and transcription do occur. I apologize in advance for these, but assume no responsibility for their consequences. 1.4 Acknowlegement Allen A. Watson's paper, "Indirect Command Files for New RSX Users", presented at the Spring, 1983 DECUS US Symposium, was both an inspiration and a reference for this paper. Page 3 Page 4 2 BACKGROUND - Has no other effect. 2.1 Historical Perspective o An "internal" comment: The RSX Indirect Command Processor (hereinafter known as the ICP) is the RSX system component that allows you to - Begins with ".;". group MCR or DCL commands in a file and have them executed as a group. The same basic processor was put in P/OS when - Is not displayed when encountered. it was spun off from the RSX mainstream, and the same logic has within the last couple years been exported to RT-11. - Has no other effect. o An ICP directive: 2.2 Invoking The ICP - Begins with ".". To feed a command file to the ICP: - Is interpreted and executed by the ICP. o Under RSX: >@filename - Most of this paper deals with these. (Default filetype is .CMD) o Under P/OS: o A CLI command: $ @filename (Default filetype is .CMD) - Is any line that doesn't meet the above criteria. o Under RT: . SET KMON IND - Is issued as a command to the current CLI, as . @filename though you typed it. If the current CLI can't or handle it, that's your problem, not ICP's. . IND @filename (Default filetype is .COM) Normally, only one of the above may appear on a line of In all cases the input is to a CLI prompt. "@filename" an ICP file. The exceptions to this rule are: in response to some other prompt has nothing to do with the ICP. For example, o Most ICP directives may be followed by an internal PIP>@filename comment. The output directives are the major feeds the file to PIP's own command processor. exception to this. o The ICP conditional directives may be followed by a comment, a CLI command, or another ICP directive 2.3 Contents Of An ICP File (including another conditional). Each line of an ICP file is composed of one of the following: o An "external" comment: 2.4 Processing A Line Of An ICP File - Begins with ";". A record (line) in an ICP file is processed in the following steps: - Is displayed when encountered (unless .ENABLE QUIET is in effect). Page 5 Page 6 1. Read it. - There are certain predefined Special Symbols, which are named according to the same 2. Perform symbol substitution (if enabled). convention, but have their names enclosed in "<>". These do not conflict with ordinary 3. Decide what category it falls in. If it's an ICP names. directive: 1. Parse the first "word". o They come in three flavors: 2. Load the overlay that processes it (overlaid - Logical (True of False). versions). - Numeric (16-bit integer values). 3. Complete parsing. - String (0 to 132 bytes). 4. Execute. o They can be assigned values: Why is this important? Because: - By computation within the ICP. o Symbol substitution occurs very early in the - By querying the user. processing of a line. Many "LISP"-ish behaviors of the ICP are based on this. - In special cases, by reference or on entry to the ICP. o Many versions of the ICP are overlaid, so grouping like operations together can improve performance. o Their values can be tested. o Running an overlaid ICP off a floppy disk can require a good deal of patience. o They are normally local to the command file in which they were created. However, if you .ENABLE GLOBAL, symbols whose name begins with a "$" are available for the life of the ICP run. 3 SYMBOLS 3.1 What Are Symbols? 3.2 Logical Symbols o They are named data stores used by the ICP. o Take on the values TRUE or FALSE. o They are not accessible outside the ICP (though the ICP can make their VALUES available). o Can be assigned values by: o Their names are 1-6 RAD50 characters (excluding .SETT symbol ! sets it TRUE. "."), and MUST contain at least one non-numeric .SETF symbol ! sets it FALSE. character. Note that: .SETL symbol expression - Certain releases of the ICP have had trouble o Logical expressions consist of logical symbols with embedded dollar signs, or with symbol (including the Special Logical Symbols or names that begin with a numeric character. ), connected by the following operators: ! (logical OR). & (logical AND). Page 7 Page 8 # (logical NOT) (RSX, P/OS). regard for usual precedence of operators. ^ (logical NOT) (RT). Operations may be grouped with parentheses. Expressions are evaluated left to right, without o Numeric constants are octal by default unless you regard for usual precedence of operators. append a decimal point, or unless you: Operations may be grouped with parentheses. .ENABLE DECIMAL ! (RSX,P/OS) .DISABLE OCTAL ! (RT) o Values can be tested by .IFT, .IFF, or .IF directives. These directives are discussed under o Values can be tested by the .IF directive. This "Control". directive is discussed under "Control". o Can take on values entered from your terminal, o Can take on values entered from your terminal, using the .ASK directive. This directive is using the .ASKN directive. This directive is discussed under "Terminal I/O". discussed under "Terminal I/O". o Substitution yields "T" for TRUE, or "F" for FALSE. o The default radix of a symbol is decimal, unless Substitution is discussed later in this section. the expression that computed its value consisted only of octal symbols and constants. This default radix can be changed by: .SETO symbol ! (set to octal); .SETD symbol ! (set to decimal). 3.3 Numeric Symbols o Substitution yields the value of the symbol, in the current default radix of the symbol. Substitution o Take on 16-bit integer values. These are unsigned. is discussed later in this section. Under RSX and P/OS, you can treat them as signed values if you .ENABLE OVERFLOW o Can be assigned values by: 3.4 String Symbols .SETN symbol expression .INC symbol ! Adds 1. o Take on the value of a 0-132 byte string. .DEC symbol ! Subtracts 1. .SETT [mask] symbol ! RT-11 only o Can be assigned values by: .SETF [mask] symbol ! RT-11 only .SETS symbol expression The ".SETx [mask] symbol" operations set or clear the masked bits in the given numeric symbols. If you .DISABLE LOWERCASE, the string is uppercased before being assigned to the symbol. o Numeric expressions consist of numeric symbols or constants, connected by the following operators: o String expressions consist of string symbols, substrings, or constants, connected by the + (addition); following operator: - (subtraction); * (multiplication); + (concatenation). / (integer division); ! (bitwise OR); Expressions are evaluated left to right. & (bitwise AND); Operations may NOT be grouped with parentheses, but # (bitwise NOT) (RSX, P/OS); then with only one operator, why would you need to? ^ (bitwise NOT) (RT). Expressions are evaluated left to right, without Page 9 Page 10 o A string constant is constructed as follows: D (substitute decimal value); O (substitute octal value); "this is a string constant" Rn (right justify in "n" byte #so is this, for RSX and P/OS only# field); Ln (left justify in "n" byte The quoting character may not appear in the string field); constant. Z (fill with leading zeros); S (signed value); o Substrings can be extracted by the construction: C (do blank compression); X (substitute RAD50 string symbol[start:end] for number); V (substitute value for first which represents the bytes between the start and byte, or a byte for value). end positions, inclusive. Any valid numeric expression can be used for "start" and "end". Also, "*" can be used, representing the last Examples (all of which assume .ENABLE SUBSTITUTION): character in the string. o Assembling and task building an arbitrary module: o Values can be tested by the .IF directive. This directive is discussed under "Control". .ASKS MODULE What module MAC 'MODULE'='MODULE' o Can take on values entered from your terminal, TKB @'MODULE'BLD using the .ASKS directive. This directive is discussed under "Terminal I/O". Effects: o Substitution yields the bytes in the string. - You are prompted for the name of a module; Substitution is discussed later in this section. - That module is assembled and taskbuilt. o Inserting control characters: 3.5 Symbol Substitution .SETN NJUNK 33 .SETS ESCAPE "'NJUNK%V'" o Occurs only when enabled by .ENABLE SUBSTITUTION. Under P/OS and RT, substitution is enabled by Effect: default. Under RSX, it is disabled by default. - String Symbol ESCAPE now contains an escape o Is called for by enclosing a symbol name in character. apostrophes. o If you attempt substitution on an undefined symbol, o Using format control to set the size of a field: an error occurs. .SETN NJUNK 1 o Substitution in a line of an ICP file occurs BEFORE PIP FILE.'NJUNK%R3Z'/LI the line is parsed. Therefore it can occur anywhere in a line, and in any kind of line. Effect: o Under RSX and P/OS, you can get format control by - A directory listing of file FILE.001 is following the symbol name (within apostrophes) by a produced. percent sign ("%") and one or more of the following: Page 11 Page 12 3.6 Determining The Characteristics Of Symbols = if a RAD50 string (string only). o Finding out whether a symbol exists: .IFDF symbol ! If it's defined .IFNDF symbol ! If it's not. 3.7 Manipulating Substrings Note that the line .IFDF symbol ;'symbol' will result in an error if the symbol is undefined. o Finding substrings of a string: The substitution is attempted BEFORE the line is parsed. .TEST string1 string2 o Characteristics of a symbol: returns the following Special Symbol value: .TEST symbol causes the following Special Symbol values to be set: = the position of first occurrence of string2 in string1, or 0 if it doesn't occur. = 0 if the symbol is a Logical Symbol, Note that: = 2 if the symbol is a Numeric Symbol, - The strings may be either string constants or = 4 if the symbol is a String Symbol; string symbols. - Extracting substrings based on character position was discussed under String Symbols. = if octal (numeric and string only); o Substrings based on character locations: .PARSE string1 string2 symbol1 symbol2 ... = Length of string (string symbols only); Takes string2 as a list of separators, and picks string1 apart. symbol1 gets everything up to the first separator, and so on. - If there are more symbols than separator = if (uppercase) alphanumeric (string characters in string2, the last separator symbols only); character gets reused. - If all separators do not occur IN ORDER in string1, symbols corresponding to the missing separators come back with the null string. = if a number (string symbols only); - Special Numeric Symbol contains the actual number of substrings processed by .PARSE. This includes explicitly null substrings, but not symbols set null because .PARSE could not find any more separators. Page 13 Page 14 For example: o The following relations are valid in a .IF directive: .PARSE "[,]" JUNK1 GROUP MEMBER JUNK2 Satisfied if value of sets String Symbols JUNK1 and JUNK2 null, GROUP to your Syntax symbol is current UIC group, and MEMBER to your current UIC member. -------- ------------------------ = or EQ equal to expression <> or NE not equal to expression > or GT greater than expression 4 CONTROL < or LT less than expression >= or GE greater than or equal to 4.1 Conditional Directives expression <= or LE less than or equal to expression o The general syntax of the Conditional Directive is The expression must be of the same type as the .IFx condition statement symbol. The "statement" (directive, CLI command, or o Tests can be connected using: whatever) is executed ONLY if the condition is satisfied. .OR - satisfied if either condition is met. .IFx condition .OR .IFx condition o There are a number of cases of the conditional directive: .AND - satisfied if both conditions are met. .IFx condition .AND .IFx condition Syntax Satisfied if: ------------------- ------------------ Parentheses after the first .IFx group tests. .IFT symbol symbol is true .IFx .AND (.IFx .OR .IFx) .IFF symbol symbol is false .IFDF symbol symbol defined .IFNDF symbol symbol not defined .IFLOA driver driver loaded .IFNLOA driver driver not loaded .IF symbol rel expr relation satisfied 4.2 Labels .IFINS task task installed .IFNINS task task not installed .IFACT task task active o Are used to identify locations as targets of .GOTO .IFNACT task task not active or .GOSUB directives. .IFT [mask] symbol numeric symbol has any masked bits set o Are formed in the same way as symbol names but do .IFF [mask] symbol numeric symbol has not conflict with them. any masked bits clr o Must occur (at least) once in the same command file Note that: as all .GOTOs or .GOSUBs that refer to them, or you get an error. - The "task"-oriented conditionals are available only in RSX and P/OS. o Need not be unique - but you can get "strange" results if they're not. - The "[mask]"-ed forms of the conditionals are available only under RT. o Come in two flavors: Page 15 Page 16 - Standard labels: o "Computed" GO TO: . Defined by the syntax: - No explicit support for this. .label: (more stuff on same line) - Can be implemented using symbol substitution . Are found by scanning the command file and smart choice of labels, as in: forward from the .GOTO or .GOSUB to the end of the file and then (if the file is on .ENABLE SUBSTITUTION disk) rewinding and scanning forward to the .SETN OPTION 0 .GOTO or .GOSUB directive; .QUERY: .ASKS FILE Which file .ASKN [0:2] OPTION Which option . Substitution does not occur when scanning .GOTO OPT'OPTION' for labels. .OPT0: .EXIT .OPT1: PIP 'FILE'/LI .GOTO QUERY - Direct-access labels: .OPT2: PIP 'FILE'/SP .GOTO QUERY . Defined by the syntax .label: with nothing else on the same line; o "Assigned" GO TO: . Location is cached, and loaded directly - No explicit support for this. when referenced by a .GOTO or .GOSUB directive; - Can be implemented using symbol substitution and smart choice of labels, as in: . If cache fills, earliest defined label is dropped (ie: it reverts to being a .ENABLE SUBSTITUTION standard label); .SETS ASSIGN "LABEL1" . . Obviously, there are no direct-access . labels if the command file is not on disk. . .GOTO 'ASSIGN' . . . .LABEL1: 4.3 Transfer Of Control o "Standard" GO TO: 5 FILE I/O - Syntax: .GOTO label 5.1 Basic File Operations - Unconditionally transfers control to the given label. o Input directives: - The given label must occur in the same command - To open an existing sequential file for input: procedure as the .GOTO that refers to it. .OPENR filename Page 17 Page 18 - To read the next sequential record into a . Labels in a .ENABLE DATA block are String Symbol: recognized during a label search. This is a restriction. .READ symbol . Some versions of the ICP don't recognize If the end of the file is encountered, Special .DISABLE DATA unless it is left justified Symbol is set , and the symbol's in the record. value is untouched. o Output directives: o Miscellaneous file I/O directives: - To open a new sequential file for output: - To close a file: .OPEN filename .CLOSE By default this file has LIST (or ) implied carriage control. You can get other - To close and delete a file (under RT only): possibilities by modifying the special symbol as follows before opening the file: .PURGE .SETN 0 ! No implied carriage control. .SETN 1 ! FORTRAN implied carriage ctrl. o Restrictions: .SETN 2 ! LIST implied carriage control. - There are no I/O directives for relative, indexed, or stream files. You can use RMSDES, - To open an existing sequential file to append RMSCNV, and RMSIFL to convert between these records to it: file organizations and sequential, if it is appropriate to your application. .OPENA filename - There is no way to read more than 132 bytes of If the specified file does not exist, the any file record. effect is the same as .OPEN. - To write a line of text to a sequential file: .DATA text 5.2 Miscellaneous Capabilities - To copy lines from the command procedure to a sequential file: o To operate on multiple files: .ENABLE DATA All file I/O directives will take an optional File Number after the directive, but before any causes all lines in the command procedure to be arguments. For example: written to the output file, until a .OPEN #1 KANGA.ROO .DISABLE DATA .DATA #2 This data goes to File 2. is encountered. Substitution is performed (if The File Number is a hash mark ("#") and a number enabled) before the output lines are written. from 0-3. #0 is the same as omitting the file Note that: number. You can, of course, generate the number by Page 19 Page 20 symbol substitution: . Under RSX and P/OS, this can be disabled with the ".DISABLE TIMEOUT" directive. .DATA #'FILENO' This data is written .DATA #'FILENO' to some file, but . Under RT, this will not work unless you .DATA #'FILENO' which one is not have a system clock, and issue the ".ENABLE .DATA #'FILENO' determined until the TIMEOUT" directive. .DATA #'FILENO' ICP is run. o To determine file attributes (RSX only): - pmp = prompt string. Special Symbol is loaded with the first 7 words of the FCS file descriptor block for the most o All .ASKx parameters are optional - except that recently .OPENed file (as a string of decimal "lo" and "hi" must be either both specified or both numbers, separated by commas). This includes such omitted. useful information as how big the file is, what its largest record is, and more. o Trailing colons in parameter block can be omitted. If all parameters are omitted, the square brackets can be, too. o If the default answer is taken, comes back 6 TERMINAL I/O TRUE. 6.1 .ASKx Operation o If the timeout expires, comes back TRUE. o You can get uppercase conversion on a .ASKS by o The .ASKx directives are used to prompt for and issuing the ".DISABLE LOWERCASE" directive. validate symbol values. o The .ASKx directives always return either a valid value or some specific exception condition. 6.2 .ASKx Exception Handling o Validation failure causes reprompting automatically. You don't get exceptions returned unless you .ENABLE them. Exception conditions which can be trapped in this way o By default, entry of ^Z causes the ICP to exit. are: o Syntax: o .ENABLE ESCAPE .ASK [df:tm] Logical_symbol pmp .ASKN [lo:hi:df:tm] Numeric_symbol pmp - Causes the escape character to be a valid .ASKS [lo:hi:df:tm] String_symbol pmp response for any .ASKx directive. Where: - Special Symbol (and its synonym - lo = lowest valid value (.ASKN) or lowest ) come back TRUE if an escape character acceptable length (.ASKS). is entered. - hi = highest valid value (.ASKN) or highest - This is generally used to break out of the acceptable length (.ASKS). normal logic sequence (eg - to print help text). - df = default value. - tm = timeout on question. o .DISABLE CONTROL-Z (RSX, P/OS only) Page 21 Page 22 - Allows ^Z to be trapped by your command If you do this: procedure. - Each .ASKx displays: - Special Symbol comes back TRUE when a prompt Control/Z has been entered. - "External" comments display: - This is generally used to break out of normal comment text logic sequence (eg - SYSGEN), or with SET /SLAVE=TI: to create captive command - CLI commands are displayed as: procedures. Command o You can get rid of "External" comments and CLI The manual specifies that the default answer is commands completely by: returned for exceptions. Not all versions of ICP support .ENABLE QUIET this. o You can also (of course) .OPEN a terminal for output. 6.3 Miscellaneous Input You can also .OPENR a terminal. This is the only way to do I/O to a terminal other than TI: (RSX, P/OS) or TT: 7 MODULES (RT). 7.1 Internal 6.4 Output o Modules internal to the current command file can be created by using the .GOSUB - .RETURN construction. o By default: o Module entry syntax: - Each .ASKx displays: .GOSUB label arguments >* prompt [parameters]: (under RSX) $ * prompt [parameters]: (under P/OS) * prompt [parameters]: (under RT) o Argument passing: - "External" comments display: - The arguments are available in the reserved >; comment text (under RSX) String Symbol COMMAN. $ ; comment text (under P/OS) ; comment text (under RT) - This contains a literal copy of anything on the .GOSUB command line after the label. - CLI commands are displayed as: >Command (under RSX) $ Command (under P/OS) o Module exit syntax: . Command (under RT) .RETURN o You can disable the extra stuff by issuing returns to the first line after the .GOSUB directive. .DISABLE DISPLAY (Under RSX and P/OS) .DISABLE PREFIX,SUFFIX (Under RT) For example: .ENABLE SUBSTITUTION Page 23 Page 24 .GOSUB STORE Arthur Dent - You can pass results back to the caller in .GOSUB STORE 6*9=42 global symbols, or in Special String Symbol .EXIT by: .STORE: ; The argument is "'COMMAN'". .SETS results .RETURN This displays (under RSX): o You can also chain between command files: >; The argument is "Arthur Dent". >; The argument is "6*9=42". .CHAIN file >@ The only parameter passing is by global symbols, or (under RSX and P/OS only) by using 7.2 External .CHAIN file/LO which causes all local symbols to be preserved in o Other command files can be called just as though the new command file. from the CLI prompt. - The module entry syntax is @file arguments 8 EXTERNAL ENVIRONMENT - The arguments are loaded into reserved String 8.1 What Kind Of System Are You On? Symbols as follows: . COMMAN - Contains the entire invoking o Your operating system type is encoded in Special command line, uppercased and with blank Numeric Symbol (in octal), as follows: compression. = 0 for RSX-11D. . P0-P9 - Are loaded as though by: .PARSE COMMAN " " P0 P1 P2 P3 .... = 1 for RSX-11M. = 2 for RSX-11S (nice trick!). - You can exit the module in two ways: = 3 for IAS. . Return to the calling module. The syntax is = 4 for RSTS (for expansion?). .EXIT status Where "status" is a number to be returned = 5 for AME, or VAX-11 RSX. to the caller in Special Symbol (the default being 1). If executed from = 6 for RSX-11M+. the top level, the ICP is terminated and the status is returned to the parent task = 7 for RT-11 SJ. (if any). The end of the command procedure is equivalent to ".EXIT" = 10 for RT-11 FB (or RTEM-11). . Terminate the ICP. The syntax is = 11 for P/OS. .STOP Page 25 Page 26 o Under RSX, a string describing your operating . Under RT, n1 is the device size as a system type is available in Special String Symbol decimal number, with trailing dot. n2 . This is a new feature, and may or may not through n4 are always zero. be in P/OS and RT. o Under RSX, a string describing your operating - Flags are three letter device status system version is available in Special String indications, separated by commas. One from Symbol . This is a new feature, and may or each group will be returned: may not be in P/OS and RT. . Driver status: o Your system name is available in Special String Symbol LOD, driver is loaded. (for RSX and P/OS) (for RT) UNL, driver is not loaded. By default, this is the name given at SYSGEN. However (at least under RSX) if you are running DECnet, it will contain your DECnet Node Name. . Device status: ONL, device is online. OFL, device is offline. 8.2 The Device Configuration UNK, status is unknown (only by RT). o Determining the status of a driver: . Mount status: - ".IFLOA driver" is satisfied if the driver is loaded. MTD, device is mounted. - ".IFNLOA driver" is satisfied if the driver is NMT, device is not mounted. not loaded. . Mount type (RSX and P/OS only): o Determining the status of a device: .TESTDEVICE name FOR, device is mounted foreign. (where "name" is a physical or logical device name) returns, in Special String Symbol , the NFO, device is not mounted foreign. string "phys,n1,n2,n3,n4,flags" where: . "Publicity" (RSX and P/OS only): - Phys is the physical name of the device. PUB, device is set public. - n1 through n4 represent: NPU, device is not set public. . Under RSX and P/OS, the contents in octal of the words U.CW1 through U.CW4. This is . Allocation (RSX and P/OS only): the same information that is returned by GETLUN in the third through sixth words of NAL, not allocated. the buffer. ALU, allocated to this terminal. Page 27 Page 28 ALO, allocated to another terminal. o Under RSX and P/OS, the state of a task can be checked: Be warned that some versions of the ICP get confused whether to return ALO or ALU. - ".IFINS task" is satisfied if the task is installed. . Attachment (RSX and P/OS only): - ".IFNINS task" is satisfied if the task is not NAT, not attached. installed. ATU, attached by this copy of the ICP. - ".IFACT task" is satisfied if the task is active. ATT, attached by another task. - ".IFNACT task" is satisfied if the task is not active. If the device is not in the system, returns "NSD,". o Under RSX and P/OS, you can check on a partition or common block using .TESTPARTITION partition name this loads Special String Symbol with "name,base,size,type," 8.3 Other Things About The System where: - name = The name of the partition; o Under RT only, you can find out what volume is on a given device by issuing - base = The partition base address in 64-byte .VOL symbol device blocks (octal); which loads the volume label into the string symbol. - size = The partition size in 64-byte blocks (octal); o The current date and time are returned in the Special String Symbols - type = one of the following: - (blank under RT if there is none); SYS (system controlled); -