Release Notice Package Name: PDP/RSX RTL/2 Compiler Package Number: 1 Package Version: 10.0 (H) Hobbyist Special Licence Issue Date: November 1992 / June 1997 Associated Software: RSX-11 family of operating systems (including Micro/RSX) Any problems encountered with this release should be emailed or faxed to the following address: Natron Software Maintenance Ltd 2 The Garlands Clifton York N. Yorkshire YO3 6NZ England Email: rtl2@natron.demon.co.uk Tel: +44 (0)1904 631450 Fax: +44 (0)1926 883370 This manual is Copyright 1992 & 1997, Natron Software Maintenance Ltd. The RTL/2 software included with this distribution is Copyright 1974, 1980, 1990 Imperial Chemical Industries Ltd Copyright 1990, 1992, 1997 Natron Software Maintenance Ltd All Rights Reserved. CONTENTS 1 INTRODUCTION .............................................. 1 2 PRODUCT DELIVERY PROCEDURE ................................. 1 2.1 Product Contents ................................... 1 2.2 Associated Documentation ........................... 2 2.3 Building The Product .................................3 2.4 Running The RTL/2 Utilities ........................ 5 2.5 Checking The Installation .......................... 6 3 CHANGES IN THIS RELEASE .................................... 7 3.1 New Features ....................................... 7 3.2 Fault Corrections .................................. 11 3.3 Outstanding Problems ............................... 13 3.4 Compatibility ...................................... 15 4 USING THE NEW RELEASE ...................................... 16 5 LEGAL DISCLAIMER ........................................... 17 PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 1 1 INTRODUCTION This document provides details of this special hobbyist Release of the PDP/RSX RTL/2 compiler product. Note that use of this product is restricted, as described in the separate HLICENCE.TXT file. 2 PRODUCT DELIVERY PROCEDURE The user should check that there is sufficient disc space available - i.e. up to 6500 blocks while the product is being built, of which up to 2500 blocks will be needed thereafter. It is assumed that the user will save or delete, as required, any old versions of files or executable images before commencing this installation. 2.1 Product Contents The Zip file HPDPRTL2.ZIP contains the following files: o Object libraries used to (re-)build the RTL/2 utilities - CIPLIBRSX.OLB ; common - CMPRSX.OLB ; compiler - CMPRSXRSX.OLB ; compiler - RLVLIBRSX.OLB ; linkage verifier - RMPLIBRSX.OLB ; macro processor - RMPCIPLIB.OLB ; macro processor - DBGLIBRSX.OLB ; Debug o Object libraries containing RTL/2 runtime support routines - MTHLIBRSX.OLB ; maths - MTHLIBRSX.NLB ; maths (compiled for FPP systems) - RSXIO.OLB ; stream i/o - RTLEXC.OLB ; executive interface - RTLRTSRSX.OLB ; base program, formatted i/o o Text libraries containing the source files for all of the RTL/2 runtime support routines, and for the Debug support routines - SOURCERSX.ULB ; runtime support - DBGRSXSRC.ULB ; Debug support o Text library containing the symbol table definition modules for some of the RTL/2 utilities, allowing the overall size of these tables to be changed before rebuilding the utilities - UTILTBLS.ULB PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 2 o Command and overlay descriptor files used to build the various RTL/2 utilities - RTLBLD.CMD ; compiler - RTL2.ODL ; compiler - RLVBLD.CMD ; linkage verifier (no .ODL file) - RMPBLD.CMD ; macro processor - RMP.ODL ; macro processor - HSTBLD.CMD ; Debug - HOST.ODL ; Debug o Command files to re-generate the RTL/2 runtime support object libraries from the source files contained in SOURCERSX.ULB - RTLCTL.CMD ; regenerate control routines - BUILDRTS.CMD ; regenerate all runtime support o Source libraries, command files, and a data file, used to build and run the demonstration programs - DEMLIBSRC.ULB ; demo source files - DEMLIBCMD.ULB ; demo command files - DEMUNPACK.CMD ; unpack the above libraries - DEMCOM.INP ; data file for the DEMCOM demo o Command files to unload and install this RTL/2 package - DLV1.CMD ; install ("deliver") package - UPD1.CMD ; apply any updates to package 2.2 Associated Documentation There is a paper set of manuals for this product which comprise: o User Manual for the PDP/RSX RTL/2 Compiler (RTL63); o Runtime Environment for the PDP/RSX RTL/2 Compiler (RTL39). New users may also need: o RTL/2 Language Specification (RTL1); o RTL/2 Training Manual (RTL3); o RTL/2 System Standards (RTL4); o RTL/2 Standard Stream I/O (RTL5); o RTL/2 Language Reference Card (RTL25). These manuals are not included with this hobbyist distribution - a set can be ordered separately, please contact Natron for details. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 3 2.3 Building the Product Once the Zip file has been unzipped into a directory on the user's system, the RTL/2 compiler and other utilities are built by running the command file DLV1 from within this "unzip" directory: > Set Default [unload_directory] ; (if not already set) > @Dlv1 The DLV1 command file poses two sets of questions to the user; the first set apply to the package utilities about to be built: o Deliver Symbolic Debug - if you do not intend to use this utility then you can save time and disc space by answering NO here. o Library directory - at the end of the installation, the task images and object libraries for the runtime support routines will be copied into this directory; the user should have write-access to this directory during the installation, but thereafter its contents should be read/execute-only for general use. o Run in I- & D- space - if you will be running the package utilities on an RSX-11M+ or Micro/RSX system then you should answer YES here. o Partition name - the memory partition in which all of the utilities will be run (defaults to GEN). o Memory resident workfile - the compiler and macro processor use a temporary work file that can be held on disc or in memory - if your system has sufficient RAM then answering YES here will produce faster versions of these utilities (each work file is 16K words). o Memory resident FCS - answering YES allows the utilities to be built with larger symbol tables since only 4K words of the image is occupied by the FCS routines; if you do reply YES then you will be asked to whether to use the FCSRES or the FCSFSL library - if you are not sure then use FCSRES. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 4 The second set of questions apply to user tasks that will be built using the product utilities (since these tasks may be run on other PDP systems with fewer features than the development one): o Run in I- & D- space - if the user tasks will be run under RSX-11M+ or Micro/RSX then you should answer YES here. o Use Trap handler - if RTL/2 modules will be compiled with the SL option (for smaller but slower code) then answer YES here. o Use REAL variables - if no RTL/2 modules will ever use REALs then answering NO here will reduce the overall size of tasks by omitting the floating point control routines. o FPP present - if the user tasks will always be run on PDPs with the FPP co-processor then answer YES here; you will then be asked whether the "old" FPP control routines should be included, to which you should reply YES unless all the RTL/2 modules will be re-compiled with the new /FP:Y switch. o FIS present - if the user tasks will always be run on PDPs with the FIS hardware option, and if all RTL/2 modules will be compiled with the FP compiler option, then answer YES here. o EIS present - if the user tasks will always be run on PDPs with the EIS hardware option then answer YES; you will then be asked if all RTL/2 modules will be compiled with the /EI:Y compiler switch (NB: all modern PDPs have EIS as standard, and its presence is implied if you answer YES to either of the I/D space or the FPP questions above). Finally, a summary of your answers is displayed and you are asked to confirm that all of the information is correct. Replying NO at this point allows you to re-start the question session, otherwise the command file proceeds with the installation. Note that a log of the installation process is set up in the file P1LOG.DAT in the first unload directory. The overall installation process takes between 10 and 20 minutes. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 5 2.4 Running The RTL/2 Utilities At the end of the installation, the library directory named should contain the task images of the utilities, the five runtime support object libraries, and (if selected) the Debug support modules. Note that only the contents of this library directory are required for the normal use of this product, although you may wish to also retain the source and build files for the runtime support library if you are not short of disc space. The task images of the package utilities can be installed thus: > Install [library_dir]RTL2 ; as task ...RTL > Install [library_dir]RTLV ; as task ...RLV > Install [library_dir]RMP ; as task ...RMP alternatively, they can be installed under other names, e.g: > Install [library_dir]RTL2/TASK=RTL2 ; as task RTL2 but note that the command files provided with this package assume the default task names. NB: the Debug task (HOST.TSK) should not be installed. IMPORTANT NOTE: The installation process assumes that the PDP-11 hardware on which you will be running these utilities supports EIS instructions. If this is not the case then please contact Natron for an alternative set of installation instructions. The affected PDP-11 models are: PDP-11/04, /05, /15, /20, and any based on the T-11 chip. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 6 2.5 Checking The Installation Several simple demonstration programs have been included with this package so that the user can verify that the RTL/2 utilities have been build correctly. Each demonstration can be compiled and built using the appropriate command file as follows: o DEMCAL - desk calculator example, showing use of RMP; o DEMCLK - timer example, showing use of executive interface; o DEMCOM - commercial example, showing use of formatted i/o for conversion between different number representations; o EXAMPL - example showing use of the Debug utility. o FPPDEMO - floating point example, shows the effect of the new inline FPP support (can only be run on FPP systems); o IDDEMO - example showing the use of separate I- and D-space (can only be run on RSX-11M+ or Micro/RSX systems); o LEARN - learning program example; o RMSTST - example showing use of the RMS-11 interface. After the installation process all of these files will be present in the delivery directory. You need to check that the new versions of the product utilities have been INSTALLed using their default task names before running any of these command files. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 7 3 CHANGES IN THIS RELEASE This section details all of the software changes that are included in this release. 3.1 New Features 3.1.1 Compiler The following command line switches have been added: /FP:Y - generate inline code to use the FPP co-processor for any floating point operations, using FPP register 0 to hold the return value for any procedures that have a floating point result; /FP:L - generate inline code to use the FPP co-processor for any floating point operations, but use the stack to hold the return value for procedures with a floating point result (hence retaining compatability with other RTL/2 modules that have not been compiled with this /FP switch); /UN:Y - append a list of all unreferenced identifiers to the end of the source listing (i.e. the .SRC) file; The cross-reference data output to the XRF file for any procedures that return a REAL result is changed if the /FP:Y switch is used. Floating point constants may be specified in RTL/2 Code statements if prefixed with the "trip 1" character (*) and the source file is compiled with the /FP switch (set to either :Y or :L). Any '_' characters in the names of global bricks, i.e. when using the XN option, are converted to '.' characters for the equivalent Macro-11 labels (this is only significant when the '_'s appear in the first six characters of the brick names). The maximum length of the compiler command line has been increased from 160 characters to 200. The maximum number of distinct strings in a single module has been increased from 250 to 280. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 8 3.1.2 Runtime support software The following control routines have been added to support the use of inline FPP code generation for procedure returning REAL value. R45 exit with result in FPP reg 0 (not I-/D-space tasks) R46 exit with result in FPP reg 0 (I-/D-space tasks) R47 exit with result on stack (not I-/D-space tasks) R48 exit with result on stack (I-/D-space tasks) The following control routines have new variants to be used with inline FPP code. R38 convert REAL to FRAC R39 convert REAL to INT No other control routines are required to support inline FPP code. The following executive interface routines have been added. RSXACN ACHN$ Assign Channel RSXCLN CLON$ Create Logical Name RSXDLN DLON$ Delete Logical Name RSXEMS EMST$ Emit Status RSXFEA FEAT$ test for specified system Feature RSXFSS FSS$ File Specification Scanner RSXGDR GDIR$ Get default Directory RSXGIN GIN$ General Information RSXPFC PFCS$ Parse FCS RSXPRM PRMS$ Parse RMS RSXRLN RLON$ Recursively translate Logical Name RSXRMF RMAF$ Remove Affinity (multi-cpu systems) RSXSCA SCAA$ Specify Command Arrival AST RSXSCL SCLI$ Set Command Line Interpreter RSXSDI SDIR$ Set default Directory RSXSMS SMSG$ Send Message RSXSRX SREX$ Specify Requested Exit AST RSXSTF STAF$ Set Affinity (multi-cpu systems) RSXSWS SWST$ Switch State RSXTFE TFEA$ test for specified Task Feature RSXTLN TLON$ Translate Logical Name A new command file, BUILDRTS, allows the user to regenerate all of the runtime support libraries from source in one session, in batch if supported by the PDP system being used. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 9 3.1.3 Linkage verifier The Linkage Verifier will report a type mismatch for any procedure that returns a REAL result if the source files that define and use that procedure are compiled with different settings of the new /FP compiler switch. The Linkage Verifier will now report any type mismatches that may occur in successive EXT declarations (instead of only checking the latest one against the corresponding ENT declaration). 3.1.4 Macro processor The following commands have been added: COMMENT any text ELSEIF condition PAGE any text (where , , and are the current Trip characters). The COMMENT and PAGE commands provide a simple way of commenting the RMP source file - none of the text before is sent to the output file, but does appear in the listing file (at the top of a new page for the PAGE command). The ELSEIF command provides an easier mechanism for a sequence of IF tests than separate ELSE and IF (and ENDC) commands. The sequence outputs a single character. The sequence outputs the value of the numeric expression. The conditional operators EQ, LE etc. now accept constant numeric expressions as well as ones involving RMP symbols. The '$' and '_' characters are now allowed in RMP names. Two new messages have been added: - a warning when the new trip characters specified using a TRIPCS command may occur in the RMP source file as normal text; - an error when a constant expression (i.e. one in which there are no RMP symbols) is present where not allowed. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 10 3.1.5 Demonstration programs A new example, FPPDEMO, has been added to illustrate the use of the compiler's new /FP switch on systems with the FPP co-processor. The DEMCAL example had to be modified due to a change in the macro processor (see section 3.4), and the opportunity was taken to do a general tidy up of its source code. The IDDEMO example has also been tidied up. The DEMMAS example, which involved accessing the processor handkeys, has been discarded. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 11 3.2 Fault Corrections 3.2.1 Compiler Invalid constant array subscripts larger than 255 are not reported by the compiler, but they are detected at runtime in the normal way (allowing for systems or applications mode and the settings of the BC and BS options) [SD 0602]. FOR loops with BY parts that cause an overflow of the loop counter will execute the correct number of times [SD 0615]. Duplicate lines no longer appear in the assembler text [SD 0628]. Assigning a local variable to a REF variable in a databrick is now flagged correctly as an error in all cases [SD 0744]. The line numbers given in listing files are no longer incorrect if the source file(s) processed contain Form-Feed characters [SD 0755]. The compiler outputs '.' characters to the assembler file where '_'s occur in the first six characters of global brick names [SD 0765]. All of the utilities in this package can be built with FCSFSL where this is available [SD 0774]. The compiler writes a unique module name to the .XRF file when the /RE:N switch is used for MTS applications [SD 0813]. The compiler does not generate .REPT/ENDR assembler directives when the /RE:N switch is used for MTS applications [SD 0814]. Large numbers of Real constants no longer lead to addressing errors when using the /FP switch [SD 0815]. 3.2.2 Runtime support software Either of the routines RASIN and RACOS may enter an infinite loop, each by calling the other which in turn calls the first, and so on until the stack is exhausted [SD 0793]. The demonstration program DEMMAS has been removed from the package [SD 0800]. The command files supplied with this package should run on systems with a user-defined CLI, provided that either DCL or MCR is also available [SD 0801]. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 12 3.2.3 Linkage verifier RTL/2 names output as part of error messages are now their correct length (previously always padded out to 32 characters). If a cross-reference module is generated without a module name (no parameter on the ";M" line), then the next one line of xref data is skipped - this may cause either an ENT definition or a mismatch to be ignored [SD 0792]. 3.2.4 Macro processor Nested REPEAT blocks are now processed correctly. The "end line number" parameter to the INCLUDE file command is now processed correctly. Every input file on the command line is processed in turn, whether or not any of them contain INCLUDE commands [SD 0769]. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 13 3.3 Outstanding Problems 3.3.1 Compiler Omitting a ';' after an RTL/2 statement (where this is legal, for example immediately before a REP statement) results in any errors being reported as occurring on the next source line that does end with a ';' [SD 0610]. {work round: do not omit ';'s in places where they will have to be added later if a new statement is inserted on the next line} The cross-reference output by the compiler may vary slightly with the order in which bricks are declared in the source modules; this is most likely for bricks containing multi-dimensional arrays, and will result in errors from the Linkage Verifier [SD 0611]. {work round: re-order the bricks in the affected module} Programs that are to run with separate I- and D- space (i.e. built with the TKB /ID switch) should not contain modules compiled with the TR (source line trace) option, since this generates data words inline with the code [SD 0646]. {work round: none, but if you find this a serious restriction then please contact Natron for further discussion} A warning message (B203) is given incorrectly for any occurrences of the integer constant -32768, although the actual code generated is correct [SD 0651]. {work round: specify the same value in a different radix using one of the keywords BIN, OCT, HEX} The compiler rejects file specifications that include DecNet node name and/or password details [SD 0740]. {work round: copy the file(s) required to the local node} 3.3.2 Runtime support software The routine RTAN is inaccurate for values close to pi [SD 0647]. {work round: use the equivalent RSIN / RCOS expression} 3.3.3 Macro processor If a macro whose definition contains an INCLUDE command is called from within another INCLUDEd file then RMP enters a loop [SD 0770]. {work round: reorganise your RMP source files} PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 14 3.3.4 Debug The RTL/2 symbolic debug utility cannot be used on target programs that invoke the CNCT$ (Connect To Interrupt) directive [SD 0614]. {work round: none - this restriction will be documented in the new version of the package User Manual} The RTL/2 symbolic debug is difficult to use with target programs that have been compiled and linked with separate sections for code and data, since it is necessary to keep using the SECTION command when switching from accessing code (e.g. setting a breakpoint) to examining or modifying data [SD 0630]. {work round: where possible, compile programs to be debugged using this utility with a single section for code and data} PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 15 3.4 Compatibility This release is upwardly compatible with the previous version (9A) of this product, with the following exceptions: - the macro processor (RMP) no longer treats white space in macro calls as terminating the list of parameter values, which means that calls which relied on this to append comment text may give incorrect results (since the additional text will be passed to the macro as a parameter); - if recompiling a program to use the FPP co-processor, note that any floating point calculations that result in errors which are detected by the FPP hardware (such as overflow) will call RRGEL. - the compiler now translates any '_' characters in global brick names into periods ('.') for both assembler and cross-reference files - in the latter case this will cause verification errors if some modules containing such names are recompiled and others are not (NB: this is only relevant where the '_'s appear in the first six characters of the brick names). Also, note that modules compiled with the /FP switch which contain REAL constants in Code statements (see 3.1.1) cannot be processed with older versions of this compiler. The code generated by the compiler will be identical to that from the previous release, assuming the same switch and option settings and the same symbol table sizes. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 16 4 USING THE NEW RELEASE This section describes how to use this new release to build RTL/2 programs using the new /FP switch on the compiler. The /FP switch has three settings: /FP:Y - this generates inline FPP code that assumes that all of the modules in the program will have been (re)compiled with this switch (NB: including any RTL/2 runtime support modules); /FP:L - this generates inline FPP code that assumes that none of the other modules in the program will be (re)compiled with the /FP:Y setting; /FP:N - this does not generate inline FPP code (default action if the /FP switch is not specified). The second of these settings allows individual modules within the program to be recompiled to use inline FPP code without having to also recompile other modules whose source may not be available. Any runtime support modules used will also need to be regenerated as follows: /FP:Y - must rebuild: base program (include FPP support) control routines (include new FPP routines only) formatted i/o routines (recompile with /FP:Y) maths routines (recompile with /FP:Y) (or use MTHLIBRSX.NLB library) /FP:L - must rebuild: base program (include FPP support) control routines (include old & new FPP routines) may rebuild: formatted i/o routines (recompile with /FP:L) maths routines (recompile with /FP:L) This is most easily done by running the BUILDRTS command file. The final point to remember is that if you are task building on a PDP-11 system which does not have the FPP hardware, then you must specify the /FP switch if the program built is to run on another PDP-11 which does have the FPP. PDP/RSX RTL/2 Compiler, release 10.0 (H) Page 17 5 DISCLAIMER The following text is also included in the HLICENCE.txt file THE PDP/RSX RTL/2 COMPILER HOBBYIST RELEASE ("(H)RTL/2") IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. (H)RTL/2 IS PROVIDED WITH NO SUPPORT AND WITHOUT ANY OBLIGATION ON THE PART OF NATRON SOFTWARE MAINTENANCE LTD ("NATRON") TO ASSIST IN ITS USE, CORRECTION, MODIFICATION OR ENHANCEMENT. NATRON SHALL HAVE NO LIABILITY WITH RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY (H)RTL/2 OR ANY PART THEREOF. IN NO EVENT WILL NATRON BE LIABLE FOR ANY LOST REVENUE OR PROFITS OR OTHER SPECIAL, INDIRECT AND CONSEQUENTIAL DAMAGES, EVEN IF NATRON HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.