DEPARTMENT OF NATIONAL DEFENCE DIRECTORATE OF AEROSPACE COMBAT SYSTEMS SPOOL/RT-11 TRANSPARENT PIPELINE SPOOLER USER'S REFERENCE GUIDE 17-OCT-80 This document corresponds to: SPOOL/RT-11 V1.00 & V1.01 For RT-11 V03B & V4.00 SPOOL/RT-11 1 USER'S REFERENCE GUIDE FORWARD _______ SUPPORT - This document and the software it _______ describes are supported by: National Defence Headquarters Ottawa Ontario K1A 0K4 Attn: G. Adams, DACS 2-2-4 Phone:(613) 993-9624 DISCLAIMER - Her Majesty and the Department of __________ National Defence, reserve the right to discontinue support at any time without notice and assume no responsibility for the correctness of this document or the operation of the associated software. COPYRIGHT - This document and the software it _________ describes are property of the Government of Canada. They may be used, in full or in part, by any person or agency provided that such use is not for gain or reward except as explicitly authorized by Her Majesty or her designated representative. CONSERVE - In the interest of conservation, if you ________ are having problems, don't waste time and effort generating a carefully worded, typed masterpiece. Just jot it down (legibly) and send it off, preferably on a post card. SPOOL/RT-11 2 USER'S REFERENCE GUIDE 1. SCOPE - This document describes the use and _____ installation procedures of a spooling package based on the paper "A Transparent Output Spooler _ ___________ ______ _______ for RT-11", which was presented at DECUS Chicago, ___ _____ in April 1980. 2. INTRODUCTION - SPOOL/RT-11 offers some noteable ____________ improvements (and hopefully not too many disadvantages) over other spooling packages currently in use on RT-11 systems. The main features of the package are: - transparent operation such that commands like ".DIR/PRI" and "COPY FOO.TXT LP:" will work correctly in the spooled environment; - pipeline operation such that output begins as soon as data is available, rather than waiting for say, a .LST file to be completely built and closed; - concurrent output for up to 8 devices and - intelligent operation supporting such features as software forms control etc. 3. PRINCIPLES OF OPERATION - The transparent pipeline __________ __ _________ spooler is implemented via a pseudo device handler "SP", which works in conjunction with a privileged foreground job named "SPOOL". The SP handler works like any other serial output handler except it doesn't handle a device. Instead, it manipulates a set of pseudo command SPOOL/RT-11 3 USER'S REFERENCE GUIDE and status registers (CSRs), located in vector memory, which are monitored by the spooling job SPOOL. SPOOL responds to the CSR bit settings as if it were a device, tricking SP. Any output to SP: will be directed to a buffer within the SPOOLer job, which in turn will be written to a ring-structured scratch file and then, as soon as there is one block of data available, on to the final output device, usually LP:. This achieves a pipeline effect. Transparent operation is accomplished by utilizing logical to physical device name assignments. For example, if LP: is assigned to SP: (ASSIGN SP: LP:) all output to LP: will, in fact, go to SP: and hence be spooled. Note that there is no conflict in having both a logical LP: and a physical LP: under RT-11. In fact, the SPOOLer job itself uses the real (physical) line-printer by doing its lookup of LP:, prior to the logical assignment. 4. GETTING STARTED - The spooling package comes with _______ _______ 2 pre-built spoolers. One for use in an RT-11 V03B and/or V4.00 foreground/background (FB) environment and one for an RT-11 V4.00 extended memory (XM) environment. (Use of the XM package should work, but has never been tested, with an SPOOL/RT-11 4 USER'S REFERENCE GUIDE RT-11 V03B XM monitor.) In most cases, one of the prebuilt spoolers will be suitable for your needs. If not, you will have to build a customized one as described later. The following points are noted to help you decide if a prebuild spooler will be suitable for your system. - Only one output device, the line-printer 'LP:', is supported by the pre-built spoolers. If you have more than one device to be concurrently spooled, or if some device other than LP: is to be used, then you must generate a tailored system. - The prebuilt spoolers require a 400 block scratch file on the system disk named 'SPOOL.SYS'. If you require a larger or smaller scratch file, or if the name is unacceptable, then you must generate a tailored system. - Physical memory locations 360 to 377 are used for the spooler vector and pseudo CSRs. If you have a device which uses any memory location in the range 360 to 377 or if you have set this area aside for the program stack, then you must generate a tailored system and select alternate memory locations. - The RT-11 SYSGEN options error logging and the device time-out are not ___ included. If your system requires either of these options to be installed, then you must build a new SP handler. - The spooler cannot support system jobs. If your monitor includes system jobs and if they do output to the line-printer then you will have to be very careful or very lucky. SPOOL/RT-11 5 USER'S REFERENCE GUIDE 5. INSTALLING A PREBUILT SPOOLER - If you decide that __________ _ ________ _______ a prebuilt spooler will do the job, the procedure for its installation is straight forward. Simply copy the appropriate files from the distribution kit to your system disk, reboot the computer and start up the spooler. For example, an FB installation from double density floppy disks (RX02s or DY:). You may substitute your device as appropriate. Mount the distribution volume in DY0: (or DY1: if DY0: is your system disk SY:) and: .ASSIGN DY0: DK: .COPY/SYS SPOOL.REL,SP.SYS SY:*.* ?PIP-W-Reboot .BOOT SY: 6. GENERATING A TAILORED SPOOLER - The procedure for __________ _ ________ _______ generating a tailored spooler is as follows: - Copy the distribution disk to a working copy and put the master away in a safe place. All subsequent operations are done on the working copy. - Edit the file SPINIT.MAC to change the parameters as necessary. The comments in the file describe each individual item (honestly). - Execute the command file SPBLD.COM to build an FB package or the command SPBLDX.COM to generate an XM version. - Copy the files to the system disk as described in section 5. SPOOL/RT-11 6 USER'S REFERENCE GUIDE 7. STARTING THE SPOOLER - Once a spooling package has ________ ___ _______ been installed, running it is quite simple. The following example, which is suitable for inclusion in a start-up command file, illustrates how to run the prebuilt FB spooler. It is assumed that SPOOL.REL is on the system disk SY:. The start up of other variants is left to your ingenuity. .DEAS LP: !In case of restart. .DEAS LP0: .LOAD LP: !SPOOL gets real LP:. .FRUN SY:SPOOL !Start the spooler. !Wait a moment for SPOOL to lookup LP: .ASSI SP0: LP: !users get logical LP: .ASSI SP0: LP0: !To ensure LP:=LP0:. 8. START UP NOTES - The following points are made in _____ __ _____ support of the startup procedure: - The INSTallation of the SP handler may not be necessary under RT-11 V04.00 since it incorporates an automatic installation algorithm. - When you FRUN SPOOL, you must wait long enough for it to lookup the physical devices, before you do your logical device assignments. If you don't, then you may lookup a a logical device which translates to SP. Ie. concurrent input and output, to and from SP makes for some peculiar race conditions. This problem is particularily noticeable when the spooler is started from a command file. A good way to get arround it is to do something else in between the FRUN SY:SPOOL and the ASSIGN commands. - SPOOL may be run as a system job using SRUN SY:SPOOL.REL. Watch out though, if you forget to enter the .REL extension, you will attempt to run the SPOOL/RT-11 7 USER'S REFERENCE GUIDE scratch file SY:SPOOL.SYS, which is bound to do something strange. - Always assign both devices xx: and xx0: to SP since xx: and xx0: may not be the same thing, "logically" speaking. 9. USING THE SPOOLER - Normally ,the spooler is _____ ___ _______ started when the system is booted, using a start-up command file. Once running, its use is transparent and no special action need be taken to access the package. For improved usability however, operators may control the spooler using some SET commands supported by the SP handler as follows: .SET SP UNIT=n is used in conjuntion with the other set options; it has no meaning alone. When given, it indicates that the next specification is to be applied to the device associated with SP unit n (SPn:). If not given, unit 0 is the default. .SET SP SHOW is used to display spooler statistics. .SET SP NEXT moves output forward to the start of the next listing in the scratch file, i.e. to the next block 0. This also can be equivalently thought of as a delete the current listing command. .SET SP LAST moves output back to the start of the last (current) listing in the scratch file, i.e. to the last block 0. .SET SP KILL removes all output currently spooled up for the specified device. .SET SP OFF stops all spooled output to the specified device but does not SPOOL/RT-11 8 USER'S REFERENCE GUIDE remove the spooled up data from the scratch file. Further output to the device may occur but will be held until the spooler is set on again. .SET SP ON counter acts the effects of setting the spooler off. Note that KILL is to as OFF is to ; think about it! 10. SECONDARY LOGICAL UNIT ASSIGNMENTS - One potential _________ _______ ____ ___________ difficulty using the spooler comes when one wishes to assign some logical unit name to a device which is already logical. For example, the logical name LST: is often used in command files when the actual device where the listing is to go is not known ahead of time. If you wanted to use the command file to obtain a listing on the line-printer LP:, you would enter the command .ASSIGN LP: LST: prior to its execution. If SPOOL/RT-11 is running however, LP: will have been assigned to SP: as in .ASSIGN SP: LP:, making LP: a logical name. Therefore you cannot .ASSIGN LP: LST: because you cannot assign a logical to a logical. The solution would be to simply .ASSIGN SP: LST:.