Introduction to the RSX, P/OS, and RT
Indirect Command File Processor
- RX018 -
T. R. Wyant
E. I. DuPont de Nemours
October 8, 1986
Housekeeping -
Outline
Housekeeping
Outline
Goal & Caveats
Acknowledgment
Background
Canned Command Procedures
Approaches to Processing Canned Command Procedures
Invoking the ICP
Contents of an ICP file
Processing a Line of an ICP file
Symbols
What Are Symbols
Logical Symbols
Numeric Symbols
String Symbols
Symbol Substitution
Determining the Characteristics of Symbols
Manipulating Substrings
Control
Conditional Statements
Labels
Transfer of Control
File I/O
Basic File Operations
Miscellaneous Capabilities
Terminal I/O
.ASKx Operation
.ASKx Exception Handling
Miscellaneous Input
Output
Modules
Internal
External
External Environment
What Kind of System Are You On?
The Device Configuration
Other Things About the System
The Context of the ICP File
Executing under Multiple CLIs
Interfacing With Your Own Code
Synchronizing With Tasks
Debugging Aids
Bibliography
Housekeeping -
Goal
Help all listeners to make efficient use of the Indirect Command
File Processor (ICP) under RSX, P/OS, and RT.
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
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. Errors in research and transcription do occur. I
apologize in advance for these, but assume no responsibility for
their consequences.
Housekeeping -
Acknowledgment
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 -
Canned Command Procedures
Canned command procedures are useful to:
Group frequently-issued Command Line Interpreter (CLI)
commands in a file.
Reduce typing.
Drastically reduce typos (and the effects thereof).
Save time (and aggravation).
Create user-friendly or custom interfaces to complex
commands (eg: BRU).
Background -
Approaches to Processing Canned Command Procedures
Integrate into I/O mechanism:
Creates a "batch"-like environment:
Input to programs is in-line to the command
procedure;
Programs think they're running interactively in
most cases, and provided you get all the
input right in the command procedure.
Drawbacks:
Advanced features can require a lot of code
where there isn't room for much.
Examples:
VMS - DCL command procedures;
RT-11 Indirect Command Facility.
Implement in separate task:
Not "batch"-like:
In-line input not allowed;
Tasks need own indirect command facility - or
interface ;
Distinguishes between logic and Command Line
Interpreter (CLI) commands.
Examples:
RSX Indirect Command File Processor;
P/OS Indirect Command File Processor;
RT Indirect Control File Processor.
Our subject is the (RSX + P/OS + RT) Indirect Command/Control
File Processor. This will hereafter be referred to as the ICP.
Background -
Invoking the ICP
To feed a command file to the ICP:
(RSX) >@filename (Default filetype is .CMD)
(P/OS) $ @filename (Default filetype is .CMD)
(RT) . SET KMON IND
. @filename (Default filetype is .COM)
or . IND @filename (Default filetype is .COM)
In all cases the input is to a CLI prompt. "@filename" in
response to some other prompt has nothing to do with the ICP.
For example,
PIP>@filename
feeds the file to PIP's own command processor.
Background -
Contents of an ICP file
Each line of an ICP file is:
An "external" comment:
Begins with ";"
Is displayed when encountered (unless
.ENABLE QUIET is in effect)
Has no other effect
An "internal" comment:
Begins with ".;"
Is not displayed when encountered
Has no other effect
An ICP directive:
Begins with "."
Is interpreted and executed by the ICP
Most of this paper deals with these
A CLI command:
Is any line that doesn't meet the above criteria
Is issued as a command to the current CLI, as though you
typed it. If the current CLI can't handle it,
that's your problem, not ICP's.
Background -
Processing a line of an ICP file
A record (line) in an ICP file is processed in the following
steps:
Read it;
Perform symbol substitution (if enabled);
Decide what category it falls in. If it's an ICP
directive:
Parse the first "word";
Load the overlay that processes it (overlaid
versions);
Complete parsing;
Execute;
Why am I telling you this? Because:
Symbol substitution occurs very early in the processing
of a line. Many "LISP"-ish behaviors of the ICP
are based on this.
Many versions of the ICP are overlaid, so grouping like
operations together can improve performance.
Running an overlaid ICP off a floppy disk can require a
good deal of patience.
Symbols -
What are Symbols?
They are named data stores used by the ICP.
They are not accessible outside the ICP (though the ICP can make
their VALUES available).
Their names are 1-6 RAD50 characters (excluding "."), and MUST
contain at least one non-numeric character.
Note: Certain releases of the ICP have had trouble with
embedded dollar signs, or with symbol names that begin
with a numeric character.
Also note: There are certain predefined Special Symbols,
which are named according to the same convention, but
have their names enclosed in "<>". These do not conflict
with ordinary names.
They come in three flavors:
Logical (True of False);
Numeric (16-bit integer values);
String (0 to 132 bytes).
They can be assigned values:
By computation within the ICP;
By querying the user;
In special cases, by reference or on entry to the ICP.
Their values can be tested.
They are normally local to the command file in which they were
created.
Note: If you .ENABLE GLOBAL, symbols whose name begins with
a "$" are available for the life of the ICP run.
Symbols -
Logical Symbols
Take on the values TRUE or FALSE.
Can be assigned values by:
.SETT symbol (sets it TRUE);
.SETF symbol (sets it FALSE);
.SETL symbol expression (sets it to value of expr.).
Logical expressions consist of logical symbols (or the Special
Logical Symbols <TRUE> or <FALSE>), connected by the
following operators:
! (logical OR);
& (logical AND);
(RSX,P/OS) # (logical NOT);
(RT) ^ (logical NOT).
Expressions are evaluated left to right, without regard
for usual precedence of operators. Operations may be
grouped with parentheses.
Values can be tested by .IFT, .IFF, or .IF directive. These
directives are discussed under "Control".
Can take on values entered from your terminal, using the .ASK
directive. This directive is discussed under "Terminal
I/O".
Substitution yields "T" for TRUE, or "F" for FALSE. Substitution
is discussed later in this section.
Symbols -
Numeric Symbols
Take on 16-bit integer values. These are unsigned.
(RSX,P/OS) - They can be treated as signed values if you
.ENABLE OVERFLOW
(RT) - They are always unsigned.
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);
(RT) .SETT [mask] symbol (Sets the masked bits);
(RT) .SETF [mask] symbol (Clears the masked bits).
Numeric expressions consist of numeric symbols or constants,
connected by the following operators:
+ (addition);
- (subtraction);
* (multiplication);
/ (integer division);
! (bitwise logical OR);
& (bitwise logical AND);
(RSX,P/OS) # (bitwise logical NOT);
(RT) ^ (bitwise logical NOT).
Expressions are evaluated left to right, without regard
for usual precedence of operators. Operations may be
grouped with parentheses.
Numeric constants are octal unless you append a decimal point,
or unless you:
(RSX,P/OS) .ENABLE DECIMAL
(RT) .DISABLE OCTAL
Values can be tested by the .IF directive. This directive is
discussed under "Control".
Can take on values entered from your terminal, using the .ASKN
directive. This directive is discussed under "Terminal
I/O".
The default radix of a symbol is decimal, unless the expression
that computed its value consisted only of octal symbols
and constants. This default radix can be changed by:
.SETO symbol (default radix to octal);
.SETD symbol (default radix to decimal).
Substitution yields the value of the symbol, in the current
default radix of the symbol. Substitution is discussed
later in this section.
Symbols -
String Symbols
Take on the value of a 0-132 byte string.
Can be assigned values by:
.SETS symbol expression (sets it to value of expr.)
If you .DISABLE LOWERCASE, the string is uppercased
before being assigned to the symbol.
String expressions consist of string symbols, substrings, or
constants, connected by the following operator:
+ (concatenation).
Expressions are evaluated left to right. Operations may
NOT be grouped with parentheses, but then with only one
operator, why would you need to?
A string constant is constructed as follows:
"this is a string constant"
(RSX,P/OS) #this is a string constant, too#
The quoting character may not appear in the constant
under any of the systems.
Substrings can be extracted by the construction:
symbol[start:end]
which represents the bytes between the start and end
positions, inclusive. Any valid numeric expression can
be used for "start" and "end". Also, "*" can be used,
representing the last character in the string.
Values can be tested by the .IF directive. This directive is
discussed under "Control".
Can take on values entered from your terminal, using the .ASKS
directive. This directive is discussed under "Terminal
I/O".
Substitution yields the bytes in the string. Substitution is
discussed later in this section.
Symbols -
Symbol Substitution
Occurs only when enabled by .ENABLE SUBSTITUTION. Under P/OS and
RT, substitution is enabled by default. Under RSX, it is
disabled by default.
Is called for by enclosing a symbol name in apostrophes.
If you attempt substitution on an undefined symbol, an error
occurs.
Substitution in an ICP file line occurs BEFORE the line is
parsed. Therefore it can occur anywhere in a line, and
in any kind of line.
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).
Examples (all of which assume .ENABLE SUBSTITUTION):
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 -
Determining the Characteristics of Symbols
Finding out whether a symbol exists:
.IFDF symbol (satisfied if symbol defined);
.IFNDF symbol (satisfied if symbol not defined).
Note: the line
.IFDF symbol ;'symbol'
will result in an error if the symbol is undefined. The
substitution is attempted BEFORE the line is parsed.
Characteristics of a symbol:
.TEST symbol (Causes the following Special Symbol
values to be set:)
<SYMTYP> = 0 if the symbol is a Logical Symbol,
= 2 if the symbol is a Numeric Symbol,
= 4 if the symbol is a String Symbol;
<OCTAL> = <TRUE> if octal (numeric and string only);
<STRLEN> = Length of string (string symbols only);
<ALPHAN> = <TRUE> if (uppercase) alphanumeric (string
symbols only);
<NUMBER> = <TRUE> if a number (string symbols only);
<RAD50> = <TRUE> if a RAD50 string (string only).
Symbols -
Manipulating Substrings
Finding substrings of a string:
.TEST string1 string2 (returns the following Special
Symbol value:)
<STRLEN> = position of first occurrence of string2
in string1, or 0 if it doesn't occur.
Note: the strings may be either string constants or
string symbols.
Also note: Extracting substrings based on character position
was discussed under String Symbols.
Substrings based on character locations:
.PARSE string1 string2 symbol1 symbol2 ...
(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 characters in
string2, the last separator 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.
Example:
.PARSE <UIC> "[,]" JUNK1 GROUP MEMBER JUNK2
sets JUNK1 and JUNK2 null, GROUP to your current UIC
group, and MEMBER to your current UIC member. JUNK1,
JUNK2, GROUP, and MEMBER are all string symbols.
Control -
Conditional Statements
.IFx statement:
Syntax:
.IFx condition statement
The "statement" (directive, CLI command, or whatever) is
executed ONLY if the condition is satisfied.
Flavors:
Syntax Condition satisfied if
------------------- ----------------------
.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
.IF symbol rel expr relation is satisfied
(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
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 - satisfied if either condition is met.
Syntax: .IFx condition .OR .IFx condition
.AND - satisfied if both conditions are met.
Syntax: .IFx condition .AND .IFx condition
Parentheses after the first .IFx to group tests.
Syntax: .IFx .AND (.IFx .OR .IFx)
Control -
Labels
Are used to identify locations as targets of .GOTO or .GOSUB
directives.
Are formed in the same way as symbol names but do not conflict
with them.
Must occur (at least) once in the same command file as all
.GOTOs or .GOSUBs that refer to them, or you get an
error.
Need not be unique - but you can get "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 forward
from the .GOTO or .GOSUB to the end of
the file and then (if the file is on
disk) rewinding and scanning forward to
the .GOTO or .GOSUB directive;
Substitution does not occur when scanning for
labels.
Direct-access labels:
Defined by the syntax
.label:
with nothing else on the same line;
Location is cached, and loaded directly when
referenced by a .GOTO or .GOSUB
directive;
If cache fills, earliest defined label is
dropped (ie: it reverts to being a
standard label);
Obviously, there are no direct-access labels
if the command file is not on disk.
Control -
Transfer of Control
"Standard" GO TO syntax:
.GOTO label
Unconditionally transfers control to the given label.
The given label must occur in the same command procedure
as the .GOTO that refers to it.
"Computed" GO TO syntax:
No explicit support for this.
Can be implemented using symbol substitution and smart
choice of labels, as in:
.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:
No explicit support for this.
Can be implemented using symbol substitution and smart
choice of labels, as in:
.ENABLE SUBSTITUTION
.SETS ASSIGN "LABEL1"
.
.
.
.GOTO 'ASSIGN'
.
.
.
.LABEL1:
File I/O -
Basic File Operations
Syntax for input directives:
.OPENR filename (Open existing file for input.)
.READ symbol (Read the next record into the String
Symbol. If the end of the file is
encountered, Special Symbol <EOF> is
set <TRUE>, and the symbol's value is
untouched.)
.CLOSE (Close the file.)
Syntax for output directives:
.OPEN filename (Open new file for output.)
or
.OPENA filename (Open existing file for append, or
new file for output.)
.DATA text (Writes one record containing the
given text to the file.)
or
.ENABLE DATA (Causes all subsequent lines in the
commend procedure to be written to
the file, down to the corresponding
.DISABLE DATA.
Note: Labels in a data block are
recognized during a label search.
This is a restriction.)
followed by
.DISABLE DATA (Turns off the writing of data to the
file.
Note: Some ICPs don't recognize unless
left justified in the record.)
.CLOSE (Closes the output file.)
or
(RT) .PURGE (Same as .CLOSE, unless the file was
opened with .OPEN - then the file is
deleted.)
File I/O -
Miscellaneous Capabilities
Multiple files:
All file I/O directives will take an optional File
Number after the directive, but before any arguments.
For example:
.OPEN #1 KANGA.ROO
.DATA #2 This data is written to File 2.
The File Number is a hash mark ("#") and a number from
0-3. #0 is the same as omitting the file number. You
can, of course, generate the number by symbol
substitution:
.DATA #'FILENO' This data is written to some
.DATA #'FILENO' file, but which one is not
.DATA #'FILENO' determined until the ICP is
.DATA #'FILENO' run.
Determining file attributes (RSX only):
Special Symbol <FILATR> is loaded with the first 7 words
of the FCS file descriptor block for the most
recently .OPENed file (as a string of decimal
numbers, separated by commas). This includes
such useful info as how big the file is, what
its largest record is, and more.
Terminal I/O -
.ASKx Operation
.ASKx is used to prompt for and validate symbol values.
.ASKx always returns either a valid value or some specific
exception condition.
Validation failure causes reprompting automatically.
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),
Where:
lo = lowest valid value (.ASKN) or lowest acceptable
length (.ASKS) ;
hi = highest valid value (.ASKN) or highest acceptable
length (.ASKS);
def = default value;
tmo = timeout on question:
(RT) This requires a system clock, and a
(RT) .ENABLE TIMEOUT
(RSX, P/OS) This can be disabled with a
(RSX, P/OS) .DISABLE TIMEOUT
All parameters are optional - except that "lo" and "hi" must be
either both specified or both omitted.
Trailing colons in parameter block can be omitted. If all
parameters are omitted, the square brackets can be, too.
If the default answer is taken, <DEFAUL> comes back TRUE.
If the timeout expires, <TIMOUT> comes back TRUE.
You can get uppercase conversion on a .ASKS by:
.DISABLE LOWERCASE
Terminal I/O -
.ASKx Exception Handling
You don't get exceptions returned unless you .ENABLE them.
.ENABLE ESCAPE
Causes the escape character to be valid for any .ASKx
directive
<ESCAPE> (and its synonym <ALTMOD>) come back TRUE
Generally used to break out of the normal logic sequence
.DISABLE CONTROL-Z (RSX, P/OS only)
Allows ^Z to be trapped by your command procedure
<EOF> comes back TRUE
Used to break out of normal logic sequence, or with SET
/SLAVE=TI: to create captive command procedures
The manual specifies that the default answer is returned for
exceptions. Not all versions of ICP support this.
Terminal I/O -
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 -
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 -
Internal
Modules internal to the current command file can be created
by using the .GOSUB - .RETURN construction.
Module entry syntax:
.GOSUB label arguments
Argument passing:
The arguments are available in the reserved String
Symbol COMMAN.
This contains a literal copy of anything on the .GOSUB
command line after the label.
Module exit syntax:
.RETURN (returns to the first line after
the .GOSUB directive.)
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".
>@ <EOF>
Modules -
External
Other command files can be called just as though from the CLI
prompt.
Module entry syntax:
@file arguments
Argument passing:
The following reserved String Symbols are loaded:
COMMAN - Contains entire command line, uppercased
and with blank compression.
P0-P9 - Loaded as though by:
.PARSE COMMAN " " P0 P1 P2 P3 P4 P5 P6 P7 P8 P9
Module exit syntax:
.EXIT status (return to the calling command file)
or
.STOP (terminate the ICP)
"status" is a 16-bit value, returned to the calling
procedure in Special Symbol <EXSTAT>, or to the
parent task (if any). If omitted, it defaults to
1.
The end of a command file is equivalent to a .EXIT
directive.
You can pass results back to the caller in global
symbols, or in Special Symbol <EXSTRI> by:
.SETS <EXSTRI> results
Under RSX and P/OS, you can also chain between command files:
.CHAIN file
The only parameter passing is by global symbols, or by using
.CHAIN file/LO
which causes all local symbols to be preserved in the
new command file.
External Environment -
What Kind of System Are You On?
Finding out what system you are running under:
A reference to Special Symbol <SYSTEM> 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.
A reference to Special Symbol <SYTYP> returns a string
describing the system type. This is a new
feature in RSX, and may or may not be in P/OS or
RT.
A reference to Special Symbol <VERSN> returns a string
describing the system version number. This is a
new feature in RSX, and may or may not be in
P/OS or RT.
Finding out the system name:
The system name is stored in Special Symbol
(RSX,P/OS) <NETNOD>
(RT) <MONNAM>
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.
External Environment -
The Device Configuration
Finding a driver:
.IFLOA driver (satisfied if driver loaded);
.IFNLOA driver (satisfied if driver not loaded).
Finding a device:
.TESTDEVICE name
returns, in Special Symbol <EXSTRI>, 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:
LOD, driver is loaded;
UNL, driver is not loaded.
Device status:
ONL, device is online;
OFL, device is offline;
(RT) UNK, device status is unknown.
Mount status:
MTD, device is mounted;
NMT, device is not mounted.
Mount type:
(RSX,P/OS) FOR, device is mounted foreign;
(RSX,P/OS) NFO, device is not mounted foreign.
"Publicity":
(RSX,P/OS) PUB, device is set public;
(RSX,P/OS) NPU, device is not set public.
Allocation:
(RSX,P/OS) NAL, device is not allocated;
(RSX,P/OS) ALU, device is allocated to this terminal;
(RSX,P/OS) ALO, device is allocated to another terminal.
Note: some versions of the ICP get confused
whether to return ALO or ALU.
Attachment:
(RSX,P/OS) NAT, device not attached;
(RSX,P/OS) ATU, device attached by this copy of the ICP;
(RSX,P/OS) ATT, device attached by another task.
If the device is not in the system, <EXSTRI> returns
"NSD," no such device in this system.
External Environment -
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:
<DATE>, when referenced, returns the system date;
<TIME>, when referenced, returns the system time.
Finding a file:
.TESTFILE file
<FILERR> returns status (1 = success)
If the file was found,
<FILSPC> returns the file name. Some versions
of the ICP have trouble, due to a bug
in RSX SYSLIB module EXPFN.
Finding a task (RSX and P/OS only):
.IFINS task (satisfied if task installed);
.IFNINS task (satisfied if task not installed);
.IFACT task (satisfied if task active);
.IFNACT task (satisfied if task not active).
Finding a partition or common block (RSX and P/OS only):
.TESTPARTITION partition
(where "partition" is a partition name, or "*"
for the partition in which ICP is running)
loads Special Symbol <EXSTRI> with
"name,base,size,type,"
where:
name = name of the partition;
base = base address in 64-byte blocks (octal);
size = size in 64-byte blocks (octal);
type = SYS (system controlled),
USR (user-controlled), or
NSP (no such partition).
External Environment -
The Context of the ICP File
Finding out what terminal you're executing on:
(RSX,P/OS) <TITYPE> (gives device type;
Note that prior to
current release, not
affected by SET /DEV)
(RSX,P/OS) .TESTDEVICE TI: (gives device name)
Finding out current default device:
(RSX,P/OS) .TESTDEVICE SY:
(RT) .TESTDEVICE DK:
Finding out default directory (RSX with named directory support,
P/OS):
<DIRECT> contains current default.
Finding out protection UIC (RSX, P/OS):
<UIC> contains current default.
Note: Under RSX, this Special Symbol returns the default UIC
if there is no named directory support.
Finding out current CLI (RSX only):
<CLI> contains name of current CLI.
Translating logical names (RSX with logical name support, P/OS):
.TRANSLATE logical (returns translation in Special
Symbol <EXSTRI>. <EXSTRI> will
be empty if translation
failed.)
Finding out which indirect command file is executing:
On entry to a command file, Special Symbol <FILSPC>
contains the fully qualified name of the file.
If you want it, you must preserve it in another
string symbol of your choosing.
External Environment -
Executing under Multiple CLIs
RSX users may be faced with the task of writing a command file
that will execute under more than one Command Line Interpreter
(CLI). There are at least the following ways to approach this:
Group CLI commands together in blocks, and execute the
appropriate block. Example:
.ENABLE SUBSTITUTION
.GOTO '<CLI>'
.MCR: PIP *.SAV;*/DE/NM
PIP *.SAV;*/RE=*.DAT;*
.EXIT
.DCL: DELETE *.SAV;*
RENAME *.DAT;* *.SAV;*
.EXIT
Or, force the CLI as desired on entry to the procedure. Example:
.IF <CLI> <> "MCR" MCR SET /MCR=TI:
Or, force individual commands to the desired CLI. Example:
.ENABLE SUBSTITUTION
.SETS MCR ""
.IF <CLI> <> "MCR" .SETS MCR "MCR "
'MCR'PIP *.SAV;*/DE/NM
'MCR'PIP *.SAV;*/RE=*.DAT;*
.EXIT
Or, modify the ICP to set the CLI override bit on entry, and
clear it on exit.
External Environment -
Interfacing With Your Own Code
Passing a single command line into your code:
Under all systems covered, you must run your task as
a CLI command for this to work.
Under RSX and P/OS:
LOGICAL*1 CMDBUF(80)
INTEGER*2 CMDLEN
CALL GETMCR(CMDBUF,CMDLEN)
Notes:
If CMDLEN is negative, no CLI command is
available.
The command name is also passed. You must remove
it yourself.
Under RT:
LOGICAL*1 CMDBUF(80)
LOGICAL*1 CMDPMP(5)
DATA CMDPMP /'C','m','d','>',"200/
CALL GTLIN(CMDBUF,CMDPMP)
Notes:
The command line is terminated with an ASCII
null character.
I know of no way to prevent DCL from munging
around with the command line.
Passing status out:
INTEGER*2 EXSTAT
EXSTAT = 1
(RSX,P/OS) CALL EXST(EXSTAT) ! to exit
(RT) CALL IPOKEB("53,EXSTAT .OR. IPEEKB("53))
(RT) CALL EXIT
Status comes back in <EXSTAT>
Note: The above code seems to be what the manuals call for
under RT-11. However, under the only system available to
me for testing (RTEM-11 V2.0, running RT-11 V5.1), the
only thing that works right is that the ICP is aborted
if EXSTAT is 20 (octal).
External Environment -
Synchronizing With Tasks
The ICP will automatically wait for an external task to complete
for:
(RSX,P/OS) Tasks run with the install/run/remove version of
(RSX,P/OS) the "RUN" command;
(RSX,P/OS) Tasks run as CLI commands;
(RT) All operations.
The ICP will proceed without waiting for an external task to
complete
Under RSX:
If you prefix .XQT to the RUN or CLI command, or
If you RUN an installed task, other than as a
CLI command.
You can resynchronize by issuing:
.WAIT task
Under P/OS:
If you SPAWN the RUN or other CLI command.
There is no way to resynchronize.
Under RT:
There is no support for this.
Debugging
Trace facility:
Prints every ICP directive processed, as well as
every CLI command.
Useful for following control and logic flow, and
finding out where it went wrong.
Turn on trace by:
.ENABLE TRACE
If you invoke the command procedure by:
(RSX, P/OS) @file/TR
(RT) @file/T
directive tracing is done by default. This
is the only way to do a trace in earlier
versions of the ICP.
CLI command suppression:
Causes CLI commands to be NOT emitted to the CLI.
They are displayed anyway, with a comment
marker ("!") in front.
Useful for verifying critical commands generated
by your command procedure, before you turn
it loose on your system.
Suppress CLI commands by:
.DISABLE MCR
(RT) .DISABLE DCL
If you invoke the command procedure by:
(RSX, P/OS) @file/-MCR
(RSX, P/OS) @file/-CLI
(RT) @file/N
CLI commands are suppressed by default. This
is the only way to suppress CLI commands in
earlier versions of the ICP.
Bibliography
"Indirect Command Files for New RSX Users"
Allen A. Watson
RSX/IAS SIG Symposium Handout
Spring 1983 DECUS US Symposium
Pro/Tool Kit Command Language and Utilities Manual
The primary reference for the ICP under P/OS.
P/OS System Reference Manual
Documents calls to EXST and GETMCR.
RSX LB:[1,2]ICP.HLP
On-line help file for ICP. Contains some information
that is not in the manual.
RSX-11 Executive Reference Manual
Documents calls to EXST and GETMCR.
RSX-11 I/O Operations Guide
Documentation for the contents of <FILATR>.
RSX-11 MCR Operations Manual
The primary reference for the ICP under RSX.
RT-11 Programmer's Reference Manual
Documents calls to GTLIN, IPEEKB, and IPOKEB.
RT-11 Software Support Manual
Documents layout of System Communication Area, which
contains the error byte.
RT-11 System Users Guide
The primary reference for the ICP under RT.