perm filename SPOOL[1,VDS] blob sn#082271
filedate 1974-01-11 generic text, type C, neo UTF8
COMMENT ⊗ VALID 00009 PAGES
C REC PAGE DESCRIPTION
C00002 00002 SPOOLER SYSTEM DOCUMENTATION:
C00005 00003 SPOOL & XSPOOL Create Spooler Commands.
C00011 00004 Delayed listings, Page range selection, Repeat copies
C00014 00005 XSPOOL Special Features
C00017 00006 QSPOOL
C00019 00007 UNSPOOL
C00022 00008 The Spooler
C00026 00009 Spooler Version 2 Operating instructions.
SPOOLER SYSTEM DOCUMENTATION:
SPOOL, QSPOOL and UNSPOOL, [LIST] and [xSPL]
Spooler for line printer listings
R. E. Gorin 15 Feb 1971
Revision #6. 25 April 1973
Spooling provides a method of producing line printer listings
of files without the usual disadvantage of tying up a users job while
the listing is actually being done.
To use the spooler, a user must create commands for it. A
command is the name of a file to list, and control switches.
Spooler commands are created by the system command "SPOOL."
This file documents the entire spooler system:
SPOOL - Accept commands to spool files to the LPT.
XSPOOL - Accept commands to spool files to the XGP.
[LIST] - The actual LPT listing program.
[XSPL] - The actual XGP listing program.
QSPOOL - Spooler status report program
UNSPOOL - Deletes spooled requests. Modifies PRINTR behavior
SPSUB - Subroutines to make spooler command files
(These subroutines are documented separately in
Example of Spooling.
The monitor level command:
will cause the LPT spooler to list this file, SPOOL.REG[UP,DOC].
When the listing is completed, the requestor will be notified with
a message on his terminal.
Spooled listings are preceeded by a title page (except see
/NOTITLE below), used to make it easy to separate different
listings. This title includes the file identifier, the name of the
requestor, and his project- programmer number, the current date and
time, and the date abd time when the file was last written.
Programmer names are read from the file FACT.TXT[SPL,SYS]. Project
names (of which there are few) are read from the file
SPOOL & XSPOOL Create Spooler Commands.
In the discussion below, 'SPOOL' is used to mean either the
command 'SPOOL' or the command 'XSPOOL', except as noted. 'SPOOL'
makes requests for the LPT spooler; 'XSPOOL' makes requests for the
To have the spooler make a listing the user must tell the
spooler what file(s) to print. This easiest way to tell the spooler
what to do is by the system level command SPOOL. This command
consists of the word SPOOL followed by the name(s) of the file(s) to
be listed. File names are separated by commas. Each file name may
be followed by switches, explained below. The program Spool will
send commands to the spooler.
Files to be spooled are specified in the conventional way, by
file name, extension, and optionally project-programmer number.
Asterisk, *, may be used to allow matching of any file name,
extension, project name or programmer name. (RPG, DMP and REL files
will not be matched by * in the extension).
Switches are allowed either preceding or following the file
name. Switches that precede the name are sticky and will be applied
to subsequent names. A switch consists of a slash, the switch name,
and sometimes, a parameter. For example, /REPEAT=5.
The following switches are available. Note that most
switches occur in two senses ('delete' and 'nodelete'). This allows
an explicit switch in some term to over-ride a sticky switch.
DELETE DELETE this file after printing. The file protection
NODELETE of this file must be low enough so that the spooler
can delete it. The file must belong to the requestor
(Alias not allowed).
NONUMBER Omit SOS line numbers from the listing. 'N' is an
NUMBER accepted abbreviation for 'NONUMBER'.
FORTRAN The first character of each line is interpeted as a
NOFORTRAN Fortran carriage control character.
LPT100 The spooler will open the LPT in mode 100, instead of
LPT0 mode 0.
HEADING Print a page heading at the top of each page. 'H' is
NOHEADING accepted as 'HEADING'. HEADING is implied for all
"LST" or "DOC" extensions,
any file from any area with programmer = DOC.
The heading includes date, time, file name and page
TITLE Precede the listing with a title page. 'TITLE' is
NOTITLE implied for all files.
NARROW Center the title page to fit an 8.5 inch wide page.
RECOPY Copy the file to [SPL,SYS] and list the copy. This
NOCOPY allows the file to be edited while the listing is in
REPEAT=n Make n copies of the listing. (REPEAT is NOT sticky).
EXTRA=n Insert n extra line feeds in the listing after every
line feed in the file. (EXTRA is NOT sticky).
DUMP Octal listing. Data will be printed as octal full
NODUMP words. ('OCTAL' is an equivalent switch.)
NOFF Each line feed in the file is translated to '177&'21
FF which causes single spacing with no form-feed between
NOWARN Suppress "spooling done" message when listing is done.
ASK Before making the spool command, SPOOL will type the
file name and wait for the user to respond with "Y" to
spool the file. (This is useful with *.* terms).
HOLD=hhmm The listing will be held in the queue until the time
specified by hh hours, mm minutes. (24 - hour time is
assumed.) If hhmm is prior to the current time, hhmm
tomorrow is assumed.
MODE=n Open the file in mode 'n' ('n' is octal).
Delayed listings, Page range selection, Repeat copies
Usually requests for spooled listings will be processed as
rapidly as possible. Under some circumstances this may not be
desired. For example, a long listing impacts the normal operation of
the system by making the line printer unavailable during its
duration. The spooler allows users to delay such listings until a
time of minimum loading (e.g., 0500) when the unavailability of the
line printer is less likely to interfere with other users.
If the construction /HOLD=hhmm appears in a command line
then hhmm is interpreted as the (24 hour) time of day when the
listing should actually be sent to the line printer. In the example
below, 1730 will be interpreted as 5:30 PM.
Example: SPOOL SYSTEM.LST[S,SYS]/HOLD=1730
If the time specified is smaller than the current time, it is
interpreted to mean, "list the file tomorrow at the time specified".
That is, if at 10PM you give the command:
then the listing will occur in six hours.
You may follow a file name by a list of ranges of pages that
you want listed. The list must be parenthesized. For example:
SPOOL FOO.SAI (1,7,5:8)
will cause page 1, page 7 and pages 5 through 8 inclusive to be
listed. Page ranges are never sticky.
In octal dump mode, this page range list is used to specify
a word-range to list.
MULTIPLE COPIES OF A FILE
The REPEAT switch (/REPEAT=n) is accepted by SPOOL. The
effect is to interpret n as a decimal number and to list that many
copies of the file. Multiple copies are spooled as usual, except
that the two pages of heading that normally precede a file (except
if the /NOTITLE switch is used) are suppressed on the second and
subsequent copies of the file.
XSPOOL Special Features
The XSPOOL command is quite similar to the SPOOL command.
The XGP has greater flexibility than the line printer, so more
parameters can be specified in the XSPOOL command.
The following switches are legal only in the XSPOOL command:
FONT#n=f 'n' is a number from 0 to 15 decimal. 'f' is a file
name. The XGP spooler will use the font named 'f'
as font 'n' when spooling. If '#n' is omitted, n=0
is assumed. Up to 16 font select switches are
LMAR=n Set left margin to column 'n'. Columns in the XGP
are numbered from 0 to 1699 (approximately). The
left margin is the column which the carriage return
RMAR=n Set right margin to column 'n'. If the XGP is going
to write a character that exceeds this margin, a new
line will be started.
TMAR=n Set the number of blank scan lines between the top
edge of the page and the first line of text.
BMAR=n Set the number of blank scan lines between the bottom
of the text and the bottom edge of the paper. (The
system interprets BMAR=0 to mean no paper cutting.)
PMAR=n Set the number of scan lines in the page body. Text
is written inside this area.
XLINE=n Set the minimum interline spacing to 'n' scan lines.
;***** the following is not yet implimented in full: (5/9/73)
If any explicit FONT selects are made in the XSPOOL command,
no /TITLE switch will be assumed, unless it is explicit. Similarly,
if any FONT select switch specifies some font number other than 0,
no /HEADING switch will be assumed, unless it is explicit.
Page headings will occur in font#0. Whatever font was in
effect before the heading line will be reinvoked before any further
processing. The title page, if present, will be made in font#0.
The QSPOOL command starts the SPOOL program in a special
way. QSPOOL reads the directory of [SPL,SYS] and interprets the
contents of the SPX and XSP (spooler command) files. Essentially,
it displays the queue of files to be printed.
The queue is based on a priority scheme. The priority of a
spool request is determined by
<time in minutes since spool request, +1>/<file size in records>
Requests are processed in the order of decreasing priority.
Line printer allocation:
The spooler uses the following scheme when it wants to use
the line printer. It uses the DEVUSE uuo to determine if there is
any one in the queue waiting for the LPT, and if there is such a
person, it waits until there is no one waiting for the LPT and there
is no one using the LPT. Once the LPT is initialized by the
spooler, the spooler hangs on to it until either it finishes
processing all command files, or it begins a new listing file and
discovers that some one is queued waiting for the LPT. In either
case, the spooler releases the LPT.
UNSPOOL is a monitor level command that invokes the program
SPOOL in a strange way:
If you run UNSPOOL it will display all the spooler commands
that you (your PPN) have requested, and it will allow you to delete
any of the command files that it displays. If you delete a command
file that hasn't been seen by the spooler then nothing special
happens since the spooler is not yet aware of the command, so it
won't be missed. If it happens that the spooler is already
processing your commands then the listing in progress will be purged.
If you log in as SPL,SYS and run Unspool then not only are
you allowed to purge any command file that is either in progress or
pending but you also can change the spooler behavior in the following
1. You can cause the present listing to be purged.
2. You can cause the present listing to be started over.
3. You can cause the spooler to hold the queue and release
the LPT immediately before starting the next file.
4. You can release the queue from the state induced by
5. You can suspend spooling, breaking the listing that is
currently in progress and releasing the LPT. When you
escape from this mode by using the release queue command,
the listing that was broken will be resumed.
The spooler, i.e. the program that actually lists user files
is called [LIST] and runs logged in as [SPL,SYS]. The following
document is copied from the spooler internal documentation. It is
for the purpose of allowing other programmers to interface to the
spooler from their own programs without going through the program
SPOOL. The following information is subject to revision without
Command files to the spooler are written in dump mode, mode
17 on the DSK. The command file must be precisely 200 (octal) words
long. Any name is allowed for the file name; the extension is SPX.
The file shall contain the following data:
NAME WORD NUMBER
SDEF CFORM, 0 ;CONTAINS THE FORMAT VERSION NUMBER.
SDEF RQNAM, 1 ;SIXBIT PPN OF REQUESTOR.
SDEF RQJOB, 2 ;LINE NUMBER,,JOB NUMBER OF REQUESTOR
SDEF FDEV, 3 ;SIXBIT NAME OF DEVICE (0 = DSK)
SDEF DEVMOD, 4 ;0,,SOURCE DEVICE MODE.
SDEF FSIZE, 5 ;FILE SIZE IN 200 WORD RECORDS IS PLACED HERE.
SDEF RQTIME, 6 ;DATE,,TIME IN MINUTES WHEN REQUEST WAS MADE
SDEF FNAME, 7 ;SIXBIT FILE NAME OF FILE TO BE LISTED
SDEF FEXT, 10 ;SIXBIT EXTENSION,,0
SDEF FDAT, 11 ;FILE DATE AND TIME ARE SAVED HERE
SDEF FPPN, 12 ;SIXBIT PPN OF FILE OWNER, (0 = RQNAM)
SDEF ANAME, 13 ;ALIAS NAME
SDEF AEXT, 14 ;ALIAS EXTENSION
SDEF APPN, 15 ;ALIAS PPN
SDEF CBITS, 16 ;LISTING CONTROL BITS
SDEF CREP, 17 ;REPCOUNT,,LINE EXPANSION COUNT
SDEF PSPEC, 20 ;PAGE SPECIFICATION LIST
FILE CONTROL FLAGS CBITS RIGHT
SDEF DELBIT,1 ;DELETE
SDEF FORBIT,2 ;FORTRAN CONVERSION
SDEF OMDBIT,4 ;LPT MODE 100
SDEF NONBIT,10 ;NO NUMBERS
SDEF PHDBIT,20 ;PAGE HEADINGS
SDEF NOLBIT,40 ;NO LOGO
SDEF NARBIT,100 ;NARROW PAGE HEADINGS
SDEF OCTBIT,200 ;OCTAL DUMP
SDEF QBIT,400 ;QUIET. NO MESSAGE ABOUT SPOOLING DONE.
SDEF LFBIT,1000 ;SUBSTITUTE 177 21 FOR EVERY LINE FEED.
CREP/ LEFT SIDE: FILE REPEAT COUNT
RIGHT SIDE: EXTRA LINE PARAMETER. (IF <0 THEN SET THE LFBIT)
IF ZERO, THEN SPOOL ENTIRE FILE.
IF ZERO LEFT HALF THEN RH,,RH
LH = LOW PAGE, RH = HIGH PAGE IN PAGE RANGE TERMS.
TERMS ARE PROCESSED UNTIL A ZERO TERM IS SEEN.
Spooler Version 2 Operating instructions.
There are three programs pertaining to the spooler.
[LIST] The spooler.
SPOOL The command creation program
SPOOLQ The spooler queue interrogation program
[LIST] runs as a detached job, logged in under the ppn
SPL,SYS. The job is identified by the name [LIST]. Normally, when
idle the spooler will spend most of its time in INTW, interrupt wait.
When it is listing a file, it will be mostly in IOWQ with brief
excursions into RUNQ. If the spooler goes into IOWQ and nothing is
listed, it may be sleeping, waiting for the line printer, which
someone else may have assigned.
The spooler may crash, entering STOP status. If this happens,
chances are that it has grabbed the line printer, rendering the LPT
unavailable to all. To remedy this, attach to the spooler's job and
kill it. The system will start a new spooler within one minute.
SPOOL is used to create command files to the spooler. SPOOL
is kept on the system area. It is accessed either by R SPOOL, or by
the monitor level command SPOOL.
When SPOOL starts it does a NAMEIN to see if it can find a
program named [LIST]. If it can't find such a program, SPOOL will
do a WAKEME uuo to initiate new spooler.
SPOOL creates command files with "SPX" extensions on the
spoolers disk area [SPL,SYS]. These files are read by the spooler,
and they contain the name of the file to be listed.