
RTL/2 USER MANUAL

for use with

DIGITAL PDP-11 SYSTEMS RUNNING RSX-11























This document contains copyright material of
Imperial Chemical Industries plc
and
Natron Software Maintenance Ltd





* Imperial Chemical Industries plc,  1991    All rights reserved.
* Natron Software Maintenance Ltd, 1991  All rights reserved.


1.	INTRODUCTION
1.1	OBJECTIVES OF THIS MANUAL
RTL/2 is a versatile, well-defined, high level programming language developed by ICI and marketed by 
Systems Designers. RSX-11M is a multi-tasking operating system developed by DEC for real time 
applications on the PDP-11 range of computers.
This manual describes the use of each component of the RTL/2 package on the DEC PDP-11 under 
RSX-11M. The package contains three utility programs (including the RTL/2 compiler) and several items 
of run-time support software. These provide a useful set of tools for generating systems. (All of the run-
time support software is also supplied in source format to allow the user if necessary, to tailor particular 
features to suit the specific requirements.)
It is not intended that this manual should provide an introduction to RTL/2 or RSX-11M. An abundance of 
thorough documentation already exists on those subjects; Section 1.3 includes a list of recommended 
literature.
A further aim of this manual is to be an aid to programming in RTL/2, not only as an introductory manual 
but also as an invaluable source of reference for use with more advanced programming. The first time 
user is presented with sufficient information in Chapters 2 and 3 to allow him to rapidly compile, build and 
run a straightforward RTL/2 program. (Error messages are conveniently arranged in a separate Appendix 
to allow you to quickly diagnose any problems.) Separate Chapters describe in detail the use of the 
various package components:
 	how to run the three RTL/2 utilities;
 	how to incorporate the RTL/2 support software into your systems;
 	what mandatory items are required to provide an RTL/2 environment;
 	methods of interfacing with the RSX-11M Executive and I/O facilities;
 	specifications of all of the RTL/2 environment and support software.
The more experienced user will find ample details concerning those items which he may wish to modify 
slightly or adopt as a basis for a private implementation. An attempt has been made to provide a package 
which exhibits an acceptable compromise between sheltering the user from the complexities of the 
underlying operating system while at the same time providing reasonably efficient "hooks" so that the low 
level facilities can be harnessed effectively.

1.2	CONTENTS OF THIS MANUAL
The structure of this document is based around the contents of the RTL/2 release package. Each 
component is discussed in a separate section. Further sections supply details of how to integrate the 
package as part of the user's program development and system generation activities.
The release package consists of three utility programs:
RTL/2 Compiler
translates RTL/2 source input into various forms of output, including 
assembler and source listings;
Linkage Verifier
provides inter-module consistency checking;
Macro Processor
a general purpose text pre-processor capable of tailoring source 
modules before compilation;

and several items of run-time support, some of which are mandatory:
Base Program
establishes the necessary entry environment and returns control to the 
operating system when the program exits;

Control Routines
provide out-of-line functions to support the code generated by the 
compiler  (reduces overall program size by avoiding code duplication)
(These two items are referred to as the Run-Time Environment software; they are always present in any 
RTL/2 program - the remaining items below need only be included with an RTL/2 program when 
necessary)
Standard Stream I/O
character stream mechanism for input/output, with associated set of 
formatting procedures;
RSX-11M Stream 
I/O Support
RSX-11M specific procedures for augmenting standard facilities and 
providing for the opening, closing and switching of files;
RSX-11M Operating 
System Interface
provides RTL/2 access on a one-to-one basis to the executive directives 
and I/O services;
Mathematical 
Routines
set of standard mathematical functions;
RMS-11 Interface
permits ready access to Record Management Services with minimal 
run-time overhead.
Further sections are dedicated to describing user program generation, the demonstration programs, error 
messages and other items relevant to the use of RTL/2 under RSX-11M.
The Chapters describing the utility programs (compiler, linkage verifier, macro processor) have been 
arranged around a basic skeleton in an effort to increase clarity and enable the user to refer quickly to the 
relevant information:
 	Introduction
 	Running the Utility
 	Switches (and run-time options)
 	Examples
 	User of command files and other implementation details.
Supplementary information has been placed in the appendices with references in the main text indicating 
where further details may be useful.
The sections on the Run-Time Support provide detailed specifications of the software supplied and 
include useful hints and guidelines on how the standard material may be adapted to cater for particular 
applications.
Once a reasonable level of proficiency has been attained and the basic approach to using the RTL/2 
software has been mastered, two sections of this manual will be of particular use, namely:
 	Section 3, User Task Generation
 	Appendix D, Error Messages
These have been carefully compiled to assist the user in his day-to-day program development activity.

1.3	PRE-REQUISITES AND RELATED DOCUMENTS:
The RTL/2 development package is designed for the development of programs under RSX-11M and 
therefore the host machine configuration must support this operating system. The limiting factor on core 
size is the compiler which requires a minimum 21K word partition.
This manual assumes a familiarity with the use of the RSX-11M operating system and in particular the 
standard RSX-11M utilities for program preparation and file manipulation (e.g., EDI, PIP, MAC and TKB).
The formal specification of the RTL/2 programming language is contained in:
	RTL/2 Language Specification	(RTL/2 Reference 1);
a more digestible presentation can be found in:
	RTL/2 Training Manual	(RTL/2 Reference 3);
and a pocket summary is provided by:
	RTL/2 Language Reference Card	(RTL/2 Reference 26).
Associated RTL/2 Standards are described in:
	RTL/2 System Standards	(RTL/2 Reference 4)
	RTL/2 Standard Stream I/O	(RTL/2 Reference 5).
These define the conventions adhered to in all standard RTL/2 implementations.
This manual may also contain references to other RSX-11M and RTL/2 documents when their content is 
relevant to the material being discussed. 

2.	THE RTL/2 COMPILER
2.1	INTRODUCTION
The PDP-11 RSX-11M host compiler validates and translates RTL/2 programs into PDP-11 assembly 
language for execution under RSX-11M. This section describes the overall features of this RTL/2 
compiler, providing details of how it is used on PDP-11 systems.
The major features of the RTL/2 compiler are:
 	thorough syntax checking of programs
 	good recovery after error detection to minimise the number of compilations necessary to produce a 
'clean' listing
 	full implementation of the language, including floating point arithmetic and machine code inserts
 	generates optimised code
 	array bound checking options for program checkout
 	generated assembler heavily commented with references to the RTL/2 source code.
All RTL/2 compilers are built from three major components; a 'front-end' which validates the program and 
generates an intermediate form of the program, a 'back-end' which generates code for a specific 
machine, and an interface which holds the symbol tables.
The front-end is completely machine independent. It uses the method of recursive descent to analyse a 
program.
The back-end is specific to the target machine (in this case PDP-11 under RSX-11M). It uses table driven 
optimisation techniques to generate good quality code.
The RTL/2 language is always fully implemented; where the target machine lacks suitable instructions, 
for example, floating point instructions, the compiler generates calls to out of line 'control routines' which 
make good the deficiencies.
Object code is generated in the form of an assembler module. The compilers automatically annotate the 
assembler with references into the source code to assist the user.

The compilers can detect over 200 distinct types of error. Good recovery after a detected error means 
that the compiler can scan a large proportion of the program in a single run, thus minimising the number 
of runs typically required to produce an error-free compilation.
The machine-independent, common front-end imposes some restrictions on all implementations of 
RTL/2. These limitations (mainly concerned with sizes) should not cause significant problems for typical 
program modules, but are presented here for reference:
Names
      maximum of 31 characters
Constants
a)  maximum integral value is 2224-1
      (maximum of some 67significant decimal digits)
b)  -128 | number of decimal places exponent | 127
c)  -128 | binary scale | 127
Options
      integer key must be in range 1..15
Arrays
a)  maximum dimension is 16
b)  maximum bound is 32767
      Repetition factors must be in the range 0..32767
Blocks
a)  maximum number per module is 255
b)  maximum depth of nesting is 15
External references
maximum number of separate EXT bricks referenced from within     
one brick is 50
External specification
maximum number of distinct MODE names used in an externally 
known brick is 15
Security
some scope checks cannot be performed absolutely and potential 
dangers can only be flagged for the programmer to check

The restrictions on external references and modes may be relaxed by amending a configuration module 
(supplied in source form) and rebuilding the compiler. The installation instructions (supplied with each 
delivery) should be consulted for details.
The following back-end restrictions are imposed by this implementation of RTL/2 on the PDP-11.
Integers are restricted to 16 bits.
Reals have a maximum modulus of 2127
Arrays: maximum number of dimensions = 8
Blocks: maximum depth of nesting = 15
Procedure calls: maximum depth of lexically nested calls is 24.
Strings: maximum number of strings is 250.
Size of a single databrick: 32K bytes.
The space available for compiler interface tables is by default divided into proportions for the various 
resources as below:
Ratio
Resource
Unit Cost 
(Bytes)
  1
Array bound pool
  2
  8
Identifiers
16
  7
Generated Labels/Mode Information
2/1
56
Name Characters
  1
  4
Constant Pool
  1
20
String Pool
  1
  7
Distinct Names
  2
* Space used by the front-end for the mode information is re-used by the back-end to store generated 
label addresses.
When a module under compilation would otherwise overflow the limits of one or more of the resources 
(but not all of them), the user may reserve specific amounts of particular resources, after which the 
remaining space is divided in the standard ratio for other resources; (this is achieved by use of the /TA 
switch, explained in 2.3).
If the total of the explicit demands cannot be met then a catastrophic front-end error will occur. It is 
possible to change the total space allocated for the tables by amending a configuration module (supplied 
in source form) and rebuilding the compiler. The installation instructions (supplied with each delivery) 
should be consulted for details.
Code inserts are permitted within procedure bricks of RTL/2 programs compiled in systems mode. These 
contain PDP-11 machine code instructions which may refer to various RTL/2 items by the use of trip 
characters. Refer to Appendix E for a fuller description of the use of code inserts on the PDP-11.

2.2	RUNNING THE COMPILER:
The RTL/2 compiler is normally built and installed with the task name "...RTL" so that it may be run by a 
command of the form:
	RTL command string
or
	RTL
in which case, the compiler will prompt with
	RTL2>
and await a command string. Indirect command files may be supplied in place of command strings, 
prefacing the file name by an '@' sign (refer to Section 2.5).
Compiler command strings have the form:
	Ospec1, Ospec2, Ospec3 = Ispec1, Ispec2, .....
where
	Ospec1 is the assembler file
	Ospec2 is the listing file
	Ospec3 is the cross reference file
	Ispec1... are the source input files in the order of processing.
All files except Ispec1 are optional.
The default file extensions are:
	Assembler output		.MAC
	Listing Output			.SRC
	Cross reference output		.XRF
	Source input			.RTL
The input datasets consist of one or more RTL/2 source files which together constitute one RTL/2 
compilation module. This allows compile time concatenation of standard declarations, taken from a 
system library, with a particular program.
The listing file consists of:
 	line numbered source program listing
 	compilation error messages, if any
 	program size summary
 	concordance listing (optional) of declaration and use of variables by line number
 	summary of compiler resources used.

The cross reference file contains information used by the RTL/2 Linkage Verifier to perform inter-module 
consistency checks (refer to Section 4 and Appendix A for further details).
Each compilation module is thoroughly checked for compiler detectable faults. Errors are output to the 
listing file. Compiler error messages are documented in Appendix D.
Compilation can be controlled in two ways:
a)	By means of OPTION statements embedded in the source program
b)	By means of the switches appended to the command line used to invoke the compiler.
Switches and options are described in the following Section.
Following the RSX-11M convention, after a compilation initiated by a reply to the prompt "RTL2>" the 
compiler outputs a prompt to commence a further compilation.
2.3	SWITCHES (AND OPTIONS):
2.3.1	Switches:
The following switches may appear, in any order, after any file specification in the command string:
Switch
Values
Effect
/AS
Y
Causes an ASECT directive to be produced.
/CN
F
Full (systems) language.
If omitted, application language assumed.
/CO
Y
A concordance listing is produced.
/CS
name
Supplies operand for CSECT directive.
If /AS, /CS and /PS are all omitted, then a blank CSECT 
is generated.
/DB
Y
Generate Symbolic Debug output file - see Reference 
RTL133 for details.
/DS
name
<*attribute*attribute>
Default name is DATA.
See below. 
/EI
Y
Causes generation of code to use EIS unit where 
applicable. Note: EI switch always overrides EI option.
/FO
Y
Causes entry to the Fortran 'Middle End' (see below)
/ID
name
Supplies operand for IDENT directive. The paired 
delimiters are not to be supplied in the switch value.
/OP
oplist<:oplist>
Where oplist is:
         (number) options
to over-ride source OPTION statement(s) - see below
/PS
name
<*attribute*attribute>
Generated a PSECT directive with the specified name 
(up to 6 characters). Default name is PROCS.
See notes for /DS switch for further details of attributes. 
/RE
N
Absolute module (default is relocatable).
/RO
Y
Allocate the string pool and procedure bricks to a 
PSECT PROCS, and all data bricks to a PSECT DATA.
/RS
name
<*attribute*attribute>
Causes string pool to be placed in the named PSECT 
with the specified attributes. Default name is DATRO.
See notes below on I- and D- space tasks.
/SE
Y
Has the same effect as: 
/PS:PROCS*I*RO/DS:DATA*RW/RS:DATAS*D*RO/EI:
Y
/SP
-
Spools the listing file direct to the printer.
/SS
-
Omits a copy of the source text from the listing file
- error messages, brick sizes, etc. are still produced.
/TA
See below
See below.
/TI
name
Supplies an operand for the TITLE directive.
If omitted then no TITLE directive is produced.
/XX
-
Continue command input on next line. (See below).
Notes:
I- and D- space tasks (RSX-11M+ USERS ONLY)
The /DS switch is used to generate a task that uses both I- and D- space active page registers (APR's).
The switch causes the procedure bricks to be included in one psect (instruction) and the data bricks in 
another psect (data). Default names for these psects are PROCS and DATA respectively, however the 
user can specify a name for the data psect by supplying a name with the /DS switch, and a name for the 
instruction psect by using the /PS switch.
The /RS switch must also be used, to put the string pool in a separate psect, which must have attribute 
'D' specified.
The attributes for psects are described in the DEC MACRO-11 reference manual.
To generate an I- and D- space task, the attribute 'D' must be specified with the /DS switch.
The /SE switch provides a useful shorthand for the above, provided the default attributes are acceptable. 
Note that I- and D- space code is not compatible with either the Symbolic Debug switch or with the trace 
option.
Note - the /ID switch MUST be used when task building to generate and I- and D- space task - see DEC 
TASK BUILDER manual for further details.
Example:
RTL FRED,FRED = FRED/DS:*D*RW/RS:*D*RO	(or = FRED/SE:Y)
Effect: -		Procedure Bricks 	in .PSECT PROCS, I
		Data Bricks		in .PSECT DATA,D,RW
		String Pool		in .PSECT DATRO,D,RO

/FO Switch
The /FO switch is used to flag certain external procedures that have been written in DEC Fortran (or 
some other language that is implemented using the DEC procedure calling convention). The compiler 
produces special code for any calls to such procedures, see Appendix F for details.
/OP Switch
The /OP switch is used to override or control OPTION statements in the RTL/2 source text. Each oplist is 
supplied to the option statement in the format.
		(opnumber)Opitem*opitem...
Where the opnumber is as specified in the source RTL/2 statement, and valid opitems are as described 
below.
/TA Switch
Using the /TA switch, the following resources may be adjusted:
Array bound pool
Constant Pool
Distinct names
Generated labels/mode information
Identifiers
Name characters
String Pool
The values to be used are given following the appropriate initial letter, preceded by a colon, e.g.,
	/TA:N1400:D320
sets a limit of 320 distinct names, and 1400 name characters.
The default table sizes are listed in the 'resources' section of the source file (.SRC) output by the 
compiler, along with actual usage for the compiled module

/XX Switch
If the /XX switch is present the command prompt will be repeated and the command line may be 
continued. However, the following restrictions apply:
1.	The total command input line length is restricted to 200 characters.
2.	Each line must have a valid command string format.
Examples:
RTL2>FREDS, FREDS = FRED1/XX
RTL2> , FRED2, FRED3/CN:F
Note that the comma is required on the second line to comply with the command string syntax.
PSECT SWITCH PRECEDENCE
The following precedence rules are used with the following switches:-
1)	/DS /PS /RS /SE
2)	/RO:Y
3)	/AS:Y
4)	/CS:name
If switches of more than one precedence level are specified, those of the lower precedence are ignored 
and a warning message is generated (B 204).
2.3.2	Options
The RTL/2 OPTION statement specifies directives to the compiler, controlling various code generation 
options. Every option statement contains an option number, and a sequence of opitems. Opitems 
available for this implementation are shown in the table below.
Each option statement replaces the previous one; any opitems not explicitly mentioned are then reset to 
their default values.
Options can be overridden by the compile-time /OP switch described above.

In addition to the standard 'opitems' (BC and BS) applicable to all RTL/2 implementations, further opitems 
specific to this compiler are available. In an OPTION not containing a particular opitem, the default value 
will be taken. The full set of opitems is as follows:
Opitem
Interpretation
Default Value
BC
array bound checks applied in 'safe' cases 
(gives full checks in application language)
array bound checks omitted in 'safe' cases
BS
array bound checks applied in 'unsafe' 
cases in systems language
array bound checks omitted in 'unsafe' 
cases in systems language
EI
coding to use EIS unit will be generated 
where applicable
extensive use of control routines for 
multiplication, division, and arithmetic shifts.

FP
coding to use FIS will be generated where 
applicable
all floating point operations will use control 
routines
NC
minimal comments only generated in 
assembler code
full comments generated
RB
relocatable brick - the code generated is 
such that ENT bricks can be assigned 
anywhere in memory
bricks contiguous in memory
(this is the normal practice)
SL
'slow' code - control routines called via 
TRAP rather than JSR;
slower but more compact code;
not supported when I- and D- space code 
is being generated.
all control routines entered via JSR;
faster but longer code
TR
BPT instructions included in assembler 
code to provide run-time line number 
monitoring;
not supported when I- and D- space code 
is being generated

no run-time line tracing
XN
allow the '$' and '_' characters to be used 
in identifiers;
prohibit the use of '$' as a synonym for the 
inequality symbol '#', and in strings
interpret '$' and '_' as specified in standard 
language specification,
i.e. '_' as an illegal RTL/2 character,
       '$' as a synonym for the symbol '#'

XW
if XN is not enabled then report on any use 
of '$' as a synonym for the symbol '#';
if XN is enabled then report on any use of 
'$' and '_' in identifiers
no reports generated either for '$' used as a 
synonym for the  symbol '#', or for '$' or '_' 
used in identifiers.
Notes:
BC and BS give the user control over two types of run time array-bound checks. A 'safe' case is one 
where even if the bounds are violated no corruption of the software structures can occur - an example is 
reading out of an integer array. An 'unsafe' case is one where corruption can occur - any store operation 
is unsafe and reading for an array of references is also unsafe because the value obtained may, when 
used as an address, cause corruption.
BS allows the user to apply bound checks in the unsafe cases only. BC allows the user to apply bound 
checks in the safe cases only. If both options are specified, all bound checks will be performed. In the 
applications language, checks are always applied in the unsafe cases, and so BS is only useful in the 
system language.
It should be noted that in the case of a constant subscript of any array accessed directly (that is not via a 
ref array variable) checks are always carried out at compile time and never at run-time.
OPTIONS may be altered at compile time as detailed in Section 2.3.1. However, it is only possible to 
affect OPTION statements within the source program, and it is therefore good practice to include at least 
one OPTION statement in every RTL/2 module.
The XN (extended names) and XW (extension warnings) options allow the user to exploit a language 
extension ('$' and '_' characters permitted in identifiers) and control reporting of usages of this extension. 
The detailed effects of these options are as follows:
XN not enabled
With XN not enabled, '_' will be reported as a non-RTL/2 character and '$' will have its standard 
interpretation as synonymous with '#' and '$'.
If XW is also not enabled then the compiler will behave as a standard implementation of BS5904. Thus 
with none of the new options enabled the standard specification is followed. This means that existing, 
working modules may be re-compiled with no changes to the source or compiler command-line.
If XW is enabled then warning reports will be issued for each use of '$' as a synonym of '#' (i.e., for each 
use of '$' as a comparator, within a compound comparator, or as a string-insert delimiter). Thus, by 
enabling XW on each OPTION statement within a module a user may generate warnings for potentially 
incompatible use of '$' and, if these warnings are resolved by substitution of '#', confidently produce 
modules which will compile through both standard and extended implementations.
XN Enabled
With XN enabled, '_' will be allowed in names (with the status of a letter, but subject to the restriction that 
leading, trailing or consecutive underscores are illegal), '$' will no longer be interpreted as a synonym of 
'#' but will be allowed in names (with the status of a letter), and '$' will be illegal in strings (i.e., in spite of 
losing its interpretation as a string-insert delimiter, it will not be allowed as a string-character). Thus, by 
ensuring that '$' is not used as a synonym for '#' or included in strings, and enabling XN on appropriate 
OPTION statements within modules, users may conveniently develop new programs using the extension.
If XW is enabled in this context the compiler will generate warning reports for each use of '_' in names, 
and for each use of '$' in names. Thus a user wishing to convert a module using the extension, to make it 
compatible with old implementations of the compiler, may readily locate actual uses of the extension as 
an aid during conversion by simply enabling XW on appropriate OPTION statements within the module.

2.4	EXAMPLES
To compile RTL/2 source files
HOLDA.RTL, HOLDB.RTL, HOLDC.RTL
naming the resulting output 'HOLD', and suppressing listing of text in the listing output file:
RTL HOLD,HOLD,HOLD=HOLDA,HOLDB,HOLDC/SS/TI:HOLD
To compile a module DISCIO using the full systems language (permitting code inserts), and omitting the 
listing output file:
RTL DISCIO,,DISCIO=DISCIO/CN:F/TI:DISCIO
To obtain a source listing with concordance output (describing where and how names are defined and 
used) of a module BIGPROG, omitting assembler and cross-reference outputs:
RTL ,BIGPROG=BIGPROG/CO:Y
To compile a module QIKRUN, extending the mode information pool to 500 and applying all array bound 
checks to OPTION (1) statements in the source program:
RTL QIKRUN,QIKRUN,QIKRUN=QIKRUN/TA:G500/OP:(1)BC*BS/TI:QIKRUN
Note that the filespecs may also include a device and UIC specification, e.g.,
LB:[1,100]MAIN.RTL
however, take care when explicitly stating a different UIC and/or device as the new settings will override 
the defaults for the remaining datasets on the command line.
2.5	USING COMMAND FILES
Command strings may be stored in indirect command files; two levels of indirection are supported by the 
compiler. As an example, to compile a series of RTL files PROG1, PROG2 and PROG3 the following 
construction could be used:
RTL @COMPILE
where COMPILER.CMD contained:
PROG1=PROG1/TI:P1
PROG2=PROG2/TI:P2
PROG3=PROG3/TI:P3
Alternatively commands to run the compiler may be included in MCR indirect command files; consider the 
following:
@BUILD
where BUILD.CMD contained:
RTL PROG1,PROG1=PREFIX,PROG1/TI:P1
MAC PROG1=PROG1
TKB @PROG1.LNK

2.6	EXIT STATUS CODE
The exit status code returned by the compiler can be checked from within an MCR indirect command file. 
The values returned are:

0
Warning
RTL errors 202-206

1
Success


2
Error
RTL errors 101-194

