Introduction

Who Should Read This Guide

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:

  • Application developers
  • Security officers
  • Database administrators
  • System programmers
  • Auditors
  • Supplemental Reading

    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.


    Overview

    Purpose for Spooler

    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:

  • Different message protocols for various devices.
  • Different treatment required for local and remote connected online devices.
  • Interleaving of reports having multiple "pages" in a multi-tasking environment.
  • Lack of control of special forms mounted at the target device.
  • Inability to re-route reports when hardware failures occur.
  • 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.

    Environment

    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.


    Security

    Online Functions

    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:

    TBLADD 252/xxx

    where: xxx               = desired new LOCATION code)

    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.

    Auto-Startup

    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.


    System Files

    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.

    DVC File

    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

    ADD a device

    DVCCHG

    CHanGe a device

    DVCDEL

    DELete a device

    DVCSEE

    SEE a device

    DVCDUP

    DUPlicate a device

    DVCNXT

    see NeXT device

    DVCLOC

    LOCate a device

    DVCSCN

    SCaN device data

    DVCFND

    FiND device data

    DVC File Maintenance

    Online, real-time maintenance is provided for the DVC file using the Device Control Screen shown in Figure 01.

    The Screen Key (SKEY) is where you enter the Terminal ID ( tttt ) for the device you wish to see or update on the file. The terminal ID must be the same as that defined to the TP Monitor for that device. If you enter an asterisk ( * ) into SKEY then MAGEC will default to the terminal ID of the terminal you are at.

    ID is not an enterable field, it displays the Terminal ID on inquiries.

    Location is where you specify the 3-character mnemonic Location code for the location of the device. The Location codes must be defined on MAGEC Lookup Table #252. The location description will display beside the code.

    Buf Size is the hardware buffer size, used to limit the maximum number of bytes of message which can be transmitted to the device. The default is 1920 bytes. You can alter this field.

    Type is the terminal type. Entries of "3286", "3289", etc. designate hardcopy devices. "3270", "3278", etc., designate video devices. You can enter into this field.

    L/R is where you specify whether this is a local (L), remote (R), logical unit (U), or dial-up (D) device. You can enter into this field.

    Desc is an up-to 30-character description of the device being defined. You can alter this here.

    Status is where the system displays, and you can modify, the current status of the device. If the status of a device is BUSY and the operator wishes to alter it to any other status, he must first issue the ** SPLR PAUSE command to that device. Valid statuses are:

    A or AVAILABLE  

    B or BUSY  

    D or DISABLED  

    P or PAUSED  

     

    Form is the mnemonic name (or code) for the paper forms mounted on the device. A blank entry means that this device may accept any report regardless what FORM was specified for it. Blank, therefore, tells MAGEC to ignore FORM matching.

    User Views is where the operator enters Y and N codes to specify which User Views are available to this device. This field is used only by the Security system.

    Active Report is not enterable; it is where MAGEC displays the report number of the report currently being printed at this device. If no report is active then it will show blanks; if one is active it will be a 5-digit numeric report number. On the DVCSEE function, you may press PF6 to automatically transfer to the Report Header Display (RPHSEE) for the report indicated.

    Time Out is the number of minutes which may elapse between transactions from this device before MAGEC will automatically log off the operator, the lesser value between this and the time out from the SIF profile will apply. This field is used only by the Security system.

    Print Classes is where you specify the Print Classes which this device is to service. Valid Classes are A thru Z and 0 thru 9; thus, there are 36 possible Classes. Any combination of Letters and Numbers is valid, the system will automatically sequence them into ascending order and eliminate duplicates.

    Authorized Hours is the range of time (Hours and Minutes) during which this device may be logged on to. This field is used only by the Security system.

    Days indicates, using Y and N codes, the days-of-week during which this device may be logged on to and whether it may be used on Holidays. This field is used only by the Security system.

    MAXIMUM AUTHORIZATION LEVELS BY APPLICATION is an array of up to 50 Authorization Codes (0 - 9) corresponding to the defined LAP's. When an operator logs on to this device, the lesser value (for each LAP) of these and the ones from the operator's SIF profile will apply. This field is used only by the Security system.

    
     DVCxxx tttt
    
      M A G E C DEVICE DEFINITION (CRT/PRINTER)
     ID= tttt
     Location: ___ ( ___________________
    _________________________ ) Buf Size:  _____
     Type: ____ L/R:______ 7-Color(Y/N): _  --TEST--  --PROD--
     Desc: ______________________________ 87654321 87654321
     Status _________  Form: ____  User Views: ________ ________
     Active Report _____  Time Out: ___ min.
     Print Classes: ______________________ SMTWTFSH
    Authorized Hours : __ __ to __ __  Days: ________

     ................MAXIMUM AUTHORIZATION LEVELS BY APPLICATION....................
    G/L (01): _  A/P (02): _






      SPLR(48): 9  SEC.49: 9  PROG(50): 9
    Press PF4 for browse (LOC)SCREEN  Press PF13 for Hardcopy
    Press PF16 for Copy field to buffer  Press PF17 to Paste data from buffer
    Press PF2 for field-level HELP

    Figure 01 --  Device Control Screen

    RPH File

    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

    SEE a report header

    RPHCHG

    CHanGe a report header

    RPHLOC

    LOCate a report header

    RPHLST

    LiST report headers for this LOCATION

    RPHLOC requires a Level 9 authorization.

    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 Maintenance

    Real-time access to Report Header data is provided using the Report Control Screen shown in Figure 02.

    The key value in SKEY is a 4-digit report number.

    Report Number is not enterable, it is where the system displays the Report Number on inquiries.

    Desc is where the report description (up to 30 characters) is displayed, you can alter it here also.

    Origin is where the system displays the terminal-id of the device which originated this report. It is not enterable.

    Location is the 3-character location code to which this report is directed. The value in this field will be validated against MAGEC Lookup Table # 252. You may alter it here.

    Class is the print class of this report, you can alter it here. Any alphabetic or numeric character will be accepted.

    Form is the 4-character form code (or number) on which this report is to be printed. A value of blanks indicates that it may be printed on whatever paper happens to be on the printer.

    Disposition is the report disposition, you may alter it. The report disposition obviously has a significant impact on the actions taken by the Spooler. Valid values are:

    F or FLUSH

    Flush the report to recapture space

    H or HOLD

    Don't print/Don't flush

    D or DELETE

    Print report then flush it

    L or LEAVE

    Same as HOLD

    K or KEEP

    Print then set to LEAVE

    Copies Requested is the number (00 to 99) of copies of this report which are requested. The first time a report is printed is considered "original" and subsequent printings are considered "copies"; thus a value of 99 will result in the report's being printed 100 times, 00 will cause it to print once. You may alter this.

    Copies Printed is not enterable, it is where the system displays the number of times a report has been printed thus far.

    Status is not enterable, it is where the current status of this report is displayed. Possible values are:

    SPOOLING

    In process of being spooled

    DONE

    Done printing, waiting to be flushed

    READY

    Spooled, ready to print

    PRINTING

    Being printed at a device

    PRINTED

    Through printing (at least once), waiting to be reprinted
    or set to DONE status

    FLUSHED

    All resources returned to system, all records released for re-use.

    Printer Trmid is the Terminal ID of the device on which this report is printing or has been printed. Not alterable.

    Number Of Spool Records is not enterable, it is a display of the number of SPL file records used to hold this report.

    First is not enterable, it is the record number of the first SPL file record for this report.

    Next is not enterable, it is the record number of the SPL file record next-in-line to be printed at the device. It can only have a non-zero value while the report is printing.

    Last is not enterable, it is the Record Number of the last SPL file record used to contain this report. Note that SPL file records are not necessarily used in any particular sequence and that it is perfectly normal for the "last" record to be a lower number than the "first" record, or vice-versa.

    Lines of Print is not enterable, it displays the number of lines of print in the report.

    Pages of Print is not enterable, it displays the number of pages of print in the report.

    NOTE:

    
    RPH... rrrr
    

      M A G E C
    TP SPOOLING REPORT CONTROL SCREEN

    REPORT NO rrrr DESC:...................... ORIGIN:....

    LOCATION: ... CLASS: . FORM: .... DISPOSITION: ..........

    COPIES REQUESTED: .. PRINTED ..

    STATUS= ........ PRINTER TRMID ....

    NUMBER OF SPOOL RECORDS ..... FIRST=.....,NEXT=.....,LAST=.....

    LINES OF PRINT=....

    PAGES OF PRINT=....



    Hit PF6 to view the report


    Figure 02 --  Report Control Screen

    SPL File

    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 :

    AVAILABLE  

    IN USE  

    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

    Form Feed

    NL

    New Line

    NULL

    Null (Idle), non-printing "padding"

    Online inquiry into the SPL file is provided via the function codes:

    SPLSEE

    SEE a Spool record

    SPLNXT

    See the NeXT Spool record

    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.

    PF8 will scroll forward a screenful at a time

    PF7 will scroll backward a screenful at a time

    PF20 will scroll forward one line at a time

    PF19 will scroll backward one line at a time

    PF22 will shift left (toward column 1)

    PF23 will shift right (The report data may be as wide as 256 columns)

    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.


    Operator Commands

    **SPLR Function

    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:

    **SPLR

    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

    xxxx               = delay value

                  possible values are:

    SLOW

    MED

    FAST

    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:

    ETRM COMMAND BUSY, TRY AGAIN  

    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.


    How To Spool a Report

    Programming Considerations

    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

    Start a new report. Might be viewed as analogous to the "OPEN" of the print-file.

    SPOOL

    Add a print-line to the spooled report. Might be viewed as analogous to the "WRITE" to the print-file.

    ENDIT

    End the report being spooled. Might be viewed as analogous to the "CLOSE" of the print file.

    ABORT

    Abort the report being spooled. Flushes without printing.

    In order to spool a 100 line report a program would CALL the Spool Subroutine once using the START command, 100 times using the SPOOL command, and once using the ENDIT command.

    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.

    CALLing Spool Subroutine

    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:

    -MAGECINC SPLRQ-C.  

    Batch programs which are to spool reports must include this "copybook" in Working-Storage, preferrably preceeded immediately by an "01" level data-name as:

      01 FILLER.  

    -MAGECINC SPLRQ-C  

    The Spool Request Area

    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.

    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.

    NOTE:

    SPLRQ-C Copybook

    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

    *  *

    *  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).


    A Sample Routine

    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'.


    Link Editing Requirements.

    DOS Batch Programs

    In a DOS environment your batch programs which CALL SPOOLSUB should be link edited as:

    // 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

    In an OS environment your batch programs which CALL SPOOLSUB should be link edited as:

    //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

    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.

    Routing, Re-routing, and Flushing

    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.


    Special Circumstances

    The following recommended actions should be taken under the circumstances described.

    SUPERVISOR NOT RUNNING

    Observe the **SPLR STATUS message for increment in the CYCLES count; if no change in several minutes then the Supervisor is probably not "polling". Enter the following:

    **SPLR HALT  

    **SPLR START  

    Observe the CYCLES again, it should reset to a 1 and commence incrementing.

    SYSTEM CRASH=

    After a TP Monitor "crash" or shutdown the Supervisor may not have been restarted. Follow the instructions for SUPERVISOR NOT RUNNING above.

    SPOOL FILE FULL

    There are three possible actions:

    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.

    In order to do the last option the Spooler's status must be HALTED (on the **SPLR STATUS screen). To achieve this status enter:

    **SPLR START  

    Wait for status to change to RUNNING or SLEEPING, then Enter:

    **SPLR HALT  

    UNWANTED REPORTS ON FILE

    In the event that there are reports on the SPL file, with proper RPH file headers, which are not wanted, enter:

    RPHCHG rrr  

    where: rrr               = report number

    Alter the Disposition to FLUSH. The Supervisor will discard this report on the next cycle and release all its SPL file records for use by other reports.

    INVALID DATA ON FILES

    In the event that there is invalid data noted on the RPH file or SPL file which cannot be properly processed by the Spooler then first enter:

    **SPLR CLEAR  

    Refer to SPOOL FILE FULL above for more instructions on using this command.

    This should restore all the RPH file and SPL file records to "virgin" status; it also FLUSHes all reports which were on the files. If this does not correct the problem, then:

    Restore the files from a recent "backup" or execute ALALDFIL with a control record to select only the SPL and RPH files. Executing ALALDFIL will initialize the files to a "virgin" status. Refer to ALALDFIL in the MAGEC "Offline Utilities" chapter for control card formats and JCL examples.

    This situation should not occur, if it does that would be a strong indication that either:

    1. The Spooler software is or has been flawed.

    2. Someone else has "stepped on" the Spooler's files.

    Call MAGEC Software's support line, if you are not able to correct the problem.

    DEVICE HUNG IN BUSY STATUS

    Occasionally you might find that a device (printer) is left in a status of BUSY (as per the DVCSEE screen), but that it is not actually printing a report. This might be because of a system crash, program abort while printing, or because the printer's status to CICS (or other TP monitor) was altered while it was printing. The MAGEC Spooler might not have sensed the error (especially if it occurred in between blocks of print data) and might have left the status of the printer as BUSY, though printing has actually ceased.

    The first step in correcting this error situation is to issue the command:

    **SPLR PAUSE/dddd  

    where dddd is the device ID. If the printer is actually printing a report when the PAUSE command is issued, then the printing program (which is a part of the MAGEC Spooler system) will sense the PAUSE command and will cease printing and set the device status to PAUSED and set the report's status to HOLD. If the printer was not printing a report, then its status will still remain BUSY, but a "PAUSE PENDING" status will also be set for the device. The DVCSEE display would show both the BUSY status and the PAUSE PENDING message. In that case, you should next do:

    DVCCHG dddd  

    Then change the device status from BUSY to AVAILABLE (or another valid status). The report status, as shown on the RPHSEE screen, should be automatically altered to HOLD when you do this.


    Printing on the System Line Printer

    SPOOLPRT

    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:

    // JOB SPOOLPRT
    // ASSGN SYS007,SYSLST
    // EXEC SPOOLPRT
    /*
    /&

    The OS JCL is:

    //SPOOLPRT JOB acctg-data
    //STEP1 EXEC PGM=SPOOLPRT
    //SYS007 DD SYSOUT=*
    //


    Printing a Screen

    The PRINTS Function

    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:

    PRINTS lll/c  

    where: lll               = LOCATION to route to

    c               = a valid Print CLASS

    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.


    Auto-Start

    Start-Up Options

    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

    Restart the supervisor and restart printing of reports which may have been interrupted by a "crash".

    COLD

    Restart the supervisor.

    CLEAR

    Flush any reports on file and restart the supervisor.

    NONE

    Do nothing.

    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.

    Setting Startup Options

    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:

    1. A control card in the jobstream.  

    2. Via console prompts.
     

    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:

    1. Startup Option (Clear, Cold, Warm, None).  

    2. Report Handling with errors (IGNORE, READY, FLUSH).  

    3. Device Handling with errors (IGNORE, AVAILABLE, DISABLE).  

    Items 2 and 3 apply only for the WARM startup option.

    To execute SPOOLOPT in DOS:

    // JOB SPOOLOPT
    // ASSGN SYS006,SYSIPT
    // DLBL  RPHK1 ..... etc.

    // DLBL  SPLK1 ..... etc.
    // ASSGN SYS007,SYSLST
    // EXEC SPOOLOPT
    - control card, if used
    /*
    /&

    To execute SPOOLOPT in OS:

    //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
    //

    The control card format is:

    Col. 01-09:

    "SPOOLOPT"

    Col. 10-19:

    Startup option

    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.

    Col. 20-29:

    Device-in-error handling option

    IGNORE It will ignore and bypass them.

    READY It will alter them to STATUS=READY, DISPOSITION=LEAVE.

    FLUSH It will flush them.

    Col. 30-39:

    Report-in-error handling option

    IGNORE It will ignore them.

    AVAILABLE It will set STATUS=AVAILABLE.

    DISABLE It will set STATUS=DISABLED.

    The CLEAR Option

    This accomplishes the same as the **SPLR CLEAR online function followed by **SPLR START. It FLUSHes all reports, then initiates the Supervisor.

    The COLD Option

    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.

    The WARM Option

    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:

    FLUSH It will flush them.

    IGNORE It will ignore and bypass them.

    READY It will alter them to STATUS=READY, DISPOSITION=LEAVE.

    The WARM option also checks for errors on the DVC file, such as illogical statuses, etc. They are handled according to the option specified:

    IGNORE It will ignore them.

    DISABLE It will set STATUS=DISABLED.

    AVAILABLE It will set STATUS=AVAILABLE.

    The NONE Option

    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.


    Operator Command Screen

    Figure 03 is an example of the **SPLR screen which permits you to do the dynamic commands to control the Spooler's operation and printing. Depending on your authorization you may be allowed to do all or just some of the commands available.

    
    **SPLR STATUS                          SPOOL FILE IS   .10 PERCENT FULL
    

      + + M A G E C T P S P O O L I N G + +
    ____________________________________________________________
    ____________________
    Date=11/06/89  Time=10 35 47

    ............................$$ SPOOLER COMMANDS $$..............................
    **SPLR START (Activate Supervisor)  **SPLR WAKEUP
    **SPLR HALT (Deactivate Supervisor)  **SPLR ETRM/dddd (Enable)
    **SPLR CLEAR (Clear Spool File) **SPLR DTRM/dddd (Disable)
    **SPLR PAUSE/dddd (Pause Device)  **SPLR ETRM/DQ (DeQueue)
    **SPLR GO/dddd ("Un-Pause" Device)
    **SPLR FLUSH/dddd  (Flush Report @ Device)
    **SPLR BACKUP/dddd/ppp (Backup ppp Pages)
    **SPLR ADVANCE/dddd/ppp (Advance ppp Pages)
    **SPLR RESTART/dddd  (Re-Print From Start)
    **SPLR STATUS  (Display Spooler Status)
    **SPLR DELAY/xxxx (Set SUPV. DELAY)  DDDD = DVC-ID  PPP = NO. PAGES

    TP SPOOLER STATUS = SLEEPING DATE =11/06/89 TIME =09 59 10 CYCLES =  90
    LAST REPORT USED WAS 0000 LOWEST REPORT # IS 0000, HIGHEST REPORT # IS 0001


    Figure 03 --  Operator Command Screen


    Dialing the Phone

    On a PC, your program can dial the phone using the Spooler.

    Requirements

    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:

    MAGEC utilizes the SET command of DOS to designate which COM port your modem is attached to. Modify the TS01.BAT file which is used to invoke MAGEC. Your TS01.BAT file (in the \MAGEC\JCL directory) should include the following statement:

    SET COM=COMn[N]  

    where: COMn               = COM1 thru COM3, appropriately

    Local Calls

    To dial a local number (area code ignored), code the following into your program:

    MOVE 'PHONE' TO SPOOL-REQUEST-AREA.
    MOVE phone-no TO SR-PRINT-LINE.
    MOVE 'LCL' TO SR-LOCATION.
    PERFORM DA400-SPOOL-SUB THRU DA499-EXIT.
     

    where: phone-no               = a phone number in the format (999) 999-9999

    Long Distance Calls

    To dial a long distance number, code the following:

    MOVE 'PHONE' TO SPOOL-REQUEST-AREA.
    MOVE phone-no TO SR-PRINT-LINE.
    MOVE 'L/D' TO SR-LOCATION.
    PERFORM DA400-SPOOL-SUB THRU DA499-EXIT.
     

    where: phone-no               = a phone number in the format (999) 999-9999