APPENDIX A BUILDING RUNOFF RSX-11M MAPPED SYSTEMS ------- ------ ------- Procedure: 1. Use UFD to set up the proper UFDs, if necessary. 2. Select the proper task build file: 1. RNOBLD.CMD Overlayed 2. BLDFCS.CMD Overlayed, resident library 3. BIGBLD.CMD Non overlayed, resident FCS library 4. SMALBL.CMD Very small RNO (slowest) If this is used >LBR CMTAB/cr CMTAB must be done to create a library. 3. Select the options you require by editing the RNPRE.MAC. This is only necessary if you wish to have a different set of defaults. Some are mentioned in the section on CUSTOMIZATION. 4. Edit the Task Build command file to reflect your individual system needs. The Task Build command file contains parameters to set the default switches, default paper size (for /-FF) and default underline mode. The underline mode is currently set as UL:L. If you use lots of index terms or otherwise make heavy demands on dynamic memory RNO will run faster by increasing the EXTSK parameter. The overlayed version has lots of room for dynamic memory extension and runs nearly as fast as the non overlayed version. 5. Assemble MAC @RNOASM 6. Build the task TKB @RNOBLD .....or TKB @BLDFCS ..or TKB @BIGBLD BUILDING RUNOFF Page A-2 RSX-11M 7. The final RNO.TSK should be copied to LB:[1,54], and in- stalled if you wish to make it available to all users. 8. Finally to generate RSX documentation: @DOCRSX 9. Alternatively the assembly and task build steps may be executed by: @RNORSX ------- This will build a standard RSX version of RNO. RSX-11M+ -------- The mapped RSX proceedure should be used. It is possible to separate the code into data and code using I/D space. The .psects have all been properly defined and M+ users may wish to experiment with various methods of reducing the program size to make more dynamic memory avail- able. RSX-11M UNMAPPED SYSTEMS ------- -------- ------- Users of unmapped systems should follow the procedure outlined for mapped systems, but selecting UICs as appropriate. File RNOBLD.CMD will have to be edited to delete the /MM switch and to change the PAR directive to match system requirements. The final RNO.TSK should be copied to LB:[1,24]. RSX-11D/IAS ----------- Users of RSX-11D/IAS should follow the procedure outlined for users of RSX-11M Mapped systems. Since the conventions for source and object files are installation dependent, all .CMD and .ODL files should be edited accordingly. Additionally, RSX-11D/IAS users should alter RNOBLD.CMD to change the /MM switch to /MU and to change the PAR directive as needed. Alternatively, IAS users may use command file RNOIAS.CMD to assem- ble and build RUNOFF. The command file IASBLD.CMD may be used for just building RNO. The command file contains parameters to set the default switches, default paper size (for /-FF) and default underline mode. BUILDING RUNOFF Page A-3 RSX-11D/IAS NOTE Indirect command files will not work with heavily overlayed versions under IAS. IAS users must use only IASBLD or BIGBLD. To generate IAS documentation: @DOCIAS Unfortunately an IAS help file is not generated. IAS users may be able to adapt the RSX help file created by @DOCRSX. VAX/VMS ------- This program must be built under compatibility mode using MCR. The com- mands are: @RNOVMS or ...... MCR MAC @RNOASM MCR TKB @RNOBLD Otherwise the 11-M proceedure should be used. The final RNO.EXE should be copied to SYS$SYSTEM with W:E protection if all users are to be able to use it via the $ MCR RNO command. The following symbol may be defined: $ RNO :== MCR RNO To generate VMS documentation: @DOCVMS RT-11/TSX --------- RT11 and TSX users should copy all .MAC and .COM files to the device as- signed INP. The output device for the .OBJ, .MAP, and .SAV files should be assigned OUP. ASS DEV INP ASS DEV OUP Before compiling the files, RNPRE.MAC may be edited to change the default options. The macro files are assembled by initiating the com- mand file RTASM.COM: @RTASM The resulting object files are linked by initiating the command file RTBLD.COM: @RTBLD BUILDING RUNOFF Page A-4 RT-11 Also, if your system is short on available memory you should modify RTBLD to properly overlay the program or remove autohyphenation (see the discussion in the efficiency and program size sections below). To generate the appropriate RT11 documentation users should use RUNOFF to create the documentation file from the .RNO files supplied. Copy all the .RNO files to the default device. RUN RUNOFF RUNOFF.TXT,RUNOFF=RNORT RUNOFF.TOC=RUNOFF.RNT /X COPY/CONCATENATE RUNOFF.TOC,RUNOFF.TXT RUNOFF.DOC The resulting file will be RUNOFF.DOC built specifically for RT11 users. No RT help file is available. RSTS/E ------ The version of RNO that this originally grew from supported RSTS/E and a symbol is in RNPRE.MAC to conditionalize this support. I do not have access to a RSTS system, and as a result RSTS users are on their own. If a RSTS user comes up with a set of patches to make it work, I will be glad to include them with the distribution. Presumably you must run this under RSX simulation available with RSTS. RESTRICTIONS This version of RNO uses the SOB instruction. If your machine (11/20 or 11/10) doesn't have this instruction it may be simulated in the RNPRE.MAC file. Since almost every PDP-11 has this instruction you will probably not have to worry about this. If your CPU doesn't have EIS (MUL and DIV instructions) you should disable the symbol $EIS in RNPRE.MAC. If you don't have EIS you need the system subroutines $MUL and $DIV. CUSTOMIZATION The prefix file RNPRE.MAC has a symbol $FLORD to define a set of default escape sequences for the Florida data printer. You can select Diablo escape sequences with the symbol $DIAB or you may define your own internal set of default escape sequences by modifying the table in routine INIT. The symbol H$$PHN may be deleted to remove the AUTOHYPHE- NATION code. The default escape sequence for variable spacing may be either 10 or 12 pitch Diablo style. A large number of symbols in RNPRE may be modified. For example you may pick default indentation, spacing, margins, pagesize, and parameter limits. Input and output buffer sizes may also be adjusted. They are labeled and commented for your BUILDING RUNOFF Page A-5 ALL OPERATING SYSTEMS convenience. Some commonly changed options are in the build command file. The default is configured for a Florida data. This will work with most Diablo compatible printers. PROGRAM SIZE The RSX overlayed version size is around 34.25 kbytes. If you need to use a non overlayed version then the size will be considerably larger. The non overlayed RT-11 version is about 40 kbytes. You may decrease the size by decreasing the buffer sizes. You can also omit the AUTOHYPHENATION feature by removing the symbol H$$PHN in RNPRE.MAC. The current RSX/IAS/VMS version also keeps all input files open and the cur- rent block resident in memory. This adds about 2 kbytes to the program size. The code may be modified to temporarily close unused files at the expense of program speed. The SMALBL.CMD builds a version which is about 31.5 kbytes. BUFFER SIZES The maximum input line is currently set to 512 characters. If this is too short you may redefine the symbol IBFSZ in RNPRE.MAC. You should be aware that if you do this the program will grow in size at the expense of dynamic memory. In general you can get around this restric- tion by using substitutions. For the RSX/VMS/IAS version the maximum output line is 256 characters. If this is not correct you may redefine it by changing symbol OBFSZ in RNPRE.MAC. The RT version has no output line limitation. This should only be necessary if you need shorter lines to pass to another program, or if you need longer lines in conjunction with the /-CR switch. Normally each line of printed text will occupy 1 output record, unless you have a large number of imbedded escape sequences which cause it to grow beyond 256. If it is longer than 256 it is split into several records. This causes no problems as long as you do not use /-CR. If you need to print more than 150 characters on a line and you use /UL:S (/U:S) or /UL:L (/U:L) the under- line buffer size may not be adequate. The current definition is symbol ULNSZ found in RNPRE.MAC. The RT-11 switches are indicated in parenthesis. EFFICIENCY The underlining options have an effect on the efficiency or RNO. /UL:S (/U:S) is the least efficient form of underlining and will slow execution especially when /PA (/P) is used to omit a large number of pages. /UL:L (/U:L) is more efficient with /UL:B (/U:B) the most effi- cient type of underlining. /UL:N (/U:N) is of course the most effi- cient, but at the cost of losing the underlining capability. The overlay structure places all of the commonly used routines and the hyphenation routine in the same overlay. The .LIST, .LIST ELEMENT, .CHAPTER, .APPENDIX, .NOTE, .HEADER LEVEL commands are in a separate overlay. The least used commands such as .STYLE, .LAYOUT, .DISPLAY are BUILDING RUNOFF Page A-6 ALL OPERATING SYSTEMS in a third overlay. This structure should be only slightly slower than a non overlaid program, and it contains a maximum of dynamic memory space (30+ Kbytes). With RUNOFF.DOC the non overlaid version was only about 10% slower. Anyone contemplating using the SUBSTITUTE commands, or indexing will probably need the overlaid version. If no indexing is done, and a limited number of escape sequences, and substitutions are defined, the non overlaid version will also probably do the job. If you wish to try different overlay schemes a few tips are in order. First RUNOFF,RNODYN,CMTAB,GCIN, and RSXIO or RT11IO should not be overlayed. If the I/O routines are overlayed then START or RNORT call the open and close file routines. HYPHEN, and RNCMD are the 2 most frequently used routines while STYLE and FMTCM are much less frequently used. COMND is called every time a command is parsed, so it should probably be in the same overlay with RNCMD. CMTAB may be split into 2 PSECTS of which STRING may be in the same overlay with COMND, but DSPTCH must not be overlayed. This is done in SMALBL.CMD. One way of increasing the efficiency of RUNOFF is to turn off autohyphenation. This will prevent excessive overlay switching as well as eliminating some code. For RUNOFF.DOC turning off hyphenation only decreased the time by about 6%. One more way to increase efficiency is to increase the the task extension. This only has an effect if large amounts of dynamic memory are used. Large footnotes, large .TEXT sec- tions, or many large definitions may make this option necessary. In general most users will find existing dynamic memory adequate. The RT version uses all available dynamic memory. NOTE This program has been successfully run on RSX-11M, VAX/VMS, RT-11/SJ, TSX, and IAS systems. It should run on RSTS under RSX emulation. It has not been tried on unmapped systems. DOCUMENTATION It may be necessary to modify the documentation to accomodate a particular printer. All of the page sizes are determined by the com- mands in the file CNTRL.RNO. This file should be edited to reflect both your hardware and your output format preference. Currently the output occupies a page size of 62 by 79 with /UL:S (/U:S) for underlining. HELP FILES Two help files are available with the current version of Bonner Lab Runoff. They are for the VAX/VMS systems and the RSX operating systems. They are called RNOVMS.HLP and RNORSX.HLP. They contain nearly the entire contents of this manual. If you are short on disk space you may BUILDING RUNOFF Page A-7 ALL OPERATING SYSTEMS not be able to use them. When you use DOCRSX or DOCVMS to generate the RNO manual the help files are also generated. Unfortunately it was not possible to generate a help file for IAS or RT. VMS installation To do this you need bypass privelege or you need to be in a system ac- count. 1. $ LIBR /HELP/CREATE RNO RNOVMS 2. $ COPY RNO.HLB SYS$HELP 3. $ SET PROT=W:R SYS$HELP:RNO.HLB 4. $ ASSIGN SYS$HELP:RNO.HLB SYS$LIBRARY/SYSTEM or . . . 5. $ LIBR /help sys$help:helplib rnovms RSX installation 1. You must copy the help RNORSX.HLP to uic [1,2] 2. The protection must be set W:R 3. An entry must be added to the main HELP.HLP referencing @RNORSX.HLP 4. It may be necessary to remove the first line in the RNORSX.HLP file. TEST FILES A number of files .TST are included with the distribution. They serve as a test, and guide to the various features available in Bonner Lab Runoff. A partial guide to these is: 1. COMAND.tst - How to define commands. 2. DISPLA.tst - Demonstrates display command on VT100 termi- nal. 3. LEVEL.tst - Demonstrates header levels. 4. DISLEV.tst - Demonstrates header levels modified by display commands. 5. LIST.tst - Demonstrates the .LIST command. 6. DISLST.tst - Demonstrates the .LIST command modified by .DISPLAY. 7. CHAPT.tst - Demonstrates various chapter styles. In addition some RNO files are available as examples of escape se- quence and substitution handling. These are: 1. GREEKMATH - Defines mathematical symbols for a Florida Data printer. The same ones should work on a Diablo printer. 2. VT100 - Defines some VT100 escape sequences to produce bolding and underlining.