4
Severe error
RTL errors 1-28, or environmental errors 9950-9999
The errors are described in Appendix D.
2.7	WORKFILE USAGE
The compiler requires the use of a temporary work area which is normally deleted after use. This area, 
which must hold up to 32K bytes of data, will be either a private (anonymous) region in memory or a 
temporary file on disc. The user selects which of these alternative approaches will be used when building 
the compiler, see the Installation Instructions for details.
If a memory work area is required then the compiler will attempt to allocate a suitable region when it is 
invoked. Should this attempt fail several times then the compiler will exit with an error message. If, 
however, a disc file is needed then the compiler will attempt to obtain 64 contiguous blocks. If this fails, 
64 non-contiguous blocks will be searched for and, should even this fail, compilation will fail with an error 
message.
LUN 2 is used for the disc workfile and it may benefit the user to redirect LUN 2 to a device other than 
SY:. This may be done by altering the task build file or (at a later stage) as the operator requires.  The 
workfile should, in general, be put on the fastest device available. Note that if the compiler is interrupted 
by system failure, or ABORTed, the workfile must be found using the /LO function of the VFY utility, after 
which the generated directory entry can be removed by PIP. (The file itself is marked for deletion 
(OPNT$D used) and will disappear when VFY accesses it).
2.8	LOGICAL UNIT NUMBERS (LUN'S)
LUN
Usage
1
Terminal/command input
2
Workfile (if on disc)
3
Input (RTL/2 source program)
4
Output MACRO program
5
Output listing
6
Output cross-reference information
7
Unrecoverable error messages

3.	USER TASK GENERATION
3.1	INTRODUCTION
This section describes the necessary compilation, assembly and task build sequence to generate an 
RTL/2 task to be run under RSX-11M on the PDP-11. It refers to other sections of this manual, where 
appropriate, and assumes familiarity with the RSX-11M task builder manual.
Generation of programs for operating systems other than RSX-11M is not dealt with here. Users wishing 
to run their programs under other operating systems should consult:
The RTL/2 Run-Time Environment on the PDP-11    (Ref: RTL39) 
for guidance on implementing their own software.
Following an example of building a simple task several RSX-11M techniques are discussed (e.g., 
shareable libraries) with reference to their applicability to RTL/2 tasks.
3.2	COMPILATION
The use of the RTL/2 compiler is described fully in Section 2 (Appendix D includes a list of all of the 
possible error messages). Frequently, a standard preamble file is used with the RTL/2 source input to 
provide common definitions required by several of the modules that form the complete RTL/2 program. 
Within the RTL/2 distribution package a source statement library file RTLSTD.RTL is provided containing 
examples of the following:
1.	EXT PROC statements for the RTL/2 routines provided in the Interface Library, the Stream Support 
Library and the Standard Stream I/O Library.
2.	MODE statements for the data structures required to utilise the above routines.
3.	SVC DATA bricks for standard RTL/2 and RSX-11M specific usage.
This file should be viewed by the user as a source of useful RTL/2 statements. It should be edited to 
extract the specific lines required by the user, to avoid overfilling the names table.

3.3	ASSEMBLY
Output from the compiler will normally be assembled with the RSX-11M MACRO assembler. If desired, 
other compatible assembly environments may be used.
3.4	TASK BUILDING
3.4.1	Modules and Libraries Required
The modules to be included in the task build may be divided into two categories:
*	mandatory items
*	optional items
(As an alternative to including the modules directly they may be accessed from a shared region which 
includes them.)
The mandatory items are the 'Control Routines' and the 'Base Program'. The control routines supply run-
time support to the compiler-generated code and as such are bound intimately to the compiler's 
conventions. The so-called base program is in fact constructed of two parts. Together they supply task 
initialisation, error handling and other miscellaneous features necessary to interface RTL/2 programs with 
the host environment.
These modules are:
*	base program (parts 1 and 2)
*	control routines
all of which are contained in the library RTLRTSRSX.OLB.
The optional items include the stream I/O formatting and support procedures and the RSX-11M interface 
library. The stream I/O package obeys the RTL/2 standards defined in RTL/2 Reference 5. The character 
and formatted I/O routines defined there have been augmented by procedures which allow the user to 
open and close datasets and switch channels without having to be familiar with the rather complicated 
RSX-11M I/O interface. If the user wishes to utilise the full power of the RSX-11M operating system, 
which means interfacing at a lower level, the RSX-11M Interface Library provides a set of procedures for 
calling the basic executive and file system functions. To work at this level the user must be familiar with 
the system at a low level. These modules are:
*	RTLRTSRSX.OLB - stream formatting procedures
*	RSXIO.OLB - stream I/O support procedures
*	Stream I/O data areas - (see below)
*	RTLEXC.OLB - RSX-11M interface procedures

The third optional item must accompany RSXIO when the procedures for opening, closing and switching 
datasets are required. This module provides the data areas used by the stream support procedures and 
may be configured to match the program requirements. (A suitable module allowing 4 streams is provided 
with the delivery - SAREA4.OBJ). Refer to section 7 for a full discussion of the need for this module and 
instructions on how to generate a set of versions.
A further collection of less frequently used run-time support software is also available; these include the 
maths routines, and RMS interface. Refer to the respective sections for a list of the modules to be 
included when these items are required.
Note that where some of the above are built into a resident library, the symbol tables are used as input to 
the task builder, instead of the actual object modules, in the usual RSX-11M fashion.
3.4.2	Stack
Stack space is allocated at task building by the STACK option of the task builder (STACK=256 words by 
default).
The STACK brick and STACK variable concepts of RTL/2 are not supported and should not be used. 
They may be of use to users building under RSX-11M for other target systems.
3.4.3	Logical Units
Any required task-build time assignments to logical units may be made, remembering that RRGEL will 
use LUN 1 for error messages by default. This can be changed by the user. Although RTL/2 programs 
are often built with an ASG = TI:1 directive, this is not always advisable as the Indirect Command File 
Processor uses LUN 1 for its own purpose making it unavailable to the user. An alternative could be ASG 
= TI:5.

3.4.4	Example
TKB @MTYTEST
where MYTEST.CMD is as follows:
	MYTEST/CP,MYTEST/-SP = MYTEST
	@TKBETC
	/
	PAR = GEN
	TASK = ...MYT
	STACK = 300
	ASG = TI : 1 : 2
	//
and TKBETC.CMD is as follows:
	RTLRTSRSX/LB:RSXBA1:RSXBA2:RTLCTL
	RTLRTSRSX/LB
	RSQRT, RLOGE, RSIN, RATIN, REXP
	RTLEXC/LB
This produces a checkpointable task MYTEST.TSK, which uses the maths routines as well as the normal 
modules required, and produces a map file which is not spooled. Of course the text in TKBETC.CMD 
could be substituted in MYTEST.CMD in place of the line @TKBETC.
In general, there are no restrictions governing the use of the task builder OPTION input except that 
STACK space must of course be adequate, and at least LUN 1 assigned to a suitable error message 
device.
3.5	SHAREABLE LIBRARIES
3.5.1	Supporting Software
Support software - file control services etc., for RSX-11M as well as the RTL/2 RSX-11M support 
software - may be built into shareable libraries in the usual way.
3.5.2	RTL/2 Written Code
RTL/2 procedures are compiled into re-entrant code and are thus ideally suited for the generation of 
shareable libraries

3.5.3	Shared Regions Under RSX-11M
Before embarking on the creation of a shared region, the user should be thoroughly familiar with the 
section of the 'RSX-11M Task Builder Reference Manual' which deals with the topic.
Problems may arise if the same PSECT name is incorporated both inside and outside the shared region.  
Therefore, if the use of shared regions is anticipated, it is advisable to provide distinctive .PSECT names 
for all compiled user modules via the /PS or /CS switch. Problems may also arise if different items from 
the same library are used inside and outside the shared region. In this case it would be advisable to 
create a special copy of the routine with a unique PSECT name for use within the shared region.
Accessing in RTL/2 uses global symbols rather than PSECTS, so the /LI switch should be used at task 
build to minimise conflicts even if the shared region contains data.
RTL/2 code is not always position-independent (examples of position dependency are ref variables and 
multi-dimensional arrays). It is recommended that the same APRs are used in task building a shared 
region and in building the tasks which map the shared region. Alternatively, the shared region should be 
built absolute (using the -PI switch) which again implies some rigidity in the use of APRs.
3.5.4	Access to Private Data from Shared Code
This is best achieved by passing reference parameters to the shared code or by means of reference 
variables in SVC data. To achieve the latter, the user must alter the base-2 program to globally define the 
SVC data brick (by defining an offset for the start of the brick on the stack). As an example, refer to the 
stream I/O support procedures.
These techniques are suggested where a large, system-wide extension to SVC data would prejudice 
memory requirements.
3.6	Common Data Blocks
Users may reference common data blocks by including EXT DATA descriptions in RTL/2 programs and 
resolving these references at task build.
The common data regions may be wholly or partly defined in RTL/2 ENT DATA bricks, compiled, 
assembled and task-built in the usual way.
Common in this context means data which is shared between a number of separate tasks, i.e., an RSX-
11M shared data area.

Where addresses of data are passed between tasks, the regions should be built absolute. Users having 
mapped systems with access to the APRs via mapping and windowing directives may, of course, pass 
addresses of 'relocatable' data between tasks.
3.7	Programs with Overlays
The RSX-11M overlay description language may be used to build overlaid programs. The RTL/2 compiler 
generates .PSECT and .CSECT directives, so that particular sections of a program can be manipulated 
at task build by the .PSECT directive in the overlay description language.
Users may choose manual or auto loading for overlay segments. If manual loading is chosen, suitable 
code to invoke the $LOAD routine must be written by the user.. An outline of such a method follows.
Assuming a definition of the form:
EXT PROC RSXLOA (INT EFN, REF RAD5ONAME SEGMENT) INT;
<with MODE RAD5ONAME (INT NAME1, NAME2):>
where EFN is an event flag number and SEGMENT points to the name of the segment to be loaded, 
suitable code might be as follows:
RSXLOA:	JSR	1,RO1
	.WORD	20,-4	;procedure entry
	MOV	R0,-(SP)	;save reg.
	MOV	*SEGMENT(R5),-(SP)	;addr of segment name part 1
	MOV	(SP),-(SP)	;duplicate
	ADD	#2,2(SP)	;addr or second half
	MOV	@2(SP),2(SP)	;name from address of name
	MOV	@(SP),(SP)	;name from address of name
	MOV	*EFN(R5),-(SP)	;Event flag for $LOAD
	MOVB	#3,1(SP)	;length of param block in words
	SWAB	(SP)	;length of lower byte
	MOV	SP,R0	;pointer to parameter block
	CALL	$LOAD
here, the condition code may be tested for success and the event flag waited for
	MOV	(SP)+,R0	;restore reg.
	JSR	1,R03	;return success or fail indicator
	.WORD	4
	.END

When using the "Autoload" technique for overlays provided by the RSX-11M task builder, the RTL/2 
programmer must be careful in the use of procedure variables.
Do not put ENT/EXT procedure names into a procedure variable as, in general, the autoload will not 
happen before the procedure is called.
For example, consider 'Module 1' to contain:
EXT PROC ( ) FRED,HARRY;
...
DATA PROCVAR;
	PROC ( ) JIM;
ENDDATA
...
ENT PROC RRJOB ( );
	JIM:=FRED;
	JIM( );
	JIM:=HARRY;
	JIM( );
ENDPROC;
where 'Module 2' contains FRED and 'Module 3' contains HARRY.
An appropriate ODL might be Module 1-*(Module 2,Module 3).
However, the modules containing FRED and HARRY will not be loaded before calling as the code 
generated for a call of 'JIM( )' is
	JSR	@PROCVAR+0
and PROCVAR is not in the Autoload vector.

4.	THE LINKAGE VERIFIER
4.1	INTRODUCTION
In general a loadable RTL/2 program is produced in the following three stages:
 	compile RTL/2 modules into assembly code
 	assemble
 	build a loadable program with base programs and system libraries.
Any undefined labels, multi-defined procedures, etc., discovered by stage 3, will necessitate the source 
being edited and the three stages being repeated. Some errors will not be identified by any of the stages, 
e.g., an 'EXT' brick specification differing from the 'ENT' definition of that brick.
The Linkage Verifier is a program which can be run between stage (a) and stage (b).. It will report all 
intra-module consistency errors including those not detected by the above three stages.
The remainder of this section describes the use of the Linkage Verifier under RSX-11M. The errors 
reported are described in Appendix D.
The Linkage Verifier operates on cross-reference files generated by the compiler or hand-coded by the 
user. The data interpreted by the Verifier is described in Appendix A.
Note that the use of the Linkage Verifier is not mandatory. However, its use is highly recommended when 
a new program is being built for the first time or after substantial changes have been made to a 
functioning system.
4.2	RUNNING THE LINKAGE VERIFIER
The Linkage Verifier is normally built and installed with the task name "...RLV", so that it can be run by:
	RLV command string
or	RLV
In the latter case the Linkage Verifier outputs the prompt:
	RLV>
and awaits a command string.

Command files can also be used as described in Section 4.5.
The command string has the following format:
	.Ospec = Ispec1, Ispec2....
where:
	Ospec is the output listing file
	Ispec1, Ispec2.... are the input cross-reference files.
Note that the comma preceding Ospec is mandatory.
The default extensions are:
	Ospec			.LKL
	Ispec1, Ispec2....	.XRF
The use of switches in the command string is described in Section 4.3 and the errors reported by the 
Linkage Verifier are described in Appendix D.
When the Linkage Verifier has read the cross-reference files specified in the command string, it outputs 
another prompt and awaits further input, thus:
	RLV>
The user then has the choice to respond with file specifications for further cross-reference files which are 
to be read, thus:
	RLV> =Ispec3,Ispec4
or to respond with a carriage return to indicate that no further input is to be read, and any unsatisfied 
linkages should be reported.
When the verification is complete the program will display
	VERIFICATION OK
or	VERIFICATION FAILS
according to whether any errors have been detected. The Linkage Verifier will then output a further 
prompt for a command string to commence a new verification run thus:
	RLV>

Cross-reference files are produced by the RTL/2 compiler when a third output file specification is present 
(see Section 2.2).
Alternatively the assembly language programmer may hand code cross-reference files according to the 
rules in Appendix A.
Cross-reference data for the system libraries:
	RTLRTSRSX	RSXIO		RTLEXC
is held in the file RTLXRF and should be input for every verification.
4.3	SWITCHES
Three switches are recognised by the Linkage Verifier:
Switch
Value
Effect
/SS
Y
Short listing only - list any verification errors, but not cross-reference 
input files.
 Note: this switch must appear on the first command line without a /XX 
switch (i.e., the final line of the initial command).
/XX
-
Continue command on new line.
 Note: there is a limit of 200 characters applicable to a command line 
"lengthened" by this mechanism. However, this limit presents no 
practical problem since further input dataset specifications may be 
entered in response to further prompts issued by the Linkage Verifier.
/SP
Y
Spool listing file to line printer.

4.4	EXAMPLES
a)	Verify a very large number of files using continuation command lines and spooling output listing 
of the source cross-reference data.
RLV
RLV>,MANFILES/SP=FILEONE,FILETWO,(123,456)FILETHREE/XX
RLV>,FILEFOUR,DKO:(123,123)FILEFIVE.XRF/XX
RLV>,FILESIX,FILESEVEN;3.FILEEIGHT
the verifier now reads those files and asks for more:
RLV>=SY:(123,123)FILENINE.XRF;2,FILETEN/XX
RLV>,FILEELEVN,FILETWELV,FILETHRTN
and more:
RLV>=FILEFRTN,FILEFIFTN
and to signify no more:
RLV>
the response to which is carriage return.
b)	Verify 3 files producing only an error listing on the terminal.
MCR>RLV
RLV>,TI:/XX
RLV>=FILEONE/XX
RLV>,FILETWO,FILETHREE/SS
RLV>
4.5	USING COMMAND FILES
Command strings may be stored in indirect command files. Only one level of indirect command file is 
supported by the Linkage Verifier. E.g., to perform two separate verifier runs:
	RLV @RLVCOM1.CMD
or	RLV
	RLV>@RLVCOM1.CMD
where	RLVCOM1.CMD contains:
		,FILES/SP=FILE1,FILE2/XX
		,FILE3
		blank line to terminate input
		,MOREFILES/SP=FILE10,FILE11,FILE12
		blank line to terminate input
RSX-11M indirect files are not so useful, since single line command format will not provide the Linkage 
Verifier with a blank line. However the following example shows the extra level of indirection being used 
to achieve the same effect as the example above:
	@RLVCOM2
where	@RLVCOM2 contains:
		RLV @RLVCOM1
4.6	EXIT STATUS CODE
The exit status code returned by the Linkage Verifier can be checked from within an MCR indirect 
command file. The values returned are:

0
Warnings
Verifier Messages 6 and 9

1
Success


2
Error
All other verifier messages

4
Severe error
Environmental errors 9950-9997
Linkage Verifier errors are described in Appendix D.
4.7	LOGICAL UNIT NUMBERS
The Linkage Verifier running under RSX-11M uses the device independent file control services. The 
logical unit numbers used for the various data sets are as follows:

LUN
USAGE

1
Terminal/command input

2
Unused

3
Cross-reference input

4
Unused

5
Listing/error output

6
Unused

7
Unrecoverable error messages

5.	THE MACRO PROCESSOR
5.1	INTRODUCTION
The RTL/2 Macro Processor is a generalised text pre-processing facility which allows parameterised 
macros and conditional processing blocks. The source input may contain arbitrarily nested macros and 
conditional blocks thus permitting extensive processing to be performed. A full description of the Macro 
Processor language is given in Appendix B.
The Macro Processor may be run before compilation in order to tailor source modules. Its use under 
RSX-11M is described in the remainder of this section.
5.2	RUNNING THE MACRO PROCESSOR
The Macro Processor is normally built and installed with the task name "...RMP" so that it can be run by a 
command of the form:
	RMP command string
or	RMP
In the latter case the Macro Processor outputs the prompt
	RMP>
and awaits a command string.
Command files can also be used as described in Section 5.5.
The command string has the following format:
	Ospec1,Ospec2 = Ispec1,Ispec2....
where
	Ospect1 is the processed output file (e.g., generated for input to the
	compiler)
	Ospec2 is the line numbered listing
	Ispec1,Ispec2.... are the source input files in the order of processing
All files except Ispec1 are optional.

The default extensions are:
	Ospec1		.RTL
	Ospec2		.SCL
	Ispec1,Ispec2....	.CND
The use of switches in the command string is described in Section 5.5 and the errors reported by the 
Macro Processor are described in Appendix D.
Following the RSX-11M convention, after a Macro Processor run initiated by a reply to the prompt 
"RMP>", the utility outputs a prompt to commence a further run.
5.3	SWITCHES
Three switches are recognised by the Macro Processor:

SWITCH
VALUE
EFFECT

/SS
Y
Short listing only -list any Macro Processor  errors, but not 
source text.
Note: This switch must appear on the first command line 
without a /XX switch (i.e., the final line of the command).

/XX

Continue command string on a new line - this switch should be 
appended to the final dataset specification of each line except 
the final line.
Note: There is a limit of 200 characters applicable to a 
command line "lengthened" by this mechanism

/SP
Y
Spool listing file to line printer
5.4	EXAMPLES
RMP MOD1,MOD1=MOD1
This command string causes the file MOD1.CND to be macroprocessed into the file MOD1.RTL with a 
full listing sent to MOD1.SCL, all in the current directory on the current device.

RMP MOD2.MAC= 20,1 MOD2.TXT,MT1:MODD2
This command string causes the file MOD2.TXT in UIC (20,1) on the current device to be concatenated 
with the file MODD2.CND on tape drive 1 under the current UIC, the whole to be macroprocessed, 
leaving the result in MOD2.MAC on the system device under the current UIC. Error messages (if any) will 
be sent to the console by default.
RMP MOD3,MOD3/SP=MOD3A,MOD3B,MOD3C/XX
RMP ,MOD3D,MOD3E,MOD3F/XX
RMP ,MOD3G,MOD3H/SS
This command string causes the files MOD3A.CND through MOD3H.CND to be concatenated and 
macroprocessed, leaving the result in MOD3.RTL and spooling an error listing via MOD3.SCL to the line 
printer. All files assumed to be on current device under current UIC.
5.5	USING COMMAND FILES
Command strings may be stored in indirect command files. Only one level of indirect command file is 
supported by the Macro Processor. For example, to macroprocess three files, separately:
RMP @RMPCOM1.CMD
or
RMP
RMP>@RMPCOM1.CMD
where
RMPCOM1.CMD contains
	FILE1,FILE1/SP=FILE1
	FILE2,FILE2/SP=FILE2
	FILE3,FILE3/SP-FILE3
Commands to run the Macro Processor may also be stored in command files; e.g.,
@RMPCOM2
where
RMPCOM2.CMD contains
	RMP FILE1,FILE1/SP=FILE1
	RMP FILE2,FILE2/SP=FILE2
	RMP FILE3,FILE3/SP=FILE3
or
	RMP @RMPCOM1.

5.6	EXIT STATUS CODE
The exit status code returned by the Macro Processor can be checked from within an MCR indirect 
command file. The values returned are:

0
Warnings


1
Success


2
Error
Macro Processor errors 20 - 43

4
Severe error
Environmental errors 9950-9997
All Macro Processor error messages are self-explanatory; they appear in the listing file immediately after 
the line causing the error.
5.7	WORKFILE USAGE
The Macro Processor requires a temporary work area in the same way as the compiler. See Section 2.7 
for details.
5.8	LOGICAL UNIT NUMBERS
The macro processor running under RSX-11M uses the device independent file control services. The 
logical unit numbers used for the various datasets are as follows:

LUN
USAGE

1
Terminal/Command Input

2
Workfile (if on disc)

3
Input text

4
Output text

5
Listing/error output

6
Unused

7
Unrecoverable error messages

6.	RUN-TIME SUPPORT
6.1	INTRODUCTION
The RTL/2 package for RSX-11M provides a comprehensive set of run-time support facilities. Some of 
these facilities are mandatory for building a task, the inclusion of others depends on the facilities used by 
the RTL/2 program. The mandatory items are the Control Routines and the Base Program.
The control routines provide run-time support to the compiler generated code and, as such, are bound 
intimately to the compiler's conventions. They are described at the user level in Section 6.2.
The base program supplies task initialisation, error handling and other miscellaneous features necessary 
to interface RTL/2 programs with their environment. It is divided into two parts so that its major part can 
be included in a shareable library. They are described at the user level in Sections 6.3 and 6.4.
The RSX-11M implementation of SVC DATA bricks (see RTL/2 Language Specification, Ref RTL1) is 
described in Section 6.6. The base program (in RSXBA2) is responsible for allocating part of the task's 
stack and establishing the initial values of the SVC DATA brick items (see Section 6.4).
The RSX-11M implementation of RRGEL (see RTL/2 System Standards, RTL/2 Ref 4) is described at 
the user level in Section 6.5. RRGEL is incorporated into the base program in RSXBA2 (see Section 6.4).
The optional items of run-time support software, are described in other sections of this manual, and 
include:
RTL/2 Standard Stream I/O	(Section 7)
RSX-11M Stream I/O Support	(Section 7)
RSX-11M Executive Interface	(Section 8)
RSX-11M File Services Interface	(Section 9)
Maths Routines	(Section 10)
RMS-11 Interface	(Section 11)
The RTL/2 package includes the source form of all the run-time support software to enable the user to 
tailor any aspect to his particular requirements.

6.2	CONTROL ROUTINES
6.2.1	Introduction
The control routines provide out-of-line functions in RTL/2 such as array bound checking and type 
conversions.
The RSX-11M control routines are specific to RSX-11M and will not, in general, operate in other 
environments.
6.2.2	Conditional Assembly
The source (Macro-11) is supplied and may be conditionally assembled into distinct versions summarised 
in TABLE 6.1:
1
Fixed point only, non-EIS
Users not having EIS hardware and not using REAL 
variables in their programs.
2
Fixed point only, EIS
Users having EIS hardware, not using REAL variables, 
and not using the compiler "EI" option or switch at all 
times.
3
Fixed point only, EIS in-line
Users having EIS hardware, not using REAL variables 
and using the compiler "EI" option or switch at all times.
4
Floating Point, no EIS or FPU
Users having neither EIS nor floating point hardware, 
using REAL variables.
5
Floating point, EIS no FPU
Users having EIS hardware but not floating point, using 
REAL variables, and not using the "EI" option or switch of 
the compiler at all times.
6
Floating point, EIS in-line, no FPU
Users having EIS hardware, using REAL variables, and 
using the "EI" option or switch of the compiler at all times.
7
Floating point, FPU, no EIS
Users having floating point unit, but not EIS hardware 
using REAL variables, and using the "FP" option of the 
compiler at all times.
8
Floating point, EIS, FPU
Users having EIS and floating point hardware, using 
REAL variables, using the "FP" option but not the "EI" 
option or switch of the compiler at all times.
9
Floating point in-line, EIS in-line
Users having both floating point and EIS hardware, using 
REAL variables, and using both the "EI" option or switch 
and the "FP" option of the compiler throughout.
10
Floating point to use Floating Point 
Processor with EIS routines for 
Fixed Point
Users having F.P.P., not using the compiler "EI" option or 
switch at all times.
11
Floating point to use Floating Point 
Processor using "EI" option 
throughout
Users with F.P.P., using the compiler "EI" option or switch 
at all times.
12
I- and D- Space
Users with separate !- and D- space hardware, typically 
running RSX-11M+.
13
"Slow code" interface
Users that always specify the "SL" compilation option.

An interactive command file is supplied to assist in selecting the appropriate options. This file is named 
RTLCTL.CMD. It uses the control routine source file, RTLCTL.MAC, in conjunction with the files:-
RTLCT1.MAC
RTLCT2.MAC
	...
RTLC12.MAC
RTLC13.MAC
containing definitions of conditional assembly symbols.
In those versions with less than the full set of control routines, an attempt to execute a function which is 
not provided will result in a call on RRGEL with error 9998.

TABLE 6.1
Control Routine Versions

Version No.
1
2
3
4
5
6
7
8
9
10
11
EIS Hardware
No
Yes
Yes
No
Yes
Yes
No
Yes
Yes
Yes
Yes
REAL is used
No
No
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
"FP" Option used 
at all times
-
-
-
No
No
No
Yes
Yes
Yes
-
-
"EI" Option used at 
all times
-
No
Yes
-
No
Yes
-
No
Yes
No
Yes
FPP Floating Point 
Processor
-
-
No
No
No
-
-
-
Yes
Yes

Notes:
(a)	"FP" Option applies only for programs to be run on a computer with F.I.S. hardware.
(b)	EIS hardware is present in all systems that have an FPP unit and/or run RSX-11M+.
(c)	RSX-11M+ users:
Control routine header 12 (RTLC12.MAC) should be included when assembling the control 
routines (RTLCTL.MAC), together with other headers as required. This will enable the conditional 
assembly of routines required by tasks using i- and d-space facilities under RSX-11M+.
(d)	Control routine header 13 (RTCL13.MAC) should be included when assembling the control 
routines for programs that are always compiled with the "SL" (smaller but slower code) option.

6.2.3	Errors detected by the Control Routines
Errors detected by the control routines (which are normally unrecoverable).

Error No:
Significance

1
Stack overflow (on procedure entry it is found that there will not be 
enough stack space to complete the procedure).

2
Label error (GOTO out-of-scope LABEL)

4
Array bound error

9998
Illegal control routine call (when entered via a TRAP where the operand 
is out of range or implies a routine excluded by conditional assembly).
6.3	BASE program 1 (RSXBA1)
RSXBA1 is task-dependent and must be built into each task, its function being to pass the stack limit and 
task entry point (i.e., entry to RTL/2) to RSXBA2.
Optionally, it may contain a Synchronous System Trap vector. This will give RRGEL reported errors on 
occurrence of one of the following SSTs (see also RSXBA2 below):
	10001	-	Memory addressing error
	10002	-	Memory protection violation
	10003	-	IOT instruction
	10004	-	Reserved instruction
	10005	-	Emulator trap
The following additional errors are given when the base programs are configured for use on a system 
with a F.P.P.
	10007	-	division by zero
	10009	-	floating-to-integer conversion error
	10011	-	floating-point overflow
	10015	-	undefined variable

Notes:
 	The BPT instruction SST is used to implement the line number tracing facility (TR option).
 	The TRAP instruction SST is used to enter control routines from 'slow code' (SL option).
6.4	BASE PROGRAM 2 (RSXBA2)
RSXBA2 is task-independent, and may be included in individual tasks or built into a shareable library. Its 
functions are as follows:
a)	to initialise SVC DATA bricks (see Section 6.6).
b)	to initialise registers for RTL/2 and enter RRJOB.
c)	to perform an RSX-11M EXST$ (EXIT with status) on return from RRJOB.
d)	to provide the standard procedures:
	RRNUL	-	Null procedure without parameters or result
	RRIPF	-	Default input routine
	RROPF	-	Default output routine
	RRGEL	-	General error label routine
