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; 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: ; 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 , and 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, , which defines an EXT PROC brick XS, , which defines an EXT STACK brick XU, , which defines an SVC DATA brick XV, , which defines an SVC PROC XY, , 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, , for an ENT PROC brick NS, , for an ENT STACK brick NU, = , for an SVC DATA brick NV, = , for an SVC PROC NY, , 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 = 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 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 = 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: this indicates an integer in Macro-11 format, i.e., the default radix is octal. 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. 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 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 ::= command trip ::= substitution trip ::= terminator trip These trip characters must obey the following rules: a) , , must be mutually distinct. b) Neither , , nor may be i) a ii) a iii) a space iv) a comma v) any non-printable character (including tab and newline). c) followed by a symbol name or macro parameter number causes the value of the symbol to be substituted at that point. d) may not be used in the text for any other purpose, 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: ::= space|tab|comma| () ::= (nextchar) ::=| (nextchar) ::= () ::=A|B|C|....|X|Y|Z|a|b|...|y|z ::=0|1|...|8|9 ::= () ::=non- 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: SAVECS RESETCS TRIPCS where ::= new command trip, i.e., new ::= new ::= new 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: ::= . ::= * ::= ; Example .TRIPCS &@; after which is &, is @, is; &SAVECS after which is ., is *, is; .TRIPCS :|! after which is :, is |, is ! RESETCS after which is &, is @, 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: SET SYMBOL where ::= | ::= ::= | (string exprsn) ::= ::= | () ::= | (numeric exprsn) ::= ::= (+|-) ::= +|-|*|/ 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 ::= 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. INCR DECR VAL | ::= | 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 MACRO ENDM EXITM Between the first two commands is the , which is the sequence of characters which replaces when the macro is called. The 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 CALL () () where ::= () ::=()() 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 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 during its expansion by a command of the form where the parameters in 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: 0 $ 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 REPEAT ENDR 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 IF ENDC where ::= ||| ::= PDF|NPDF () ::= | ::= DF|NDF | ::= ZERO|NZERO ::= EQ|NE|GE|GT|LE|LT ::= ALLOF|ONEOF () ::= () ::= | ::= When an IF block is encountered, the processor evaluates the , which can be either true or false. If the 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 IFT|IFF|IFTF|ELSE (, >) | These subconditional commands work as follows: IFT (IFF): If the 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 . 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 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 INCLUDE () where filename::= lines::= ( ) This command causes the processor to switch input from the current text file to the file given as - 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 ENDI 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 FORGET 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- L RTL/2 Linkage Verifier ...RLV- L RTL/2 Macro Processor ...RMP- 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 LINE B where F or B is printed to indicate whether the compiler front or back end found the error. The |line number^ refers to the line number in the source program. Three categories of diagnostics are distinguished by the compiler: 1) Catastrophic Errors These are caused by a size limit violation or an internal compiler fault, and terminate the compilation. 2) Program Errors These are the most common. The compiler attempts to recover from the error and continue error checking. Output of the assembler file is inhibited except in the case of the small class of 'back-end' errors where the assembler file output should be deleted. 3) Warnings These draw the attention of the user to RTL/2 statements which may have unintended effects. Compilation is not inhibited by this class of diagnostics. If an error is detected, the compiler may skip to the next recognisable text, and may assume the presence of missing keywords. This can lead to side-effect errors. Note that errors in LET definitions may cause side-effect errors because occurrences of the name may be replaced by null or erroneous sequences. The following pages list front-end, middle-end and back-end error messages separately. CATASTROPHIC ERRORS No. Message Extra Information 1 Program too long 2 Blocks nested too deep 3 Too many blocks 4 Statement structure nested too deep 5 Compiler error - please report 6 Mode too complex 7 Compiler error - please report 8 Compiler error - please report 10 Compiler error - please report 11 Expression nested too deep 12 Compiler error - please report 20 Too many name characters 21 Too many names 22 Too many identifiers 23 Mode information overflow 24 Array pool overflow 25 Table space exceeded 26 Invalid table switch Probably colon missing in table switch string 27 D specified greater than 1 28 Too many generated labels PROGRAM ERRORS No. Message Extra Information 101 Non-RTL character Treated as layout and hence may terminate item 102 Illegal stringchar Can give later length mismatches 103 Newline/tab in string or " missing Concatenation still attempted with adjacent strings 104 Illegal symbol in inner sequence /# missing i. Not a byte constant or repetition factor ii. If fails on " then # missing probably and concatenation attempted. 105 Mismatched # symbol in string Source representations differ 106 String pool overflow - null string inserted 107 Terminator in item Module reading terminated, any subsequent text not processed. 108 Newline in comment/ % missing 109 Non stringchar / " missing Byte constant inserted; newline and terminator treated as such 110 :# illegal : # : assumed which may give side errors 111 Illegal macro-item Keyword is ignored 112 Compile-time option error Subsequent option ignored 113 Option syntax error Refers to option in text; subsequent option ignored 114 Code in applications Treat as if systems module to give maximum error information 115 Digit missing 116 Constant too long Remaining digits skipped: may cause later mode errors 117 Illegal exponent 118 Exponent/binary scale out of range No. Message Extra Information 119 Illegal binary scale 120 Illegal repetition factor i. Inner string sequence ignored: could cause length errors ii. Array initialisation 121 ) missing Various - can lead to length, mode and parameter errors 122 Name too long Subsequent alpha-numerics ignored 123 Constant pool overflow-zero Zero is of same mode so later mismatches inserted 124 Identifier missing Various - whenever a name is expected; can cause side errors 125 Identifier is keyword i. RTL encountered outside code item; removed ii. Attempting to define LET iii Reserved word CODE, LET OPTION or TITLE used as for loop control variable 126 = missing After LET identifier 127 Identifier already declared Various - subsequent identifiers in a list will not be declared. This message also used in mismatch situations for redundant EXT/ENT 128 Code section error i. Parameter syntax error; ii. Layout following trip character; iii. No name after second trip; iv. No identifier preceding brick name 129 Illegal item in data brick Only occurs on recovery from failure 130 Illegal item(s) at brick level Only one such message of a group of items are misinterpreted 131 ; missing Syntactic semi-colons assumed 132 EXT/ENT descriptions mismatch i. Data brick case: more than one message is likely ii. ENT procedure specification 133 Stack length missing/not integer 134 ( missing i. After MODE name: component names not declared ii. Literal procedure becomes PROC( ) iii. various Syntactic omission can lead to mode mismatches 135 Illegal result mode Recovery depends on situation 136 Illegal mode specification May be mode missing or use of REF REF; leads to non declared names 137 Array/record declaration illegal 138 Bound illegal/too big Can cause length mismatch 139 Too many bounds 140 : = missing Only possible after FOR-loop control variable 141 DO missing/illegality in loop heading 142 Empty mode Mode name is declared 143 Illegal initialisation i. Within MODE definition) attempting to initialise label ii. Within PROC parameters) variables in DATA not failed here 144 Illegal item in declaration Various - A semi-colon may be inserted which may cause side-errors 145 Misplaced ENDPROC Two messages if ENDPROC caused original error (in data) 146 Illegal item at statement level 147 REP missing (matching TO) The appropriate keyword is inserted: this may be in the wrong place and cause later errors. Can also be side-effect errors caused by misplaced keyword. 148 REP missing (matching FOR) “ 149 ENDBLOCK missing “ 150 REP missing (matching WHILE) “ No. Message Extra Information 151 END missing “ 152 ENDPROC missing “ 153 ENDDATA missing “ 154 Illegal use of : No label identifier: meant for ; or compound item ? 155 Misplaced REP Item removed: this can give use to or be caused by "XXX 156 Misplaced END missing" messages or other errors particularly in case of END and expressions/ 157 Misplaced ENDBLOCK statement ambiguity 158 Variable not initialised Declaration is still successful 159 Identifier not declared/out of scope i. in code sequence ii. Use of variable in dynamic initialisation before its declaration iii. General access of variable name 160 Too many modes in specification Unlikely; too many MODE example in external specification 161 Expression of wrong mode LHS in multiple assignments or RHS expression or initialisation. Can be a side-error. It is common and includes wrong mode terms supplied to operators and passing SVC name to variable 162 Illegal byte constant + or - sign supplied 163 Array length mismatch Can be side error in initialisation 164 Illegal item in initialisation 165 External references list full Too many external bricks referenced by local brick 166 Identifier not in module Reference to variable in SVC data brick in data initialisation 167 Identifier of wrong mode Attempting to access brick or component in expression 168 Invalid selector for record 169 Non integer subscript Must be constant in data 170 Array bound violation Constant subscript case only 171 Dereferencing in data 172 FOR control variable read only Includes passing to reference 173 Too many subscripts/ ) missing Always fails on comma 174 Not a procedure Operator omitted before (? 175 Parameter mismatch Should not occur and may indicate compiler fault 176 Too few parameters/ , missing 177 ELSE missing/expression ends incorrectly 178 END missing/expression ends incorrectly 179 Illegal item in expression 180 Illegal use of VAL Includes cases where dereferencing is automatic 181 : = missing/destination invalid 182 Host brick error i. brick name absent or unnecessary for brick ii. variable does not belong 183 ; missing/statement ends incorrectly Can cause side-errors on recovery 184 Illegal use of ELSEIF May be logically impossible (already had an ELSE part) 185 DO missing/condition ends incorrectly 186 THEN missing/condition ends incorrectly 187 RESULT not returned ENDPROC reached without result' can occur as side effect of inserted keywords; also if each branch of an IF statement contains a RETURN statement - compiler not clever enough! 188 OF missing/illegal item in switch 189 Illegal label in switch Labels must be literals 190 TO missing/illegality in loop heading 191 Illegal use of ELSE May be logically impossible (already had an ELSE part) 192 Bracketed comparison Syntactic error: may also have ") missing "= logical error 193 Taking out of scope In applications mode, the address of a logical variable has been assigned to a data brick reference or returned as a proc result 194 Used Mode hidden A variable has been declared with the same name as a record used in this block. Detected at end of the block WARNING MESSAGES No. Message Extra Information 202 Floating constant at run-time Run time float inefficient; ensure that if this constant is supplied via a LET definition, all uses are the same mode 204 Silly TO loop Limit is 0; executed zero times via run-time check 205 String concatenation Replace by enclosing the newline in a # sequence 206 Non-standard use of end-of-module character Uparrow no longer signifies EOM and should be removed Middle-End Failure Messages (FORTRAN Interface) Error messages are of the form: FORTRAN NAME "XXXXXX" ERROR nnn where nnn is as defined below. Note that no particular recovery action is visible to the user on the detection of program errors; the compiler back-end will not run after an error (other than a warning) is detected by the middle-end. PROGRAM ERRORS 101 FORTRAN name longer than six characters 102 Name in FORTRAN names list is not an EXT PROC 103 Too many FORTRAN names (Maximum = 256) 104 FORTRAN procedure with unsupported parameter or result type 105 Compiler tables cannot accommodate additional names for interface procedures 106 Compiler tables cannot accommodate additional name characters for interface procedures 108 Supposedly FORTRAN brick present in RTL/2 module WARNING MESSAGES 201 Name specified in FORTRAN names list does not appear in RTL/2 module CATASTROPHIC ERRORS No. Message Extra Information 1 Program too long 2 Too many generated labels 3 Too many strings 4 Compiler error 5 Array of too many dimensions 6 Compiler error 7 Compiler error 8 Too many levels Blocks nested too deeply 9 Compiler error 10 Compiler error 11 Not used 12 Compiler error 13 Compiler error 14 Compiler error 15 Compiler error 16 Procedure calls nested too deeply 17 Compiler error 18 Compiler error 19 Compiler error 20 Compiler error PROGRAM ERRORS No. Message Extra Information 101 Integer constant overflow 102 Fraction constant overflow 103 Real constant overflow 104 Compiler error 106 : missing after &ENT In CODE sequence 107 Array exceeds 32767 bytes 108 Real constant in code 109 Databrick exceeds 32768 bytes WARNING MESSAGES No. Message 201 Unknown option 202 Real constant underflow 203 Integer too big 204 Incompatible psect switches specified 205 Slow code option and /DS:*D switch used together - this combination is not supported Note that no particular recovery action is visible to the user in the case of program errors. The assembler module produced by the compiler will be of no value after an error (other than a warning) has been detected by the back-end. D.3.3 Linkage Verifier Error and Warning Messages Inconsistencies detected by the Linkage Verifier in the cross-reference information are classed as either errors or warnings. This distinction makes it easier to run the verifier on an incomplete system as all "missing definitions" are classed as warnings. The possible messages and their cause are given below. No. Significance 1 An illegal item has been found while reading the module named. 2 The list used within the Verifier to hold 'ENT' brick information has overflowed. 3 The list used within the verifier to hold 'EXT' brick information has overflowed. Note that this error is less likely to happen if the order of input of the cross-reference files is such that 'ENT' definitions precede their 'EXT' references. 4 Two 'ENT' bricks have been declared with the same name. The brick name is printed, together with that of the module containing the duplicate definition. 5 The specification of an 'EXT' brick does not conform to the 'ENT' definition of the brick. The names of the brick and the module are printed. 6 An 'EXT' brick has been defined for which no corresponding 'ENT' exists. The names of the brick and the module containing the 'EXT' are printed. 7 An 'R' number reference has been found that is not of the form R digit digit. The two characters following the 'R' have been treated as digits and the value resulting from this treatment is printed, together with the name of the module. 8 An attempt has been made to define an 'R' number twice. The number concerned is printed, together with the name of the module containing the duplicate definition. 9 An 'R' number definition has been found which depends on another 'R' number which has not previously been defined in the cross-reference input. The number and module name are printed. 10 An external reference has been made to an 'R' number that is not defined. The number concerned is printed, together with the name of the module containing the external reference. Notes: 1. Messages 6 and 10 are only output during verification after all the cross-reference files have been input. Messages 1-4 and 7-9 are only output as the cross-reference information is read. Message 5 may appear at either time. 2. The limits for errors 2 and 3 are set when the Verifier is built (see the Installation Instructions). 3 Messages 6 and 10 are classed as warnings, the rest are errors. E CODE INSERTS The syntax follows the overall standard as described in the RTL/2 Specification Manual thus: codeseq::= codeheading codeitem... codeheading::= CODE digitlist, digitlist; codeitem::= ISO7-character-other-than-*-or/*macroitem/name Thus, in this implementation, the characters 'trip-1' and 'trip-2' of the specification manual are '*' and '/' respectively. The two values denoted by "digitlist" in the heading denote, in bytes, the core space required by the code itself and additional stack workspace required at run time. The forms *macroitem and *macroitem/name are transformed by the compiler as follows: RTL Corresponding Assembler *integer literal value of integer in octal *fraction literal value of fraction in octal *string address of conceptual zeroth element of string **,*/ *, / respectively *modename length of mode in bytes *brickname address of start of brick *literallabelname address of label *localname displacement of variable from current link-cell (i.e., from contents of R5) *component/mode displacement of component from start of record *variable/databrick address of variable within brick *variable/SVC databrick displacement of variable from start of SVC data area (i.e., from R0) *name* declares RTL/2 literal label at this point in the code section *%...% comment The remainder of the sequence is written in normal PDP-11 assembler with the following additions: &CR All characters after &CR on a line are converted to cross-reference information. &ENT All characters between &ENT and a colon on a line are taken as an assembler name and the start of a CODE insert will be defined as an entry point with that name. To compile a module containing a code insert, use the /CN switch, (as described in Section 2.3). For further information on code statements and the run time representation of RTL/2 programs on the PDP-11, see "The RTL/2 Run Time Environment on the PDP-11" (Ref. RTL39). F. THE FORTRAN INTERFACE F.1 INTRODUCTION The Fortran interface is an extra feature included in the RTL/2 compiler in order to support the use of existing Fortran subprograms with RTL/2 programs. The interface generates extra code to "envelop" calls to external procedures that are flagged as being written in Fortran, so the user does not need to write sets of assembler routines to convert between the differing conventions of the two languages. Note that the interface supports the calling of Fortran from RTL/.2 but not vice versa. F.2 USING THE FORTRAN INTERFACE F.2.1 Compiler Command Line The Fortran interface is activated by a compiler command string switch, "FO:Y". On recognition of this switch, the compiler solicits an additional command string, which contains one or more input datasets which contain the names of Fortran subprograms. The dataset name(s) must follow an '=' sign. As a consequence of this behaviour, it is not possible to invoke the computer and specify the Fortran interface on the same command line. This means that the multiple command line mode must be used. For example, to compile FCALLS.RTL into FCALLS.MAC with a listing to FCALLS.SRC and the Fortran names to be read from FNAMES.DAT. > RTL RTL2> FCALLS,FCALLS=FCALLS/TI:F1/FO:Y FORTRAN NAMES FROM RTL2> =fnames.dat RTL2> ^Z The underlining indicates prompts produced by the system or the compiler. Alternatively, a command file could be used > RTL RTL2> @COMPF RTL2> ^Z where COMPF.CMD contains FCALLS,FCALLS:=FCALLS/TI:F1/FO:Y =FNAMES.DAT F.2.2 Specifying Fortran procedures Procedures which are Fortran subroutines or functions are specified in the RTL/2 source text simply as RTL/2 EXT PROCs. When the /FO switch is specified, the compiler solicits an additional input dataset specification. The data set contains the list of EXT PROC names (and no information other than the names) which are in fact written in Fortran. One or more names may appear on each line; one or more spaces should be used to separate names within a line. F.2.3 Making use of Fortran procedures The RTL/2 text can make normal RTL/2 use of Fortran procedures. an RTL/2 procedure variable may be set to point to a Fortran procedure and the correct interfacing code will be executed when the procedure variable is called. As usual a procedure defined as returning a result can be used for side-effects only, the result being ignored. F.2.4 Call-by-reference and call-by-value RTL/2 offers only call-by-value. A call-by-reference effect is obtained by call-by-value with REF parameters. This is true also of Fortran calls from RTL/2. For example, if a particular Fortran subroutine, FSUBA, takes a single integer parameter then the RTL/2 user of it may define either:- %1% EXT PROC (INT) FSUBA; in which case a copy of the INTeger parameter is made for FSUBA and the call's data is immune from FSUBA actions, or %2% EXT PROC (REF INT) FSUBA; in which case FSUBA is using a pointer to some RTL/2 variable to which it can therefore assign some value. F.2.5 Valid Parameter Types The following RTL/2 parameter types are supported by the interface: INT, REAL, REF INT, REF REAL REF ARRAY INT (Single dimension only) REF ARRAY REAL (Single dimension only) F.3 IMPLEMENTATION DETAILS F.3.1 Main Incompatibilities between RTL/2 and Fortran Procedure calls: Fortran uses JSR PC,... whereas RTL/2 uses JSR R1,... Register usage: Fortran routines may corrupt any registers (except SP), but RTL/2 expects R5 and R0 to be saved across procedure calls. F.3.2 Interface Code Generated F.3.2.1 Calls on Fortran procedures The interface changes references to EXT PROCs which have been specified as Fortran to be references to local procedures. These references include the static and dynamic setting of procedure variables as well as literal procedure calls. F.3.2.2 Local Interface Procedures The local procedures are interface procedures; one interface procedure is generated for each Fortran procedure name which is not only quoted in the Fortran names list (and specified in the RTL/2 module as an EXT PROC) but also is referenced within the RTL/2 module. The name of an interface procedure is the corresponding Fortran name with a '#' character prefixed. F.3.2.3 Interface Details Each interface procedure consists of procedure entry and exit control routine calls, between which are instructions to:- 1) Assign stack space for the result, if any 2) Save registers R0 and R5 3) Reformat the parameters into a Fortran argument list 4) Call Fortran routine 5) Move the result, if any, to the stack 6) Restore registers R0 and R5. F.3.3 Using Fortran procedures in CODE statements The normal philosophy of CODE statements applies, i.e., it is the user's responsibility to use Fortran names correctly where they appear in CODE statements. Bending of the reference takes place if the name follows a trip-1 character. This if RSINE were a Fortran procedure a CODE statement may contain (a) *RSINE in which case it is translated to be a reference to the generated interface procedure brick, #RSINE, or (b) RSINE in which case a direct reference to the actual Fortran routine is made, unbeknown to the RTL/2 compiler. F.3.4 I/O Interaction Care must be taken when mixing Fortran I/O with Stream I/O and QIOs. Lack of a Fortran main program causes a severe Fortran I/O package failure due to lack of initialisation. It is recommended that hybrid programs use stream I/O or block I./O in RTL/2 defined buffers. Assembler level I/O should be done through the RTL/2 buffers taking care to protect the RTL/2 environment. Chapter 1 Introduction Chapter 1 Introduction RTL/2 User Manual for PDP-11/RSX-11 Page 26 RTL/2 User Manual for PDP-11/RSX-11 Page 27 Chapter 2 The RTL/2 Compiler Chapter 2 The RTL/2 Compiler Chapter 3 User Task Generation Chapter 3 User Task Generation Chapter 4 The Linkage Verifier Chapter 4 The Linkage Verifier Chapter 5 The Macro Processor Chapter 5 The Macro Processor Chapter 6 Run-Time Support Chapter 6 Run-time Support Chapter 7 Stream I/O Chapter 7 Stream I/O Chapter 8 The RSX-11M Executive Interface Chapter 8 The RSX-11M Executive Interface Chapter 9 The RSX-11M I/O Interface Chapter 9 The RSX-11M I/O Interface Chapter 10 Mathematical Routines Chapter 10 Mathematical Routines Chapter 11 Record Management Services Chapter 11 Record Management Services Appendix A Cross-Reference Information Appendix A Cross-Reference Information Appendix B Macro Processor Language Appendix B Macro Processor Language Appendix C Demonstration Programs Appendix C Demonstration Programs Appendix D Error Messages Appendix D Error Messages Appendix E Code Inserts Appendix E Code Inserts Appendix F The Fortran Interface Appendix F The Fortran Interface