.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 Emulator User"s Guide''%'
.if t .if e 'tl '%''RT-11 Emulator User"s Guide'
.if n 'tl 'RT-11 Emulator 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 Emulator User's Guide
Version 2.0
.sp
24 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 system which executes RT-11* programs
under the UNIX* timesharing system.
The emulator allows most
relatively "clean" RT-11 programs to run under UNIX with no modifications.
.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.
It is supplied and supported by DEC.
Many installations must develop software for RT-11
systems.
If a UNIX system is available, it would be desirable to conduct software
development under UNIX, since 1) it has extensive program development
facilities, 2) it is time-shared (so that one user does not tie up the whole machine
while text editing or compiling),
and 3)
it has a hierarchical file system which allows software to be organized
and shared among users on a central facility.
This document describes an RT-11 emulator which runs under the UNIX operating
system on the PDP-11.
The emulator allows a large class of RT-11 programs to be executed without
change under UNIX.
Certain programs will
.ul
not
execute, but even these can at least be edited and compiled under UNIX.
.pg
This document assumes some familiarity with both UNIX and RT-11.
.pg
The User's Guide is organized as follows:
.sp
.in +5
.nf
1.	Overview
2.	Invoking the Emulator
3.	Files and Devices
4.	Input Conventions
5.	Memory Organization
6.	Programmed Requests
7.	Limitations
8.	Error Reporting
9.	Performance
10.	Useful Hints
.fi
.in -5
.se OVERVIEW
.pg
Many installations now run the UNIX time-sharing system to support program
development.
Often a number of RT-11 machines also exist which are usually used to run various
experiments, special hardware, etc.
Since RT-11 is a single-user system, program development requires
that the machine not be used for its intended purpose while
a program is keyed in, edited, compiled, and debugged.
Such activity is more conveniently handled on a time-sharing system.
In addition, there are obvious advantages in keeping
all source and
documentation in a central file system.
The UNIX system is especially good for program development, with
powerful text manipulation facilities,
a friendly and flexible user interface,
and an excellent hierarchical file system.
.pg
Because of these considerations, the RT-11 emulator was developed.
The emulator allows RT-11 programs which conform to certain
rules to be run without change on the UNIX system.
Unmodified "SAV" images are directly executed.
Programs such as MACRO, LINK, LIBR, and FORTRAN run without change.
.pg
Sometimes
.ul
UNIX
users would like to run
.ul
RT-11
software.
For example, a number of UNIX installations run DEC MACRO-11 or
FORTRAN-IV+.
Usually these programs have been re-written or modified to run
under UNIX.
Generally each program is quite costly, and is not always up to the
latest DEC version.
The RT-11 emulator allows most DEC software to be run.
The only cost involved is the cost of a DEC binary license.
If one wished to use MACRO-11 as a UNIX assembler, it would be sufficient
to supply some appropriate libraries, and a program to convert
"SAV" images into UNIX "a.out" format.
(This has not yet been done, however.)
Other examples might be a DEC word-processing system, or some standard software
written in DEC FORTRAN.
.su RT-11
.pg
RT-11 is a simple, single-user, "real-time" operating system for the PDP-11.
RT-11 users have full access to the machine, since the monitor does not
protect trap vectors, device registers, or its own code.
.pg
The RT-11 monitor itself (as opposed to utilities, compilers, etc.) supports
various I/O devices and a simple file system.
RT-11 provides a multitude of system calls (known as "programmed requests")
but most are quite simple.
Sufficient system services are available to make it possible to write
programs which do not access trap vectors or device registers.
Programs which are written in this way will run correctly in the
presence of strict operating system protection.
The DEC manuals suggest this style of programming.
Most DEC software is written in this way.
The typical RT-11 FORTRAN user will usually conform to this standard, since he/she
writes programs using the standard library routines.
Only programs which access some specialized device need to violate the standard.
.pg
The RT-11 monitor comes in several flavors.
The single-job or SJ monitor is the most frequently used.
The foreground-background (FB) monitor will support a foreground and a
background job.
The foreground job has absolute priority and a fixed memory location;
there is no "time-slicing" or paging.
The extended-memory (XM) monitor allows a program to access more than the usual
56K bytes of memory via memory management hardware.
Its main fuction is to allow the processing of large arrays of data.
.pg
Only the SJ monitor is emulated.
This allows
development of most RT-11 applications under UNIX.
Programs which depend upon FB system calls are very system-dependent, and
are not likely to be produced by the typical applications programmer.
The XM monitor merely increases the amount of memory available.
Simulation of the FB monitor would be very difficult.
Simulation of the XM monitor would not be difficult,
but has not been done.
.su Features
.pg
The RT-11 emulator:
.in +5
.-
supports RT-11 programs which do not access trap vectors and device registers,
.-
simulates the SJ monitor programmed requests,
.-
provides reasonable access to the UNIX file system, so that standard UNIX
tools can process program text, and
.-
checks for violations of various restrictions (e.g. accessing device registers.)
.in -5
.pg
Only Version 3 of the SJ monitor is supported.
The RT-11
.ul
user
interface (KBMON) is not supported.
(A keyboard monitor which calls upon the emulator is available as a 
separate product.)
.pg
The following RT-11 programs will run under the emulator:
.in +5
.-
MACRO
.-
LINK
.-
LIBR
.-
FORTRAN
.-
EDIT
.-
TECO
.-
PIP
.-
DIR
.in -5
.pg
NOTE:
Only a partial subset of the features of PIP and DIR will work.
Any features which require the direct modification of the RT-11
directory structure can never work.
For example, PIP can not be used to change the creation date of a file.
.pg
Of course, many other RT-11 programs can be installed.
.se "INVOKING THE EMULATOR"
.pg
The RT-11 emulator is invoked via the UNIX command
.it ru.
The command syntax is as follows:
.sp
.bd ru
[
.bd -c
]
[
.bd -e
]
[
.bd -f
]
[
.bd -p
]
[
.bd -w
]
[
.bd -C
.it chainline
]
.if n .ti +3
[
.bd -a
.it physical
.it logical
]
[
.bd -i
.it csiline
]
.it file.sav
.pg
.it Ru
resembles the RT-11 command of the same name.
.it File.sav
specifies the file containing the RT-11 executable program ("SAV" image.)
Before execution the file name may be modified:
If the file name does not contain `.', then ".sav" is appended.
If it does not contain a `/', the "dk0/" is prepended.
If the name starts with "sy?/...", it is modified to read "dk?/...".
If the name starts as "dk/..." it is modified to "dk0/...".
.it Ru
then attempts to run the resulting file.
If it is not found, "/lib/rt11/" is prepended and a second attempt
is made.
Thus the command
.sp
.ti +5
ru macro
.sp
will typically run the file "/lib/rt11/dk0/macro.sav".
If the file "dk0/test.sav" exists, the following will be equivalent:
.sp
.in +5
.nf
ru test
ru test.sav
ru sy0/test.sav
ru dk/test.sav
.fi
.in -5
.pg
The optional arguments
may be ignored in most cases.
One simply uses
.it ru
as if it were the RT-11
RUN command.
.pg
If
.bd -c
is specified, then an error which causes execution to terminate will produce a core dump.
The dump may be examined with
.it db.
.pg
If
.bd -e
is specified, any RT-11 programmed request that returns an error code
will produce a warning message.
This is handy for debugging.
.sp
If
.bd -w
is specified, any RT-11 programmed request which is ignored (i.e. which
the emulator treats as a NOP) will produce a warning message.
This is useful for debugging programs which work under RT-11 but not
under the emulator.
.sp
If
.bd -f
is specified, certain input handling features are enabled which
simulate the behavior of RT-11 input from within RT-11 "indirect" files.
In particular, CSI and GTLIN input always comes from the standard input,
while TTYIN and input from TT: will refer to the user's tty.
(Without this option, all input comes from the standard input.)
In addition,
.bd -p
is implied.
.sp
If 
.bd -p
is specified, CSI prompting is suppressed.
This is useful when input is to come from a shell file.
.sp
.bd -C
indicates that
the chain information area is to be initialized with
.it chainline.
If chainline contains the characters "\\0", a null byte will
be generated.
("\\\\" will generate "\\".)
This is required to pass arbitrary binary data.
.sp
If 
.bd -a
is specified the
.it physical
device name is assigned to the
.it logical
device name.
This simulates the effect of the RT-11 "ASSIGN" command.
The device names do not contain `:'.
The command
.sp
.ti +5
ru -a tt lp test.sav
.sp
will cause references to "lp" during the execution of "test.sav" to
be translated to "tt".
More than one
.bd -a
may be specified.
.pg
If
.bd -i
is specified,
.it csline
is supplied as a CSI command line.
More than one
.bd -i
may be specified.
When the CSI exhausts the
.it cslines,
.it ru
exits.
.pg
.it Ru
provides most of the features of the RT-11 SJ monitor, Version 3.
One executes programs as if the RT-11 "RU" command were being used.
The emulator does not provide the services of the RT-11 Version 3
command interpreter.
Thus, to assemble a program with a listing, one uses:
.sp
.in +5
.nf
ru macro
*prog,lp:=prog
.sp
.ti -5
rather than
.sp
macro/list prog
.in -5
.fi
.sp
(Note:  A command interpreter program is available.
See
.ul
The RT-11 Command Interpreter User's Guide.)
.pg
The
.it ru
command executes RT-11 "SAV" images.
This allows the greatest software portability, since it should not be necessary
to modify any DEC software for use on UNIX.
The program will execute normally until it wishes to call upon RT-11 for
service.
The RT-11 system call (an EMT instruction) will be trapped by the emulator
and translated into the appropriate UNIX system call(s).
.se "FILES AND DEVICES"
.pg
RT-11 programs read and write certain devices, and create files
on "file-structured" (disk) devices.
The emulator provides several simulated devices:
"LP", "TT", "NL", and "DK".
"SY" is also provided as a synonym for "DK".
.pg
The "TT" device refers to the standard input or output.
Its peculiarities are described further in the section on input
conventions.
.pg
The "LP" device refers to the UNIX line printer spooler.
When "LP:" is
opened, output is sent to the UNIX program
.it opr
for later printing.
.pg
The "NL" device is the "null" device, exactly as under RT-11.
.pg
The "DK" device provides a simulation of an RT-11 file structured device.
When
.it ru
is invoked, it generally expects to find directories of the form
"dkn" where "n" is a digit from 0-7.
These directories exist in the current working directory.
Each directory contains simulated RT-11 files; each is used to
simulate a "DKn:" device.
RT-11 file "extensions" are simply characters on the end of a UNIX
file name.
Thus the RT-11 file "DK:ABC.XYZ" corresponds to the UNIX file
"dk0/abc.xyz".
.pg
If a LOOKUP is attempted on a file, and the emulator cannot locate
the file, "/lib/rt11/" is prepended to the file name, and the file
open is repeated.
This allows common files to be stored in a central location.
Thus MACRO will access "DK0:SYSMAC.SML" and will find the file
"/lib/rt11/dk0/sysmac.sml" (assuming the user does not have his/her
own copy.)
.pg
When a file is ENTERed a so-called "tentative entry" is created.
This entry is named with the "permanent" file name suffixed with
the characters ":tmp".
When a file is CLOSEd and made "permanent", the file is renamed.
Thus if "DK:TEST.DAT" is ENTERed, it will exist as
"dk0/test.dat:tmp" while it is open, and will be renamed to
"dk0/test.dat" when it is closed (replacing any previous file
of the same name.)
.pg
Non-file-structured access to the "DK" device is allowed,
however the simulation of the RT-11 internal directory structure is limited.
The simulation is close enough to allow most functions of PIP and DIR
to work correctly.
(NOTE:
The simulated directory structure provides file modification dates rather
than file creation dates.)
Users are strongly advised to avoid non-file-structured access to the
DK devices, since the complete
internal structure of the RT-11 file system is not simulated.
RT-11 files are simulated as normal UNIX files, so that normal UNIX
utilities may operate upon them.
The simulated RT-11 directory only has room for 280 files per "device."
The emulator can be re-compiled to allow more files.
If this is a problem, see your system adminstrator.
.pg
All I/O appears "instantaneous" to the program.
(I.e. normal UNIX I/O occurs.
The program always delays until each I/O operation completes.)
.se "INPUT CONVENTIONS"
.pg
All input via "TT:", TTYIN, and the CSI comes from the standard input,
unless the
.bd -f
option has been specified.
(See above.)
If the standard input is a TTY, then the standard UNIX keyboard editing
conventions apply.
There is no distinction between one and "two consective" interrupt
characters (CNTL-C on an RT-11 system.)
One interrupt kills the program.
.pg
Certain translations do apply:
All input is translated to upper case, and any newline not preceded by
a carriage return is translated to CR-LF.
.pg
When reading from "TT:", a CNTL-Z (octal 032) or the characters "^Z"
will cause an end of file to be read, as will a genuine end of file.
However, remember that CNTL-Z is not an "action character" on UNIX,
as it is on RT-11.
A "^" followed by other than "Z" is ignored, and the next character is
transmitted.
(Thus "^^" is turned into "^".)
.pg
When reading via TTYIN or via the CSI, an end of file causes the
program to exit.
When reading via the CSI, any line that starts with "^" causes
the program to exit.
This is handy for creating shell files, and is similar (but not equivalent)
to the RT-11 indirect file convention.
.pg
Certain bits in the Job Status Word are used to control keyboard input
handling.
The upper/lower case bit and the special tty mode bits are implemented.
The special mode bit causes the user's tty to go into raw mode with
no echo.
Note that the change of tty mode under UNIX can cause queued input characters
to be deleted, so one should not type ahead when using programs which
change the mode bit.
(For example, EDIT changes the tty mode, so one should wait until EDIT
has started before typing commands.)
.se "MEMORY ORGANIZATION"
.pg
The emulator's core area is organized much like that of RT-11.
The user loads into low core, and the emulator is located at the top
of memory.
It is desirable to trap references to the I/O page in order to produce an
error message.
UNIX assumes that the "I/O page" is the normal stack area
(see Fig. 1), but the actual SP would point to a lower area in core.
There is a small amount of accessible memory at the very top address
(where the default UNIX stack lies).
When the emulator starts it moves the SP out of the "I/O page"
to a location just below the emulator code.
However, the initial stack memory remains in the process address space.
Most references to the I/O page are caught, except references to the very
top.
(E.g. an attempt to reference the PS would not be detected.)
The user could accidentally point the stack pointer to the high (I/O) page,
which would also not be detected.
.pg
.nf
.in +8
.ne 12
.cs R 24
-----------   0177776
| stack   |
|    |    |
|    |V    |
-----------  <-- Hole in addresses in virtual memory
|    |^    |
| data,   |
| text    |
-----------   0

.in -8
.ce
Figure 1
.fi
.cs R
.pg
Figure 1 shows the normal core layout of a UNIX process.
The stack grows down from the top as required.
(It never grows smaller, even when the SP goes back down.)
The text-data is loaded at the start, and may grow larger or smaller.
There is a "hole" in virtual memory between stack and data, which are physically
contiguous.
.pg
Figure 2 shows the RT-11 emulator core layout.
The "I/O" page is the top segmentation register reserved for the normal
UNIX stack.
The emulator is at the top of accessible memory, and the program is located
in the remaining low memory.
This is identical to the normal RT-11 layout (except that all of the emulator
is in core at all times.
There is no such thing as "USR swapping".
All necessary emulator routines are permanently resident, i.e. "LOCKed"
and "LOADed".)
The process image is always 56K bytes in length, to simulate the maximum
size RT-11 machine.
.nf
.in +8
.ne 18
.cs R 24
----------------   0177776
|     I/O      |
|     page     |         } Not in address space
----------------   0160000
|              |
|  Emulator    |
|              |
----------------
|    Free      |
|   Memory     |         } 56K bytes total address space
----------------
|              |
|    User      |
|   Program    |
|              |
----------------  0

.in -8
.ce
Figure 2
.sp
.cs R
.fi
.se "PROGRAMMED REQUESTS"
.pg
This section describes the RT-11 SJ V3 programmed requests which will be
implemented.
Requests not described (i.e. FB and XM) are not implemented.
Requests are in alphabetical order.
Please note that this is a description of PROGRAMMED REQUESTS, not
of library routines.
The various standard libraries can also be installed if desired, so that Fortran
users may call IREAD, etc.
.pg
The following programmed requests are implemented:
.sp
.in +10
.ta 10
.sp
.sp
.ti 0
CDFN	\c
Ignored, produces a warning message.
Program must not expect RT-11 internal channel information to appear
in the CDFN space.
.sp
.ti 0
CHAIN	\c
.id
.sp
.ti 0
CLOSE	\c
In order to close an ENTERed file, the emulator must be able to rename
the tentative entry.
If not, a warning message is produced.
See discussion of ENTER below.
.sp
.ti 0
CMKT	Ignored.
.sp
.ti 0
CSIGEN	\c
Lines that Start with "^" cause the program to terminate.
This is useful for the preparation of shell files.
.sp
The current RT-11 monitor takes all file size specifications to be
decimal, and in fact will not accept numbers with decimal points.
The emulator, however, agrees with the DEC documentation.
.sp
.ti 0
CSISPC	\c
See above.
.sp
.ti 0
DATE	\c
The UNIX month and year
.ul
do
roll over correctly.
.sp
.ti 0
DELETE	\c
If the file exists and cannot be deleted (e.g. due to UNIX protection
restrictions) a warning message is printed.
.sp
.ti 0
DSTATUS	The "dk" device
is always an RK05.
The "handler size" is always two bytes.
The "load point" is always non-zero and odd--do not attempt
to use it as an address.
For disks the device size is always 077777.
.sp
.ti 0
ENTER	Unless a specific file size is requested, the allocated size
will be as large as possible (077777).
.sp
ENTER creates a "tentative entry" whose name consists of ":tmp" appended
to the "permanent" file name.
.sp
"Non-file-structured" access to "dk" should not be attempted.
Attempts to write upon the "DK:" device will fail.
.sp
File names may have trailing blanks (for either name or extension)
but may not have embedded blanks.
.sp
.ti 0
EXIT	Terminates the program only.
Does not pass command line to KBMON, etc.
.sp
.ti 0
FETCH/RELEAS	"Handlers" are always "in core".
These calls only check the validity of the handler name (e.g. "DK:").
.sp
.ti 0
GTIM	\c
The clock time is returned in 60 Hz ticks, just as in RT-11.
However, the clock only has 1 second resolution (i.e. it jumps 60
ticks every second.)
.sp
.ti 0
GTJB	\c
The "I/O channel space" is non-zero and an odd number.
.sp
.ti 0
GTLIN	\c
As in the other CSI calls, lines that begin with "^" terminate
the program.
.sp
.ti 0
GVAL	Values
returned try to match RT-11 as closely as possible, but often have
to be faked to look reasonable.
Programs that depend on some of the more obscure bits may not work.
.sp
.ti 0
HERR/SERR	Ignored.
.sp
.ti 0
HRESET	Indentical to SRESET.
.sp
.ti 0
LOCK/UNLOCK	Ignored.
.sp
.ti 0
LOOKUP	\c
Files not found in the local "dk" may be looked up in "/lib/rt11/dk".
This allows things like subroutine libraries to exist in one central
location.
.sp
If the file being looked up is write protected, it will be opened for
reading only, and writes will return errors.
.sp
.ti 0
MRKT	\c
Ignored.
Until UNIX implements alarm clock signals, this will not be implemented.
Since MRKT is usually used to time some user interaction, and take action
if nothing has happened in a certain length of time, this will usually
result in no harm.
It simply gives the user all day to respond.
.sp
.ti 0
PRINT	\c
.id
.sp
.ti 0
PROTECT/
.ti 0
UNPROTECT	Ignored.
.sp
.ti 0
PURGE	\c
.id
.sp
.ti 0
QSET	Ignored.
.sp
.ti 0
RCTRLO	Ignored, "CNTL-O" support is not in UNIX.
.sp
.ti 0
READ/READC/
.ti 0
READW	All I/O is "instantaneous", i.e. synchronous.
I/O is always completed before the request returns.
Completion routines will be called before READC returns.
The status word in a completion routine only supplies the end of file bit.
.sp
.ti 0
RENAME	\c
.id
.sp
.ti 0
REOPEN	\c
See SAVESTATUS.
.sp
.ti 0
SAVESTATUS	\c
The information saved is not the same as that saved by RT-11.
If SAVESTATUS is only used to allow later REOPENing, its behavior is
.id
.sp
.ti 0
SCCA	Produces warning message.
CNTL-C can't be caught.
.sp
.ti 0
SETTOP	\c
.id
.sp
.ti 0
SFPA	\c
See TRPSET.
.sp
.ti 0
SPFUN	Special functions are not supported by any emulated device.
Ignored.
.sp
.ti 0
SRESET	\c
Purges all open files.
.sp
.ti 0
TRPSET	\c
If TRPSET is called, any values in the associated trap vectors are
ignored, even if filled in
.ul
after
TRPSET was called.
.sp
.ti 0
TTYIN	Reads from standard input.
See previous comments about tty conventions.
.sp
.ti 0
TTYINR	Behaves as TTYIN, tty cannot be polled waiting for input.
.sp
.ti 0
TTYOUT	Writes on standard output.
.sp
.ti 0
TTYOUTR	Behaves as TTYOUT.
.sp
.ti 0
TWAIT	Timing is to the nearest second.
.sp
.ti 0
WAIT	\c
.id
(Remember that WAIT will never delay, since all I/O is always complete
by the time WAIT is called.)
.sp
.ti 0
WRITE/WRITC/
.ti 0
WRITW	See READ.
.in -10
.se "LIMITATIONS"
.pg
In this section some restrictions upon emulated programs are summarized,
and some hints for writing programs that will work on future versions
are given:
.in +5
.-
Only the programmed requests described in the previous section may be issued.
Restrictions given there apply.
.-
Only Version 3 EMTs should be used.
Some Version 1 EMTs have been implemented because much of the DEC
software still uses them,
but users should avoid them.
.-
Programs should not issue "TRAP" instructions (which are UNIX system calls.)
A simple modification to UNIX does allow the emulator to handle these,
but this may not be implemented on all systems.
Consult your system adminstrator if you require this feature.
.-
Programs may not reference the I/O page.
.-
Programs may not illegally reference the emulator core area.
"GVAL" should always be used to access values within the emulator.
(In fact, the emulator
.ul
does
arrange that access via offsets works for all offsets documented
in the manual.
One should not trust this to work in all future versions, however.)
.-
RT-11 internal data structures should not be assumed.
For example, programs that inspect the headers of drivers,
I/O queue elements, or data saved by SAVESTATUS may not work correctly.
.-
Trap vectors should not be touched.
For example, TTY I/O does not use the console trap vector.
Some trap vectors (e.g. IOT or BPT) can be filled in and used.
TRPSET and SFPA should be used if possible.
.-
Error messages will not exactly duplicate those of RT-11.
.in -5
.se "ERROR REPORTING"
.pg
All error messages are produced on the standard output.
Messages are of three kinds:
warnings, errors, and fatal errors.
Warnings indicate that something bad has happened, but execution continues.
Errors terminate execution.
Fatal errors should not happen:  they indicate some internal problem.
.pg
All error messages provide a program counter location, which will indicate
where the error occured.
.su "Diagnostic Messages"
.pg
The following messages may be produced:
.in +5
.sp
.ti -5
err code N returned--
An RT-11 programmed request returns the given error code.
.sp
.ti -5
Breakpoint/Trace trap--
A BPT instruction was executed or the trace bit was set.
.sp
.ti -5
Quit signal received--
The UNIX quit signal has been received.
A core dump will follow.
.sp
.ti -5
CNTL-C intercept (SCCA) not supported--
It is not possible to catch keyboard interrupt signals.
.sp
.ti -5
Directory overflow--
A simulated DK directory contains too many files (currently, about 280).
This warning message is produced only when a program attempts to read
the RT-11 disk directory.
The files can still be accessed by programs which do not read the directory,
but DIR and
PIP will have trouble.
Some files should be deleted.
.sp
.ti -5
ENTER rename fails--
This should not happen.
It was not possible to move the "tentative entry" to its permanent name.
.sp
.ti -5
Floating exception--
Floating divide by zero probably occured.
.sp
.ti -5
IOT trap--
An IOT instruction was executed.
.sp
.ti -5
Illegal instruction--
An illegal or reserved instruction was executed.
.sp
.ti -5
Internal EMT--
One of the EMT codes reserved for the RT-11 monitor was executed.
.sp
.ti -5
Invalid or not supported EMT--
An unknown EMT was executed.
.sp
.ti -5
LP spooler missing--
The line printer spooler could not be found.
.sp
.ti -5
REOPEN fff fails: N--
A previously saved file could not be reopened.
The error code is N.
.sp
.ti -5
Reference to I/O page--
The program made a reference to the upper 4K words of memory.
.sp
.ti -5
Reserved EMT--
An EMT reserved for internal use was executed.
.sp
.ti -5
SPFUN not supported--
One may not execute special device functions.
.sp
.ti -5
Trap to 4--
A "bus error" trap was taken.
.sp
.ti -5
Version 1 EMT--
A version 1 EMT was executed which the emulator does not support.
.sp
.ti -5
Can't fork for LP spooler, output discarded--
Too many UNIX processes are running, so the spooler can not be
started.
Try running the program later.
.sp
.ti -5
Can't reopen fff--
Should never happen.
.sp
.ti -5
File fff is gone--
During the execution of a program, the file associated with an active
channel disappeared.
.sp
.ti -5
File fff, unlink fails--
The given file could not be deleted.
.sp
.ti -5
No files--
Should never happen.
.sp
.ti -5
TWAIT too long--
A wait of more than 32767 seconds is not supported.
.sp
.ti -5
Bad CSI command line--
Syntax error or line too long.
.sp
.ti -5
CSI illegal device--
An invalid device was supplied.
.sp
.ti -5
CSI unused--
Should never happen.
.sp
.ti -5
CSI ENTER fails--
The CSI was not able to ENTER a file or device.
.sp
.ti -5
CSI input file not found--
The CSI was not able to LOOKUP a file or device.
.sp
.ti -5
RU filename too long--
The 
.it f.sav
has too many characters.
.sp
.ti -5
RU program not found--
.it F.sav
could not be found.
.sp
.ti -5
Program load fails, invalid sav image--
A "SAV" image does not have the correct format.
.sp
.ti -5
SAV image too large to load--
It just won't fit.
.sp
.ti -5
Channel N not preserved by CHAIN--
All channels should be preserved by a chain, but channel 15 may
be needed if the chained program does overlays.
.sp
.ti -5
CHAIN fails, can't find file--
The file given in a .CHAIN request could not be found.
.sp
.ti -5
CSTAT not implemented--
CSTAT is not allowed by the SJ monitor.
.sp
.ti -5
Device assignment table full--
Too many logical device names.
.sp
.ti -5
CSI line table full--
Too many CSI command lines provided in the argument list.
.sp
.ti -5
CDFN is ignored--
It is not possible to redefine the number of channels.
.sp
.ti -5
MRKT is ignored.
.sp
.ti -5
CMKT is ignored.
.sp
.ti -5
PROTECT is ignored.
.sp
.ti -5
HERR and SERR are ignored.
.sp
.ti -5
QSET is ignored.
.sp
.ti -5
LOCK is ignored.
.sp
.ti -5
RCTRLO is ignored.
.sp
.ti -5
TRAP instruction--
The program executed a TRAP instruction.
(This message is only possible if the "trapcatch" system call is installed
on the system.
If this modification is not installed, execution of a TRAP will cause
undefined results.)
.sp
.ti -5
UNLOCK is ignored.
.sp
.ti -5
/dev/tty cannot be opened for command file init--
If the
.bd -f
option is specified, /dev/tty must be opened.
For some reason it could not be.
This should never happen.
.in -5
.se PERFORMANCE
.su Speed
.pg
The UNIX RT-11 emulator compares well with the performance of the
real RT-11.
Programs which make heavy use of RT-11 system services, or which perform
a lot of I/O
will be a bit slower than the RT-11 version.
For example, a compile and link-edit of a medium size Fortran program
required 1:48 on an RK-based UNIX system, and 1:25 under RT-11 (also
with RK disks.)
.su "Available Memory"
.pg
RT-11 with the usual drivers allows about 46 Kbytes in which to run
user programs.
However, some of that space may be required for USR swapping.
The UNIX RT-11 emulator allows about 42 Kbytes, but this includes
all "drivers" and the "USR".
Nothing is swapped.
.su "Timesharing Impact"
.pg
If numerous emulated RT-11 programs are running simultaneously,
there is likely to be considerable overhead due to swapping,
since each emulator core image occupies 56 Kbytes.
If this is a problem, your system adminstrator can prepare a version
of the emulator with a smaller core size.
.se "USEFUL HINTS"
.su "Common Problems"
.pg
The most difficult problems arise with the use of programs which
do not obey the rules given previously.
If you think you are having such problems, you should:
1)  Make sure the TRAP instruction modification is installed in your
local version of UNIX.  (See your system administrator.)
DEC Fortran, EDIT, and some other programs use the TRAP instruction
when various errors occur.
2)  Try running the program with
the
.bd -w
flag set.
This will give you a report of various programmed requests which are
being ignored, and other warnings.
.pg
When writing Fortran programs, do not use library routines which
would violate the rules for using the emulator.
Besides the obvious routines, one other Fortran library routine
also violates the rules.
The ASSIGN routine reaches inside the monitor to manipulate monitor
tables, and wreaks havoc when run under the emulator.
Use IASIGN instead.
.su "Using Special Devices"
.pg
One often wishes to write programs which access device registers on
non-standard devices.
Much of the development of these programs can still be done under
UNIX.
We suggest that one write a fake interface to the special device, and
compile and test the program under UNIX.
When that works, then one must move the program
to an actual RT-11 machine for final testing.
.sp 4
.ul
Note:
The following sections are of interest to people who wish to run
the emulator as a UNIX command.
Users of
.it rtcom,
the RT-11 command interpreter, may skip the remaining paragraphs.
.sp 1
.su "Examining Core"
.pg
RT-11 provides an Examine command which allows the user to look at
various memory locations.
If the
.bd -c
option was specified for the
.it ru
command,
any error will produce a core dump.
The UNIX
.it db
command can then be used to examine the "core" file.
.su "Closing Files"
.pg
When an RT-11 program terminates unexpectedly, so-called
"tentative" files can be made "permanent" via the keyboard
CLOSE command.
Under the RT-11 emulator, files in the "dk" directories are
"tentative" if they are suffixed with ":tmp".
They can be made "permanent" as in the following example:
.sp
	mv dk0/test.dat:tmp dk0/test.dat
.su "Editing Text"
.pg
Most RT-11 programs require text lines to end with CR-LF, rather
than the single newline (LF) used by UNIX.
Also, most programs by default want input in upper case.
Because of this, a slightly modified version of
.it ed
is supplied, called
.it rted.
This editor translates all input to upper case, and puts carriage returns
on the end of every line when a file is written out.
See the appropriate manual entry for more details.
.su "Using UNIX Text Utilities"
.pg
Because RT-11 text files contain a carriage return at the end of
every line, some caution should be exercised when using programs
like
.it grep.
A pattern match such as:
.sp
	grep "something$" dk0/file.mac
.sp
will probably fail because one must match "something<CR>$".
A solution such as:
.sp
	grep "something.$" dk0/file.mac
.sp
will usually work.
.su "Reading DEC Documentation"
.pg
The latest DEC manuals provide instructions for using programs
under the Version 3 keyboard monitor.
The emulator does not provide this feature, it only provides
run-time emulation.
(One can also use "rtcom", the RT-11 command simulator.)
Under RT-11, one can usually RUN the appropriate utility program
rather than use the keyboard command.
Files and options are entered to the CSI in response to the "*"
prompt.
Appendix B of the
.ul
RT-11 System User's Guide
is useful for translating command options into CSI options.
One should also refer to the chapters describing each program.