e)	to provide a BPT service routine for RTL/2 programs compiled with the TR (trace) option.
Both RSXBA1 and RSXBA2 are coded in macro assembler, and supplied in source and object form.
Note that the default procedures RRIPF and RROPF report unrecoverable errors 98 (IN procedure not 
established) and 99 (OUT procedure not established) respectively.
6.5	RRGEL
The RSX-11M implementation of RRGEL (see RTL/2 System Standards, RTL/2 Reference 4) performs 
the output of a message and passes control to Label ERL (if this is in scope). If ERL is not in scope a 
further RRGEL message occurs - error number 3, ERL out of scope - and then an RSX-11M EXST$ is 
executed.
The message is output on LUN1 unless the user sets the BYTE ERRLUN in his SVC DATA brick 
RRERRX (see Section 6.6) to some other desired value.
The message has the format:-
task name (6 characters) /hyphen/error number (variable length)/'L'/line number in program (when TR 
option in use)
e.g., Task "PROGAB" calling RRGEL with parameter = 987 produces
	PROGAB-987L
or if compiled with the TR OPTION, and the error occurs at line 404, produces
	PROGAB-987L404
RSXBA2 may be conditionally assembled so that RRGEL produces an octal dump of the user's registers 
and stack as well as the usual error message. The symbol ZERRD must be defined when assembling 
RSXBA2. This is achieved by prefacing the file RSXBAD.MAC to the source of RSXBA2 at assembly 
time.
The user's registers at the time of entry to RRGEL are output first. "R0" will normally point to the SVC 
DATA region. The "R1" value is R1 before JSR R1,RRGEL. The "PC" is the value of the return address 
placed in R1 by JSR R1,RRGEL, and the "SP" value is SP after the JSR and points to the INT error 
number parameter minus 2.
For a description of the stack format, see "The RTL/2 Run-Time Environment on the PDP-11" - 
Reference RTL39.
Conditional assembly may also alter RSXBA2 to produce error messages for Synchronous System 
Traps. ZERRS must be defined to provoke such an assembly (provided by preface file RSXBAS.MAC).
File BASE.CMD has been provided to control the standard assembly options.
Note:	It is RSXBA1 which contains the SST vector and so tasks in a system with a shared BASE-2 
may still have different SST vectors. (In particular, the vector may be set to zero in all but 
'Breakpoint' and 'Trap' locations.)

6.5.1	Example of Stack/Register Dump Version of RRGEL
Three calls on RRGEL are illustrated from the task "...B2T":-
1)	RRGEL ERROR NO. 9990 FROM RRJOB
2)	RRGEL ERROR NO. 917 FROM PROC1 CALLED BY RRJOB
3)	RRGEL ERROR NO. 4150 FROM PROC2 CALLED BY PROC1 CALLED BY RRJOB
RRJOB has locals INT A=+1,B=-1,REAL X=10.7
These are passed as parameters INT, INT, REAL to PROC1.
PROC1 has no local data.
PROC2 is parameterless and has no local data.
B2T-
9990L10









R0
R1
R2
R3
R4
R5
SP
PC

002124
002362
005324
002076
005316
002106
002102
005422
002104
023406
002122
002362
041053
031463
177777
000001
002122
B2T-917L16









R0
R1
R2
R3
R4
R5
SP
PC

002124
005456
005472
002066
002106
002072
002066
005524
002070
001625
002106
005456
041053
031463
177777
000001
002122
002110
002362
041053
031463
177777
000001
002122


B2T-
4111150L22









R0
R1
R2
R3
R4
R5
SP
PC

002124
005540
005554
002062
002072
002066
002062
005606
002064
010066
002072
005540
002106
005456
041053
031463
177777
002104
000001
002122
002362
041053
031463
177777
000001
002122
In general, following the normal RRGEL error message, the first line of numbers indicates the contents of 
the registers, subsequent lines contain the dump of the stack from the top (low addresses) to the bottom 
(high addresses).

6.5.2	Post Mortem Dumping under RSX-11M
It is impossible to include a call to PMD in RSXBA2 so that, on a call to RRGEL, a Post Mortem Dump is 
produced in addition to the message on the error-LUN. The PMD output, typically, replaces the optional 
stack dump information (as determined by the definition of ZERRD at assembly time).
Two separate pieces of coding are required:
1.	The Snap definition block - the SNPBK$ macro
2.	The SNAP$ macro to call on the task PMD.
It is possible to have different setting of the SNPBK$ macro even when RSXBA2 is shared by putting the 
SNPBK$ macro into RSXBA1. In the example that follows, however, both SNAP$ and SNPBK$ are 
shown in RSXBA2.
Typical coding in a PMD RSXBA2

;	RRGEL Error Routine
;
CR=15
LR=12
	.EVEN
.IF DF ZERRD
	.MCALL SNPBK$,SNAP$
	SNPBK$ SY,0,SC.HDR!SC.LUN!SC.OVL!SC.STK,43.
.ENDC
	...
RRGEL::
	TSTB	UEFLAG(R0)	; Test UEFLAG for error within error
	BEQ	1$
	...
	MOV	2(SP),ERN(R0)	; Set ERN
	...
.IF DF ZERRD
	SNAP$,,ERN(R0)
.ENDC
	CLR	R3
	MOVB	ERRLUN(R0),R3	; LUN for error message
	...
71$:	QIOW$S	#IO.WLB,R3,#1,,,, R4,R1
; The coding for the register dump here should be omitted
	ADD	#24.,SP	; Restore space used for message building
	...

6.6	SVC DATA BRICKS
6.6.1	Introduction
SVC DATA bricks have the properties of ENT DATA except that each task has its own private copy. 
Although the RSX-11 task builders may be used to generate tasks with their own copies of any such 
bricks, access to them by shareable support software would be awkward. SVC DATA areas are therefore 
defined for all programs and set up by RSXBA2, where offsets (from the lowest addressed SVC DATA 
brick) are defined and, in accordance with normal RTL/2 on PDP-11 practice, register 0 is set to point to 
the SVC DATA region.
A portion of the task stack is actually used for SVC DATA.
The remainder of this section contains the specification of the standard and RSX-11M specific SVC 
bricks, and describes how additional bricks may be included.
The reader is assumed to be familiar with the run-time environment as described in Reference RTL39, 
"The RTL/2 Run-Time Environment on the PDP-11".
6.6.2	Standard RTL/2 SVC Data Bricks
The following bricks are as defined in RTL/2 Systems Standards, and are given here for completeness 
only.
Stream I/O
SVC DATA RRSIO;
	PROC () BYTE	IN;
	PROC (BYTE)	OUT;
ENDDATA;
SVC DATA RRSED;
	BYTE	TERMCH;
		IOFLAG;
ENDDATA;

Error Recovery
SVC DATA RRERR;
	LABEL		ERL;
	INT		ERN;
	PROC (INT)	ERP;
ENDDATA;
Default Values
Until set otherwise, the values of the above items (initialised dynamically) are:-

IN
RRIPF

OUT
RROPF

TERMCH
end of stream (octal 200)

IOFLAG
0

ERL
points to an EXST$

ERN
0

ERP
RRGEL
6.6.3	RSX-11M Extensions of SVC Data
The following additional bricks are set up in the RSX-11M implementation. Except where stated explicitly 
users should not modify the contents of these bricks.
6.6.3.1	Task Name
SVC DATA RRTASK:
	INT	TN1,
		TN2;
ENDDATA;
TN1 and TN2 are the 2-word RADIX-50 packed task name, and are initialised by "GET TASK" directive 
(GTSK$S) in RSXBA2.
This brick is used by RRGEL to print the calling task name, and may be useful for task control executive 
directives.
6.6.3.2	Diagnostic Information
SVC DATA RRERRX;
	INT	LINENO;
	BYTE	UEFLAG,
		ERRLUN;
	INT	RSXDSW;
ENDDATA;

LINENO is used by the TR (trace) option and RRGEL to supply program line numbers on error 
messages. If the TR option is not in use it may be set by the user to give additional information when 
RRGEL is called.
UEFLAG is private to RRGEL.
ERRLUN is the LUN for error messages output by RRGEL (default = 1) and may be set to some other 
value. The user must assign this LUN (whether default or not) to a suitable device at either task-build or 
run-time.
RSXDSW is used by the RSX-11M library procedures for the Directive Status Word results from 
executive directives (see Section 8).
6.6.3.3	Stack Information
SVC DATA RRSTK;
	INT	STKLO;
	INT	STKLIM;
ENDDATA;
STKLO is the lowest actual value of the stack pointer. Provided that a program is written entirely in RTL/2 
(with correct stack usages in any CODE inserts), or that suitable allowance is made for any stack use by 
non-RTL/2 parts of the task, STKLO may be used to re-assess the size of stack needed by the task.
STKLIM is the lowest allowance value of the stack pointer, against which a check is made on RTL/2 
procedure entry.
6.6.3.4	Task Exit Status
SVC DATA RREXS;
	INT  EXS;
ENDDATA;
EXS holds the exit status code returned to the parent task or RSX-11M indirect command file. This item 
can be used to return any value the programmer chooses to set, but is initialised to 1 (the standard RSX 
success status code).
6.6.3.5	Shareable Stream I/O
An SVC brick named RRTLIO is used to control the RSX-11M implementation of Stream I/O. This brick is 
described in Section 7.4.

6.6.4	User Extension of SVC Data
To extend the SVC DATA region the user should amend RSXBA2 so that it reserves the appropriate 
extra space and defines the brick name(s) (globally) as offsets from the SVC DATA area start. The first 
available value for further offsets beyond those provided is given by the constant SYSVCL, while the total 
length of the SVC DATA area is given by SVCLEN.
Example
To define:-
SVC DATA EXTRA;
	INT	EXTRAI;
	LABEL	EXTRAL;
	BYTE	EXTRAB;
ENDDATA;
add the definition
EXTRA==SYSVCL	; +size of any other bricks added
to RSXBA2, and add 8 (the length, in bytes, of EXTRA) to the value assigned to SVCLEN.
Code should also be added to initialise the contents of the databrick.

7.	STREAM I/O
7.1	INTRODUCTION
Character stream I/O is supported according to the standards defined in Reference RTL 5, "RTL.2 
Standard Stream I/O". The character and formatted I/O procedures defined therein are augmented in the 
RSX-11M implementation by procedures for opening, closing and switching I/O channels.
7.1.1	Standard Library Procedures
	I/O Formatting Procedures
The following standard I/O formatting procedures are supplied with the delivery package. More detailed 
descriptions are given in the Standard Stream I/O manual.
BREAD,	read binary/hex/octal integer
HREAD,
OREAD() INT
BRWT,	write I in binary/hex/octal
HWRT,
OWRT (INT I)
BWRTF,	write N bits of I in binary/hex/octal
HWRTF,
OWRTF (INT I, N)
FREAD () FRAC	read decimal number, return truncated fraction
FWRT (FRAC F)	write fraction F
FWRTF (FRAC F, INT N)	write fraction F using N print positions
IREAD () INT	read decimal integer
IWRT (INT I)	write I in decimal
IWRTF (INTI, N)	write I in decimal using N print positions
IWRTZ (INT I, N)	as IWRTF but with leading zeros output
NLS (INT N)	write N newlines
SPS (INT N)	write N spaces
RREAD () REAL	read decimal number, return real result
RWRT (REAL R)	write real R using exponent notation
RWRTF (REAL R, INT M, N)	write R as decimal number in format determined by M, N
TREAD (RAB AB1, AB2) INT	read characters into AB1 until one of the characters in AB2 is 
	encountered, and return number of characters read
TWRT (RAB AB1)	write AB1 as characters
Note: that several of the routines above use the databrick RRENV, which contains target-specific data 
such as word length.

7.1.1.1	Formatted input
All the formatted input routines have two actions in common:
i)	the last character that they read from the current input stream is always
placed in TERMCH in RRSED. Stream input stops when either a certain "terminating character" is 
encountered or an error situation is detected. in either case the last character read will have been 
removed from the current input stream and therefore it is no longer accessible to the calling task (since 
another call of IN would return the next character from the current input stream). Often the loss of this 
character will not matter; however there are occasions when it is necessary to inspect this character (for 
example, to check that a number has been terminated with the correct character), and so it is always 
placed in TERMCH. It is therefore available to a task if it is interested in it.
ii)	if an error is encountered in the format of the input obtained from the current
stream then it is always reported to the calling task in the following way:
a)	IOFLAG in RRSED is set to 1. It is the task's responsibility to ensure
that IOFLAG is cleared to zero prior to using any of the stream input facilities if there is any possibility of 
spurious error indications arising from previous errors, since nothing else will clear it. However this can 
also be very useful since it means that a whole series of stream input facilities can be used, and one test 
of IOFLAG at the end will show whether they were all successful or not (a null error procedure should be 
in effect).
b)	the recoverable error procedure contained in ERP in RRERR is
called. The recoverable error number, which is passed as parameter to this procedure, will identify this 
fact and also the procedure that was being called. The possible error codes are:
100	- bad format or overflow in FREAD
101	- bad format or overflow in IREAD
102	- bad format or overflow in RREAD
103	- bad format or overflow in TREAD
104	- bad format or overflow in BREAD
105	- bad format or overflow in OREAD
106	- bad format or overflow in HREAD
Therefore it is possible to use either mechanism to detect and act upon any stream input recoverable 
errors, or ignore them as desired.
7.1.1.2	Formatted output
The only formatted output routine that may give an error is IWRTZ, which will report error 200 if the 
number given does not fit in the field width specified.

7.1.2	Stream I/O Implementation
To permit use of the Standard Stream I/O routines, and the character input/output procedure variables IN 
and OUT, the RSX-11M support software contains the procedures listed below.

Module
Procedure
Description

RSXINT
RSXINT
Initialise Stream I/O support

RSXOBO
RSXOBO
Create a binary file (output only)

RSXOBA
RSXOBA
Open existing binary file at end (output only)

RSXOBI
RSXOBI
Open existing binary file (input only)

RSXOBU
RSXOBU
Open existing binary file (input/output)

RSXBIN
RSXBIN
Input a byte from binary file

RSXBOUT
RSXBOUT
Output a byte to binary file


RSXBFLSH
Flush out stream to binary file

RSXOPO
RSXOPO
Create an ascii file (output only)

RSXOPA
RSXOPA
Open existing ascii file at end (output only)

RSXOPI
RSXOPI
Open existing ascii file (input only)

RSXOPU
RSXOPU
Open existing ascii file (input/output)

RSXAIN
RSXAIN
Input a byte from ascii file

RSXAOUT
RSXAOUT
Output a byte to ascii file


RSXAFLSH
Flush out stream to ascii file

RSXSWI
RSXSWI
Switch current input stream

RSXSWO
RSXSWO
Switch current output stream

RSXCL
RSXCL
Close file


RSXSP
Close and spool file


RSXDLT
Close and delete file

RSXCHK
RSXCHK
Validate stream number and file name string

RSXINFO
RSXFREESTRM
Returns number of next available stream


RSXFILEDATA
Returns pointer to FCS block for a stream


RSXERRORDATA
Returns FCS error code values
These procedures are described in detail in Section 7.3. Each task must also set up a Stream I/O Data 
Area as described in Section 7.1.3. Error handling is described in Section 7.1.4.
7.1.3	Stream I/O Data Areas
Tasks using the Stream I/O procedures must be built to include a module which contains FCS File 
Definition Blocks, I/O buffers, plus various control information for the Stream I/O implementation.
Section 7.2 describes, in detail, the source for this module. A module generated for a given number of 
files may be included in all tasks where the highest logical unit number assigned does not exceed this 
number and where the buffer sizes are appropriate.
For example, the file SAREA4.OBJ has been provided with the delivery. This contains sufficient data 
areas for four LUNs and may be included in all programs which do not require to have more than four 
LUNs assigned at any one time.

7.1.4	Stream I/O Error Handling
Various error conditions are reported by the RSX-11M Stream I/O support procedures. These are listed, 
following the discussion of the various procedures, in Section 7.5.
The error flagging takes the form of a call to ERP (the recoverable error procedure variable), with an 
integer parameter in the range 110 to 123 inclusive.
If a program calls RSXIN or RSXOUT when there is no valid LUN these two procedures will call ERP to 
flag the error, and they will have null effect (EOS returned from RSXIN and output lost in RSXOUT). Thus 
to continue the user must write his own error-handling procedure. This also applies for I/O before the 
streams are initially switched.
Use of the character input/output procedure variables IN and OUT (either directly or indirectly via the 
stream formatting procedures) before they have been assigned will result in unrecoverable errors 98 and 
99 respectively. If a low-level I/O error occurs, then the corresponding FCS code can be obtained by 
calling RSXERRORDATA (see 7.3.6).
7.2	DATA AREA ALLOCATION
Before any stream I/O can be performed it is necessary to allocate for each of the I/O streams required, 
a data area containing a buffer and various control information for use by the I/O interface. There are two 
methods for allocating this area which are now described in detail.
7.2.1	Code Insert
Within a code insert of a non-overlaid RTL/2 module a call to the RSX-11M macro RTLIOM can be made. 
The form of the call is:
RTLIOM maxlun, psect, < size 1, ......,size 10>
where
maxlun	the number of LUNs (logical unit numbers which are synonymous with I/O streams or 
channels) used by the program
psect	the name given in a CSECT (/CS switch for the compiler) or PSECT (/PS switch for the 
compiler) directive for the module, or null if no such switch was specified (the blank 
CSECT is the default)
size N	the appropriate buffer size for each of the streams specified; the size is given as a 
decimal integer number of bytes. If any value is left blank, 80 is assumed by default. Only 
the first maxlun streams are considered.
The distributed RTLIOM will only allow up to ten I/O streams to be set up. To change this the RTLIOM 
macro definition (in the file RTLIOB.MAC) must be altered by extending the S1,...., S10 lines to include 
the extra buffers, e.g., S11, S12 etc.
The call to RTLIOM generates no assembly code within the calling procedure but allocates and names an 
area of read-write data in a separate PSECT called RTLIO.
Hence to allocate 6 streams for a program (where the 1st, 2nd, 5th, 6th have a buffer size of 80 
characters and the 3rd, 4th a buffer size of 512 characters) the following is valid:-
ENT PROC RRJOB ( );
  local declarations
	CODE 0,0;
		RTLIOM 6, PROCS,,,512,512
	*RTL;
  executable statements
ENDPROC;
In this instance it is assumed that the name PROCS is given to the module's code section when it is 
compiled (e.g., the switch /SE:Y is used).
7.2.2	File Areas Module
As an alternative to using a call to RTLIOM from within a code insert a short MACRO-11 source module 
can be written which includes a call to RTLIOM to define a standard set of buffers (RTLIOM is described 
in Section 7.2.1).
For example a file area (SAREA4.MAC) module can be written to define four 80 byte buffers as in:-
.PSECT	PROCS, I
.MCALL	RTLIOM
RTLIOM	4, PROCS
.END
This is considered to be the better method.
7.2.3	Assembly for RTLIOM
The definition for RTLIOM is in the supplied module RTLIOB.MAC which should be included when 
assembling the program (or area module) containing the RTLIOM call.
For example, the data area SAREA4.OBJ has been generated by:
	MAC SAREA4=RTLIOB,SAREA4
Similarly, the equivalent step for the program described in 7.2.1 would be:
	MAC BASE=RTLIOB,BASE
assuming that the file BASE.MAC represents the output from compiling BASE.RTL.
7.2.4	Data Areas Generated by RTLIOM
The inclusion of RTLIOM in any module will cause the following data areas to be generated (the casual 
user of stream I/O should ignore the rest of this section).
RCPTRS	Array of pointers to stream I/O control data records (one for each stream).
RTLBn	The buffer is allocated to stream n.
RTLFn	The FDB allocated to stream n.
RTLn	The default Name Block allocated to stream n.
RTLCSI	The Command String Interpreter control block (used for parsing file names).
The first three of the above can be accessed either using the stream I/O procedures (see 7.3) or by using 
the stream I/O SVC databrick RRTLIO (see 7.4). The Name Block for a stream can be referenced via the 
appropriate FDB, but the CSI block can only be referenced by using the above label in assembler code.
7.2.5	Buffer Sizes
It is usual for binary streams to use fixed length records of size 512 bytes, and it is therefore 
recommended that all binary streams use buffers of this size.
Buffers for devices requiring carriage control characters are effectively 2 bytes smaller than expected as 
room has to be allocated for the CR/LF pairs required to start new buffers on new lines. It is 
recommended that if a stream is known to be always associated with a carriage control device, the buffer 
size should be 2 bytes larger than the line length of the device (e.g., a VDU should use a buffer of 82 
characters if its line is

7.3	PROCEDURE DEFINITIONS
To allow the standard stream I/O procedures (using IN and OUT in SVC data RRSIO) to be used under 
RSX-11M the following routines must be used to specify where IN and OUT are to direct the data.
7.3.1	Initialisation
Before any I/O can be performed, the various control data value in SVC data RRTLIO must be set up. 
The procedure:-
EXT PROC ( ) RSXINT;
when called sets NSTREAMS and STREAMS, both of which are defined in Section 7.4. RSXINT also 
calls the RSX macro FINIT$ to initialise the file storage region. Note that this routine is not shareable and 
must be specified in the root of overlaid tasks.
7.3.2	Setting up I/O Streams
Each I/O stream has an associated LUN with the same number. It is necessary to allocate this LUN to an 
RSX-11M dataset descriptor in order to define the device or file to be used for the stream.
The stream I/O interface allows each stream to be treated as a series of ASCII characters or as a series 
of binary numbers (bytes). To open an ASCII character stream the procedures:-
EXT PROC (INT, REF ARRAY BYTE) RSXOPI, RSXOPO, RSXOPU, RSXOPA;
are provided to open a stream for 
Input	-	to read from a file
Output	-	to create and write to a file
Update	-	to read from and write to a file
Append	-	to write to the end of a file
The first parameter is the LUN associated with the stream and the second is a pointer to a byte array 
containing an RSX-11M dataset (without switches); any valid dataset is allowed, e.g.,
a)	STARTUP.CMD
b)	TI:
To open a binary number stream the procedures:-
EXT PROC (INT, REF ARRAY BYTE, PROC ( ), PROC ( )) RSXOBI;
EXT PROC (INT, REF ARRAY BYTE) RSXOBO, RSXOBU, RSXOBA;
are available to open a stream as described above for Ascii streams.
In both cases the first two parameters define the stream number (LUN) and the associated dataset; 
RSXOBI has two extra parameters namely:
a)	a procedure to be called when the end of each record is met
b)	and a procedure to be called when the end of the stream is met.
The following notes clarify certain points:
1.	It is illegal to use the same LUN twice (i.e., to open two streams on the same LUN) without closing 
the previously opened stream (see Section 7.3.4).
2.	Several streams (LUNs) may be allocated to the same dataset at the same time.
3.	Significant fields in any dataset should not be left to default as no default values are assumed by the 
stream I/O.

7.3.3	Changing Streams
It is possible to have many I/O streams actually open, but only two will currently be selected for use, one 
for input and the other for output.
To change streams the following procedures are available:
EXT PROC (INT) INT RSXSWI, RSXSWO;
which select the new input and output streams respectively. The parameter defines the new stream while 
the result is the previously selected stream number. If no stream was previously selected a value of zero 
is returned. Selecting a new stream involves updating the current stream pointer in SVC databrick 
RRTLIO and then setting IN and OUT to the input or output procedure for the new stream.
The opening of a new input or output stream does not affect the values of the currently selected input and 
output streams. However, if RSXCL (see Section 7.3.4) is called for the current input or output stream 
then that stream is deallocated (i.e., the current input or output stream LUN is set to zero).
Initially no input or output streams are selected.
7.3.4	Closing Streams
Once a stream has been finished with, it can be closing using:-
EXT PROC (INT) RSXCL;
This procedure takes as its parameter the LUN for the stream to be closed (input and output streams are 
both closed by this method) and dis-associates the LUN from its dataset (as set up by the open stream 
routines - see Section 7.3.2).
If the stream is an output stream an appropriate routine (see Section 7.3.5) is called to force out the 
contents of the I/O buffer (unless it is empty) before the stream is closed.
If the stream to be closed is the current input or output stream then the current input or output stream is 
de-allocated (i.e., set to LUN zero) when the stream is closed.

A second procedure:-
EXT PROC (INT) RSXSPP;
not only closes a stream but (if the corresponding dataset is a disc file) will "spool" the file as well (i.e., it 
calls the spooler to list the file on the line printer).
A third procedure:-
EXT PROC (INT) RSXDLT;
will delete an opened disc file as well as closing the stream. (Input or output files can be deleted with 
RSXDLT.) This procedure only works for currently opened streams using disc files.
7.3.5	Input and Output
The stream I/O uses procedures:-
EXT PROC ( ) BYTE RSXAIN, RSXBIN
EXT PROC (BYTE) RSXAOUT, RSXBOUT;
for Ascii and Binary input and output. These procedures read from and write to the currently selected 
input and output streams, which must be opened before they are used.
For input the procedure variable IN and SVC data RRSIO is set to RSXAIN or RSXBIN and, when called, 
returns a single byte from the current input stream. If the stream was opened as an Ascii (via RSXOPI or 
RSXOPU) stream the following applies:-
*	all carriage return characters (octal code 15) are ignored,
*	a line feed character (octal code 12) is returned when the end of a record is met,
once the end of the input stream (end of a file) is met, IOFLAG in SVC data RRSED is set to 2 and an 
end of stream character (EOS octal code 200) is returned to this and all subsequent calls of IN until the 
stream is closed.

If the input stream is opened as binary (via RSXOBI or RSXOBU) the following applies:
At the end of each record the 'end-of-record' procedure (third parameter to RSXOBI) is called after 
returning the last character in the record, and IOFLAG in SVC data RRSED is set to 3,
At the end of the stream IOFLAG is set to 2 and the 'end-of-file' procedure (fourth parameter to RSXOBI) 
is called after the last character in the last record has been returned (which implies a call of the 'end of 
record' procedure). Once the 'end of file' procedure has been called, the EOS character is returned (as 
per ASCII input) to subsequent calls of IN.
For output the procedure variable OUT in SVC data RRSIO is set to RSXAOUT or RSXBOUT to output a 
single byte to the current output stream.
For Ascii output streams (opened with RSXOPO, RSXOPA or RSXOPU) the following apply:-
all carriage return characters are ignored,
the end of a record is denoted by either:-
*	a line feed character which forces out the current buffer and, if the output device requires carriage 
control (e.g., a terminal or line printer or similar), appends a carriage return character.
*	a vertical tab character (octal code 13) which forces output of the buffer but is not included in the 
buffer (mainly used to output a prompt and to wait on the same line for a user response).
For binary streams no interpretation is placed on the outgoing characters. For binary output the output 
records are set up to be fixed length, the size of the records being equal to the size of the buffer used to 
hold the characters as they are output.
The procedures:-
EXT PROC ( ) RSXAFLSH, RSXBFLSH;
can be called to force output of any contents of the buffer for the currently selected stream. The Ascii 
version has the same effect as a vertical tab character output to the stream, while the binary version pads 
the output record with nulls.

