This guide is written primarily for use by those persons who will be using the MAGEC TP Spooler software to manage hardcopy output and reports.
Copies of this guide should be distributed to:
This guide is written assuming that the reader is familiar with the overall MAGEC philosophy. It presumes that you understand how the "standard set of nine" functions work and that you are familiar with the standard screen formats of MAGEC. We suggest that you first read the MAGEC Application User's Guide, if you have not already.
The TP Spooler facility gives MAGEC users the ability to "spool" reports from batch and online applications and to print them at the system line printer and/or at online hardcopy devices (IBM 3287, 3268, etc.). The Spooler provides a number of valuable services and facilities and solves several technical problems often encountered when attempting to use online hardcopy devices. Some of the problems solved are:
MAGEC TP SPOOLING allows any number of online tasks and/or batch tasks to spool reports concurrently.
It allows for any number of reports to be concurrently printed at online and system printers.
It allows for any report to be routed or re-routed to any location or to the system printers.
It stores print data in compressed format on its own spool file which never requires re-organization and recaptures freed space automatically.
It allows for report DISPOSITION and FORMS control as well as LOCATION designation. Reports may be specified to print spontaneously or to await operator intervention.
Multiple COPIES of reports may be specified and dynamic operator commands may be used to PAUSE, BACKUP, ADVANCE, or FLUSH reports while printing.
Using the TP Spooling System is no more complicated than writing to a standard print file.
The Spooling System operates only in a MAGEC environment and under the control of the MAGEC Security System.
A major portion of the benefit of the Spooler is that it enforces a discipline over accesses to online hardcopy devices; therefore it is important that all messages and reports directed to those devices be routed using the Spooling system. The Spooler does not prevent you from writing directly to any device from your program; but, doing so could void the benefits of the system.
Reports are stored on the Spool file (SPL file) to await printing. Control information about the reports is stored on the Report Header file (RPH file). A "Spooler Supervisor" routine periodically "polls" those files looking for reports which are ready to be printed and for matching devices on which to print them. To prevent the Spooler Supervisor from monopolizing the resources of your system, a DELAY is inserted at intervals in the "polling sequence". The duration of this DELAY can be dynamically modified via online commands.
Application programs wishing to direct output to online printers do so by building "print lines" (as they would to a line printer) and CALL'ing the system-provided user subroutine (as though they were WRITE'ing to the printer) for each print line. The "Spool Subroutine" compresses the print lines and "blocks" them for storage on the SPL file. A "copybook" is provided for your programs to make it easy to CALL the Spool Subroutine.
The MAGEC Security System controls all online Spooler functions. Refer to the MAGEC "Security" chapter for more information.
All online Spooler functions are defined as being in Logical Application number 48 to the Security System.
MAGEC Lookup Table # 252 defines all LOCATIONS. You can add new definitions using the online function as:
All the TP Spooler online function codes require at least a Level 1 authorization, your installation may specify that they require higher. Some functions require a Level 9. In most cases, operators with less than a Level 9 will only be permitted to access report and device data for their own LOCATION. This provides for isolation of remote LOCATIONs and protection against having one LOCATION view or modify another LOCATION's reports or devices.
Spooler online functions may only be done from terminals which are defined to the MAGEC Device file (DVC) unless you are a Level 9.
If you have a Level-9 authorization for Logical Application 48 you can make any entry from any terminal; but, operators having Level 1 through 8 are usually restricted to their own LOCATIONs. The special privileges for Level 9 operators give Technical Support personnel the capabilities they require from time to time.
We recommend that every LOCATION with hardcopy devices also have at least one video terminal so that they can use the dynamic commands.
An automatic startup feature is available, it automatically restarts the Supervisor "polling" when the TP system is "brought up". It is described later in this chapter.
There are two files provided with the MAGEC TP Spooler. They are the Spool file (SPL) and the Report Header file (RPH). The Spooler also uses the standard MAGEC Device file (DVC) which is part of the MAGEC Security System.
The DVC file contains the defintions for all hardcopy and video terminals on the network. The Security System references the DVC file to determine LOCATION and to provide Terminal-level security control when an operator logs on to MAGEC. The Spooler uses the DVC file to further restrict access to certain Spooler online functions and, for printers, to route reports to the appropriate devices.
You can, if you are properly authorized, see and update the device profiles on the DVC file using the online functions:
DVCADD
DVCCHG
DVCDEL
DVCSEE
DVCDUP
DVCNXT
DVCLOC
DVCSCN
DVCFND
Supplemental Reading
Overview
Purpose for Spooler
Environment
Security
Online Functions
Auto-Startup
System Files
DVC File
DVCxxx tttt |
The RPH file contains control and status information about every spooled report. The file has a maximum capacity of 99,999 Report Header records; thus, the TP Spooling System can accommodate up to that many Spooled reports at any given time. The usual configuration is with 999 Report Header records activated with the remaining numbers held in reserve.
The only key to this file is Report Number. As reports are spooled they are assigned Report Numbers, starting with 001 and incrementing up to the maximum (usually 999) then "wrapping" back to 001. As each new report is STARTed and its number is assigned, the appropriate Report Header record is updated with the parameters specified by the originator program.
This file does not contain spooled print data. That data is on the Spool file (SPL file). The Report Header record "points" to the record on the SPL file where the actual report data begins and also to where it ends.
When a report is "flushed", usually after being printed, the Report Header record is cleared and all the SPL file records associated with the report are "freed" for subsequent use by other reports.
Inquiry, browse, and partial update capabilities are provided via the online function codes:
RPHSEE
RPHCHG
RPHLOC
RPHLST
RPHLST must be done from a device which is defined to the DVC file, even if you are a Level 9.
RPHCHG and RPHSEE must be done from a terminal which is defined to the DVC file unless you are a Level 9. They will only access Report Headers routed to the same LOCATION as the terminal you are at.
RPH File
RPH... rrrr |
The SPL file is where the actual reports are stored. As print lines are spooled (via the Spool Subroutine) they are compressed and "blocked" to conserve space. A "block" (one SPL file record) consists of up to 1,920 characters of report data plus 20 characters of SPL record ID and "chaining" information.
The SPL file consists of a fixed number (usually 15,360) of preinitialized records, plus one control record for maintaining status of the system and each of the SPL file records. The possible statuses for a SPL file record are :
Initially, of course, all of them are AVAILABLE. When a report is spooled it occupies one or more SPL file record(s), these are marked IN USE as thay are used. When that report is flushed, then all the SPL file records which it formerly occupied are marked AVAILABLE once again. They may then be re-used to contain other reports' data.
Any number of SPL file records may be used by a report, they are not necessarily used in any particular sequence. As a report is spooled it obtains (and occupies) SPL records one by one as needed depending on the size of the report. Any number of concurrently active tasks may be spooling at any given time.
SPL records are identified (keyed) by Ordinal Record Number, a numeric value from 00001 through the maximum (usually 15,360).
As each report being spooled needs another SPL record it is given the lowest SPL record which is AVAILABLE. In a multi-tasking environment where records are being used and released by many concurrent tasks this means that the second record (or subsequent records) might very well have a lower number than the first record. In order for the Spooler to be able to "navigate" from the first to the second and so on, a technique of "chaining" is employed. As each SPL record is used for the report it is updated to contain the Record Number of the Prior (last) record and the Next record for this report.
The actual report detail data stored in each SPL file record is compressed (trailing blanks truncated) and contains some special control characters which have meaning to the online printer:
FF
NL
NULL
SPLSEE
SPLNXT
Program Function keys (PF keys) are used to move about within the report you are viewing. The display screen presented contains the Identification and chaining data as well as the actual spooled report detail data, plus PF key instructions.
The SPLSEE/SPLNXT display shows reports approximately as they will appear when printed (if, that is, you decide to actually print them). The major difference is that the amount of data displayed is limited by the width and length of the screen (24 by 80). Therefore, these functions include PF keys to control scrolling up and down and left and right.
After you have viewed a report online, you may wish to flush it from the spool file so that the space taken up by it is recaptured. To do so you would simply use the RPHCHG screen to set its Disposition to FLUSH.
The MAGEC TP Spooling System accepts operator commands to modify its processing via the Spooling Command Screen. The Command Screen is presented whenever the operator enters the function code:
The function code is entered into the standard MAGEC screen field SFUNCT. A Spooler command may be entered into the standard screen field SKEY. Blank in SKEY defaults to the command: STATUS.
The possible commands in SKEY are:
STATUS
Display Spooler system status
HALT
Terminate Supervisor processing
START
Begin Supervisor processing
DELAY/xxxx
Set Supervisor delay
possible values are:
CLEAR
Flush ALL reports, release ALL SPL file records
PAUSE/dddd
Pause printing at device dddd
GO/dddd
Un-pause at device dddd
RESTART/dddd
Restart printing at beginning of report at device dddd
FLUSH/dddd
Flush report printing at device dddd
BACKUP/dddd/ppp
Backup ppp pages at device dddd
WAKEUP
Prod the Spooler Supervisor into RUNNING status
ETRM/DQ
Dequeue ETRM/DTRM command
ETRM/dddd
Enable device dddd
DTRM/dddd
Disable device dddd
ADVANCE/dddd/ppp
Advance ppp pages at device dddd
The Spooler Command Screen always displays a list of the commands and their meanings. It also displays date and time.
Refer to Figure 03 for a sample of the **SPLR STATUS Screen.
The DELAY command only works if the Supervisor is SLEEPING or RUNNING.
Each time the STATUS command is given the system calculates the "percent full" of the Spool file (SPL file) by dividing the number of SPL file records marked as being IN-USE in the control-record by 15,360. The result is displayed on the first line of the screen in the SCOMPL field (MAGEC standard field).
A number of "cycles" is also shown; this is a count of the number of times the Spooler Supervisor has "polled" since being START'ed. Polling consists of the Supervisor's inquiring into the Report Header file (RPH file) to see whether there are any reports to either flush or print; it does NOT USUALLY involve accessing more than a few RPH records, but it MAY involve accessing all of the RPH records under certain circumstances. Observing the rate of change in the cycles counter could provide re-assurance that the Supervisor is actually running (if in doubt) and also could help you determine whether to set the DELAY value higher or lower.
A display of the "lowest report number" and "highest report number" is also shown on the screen. This is to indicate to you the range of report numbers on the RPH file from the lowest report having a status other than FLUSHED to the highest one having a status of other than FLUSHED. This range is the limit of the Supervisor's "polling". The Spooler will use far less system overhead when this range is kept relatively small (under 100, let us say). Periodically flushing obsolete reports which may remain on the Spool file or, better yet, using the **SPLR CLEAR command will help keep overhead down.
The WAKEUP command prods the Spooler Supervisor into the RUNNING Status if it was in SLEEPING Status. The Supervisor will automatically be proded into RUNNING from SLEEPING whenever any DVCADD or DVCCHG or RPHCHG is done, and whenever any report completes printing at an online device. It should never be necessary to use the WAKEUP command since the Supervisor automatically shifts to RUNNING when needed and back to SLEEPING when not needed in order to minimize overhead; the WAKEUP command is provided as a "failsafe" in the event that the Spooler should fail to automatically shift when you think it should have.
The ETRM and DTRM commands are used to Enable and Disable terminals (devices) respectively. Only one DTRM or ETRM request can be processed at any one time; if one is in process and you request another you will receive the message:
This means that the ETRM or DTRM facility has been "Enqueued" by a prior request. When the prior request is completely processed it will "Dequeue" the facility. The DQ option of the ETRM/DTRM commands forces the facility to Dequeue; it should be used only when necessary.
A Level 9 operator may do all the **SPLR commands and may do them at any device (where appropriate). Operators having less than Level 9 authorization are not allowed to do the DELAY, HALT, START, and CLEAR commands at all.
Operators having less than Level 9 may only do **SPLR from a terminal defined to the DVC file and may only affect reports or devices at their own LOCATION.
The programming required to spool reports is actually quite simple and straight-forward. All spooling requests are done using the Spool Subroutine which is provided with the system.
There are only four commands which the user program may make to the Spool Subroutine.
START
SPOOL
ENDIT
ABORT
The ABORT command could be used at any time if the program detected that something was wrong and the report being spooled should be discarded.
Programs (or MMP's) may spool more than one report but must do so serially. They must end one before starting the next.
There are three versions of the Spool Subroutine installed, a batch version, a version for MMP's, and an online version for non-MAGEC programs. They do exactly the same thing, only in different environments.
A "copybook" is provided for use by your Applications programs and MMP's to define the communications area for the subroutine. The name of the "copybook" is SPLRQ-C.
Online MMP's which are to spool reports must include this "copybook" into the DATADEF or VARSTOR portion of the Linkage Section by coding:
Batch programs which are to spool reports must include this "copybook" in Working-Storage, preferrably preceeded immediately by an "01" level data-name as:
The following exhibit shows the SPOOL-REQUEST-AREA as defined by the SPLRQ-C "copybook".
The SPOOL-REQUEST-AREA is always passed as a parameter to the Spool Subroutine. It must be filled in correctly.
NOTE:
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* MAGEC TP SPOOLING REQUEST AREAS. *
* *
* 52-BYTE REQUEST PARAMETER AREA FOLLOWED BY *
* 132-BYTE PRINT-LINE AREA. *
* *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
03 SPOOL-REQUEST-AREA.
05 SR-CMD PIC X(05).
88 SR-START-CMD VALUE 'START'.
88 SR-END-CMD VALUE 'ENDIT'.
88 SR-SPOOL-CMD VALUE 'SPOOL'.
88 SR-ABORT-CMD VALUE 'ABORT'.
05 SR-DESC PIC X(30).
05 SR-LOCATION PIC X(03).
05 SR-CLASS.
07 SR-CLASS-N PIC 9(01).
05 SR-DISPOSITION PIC X(01).
88 SR-FLUSH VALUE 'F'.
88 SR-HOLD VALUE 'H'.
88 SR-DELETE VALUE 'D'.
88 SR-LEAVE VALUE 'L'.
88 SR-KEEP VALUE 'K'.
05 SR-FORM PIC X(04).
05 SR-COPIES-X.
07 SR-COPIES PIC 9(02).
05 SR-REPORT-NO.
07 SR-REPORT-NO-N PIC 9(04).
05 SR-RET-COD PIC X(01).
88 SR-OK VALUE SPACE.
88 SR-BAD-REQUEST VALUE 'B'.
88 SR-RPT-NOT-STARTED VALUE 'S'.
88 SR-SPL-FILE-FULL VALUE 'F'.
88 SR-IO-ERROR VALUE 'I'.
88 SR-BAD-LOCATION VALUE 'L'.
88 SR-BAD-CLASS VALUE 'C'.
88 SR-BAD-DISPOSITION VALUE 'D'.
88 SR-BAD-NR-COPIES VALUE 'N'.
88 SR-INTERNAL-ERROR VALUE 'E'.
05 SR-NEW-PAGE PIC X(01).
88 SR-NEW-PAGE-NUMBER VALUE '0' THRU '9'.
88 SR-WRITE-AFTER-TOP VALUE 'T' '0'.
88 SR-WRITE-AFTER-1 VALUE '1'.
88 SR-WRITE-AFTER-2 VALUE '2'.
88 SR-WRITE-AFTER-3 VALUE '3'.
88 SR-WRITE-AFTER-4 VALUE '4'.
88 SR-WRITE-AFTER-5 VALUE '5'.
88 SR-WRITE-AFTER-6 VALUE '6'.
88 SR-WRITE-AFTER-7 VALUE '7'.
88 SR-WRITE-AFTER-8 VALUE '8'.
88 SR-WRITE-AFTER-9 VALUE '9'.
05 SR-PRINT-LINE.
07 SR-BYTE OCCURS 132 TIMES
PIC X(01).
The following exhibit is a sample of the COBOL code to use the Spool Subroutine to spool a report. The routine is identical in batch or online programs with the exception of the single difference noted.
Code shown in uppercase is real COBOL code while that in lowercase is symbolic and must be replaced with appropriate real code.
* START A NEW REPORT
MOVE 'START' TO SR-CMD.
MOVE SPACE TO SR-RET-COD.
MOVE location TO SR-LOCATION.
MOVE description TO SR-DESC.
MOVE class TO SR-CLASS.
MOVE disposition TO SR-DISPOSITION.
MOVE form TO SR-FORM.
MOVE 00 TO SR-COPIES.
MOVE 0 TO line-ctr.
PERFORM DA400-SPOOL-SUB THRU DA499-EXIT.
* SPOOL A PRINT-LINE
XX900-SPOOL.
ADD 1 TO line-ctr.
IF line-ctr GREATER THAN 50
MOVE 'T' TO SR-NEW-PAGE
MOVE 00 TO line-ctr.
MOVE print-line TO SR-PRINT-LINE.
MOVE 'SPOOL' TO SR CMD.
PERFORM DA400-SPOOL-SUB THRU DA499-EXIT.
.
.
.
IF end-of-data
GO TO XX980-ENDIT.
GO TO XX900-SPOOL.
* END THE REPORT
XX980-ENDIT.
MOVE 'ENDIT' TO SR-CMD.
PERFORM DA400-SPOOL-SUB THRU DA499-EXIT.
.
.
The routine performed to actually CALL the Spool Subroutine in an online MMP is:
* CALL SPOOL SUB-ROUTINE (online programs)
DA400-SPOOL-SUB.
-MAGECINC &MON31
IF (NOT SR-OK)
Take error handling action.
DA499-EXIT.
EXIT.
The routine performed to actually call the Spool Subroutine in a batch program is :
* CALL SPOOL SUB-ROUTINE (batch programs)
DA400-SPOOL-SUB.
CALL 'SPOOLSUB' USING SPOOL-REQUEST-AREA.
IF (NOT SR-OK)
take error handling action.
DA499-EXIT.
EXIT.
NOTE:
PROCEDURE DIVISION.
ENTRY 'BEGIN'.
PROCEDURE DIVISION.
ENTRY 'DBMSCBL'.
In a DOS environment your batch programs which CALL SPOOLSUB should be link edited as:
In an OS environment your batch programs which CALL SPOOLSUB should be link edited as:
This section describes the conditions which the MAGEC TP Spooler looks for in order to assign a given report to a given device.
Spooled reports are directed to a Location, a Print Class within the Location, and a Form Code; they are not directed to a particular hardware device. The Supervisor routine "polls" the RPH file periodically seeking reports which are ready to be flushed or printed. Those to be flushed are handled immediately in order to re-capture file space on the SPL file.
A report is considered ready to be printed when the Supervisor detects that its Disposition is either DELETE or KEEP and its Status is READY. For those reports it then begins searching for a device on which to print.
The LOCATION code of the device must match the LOCATION code for the report, and the device must have a status of AVAILABLE.
The Form Code on the device record must match the Form Code on the Report Header record or either one must be blank. A blank Form Code on the device record indicates that this device will accept reports without regard for the Form specified; a blank Form Code on the Report Header indicates that the report is to be printed at a device without regard for the Form mounted.
The PRINT CLASS of the report (from the RPH record) must match one of the PRINT CLASS's being serviced by the device (from the DVC record).
The Spooling Supervisor will attempt to find a "match" among all the devices at the proper LOCATION, failing that it will bypass that report until the next "cycle". The time DELAY between cycles is variable and may be somewhat controlled by the **SPLR DELAY command; however, competition for system resources with other tasks currently running in the computer could cause noticeable variance from one time to another.
If you understand how the Spooler determines which printer to assign to a report then you will be able to effectively route reports that you spool from your programs and you will also be able to re-route them using the online functions of the Spooler. You can alter the parameters specified on the DVC file for the printers and on the RPH file for the reports. You can use the **SPLR commands to dynamically interrupt and alter the printing of reports and to initiate and halt the Supervisor.
After a report has been printed the requested number of times, controlled by the NUMBER OF COPIES REQUESTED, its Disposition is automatically altered. If the Disposition was DELETE then it is changed to FLUSH; if it was KEEP then it is changed to LEAVE. The FLUSH Disposition will direct the Spooling Supervisor to flush the report and to release all its SPL file records so as to make them AVAILABLE to be used for future spooled reports. The LEAVE Disposition will direct the Supervisor to allow the report to remain on the SPL file for possible subsequent printing of additional copies.
The following recommended actions should be taken under the circumstances described.
SUPERVISOR NOT RUNNING
SYSTEM CRASH=
SPOOL FILE FULL
UNWANTED REPORTS ON FILE
INVALID DATA ON FILES
DEVICE HUNG IN BUSY STATUS
A batch utility program is provided to allow spooled reports to be printed on the system line printer(s) which are usually located in the computer room. No special considerations need be made when spooling reports; in fact, the same report may be printed at an online hardcopy device and/or at the system line printer. A report may be spooled with a Disposition of KEEP and printed on one device then re-printed at another regardless of what type devices they are.
A special Location Code of SYS is reserved for the System Printers. The batch utility program scans the Spooler's files looking for reports routed to the Location of SYS which are READY to print. The name of the batch utility is SPOOLPRT.
Each execution of SPOOLPRT will find all the reports which are for Location SYS, are READY to print, and have Dispositions of KEEP or DELETE. All such reports are printed on the line printer and their Dispositions are altered according to the same rules as if they were printed to an online device.
If there are no reports to be printed then SPOOLPRT simply goes to end-of-job; therefore it is acceptable to execute SPOOLPRT whenever you suspect that there may be reports to be printed.
The DOS JCL to execute it is:
The OS JCL is:
The Spooler includes a facility to allow you to "print" the contents of any MAGEC application's screen. The facility simply creates a "report" consisting of the screen image, including any data being displayed, and spools it by CALLing the Spool Subroutine just as your MMP's do. The screen image may be routed to any LOCATION, including SYS (which prints on the computer room line printer).
To print a screen you must first enter the appropriate function and key value to bring up the desired screen; then, on the top line of the screen (the Command Line) you enter:
The generated "report" will be routed to the LOCATION and CLASS you have specified. If you omit the "lll/c" then MAGEC will default to the LOCATION of the terminal you are at and the first (lowest) print CLASS specified on your terminal's DVC file definition. If your terminal is not defined on the DVC file then MAGEC will default to the LOCATION=SYS and CLASS=P for lack of anything better.
The values of SFUNCT and SKEY will be restored to what they were before you typed in the PRINTS command. If you overtype any screen data when you enter the PRINTS command then it will be printed as it appears on the screen, with your overtyped modifications.
After generating the spooled screen image report, MAGEC will place a message in the SCOMPL screen field on the top line of your screen to tell you the Report Number and routing generated.
Standard generated MMP's utilize exactly this function when you press the (PF13) hardcopy key from a "maintenance" screen (as opposed to the "browse" screens used by the LOC, SCN, and FND functions). The MMP's simply do a fetch to the PRINTS function (FTHFUNCT). You can accomplish the same results by typing in the PRINTS command at any time.
The MAGEC Spooler includes an Automatic Startup feature which can be used to initiate the Supervisor's "polling" and to reset error conditions at the time that your TP Monitor is initiated. This eliminates the need to remember to manually START the Supervisor via the **SPLR screen whenever the Monitor is brought down and back up, whether by intent or as a result of a "crash".
The Auto Startup feature has four possible startup options:
WARM
COLD
CLEAR
NONE
The Auto Startup routine is invoked whenever the Monitor is initiated. The normal procedure should be to invoke the WARM option, the others are for exceptional cases. WARM-start has several variations controlled by other parameters you specify. It can "clean up" the SPL file and RPH file and dispose of erroneous reports to minimize the need for manual handling. It can also advise the console operator of situations which might indicate a problem, such as a report which was in process of spooling when the system "crashed", etc.
The Startup options are stored on a special control record which is on the RPH file. A batch utility program is used to set the desired values into the control record. Some users insert an execution of this batch program into the Monitor startup deck so that they can alter the options at the time they initiate the Monitor, other users prefer to leave it as a separate stand-alone job. The program is named SPOOLOPT.
You can tell SPOOLOPT what options you wish set in either of two ways:
If there is a control card present then SPOOLOPT will accept it and set the options accordingly and will not prompt the console operator. There are three parameters which are set:
Items 2 and 3 apply only for the WARM startup option.
To execute SPOOLOPT in DOS:
To execute SPOOLOPT in OS:
The control card format is:
Col. 01-09:
"SPOOLOPT"
Col. 10-19:
Startup option
Col. 20-29:
Device-in-error handling option
Col. 30-39:
Report-in-error handling option
This accomplishes the same as the
**SPLR CLEAR
online function followed by
**SPLR START.
It FLUSHes all reports, then initiates the Supervisor.
This does exactly the same thing as the
**SPLR START
online function. It initiates the Supervisor "polling" without trying to clean up any errors which might exist.
This option initiates the Supervisor after first scanning the files for errors and for reports which were in process of PRINTING when the system was brought down (intentionally or otherwise). It resumes the printing of reports similar to the
**SPLR GO
function. If errors are found on the RPH records they will be handled according to the report handling option specified:
The WARM option also checks for errors on the DVC file, such as illogical statuses, etc. They are handled according to the option specified:
This option sets the Supervisor's STATUS (as on the **SPLR STATUS screen) to HALTED in preparation for manual initiation using the
**SPLR START
command. It takes no other action.
SPL File
AVAILABLE
IN USE
Operator Commands
**SPLR Function
SLOW
MED
FAST
ETRM COMMAND BUSY, TRY AGAIN
How To Spool a Report
Programming Considerations
CALLing Spool Subroutine
-MAGECINC SPLRQ-C.
01 FILLER.
-MAGECINC SPLRQ-C
The Spool Request Area
SR-CMD
Must always contain a valid command.
SR-DESC
Report description, used only for START command.
SR-LOCATION
Location report is to be reouted to, used only on START command.
SR-CLASS
Report Class, used only on START command.
SR-DISPOSITION
Disposition, used only on START command.
SR-FORM
Form Code (or blanks), used only on START.
SR-COPIES
Number of copies, used on START command. Blank defaults to 00.
SR-REPORT-NO
Report Number, Spool-Sub fills it in on START command - DO NOT MODIFY.
SR-RET-COD
Return code from Spool Subroutine to caller, should be tested after each CALL.
SR-NEW-PAGE
Print Control Code. Set by the calling application report program prior to each SPOOL command. The Spool Subroutine resets this to '1' every time it is called. A value of 'T' or '0' causes the print line to be written "after top of page". A value of '1' or Space causes it to be written "after advancing 1 line". Values of '2' through '9' cause it be be written "after advancing 2 lines" through "9 lines" respectively.
SR-PRINT-LINE
Actual print line to be spooled. Filled in by calling application report program only on SPOOL commands.
SPLRQ-C Copybook
A Sample Routine
Link Editing Requirements.
DOS Batch Programs
// OPTION CATAL
PHASE ........,*
INCLUDE file-table (if Datacom/DB files are accessed)
INCLUDE DATACOB
INCLUDE SPOOLSUB
// EXEC FCOBOL
/*
ENTRY BEGINS (if using Datacom/DB)
ENTRY BEGIN (if not using Datacom/DB)
// EXEC LNKEDT
/*
/&
OS Batch Programs
//LKED EXEC PGM=IEWL,.....
//SYSLIB DD ....
//SYSLMOD DD ....
//SYSLIN DD *
INCLUDE SYSLMOD (filetable) if Datacom/DB used
INCLUDE SYSLMOD(DATACOB)
INCLUDE SYSLMOD(SPOOLSUB)
ENTRY BEGIN if not using Datacom/DB
ENTRY BEGINS if Datacom/DB used
NAME ........(R)
/*
//
Routing Logic
How Reports are Matched to Printers
Routing, Re-routing, and Flushing
Special Circumstances
**SPLR HALT
**SPLR START
1. Don't spool any more reports.
2. Print and/or flush some of the reports now on the Spool file.
3. Use the **SPLR CLEAR command to flush ALL spooled reports
and release ALL SPL file records.
**SPLR START
**SPLR HALT
RPHCHG rrr
**SPLR CLEAR
1. The Spooler software is or has been flawed.
2. Someone else has "stepped on" the Spooler's files.
**SPLR PAUSE/dddd
DVCCHG dddd
Printing on the System Line Printer
SPOOLPRT
// JOB SPOOLPRT
// ASSGN SYS007,SYSLST
// EXEC SPOOLPRT
/*
/&
//SPOOLPRT JOB acctg-data
//STEP1 EXEC PGM=SPOOLPRT
//SYS007 DD SYSOUT=*
//
Printing a Screen
The PRINTS Function
PRINTS lll/c
Auto-Start
Start-Up Options
Setting Startup Options
1. A control card in the jobstream.
2. Via console prompts.
1. Startup Option (Clear, Cold, Warm, None).
2. Report Handling with errors (IGNORE, READY, FLUSH).
3. Device Handling with errors (IGNORE, AVAILABLE, DISABLE).
// JOB SPOOLOPT
// ASSGN SYS006,SYSIPT
// DLBL RPHK1 ..... etc.
// DLBL SPLK1 ..... etc.
// ASSGN SYS007,SYSLST
// EXEC SPOOLOPT
- control card, if used
/*
/&
//SPOOLOPT JOB acctg-data
//STEP1 EXEC PGM=SPOOLOPT
//RPHK1 DD DSN=MAGEC.RPH.CLUSTER.... etc.
//SPLK1 DD DSN=MAGEC.SPL.CLUSTER.... etc
//SYS007 DD SYSOUT=*
//SYS006 DD *
- control card, if used
//
CLEAR
Flushes all reports, then initiates the Supervisor.
COLD
Initiates the Supervisor polling without regard to errors.
WARM
Initiates the Supervisor, first scanning for errors and for reports which were being printed when the system was brought down.
NONE
Sets the Supervisor's Status to HALTED.
IGNORE
It will ignore and bypass them.
READY
It will alter them to STATUS=READY, DISPOSITION=LEAVE.
FLUSH
It will flush them.
IGNORE
It will ignore them.
AVAILABLE
It will set STATUS=AVAILABLE.
DISABLE
It will set STATUS=DISABLED.
The CLEAR Option
The COLD Option
The WARM Option
FLUSH
It will flush them.
IGNORE
It will ignore and bypass them.
READY
It will alter them to STATUS=READY, DISPOSITION=LEAVE.
IGNORE
It will ignore them.
DISABLE
It will set STATUS=DISABLED.
AVAILABLE
It will set STATUS=AVAILABLE.
The NONE Option
**SPLR STATUS SPOOL FILE IS .10 PERCENT FULL |
On a PC, your program can dial the phone using the Spooler.
1. You must have a Hayes
compatible modem attached.
2. The phone number is in the format (999) 999-9999.
3. You must set the definition of the serial port for MAGEC, as follows:
Dialing the Phone
Requirements
SET COM=COMn[N]