This paper documents the 1906A/FR80 spooling system by filling the gaps left by and referring to other documents. Documentation is already provided for users and operators and a specification of the spool layout exists. These documents are listed. in Section l.2. This paper does not duplicate information already contained in one of those documents and the internal structure of the programs themselves is documented in their respective sources. It lists all files used (Sections 2 and 3), describes how to compile and test spool programs (Sections 4 and 6) and notes how to initialise and/or recover the spool file.
The following processes currently access the spool.
Process II, III, IV and V are documented in this paper. Those parts of SMOG, SPROGS and GROATS which access the. spool are described in the GEORGE file :SPOOL.SPEC under user :GSIN00.
Documentation about the spool system in other papers is as follows:
FR80 USER NOTES 3 and 8 contain the user's guide to the spooling system, including how to view a job with SPOOLJOB.
FR80 OPERATOR NOTICE 4 is a brief guide for the operators about the structure and use of the spooling system.
FR80 OPERATOR NOTICE 5 describes the use of the FR80 macro from the operators' console; this controls the despooler and the spool enquiry program.
File :SPOOL.SPEC in user :GSIN00 describes the layout of the spool and provides instructions to graphics package writers on how to write jobs to the spool.
FR80 PROJECT NOTE 15 describes the listing produced for the FR80 operators.
(615,SPOOLGRAPH) is the disc area used for the spooled data; there are 256 words per bucket. Current maxima are 20 jobs and 1316 buckets per job. The 2 maxima are themselves written in the file, so that graphics packages do not have to be altered if a change in layout should be required. However, the file must be clear of all jobs before the file structure is altered.
Access to the file is limited by GEORGE such that no 2 writers can simultaneously access it; the second potential writer is held up when it attempts to ONLINE it. The integrity of the spool control buckets depends on this. GEORGE can be made to allow or deny 2 simultaneous readers; alternatively, 3 simultaneous reader and writer. One of the standard 1900 utilities can be used to alter the required file settings. The spoolfile is currently set so that a simultaneous writer and reader are allowed (so that process IIb can always be run). Processes IIb and IV (both are readers) may occasionally show some self-inconsistency as a result.
The layout of data and control buckets is described in the GEORGE file :SPOOL.SPEC (see 3.4).
If the spool is moved to another disc, the graphics packages must be recompiled and the macros :SPOOL.FR80 and :SPOOL.PLOT (see 3.4) must be edited. The file would also have to be initialised (Section 5).
(615,TESTSPOOL) is used for testing. Its maxima are 4 jobs and 15 blocks. It is also possible to simulate the spool in the filestore.
As a rough guide user :GSIN00 is used to hold macros, sources and binaries of jobs currently in use - except for the viewing system which is under :GSIN23 (Section 6). :GSIN04 is used to hold versions being tested. :GSIN11 is used by the FR80 operators and is accessed by the operator jobs at run-time.
:GSIN11 contains files accessed during the running of the despooler program. :FR80TAPES under :GSIN11 contains the tapes written to by the despooler. A tape is acquired from the pool when required and is returned by the operators. Tapes used by the fiche-listing system (not documented in this paper) are also in this directory.
:SPOOL under :GSIN00 contains macros, sources and binaries of programs currently in use.
:SPOOPH under :GSIN04 is for testing. It contains files being developed which correspond to some of the files in :SPOOL, :FR80TAPES and :GSIN11. :SPOOPH stands for SPOOled graPHics.
:MACROS just contains the macro FR80. Was put into :OPERATORS, but fiche listen facility would not work.
:SPOOLF and :SYSBIN are used for the viewing system and are described in Section 6.
RTFR80 is a macro for releasing FR80 tapes. It can be used by :GSIN11 or :GSIN04. If a file is set up such that each line describes a tape thus:
<tapeserialnumber>,<cameraname>
Then RTFR80 can be called with the filename as its first parameter to return all the tapes specified.
For example, suppose that file FILEOFTAPES has the following contents:
7000777,HCS 7000776,BW35 1000,MFCH
Then the command:
RTFR80 FILEOFTAPES
will return the tapes (7000777,FR80-HCS), (7000776,FRBO-BW35) and (1000,FR80-MFCH) to the pool. The directory is set to be :FR80TAPES if the user is :GSIN11.
Files LOGmmmyy contain Logging data, output by the despooler. mmmyy specifics a month in the DATE format for the GEORGE SETPARAM command - for example, data for October 1975 goes to file LOGOCT75. All data written has so far been kept (beginning with LOGJUN75), and can be used for analysis. The data is in character form (in a GRAPHIC file) and can, therefore be LISTFILEd, :EDITed or SEARCHed. The precise format is described in :GSIN11.LOGFORMAT; 2 records are output for each tape written to and one for each job despooled or erased.
LOGFORMAT describes the format of the LOG files (previous paragraph).
Files of the form STUmmmyy are more ephemeral. mmmyy represents a month as for LOG files (above). The current file is occasionally listed by the despooler and emptied. The most recent listing is kept as an aid for program maintenance. If there are no errors, the output for one run of the despooler is as shown below.
MONITORING PRINTOUT FROM FR80 SPOOL PROGRAM OUTPUT OF SPOOLED FR80 JOBS TO TAPE ON 01/12/75 AT 14/47 FROM DISC AREA (A15,SPOOLGRAPH) CAMERA IS 8632 MICROFICHE ***JOB NOT PLOTTED :VMGA01 .FAULT **CAM= 7 **DELAY= 0 MINS **WD35= 1 **AVAIL CODE = 1 OUTPUT FOR USER :NSIN37 .DAD=MOP1 FRAMECOUNT UNAVAILABLE---JOB ENDED PREMATURELY OUTPUT FOR USER :FMPL01 .MOP2BELOW OUTPUT FOR USER :NRIN06 .PROG-GP39 ***JOB NOT PLOTTED :SPSV01 .XYDYUJOB236 **CAM= 4 **DELAY= 0 MINS **WD35= 1 **AVAIL CODE = 2 OUTPUT FOR USER :NSIN42 .MFVDOE OUTPUT FOR USER :NSIN57 .DAD-MOP1 END OF DATA FOR CAMERA PD32 MICROFICHE NUMBER OF JOBS COPIED TO TAPE = 5
(WD35 = Word 35 of J.I.B, =0 to be erased, =1 to be plotted)
(AVAIL is Word 30 of J.I.B, =0 Vacant, =1 Job Complete, =2 occupied)
A line starting OUTPUT FOR is written for each job despooled. A line starting *** JOB NOT PLOTTED indicates that the job was present on the spool but is not despooled because either its camera has not been requested, a delay has not expired or it is marked as erasable. Error messages are put to this file and as a last resort diagnostic printouts can be sent to it.
FR80LISTING contains the most recent listing generated by the despooler for the FR80 operators. The purpose of filing it is to avoid losing the contents if the lineprinter output is lost.
When the despooler is being tested LOGmmmyy, STUmmmyy and FR80LISTING are just ! files and are listed immediately.
The file SPEC contains a detailed description of the structure of the spool area (615,SPOOLGRAPH). Each word in the control blocks and the arrangement of data blocks is described. The second half (Section 6) contains a detailed specification that needs to be followed by the graphics packages when they access the spool.
The FR80 macro in :SPOOL runs both operators' jobs - the despooler and the spool enquirer. It is structured in such a way that the same macro can be used both for testing and for normal production runs. A test run can be initiated from MOP (Section 4.1). A production run is initiated from the operators' console; the operators' macro :MACROS.FR80 routes it to :SPOOL.FR80 with an extra parameter *OPS. The testing environment is different in that binaries are loaded from directory :SPOOPH, output is written to workfiles instead of disturbing the files on :GSIN11 (Section 3.3), displays go to the monitoring file not to the operators' console and jobs are not deleted from the spool when they are copied to a test tape.
FR80PROG contains the source of the despooler program. It is a macro which compiles and consolidates the included FORTRAN and PLASYD routines and optionally runs the binary by calling FR80. Details of how to compile and test it are in 4.1 and 4.2. Documentation about it is in the source itself.
FR80-BIN is the consolidated binary of FR80PROG.
OUT1COMM contains a declaration of the COMMON BLOCK/OUT1/ used by FR80PROG. FR80PROG incorporates it by *INCLUDE statements. Any other installation would need to perform a global edit.
OUT1COMM includes COMMENTS for each variable in the block. If any change is made to the COMMON block, it is made to OUT1COMM and also the GLOBAL declaration in the FR80PROG PLASYD segment. The GLOBAL declaration assumes COMPRESS INTEGER AND LOGICAL in the FORTRAN PD.
BLOCK DATA for this COMMON block is in FR80PROG.
STATEPR contains the source (PLASYD only) of the spool enquirer (FR80 STATE etc). Like FR80PROG, it is a macro which compiles and consolidates itself and optionally runs the binary by calling FR80. Details of how to compile and test it are in 4.1 and 4.3. Documentation is in the source itself.
FR80ST-BIN is the consolidated binary of STATEPR.
OLDFR80,OLDFR80PROG,OLDFR80-BIN are old versions. When new versions are implemented, the previous versions are kept for a short period in the above-mentioned files under :SPOOL.
PLOT is a macro whose first parameter can be either INIT or LOOK. INIT causes the spool initialisation program to be compiled and run (see Section 6); the source is included in the file PLOT.
The LOOK parameter of PLOT causes a program to be compiled and/or run (binary LOOK-BIN); this reads spool control buckets and prints their contents in an intelligible form. Control buckets, marked as being free, are not printed in this way. However, a NUTS parameter can be used to print all control buckets in NUTS format. For example:
OB :SPOOL.PLOT,PARAM(LOOK,NUTS21,JT15)
This will read from (615,SPOOLGRAPH) by default; the first 21 buckets will be printed in NUTS format.
The LOOK parameter will cause certain other parameters to be recognized:
The file FRINIT is a test version of the same-named internal routine in SMOG. In conjunction with the rest of SMOG, it can be used to write user jobs to a different spool file and also its displays do not go to the operators' console.
The file SPAN is a program which lists some data from System Journal.
The macro :MACROS.FR80 is a general driving macro for all things concerned with the FR80 and is used from the operators' console. Certain parameters are recognized immediately and in fact have nothing to do with the spooling system. These parameters at present are COPY (FR80 Technical Paper 13), SPOOLCOPY, WORKCOPY, IBMCOPY (the last 3 described in FR80 Operator Notice 20), LIST(FR80 Technical Paper 14), LOOK, FICHE(for running LISTFILE PR FICHE files for the print program), SUBFICHE (used by FICHE) and VIEW. To be recognized, these parameters must be first.
If the first parameter is not so recognized, a job is run using :SPOOL.FR80 and the parameter list is passed to it together with *OPS.
This section only refers to the regular operator-controlled jobs. Test versions of the macro FR80 and sources FR80PROG,STATEPR are kept in directory :SPOOPH (in :GSIN04). If for any reason, testing was to take place in another directory, a global edit could be made to the test versions in order to alter the references to :SPOOPH.
If a binary already exists (for the despooler or the spool enquirer), the test version of FR80 can be used to run it. All the parameters (except CP) that the operators use (FR80 OPERATOR NOTICE 4) to drive the despooler and spool enquirer can be used. So the first parameter must be STATE, ALL, FU or one of the cameracodes (CL16, BW16, CL35, BW35, PR16, MFCH, HCS, HCM or HCMS). The parameters TRACK7 or TRACK9 (TRACK7 is the default) can be used additionally from the operator's console to specify tape-class.
If issued from MOP, FR80 initiates a runjob itself. Additional testing parameters are:
The non-RJ examples assume that :SPOOL directory has been selected first.
FR80 STATE,JT10 [test spool enquirer] RJ MOPSTATE,:GSIN00,:SPOOL,PARAM(STATE),JD(JT10,URH) [same but at urgency H] FR80 BW16,JT25 FR80 FULL,TRACK9,DISC(615,TESTSPOOL),TAPEPRINT,RJMOPJRGFU2,JT30
Compilations are normally made by running :SPOOPH.FR80PROG from user :GSIN04. When tested, source and binary are copied to directory :SPOOL. It is also possible to generate a binary from :SPOOL.FR80PROG directly, running under user :GSIN00.
FR80PROG can be run from MOP and it will issue a runjob itself. The first parameter must be NORUN, RUN, SAVE or RUNSAVE. Any of these compiles and consolidates the program. NORUN does nothing else. SAVE and RUNSAVE also save the consolidated binary in FR80-BIN. RUN and RUNSAVE then run the binary by calling FR80; in this case the first and the JT parameters are omitted and the rest are passed on to FR80. Therefore, a parameter which must be first for the FR80 macro (see 4.1), must be second for FR80PROG.
FR80PROG SAVE,JT55 [Compile,save,no test run] FR80PROG RUN,FU,JT80 [Compile,do not save,call FR80 FU] FR80PROG RUNSAVE,BW16,TRACK9,DISC:PSEUD.DAFILE,TAPEPRINT,RJMOPJRGBW2,JT75
Compilation of STATEPR _is like FR80PROG. If a test run is requested (parameter RUN or RUNSAVE), then the parameter STATE is assumed.
STATEPR SAVE,JT20 STATEPR RUN,ALL,JT20 [Parameter STATE is not needed] STATEPR RUNSAVE,BW35,RJMOPJRGST2,JT20,DISC:DIRECTORY.SIMSPOOL
Before any graphics data can be written to a spoolfile, the file must be in an acceptable form. It must exist as a *DA file with 256-word buckets, it must be accessible to an ONLINE command (or ASSIGN if in the filestore) and its contents must conform with the specification in the file :SPOOL.SPEC.
The initial-job ensures the third of these if the other 2 are fulfilled. It sets up the spool control buckets (which are simply the first (n+1) buckets where n is the maximum number of jobs), such that no jobs are present. As a result, all words are zero except words embodying the file structure, date and time of initialisation and checksums (for details see :SPOOL.SPEC). Before writing to the file, the job first checks that the file is big enough to accommodate the specified spool size.
The initial-job must not be used if it is suspected that there are users' jobs on the file which can be removed first. The initial-job clears the file without regard to its previous contents. For the same reason, users' jobs must be prevented from writing data to the file via a graphics package immediately before the initial-job is run. This will require cooperation with the 1906A operators as it may be necessary to run the initial-job in an empty machine.
The initial-job, therefore, is likely to be used only in one of the following situations:
This is situation (1) above. Note that if a fresh file is to be used, by the spooling system, it is not only necessary to run the initial job; the graphics packages must be edited and recompiled and the macro :SPOOL.FR80 should be edited. As an alternative to editing the FR80 macro, the DISC parameter could be used (see Section 4.1) For details of how to run the initialised job see 5.3 below.
Occasionally a job will corrupt the spool. Every graphics job checks the validity of the control buckets and displays to the operators' console, if any bucket is found to be invalid. The message currently says:
FR80 SPOOLFILE IS CORRUPT PLEASE TYPE 'FR80 CP'
If an operator types 'FR80 CP', 2 runjobs are initiated. The first is a LOOK job (see Section 3.4); the purpose is to print out the contents of the control buckets before any recovery is attempted.
The second runjob simulates an 'FR80 ALL'. This will attempt to output every job on the spool (with different tapes for different cameras). In the present version, delayed jobs are not output. Data belonging to a corrupted Job Information Bucket will not be output but the JIB itself will be repaired. If a corrupt JIB - or a corrupt data bucket is the only trouble then, at the end of an 'FR80 CP' run, the spool should be valid. However, if the FCB is corrupted or there is a hardware error, the job will not continue (in the present version).
An operator can do a rough check on whether the spool is still corrupt by running 'FR80 STATE,ALL'. If this gives no problem, the spool should be alright. If 'FR80 CP' does not appear to have solved the problem, more investigation may be necessary. All the operator can do if there is still a fault is put the disc off-line and request that users send data to tape until the problem is sorted out.
The spooling system maintainer can use the listing from the LOOK job (which was initiated by 'FR80 CP') and also the most recent contents of the file STUmmmyy (see Section 3.3) to find out the problem. He will have to decide whether the spoolfile needs to be reinitialised or whether a different spoolfile must be introduced. If a different spoolfile is introduced, changes must be made to software as outlined in Section 5.1.
As already mentioned above (beginning of Section 5), the initial-job is likely only to be needed in one of 3 situations, since it pays no attention to previous contents.
The macro is :SPOOL.PLOT which can be run under :GSIN00 and the first parameter must be INIT. The parameters are:
RJ INITSPOOL, :GSIN00,:SPOOL.PLOT,PARAM(INIT(615,SPOOLGRAPH),DEFAULTS),JD(JT25)
No user context. Initialise the present spool to use the current sizes (number of databuckets 1316, number of jobs 20).
PLOT INIT:PSEUD. SOMEDAFILE, DATABUCKETS40,JOBS5,JT15
Logged in as user :GSIN00 and under directory :SPOOL. Initialise a *DA file (probably for testing purposes) in the filestore.
There are four source files for spooljobs which are as follows:
All these files are held in pseudo-directory :SPOOLF belonging to :GSIN23.
When writing spooljob it was found advantageous to have a macro which would recompile and test the new binary.
In order that the user should not be inconvenienced by bad versions the new binary is held in :SYSBIN.TESTVIEW-BIN whilst the binary in use by spooljob held in :SYSBIN.USERVIEW-BIN.
The macro for regeneration is held in :SPOOLF.NEWVIEW and works in the following way:
The first parameter controls the action to be taken by the macro and has four legal values, the first two characters only being significant. The possible two-character values are RE, TE, NE and OL.
NEWVIEW RE,NOLIST,SMOGTONYMOP,FRAMES1-END,URH,ERASE
will release a job called :GSIN23.NEWSPOOLJOB at urgency M which will Recompile the source files and if successful test the new binary on the output from :GSIN23.SMOGTONYMOP. If NOLIST is not specified then the format would be:
NEWVIEW RE,SMOGTONYMOP,FRAMES1-END,ERASE,URH
If one wishes to test the new binary in :SYSBIN.TESTVIEW-BIN then the first parameter should be:
NEWVIEW TE,SMOGTONYMOP,ERASE,URH
The only other two legal first parameters are:
A list of the necessary files is as follows:
:SPOOLF.TEKT :SPOOLF.FR80ITEM Source files :SPOOLF.PROCESSOR :SPOOLF.MAINSEC :SPOOLF.NEWVIEW Regeneration macro :SYSBIN. USERVIEW-BIN Binary in use by spooljob :SYSBIN.TESTVIEW-BIN New Binary under test :SYSBIN.BINSAFE.USERVIEW-BIN Saved version of old binary
Only one job can write to the spool exofile at one time. Therefore, it is possible for one job to have to wait for another and unfortunately the job that waits does so with a core image. No action is being taken currently since it is not thought to be a serious problem.
If this gets more serious, some analysis may have to be carried out to identify the most frequent cause. The LOGmmmyy files may be useful (Section 3.3). The information in them includes start time, elapsed time and mill time for each job. Another source of information is the System Journal. .JNUTS can be used to print System Journal messages for a selected period (1906A Technical Notice 99). Useful messages are 101, 103, 105, 900 (WAITING FOR FILE TO BE FREE) and 4020 (specially allocated to the FR80 Spool). A program called SPAN in directory :SPOOL will only print occurrences of "WAITING FOR FILE (615,SPOOLGRAPH) TO BE FREE". It does this for a specified period. It will also print an approximate time which JNUTS does not do for this message.
There is more than one possible way cof alleviating this problem. A graphics package could temporarily close a user's spoolarea and reopen it later. A temporary close could be effected either by a subroutine call from the user's program or automatically. The graphics package would only do it automatically if the user has requested this by an initial subroutine call. It is not clear what event could best trigger such an automatic temporary close. Its purpose would be to allow a job to release the spool if extensive computing takes place without graphics output. The state of being temporarily closed would be represented by a new setting of word 30 in the Job Information Block. If a job is temporarily closed, the despooler MUST NOT OUTPUT IT unless it detects that the job is no longer present in the machine.
Another possible method is to use more than one separate spool file. A graphics package can decide which on a random basis. The despooler must search control buckets for all spool files.
If a disc problem occurs (software corruption or hardware error), any graphics jobs which use the spool must either be held up or they fail. A disc hardware error could put the spool out of action for an appreciable time, so ideally each graphics package should divert graphics output to a worktape if any disc problems are encountered before the first record of data is written. This is not done currently, mainly because some reorganisation of the initialising routines would be required. However, a potential problem exists while this is not done.
The despooler can repair a corrupted JIB although the operators' information will be incomplete. However, the despooler will not repair a corrupted FCB.