In both types of output the buffer is written out whenever the next character to be written would overflow 
the buffer (i.e., the buffer is full). In the case of Ascii output requiring carriage control, a CR character is 
appended to the buffer and an LF character is put at the beginning of the next buffer (as though a LF had 
been written to the output stream).
7.3.6	Stream Information
The RSX-11M stream I/O includes a set of procedures that provide various checks and/or information 
concerning the streams during processing.
The procedure.
EXT PROC (INT, REF ARRAY BYTE) INT RSXCHK;
validates a stream number and a RSX-11 file name string. Should either parameter be incorrect then an 
error is reported and RSXCHK returns a non-zero value, otherwise it returns zero.
The procedure
EXT PROC ( ) INT			RSXFREESTRM;
returns the number of the next available stream (i.e., one that is not currently open), or -1 if all streams 
are in use.
The procedure
EXT PROC (INT) REF BYTE		RSXFILEDATA;
returns a pointer to the start of the FCS File Description Block (FDB) for the file open on a specific 
stream.
The procedure
EXT PROC (REF ERRORDATA)		RSXERRORDATA;
returns the latest FCS error codes detected and then clears the copy of these codes in stream I/O - so 
that a second consecutive call will return zeroes (ERRORDATA is described in Section 7.4.1.).

7.4	SVC DATA CONTROL BLOCK
The various data structures set up by the RTLIOM macro (see 7.2) are accessed via a control block in a 
task's SVC Data area. This control block is initialised when the procedure RSXINT (see 7.3.1) is called, 
after which it is used by the stream I/O procedures to control all stream I/O activities for the task. The 
reason for this approach is that none of the stream I/O routines - apart from RSXINT - need be linked to 
the actual stream I/O data structures, which means that one copy of these routines can be shared by 
many tasks.
This SVC databrick, RRTLIO, is described below.
7.4.1	Definition of RRTLIO
SVC DATA RRTLIO;
	INT	NSTREAMS;
	REF STREAMREC	INSTREAM,
		OUTSTREAM;
	REF ARRAY REF STREAMREC	STREAMS;
	ERRORDATA	FSYSERROR;
ENDDATA;
where
	MODE ERRORDATA (INT ERRORCODE, EXTRADATA)
and
	MODE STREAMREC	(INT	STRNUM, STRTYPE,
			INPTR, OUTPTR,
			INLEN, OUTLEN,
		 REF ARRAY BYTE BUFFER, REF BYTE FSYSPTR,
		 PROC () EORPROC, EOFPROC,
		 PROC () BYTE INPROC, PROC (BYTE) OUTPROC
		)
The components of RRTLIO are as follows:
NSTREAMS
the maximum number of streams supported,
(this is zero until RSXINT has been called)
INSTREAM
pointer to the control record for the current input stream;
OUTSTREAM
pointer to the control record for the current output stream;
STREAMS
pointer to the table of control records, one for each stream, set up by RTLIOM;
ERRORDATA
contains the FCS status byte values from the last I/O operation that failed to 
complete successfully

The components of each stream control record are:
STRNUM
stream number (1..NSTREAMS) - this never changes;
STRTYPE
stream I/O type, which will be one of:

 -1 = binary stream

  0 = stream not in use

+1 = Ascii stream

+3 = Ascii stream requiring explicit device carriage-control characters;
INPTR
position in I/O buffer of the next input byte;
OUTPTR
position in I/O buffer for the next output byte;
INLEN
number of bytes input into I/O buffer;
OUTLEN
number of bytes to be output from I/O buffer;
BUFFER
I/O buffer for stream;
FSYSPTR
address of stream's FDB;
EORPROC
procedure to be called when the end of an input record is detected on the stream;
EOFPROC
procedure to be called when the end of an input file is detected on the stream;
INPROC
input procedure (i.e., value of IN) for stream;
OUTPROC
output procedure (i.e., value of OUT) for stream

7.5	ERRORS GENERATED
The following errors may be reported by the stream I/O routines via a call of the procedure variable ERP 
in SVC data RRERR.

110
bad stream number

111
bad filename

112
cannot open file for append

113
cannot open file for input

114
cannot open file for output

115
cannot open file for update

116
cannot close file

117
bad new input stream number

118
bad new output stream number

119
error on read from file

120
error on write to file

121
cannot spool file

122
cannot delete file
7.6	IMPLEMENTATION
7.6.1	Compilation
No special considerations are needed except that if the macro RTLIOM (Section 7.2) is included in a 
code insert, ensure that the .PSECT (or .CSECT) name given in RTLIOM corresponds to any directive 
switch supplied to the compiler.,
7.6.2	Assembly
Ensure that the module containing the call of macro RTLIOM is preceded by the file RTLIOB.MAC when 
using the MACRO-11 assembler. No harm occurs if the file RTLIOB.MAC precedes a module which does 
not call the RTLIOM macro.
7.6.3	Task Build
If a 'data areas' module is being used, include it in the task builder's list of modules.
Always use the following options with each task build:-
*	UNITS = n where n is the value of maxlun (see Section 7.2.1) in the call to RTLIOM
*	ASG = TI:1	Assigns LUN 1 to the user's terminal (for error reporting).

The stream I/O procedures may be included in each task by specifying the object library in every build, or 
they may be built into a separate memory-resident library that can then be shared by different tasks by 
use of the RESLIB task builder option. Note, however, that the stream I/O data areas and the initialisation 
procedure (RSXINT) must be included in every task build and, for overlaid tasks, must be in the root part 
of the task.
7.7	SPECIAL CONSIDERATIONS
1.	Users are recommended not to use LUN 1 as anything other than output to the console for the 
following reasons:-
	*	The RTL/2 RSX-11M interface uses LUN 1 for error reporting to the terminal.
	*	The RSX-11M indirect command file processor uses LUN 1 for its own purposes.
2.	Calls to the open stream procedures and RSXCHK rewrite the given file name string by removing any 
layout characters (tabs and spaces) in the name, but do not tidy up the array by filling it out with 
spaces. Hence if the array did contain any layout characters it will be corrupted (effectively unusable) 
on return from any of these procedures.

8.	THE RSX-11M EXECUTIVE INTERFACE
8.1	INTRODUCTION
The RSX-11M interface library provides the user with a procedure interface to the RSX-11M Executive. 
The content of this section has been written on the assumption that the user is fully conversant with the 
relevant RSX-11M macros to implement executive directives as described in the DEC Executive 
Reference Manuals. There are three forms of these macros, the $S, $C and $-forms.
The $S-form macros generate code to create a Directive Parameter Block (DPB) at run-time on the 
stack. These macros generate re-entrant code, unlike the other forms. The RTL/2 RSX-11M Interface 
Library provides routines which enclose calls to the $S-form of the macros. In the case where no $S-form 
exists an alternative form is used. The routines are described in Sections 8.2 to 8.8. The record formats 
(i.e., MODE statements) used by these routines are described in Section 8.9.
The $C-form macros create a Directive Parameter Block (DPB) at assembly time and generate code to 
execute the DPB. The DPB cannot be otherwise accessed at either RTL/2 or CODE level. Routines are 
not provided to invoke these macros.
The $-form macros create a Directive Parameter Block (DPB) at assembly time. as the DPB formats are 
not guaranteed against change, a MODE statement for accessing a DPB might need to be revised with 
new releases of RSX-11M. If the $-form macros are desired the DPB is best accessed at CODE level. 
The RTL/2 executive interface library does not offer these macro forms but the DPB may be created at 
CODE level, along with the DIR$ macro to execute the DPB.
Some executive directives are associated with Asynchronous System Trap (AST) service routines. These 
routines are required to leave the program stack in a particular format on exit and therefore, cannot be 
written completely in RTL/2. Section 8.10 outlines a method to enable the use of RTL/2 for the major part 
of large AST routines. However, small AST routines, especially those frequently used, should normally be 
written in assembler.

Notes:
1.	The parameters for the executive routines are for the full RSX-11D implementation. RSX-11M users 
should supply a valid dummy or null value for those parameters marked with an asterisk. This is to 
satisfy the RTL/2 compiler's mode checking of parameters to procedure calls, with respect to their 
EXT definition.
2.	The routines all place the contents of the Directive Status Word into RSXDSW (in SVC DATA 
RRERRX) after the embedded RSX-11M macro call, Error conditions are denoted by a negative 
value.
3.	For full details of routine functions and explanations of parameters, refer to the relevant DEC RSX-
11M Executive Reference Manual.
8.2	TASK EXECUTION CONTROL ROUTINES
RSXABT
Abort task
(ABRT$S)
Parameter
REF R50NAME
task name
RSXCNT
Connect task
(CNCT$S)
Parameters
REF R50NAME
Task name

INT
Event flag number

PROC( )
AST service routine

REF ESBLOCK
8 word status block
RSXCRM
Cancel time based initiation requests
(CSRQ$S)
Parameter
REF R50NAME
Scheduled (target) task name
RSXEXI
Task Exit

Note:
This (RSXEXI) is a label within the RTL/2 base program. To exit from a 
task, control should be passed to the end of the RRJOB procedure brick. 
The exit status code should, in this case, be ignored.

RSXEXS
Task Exit with status
(EXST$S)
Parameters
INT
Exit Status
RSXRPI
Request and Pass Offspring Control Block
(RPOI$S)
Parameters
REF R50NAME
Requested Task Name

INT
UIC group code

INT
UIC user code

REF R50NAME
Parent Name

REF ARRAY BYTE
Command Line

INT
Command Line Length

INT
Flag Byte Setting

REF ARRAY BYTE
Offspring TI: Unit Number

INT
Offspring TI: Device Mnemonic

REF R50NAME
Run Name

INT
OCB Address
Note:
The requested task's run name is only specified if 
the issuing task is a CLI task

RSXRQS
Request
(RQST$S)
Parameters
REF R50NAME
Task name

REF R50NAME
Partition name

INT
Priority

INT
UIC group code

INT
UIC owner code



RSXRSU
Resume
(RSUM$S)
Parameter
REF R50NAME
Task name
RSXRUN
Run
(RUN$S)
Parameters
REF R50NAME
Task name

REF R50NAME
Partition name

INT
Priority

INT
UIC group code

INT
UIC owner code

INT
Schedule delta magnitude

INT
Schedule delta unit

INT
Reschedule interval magnitude

INT
Reschedule interval unit
RSXSPN
Suspend
(SPND$S)
Parameters
None

RSXSPW
Spawn task
(SPWN$S)
Parameters
REF R50NAME
Offspring task name

INT
UIC group code

INT
UIC user code

INT 
Event flag number

PROC( )
AST service routine

REF ESBLOCK
8 word status block

REF ARRAY BYTE
Command line

INT
Command line length

INT
Offspring TI: Unit Number
RSXSTP
Stop task
(STOP$S)
Parameters 
None

RSXUNS
Unstop task
(USTP$S)
Parameters
REF R50NAME
Task name
8.3	TASK STATUS CONTROL ROUTINES
RSXALT
Alter priority
(ALTP$S)
Parameter
REF R50NAME
Task name

INT
Priority
RSXCPC
Checkpoint Common Region
(CRCP$S)                                     
11M+
Parameters
REF R50NAME
Name of Common Region to be

checkpointed

RSXDSC
Disable checkpointing
(DSCP$S)
Parameters
None

RSXENC
Enable checkpointing
(ENCP$S)
Parameters
None

8.4	INFORMATION ROUTINES
RSXGPR
Get partition parameters
(GPRT$S)
Parameters
REF R50NAME
Partition name

REF PARBUF
Reply buffer
RSXGSS
Get sense switches
(GSSW$S)
Parameters
None

Result
INT    ( 0 - successful, contents of the console switch register is in 
RSXDSW,
              1 - unsuccessful, error code is in RSXDSW)

RSXGTI
Get time parameters
(GTIM$S)
Parameter
REF TIMEBUF
Reply buffer
RSXGTS
Get task parameters
(GTSK$S)
Parameter
REF TASKBUF
Reply buffer
RSXSTI
Get System Time
(STIM$S)
Parameters
REF TIMEBUF
New Time Buffer

REF TIMEBUF
Old Time Buffer
8.5	EVENT ASSOCIATED ROUTINES
RSXCGF
Create group global event flags
(CRGF$S)
Parameter
INT
Group number for the flags
RSXCLE
Clear event flag
(CLEF$S)
Parameter
INT
Event flag number
RSXCMK
Cancel mark time requests
(CMKT$S)
Parameters
* INT
Event flag number

* PROC()
AST service routine
Note:
the null parameters (0,RRNUL) must be used by RSX-11M users.

RSXDEC
Declare significant event
(DECL$S)
Parameter
*INT
Event flag number
Note:
RSX-11M users should specify event flag zero.

RSXEGF
Eliminate group global event flags
(ELGF$S)
Parameter
INT
Group number for the flags
RSXEXF
Exit if
(EXIF$S)
Parameter
INT
Event flag number
RSXMRK
Mark time
(MRKT$S)
Parameters
INT
Event flag number

INT
Time interval magnitude

INT
Time interval unit

PROC()
AST service routine
RSXRDA
Read all even flags
(RDAF$S)
Parameter
REF FLAGBUF
Reply buffer
RSXRDE
Read Event Flag
(RDEF$S)                                     
11M+
Parameters
INT
Event Flag Number
RSXRDX
Read extended event flags
(RDXF$S)
Parameter
REF XFLAGBUF
6 word buffer for flags 1-96
RSXSET
Set event flags
(SETF$S)
Parameter
INT
Event flag number
RSXSTL
Stop on logical or (local) even flag
(STLO$S)
Parameters
INT
Event flag group number

INT
Mask word
RSXSTS
Stop on single event flag
(STSE$S)
Parameter
INT
Event flag number
RSXULG
Unlock Group Global Event Flags
(ULGF$S)
Parameters
None

RSXWSI
Wait for significant event
(WSIG$S)
Parameters
None

RSXWTL
Wait for logical OR of event flags
(WTLO$S)
Parameters
INT
Desired group of event flags

INT
16 bit octal mask word
Note:
the group of event flags has values 0 to 3 for flags 1-16, 17-32, 33-48 and 49-
64.

RSXWTS
Wait for single event flag
(WTSE$S)
Parameter
INT
Event flag number

8.6	TRAP ASSOCIATED ROUTINES

AST Service Exit
(ASTX$S)
Note:
As AST service routine must be interfaced in assembler, there 
is no RTL/2 equivalent of this macro
(see Section 8.10 for guidance on writing AST service 
routines).

RSXCIN
Connect to interrupt
(CINT$S)
Parameters
INT
Interrupt vector address

INT
Virtual Base address

PROC()
Interrupt Service Routine

PROC()
Enable/Disable Interrupt Routine

INT
Initial Priority

PROC()
AST routine or RRNUL
RSXDSA
Disable AST recognition
(DSAR$S)
Parameters
None

RSXENA
Enable AST recognition
(ENAR$S)
Parameters
None

RSXSFP
Specify floating point exception AST
(SFPA$S)
Parameter 
PROC( )
AST service routine
Notes:
(1)  To stop the occurrence of floating point exception ASTs, use RRNUL 
as parameter.
(2)  This directive applies only to machines with a floating point processor.
RSXSPR
Specify power recovery AST
(SPRA$S)
Parameter
PROC()
AST service routine
Note:
To stop the occurrence of power recovery ASTs, use RRNUL as parameter.

RSXSRD
Specify receive AST
(SRDA$S)
Parameter
PROC()
AST service routine
Note:
To stop the occurrence of "receive ASTs", use RRNUL as parameter.

RSXSRE
Specify Requested Exit AST
(SREA$E)
Parameters
PROC()
AST service routine
RSXSVD
Specify SST vector table for debugging 
aid
(SVDB$S)
Parameter
REF SSTTBL
Table of SST service routine 
addresses
Notes:
(1)  If an entry specifies RRNUL, then the system default is taken for that 
entry.


(2)  The entry for execution of a TRAP instruction is always overwritten by 
this routine prior to the macro call (TRAP is used by the RTL/2 
implementation).

RSXSVT
Specify SST vector table for task
(SVTK$S)
Parameter
REF SSTTBL
Table of SST service routine 
addresses
Note:
The TRAP entry will be overwritten (as RSXSRD)

8.7	I/O AND INTERRASK COMMUNICATION ROUTINES
RSXALU
Assign LUN
(ALUN$S)
Parameters
INT
Logical unit number

REF ARRAY BYTE
Physical device name (two ASCII 
characters)

INT
Physical device unit number
RSXCRV
Create virtual Terminal
(CRVT$S)                                   
11M+
Parameters 
PROC()
AST Routine for input requests

PROC()
AST Routine for output requests

PROC()
AST Routine at which parent task 
can be notified of successful 
completion of offspring attach and 
detach requests.

INT
Maximum buffer length for offspring 
I/O requests.
RSXELV
Eliminate Virtual Terminal
(ELVT$S)                                     
11M+
Parameters
INT
Unit number of Virtual Terminal
RSXGCI
Get Command Interpreter Information
(GCII$S)
Parameters
REF ARRAY BYTE
Information Buffer

INT
Buffer Length

REF R50NAME
Cli name

REF ARRAY BYTE
Ascii Name of Terminal

INT
Unit Number of Terminal
RSXGLU
Get LUN information
(GLUN$S)
Parameters
INT
Logical unit number

REF LUNBUF
Reply buffer
RSXGMC
Get MCR command line
(GMCR$)
Parameter
REF ARRAY BYTE
80 byte reply buffer
Note:
This routine calls the DIR$ macro.

RSXQIO
Queue I/O
(QIO$S)
and


RSXQIW
Queue I/O and Wait
(QIOW$S)
Parameters
INT
I/O function code

INT
Logical unit number

INT
Event flag number

* INT
Priority

REF IOSTAT
I/O status block

PROC( )
AST service routine (or RRNUL)

REF ARRAY INT
6 word array of device-dependent 
parameters (unused entries must 
be set to zero)
RSXRST
Receive data or stop
(RCST$S)
Parameters
REF R50NAME
Name of task from which data is to 
be received

REF ARRAY INT
Reply buffer (15 words)
RSXRVD
Receive data
(RCVD$S)
Parameters
REF R50NAME
Task name

REF ARRAY INT
Reply buffer (15 words)
Result
INT

Note:
This integer contains Condition Code Carry-bit setting in bit 0

RSXRVX
Receive data or exit
(RCVX$S)
Parameters
*REF R50NAME
Task name

REF ARRAY INT
Reply buffer (15 words)
Result
INT

Note:
This integer contains Condition Code Carry-bit setting in bit 0

RSXSDA
Send data
(SDAT$S)
Parameters
REF R50NAME
Receiver task name

REF ARRAY INT
13-word data buffer

INT
Event flag number
RSXSDC
Send, Request and Connect
(SDRC$S)
Parameters
REF R50NAME
Receive Task Name

REF ARRAY INT
13 word Data Buffer

INT
Event Flag Number

PROC()
AST Service routine

REF E5BLOCK
8 word status block
RSXSDR
Send Data, Request and Pass 
Offspring Control Block
(SDRP$S)
Parameters
REF R50NAME
Receiver task name

REF ARRAY INT
Data Buffer

INT
Buffer length (MAX SIZE = 13)

INT
Control action specification

REF R50NAME
Parent name

INT
Address of OCB to pass (CLI's 
only)
RSXSNX
Send Next Command
(SNXC$S)                                    
11M+
Parameters
REF ARRAY BYTE
Device name (2 ASCII characters)

INT
Unit number of terminal from which 
command is to be sent
RSXVRC
Variable Receive Data
(VRCD$S)                                    
11M+
Parameters
REF R50NAME
Sender task name

REF ARRAY INT
Reply buffer

INT
Buffer length (Max Size = 256)
RSXVRS
Variable Receive Data Or Stop
(VRCS$S)                                     
11M+
Parameters
REF R50NAME
Sender task name

REF ARRAY INT
Reply buffer

INT
Buffer length (Max Size = 256)
RSXVRX
Variable Receive Data Or Exit
(VRCX$S)                                       
11M+
Parameters
REF R50NAME
Sender task name

REF ARRAY INT
Reply buffer

INT
Buffer length (Max Size = 256)
RSXVSD
Variable Send Data Parameters
(VSDA$S)                                       
11M+
Parameters
REF R50NAME
Receiver task name

REF ARRAY INT
Data buffer

INT
Buffer size

INT
Event flag number
RSXVSR
Variable Send, Request & Connect
(VSRC$S)                                       
11M+
Parameters
REF R50NAME
Receiver task name

REF ARRAY INT
Data buffer

INT
Buffer length

INT
Event flag number

PROC()
AST Service routine

REF ESBLOCK
8 word status block

8.8	MEMORY MANAGEMENT ROUTINES
RSXARG
Attach Region
(ATRG$S)
Parameter
REF RSXRDB
Region def. block
RSXCRR
Create Region
(CRRG$S)
Parameter
REF RSXRDB
Region def. block
RSXCRW
Create Window
(CRAW$S)
Parameter
REF RSXWDB
Window def. block
RSXDTR
Detach Region
(DTRG$S)
Parameter
REF RSXRDB
Region def. block
RSXELW
Eliminate Window
(ELAW$S)
Parameter
REF RSXWDB
Window def. block
RSXEXT
Extend Task
(EXTK$S)
Parameter
INT
Length of extension
RSXGMX
Get Mapping Context
(GMCX$S)
Parameter
REF ARRAY RSXWDB
Array of window def. blocks
Note:
(1)  The routine adds the length of an RSXWDB record to the address given 
before calling the Executive, so the address passed to RSX-11M is that of the 
first window block and not that of the array.


(2)  There should be (N+1) window definition blocks in the array where N is 
the maximum number of definition blocks in use, so that the first word of the 
last record will be used for the terminator word if necessary. The user may 
test for the last entry set by RSX-11M by testing the second byte of the 
window definition block (WDBWID) for a value of 255.

RSXGRG
Get region parameters
(GREG$S)
Parameters
INT
Region ID

REF ARRAY INT
3 integers for information
RSXMAP
Map window onto region
(MAP$S)
Parameter
REF RSKWDB
Window def. block
RSXRRF
Receive by reference
(RREF$S)
Parameter
REF RSXWDB
Window def. block
RSXSRF
Send by reference
(SREF$S)
Parameters
REF R50NAME
Task

REF RSXWDB
Window def. block

INT
Event flag
RSXSRR
Set receive by reference AST
(SRRA$S)
Parameter
PROC()
AST routine
Note:
to unset Receive by Reference ASTs, this procedure's parameter should 
take the value RRNUL.

RSXUMP
Unmap Window
(UMAP$S)
Parameter
REF RSXWDB
Window defn. block
8.9	RECORDS USED BY EXECUTIVE ROUTINES
MODE R50NAME	( INT	R50N1,	% First 3 characters in RAD50	%
		R50N2);	% Second 3 characters in RAD50	%
MODE PARBUF	( INT	PARBASE,	% X32 base address	%
		PARSIZE,	% X32 size	%
		PARFLAGS);	% Flags word	%
MODE TIMEBUF	( INT	TIMEYEAR,	% Year since 1900	%
		TIMEMTH,	% Month (1..12)	%
		TIMEDAY,	% Day (1..31)	%
		TIMEHOUR,	% Hour (0..23)	%
		TIMEMIN,	% Minute (0..59)	%
		TIMESEC,	% Second (0..59)	%
		TIMETICK,	% Tick of second	%
		TIMETPS);	% Ticks per second	%
MODE TASKBUF	( INT	TASK11, TASK12,	% Issuing task's name	%
		TASKP1, TASKP2,	% Partition name	%
		TASKR1, TASKR2	% Requesting task's name	%
			% (not RSX-11M)	%
		TASKRUN,	% Run priority	%
		TASKUIC,	% User identification code	%
		TASKNLUN.	% Number of LUNs	%
		TASKMCTY,	% Machine type (not RSX-11M)	%
		TASKSTDF,	% Std flags (not RSK-11M)	%
	  REF	PROC () TASTSST	% First entry in SST vector table	%
	  INT	TASTSST2,	% Size of  SST vector table (words)	%
		TASK15, TASK16,	% Reserved	%
		TASK17);

MODE FLAGBUF	( INT	FLAGLOCAL0,	% Flags  1..16	%
		FLAGLOCAL1,	% Flags 17-32	%
		FLAGCOMMON2,	% Flags 33-48	%
		FLAGCOMMON3);	% Flags 49-64	%
MODE LUNFUB	( INT	LUNNAME,	% Name of device	%
	 BYTE	LUNDEV,	% Unit number of device	%
		LUNDEV1,	% and flags bytes	%
	  INT	LUNCHAR1,	% Characteristics words	%
		LUNCHAR2,		
		LUNCHAR3,		
		LUNSIZE);	% Buffer size	%
MODE IOSTAT	(BYTE	IOSTLOW,	% Error code	%
		IOSTHIGH,	% (remaining bytes are	%
	  INT	IOSTVAL);	%  device dependent)	%
MODE SSTTBL	(PROC()	SSTODD,	% Odd address	%
		SSTSEG,	% Memory protect violation	%
		SSTBPT,	% BPT instruction or cpu T-bit	%
		SSTIOT,	% IOT instruction	%
		SSTRES,	% Reserved instruction	%
		SSTEMT,	% Non-RSX-11M EMT	%
		SSTTRP,	% TRAP instruction	%
		SSTFPX);	% Floating point exception	%
MODE RSXWDB	(BYTE	WDBWID,	% Window id	%
		WDBAPR,	% APR number	%
	  INT	WDBBAS,	% Base address	%
		WDBSIZ,	% Size of window	%
		WDBRID,	% Region id	%
		WDBOFF,	% Offset in region	%
		WDBLEN,	% Length to map	%
		WDBWST,	% Window status	%
	REF INT WDBBUF);	% Start of buffer	%
