.if n .po 12
.hy 14
.nr SE 0 1
.nr SU 0 1
.nr PT 0 1
.de it
.ul
\\$1
..
.	Only works for 2 character arguments
.	The following contains backspace characters
.	Replace when the new nroff is available
.de bd
.if n \\$1\\$1\\$1
.if t .ft B
.if t \\$1
.if t .ft
..
.de hd
.cp
.if t 'tl '-''-'
.ev 2
.ps 9
'sp 2
.tr "'
.if t .if o 'tl 'RT-11 Command Interpreter User"s Guide''%'
.if t .if e 'tl '%''RT-11 Command Interpreter User"s Guide'
.if n 'tl 'RT-11 Command Interpreter User"s Guide''%     '
.tr ""
'sp 2
.ev
..
.de fo
.ev 2
'sp 2
.ps 9
'tl ''Human Computing Resources Corporation''
'bp
.ev
..
.de BE
.wh 0 hd
.wh -6 fo
.nr % 0
..
.de se
.bp
.ps +1
\\n+(SE.
.nr SU 0 1
.nr PT 0 1
.ul
\\$1
.in 0
.ps -1
.br
..
.de su
.br
.ps +1
.ne 8
.sp 2
.nr PT 0 1
\\n(SE.\\n+(SU
.ul
\\$1
.br
.ps -1
..
.de pt
.br
.ne 5
.sp 2
\\n(SE.\\n(SU.\\n+(PT
\\$1
..
.de pg
.br
.ne 2
.sp
..
.de -
.sp
.ti -2
-\\ \\c
..
.de id
Identical to RT-11 SJ.
..
.sp 22
.nf
.ce 100
RT-11 Command Interpreter, Version 2
User's Guide
.sp
May 1979
.sp 5
Michael D. Tilson
Human Computing Resources Corporation
10 St. Mary Street
Toronto, Ontario, Canada
M4Y 1P9
.sp 2
ABSTRACT
.sp
.ce 0
.fi
.in +5
.ll -5
This document describes a program which interprets RT-11* keyboard commands
under the UNIX* timesharing system.
The command simulator allows a large subset of the RT-11 commands to be
used, such as MACRO, COPY, DIRECTORY, EDIT, etc.
.sp
Information contained in this document is proprietary and is not to be
transmitted or reproduced
without permission.
.sp 3
.ps -1
* RT-11 is a trademark of Digital Equipment Corp.
.br
* UNIX is a trademark of Bell Laboratories.
.ps +1
.in -5
.ll +5
.BE
.bp
.ul
INTRODUCTION
.pg
RT-11 is a simple single-user system for the PDP-11.
Although many installations use UNIX as the main software development system,
it is often necessary to develop software for use under RT-11.
There is often also a need to provide RT-11 services to a number of users.
This document describes a system which allows
RT-11 commands to be executed at a UNIX timesharing
terminal.
The UNIX RT-11 command interpreter executes most RT-11 commands by
running the appropriate RT-11 system software.
(This is done by means of the RT-11 emulator program.
See
.ul
RT-11 Emulator User's Guide
for more details.)
.pg
This document assumes some familiarity with both UNIX and RT-11.
However, the next section is written from the RT-11 user's point of view.
One should also consult the emulator documentation before using
the software.
.pg
The User's Guide is organized as follows:
.sp
.in +5
.nf
1.	Getting Started
2.	Overview
3.	Summary of Differences
4.	Command Summary
5.	Errors
.fi
.in -5
.se "GETTING STARTED
.pg
This section is written for the RT-11 user who wishes to run
RT-11 programs under UNIX without really knowing anything
about UNIX.
It might be helpful to read
.ul
A Tutorial Introduction to UNIX,
which is part of the UNIX documentation.
This is not required, however.
.pg
When one first steps up to an RT-11 machine, one often has to
bootstrap the machine before any commands can be typed or
programs run.
Similarly, when one steps up to a UNIX terminal,
a few preliminary steps are required.
First, it is necessary to log in.
Your local system administrator will supply you with an account name
and instructions for logging in.
Once you have logged in, UNIX will print a "%" prompt character.
This indicates that UNIX is ready to accept commands.
You should then type "rtcom" (followed by a carriage return.)
If all is well, UNIX will reply with a "." prompt character.
The system is now ready to accept RT-11 keyboard commands.
.pg
The way in which UNIX handles the keyboard
is somewhat different from RT-11.
Most input is in lower case (and is translated to upper case when necessary.)
The conventions for erasing the last character typed or cancelling a line
are different.
(These conventions differ from site to site, so consult your local system
adminstrator.)
One obvious difference is the handling of the interrupt character
(CNTL-C under RT-11.)
Under UNIX, a single interrupt character
.ul
always
stops the running program.
If you wish to type ahead and queue up a CNTL-C which will be read later
by the CSI, simply type a line consisting of "^C" (caret, upper- or lower-case C,
return.)
When this line is read the action appropriate to a single CNTL-C will be taken.
(NOTE:
the RT-11 text editors EDIT and TECO are able to override UNIX terminal handling.
These programs behave exactly as under RT-11.)
.pg
RT-11 supports various devices.
Under UNIX the devices TT:, NL:, and LP: are supported.
Since UNIX is timeshared,
UNIX arranges to spool output to LP: for printing whenever the
printer is available.
UNIX protects its disk structures from direct access by users.
Under UNIX, there is only one disk device supported, called DK:.
Entire disks are not actually used.
Instead, DK0-DK7 are simulated.
Each user has his/her own set of disks.
All other users' files and all system files (e.g. MACRO.SAV) are
stored elsewhere.
You only need to be concerned about your own files.
(If a copy of another user's program is required, that
is easily arranged.)
.pg
The very first time that you use the RT-11 command simulator, you
will find that you have
.ul
no
disks available.
You should use the INITIALIZE command to initialize the disks you need.
Thus, the very first time you use the system, you will likely type:
.ti +5
INIT DK0:
.br
Remember, you only do this the
.ul
first
time.
INIT will wipe out any files on the specified device if you do it again.
(If you do not INIT DK0:, a DIRECTORY listing will show a listing
of system files.
However, you have no real access to these files.
To prevent confusion, INIT DK0:, which will give you your own
private disk area.)
Once you have created some files, your simulated disks remain "on-line"
forever (or until your system adminstrator decides to remove them.)
You never load (or even touch) an actual disk pack.
(One other advantage of this is that your
system adminstrators will take regular backup copies of all files, so
that you can recover files in the event of an accident.)
.pg
When you have finished a session, you must log off.
First, type the BYE command.
This will cause the RT-11 command interpreter to exit.
UNIX will reply with the "%" prompt.
In response to this, type a CNTL-D character.
UNIX should then respond with its login message.
.pg
Finally, you may notice other minor differences between RT-11 and the
UNIX simulation.
For example, any commands which require direct access to a physical disk device will
not work (e.g. COPY/DEVICE, DIR/VOL.)
Some error messages are different as well.
.pg
Because RT-11 is being simulated, and because UNIX is serving many
users at once, you may find that some commands take longer than expected.
For short commands (e.g. DIR) you may expect response roughly equivalent
to that obtained under a floppy-based RT-11 system.
For longer commands (e.g. MACRO) response will be better -- about
equivalent to an RK-based system.
(There is a fixed overhead for each command because the emulator must
be loaded each time.
This is more apparent on the short commands.)
.se OVERVIEW
.pg
This section describes the basic features of the command interpreter.
.su Usage
.pg
To invoke the interpreter, type
.sp
.ti +8
rtcom [-d]
.pg
The -d option causes the interpreter to print a description of the command
it would execute, rather than actually executing it.
.pg
When the interpreter is starting, it attempts to execute the startup
indirect command file DK0:STARTS.COM, if it exists.
When that is complete, it will print a "." prompt character.
At this point RT-11 keyboard commands may be entered.
The interpreter is intended to run as a keyboard command interpreter.
It is best to run it with its standard input and output being the
terminal.
.su "How it Works"
.pg
Rtcom parses user commands.
For some commands, e.g. DATE and TIME, it executes the desired function
immediately.
For most other commands, e.g. MACRO, the inputs, outputs, and  options
are translated into CSI command strings, and the command is executed by
calling the appropriate RT-11 system program.
For example the command
.sp
.ti +5
MACRO ABC
.sp
will be translated into
.sp
.ti +5
R MACRO
.ti +5
*ABC=ABC
.sp
This command is then executed by
.ul
ru,
the RT-11 emulator program.
.ul
Ru
is a program which supervises the execution of an RT-11 binary SAV file.
Whenever the RT-11 program calls upon RT-11 for service (makes a
"programmed request") the emulator intercepts the request and translates
it into the appropriate UNIX system calls.
.su "Files and Devices
.pg
The UNIX RT-11 simulation system supports only 4 devices:
TT:, NL:, LP:, and DK:.
.pg
The TT: device refers to the user's terminal.
.pg
The NL: device is a "null" device, just as in RT-11.
.pg
The LP: device does not refer to the printer directly, but rather to
the line printer spooler.
Output does not appear on the line printer until the channel associated
with LP: is closed.
.pg
The DK: device is not an assigned device name under this system.
Instead it is the name of a set of
.ul
simulated
disks.
These "disks" are in fact UNIX directories, called dk0-dk7.
The files on each "disk" device are kept in the appropriate directory.
Thus various UNIX file manipulation commands may be applied if desired.
The RT-11 emulator will fake enough of the RT-11 disk directory structure
to make PIP and DIR work properly.
.se "SUMMARY OF DIFFERENCES"
.pg
There are a number of differences between the simulated RT-11 and the
real RT-11.
This section summarizes the differences between the two command interpreters.
(See the
.ul
RT-11 Emulator User's Guide
for a description of the differences from a programming point of view.)
.su "Commands Implemented"
.pg
Not all of the RT-11 keyboard commands are implemented.
Only the commands appropriate to the SJ monitor are implemented.
The COMPILE and EXECUTE commands are not implemented.
One should invoke the appropriate compiler directly.
Any options which would imply direct access to an actual disk device
are not implemented.
For example, COPY/DEVICE will not work.
Most commands which imply direct access to actual machine memory
(e.g. GET, SAVE, START) are not implemented.
Section 4 gives a complete description of the commands which are implemented.
.su "Keyboard Handling"
.pg
The UNIX keyboard editing conventions apply.
All input is in lower case, and is automatically translated to upper case
as necessary.
The line delete and character delete characters are those used by UNIX.
This varies from site to site, so the local documentation must be consulted.
[Some sites in fact use CNTL-U and RUBOUT, so RT-11 users may find no
real differences here.
Consult your system adminstrator.]
CNTL-D is interpreted as an end-of-file, and most programs, including
the command interpreter itself, will exit when one is typed.
There is a certain set of SET TT options in effect.
These options may vary from site to site, and cannot be changed by
the SET command (except in the few cases described later.)
.su "Keyboard Interrupts"
.pg
The UNIX keyboard interrupt (CNTL-C under RT-11) is used.
A
.ul
single
keyboard interrupt
always
terminates execution immediately.
This is equivalent to double CNTL-C under RT-11.
If one types a line consisting of "^C" (caret, upper- or lower-case C, return),
this will behave like a single CNTL-C under RT-11.
When the CSI reads this sequence, the program involved exits.
.pg
(IMPORTANT EXCEPTION:
The editing programs (e.g. EDIT, TECO) are capable of taking over complete
control of terminal handling.
These programs interpret keyboard characters exactly as under RT-11.)
.su "Default Options
.pg
The SET options which are in effect are generally fixed and unchangeable.
Most options involved with LP and TT cannot be changed.
The set of defaults has been chosen to be as convenient as possible for
most users.
.su Abbreviations
.pg
The command interpreter accepts the minimum unambiguous spelling of any
command or option.
Since not all commands are implemented, this spelling may be shorter
than the shortest spelling allowed under RT-11.
If one is writing command files to be transfered to a real RT-11, always
use the spelling recommended in the RT-11 manuals.
.su Factoring
.pg
The factoring feature of the command interpreter is that described in the
documentation for Version 3A of RT-11.
Thus only device names may be factored.
The more general factoring announced in Version 3B is not implemented.
.se "COMMAND SUMMARY"
.pg
This section describes each command which is implemented, and any
differences between it and the real RT-11.
.sp
.in +10
.ta 10
.sp
.ti 0
ASSIGN	\c
.id
However, the DK device is the name of a "physical" device.
.sp
.ti 0
B	\c
.id
.sp
.ti 0
BYE	\c
This command causes the command interpreter to terminate.
Control is returned to UNIX.
All "tentative" files and the core image file are deleted.
.sp
.ti 0
CLOSE	\c
.id
.sp
.ti 0
COPY	\c
The BOOT, DEVICE, SETDATE, DOS, INTERCHANGE, POSITION, and TOPS
options are not implemented.
.sp
.ti 0
DATE	\c
The date can only be printed, not set.
.sp
.ti 0
DEASSIGN	\c
.id
.sp
.ti 0
DELETE	\c
The DOS and INTERCHANGE options are not implemented.
.sp
.ti 0
DIFFERENCES	\c
.id
.sp
.ti 0
DIRECTORY	\c
The DOS, INTERCHANGE, TOPS, VOLUMEID, and DELETED options are not
implemented.
.sp
.ti 0
DUMP	\c
.id
.sp
.ti 0
E	\c
The actual machine memory is not examined.
Whenever a program terminates abnormally (e.g. via trap through location 4)
a core image is produced and saved away.
Rtcom will print a message whenever this happens.
The Examine command examines the core image of the last such program.
The core image is deleted at the end of a session.
.sp
.ti 0
EDIT	\c
.id
The various EDIT programs take control of the keyboard and interpret characters
according to the RT-11 rules rather than the UNIX rules.
Because this involves use of the UNIX system call
.ul
stty,
all type-ahead characters are flushed.
Thus one should not type input to EDIT until the "*" prompt is printed.
.sp
An additional feature has been added.
EDIT/UNIX invokes the UNIX text editor "rted".
No other options should be used in combination with this.
.sp
.ti 0
FORTRAN	\c
.id
.sp
.ti 0
HELP	\c
.id
.sp
.ti 0
INITIALIZE	\c
Only the [NO]QUERY option is implemented.
The only valid devices are DK0-7.
This version of
INIT will NOT accept ^C within indirect files to redirect input to the terminal.
.sp
The very first time rtcom is used, INIT must be executed to create
the UNIX dk directories.
.sp
.ti 0
LIBRARY	\c
.id
.sp
.ti 0
LINK	\c
The DEBUG, LIBRARY, and LINKLIBRARY options are not implemented.
(LIBRARY and LINKLIBRARY are only used with the EXECUTE command, which
is not implemented.)
.sp
.ti 0
MACRO	\c
.id
.sp
.ti 0
PRINT	\c
.id
.sp
.ti 0
R\ and\ RUN	\c
Both are equivalent.
The extra arguments of RUN are not implemented.
If a system program is not found in the directory dk0, a system-wide
directory is searched.
Thus the user does not have to worry about destroying system files on
DK0:, and there is no need for an R  which always loads from SY:.
The RUN command can always find the system program provided that the user
does not have a program of the same name on his/her "private" DK0:.
.sp
.ti 0
SET	\c
Only SET EDIT and SET TT are valid.
.sp
One may SET EDIT to EDIT, TECO, or UNIX.
(See discussion of EDIT above.)
.sp
Only the [NO]CRLF option of TT may be set.
(This setting may be ignored on versions of UNIX which do not have
such a terminal mode.)
Because this involves use of the UNIX system call
.ul
stty,
all type-ahead characters are flushed.
One should wait for the next "." prompt before typing another command.
.sp
In addition, there is a SET MSG feature which is not a standard RT-11
SET option.
This controls certain error and warning messages of the emulator.
.in +15
.sp .5
.ti -10
SET MSG WARN	causes emulator warning messages to print.
For example, "Warning, QSET is ignored."
.ti -10
SET MSG NOWARN	suppresses warning messages.  (This is the
default.
.ti -10
SET MSG ERR	causes a warning message to print whenever
any programmed request returns an error code.
This is useful for program debugging.
.ti -10
SET MSG NOERR	turns this feature off. (Default.)
.in -15
.fi
.sp .5
Any combination of SET MSG options may be in effect.
The SET MSG command is useful in debugging programs which
behave "strangely".
.sp
.ti 0
SHOW	\c
No arguments are allowed.
.sp
.ti 0
TIME	\c
The time may only be printed, not set.
.sp
.ti 0
TYPE	\c
.id
.sp
.ti 0
UNIX	\c
This command invokes a copy of the shell (UNIX command interpreter.)
This allows one to temporarily escape to UNIX.
One should return to RT-11 via a CNTL-D -- do not type "rtcom" again.
(That would start up an additional copy of the command interpreter.)
.in -12
.se "ERRORS"
.pg
Error messages generated by the command interpreter are not
the same as those generated by the RT-11 KMON.
The error messages are of the form:
.ti +5
** Error:  message **
.br
The command interpreter calls the RT-11 emulator to execute most programs.
The emulator produces messages of the form:
.ti +5
**Error at pc=NNNN, message
.br
These messages are described in the
.ul
RT-11 Emulator User's Guide.
.pg
The following is a list of possible error messages:
.sp
.in +3
.sp
.ti 0
Ambiguous command name -- 
Try spelling out at least 4 letters of the command name.
.sp
.ti 0
Ambiguous option name -- 
Try spelling out at least 4 letters of the option name.
.sp
.ti 0
Assign table full -- 
You have made too many device assignments.
DEASSIGN a few.
.sp
.ti 0
Bad examine -- 
You have attempted to examine a region of a core image that does not exist.
(For example, device registers.)
.sp
.ti 0
Can't execute FFFF -- 
The named file could not be executed.
This should not happen.
Contact your system adminstrator if it does.
.sp
.ti 0
Can't nest device factoring -- 
You are trying to be too fancy with factoring.
.sp
.ti 0
Command syntax -- 
The command interpreter can't make any sense out of your command.
.sp
.ti 0
Command too complex -- 
This should only happen in really pathological cases.
Make it simpler.
.sp
.ti 0
Command too long -- 
80 character limit exceeded.
Make it simpler.
.sp
.ti 0
Incorrect arg count -- 
You had too many or too few arguments.
For example, DIFFERENCES takes exactly two inputs.
.sp
.ti 0
Indirect file FFFF not found -- 
You typed @FFFF, and FFFF.COM did not exist, for example.
.sp
.ti 0
Indirect nesting too deep -- 
Maximum of 3 levels.
.sp
.ti 0
Invalid ')' -- 
You can't have one of these without  a preceding left paren.
.sp
.ti 0
Invalid SET --
You tried to SET something which is not supported.
.sp
.ti 0
Invalid argument -- 
Most likely a file name was expected, and you typed something that
could not possibly be one.
(E.g. a 4 character extension, or an illegal character.)
.sp
.ti 0
Invalid assignment -- 
You tried to ASSIGN an illegal device.
.sp
.ti 0
Invalid base -- 
Use an octal number please.
.sp
.ti 0
Invalid device -- 
In a context where a device name was expected, you supplied something incorrect.
(For example, more than 3 characters, or containing non-RAD50 characters.)
.sp
.ti 0
Invalid option -- 
An incorrect option was supplied, or option is in the wrong location.
.sp
.ti 0
Invalid option value -- 
You botched an option with a value.
(An option with a value is one such as COPY/COPIES:3.)
.sp
.ti 0
Invalid use of '+' -- 
This command does not support the use of '+' as a separator.
.sp
.ti 0
Logical name not found -- 
You tried to DEASSIGN a non-existent logical name.
.sp
.ti 0
No closing ')' -- 
If you have an opening paren, you need a closing one.
.sp
.ti 0
No core image to examine -- 
You tried to Examine, but there is no core image.
Remember that you do not have access to physical memory, so you can
only examine the image of a program which terminated abnormally.
.sp
.ti 0
No such command -- 
You spelled it wrong, or that command is not implemented.
.sp
.ti 0
Option does not take a value -- 
The option probably does not take a value, and you supplied one.
(E.g. COPY/NEWFILES:5.)
.sp
.ti 0
Option in wrong position -- 
E.g. you supplied an option on an input file, and the option may only
appear after output files.
.sp
.ti 0
Option requires value -- 
An option requires a value, and you left it out.
.sp
.ti 0
Program terminates with core dump -- 
For example, a trap through location 4 will produce this.
The core image may be Examined.
.sp
.ti 0
System overloaded, try later -- 
Should not happen.
If it does, wait a moment, and try again.
.sp
.ti 0
Too many arguments -- 
You specified more arguments than are allowed.
For example, EDIT takes only one argument.
.in -3
.sp
.pg
In addition to the above messages, there are some messages which identify
themselves as "fatal."
None of these should ever happen, as they indicate serious internal errors.
Such messages should be reported to your system administrator.
