Introduction to the RSX Indirect Command File Processor - RX009 - T. R. Wyant E. I. DuPont de Nemours December 10, 1990 Housekeeping - Outline Housekeeping Background Symbols Control File I/O Terminal I/O Modules External Environment Interfacing With Your Own Code Debugging Bibliography Housekeeping - (1.1) Goal Help all listeners to make efficient use of the Indirect Command File Processor (ICP) under RSX, P/OS, and RT. (1.2) Caveats 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 P/OS V1.0 RT-11 V5.0 (FB and XM) 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. I am not the final authority on the ICP in all its multifarious versions. (1.3) 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. Background - (2.1) Historical Perspective The RSX Indirect Command Processor lets you "can" CLI commands. The same processor (with minor modifications) went with P/OS when it was spun off from RSX. The same logic (modified to fit the different environment) was incorporated into RT-11 three years ago. Background - (2.2) Invoking the ICP To feed a command file to the ICP: (RSX) >@filename (P/OS) $ @filename (RT) . SET KMON IND . @filename or . IND @filename In all cases the input is to a CLI prompt. "@filename" in response to some other prompt has nothing to do with the ICP. Background - (2.3) Contents of an ICP file Each line of an ICP file is composed of one of the following: An "external" comment; An "internal" comment; An ICP directive; A CLI command; (2.4) Processing a line of an ICP file To process a record in an ICP file: Read it; Perform symbol substitution (if enabled); Decide what kind it is. If it's an ICP directive: Parse the first "word"; Load the overlay that processes it (overlaid versions); Complete parsing; Execute. Symbols - (3.1) What are Symbols? Symbols are named data stores used by the ICP. Symbols are not accessible outside the ICP. Symbol names are 1-6 RAD50 characters (excluding "."). Symbols come in three flavors: Logical (True of False); Numeric (16-bit integer values); String (0 to 132 bytes). Symbols can be assigned values: By computation within the ICP; By querying the user; In special cases, by reference or on entry to the ICP. Symbol values can be tested. Symbols are normally local to the command procedure in which they were created. Symbols - (3.2) Logical Symbols Logical Symbols take on the values TRUE or FALSE. Logical Symbols can be assigned values by: .SETT symbol (sets it TRUE); .SETF symbol (sets it FALSE); .SETL symbol expression (sets it to value of expr); .ASK symbol prompt (reads it from terminal). Logical operators: ! (logical OR); & (logical AND); (RSX,P/OS) # (logical NOT); (RT) ^ (logical NOT). Logical Expressions are evaluated strictly left to right. Logical Symbols can be tested using .IFT, .IFF, or .IF. Substitution yields "T" for TRUE, or "F" for FALSE. Symbols - (3.3) Numeric Symbols Numeric Symbols take on 16-bit unsigned integer values. Numeric Symbols can be assigned values by: .SETN symbol expression (sets it to value of expr); .INC symbol (adds 1 to it); .DEC symbol (Subtracts 1 from it); .ASKN symbol prompt (reads it from terminal); (RT) .SETT [mask] symbol (Sets the masked bits); (RT) .SETF [mask] symbol (Clears the masked bits). Numeric operators: + (addition); - (subtraction); * (multiplication); / (integer division); ! (bitwise logical OR); & (bitwise logical AND); (RSX,P/OS) # (bitwise logical NOT); (RT) ^ (bitwise logical NOT). Numeric expressions are evaluated strictly left to right. Numeric constants are normally OCTAL. Numeric Symbols can be tested by the .IF directive. The default radix of a Numeric Symbol comes from the expression that determined its value. Substitution yields the value of the symbol, in its default radix. Symbols - (3.4) String Symbols String Symbols take on the value of a 0-132 byte string. String Symbols can be assigned values by: .SETS symbol expression (sets it to value of expr); .ASKS symbol prompt (reads it from terminal). String operator: + (concatenation). String Expressions are evaluated strictly left to right. A string constant is constructed as follows: "this is a string constant" (RSX,P/OS) #this is a string constant, too# Substrings can be extracted by the construction: symbol[start:end] String Symbols can be tested by the .IF directive. Substitution yields the bytes in the string. Symbols - (3.5) Symbol Substitution Occurs only when enabled (by .ENABLE SUBSTITUTION). Is called for by enclosing a symbol name in apostrophes. Can not do substitution on an undefined symbol. Substitution occurs BEFORE the line is parsed. Under RSX and P/OS, you can get format control by following the symbol name (within apostrophes) by a percent sign ("%") and one or more of the following: D (substitute the decimal value); O (substitute the octal value); Rn (right justify in "n" byte field); Ln (left justify in "n" byte field); Z (fill field with leading zeros); S (signed value); C (do blank compression); X (substitute RAD50 string for number); V (substitute value for first byte, or a byte for value). Symbols - (3.5) Symbol Substitution (continued) Examples Assembling and task building an arbitrary module: .ASKS MODULE What module shall I assemble MAC 'MODULE'='MODULE' TKB @'MODULE'BLD Effects: You are prompted for the name of a module; That module is assembled and taskbuilt. Inserting control characters: .SETN NJUNK 33 .SETS ESCAPE "'NJUNK%V'" Effect: String Symbol ESCAPE now contains an escape character. Using format control to set the size of a field: .SETN NJUNK 1 PIP FILE.'NJUNK%R3Z'/LI Effect: A directory listing of file FILE.001 is produced. Symbols - (3.6) Determining the Characteristics of Symbols Finding out whether a symbol exists: .IFDF symbol (satisfied if symbol defined); .IFNDF symbol (satisfied if symbol not defined). Characteristics of a symbol: .TEST symbol (Causes the following Special Symbol values to be set): = 0 if the symbol is a Logical Symbol, = 2 if the symbol is a Numeric Symbol, = 4 if the symbol is a String Symbol; = if octal (numeric and string symbols only); = Length of string (string symbols only); = if (uppercase) alphanumeric (string symbols only); = if a number (string symbols only); = if a RAD50 string (string symbols only). Symbols - (3.7) Manipulating Substrings Finding substrings of a string: .TEST string1 string2 (returns the following Special Symbol value): = position of first occurrence of string2 in string1, or 0 if it doesn't occur. Substrings based on character locations: .PARSE string1 string2 symbol1 symbol2 ... (separates the first string into substrings at the characters in the second string; the resulting substrings are stored in the given symbols). Example: .PARSE "[,]" JUNK1 GROUP MEMBER JUNK2 sets String Symbols JUNK1 and JUNK2 null, GROUP to your current UIC group, and MEMBER to your current UIC member. Control - (4.1) Conditional Directives Syntax: .IFx condition statement Flavors: Syntax Condition satisfied if ------------------- ---------------------- .IF symbol rel expr relation is satisfied .IFT symbol logical symbol is true .IFF symbol logical symbol is false .IFDF symbol symbol is defined .IFNDF symbol symbol is not defined .IFLOA driver driver is loaded .IFNLOA driver driver is not loaded (RSX,P/OS) .IFINS task task is installed (RSX,P/OS) .IFNINS task task is not installed (RSX,P/OS) .IFACT task task is active (RSX,P/OS) .IFNACT task task is not active (RT) .IFT [mask] symbol numeric symbol has any (RT) masked bits set (RT) .IFF [mask] symbol numeric symbol has any (RT) masked bits clear Control - (4.1) Conditional Directives (continued) Valid relations in a .IF directive: Satisfied if value of Syntax symbol is ------------------- ---------------------- = or EQ equal to expression <> or NE not equal to expression > or GT greater than expression < or LT less than expression >= or GE greater than or equal to expression <= or LE less than or equal to expression The expression must be of the same type as the symbol. Tests can be connected using: .OR - Syntax: .IFx condition .OR .IFx condition .AND - Syntax: .IFx condition .AND .IFx condition Parentheses - Syntax: .IFx .AND (.IFx .OR .IFx) Control - (4.2) Labels Identify locations as targets of .GOTO or .GOSUB directives. Formed like symbol names but do not conflict with them. Must occur in the same command file as all references to them. Need not be unique - but "strange" results if they're not. Come in two flavors: Standard labels: Defined by the syntax: .label: (more stuff on same line) Are found by scanning the command file. Substitution does not occur during label scan. Direct-access labels: Defined by the syntax .label: with nothing else on the same line; Location is cached, and loaded when referenced; If cache fills, earliest label is dropped; Require direct-access media. Control - (4.3) Transfer of Control "Standard" GO TO syntax: .GOTO label "Computed" GO TO syntax: Can be implemented using symbol substitution: .ENABLE SUBSTITUTION .SETN OPTION 0 .QUERY: .ASKS FILE Which file .ASKN [0:2:OPTION] OPTION Which option .GOTO OPT'OPTION' .OPT0: .EXIT .OPT1: PIP 'FILE'/LI .GOTO QUERY .OPT2: PIP 'FILE'/SP .GOTO QUERY "Assigned" GO TO syntax: Can be implemented using symbol substitution: .ENABLE SUBSTITUTION .SETS ASSIGN "LABEL1" . . . .GOTO 'ASSIGN' . . . .LABEL1: File I/O - (5.1) Basic File Operations Input directives: .OPENR filename (Open existing file for input); .READ symbol (Read next record into String Symbol). Output directives: .OPEN filename (Open new file for output); or .OPENA filename (Open existing file for append); .DATA text (Writes the given text to the file); or .ENABLE DATA (Causes all subsequent lines in the commend procedure to be written to the file); followed by .DISABLE DATA (Turns off the writing of data to the file). Other directives: .CLOSE (Closes the output file); (RT) .PURGE (Same as .CLOSE, but deletes the file after closing). Can use the RMS utilities to convert to/from sequential. File I/O - (5.2) Miscellaneous Capabilities Multiple files: Insert File Number after the directive name: .OPEN #1 KANGA.ROO .DATA #2 This data is written to File 2. .CLOSE #3 File numbers must be in range 0 to 3. Determining file attributes (RSX only): Special Symbol has first 7 words of FDB: File size Largest record Record type Implied carriage control (more) Terminal I/O - (6.1) .ASKx Operation .ASKx is used to prompt for and validate symbol values. .ASKx always returns a valid value. By default, entry of ^Z causes the ICP to exit. Syntax: .ASK [def:tmo] symbol prompt (Logical); .ASKN [lo:hi:def:tmo] symbol prompt (Numeric); .ASKS [lo:hi:def:tmo] symbol prompt (String), If the default answer is taken, comes back TRUE. If the timeout expires, comes back TRUE. You can get uppercase conversion on a .ASKS by: .DISABLE LOWERCASE Terminal I/O - (6.2) .ASKx Exception Handling You don't get exceptions returned unless you .ENABLE them. .ENABLE ESCAPE - traps the escape character. (and its synonym ) come back TRUE. Generally used to break out of the normal logic sequence. .DISABLE CONTROL-Z (RSX, P/OS only) - Traps ^Z. comes back TRUE. Used with SET /SLAVE=TI: in captive command procedures. Terminal I/O - (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: (RT). Terminal I/O - (6.4) Output By default: Each .ASKx displays: (RSX) >* prompt [parameters]: (P/OS) $ * prompt [parameters]: (RT) * prompt [parameters]: "External" comments display: (RSX) >; comment text (P/OS) $ ; comment text (RT) ; comment text CLI commands are displayed as: (RSX) >Command (P/OS) $ Command (RT) . Command You can disable the extra stuff by: (RSX,P/OS) .DISABLE DISPLAY (RT) .DISABLE PREFIX,SUFFIX If you do this: Each .ASKx displays: prompt "External" comments display: comment text CLI commands are displayed as: Command You can get rid of "External" comments and CLI commands completely by: .ENABLE QUIET You can also (of course) .OPEN a terminal for output. Modules - (7.1) Internal Internal Module entry syntax: .GOSUB label arguments Argument passing: Reserved String Symbol COMMAN contains the arguments. Internal Module exit syntax: .RETURN Example: .ENABLE SUBSTITUTION .GOSUB STORE Arthur Dent .GOSUB STORE 6*9=42 .EXIT .STORE: ; The argument string is "'COMMAN'". .RETURN This displays (under RSX): >; The argument string is "Arthur Dent". >; The argument string is "6*9=42". >@ Modules - (7.2) External External Module entry syntax: @file arguments Argument passing: COMMAN - Contains entire command line. P0-P9 - Loaded as though by: .PARSE COMMAN " " P0 P1 P2 P3 P4 P5 P6 P7 P8 P9 External Module exit syntax: .EXIT status (return to the calling command file); or .STOP (terminate the ICP). If you exit using the .EXIT directive: contains the passed status; can return results to calling module: .SETS results You can also chain between command files: .CHAIN file The only argument passing is by global symbols, or (under RSX and P/OS only) by using: .CHAIN file/LO External Environment - (8.1) What Kind of System Are You On? Special Symbol returns (in octal): 0 = RSX-11D; 1 = RSX-11M; 2 = RSX-11S (nice trick!); 3 = IAS; 4 = RSTS (for expansion?); 5 = AME, or VAX-11 RSX; 6 = RSX-11M+; 7 = RT-11 SJ; 10 = RT-11 FB (or RTEM-11); 11 = P/OS. Special Symbol returns a string describing the system type. Special Symbol returns a string describing the system version number. Special Symbol (under RSX and P/OS) or (under RT) returns the name given at SYSgen. External Environment - (8.2) The Device Configuration Finding a driver: .IFLOA driver (if driver loaded); .IFNLOA driver (if driver not loaded). Finding a device: .TESTDEVICE name returns, in Special Symbol , the string "phys,n1,n2,n3,n4,flags" where: Phys is the physical name of the device; (RSX,P/OS) n1 thru n4 are octal numbers, and represent (RSX,P/OS) U.CW1 thru U.CW4 for the given device; (RT) n1 is a decimal number (with trailing dot) (RT) which gives the size of the device; (RT) n2 through n4 are zero. Flags are various device status indicators: Driver status (loaded or not) Device status (online or off) Mount status (RSX,P/OS) Mount type (foreign or not) (RSX,P/OS) "Publicity" (Public or not) (RSX,P/OS) Allocation (RSX,P/OS) Attachment If the device is not in the system, returns "NSD," no such device in this system. External Environment - (8.3) Other Things About the System Finding out what volume is on a drive (RT ONLY): .VOL symbol device (loads volume label in symbol). Finding out what time it is: , when referenced, returns the system date (under RT this is blank if there is none);