MODE RSXRDB	( INT	RDBRID,	% Region ident	%
		RDBSIZ,	% Region size	%
		RDBN1,	% Region name (RAD50)	%
		RDBN2,	% Region name (2nd part)	%
		RDBPN1,	% Partition name (RAD50)	%
		RDBPN2,	% Partition name (2nd part)	%
		RDBRST,	% Status of region	%
		RDBPRO);	% Protection word	%

MODE XFLAGBUF	(INT	FLOCAL0,	% Local flags   1..16	%
		FLOCAL1,	% Local flags 17..32	%
		FCOMMN2,	% Common flags 33-48	%
		FCOMMN3,	% Common flags 49-64	%
		FGROUP4,	% Group-global flags 65-80	%
		FGROUP5);	% Group-global flags 81-96	%
MODE ESBLOCK	( INT	STWRD0,	% Offspring task's exit status	%
		STWRD1,	% Next 7 words are reserved	%
		STWRD2,	% for RSX-11M...	%
		STWRD3,		%
		STWRD4,		
		STWRD5,		
		STWRD6,		
		STWRD7);		
MODE RBLOCK	(INT	TASKND1,  TASKND2,	% Sender task's name	%
		TASKND3,  TASKND4	% and data...	%
		TASKND5,  TASKND6,		
		TASKND7,  TASKND8,		
		TASKND9,  TASKND10,		
		TASKND11,TASKND12,		
		TASKND13,TASKND14,		
		TASKND15);		
8.10	AST SERVICE ROUTINES
It is possible to write an interface in Assembler such that the major part of the logic of AST service 
routines may be written in RTL/2. It is necessary, before AST servicing, to create a safe 'compartment' to 
prevent the service routine from corrupting the normal program's environment.
The following examples show how this may be done. It should be noted that there are, unfortunately, 
many stack formats on entry to AST's and, even more unfortunately, the stack does not contain an 
indication of which AST has been spring. Each trap must, for this reason, be set to point at a separate 
label where an indicator may be stacked before entry to the command code.

8.10.1	Example of AST interfacing with several entries
Let RTLAST be an AST service routine, written in RTL/2, of the form:
ENT PROC RTLAST (INT INDIC, REF ASTMODE INFO,INT EFN) INT;
used to handle the following ASTs:
	Power fail
	Receive data
	Receive by reference
and	Mark Time
The procedure parameters have the following significance:

INDIC
a value to indicate which AST has been sprung;

INFO
the standard 4-word information block stacked by 
all ASTs: PS, PC, Eventflag Mask, and DSW;

EFN
the event flag number for the Mark Time trap
(for the other traps this would be undefined).
The returned value is the value of the INT INDIC on entry, so that the exit-trap handling may be informed 
how many words must be stripped from the stack prior to exit.
	MODE ASTMODE ( INT DSW, PS, PC, EVENTS);
The PC is defined as an INT to prevent applications routines from using it directly in a GOTO statement.

On entry to the RTL./2 procedure, the stack needs to be in the following format:
Information block
diag 1		|				|
			|				|
			|	Normal program	|
			|	Work space		|
			|_________________________	|					
			|	|			|
			|	Event Flag Mask	|
			|__________________________|	
			|				|	
			|	PS			|
			|__________________________|	
			|				|	
			|	PC			|
			|__________________________|	
			|				|	
			| 	DSW			|	
			|__________________________|	
			|				|
			|	Event Flag No.		|
			|	(if MARK TIME)		|
			|__________________________|	
			|				|	
			|	Save Area for registers	|
			|	etc.			|
			|				|
			|__________________________|	
			|				|
	| high		|				|
			|	DUMMY LINK CELL	|
Stack addresses	|				|
			|__________________________|	
	| low 		|				|	
			|	INDIC			|
			|__________________________|	
			|				|
			|  .	REF ASTMODE	|
			|__________________________|	
			|				|
			|	EVENT FLAG /0	|
			|__________________________|	
			|				|	
			|	LINK CELL		|
SP=R5		|				|
			|__________________________|

On entry to the Trap address, the stack is set to the following formats by RSX-11M:
1)	Power recovery, Receive data, Receive by Reference
	|					|
	|	EVENT FLAG MASK		|
	|________________________________	|
	|					|
	| 	PS				|
	|________________________________	|
	|					|
	|	PC				|
	|________________________________	|
	|					|
	|	DSW				|	sp
	|________________________________	|
2)	QIO
	|					|
	|	EVENT FLAG MASK		|
	|________________________________	|
	|					|
	|	PS				|
	|________________________________	|
	|					|
	|	PC				|
	|________________________________	|
	|					|
	|	DSW				|
	|________________________________	|
	|					|
	|	STATUS BLOCK ADDR	|	SP
	|________________________________	|

3)	Mark Time
	|					|
	|	EVENT FLAG MASK		|
	|________________________________	|
	|					|
	|	PS				|
	|________________________________|
	|					|
	|	PC				|
	|________________________________	|
	|					|
	|	DSW				|
	|________________________________	|
	|					|
	|	EVENT FLAG NO.		|	SP
	|________________________________	|
4)	Floating Point Exception AST
	|					|
	|	EVENT FLAG MASK		|
	|________________________________	|
	|					|
	|	PS				|
	|________________________________	|
	|					|
	|	PC				|
	|________________________________	|
	|					|
	|	DSW				|
	|________________________________	|
	|					|
	|	FP EXCEPTION CODE		|
	|________________________________	|
	|					|
	|	FP EXCEPTION ADDR		|	SP
	|________________________________	|

5)	DECNET
	|					|
	|	EVENT FLAG MASK		|
	|________________________________	|
	|					|
	|	PS				|
	|________________________________	|
	|					|
	|	PC				|
	|________________________________	|
	|					|
	|	DSW				|
	|________________________________	|
	|					|
	|	OPTIONAL MESSAGE OF	|
	|	N BYTES			|
	|________________________________	|
	|			|		|
	|	N(BYTES)	|	LUN	|
	|___________________|____________	|
	|					|
	|	AST CODE			|
	|________________________________	|
A possible MACRO interface for the routine RTLAST would be as follows (most steps abbreviated for 
clarity).
The AST service routine entry points are specified as:-
	POWER RECOVERY	RSXPOW
	RECEIVE DATA	RSXRCD
	RECEIVE BY REF	RSXRCR
	MARK TIME		RSXMKT
		.CSECT	MACAST
RSXPOW:	MOV		#1,-(SP)	;INDIC = 1
		JMP		GENAST
RSXRCD::	MOV		#2,-(SP)	;INDIC = 2
		 .
		 .
		 .
GENAST:	SUB		#n,SP		;MAKE SPACE FOR REG.SAVE
		MOV		n(SP),0(SP)	;INDIC
		MOV		#2(SP),2(SP)	;SAVE REGs
		MOV		R1,a(SP)	;
		MOV		r2,b(SP)
		 .
		 .		; ETC.
	
; NOW SAVE ERP,ERN IF NECESSARY
; IN FACT ANYTHING THAT MAY BE ALTERED BY THE AST PROCEDURE
	.
	.
	.

; SET REF ASTMODE
		MOV		#n+4,-(SP)
		ADD		SP,0(SP)	;ADDR OF INFO STACKED BY TRAP
; NOW IF TRAP WAS MARK TIME, MUST ADD 2 TO 0(SP) TO POINT TO DSW.
		CMP		#4,2(SP)	;INDIC
		BNE		1$
		MOV		@0(SP),-(SP)	;EVENT FLAG
		ADD		#2,2(SP)	;POINT TO DSW
		BR		2$
1$		CLR		-(SP)		;EVENT FLAG SET ZERO
2$
; STACK NOW IN FORMAT READY FOR RTL/2 PROCEDURE
		JSR		R1,RTLAST
; ON RETURN WE MUST, BY RSX-11M CONVENTION, SET THE SP TO POINT TO THE DSW 
; BEFORE EXIT, EVEN WHEN THERE ARE OTHER PARAMETERS.
; AT THIS POINT THE SP POINTS AT THE PROCEDURE RESULT SO WE MAY DETERMINE 
; HOW MUCH TO ADD TO SP.
			.
			.
			.
;		RESTORE REGISTERS
			.
			.
			.
		ASTX$S	;EXIT TRAP + REMOVE 4 PARAMS

Notes on saving environment
Register 0:	By RTL/2 convention, this points to SVC DATA and is normally untouched by RTL/2 
programs. Consider, however, what happens in a code insert or Exec interface 
routine when register 0 is used to point to a file - either explicitly or implicitly by use 
of an RSX-11M macro. On entry to the RTL/2 AST routine, what ought to be SVC 
data is now an FDB, so access to SVC data inside the AST would have unfortunate 
consequences. So one has to Save Register 0 and set it to point to the SVC data 
before entry to the RTL/2 AST routine. this is fairly easy, as SVC data is at the same 
offset from the initial stack pointer for all programs in a system. The initial stack 
pointer may be obtained from the task header.
Similar consideration must be given to any variable which may be temporarily 
'suspended from duty': other examples are ERL, IN, OUT, etc.
Dummy Link Cell:	This is placed on the stack to prevent a bad GOTO |LABEL variable which might 
bypass the correct AST exit mechanism.

DECNET
Also given for consideration is a possible entry to a DECNET processing routine, which would probably 
be separate from the others.
	PROC RTLNET (INT ASTCODE, LUN, REF ARRAY BYTE MSG,
		REF ASTMODE FRED);
	|						|
	|	NORMAL PROGRAM WORKSAPCE	|
	|_______________________________________|
	|						|
	|	EVENT FLAG MASK			|
	|_______________________________________|
	|						|
	|	PS					|
	|_______________________________________|
	|						|
	|	PC					|
	|_______________________________________|
	|						|
	|	DSW					|
	|_______________________________________|
	|						|
	|	N BYTES OF MESSAGE		|
	|_______________________________________|
	|						|
	|	N					|
	|_______________________________________|
	|						|
	|	SAVE AREA FOR REGISTERS, ETC.	|
	|_______________________________________|
	|						|
	|	DUMMY LINK CELL			|
	|_______________________________________|
	|						|
	|	POINTER TO INFO			|
	|_______________________________________|
	|						|
	|	POINTER TO MESSAGE		|
	|_______________________________________|
	|						|
	|	LUN					|
	|_______________________________________|
	|						|
	|					PC	|
	|_______________________________________|	LINK CELL SP=R5
	|						|
	|				NEXT LINK	|
	|_______________________________________|

Note:	if an REF ARRAY BYTE is used for the DECNET message, the pointer must point at the high 
order byte of the length word - the conceptual zeroth element.
In these examples we have been forced to consider general cases. In any one system, much better (i.e., 
faster ?) entry interfaces may be designed but one must exercise caution against 'optimisations' which 
leave a register or variable unprotected.
Since ASTs are by their very nature 'interrupts', users should localise AST handling and consider 
carefully any actions which might prejudice the security of the RTL/2 program complex. Where 
performance criteria permit, AST handling should be encapsulated and rigorously tested, to provide a 
trusted RTL/2 callable facility.

9.	RSX-11M I/O INTERFACE
9.1	INTRODUCTION
The RTL/2 RSX-11M interface library contains routines to perform the main I/O functions offered by RSX-
11M, typically by calling the equivalent RSX-11M macro. full details of I/O operations should be obtained 
from the appropriate DEC RSX-11M manual and the RTL/2 routines used in this light.
The RTL/2 routines are described in Sections 9.2 to 9.4. They are grouped into sections according to the 
classification used in the DEC RSX-11M I/O Operations Reference Manual.
Note that File Control Routines are not provided because they would require detailed manipulation of 
FDBs and, in some cases, special use of registers (which is not compatible with RTL/2).
Section 9.5 describes the records (i.e., MODE statements) used by the RTL/2 I/O routines and Sections 
9.6 to 9.9 describe the various data areas and code sequences required.
9.2	PREPARING FOR I/O
RTL/2 routines are available to implement the $R-form of the FDB initialisation macros, as described 
below. The default name block and dataset descriptor parameters must be specified, but may contain 
dummy fields. Buffer descriptions, however, are left until record-block transfer time.
Initialisation of the File Storage Region is accomplished at assembly time by a CODE insert as described 
in Section 9.6. The library routine RSXINI may be used to initialise the FSR at run time, as described 
below.
RSXFAT
Initialise or alter the file attribute 
section of an FDB
(FDAT$R)
Parameters
REF FDB
FDB

BYTE
FRTYP entry

BYTE
FRATT entry

INT
FRSIZ entry

INT
FCNTG (=FRCNM) entry

INT
FALOC entry
RSXFRC
Initialise or alter the record access 
section of an FDB
(FDRC$R)
Parameters
REF FDB
FDB

BYTE
FRACC entry
Note:
Buffer information should be supplied to the FDB by RSXGET/RSXPUT.

RSXFBK
Initialise or alter the block access 
section of an FDB
(FDBK$R)
Parameters
REF FDB
FDB

INT
Virtual block number (word 2)

INT
Virtual block number (word 1)

BYTE
Event flag number

REF IOSTAT
I/O status block

PROC ()
AST service routine
Notes:
(1)  If an AST service routine is not required, this parameter should be set 
to RRNUL.
(2)  Buffer information should be supplied to the FDB by 
RSXREA/RSXWRI.

RSXFOP
Initialise or alter the file-open section of 
an FDB
(FDOP$R)
Parameters
REF FDB
FDB

INT
LUN

REF DATAD
Data set descriptor

REF FNB
Default file name block

INT
File access code
(positive to set FFACC, zero if this field is 
to be set up by RSXOPN)
RSXFBF
Initialise block buffer section of FDB
(FDBF$R)
Parameters
REF FDB
FDB

INT
Event flag number

INT
Block buffer size
(zero for RSX-11M default)
RSXINI
Initialise FSR
(FINIT$)
Parameters
None


9.3	FILE PROCESSING
All the OPEN$x and OPNS$x macros in RSX-11M are subsets of one generalised open macro. The 
RTL/2 RSX-11M library offers one OPEN routine to cover these cases, as described below.
The remaining specialised RSX-11M open macros are not offered in the library, but may be performed in 
CODE inserts if required.
The RTL/2 record routines are equivalent to GET$ and PUT$. The random versions of these macros may 
be simulated by manipulation of the File Definition Block by the RTL/2 program. The record buffer for 
each transfer should be specified with the routine call. The FDB MODE statement in Section 9.5 is 
described for record access in move mode. The MODE statement may be changed if locate mode is to 
be used.
The result from the RTL/2 routines in this group is the same as the RSX-11M file error code. Note that 
end-of-line is shown as an error condition by RSX-11M.
RSXOPN
Generalised open
(OPEN$)
Parameters
REF FDB
FDB

INT
File access code
Result
INT
Error reply code
(as FERR, FERR1 in FDB)
Note:
File access codes for RSXOPN are as follows:


Value
Equivalent RSX-11M Macro

Positive or 
zero
OPEN$ - FFACC entry in FDB is set to this value
(allows any combinations of file privileges to be set up)

-  1
OPEN$R

-  2
OPEN$W

-  3
OPEN$M

-  4
OPEN$U

-  5
OPEN$A

-  6
OPNS$R

-  7
OPNS$W

-  8
OPNS$M

-  9
OPNS$U

-10
OPNS$A
RSXCLS
Close specified file
(CLOSE$)
Parameter
REF FDB
FDB
Result
INT
Error reply code
(as FERR, FERR1 in FDB)
RSXGET
Read logical record
(GET$)
Parameters
REF FDB
FDB

REF recmode
Record Buffer

INT
Size of record buffer
Result
INT
Error reply code
Notes:
1.  The RTL/2 user should include in his program a MODE statement for use 
with the routine. If records of several formats are to be read, a CODE insert 
may need to be included in the program, to circumvent the RTL/2 checks, which 
prevent field re-definitions with different types.
2.  The FDB MODE statement (see Section 9.5) will need to reflect the record 
buffer mode.
3.  Unless the linker information is hand-coded by the user, the linkage verifier 
will flag an error with RSXGET.
4.  If a file is to be read in locate mode, the record may not be transferred to the 
named buffer (though the parameter must be present to satisfy linking). The 
FDB will contain information on the record so read. For a description of locate 
mode, refer to the DEC information.

RSXPUT
Write logical record
(PUT$)
Parameters
REF FDB
FDB

REF recmode
Record buffer

INT
Size of buffer (bytes)
Result
INT
Error reply code
Notes:
1.  The RTL/2 User should include in his program MODE statements for use 
with this routine, to describe any areas that records are to be written from.
2.  The FDB MODE statement, as detailed in Section 9.5 will need to reflect the 
record buffer modes.
3.  Unless the User hand-codes the linker information for the routine, and uses 
only one MODE statement for the record per module, the linkage verifier will 
flag an error with RSXPUT.
4.  If the file is to be written in locate mode, the record should be moved to the 
FCS region, and this address supplied to the routine.

RSXREA
Read virtual block
(READ$)
Parameters
REF FDB
FDB

REF recmode
Block buffer

INT
Buffer size (bytes)
Result
INT
Error reply code
Notes:
1.  The RTL/2 User should include in his program a MODE statement for use 
with the routine. If blocks of several formats are to be read, a CODE insert may 
need to be included in the program, to handle "redefined" fields.
2.  The MODE statement for the FDB, as detailed in Section 9.5 needs to be 
edited to reject block I/O usage.
3.  Unless the linker information is hand-coded by the user, linkage verifier will 
flag an error with RSXREA.

RSXWRI
Write virtual block
(WRITE$)
Parameters
REF FDB
FDB

REC recmode
Block buffer

INT
Buffer size (bytes)
Result
INT
Error reply code
Notes:
1.  The RTL/2 User should include in his program MODE statements for use 
with this routine, to describe any areas that blocks are to be written from.
2.  The MODE statement for the FDB, as detailed in Section 9.5 needs to be 
edited to reflect block I/O usage.
3.  Unless the linker information is handcoded by the user, the linkage verifier 
will flag an error with RSXWRI.

RSXDEL
Delete specified file
(DELET$)
Parameter
REF FDB
FDB
Result
INT
Error reply code
RSXWAI
Wait for block I/O completion
(WAIT$)
Parameter
REF FDB
FDB
Result
INT
Error reply code
9.4	COMMAND LINE PROCESSING
Routines are available for both Get Command Line (GCML) and the Command String Interpreter (CSI) as 
described below. The control blocks should be created by CODE sequences as described in Sections 9.7 
and 9.8.
The RTL/2 routines have a shorter set of parameters and options than the RSX-11M equivalent. The 
Logical Unit Number for GCML is LUN1.
The CSI Switch Descriptor Table and Switch Value Descriptor Tables must be described in MACRO, as 
described in Section 9.9.
RSXGCM
Get command line
(GCML$)
Parameters
REF ARRAY BYTE
Buffer to receive command line (any 
remaining bytes space filler)

REF ARRAY BYTE
Prompt string
Result
BYTE
Error reply code (as G.ERR of GCML 
control block)
RSXRCM
Reset indirect command file scan
(RCML$)
Parameters
None

RSXCCM
Close current command file
(COML$)
Parameters
None

Note:
CCML$ is only available in RSX-11M

RSXCSA
Command syntax analyser
(CSI$1)
Parameter
REF ARRAY BYTE
Command string
Result
INT
Zero -> error detected
Positive -> length of compressed string 
in BYTE ARRAY
RSXCSP
Command syntax parser
(CSI$2)
Parameters
BYTE
Request type
I to denote input, 0 for output
(invalid parameters treated as 0).

REF ARRAY SWTAB
Switch Descriptor Table (see notes 
below)

REF INT
Switch reply indicator
(INT set to zero/one by RSXCSP if C bit 
clear/set after CSI$2)
Result
REF DATAD
Pointer to dataset descriptor produced 
by command syntax parser
Notes:
1.	If a switch table is not to be supplied, the second parameter should be a reference to an ARRAY (0) 
SWTAB.
2.	It is not possible to fully describe entries in the Switch Descriptor Table in RTL/2
(e.g., several table entries are one bit long, in words otherwise used for addressing).
3.	RSXCSP assumes that a command string is in the buffer supplied to the immediately preceding 
RSXCSA call.
If only a few switches are likely to be encountered, it is recommended that no switch tables are used. If 
any switches are present in the command line, the switch reply indicator will be set to one. The switch 
may then be processed in user written RTL/2.
If there are a large number of possible switches, Switch Descriptor Tables may be considered. One 
possible method of setting up Switch Descriptor Tables and Switch Value Descriptor Tables for use by 
RTL/2 programs is described in Section 9.9.

9.5	RECORDS USED BY I/O ROUTINES
Refer to the DEC I/O Operations Manual for descriptions of all fields.
MODE FDB (BYTE FRTYP,FRATT,	%==FILE ATTRIBUTE SECTION=	%
	INT	FRSIZ,FHIBK,FHIBKI,
		FEFBK,FEFBK1,FFFBY, %		==RECORD OR==	%
	BYTE	FRACC,FRCTL,		%=BLOCK ATTRIBUTE SECTION==	%
	INT	FURBD,		% INT FBKDS				%
	REF	RECMODE FURBD1,	%REF RECMODE FBKDS1		%
	INT	FNRDB,		%REF IOSTAT FBKST			%
	REF	RECMODE FNRBD1,	%PROC ( ) FBKDN			%
	INT	FNREC,		%INT FOVBS				%
		FEOBB,	
		FRCNM,		%INT FCNTG				%
		FRCNM1,		%REF MODE FSTBK			%
	INT	FALOC,			%====FILE OPEN SECTION===	%
	BYTE	FLUN,FFACC,
	REF	DATAD FDSPT,
	REF	FNB FDFNB,		%===BLOCK BUFFER SECTION===	%
	BYTE	FBKEF,FBKP1,FERR,FERR1,
		FMBCT,FMBC1,FMBFG,FBGBC,
	INT	FBVSZ,FBBFS,
		FBKVB,FBKVB1,
		FBDB,
	BYTE	FSPDV,FSPDV1,
	BYTE	FSPUN,FDBUMMY1,
	INT	FDBDUMMY2,FDBDUMMY3,
	INT	FNFID,FNFID1,FNFID2,FNFNAM,FNFNM1,FNFNM2,
					%FILENAME				%
		FNFTYP,FNFVER,FNSTAT,FNNEXT,
					%BLOCK				%
		FNDID,FNDID1,FNDID2,
	BYTE	FNDVNM,FNDVNM1,
	INT	FNUNIT);

MODE IOSTAT (BYTE	IOSTLOW,		%ERROR CODE		%
			IOSTHIGH,		%(REMAINING BYTES		%
		INT	IOSTVAL);		%DEVICE DEPENDENT)	%
(also see Section 8.9)
MODE DATAD (INT	DEVNML,		%DATASET			%
	REF	BYTE	DEVNMA,		%DESCRIPTOR			%
		INT	DIRNML,
	REF	BYTE	DIRNMA,
		INT	FILNML
	REF	BYTE	FILNMA);
Note:	References are to first item in a byte array.
MODE FNB (INT	NFID,NFID1,NFID2		%DEFAULT		%
			NFNAM,NFNAM1,NFNAM2, 	%FILENAME		%
			NFTYPE,NFVER,		%BLOCK		%
			NSTAT,NNEXT,
			NDID,NDID1,NDID2,
		BYTE	NDVNM,NDVNM1,
		INT	NUNIT);
9.6	FILE STORAGE REGION
RTL/2 programs using the RSX-11M file routines (other than stream I/O) must include at task build a 
module containing code of the following form, either within RTL/2 or in Assembler:
CODE 0,0;
	.MCALL	FSRSZ$
	FSRSZ$	files, bufsiz
*RTL;
where 'files' is the number of files that can be open simultaneously for record I/O and 'bufsiz' is the total 
block buffer pool size. These parameters are described fully in the RSX-11M I/O Operations Reference 
Manual (under FSRSZ$).
The module need not be called or referenced in the main RTL/2 program.

9.7	GCML CONTROL BLOCK
RTL/2 programs using Get Command Line must include at task build a module containing code of the 
following form, either in RTL/2 or in Assembler directly:
CODE 0,0;
	.PSECT	RTLGCM
	.MCALL	GCMLB$,GCMLD$
	GCMLD$
RTLGCM::	GCMLB$	maxd
	.PSECT
*RTL;
where 'maxd' is the maximum nesting depth to the permitted for indirect command files.
9.8	CSI CONTROL BLOCK
RTL/2 programs using the command string interpreter must include at task build a module containing 
code of the following form, either in RTL/2 or in Assembler directly:
	CODE 0,0;
		.PSECT	RTLCST
		.MCALL	CSI$
		CSI$
		.EVEN
RTLCST::	.BLKB	c.SIZE
		.PSECT
	*RTL;
9.9	CSI SWITCH DESCRIPTOR TABLES
9.9.1	Introduction
It is not possible to create all the fields in a CSI Switch Descriptor Table using an RTL/2 MODE 
statement, as the table entries do not conform to the standard data formats.
The Switch Descriptor Table, Switch Value Descriptor Tables and any associated fields should be set up 
by MACRO in a separate module (possibly a CODE insert in an RTL/2 module). RTL/2 modules which 
call RSCCSP should contain a description of this module in an EXT DATA brick, using simplified MODE 
statements.
This procedure is described below.

9.9.2	CODE Module
CSI Switch Descriptor Tables should be set up in the following way:-
			.MCALL CSI$SW,CSI$SV,CSI$ND
			.EVEN
	table name	::
			.WORD		X1-.+2 ; ARRAY LENGTH
			CSI$SW	parameters as described in RSX-11M manual
			CSI$SW	(macro call for each table entry)
			CSI$SW
			.
			.
			.
X1 :			CSI$ND	; any further switch tables
			.WORD		X2-.+2
Value table:		CSI$SV		parameters as described in RSX-11M manual
			CSI$SV		(macro call for each table entry)
			.
			.
			.
X2 :			CSI$ND
another value:		.WORD		X3-.+2
			CSI$SV		---
X3 :			CSI$ND
name:			.WORD		0 ; any words to be set/unset by the switch processing
Note:	Any items referred to by parameters to CSI$SW or CSI$SV should be described in this module.
9.9.3	EXT DATA brick
Switch Descriptor Table entries may be described (in a simplified form) as:
MODE SWTAB (BYTE	SWCHAI, SWCHAZ,
		INT	SWMASK,
		REF	ARRAY INT SWWORD,
		REF	SVTAB SWSVT);
