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.