Switch Value Descriptor Table entries must be described as
MODE SVTAB (BYTE	SVCTYP, SVLENG,
		REF	INT SVWORD);
  The entire CSI Switch Table can thus be described in an RTL/2 data brick as:
EXT DATA table name;		%SAME NAME AS GLOBAL IN CODE MODULE	%
	ARRAY (n) SWTAB array name;
	INT DUMMY1;			%EQUIVALENT TO CSI4ND ENTRY	%
	ARRAY (m) SWTAB array name;
	INT DUMMY2;			%FURTHER SWITCH TABLES		%
	ARRAY (x) SVTAB array name;	
	INT DUMMY3;			%VALUE TABLE			%
	ARRAY (y) SVTAB array name;
	INT DUMMY4;
	.
	.
	.
	INT reply_word_1,		reply word 2 ...
					%WORDS MASKED OR RESULTS	%
					%GIVEN BY SWITCH PROCESSING	%
ENDDATA;

10.	MATHEMATICAL ROUTINES
10.1	INTRODUCTION
This section describes the set of mathematical routines. as supplied, they are tuned to give maximum 
accuracy for the PDP-11. They are delivered in source form so that the user can view the techniques 
used. If the requirement is for faster but less accurate calculations, the user can adapt them to use fewer 
terms of the Chebyshev series.
Note:
Notation:- Ranges of values are indicated using square brackets to denote that the end value is included 
and round brackets to denote that the end value is excluded. Thus the statement
		x is in (1,2]
is equivalent to
		1 | x | = 2
10.2	SPECIFICATIONS OF THE MATHS ROUTINES
The Maths Routines supplied are listed below, together with details of any errors which may occur, and of 
valid ranges for the arguments.
10.2.1	Trigonometric Functions
The ranges of valid arguments are given in terms of machine-dependent values SINETOP and TANTOP, 
which are fixed in LET statements in the RSIN and RTAN modules respectively.
PROC RSIN(REAL X)REAL
This returns the sine of X radians. Recoverable error 302 is reported, and 0.0 returned, if X is not in the 
range <- /2 x SINETOP, /2 x SINETOP>. A Chebyshev series is used.
PROC RCOS(REAL X)REAL
This returns the cosine of X radians. Recoverable error 302 is reported, and 0.0 returned, if X is not in the 
range <- /2 x SINETOP - /2 x SINETOP - /2>. The result is obtained from the RSIN procedure, using the 
identity cos x = sin (x + /2).

PROC RTAN(REAL X)REAL
This returns the tangent of X radians. Recoverable error 302 is reported, and 0.0 returned, if X is not in 
the range <-TANTOP,TANTOP>, or if the tangent has no finite value (i.e., x=(n+1/2) for some integer n).
A Chebyshev series is used.
10.2.2	Inverse Trigonometric Functions
PROC RASIN(REAL X)REAL
This returns the principal value, in radians, of the inverse sine of X, i.e., the value returned is in <- /2, /2>. 
If X is not in <-1,1> then recoverable error 304 is reported 
								   -1	
and 0.0 is returned. A Chebyshev series for sin x, |x|| /2 is used
                               2     2      -1
together with the identities cos x = 1-sin x and sin x +
  cos-1 x = /2.
PROC RACOS(REAL X)REAL
This returns the principal value, in radians, of the inverse cosine of X, i.e., the value returned is in <0, >. If 
X is not in <-1,0> then recoverable error 304 is reported and 0.0 is returned. The method used is the 
same as for RASIN, - see 1.2.1 above.
PROC RATN(REAL X)REAL
This returns the principal value, in radians of the inverse tangent of X, i.e., the value returned is in (-*/2, 
/2). Any real value X is a valid argument. A Chebyshev series is used.
PROC RATAN(REAL X,Y)REAL
This is a two-argument inverse tangent function returning (in radians) the angle in 
(- , ) between the positive Cartesian x-axis and the line joining the origin to the point with Cartesian co-
ordinates (X,Y). Thus RATAN (X,Y) is equivalent to RATN(Y/X), with retention of the quadrant.

e.g.,	RATAN (1, - 3) = - /3
	RATAN (-1, 3) = 2 /3
	RATAN (1,1) = /4
	RATAN (-1,-1) = 3 /4
Recoverable error 304 is reported, and 0.0 is returned, if X=Y=0.0 or if Y/X numerically exceeds the 
maximum REAL number.
The result is found using RATN(Y/X), after checking that Y/X can be evaluated, and changing the 
quadrant as necessary.
10.2.3	Exponential and Logarithmic Functions
PROC REXP(REAL X)REAL
                         x
This returns the exponential of X (e ). Recoverable error 203 is reported,. and 0.0 is returned, if X 
exceeds a machine-dependent value EXPTOP, which is fixed in a LET statement in the REXP module. (If 
X|-EXPTOP, 0.0 is returned but no error is reported). A Chebyshev series is used, together with direct 
manipulation of REAL Numbers using SSXEXP.
PROC RLOGE(REAL X)REAL
This returns the natural (base e) logarithm of X. Recoverable error 301 is reported, and 0.0 is returned, if 
X|0.0. A Chebyshev series for log (1+x) is used, together with direct
                   e
manipulation of REAL numbers using SSXEXP.
PROC RLOG(REAL X)REAL
This returns the common (base 10) logarithm of X. Recoverable error 301 is reported, and 0.0 is 
returned, if X|0.0.
The result is obtained by calling RLOGE and multiplying the value returned by the constant log   e
          10
10.2.4	Power Functions
PROC RPOWR(REAL X,Y)REAL
This returns the value of X raised to the power Y. If the result is too small to be represented as a non-
zero value, 0.0 is returned but no error is reported.

RPOWR (X,0.0) returns 1.0 for any non-negative X (including 0.0). Recoverable errors are reported in the 
following circumstances (in each case 0.0 is returned);
If X|0.0						error 305
If X=0.0 and Y|0.0				error 305
   Y
If X ^ EXPTOP					error 303
    e
The result is calculated using the procedures REXP and RLOGE.
PROC RPOWI(REAL X, INT Y)REAL
This returns the value of X raised to the power Y. X may be negative (this is not true 
                      Y
of RPOWR). If the value of X  is numerically too small to be represented as a non-zero value, 0.0 is 
returned but no error is reported.
RPOWI(X,0) returns 1.0 for any X (including 0.0).
Recoverable errors are reported in the following circumstances (in each case 0.0 is returned).
	If X=0.0 and Y|0				error 305
	   Y
	If X  ^MAXREAL				error 303
(MAXREAL is contained in the data brick RRENV.)
The result is calculated by multiplying the appropriate factors from the sequence
    2   4   8
X, X  , X  , X  ,....
10.2.5	Square Roots
PROC RSQRT(REAL X)REAL
This returns the (non-negative) square root of X. Recoverable error 300 is reported, and 0.0 is returned, if 
X|0.0.
The method used is a linear approximation, followed by Newton-Raphson iterations, together with direct 
manipulation of REAL numbers using SSXEXP.

PROC FSQRT(FRAC X)FRAC
This returns the (non-negative) square root of the fraction X. Recoverable error 300 is reported, and 
0.0B0 is returned, if X|0.0B0.
The method used is a linear approximation, adjusted to the range of the argument by shifting, followed by 
Newton-Raphson iterations.
10.2.6	Random Numbers
To use the random number generator, the MODE RRSEED must be defined as follows:
MODE RRSEED (INT SINT1, SINT2, SINT3);
and an insurance of RRSEED must be declared and initialised (any integer values may be used).
PROC RNDOM (REF RRSEED)REAL
returns a value in the range (0,1), generated from the instance of RRSEED referenced by its parameter, 
and changes the values of the components of that instance of RRSEED, so that calling RNDOM again 
with the same parameter gives a different result. Successive calls of RNDOM with the same parameter 
return numbers which are uniformly distributed over the range (0,1).
This provides a considerable amount of flexibility. Restoring the components of an instance of RRSEED 
to earlier values allows the same sequence of "random" numbers to be repeated, and any number of 
independent streams of random numbers can be obtained by using a separate instance of RRSEED for 
each and supplying the appropriate one whenever RRSEED is called. The current state of any stream 
can be saved at any time by copying the appropriate instance of RRSEED, and can be restored at any 
later time simply by copying the old values back again.
The procedure RNDOM does not report any errors.
The method of generating the "random" numbers from an instance of RRSEED is described in "An 
Efficient and Portable Pseudo-Random Number Generator" by B.A. Wichmann and I.D. Hill. Three 
independent multiplicative congruential generators, each using one component of RRSEED, are each 
used to produce a number in (0,1) whenever RNDOM is called. The value returned is the fractional part 
of the sum of these 3 results. This produces values which are more "random" than those which would be 
produced by a single multiplicative congruential generator.

10.3	CONTENTS OF MODULES
The modules containing the Maths Routines are as follows:
Module Name			ENT Procedures Contained
RSIN				RSIN, RCOS
RTAN				RTAN
RASIN				RASIN, RACOS
RATAN				RATN, RATAN
REXP				REXP
RLOGE				RLOGE
RLOG				RLOG
RPOWR			RPOWR
RPOWI				RPOWI
RSQRT				RSQRT
FSQRT				FSQRT
RNDOM			RNDOM
10.4	INTERDEPENDENCE OF ROUTINES
Some of the Maths Routines require other modules; either other Maths Routines, or the module SSXEXP 
which allows direct manipulation of REAL numbers, or the data brick RRENV (which may be available in 
the Run-Time Support Routines). The modules required by each routine (excluding that containing the 
routine itself) are shown in the list below:
Routine				Other Modules Required
RSIN				NONE
RCOS				NONE
RTAN				NONE
RASIN				RSQRT, (SSXEXP)
RACOS			RSQRT. (SSXEXP)
RATN				RRENV
RATAN				RRENV
REXP				SSXEXP
RLOGE				SSXEXP
RLOG				RLOGE, (SSXEXP)
RPOWR			RLOGE, REXP, (SSXEXP)
RPOWI				RRENV
RSQRT				SSXEXP
FSQRT				RRENV
RNDOM			NONE
Modules shown in brackets are required "indirectly", e.g., RASIN does not itself call SSXEXP, but it does 
call RSQRT, which requires SSXEXP.

11.	RECORD MANAGEMENT SERVICES
11.1	INTRODUCTION
An interface to RMS-11 (Record Management Services) is provided to the RTL/2 programmer through a 
library of RTL/2 macros. (Refer to Section 5 and Appendix B for a description of the use of the RTL/2 
Macro Processor and the Macro Processor language). This interface is pitched at a sufficiently low level 
to permit all the facilities of RMS to be accessed readily and with minimal run-time overheads. The user 
of the RMS interface should be familiar with RMS concepts as described in DEC documentation 
(particularly RMS-11 MACRO Programmer's Reference Manual).
The RMS interface macros plan CODE statements in the user's program, and hence calls to them should 
be made only in PROC bricks.
11.2	DECLARING RMS FACILITIES
MCALLS
The user should make a call to the RTL/2 macro MCALLS prior to other calls to the RMS interface 
macros; this will plant all the necessary .MCALL directives in his program.
ORG
The macro ORG is used to declare the processing environment; one or more calls to ORG should be 
coded in a dummy PROC brick (i.e., a procedure which is never called), each call declaring a unique 
combination of file organisation and record operations. The ORG macro takes one parameter, the form 
being equivalent to the list of parameters of the ORG$ RMS-11 MACRO facility, but surrounded by the 
RTL/2 macro-processor trip-1 character, e.g.,
	&CALL ORG &SEQ,GET&?
POOL
Pool space requirements are specified by calling the RTL/2 macro POOL in a dummy PROC brick; this 
macro takes as parameters a sequence of paired keywords and values corresponding to MACRO-11 
usage of the space pool macros, e.g.,
	&CALL POOL BDB,3,FAB,2,RAB,2,BUG,1024?

equivalent to the MACRO-11 coding
	POOL$B
	P$BDB 3
	P$FAB 2
	P$RAB 2
	P$BUF 1024
	POOL$E
INIT OR INITIF
A call to one of the two macros INIT or INITIF should be made by the user to initialise the RMS system at 
run time (the INITIF macro performs initialisation only if it has not already been done). These macros take 
no parameters.
11.3	CONTROL BLOCKS
The following RTL/2 macros are provided for the declaration of control blocks
	FAB	RAB	XAB	NAM
These take parameters as follows:
	the symbolic name to be given to the control block;
	for FAB and NAM, the second parameter is null; for RAB it should be SYN or ASYN for 
synchronous only, or synchronous and asynchronous record operations respectively; for XAB it should be 
the type of attribute information the block is to contain - the MACRO-11 symbolic value is given, 
surrounded by the RTL/2 macro-processor trip-1 character, e.g.,
&XB$ALL&
the remainder of the parameter list consists of pairs of keywords and values, corresponding to MACRO-
11 usage of RMS; where a value contains a character which cannot be part of an RTL/2 name it should 
be surrounded by the macro processor trip-1 character.

An example follows of a call to declare a File Access Block:
	&CALL FAB MSTFAB,,FAC,&FB$PUT&,LCH,3?
-	this declares a FAB named MSTFAB; it sets the field FAC (file access) to
FB$PUT (allowing PUT operations) and the field LCH (logical channel number) to 3.
Calls to the RTL/2 Control Block macros should be coded in a dummy procedure brick.
An additional macro (SETADD) is provided to facilitate usage of RTL/2 objects within the Control Block 
macro calls. SETADD takes two parameters, the first a symbolic name, the second a CODE statement-
style expression using an RTL/2 item, and assigns the latter to the former, which may then be used as an 
address in a call to a Control Block macro.
Thus suppose an RTL/2 program contains the declaration:
	DATA LOCAL;
		ARRAY (80) BYTE BUFFER;
	ENDDATA;
-	if the user wishes to set the field RBF of a RAB to point to the array BUFFER,
	he could write:
	&CALL SETADD BUFFAD, &*BUFFER/LOCAL+1&?
	&CALL RAB MYRAB,SYN,RBF,BUFFAD?
-	note the +1 in the second parameter of SETADD to convert the address
from that of the zeroth element of the array to that of the first (this being the address to which data will be 
read).
11.4	RMS RUN TIME FACILITIES
The following macros are provided and have a corresponding function to their MACRO-11 equivalent:
CREATE			OPEN				DISPLAY
ERASE				EXTEND			CLOSE
CONNECT			DISCONNECT			FIND
GET				PUT				UPDATE
DELETE			REWIND			TRUNCATE
FLUSH				NXTVOL			READ
WRITE				SPACE

All take one parameter; this is either (i) the symbolic name given to a File or Record Access Block, 
according to whether the operation is on a file or record; or (ii) the access block symbolic name followed 
optionally by the address of a failure completion routine, itself followed optionally by the address of a 
success completion routine, the whole enclosed in macro-processor trip-1 characters. For example, to 
open the file described by the FAB labelled MSTFAB, one could write
	&CALL OPEN MSTFAB?
11.5	ACCESSING CONTROL BLOCK FIELDS AT RUN TIM
The following RTL/2 macros are provided for setting and fetching fields of control blocks and correspond 
to their MACRO-11
	FETCH		OFF
	SET		STORE
These take 3 parameters:
.	the destination or value to be used in the operation
.	the 3-character name of the field within the control block to be used in the
	operation
.	the symbolic name of the control block to be used in the operation
e.g., &CALL SET &##FB$GET&,FAC,MSTFAB?
-	this sets the bit in the file access (FAC) field of the FAB labelled MSTFAB to indicate GET 
operations will be performed on the associated file; note that the trip-1 character must surround the first 
parameter as it contains non-RTL/2 name characters.
Four further macros are provided to allow conditional branching to be carried out on the result of 
$COMPARE or $TESTBITS RMS-11 MACRO operation. These RTL/2 macros are:
	IFEQGO		IFNEGO
	IFBEQGO		IFBNEGO

and take four parameters:
.	the source of the value to be used in the comparison
.	the 3-character name of the field within the control block to be used in the
	operation
.	the symbolic name of the control block to be used in the operation
.	the destination of the conditional branch (an RTL/2 LABEL expression)
The macro IFEQGO and IFBEQGO branch on equality; the other two on inequality.
The macro IFEQGO and IFNEGO correspond to the assembler $COMPARE; the other two to 
$TESTBITS.
For example, to branch to RTL/2 label EOF if the STS field of INRAB contains the value ER$EOF, one 
could write:
	&CALL IFEQGO &#ER$EOF&,STS,INRAB,EOF?
11.6	USING THE RMS INTERFACE
The interface macros are held in the file RSXRMS.CND. To use them in a program (e.g., 
MYPROG.CND), the RTL.2 macro-processor is first run as follows:
	RMP MYPROG = RSXRMS,MYPROG
and the output compiled:
	RTL MYPROG = MYPROG/CN:F
and assembled:
	MAC MYPROG = RMSMAC/ML,MYPROG
Note that the compilation requires the switch CN:F as the macro-processor will plant code statements 
where the RMS Interface is used.

The interface library defines macro-processor trip characters as follows:
	trip-1 = &
	trip-2 = @
	trip-3 = ?
and these definitions have been assumed in the examples given though the user may of course over-ride 
them.
11.7	EXAMPLES
	An example program is described in Appendix C.

A.	CROSS-REFERENCE INFORMATION
A.1.	INTRODUCTION
This information is output by the RTL/2 compiler to the third output dataset specified in the compiler's 
command string.
It is arranged as a series of separate items, each starting a new line, and each being written as an 
assembler comment. Each type of item is indicated by a key letter, which is the first non-layout character 
to be found after a semi-colon. An item of data looks thus:
	; <key letter> <data item list>
Spaces embedded within the data of an item will be ignored.
A.2	KEY LETTER INTERPRETATION
The following output is generated by the RTL/2 compiler. The Linkage Verifier interprets cross-reference 
items which begin with the key-letter types M,W,N,R or X. The terms <name>, <int> and <spec> are 
defined in A.3 below.
External References - X
Items with the key letter 'X' appear for every EXT or SVC declaration in an RTL/2 module, and for control 
routines and any other 'R' number labels used. There are five forms:
XP, <name> , <spec> 	which defines an EXT PROC brick
XS, <name> , <spec>		which defines an EXT STACK brick
XU, <name> , <spec>		which defines an SVC DATA brick
XV, <name> , <spec>		which defines an SVC PROC
XY, <name> , <spec>		which defines an EXT DATA brick
and XRnn which defines an external 'R' number.
Entry Points - N
Items with key letter 'N' define the name and specification for every entry point in a module. There are 
five forms:
NP, <name> , <spec>		for an ENT PROC brick
NS, <name> , <spec>		for an ENT STACK brick
NU, <name> = <int> , <spec>	for an SVC DATA brick
NV, <name> = <int> , <spec>	for an SVC PROC
NY, <name> , <spec>		for an ENT DATA brick

Note the SVC DATA and SVC PROC items define an entry integer value as well as a name and 
description. This integer is included for cross-reference file format compatibility with other RTL/2 
implementations, where it is not used it may be zero.
SVC DATA entries define the symbol type for the offset in bytes of that data brick from the start of the 
SVBC area. The offset itself is defined by a global equate in the run time base program.
SVC PROC entries define the symbol type for a system-wide PROC entry; addresses are resolved by the 
linker. Note that an SVC PROC entry point cannot be declared in RTL/2.
Note that 'R' numbers are not defined by 'N' items. See 'R' below.
Control Routine - R
This item defines a control routine so that it may be used in this and other modules. The format is:
	Rnn = <int>
The integer is included for cross-reference file compatibility with other RTL/2 implementations, where it is 
not used it may be zero.
Module Name - M
This gives the module name (from the argument given to the compiler /TI switch). The format is:
	M <name>
The name is by the Verifier in some messages.
End of Module - W
The key letter W denotes the end of the cross-reference information for a module.
RTL/2 TITLES - T and RTL/2 OPTIONS - O
TITLE and OPTION statements appear in the cross-reference information. TITLEs are reproduced with a 
key letter 'T' before each line of the TITLE text. OPTIONs are reproduced verbatim with key letter 'O'.

Local Bricks - E and ENT Bricks - B
Brick names appear in the cross-reference information with key letter 'E' if ENT or 'B' otherwise.
Lengths of Bricks - L
The brick sizes appear in the cross-reference information as:
	;L = <size>
The size is in octal bytes. The first ';L=' line is for the string pool.
A.3.	NOTATION FOR DATA ITEMS
In the description of items, the following symbols are used:
<int>	this indicates an integer in Macro-11 format, i.e., the default radix is octal.
<name>	this indicates the name of an RTL/2 brick or module. It should be noted that the Linkage 
Verifier, like the assembler and task builder, restricts names to a maximum of six characters. 
Longer RTL/2 names are, therefore, truncated.
<spec>	this is the brick specification string output by the compiler. It gives, in a coded form, a list of 
data types or parameters and results involved, and is used by the Verifier to check that, for 
example, the description of an EXT data brick is correct. The symbols used in these strings 
are as follows:
B	byte
I	int
F	frac
R	real
P	proc
L	label
S	stack
E	ref
X	ref array
A	array. This will be followed by the bounds of the array (decimal) separated by a ',' if 
there are more than one.
M	mode. This will be followed by a specification of the mode and terminated by an 'N', or, 
if this mode definition is already in the specification string, by a backward pointer 'Y'.
N	end of mode.
Y	backward mode pointer. This will be followed by an integer that indicates the position of 
the relevant mode definition in the string as count of characters from the beginning of 
the string.
Q	type or result of proc. Followed by the characters defining the result of the procedure, or 
by a '0' if the procedure returns no result.
T	repetition factor. This will be followed by an integer to indicate the number of repetitions. 
Not used in record specifications.
Z	string terminator.
A.4	EXAMPLES
Two examples of cross-reference information are:
1)	ENT PROC OUTTP (BYTE X)
which would result in the following cross-reference data:
	;N P, OUTTP, BQ0Z

2)	ENT DATA DTX;
	INT I,J;
	REC HOLDER;
	REF REC PTR;
	REF ARRAY BYTE RAB;
	ENDDATA;
which if REC is defined by MODE REC (INT I1, I2, BYTE B3); would yield
	;N Y,DTX,IT2MIIBEY4XBZ
It can be seen that it is easily possible for these specification strings to be too long to fit on a single line. If 
this is the case they continue on as many continuation lines as are necessary, each line starting with a 
semi-colon.
A.5.	COMPILER GENERATED DATA
Cross-reference items are arranged by the compiler in two main groups. The first group describes the 
EXT, SVC or ENT declaration appearing in the module, i.e., the names and parameter or data layouts 
which the Verifier must check. The second group define the layout of the compiled brick structure of the 
module in sufficient detail to enable the program to be linked in other operating systems. This second 
group is ignored by the Verifier.
In addition, cross-reference information will contain details of non-RTL/2 external references. These 
include:
i)	'R' numbers, i.e., labels of the form Rnn (nn being 2-digit decimal numbers in
the range 00 to 99) which represent control routines or other system addresses and constants.
ii)	Entry values for SVC PROC and SVC DATA. The compiler will generate
external reference calls for standard control routines. Other non-RTL/2 items are inserted by hand either 
via the compiler in CODE statements or in hand-written modules - see next section.
A.6.	HAND-CODED CROSS-REFERENCE INFORMATION
A user may wish to include non-RTL/2 items of his own specification in the Cross-Reference Information. 
Such information is directly supplied to the linkage verifier or placed within code sections.
A.6.1	Code Sections
The compiler will interpret a line within a code section of the form:
	&CR <data>
as information intended for the cross-reference file.
For example, if an SVC PROC were being declared the user might write:
	&CR NV, CHANGE=128., Q0Z
which would appear in the compiler output as:
	;NV, CHANGE=128.,Q0Z
Notice that it is not necessary to include the semi-colon before the type key letters when writing the data 
in a code section.

A.6.2	Direct hand coding
Cross reference information must begin with an 'M' line containing a valid module name, unique to six 
characters, and must end with a 'W' line. the order of its contents is immaterial.
For specifications to match with compiler-generated item specifications, the specification character string 
must be identical with compiler output, e.g., where the compiler generates a repeat character, the 
handcoded string must use a repeat character, rather than duplicating the item characters.

B.	MACRO PROCESSOR LANGUAGE
B.1	INTRODUCTION
A macro processor is a facility for replacing one sequence of characters with another. There are two 
kinds of input to a macro processor - these are the macro definitions and the source text in which the 
string replacements are to be made.
As an example of a macro, consider the following:
	X: = A;
	A: = B;
	B: = X;
This piece of code simply interchanges variables A and B. If a sequence of instructions like this was 
performed several times throughout a program, one could save time (and paper) by defining a macro as 
follows:
	MACRO SWAPAB;
		X: = A;
		A: = B;
		B: = X;
	ENDM;
This is an example of a macro definition. The keyword MACRO tells the processor that a macro is to be 
defined. The name of the macro, i.e., the sequence of characters to be replaced, immediately follows 
MACRO, so this macro has the name SWAPAB. The lines of code between this line and the ENDM 
keyword constitute the macro body. Now, whenever we want to swap variables A and B in a program, we 
may write, e.g.,
	CALL SWAPAB
and our three lines of code will be output in its place.
The only failing of our macro at the moment is that, if we want to swap variables P and Q, we still have to 
write the code explicitly.
To circumvent this problem, we parameterise our macro as follows:
	MACRO SWAP A,B;
		X: = A;
		A: = B;
		B: = X;
	ENDM;

The name of our macro is now SWAP; A and B are formal parameters which will be replaced by actual 
parameters when the macro is called.
Now, if we want to swap two variables, P and Q say, we would write
	CAL SWAP P,Q;
and the macro processor would output
	X: = P;
	P: = Q;
	Q: = X;
An alternative syntax for parameterising our macro could have been as follows:
	MACRO SWAP;
		X: = #1;
		#1: = #2;
		#2: = X;
	ENDM;
In this case the actual parameters of the macro call are accessed by their position in the parameter list. 
The special character # indicates that a parameter is to be substituted, with the integer following 
indicating which parameter.
Thus, in our call
	CALL SWAP P,Q;
#1 would refer to P,
#2 would refer to Q.
This latter approach is the one taken by the RTL/2 Macro Processor.
A further facility offered by the RTL/2 Macro Processor is conditional processing, i.e., the inclusion or 
exclusion of text depending on the definition of macro time variables. By using this facility one can, for 
example, tailor software to make full use of the hardware available on a particular machine. Thus, one 
might generate software which uses hardware multiply and divide units when they are available, and 
otherwise generates long-hand routines to do these jobs. In this way one might have 
	IF DF HMD:
	MUL A,B	;	Hardware multiply
	IFF
	JSR MUL A,B	'	Software multiply
	ENDC;
    

In the above piece of text, the keyword IF begins a conditional block. ON recognising the IF, the 
processor will evaluate the condition, in this case DF HMD, where DF is an operator which sets the 
condition to true if HMD (hardware multiply/divide) is defined, false otherwise.
If the condition is true, the line of code following will be output. If the condition is false, then the line 
following the keyword IFF will be output. The keyword ENDC ends the conditional block.
To save writing the block every time we wish to do a multiplication, we could define a macro
	MACRO MULT;
	IF DF HMD
		MUL #1.#2
	IFF
		JSR MUL #1,#2
	ENDC
	ENDM
and now we would simply write
	CALL MULT P,Q
to multiply P and Q.
In all the examples in this introduction, the keywords have stood by themselves. This is known as "free 
mode" processing. It has the disadvantage that every string of characters must be checked to see 
whether or not it is a keyword, and this makes the processor rather slow.
The alternative is to run in "warning mode". Here every keyword is preceded by a special character, 
known as a "trip character", which will tell the processor that the word following is a keyword. This makes 
the processor run faster, and also allows the use of keywords for other purposes.

Thus, if the trip character was &, then
	&MACRO	would tell the processor that a macro was following
	MACRO	would just be a string of characters with no special meaning
			to the processor.
The RTL/2 Macro Processor is one which runs in warning mode, and allows parameterised macros and 
conditional processing blocks, together with other powerful constructs.
B.2	TRIP CHARACTERS
As stated in the introduction above, the Macro Processor runs in warning mode. Three trip characters are 
used, known as the command trip, substitution trip, and the terminator trip. Henceforth these trip 
characters will be written as
	<TI> ::= command trip
	<T2>::= substitution trip
	<T3>::= terminator trip
These trip characters must obey the following rules:
a)	<T1>, <T2>, <T3> must be mutually distinct.
b)	Neither <T1>, <T2>, nor <T3> may be
	i)	a <letter>
	ii)	a <digit>
	iii)	a space
	iv)	a comma
	v)	any non-printable character (including tab and newline).
c)	<T2> followed by a symbol name or macro parameter number causes the value of the symbol to 
be substituted at that point.
d)	<T1> may not be used in the text for any other purpose,
	<T2> may if not immediately followed by a letter of digit or any other special character.
Note: Rule (d) above does not, in fact, place too great a restriction on the text to be processed, since the 
trip characters may be redefined at any time during the processing of the text by using the TRIPCS 
command.

B.3	COMMAND SYNTAX
The following definitions are used in describing the syntax of the processor commands:
<layout>::= space|tab|comma|<NL> (<layout>)
<name>::= <letter> (nextchar)
<nextchar>::=<letter>|<digit> (nextchar)
<number>::=<digit> (<number>)
<letterr>::=A|B|C|....|X|Y|Z|a|b|...|y|z
<digit>::=0|1|...|8|9
<comend>::= (<layout><comment>) <T3)
<comment>::=non-<T3> character (comment)
where | separates alternative values and ( ) enclose optional items.
B.4	COMMANDS
B.4.1	Trip Characters Commands
These commands are used to manipulate the trip characters recognised by the processor. The 
commands are:
<T1> SAVECS <layout>
<T1> RESETCS <layout>
<T1> TRIPCS <layout><NT1><NT2><NT3><comment><NL>
where
<NT1>::= new command trip, i.e., new <T1>
<NT2>::= new <T2>
<NT3>::= new <T3>
The SAVECS and RESETCS commands save and restore a set of trip character values, and pairs of 
these commands may be nested up to 20 deep. The TRIPCS command overwrites the current trip 
character values with the new values specified, the SAVECS overwrites them with their default values.
The default trip character values are:
	<T1>::= .
	<T2>::= *
	<T3>::= ;

Example
	.TRIPCS &@;
	after which <T1> is &, <T2> is @, <T3> is;
	&SAVECS
	after which <T1> is ., <T2> is *, <T3> is;
	.TRIPCS :|!
	after which <T1> is :, <T2> is |, <T3> is !
	RESETCS
	after which <T1> is &, <T2> is @, <T3> is ;
Notes:
1.	Trip characters are defined until one of the above commands redefines them; or the source text 
is completely processed.
Thus, at the beginning of each processor run the trip characters will be defined as the default values 
given above.
2.	All macro-processor input files should reset the trip characters to their values on entry prior to the 
end of processing. If a micro-processor input file uses its own trip characters then it should use SAVECS 
before a TRIPCS command and RESETCS at the end.
B.4.2	Symbol Commands
To define a macro time symbol either the SET or SYMBOL command is used. The command definitions 
are:
	<T1> SET <layout><name><layout><expression><comend>
	<T1> SYMBOL <layout><name><comend>
where
<expression>::= <string expression>|<numeric expression>
<string expression>::= <T1><string exprsn><T1>
<string exprsn>::= <string subs>|<char other than T1, T2> (string exprsn)
<string subs>::= <T2><symbol name>
<numeric expression>::= <signed number>|<numeric subs>
				(<numeric exprsn>)
<numeric exprsn>::= <operator><number>|<numeric subs>
				(numeric exprsn)
<numeric subs>::= <T2><numeric symbol name>
<signed number>::= (+|-) <number>
<operator>::= +|-|*|/

Each macro time symbol has associated with it a value and a type. the SYMBOL command defines a 
Boolean type symbol with the value zero. The SET command defines a numeric or string type symbol 
whose value is given by a numeric or string expression - the type of the expression determines the type 
of the symbol. In general, symbols of differing types may not be combined or compared - the main 
exception being that Boolean symbols may be treated as numeric symbols of value zero.
Examples
Assuming the default trip characters then the following are valid symbol definitions
	.SET NUM 5+4 (NUM=9);
	.SET STR .a string. (STR= a string);
	.SET NUM *NUM+*NUM-1 (NUM=17);
	.SET STR .this is *STR. (STR= this is a string);
	.SYMBOL FRED;
Notes
1)	A symbol can always be substituted by the value of that symbol by a command of the form <sym-
value>::= <T2><name><layout>
2)	Both the value of a symbol and its type (i.e., numeric, string or Boolean)  can be changed by 
successive commands.
The following commands can also be used to manipulate symbols.
	<T1> INCR <layout><name><comend>
	<T1> DECR <layout><name><comend>
	<T1> VAL <layout><name>|<T2><nameref> <layout
where
<nameref> ::= <name>|<number>
The first two of these commands increment and decrement the value of a numeric symbol respectively, 
the third command substitutes the value of the symbol. Note that the last command also accepts a 
substitution expression, in which case a double substitution is performed.

Examples	.SET NAME .NUM.;
		.SET NUM 3;
		.INCR NUM (NUM=4);
		.DECR NUM (NUM=3);
		.VAL NAME
		outputs NUM
		.VAL *NAME
		outputs 3
B.4.3	Macro Commands
A macro definition is delineated by the following
	<T1> MACRO <layout><name><comend>
	<T1> ENDM <comend>
	<T1> EXITM <comend>
Between the first two commands is the <macrobody>, which is the sequence of characters which 
replaces <name> when the macro is called. The <macrobody> may contain any processor commands, 
(including nested MACRO/ENDM command pairs), which will be obeyed when the macro is called and 
not while it is being defined. A variation of the ENDM command - EXITM - indicates that processing of the 
macro should stop if the command is encountered while the macro is being expanded as the result of 
being called.
Example
.MACRO JOE;
.MACRO FRED;
		THIS IS MACRO FRED
.ENDM;
THIS IS JOE
.EXITM;
NEVER REACHED
.ENDM;
When the macro JOE is called, it will define the macro FRED and the processor will output
	THIS IS JOE
Once a macro has been defined, it may be called as follows
	<T1> CALL <layout><name> (<layout><paramlist>) (<layout>) <T3>
where
	<paramlist>::= <expression>(<separator><parmlist>)
	<separator>::=(<layout>)<comma>(<layout>)

Example
A valid macro call might look like
	.CALL MAC F12,,*2,. YZ, P.;
This is a call on macro MAC with 4 parameters which are:
	1)	F12
	2)	a null parameter
	3)	a parameter reference *2
	4)	a string enclosed in a pair of <T1> characters - the string enclosed is the actual 
parameter
Macros may freely be CALLed from within other macros.
The values of any parameters given can be substituted within the <macrobody> during its expansion by a 
command of the form
	<T2><number>
where the parameters in <paramlist> are numbered left to right from 1.
Example
.MACRO ADD This is a Macro which will reference two parameters;
X:= *1+ *2;
.ENDM;
Note:	If a particular parameter has not been given a value in a CALL, nothing is substituted.
There are two special cases of parameter value substitution:
	<T2>0
	<T2>$
The first (parameter number zero) substitutes the name of the macro currently being expanded, while the 
second substitutes a two-character string giving the current depth of nested macro expansions.

Example
	.MACRO HARRY;
	This is *0
	LABEL*S:
	.ENDM;
When called, this macro gives
	This is HARRY
	LABEL01:
B.4.4	Repeat Block Commands
A block of the source text can be repeated a given number of times by enclosing it with the following 
commands
	<T1> REPEAT <layout><numeric expression> <comend>
	<T1> ENDR <comend>
The text between these commands may contain any processor commands, including nested 
REPEAT/ENDR pairs. The numeric expression must evaluate to a non-negative number.
Note that, unlike macros, repeat blocks are expanded the required number of times at the point at which 
they are defined.
Example
	,REPEAT 2;
		A line of text
	.ENDR;
		gives
		
		A line of text
		A line of text
A repeat block within a macro inherits all of the parameter values for that macro, except for the special 
parameter zero which is set to the number of iterations of the repeat block expression that remain.

Example
.MACRO REP;
.REPEAT *1
*0, *1, *2
.ENDR;
.ENDM;
.CALL REP 2, Text;
will give
2, 2, Text
1, 2, Text
B.4.5	Conditional Commands
Portions of the source text may be included or excluded at will by using the IF block, which is delineated 
by
	<T1> IF <layout> <condition> <comend>
	<T1> ENDC <comend>
where
<condition>::= <param test>|<symbol test>|<comparison>|<logical>
<param test>::= PDF|NPDF <layout> (<T2>) <numeric>
<symbol test>::= <defined test>|<zero test>
<defined test>::= DF|NDF <layout> <name>|<paramref>
<zero test>::= ZERO|NZERO <layout> <operand>
<comparison>::= EQ|NE|GE|GT|LE|LT <layout> <operand>
			<separator> <operand>
<logical>::= ALLOF|ONEOF <layout> <operand> (<operand-list>)
<operand-list>::= <separator> <operand> (<operand list>)
<operand>::= <symbol name>|<paramref>
<paramref>::=<T2><number>
When an IF block is encountered, the processor evaluates the <condition>, which can be either true or 
false. If the <condition> is true, the body of the IF block will be processed; otherwise it will be ignored.
Further control over the processing within the block body is provided by the subconditional commands
	<T1> IFT|IFF|IFTF|ELSE (<any chars but <NL>, <T3>>) <NL>|<T3>

These subconditional commands work as follows:
IFT (IFF):	If the <condition> was true (false), then the text which follows, up to the next 
subconditional command or the ENDC of the current IF block, will be processed; otherwise 
it is ignored.
IFTF:	The following text, up to the next subconditional command or ENDC of the current IF, will 
be processed regardless of the value of <condition>.
ELSE:	If text is currently being processed then this causes what follows (up to the next 
subconditional command or ENDC) to be ignored, and vice versa.
The <condition> operators act as follows:
DF	If the name which follows has been defined using a SYMBOL or SET command, then the 
condition will be true; otherwise false.
NDF	Converse of DF.
ZERO	If the name which follows has been defined as a numeric symbol, and if its associated 
value is zero, then the condition will be true; otherwise false.
NZERO	Converse of ZERO.
PDF	If the macro parameter being referenced is NULL, then the condition will be false; 
otherwise true.
NPDF	Converse of PDF.
ALLOF	If each of the names that follow refers to a symbol that has been defined then the condition 
will be true; otherwise false.
ONEOF	If any one of the names that follow refers to a symbol that has been defined then the 
condition will be true; otherwise false.
EQ	If the two names refer to symbols of the same type, and the first symbol is equal to the 
second, then the condition will be true; otherwise false.
GE	As for EQ, but first symbol greater than or equal to the second.
GT	As for EQ, but first symbol greater than the second.
LE	As for EQ, but first symbol less than or equal to the second.
LT	As for EQ, but first symbol less than the second.
NE	As for EQ, but first symbol not equal to the second.

B.4.6	Include file command
Part or all of one text file may be included from within another by the command
	<T1> INCLUDE <layout><filename> (<lines>) <comend><NL>
where
	filename::= <string expression>
	lines::= <numeric expression> (<separator> <numeric expression>)
This command causes the processor to switch input from the current text file to the file given as 
<filename> - which it then processes from its start to its end, or between the line numbers specified, or 
until it reads a command of the form
	<T1> ENDI <comend>
When the processor finishes with the included file it returns to the line in the original file following the 
Include command. Note that included files may themselves contain Include commands.
Example
.TRIPCS &*;				As file name contains trip1
&INCLUDE &file.inc& 10,20;
will process the contents of the file "file.inc" from line 10 through to line 20 (or until an ENDT command is 
encountered).
B.4.7	Miscellaneous Commands
A symbol or macro definition may be deleted by the command
	<T1> FORGET <layout><name><comend>
B.5	RESTRICTIONS AND GENERAL NOTES
The following limits are imposed for the PDP/RSX version of the macro processor:
Maximum depth of macro expansion nesting 	= 40
Maximum depth of include file nesting 		= 10
Maximum depth of tri-character nesting		= 20
Maximum length of a symbol or macro name	= 80
Maximum number of parameters for a macro	= 40
Total number of characters in symbols and expressions	= 10000
Total number of characters in macro bodies and parameters = 10000
Total number of symbol and macros names = 2048
(Note that Repeat blocks count as macros above, where appropriate).
Symbol names may be re-used freely, although the processor gives a warning message if a macro name 
is re-used to help detect any inadvertent use of this feature.
Lines included from other files are indicated in the listing file by being prefixed with the letter 'I', instead of 
a line number.
Error recovery always involves discarding the rest of the input line containing the error. The offending line 
is output to the listing file followed by the error message, even when the error is found during the 
expansion of a macro. All error messages are self-explanatory.

B.6	GENERAL OBSERVATIONS
As most texts on the subject note, macroprocessing is both a powerful and a dangerous facility. It can 
afford the wise user the means to insulate himself, to some extent, from changes to the operational 
environment of his software which are beyond his authority or comprehension. It can also, to some 
extent, allow him to generate shorthand notation to suit his own current working environment. It can be 
dangerous in the hands of the unwise user, helping him only to expend computer time and manpower in 
diagnosing problems induced by obscure macro programming operations.
In an RTL/2 environment (i.e., one which is particularly clean and elegant), macros look ugly. Their use 
should be avoided wherever possible; in particular, they should not be used where a LET definition would 
be sufficient. Macros are, however, useful for generating repetitive data structures and, if your philosophy 
permits, for disguising code inserts. Conditional processing is useful for producing "versioned" software 
which can be pre-processed to configure modules to a particular target environment: for instance, writing 
operating systems which may be run on a number of different hardware configurations.
As a final point, there is usually little need to nest conditionals and macros to more than two levels, since 
beyond this depth macro programming rapidly becomes obscure.

C.	DEMONSTRATION PROGRAMS
C.1	INTRODUCTION
This appendix describes the standard demonstration programs distributed with the RSX-11M package. 
For each program a brief description is accompanied by the necessary administration details: file names, 
facilities used, instructions to build program, etc.
An MCR indirect command file is supplied with each individual program to compile, assemble, task build 
and run the demonstration. Certain of the command sequences include privileged commands and, 
therefore, should only be run from a privileged terminal. Files generated by intermediate steps in the build 
sequence are not deleted; users may wish to examine them (particularly compiler output).
The command files assume that the following standard tasks are already installed:
	RTL/2 Macro Processor		(...RMP)
	RTL/2 Linkage Verifier		(...RLV)
	RTL/2 Compiler			(...RTL)
	Assembler			(...MAC)
	Task Builder			(...TKB)
	PIP				(...PIP)
(The user may wish to adapt DEMETC.CMD for use with his own programs; it contains a list of the 
standard run time support modules required to build an RTL/2 task).
C.2	"LEARN" - LEARNING PROGRAM
Description
LEARN is a very simple example of using the Stream I/O Support Package. It has one input and one 
output stream, both of which use the user's terminal (i.e., TI:).
The program 'learns' from asking the user questions until it can find the answer. Type control-Z to learn 
LEARN and return to MCR.

Files supplied
The files supplied are as follows:
.	LEARN.RTL	-	source program
.	LEARN.CMD	-	MCR commands to compile, assemble and task 	build
.	LENTK.CMD	-	task builder commands
.	DEMETC.CMD	-	general files for task build
Files generated
.	LEARN.MAC	-	assembler source
.	LEARN.SRC	-	compiler report listing
.	LEARN.OBJ	-	object
.	LEARN.LST	-	assembler listing
.	LEARN.TSK	-	task image
.	LEARN.MAP	-	task build map
EXAMPLE OUTPUT (user input underlined)
RUN LEARN
THINK OF AN OBJECT
WHAT IS IT ?
SUET PUDDING
THANKS
THINK OF AN OBJECT
SUET PUDDING? NO
GIVE A PROPERTY TO DISTINGUISH FROM A SUET PUDDING
NON-FATTENING
WHAT IS IT?
RTL/2 MODULE
THANKS
THINK OF AN OBJECT
NON-FATTENING? YES
RTL/2 MODULE? NO
GIVE A PROPERTY TO DISTINGUISH FROM AN RTL/2 MODULE
PART OF AN RTL/2 MODULE
WHAT IS IT?
EXT SPECIFICATION
THANKS
THINK OF AN OBJECT
NON-FATTENING? Y
EXT SPECIFICATION?N
GIVE A PROPERTY TO DISTINGUISH FROM AN EXT SPECIFICATION
TYPE OF BRICK

WHAT IS IT?
DATA BRICK
THANKS
THINK OF AN OBJECT
NON-FATTENING? Y
PART OF AN RTL/2 MODULE? Y
TYPE OF BRICK? Y
DATA BRICK? N
GIVE A PROPERTY TO DISTINGUISH FROM A DATA BRICK
CONTAINS EXECUTABLE STATEMENTS
WHAT IS IT?
PROC BRICK
THANKS
THINK OF AN OBJECT
NON-FATTENING? Y
PART OF AN RTL/2 MODULE? Y
TYPE OF BRICK? Y
CONTAINS EXECUTABLE STATEMENTS? Y
PROC BRICK? Y
*** CLEVER ME
THINK OF AN OBJECT
NON-FATTENING? ^Z
I QUIT
C.3	"DEMCOM" - COMMERCIAL EXAMPLE
Description
DEMCOM uses stream I/O support and illustrates how the standard formatting procedures can be used 
for data conversion in-core as well as to and from peripherals.
The program takes input records of personnel no., name, address, payment factor, hours worked.
A calculation is performed of the payment due (= hours * factor).
The program outputs a data file containing records of personnel no., payment due, address and name, 
and a report containing the same information (except address) in a form suitable for printing.
See the comments in the program text for precise data formats. Note the use of the RTl/2 Linkage 
Verifier with this example.

Files supplied
Files supplied are as follows:-
(1)	DEMCOM.RTL	-	source program
(2)        DEMCOM.CMD -	MCR commands to compile, linkage verify, assemble, task build and run 
DEMCOM
(3)	DCOMLV.CMD	-	linkage verification commands
(4)	DCOMTK.CMD	-	task builder commands
(5)	RTLXRF.XRF	-	standard linkage verifier input
(6)	DEMCOM.INP	-	data input file
(7)	DEMETC.CMD	-	general files for task build
Files generated
(1)	DEMCOM.MAC	-	assembler source
(2)	DEMCOM.XRF	-	cross reference information
(3)	DEMCOM.OBJ	-	object program
(4)	DEMCOM.SRC	-	compilation listing
(5)	DEMCOM.LST	-	assembler listing
(6)	DEMCOM.MAP	-	task build map
(7)	DEMCOM.LKL	-	linkage verifier report
(8)	DEMCOM.TSK	-	task image
(9)	DEMCOM.OUT	-	output data file
(10)	DEMCOM.REP	-	output report file
Control Routines
REAL arithmetic and conversions are used by DEMCOM. An appropriate version of the control routines 
must be available when task building DEMCOM.
C.4	"DEMCAL" - DESK CALCULATOR
Description
DEMCAL is a simple desk calculator program. It is chiefly aimed at illustrating use of the RTL/2 Macro 
Processor to generate an RTL/2 program. The macro processor is used:-
(1)	To allow a choice of REAL or INT arithmetic.
(2)	To allow for variations in operating environment - e.g., RSX-11M or -11D.
(3)	To generate an arbitrary number of pseudo-registers with variable names in
	the calculator.

Files Supplied
(1)	DCALM.CND	-	Macro and symbol definitions source
(2)	DCALP.CND	-	Body of program source
(3)	DEMCAL.CMD	-	MCR commands to macro process, compile, assemble, task build and 
run DEMCAL
(4)	DEMETC.CMD	-	General files for task build
Files Generated
(1)	DEMCAL.RTL	-	RTL/2 source (output of macro processor)
(2)	DEMCAL.SCL	-	macro processor listing
(3)	DEMCAL.MAC	-	assembler source
(4)	DEMCAL.SRC	-	compiler listing
(5)	DEMCAL.OBJ	-	object program
(6)	DEMCAL.LST	-	assembler listing
(7)	DEMCAL.TSK	-	task image
(8)	DEMCAL.MAP	-	task build map
Control Routines
If DCALP.CND is revised for REAL arithmetic then a suitable version of the control routines must be 
configured before task building DEMCAL.
C.5	"DEMCLK" - SPEAKING CLOCK
Description
This demonstration is an extremely simple illustration of using the RSX-11M interface library to achieve 
real-time functions.
There are two tasks. The main one when activated obtains the system time and then prints it out in a 
formatted message, rounding the value to the nearest ten second.
The other task is a start-up task which schedules the main task to run every ten seconds, so that after 
running the start-up task, the time will be printed every ten seconds on CO: (beware of messages on the 
system console).

Files Supplied
Start-Up Task
(1)	DEMCL1.RTL	-	source program
(2)	DCL1TK.CMD	-	task build commands
Main Task
(1)	DEMCL2.RTL	-	source program
(2)	DCL2TK.CMD	-	task build commands
MCR Commands
(1)	DEMCLK.CMD	-	compile, assemble and task build both tasks
(2)	DEMETC.CMD	-	general files for building of both tasks
Files Generated
Start-Up Task
(1)	DEMCL1.MAC	-	assembler source
(2)	DEMCL1.OBJ	-	object program
(3)	DEMCL1.TSK	-	task file
(4)	DEMCL1.SRC	-	compilation listing
(5)	DEMCL1.LST	-	assembly listing
(6)	DEMCL1.MAP 	-	task build map
Main Task
(1)	DEMCL2.MAC	-	assembler source
(2)	DEMCL2.OBJ	-	object program
(3)	DEMCL2.TSK	-	task file
(4)	DEMCL2.SRC	-	compilation listing
(5)	DEMCL2.LST	-	assembly listing
(6)	DEMCL2.MAP	-	task build map
Task Names
The Start-Up Task is named
		DEMCLK
at task build time. This name may be changed at task build time.

The Main Task	is named
	SPKCLK
at task build time. This name may not be changed since it is used within the first task (refer to DEMCL1).
Initiating the Speaking Clock
The MCR command file does not initiate the program in this case.
To run the speaking clock use the command:-
	RUN DEMCLK
To terminate the speaking clock a "cancel scheduled requests" command is used:-
	CAN SPKCLK
Note that DEMCLK uses the RUN request to schedule SPKCLK. RSX-11M always sets the TI: device for 
the requested task to CO:, hence the output from SPKCLK will be directed to CO:.
C.6	"RMSTST" - RMS INTERFACE EXAMPLE PROGRAM
Use
To start the program you type:
	RUN RMSTST
The program responds with the request
	PLEASE TYPE A FOUR DIGIT KEY
You should type in an integer of the form 0045 which must not be greater than 1000. If a record already 
exists in the file the program will find and display it. The program then asks
	DO YOU WANT TO UPDATE THIS RECORD?
If you do want to update the record you must answer yes to this question - any other response will not 
enable you to update the record.
If the record did not exist or you wanted to update it the next question will be:
	PLEASE TYPE THE NEXT RECORD - WITHOUT ITS KEY
Here you may type anything up to a maximum of 80 characters. If you type any more than 80 characters 
the program will fail.
Typing CNTL-Z when asked for a new key will halt the program and close the file.
How it works
The macro calls to set up the necessary descriptor blocks are coded in a dummy procedure brick. This 
calls the routines which set up pool-space and initialise the FABs and RABs. In the main procedure 
RRJOB the terminal (TI:) is opened both for reading and writing. An attempt is made to open the data file 
(RMSTST.DAT) - if this fails then the file is created.

The main loop consists of three steps:
	1.	Get a key from the terminal;
	2.	Find the record;
	3.	Update the record.
In the first stage the pointer to the message requesting a new key is STOREd in the RBF field of 
REQRAB (the file open for writing) and a binary key is computed from the input. The message is then 
PUT to the terminal. The key is obtained by issuing a GET to UPDRAB. A CNTL-Z here signifies end-of-
file and is used as a method of informing the program that this session has terminated.
The second stage consists of doing a GET using the key to try to find a record. If this record has already 
been put into the file it is displayed by loading the RBF field of REQRAB with the address of the record 
obtained and PUTting this record to the terminal. A message asking whether the user wants to modify 
this record is output in a similar manner to other messages to the terminal.
If an update is required or the record did not already exist the user is asked to input the next record. The 
RSZ field of MSTRAB is set to 80 (it is overwritten by a get operation) and the KBF field is also reset. 
The record is then PUT to the file and the process is restarted from step 1.
At the end of the session all files are disconnected from their streams and closed.
An error at any time is shown by a call to the RTL/2 error procedure RRGEL with 999 as the parameter.

D.	ERROR MESSAGES
D.1	INTRODUCTION
This appendix is provided as a quick reference to aid users in locating details concerning error number 
descriptions.
There are two categories of errors:
	-	those reported as RTL/2 Errors by calling RRGEL
	-	those reported as some other mechanism specific to the program involved
For the second category this section lists those errors reported by the three RTL/2 utilities: the compiler, 
linkage verifier and macro processor.
RRGEL reported errors correspond to the standard methods for error recover in RTL/2 as described in 
the "RTL/2 System Standards" manual (RTL/2 Ref 4). The ranges of error numbers for the different types 
of runtime errors, detected by the RTL/2 support and environment system, are reserved as follows:
0-99		Unrecoverable errors reported by the system
100-4999	Recoverable errors reported by the system
5000-9999	Errors (recoverable and unrecoverable) reported by a user program
10000-onwards	Machine oriented errors detected by hardware.

D.2	RRGEL REPORTED ERRORS
D.2.1	Unrecoverable Errors
										
Error No
  Meaning			
 Detected by	
 Applicability	

				
		
		
1
 Stack overflow on procedure entry
 Control	 Routines
All RTL/2 programs
2
Label in GOTO statement out of scope
 

3
Inaccessible Error Label - ERL out of 
scope on exit from RRGEL
 Base Program
 
4
Array bound violation - array subscript 
out of range	
Control Routines
Unless compiled with 
no checks








97
End of file on output
Base Program
All RTL/2 programs
98
IN procedure not established

that use
99
OUT procedure not established

SVC DATA RRSIO
D.2.2	Recoverable Errors:
The following ranges are allocated:
100-199	Streamed input
200-299	Streamed output
300-300	Mathematical functions
400-400	Other standard facilities
500-4999	General packages
Recoverable errors are reported via ERP which points to RRGEL, by default.	

										
Error No
 Meaning
 Detected by
 Applicability  




100
 Illegal format in FREAD
 Standard
RTL/2 programs
101
 Illegal format in IREAD
 Stream
that use the
102
 Illegal format in RREAD
 Formatting
 formatted I/O
103
 Illegal format in TREAD
 Procedures
support library



 
110
 Bad open stream LUN

RTL/2 programs
111
 Bad filename
 RSXOPI
that use the
112
 Bad filename
 RSXOPO
RSX stream I/O
113
 Cannot open input file
 RSXOBI
support library
114
 Cannot open output file
 RSXOBO

115
 Bad close stream LUN
 RSXCL, RSXDEL

116
 Cannot close file
 RSXSP

117
 Bad new input stream LUN
 RSXSWI

118
 Bad new output stream LUN
 RSXSWO

119
Cannot read from file
 RSXIN

120
 Cannot write to file
 RSXOUT

121
 Cannot spool file
 RSXSP

122
 Cannot delete file
 RSXDLT

123
 Current stream LUN not set up
 RSXIN, RSXOUT









300
 Invalid argument to RSQRT, FSQRT
Mathematical
 RTL/2 programs
301
 Invalid argument to RLOGE
Routines
that use the
302
 Invalid argument to RSIN, RCOS

 Maths
303
 Invalid argument to REXP

 package




A further set of recoverable error numbers in the range 9950-9997 (and 9999) have been allocated to the 
errors detected by the environment for the RTL/2 utilities. For convenience sake, these have been 
included with the list of utility reported errors in Section D.3, although strictly speaking, since they are 
reported via RRGEL, they should be presented here.
A further error detected by the RTL/2 runtime environment is:
									
Error No
 Meaning
 Detected by
Applicability  




9998
Illegal control routine call  (when entered via a TRAP 
where the operand is out of range or implies a routine 
excluded by conditional assembly)
Control 
Routines
All RTL/2 
programs





D.2.3	Hardware detected errors
									
Error No
 Meaning
 Detected by
 Applicability  




10001
Memory addressing error
Base Program
System Traps
10002
Memory protect violation


10003
IOT instruction


10004
Reserved instruction


10005
Emulator trap






10007
Division by zero	

FPP unit Exceptions
10009
Floating-to-integer conversion error

 
10011
 Floating-point overflow


10015
 Undefined variable



Errors 10007, 10009, 10011 and 10015 only occur when the base programs have been configured for 
use with the floating-point processor.

D.3	UTILITY REPORTED ERRORS
D.3.1	Environmental Errors
In addition to outputting diagnostics relating to the input being processed the RTL/2 utilities' operating 
system interface may generate error messages concerning the environment. All such errors are treated 
as fatal, causing the run of the utility to be abandoned.
The format of the error message is as follows:
	RTL./2 Compiler		...RTL-	<error number> L
	RTL/2 Linkage Verifier		...RLV-	<error number> L
	RTL/2 Macro Processor		...RMP- <error number> L
A complete list of such error numbers is given below:
										
Error No		Meaning						
9950		Input (source) file, open failure; may be no such file
9951		Input (source) file, error when reading; may be caused by record	longer than 132 bytes
9955		Command line too long
9960		Output file, open failure; may be caused by protection settings
9961		Output or listing file, error when writing; may be caused by device full
9968		Syntax error in indirect command
9970		Command I/O error
9971		Command (indirect) file, open failure
9972		Syntax error in indirect command specification
9973		Indirect file depth exceeded (limit is 3 deep)
9980		Work file, open failure
9981		Available workfile space exceeded
9982		Unable to allocate enough workfile space
9983		Workfile, read error
9984		Workfile, write error
9990-9997	Program faults
										
Apart from the general errors listed above, certain environmental errors are particular to the RTL/2 
compiler:
										
Error No	Meaning							
9974		Required switch invalid or missing
9981		Workfile page number unavailable
9985		Fortran Middle End not supported
9999		/RE:N specified without a /CS:name
										

D.3.2	Compiler Error Messages
Compiler error diagnostics and warning messages detected by the front-end and back-end are in the 
format:
F
	<error number> LINE <line number>
B
where F or B is printed to indicate whether the compiler front or back end found the error. The |line 
number^ refers to the line number in the source program.
Three categories of diagnostics are distinguished by the compiler:
1)	Catastrophic Errors
These are caused by a size limit violation or an internal compiler fault, and terminate the compilation.
2)	Program Errors
These are the most common. The compiler attempts to recover from the error and continue error 
checking. Output of the assembler file is inhibited except in the case of the small class of 'back-end' 
errors where the assembler file output should be deleted.
3)	Warnings
These draw the attention of the user to RTL/2 statements which may have unintended effects. 
Compilation is not inhibited by this class of diagnostics.
If an error is detected, the compiler may skip to the next recognisable text, and may assume the 
presence of missing keywords. This can lead to side-effect errors.
Note that errors in LET definitions may cause side-effect errors because occurrences of the name may 
be replaced by null or erroneous sequences.
The following pages list front-end, middle-end and back-end error messages separately.

CATASTROPHIC ERRORS
No.
Message
Extra Information 
1
Program too long

2
Blocks nested too deep

3
Too many blocks

4
Statement structure nested too deep

5
Compiler error - please report

6
Mode too complex

7
Compiler error - please report

8
Compiler error - please report

10
Compiler error - please report

11
Expression nested too deep

12
Compiler error - please report

20
Too many name characters

21
Too many names

22
Too many identifiers

23
Mode information overflow

24
Array pool overflow

25
Table space exceeded

26
Invalid table switch
Probably colon missing in table switch string
27
D specified greater than 1

28
Too many generated labels


PROGRAM ERRORS
No.
Message
Extra Information 
101
Non-RTL character
Treated as layout and hence may terminate item
102
Illegal stringchar
Can give later length mismatches
103
Newline/tab in string or " missing 
Concatenation still attempted with adjacent strings
104
Illegal symbol in inner sequence /# missing
i. Not a byte constant or repetition factor
ii. If fails on " then # missing probably and concatenation attempted.
105
Mismatched # symbol in string
Source representations differ
106
String pool overflow - null string inserted

107
Terminator in item
Module reading terminated, any subsequent text not processed.
108
Newline in comment/ % missing

109
Non stringchar / " missing
Byte constant inserted; newline and terminator treated as such
110
:# illegal
: # : assumed which may give side errors
111
Illegal macro-item
Keyword is ignored
112
Compile-time option error
Subsequent option ignored
113
Option syntax error
Refers to option in text; subsequent option ignored
114
Code in applications
Treat as if systems module to give maximum error information
115
Digit missing

116
Constant too long
Remaining digits skipped: may cause later mode errors
117
Illegal exponent

118
Exponent/binary scale out of range

No.
Message
Extra Information 
119
Illegal binary scale

120
Illegal repetition factor
i. Inner string sequence ignored: could cause length errors
ii. Array initialisation
121
) missing
Various - can lead to length, mode and parameter errors
122
Name too long
Subsequent alpha-numerics ignored
123
Constant pool overflow-zero
Zero is of same mode so later mismatches inserted
124
Identifier missing
Various - whenever a name is expected; can cause side errors
125
Identifier is keyword
i. RTL encountered outside code item; removed
ii. Attempting to define LET
iii Reserved word CODE, LET OPTION or TITLE used as for loop 
control variable
126
= missing
After LET identifier
127
Identifier already declared
Various - subsequent identifiers in a list will not be declared. This 
message also used in mismatch situations for redundant EXT/ENT
128
Code section error
i. Parameter syntax error;
ii. Layout following trip character;
iii. No name after second trip;
iv. No identifier preceding brick name
129
Illegal item in data brick
Only occurs on recovery from failure
130
Illegal item(s) at brick level
Only one such message of a group of items are misinterpreted
131
; missing
Syntactic semi-colons assumed
132
EXT/ENT descriptions mismatch 
i. Data brick case: more than one message is likely
ii. ENT procedure specification
133
Stack length missing/not integer 

134
( missing
i. After MODE name: component names not declared
ii. Literal procedure becomes PROC( )
iii. various Syntactic omission can lead to mode mismatches
135
Illegal result mode
Recovery depends on situation
136
Illegal mode specification
May be mode missing or use of REF REF; leads to non declared 
names
137
Array/record declaration illegal

138
Bound illegal/too big
Can cause length mismatch
139
Too many bounds

140
: = missing
Only possible after FOR-loop control variable
141
DO missing/illegality in loop heading

142
Empty mode
Mode name is declared
143
Illegal initialisation
i. Within MODE definition) attempting to initialise label
ii. Within PROC parameters) variables in DATA not failed here
144
Illegal item in declaration
Various - A semi-colon may be inserted which may cause side-errors
145
Misplaced ENDPROC
Two messages if ENDPROC caused original error (in data)
146
Illegal item at statement level

147
REP missing (matching TO)
The appropriate keyword is inserted: this may be in the wrong place 
and cause later errors. Can also be side-effect errors caused by 
misplaced keyword.
148
REP missing (matching FOR)

149
ENDBLOCK missing

150
REP missing (matching WHILE)

No.
Message
Extra Information 
151
END missing

152
ENDPROC missing

153
ENDDATA missing

154
Illegal use of :
No label identifier: meant for ; or compound item ?
155
Misplaced REP
Item removed: this can give use to or be caused by "XXX
156
Misplaced END
missing" messages or other errors particularly in case of END and 
expressions/
157
Misplaced ENDBLOCK
statement ambiguity
158
Variable not initialised
Declaration is still successful
159
Identifier not declared/out of scope
i. in code sequence
ii. Use of variable in dynamic initialisation before its declaration
iii. General access of variable name
160
Too many modes in specification Unlikely; 
too many MODE example in external 
specification

161
Expression of wrong mode
LHS in multiple assignments or RHS expression or initialisation. 
Can be a side-error. It is common and includes wrong mode terms 
supplied to operators and passing SVC name to variable
162
Illegal byte constant
+ or - sign supplied
163
Array length mismatch
Can be side error in initialisation
164
Illegal item in initialisation

165
External references list full
Too many external bricks referenced by local brick
166
Identifier not in module
Reference to variable in SVC data brick in data initialisation
167
Identifier of wrong mode
Attempting to access brick or component in expression
168
Invalid selector for record

169
Non integer subscript
Must be constant in data
170
Array bound violation
Constant subscript case only
171
Dereferencing in data

172
FOR control variable read only
Includes passing to reference
173
Too many subscripts/ ) missing
Always fails on comma
174
Not a procedure
Operator omitted before (?
175
Parameter mismatch
Should not occur and may indicate compiler fault
176
Too few parameters/ , missing

177
ELSE missing/expression ends incorrectly

178
END missing/expression ends incorrectly

179
Illegal item in expression

180
Illegal use of VAL
Includes cases where dereferencing is automatic
181
: = missing/destination invalid

182
Host brick error
i. brick name absent or unnecessary for brick
ii. variable does not belong
183
; missing/statement ends incorrectly
Can cause side-errors on recovery
184
Illegal use of ELSEIF
May be logically impossible (already had an ELSE part)
185
DO missing/condition ends incorrectly

186
THEN missing/condition ends incorrectly

187
RESULT not returned
ENDPROC reached without result' can occur as side effect of 
inserted keywords; also if each branch of an IF statement contains a 
RETURN statement - compiler not clever enough!
188
OF missing/illegal item in switch

189
Illegal label in switch
Labels must be literals
190
TO missing/illegality in loop heading

191
Illegal use of ELSE
May be logically impossible (already had an ELSE part)
192
Bracketed comparison
Syntactic error: may also have ") missing "= logical error
193
Taking out of scope
In applications mode, the address of a logical variable has been 
assigned to a data brick reference or returned as a proc result
194
Used Mode hidden
A variable has been declared with the same name as a record used 
in this block. Detected at end of the block

WARNING MESSAGES
No.
Message
Extra Information 
202
Floating constant at run-time
Run time float inefficient; ensure that if this constant is supplied via 
a LET definition, all uses are the same mode
204
Silly TO loop
Limit is 0; executed zero times via run-time check
205
String concatenation
Replace by enclosing the newline in a # sequence
206
Non-standard use of end-of-module 
character
Uparrow no longer signifies EOM and should be removed
						

Middle-End Failure Messages (FORTRAN Interface)
Error messages are of the form:
FORTRAN NAME "XXXXXX" ERROR nnn
where nnn is as defined below. Note that no particular recovery action is visible to the user on the 
detection of program errors; the compiler back-end will not run after an error (other than a warning) is 
detected by the middle-end.
					
PROGRAM ERRORS
101	FORTRAN name longer than six characters
102	Name in FORTRAN names list is not an EXT PROC
103	Too many FORTRAN names (Maximum = 256)
104	FORTRAN procedure with unsupported parameter or result type
105	Compiler tables cannot accommodate additional names for interface procedures
106	Compiler tables cannot accommodate additional name characters for interface procedures
108	Supposedly FORTRAN brick present in RTL/2 module
					
WARNING MESSAGES
201	Name specified in FORTRAN names list does not appear in RTL/2 module
					

						
CATASTROPHIC ERRORS
No.
Message
Extra Information 
1
Program too long

2
Too many generated labels

3
Too many strings

4
Compiler error

5
Array of too many dimensions

6
Compiler error

7
Compiler error

8
Too many levels
Blocks nested too deeply
9
Compiler error

10
Compiler error

11
Not used

12
Compiler error

13
Compiler error

14
Compiler error

15
Compiler error

16
Procedure calls nested too deeply

17
Compiler error

18
Compiler error

19
Compiler error

20
Compiler error


PROGRAM ERRORS
No.
Message
Extra Information 
101
Integer constant overflow

102
Fraction constant overflow

103
Real constant overflow

104
Compiler error

106
: missing after &ENT
In CODE sequence
107
Array exceeds 32767 bytes

108
Real constant in code

109
Databrick exceeds 32768 bytes


WARNING MESSAGES
No.
Message
201
Unknown option
202
Real constant underflow
203
Integer too big
204
Incompatible psect switches specified
205
Slow code option and /DS:*D switch used together - this combination is not supported
						

Note that no particular recovery action is visible to the user in the case of program errors. The assembler 
module produced by the compiler will be of no value after an error (other than a warning) has been 
detected by the back-end.
D.3.3	Linkage Verifier Error and Warning Messages
Inconsistencies detected by the Linkage Verifier in the cross-reference information are classed as either 
errors or warnings. This distinction makes it easier to run the verifier on an incomplete system as all 
"missing definitions" are classed as warnings.
The possible messages and their cause are given below.
No.		Significance		
1	An illegal item has been found while reading the module named.
2	The list used within the Verifier to hold 'ENT' brick information has overflowed.
3	The list used within the verifier to hold 'EXT' brick information has overflowed. Note that this error 
is less likely to happen if the order of input of the cross-reference files is such that 'ENT' definitions 
precede their 'EXT' references.
4	Two 'ENT' bricks have been declared with the same name. The brick name is printed, together with 
that of the module containing the duplicate definition.
5	The specification of an 'EXT' brick does not conform to the 'ENT' definition of the brick. The names 
of the brick and the module are printed.
6	An 'EXT' brick has been defined for which no corresponding 'ENT' exists. The names of the brick 
and the module containing the 'EXT' are printed.
7	An 'R' number reference has been found that is not of the form R digit digit. The two characters 
following the 'R' have been treated as digits and the value resulting from this treatment is printed, 
together with the name of the module.
8	An attempt has been made to define an 'R' number twice. The number concerned is printed, 
together with the name of the module containing the duplicate definition.
9	An 'R' number definition has been found which depends on another 'R' number which has not 
previously been defined in the cross-reference input. The number and module name are printed. 
10	An external reference has been made to an 'R' number that is not defined. The number concerned 
is printed, together with the name of the module containing the external reference.
Notes:
1.	Messages 6 and 10 are only output during verification after all the cross-reference files have been 
input. Messages 1-4 and 7-9 are only output as the cross-reference information is read. Message 5 
may appear at either time.
2.	The limits for errors 2 and 3 are set when the Verifier is built (see the Installation Instructions).
3	Messages 6 and 10 are classed as warnings, the rest are errors.

E	CODE INSERTS
The syntax follows the overall standard as described in the RTL/2 Specification Manual thus:
	codeseq::= codeheading codeitem...
	codeheading::= CODE digitlist, digitlist;
	codeitem::= ISO7-character-other-than-*-or/*macroitem/name
Thus, in this implementation, the characters 'trip-1' and 'trip-2' of the specification manual are '*' and '/' 
respectively.
The two values denoted by "digitlist" in the heading denote, in bytes, the core space required by the code 
itself and additional stack workspace required at run time.
The forms *macroitem and *macroitem/name are transformed by the compiler as follows:
					
RTL
Corresponding Assembler
*integer
literal value of integer in octal
*fraction
literal value of fraction in octal
*string
address of conceptual zeroth element of string


**,*/
*, / respectively


*modename
length of mode in bytes
*brickname
address of start of brick
*literallabelname
address of label
*localname
displacement of variable from current link-cell (i.e., from contents of R5)
*component/mode
displacement of component from start of record
*variable/databrick
address of variable within brick
*variable/SVC databrick
displacement of variable from start of SVC data area (i.e., from R0)
*name*
declares RTL/2 literal label at this point in the code section
*%...%
comment
					

The remainder of the sequence is written in normal PDP-11 assembler with the following additions:
&CR All characters after &CR on a line are converted to cross-reference information.
&ENT All characters between &ENT and a colon on a line are taken as an assembler name and the start 
of a CODE insert will be defined as an entry point with that name.
To compile a module containing a code insert, use the /CN switch, (as described in Section 2.3).
For further information on code statements and the run time representation of RTL/2 programs on the 
PDP-11, see "The RTL/2 Run Time Environment on the PDP-11" (Ref. RTL39).

F.	THE FORTRAN INTERFACE
F.1	INTRODUCTION
The Fortran interface is an extra feature included in the RTL/2 compiler in order to support the use of 
existing Fortran subprograms with RTL/2 programs. The interface generates extra code to "envelop" calls 
to external procedures that are flagged as being written in Fortran, so the user does not need to write 
sets of assembler routines to convert between the differing conventions of the two languages.
Note that the interface supports the calling of Fortran from RTL/.2 but not vice versa.
F.2	USING THE FORTRAN INTERFACE
F.2.1	Compiler Command Line
The Fortran interface is activated by a compiler command string switch, "FO:Y".
On recognition of this switch, the compiler solicits an additional command string, which contains one or 
more input datasets which contain the names of Fortran subprograms. The dataset name(s) must follow 
an '=' sign.
As a consequence of this behaviour, it is not possible to invoke the computer and specify the Fortran 
interface on the same command line. This means that the multiple command line mode must be used. 
For example, to compile FCALLS.RTL into FCALLS.MAC with a listing to FCALLS.SRC and the Fortran 
names to be read from FNAMES.DAT.
> RTL
RTL2> FCALLS,FCALLS=FCALLS/TI:F1/FO:Y
FORTRAN NAMES FROM
RTL2> =fnames.dat
RTL2> ^Z
The underlining indicates prompts produced by the system or the compiler.
Alternatively, a command file could be used
> RTL
RTL2> @COMPF
RTL2> ^Z
where COMPF.CMD contains
FCALLS,FCALLS:=FCALLS/TI:F1/FO:Y
=FNAMES.DAT
F.2.2	Specifying Fortran procedures
Procedures which are Fortran subroutines or functions are specified in the RTL/2 source text simply as 
RTL/2 EXT PROCs.
When the /FO switch is specified, the compiler solicits an additional input dataset specification. The data 
set contains the list of EXT PROC names (and no information other than the names) which are in fact 
written in Fortran. One or more names may appear on each line; one or more spaces should be used to 
separate names within a line.

F.2.3	Making use of Fortran procedures
The RTL/2 text can make normal RTL/2 use of Fortran procedures. an RTL/2 procedure variable may be 
set to point to a Fortran procedure and the correct interfacing code will be executed when the procedure 
variable is called.
As usual a procedure defined as returning a result can be used for side-effects only, the result being 
ignored.
F.2.4	Call-by-reference and call-by-value
RTL/2 offers only call-by-value. A call-by-reference effect is obtained by call-by-value with REF 
parameters. This is true also of Fortran calls from RTL/2.
For example, if a particular Fortran subroutine, FSUBA, takes a single integer parameter then the RTL/2 
user of it may define either:-
%1% EXT PROC (INT) FSUBA;
in which case a copy of the INTeger parameter is made for FSUBA and the call's data is immune from 
FSUBA actions, or
%2% EXT PROC (REF INT) FSUBA;
in which case FSUBA is using a pointer to some RTL/2 variable to which it can therefore assign some 
value.
F.2.5	Valid Parameter Types
The following RTL/2 parameter types are supported by the interface:
	INT, REAL, REF INT, REF REAL
	REF ARRAY INT (Single dimension only)
	REF ARRAY REAL (Single dimension only)
F.3	IMPLEMENTATION DETAILS
F.3.1	Main Incompatibilities between RTL/2 and Fortran
	Procedure calls:
Fortran uses JSR PC,...
whereas RTL/2 uses JSR R1,...
Register usage:
Fortran routines may corrupt any registers (except SP), but RTL/2 expects R5 and R0 to be saved across 
procedure calls.
F.3.2	Interface Code Generated
F.3.2.1	Calls on Fortran procedures
The interface changes references to EXT PROCs which have been specified as Fortran to be references 
to local procedures. These references include the static and dynamic setting of procedure variables as 
well as literal procedure calls.

F.3.2.2	Local Interface Procedures
The local procedures are interface procedures; one interface procedure is generated for each Fortran 
procedure name which is not only quoted in the Fortran names list (and specified in the RTL/2 module as 
an EXT PROC) but also is referenced within the RTL/2 module.
The name of an interface procedure is the corresponding Fortran name with a '#' character prefixed.
F.3.2.3	Interface Details
Each interface procedure consists of procedure entry and exit control routine calls, between which are 
instructions to:-
1)	Assign stack space for the result, if any
2)	Save registers R0 and R5
3)	Reformat the parameters into a Fortran argument list
4)	Call Fortran routine
5)	Move the result, if any, to the stack
6)	Restore registers R0 and R5.
F.3.3	Using Fortran procedures in CODE statements
The normal philosophy of CODE statements applies, i.e., it is the user's responsibility to use Fortran 
names correctly where they appear in CODE statements. Bending of the reference takes place if the 
name follows a trip-1 character. This if RSINE were a Fortran procedure a CODE statement may contain
(a) *RSINE
in which case it is translated to be a reference to the generated interface procedure brick, #RSINE,
or
(b) RSINE
in which case a direct reference to the actual Fortran routine is made, unbeknown to the RTL/2 compiler.
F.3.4	I/O Interaction
Care must be taken when mixing Fortran I/O with Stream I/O and QIOs.
Lack of a Fortran main program causes a severe Fortran I/O package failure due to lack of initialisation. It 
is recommended that hybrid programs use stream I/O or block I./O in RTL/2 defined buffers.
Assembler level I/O should be done through the RTL/2 buffers taking care to protect the RTL/2 
environment.

Chapter  1   Introduction

Chapter  1   Introduction

RTL/2 User Manual for PDP-11/RSX-11		Page  26

RTL/2 User Manual for PDP-11/RSX-11		Page  27

Chapter  2   The RTL/2 Compiler

Chapter  2   The RTL/2 Compiler

Chapter  3   User Task Generation

Chapter  3   User Task Generation

Chapter  4   The Linkage Verifier

Chapter  4   The Linkage Verifier

Chapter  5   The Macro Processor

Chapter  5   The Macro Processor

Chapter  6   Run-Time Support

Chapter  6   Run-time Support

Chapter  7   Stream I/O

Chapter  7   Stream I/O

Chapter  8   The RSX-11M Executive Interface

Chapter  8   The RSX-11M Executive Interface

Chapter  9   The RSX-11M I/O Interface

Chapter  9   The RSX-11M I/O Interface

Chapter 10   Mathematical Routines

Chapter 10   Mathematical Routines

Chapter 11   Record Management Services

Chapter 11   Record Management Services

Appendix A   Cross-Reference Information

Appendix A   Cross-Reference Information

Appendix B   Macro Processor Language

Appendix B   Macro Processor Language

Appendix C   Demonstration Programs

Appendix C   Demonstration Programs

Appendix D   Error Messages

Appendix D   Error Messages

Appendix E   Code Inserts

Appendix E   Code Inserts

Appendix F   The Fortran Interface

Appendix F   The Fortran Interface


