TUMSUTIL - Printout Spool Files Print Utility, COMSPL, Backup And Restore Utility

The batch utility TUMSUTIL provides the following facilities:

  • Print of selected printout spool files on the system printer;

  • Backup of selected printout spool files onto any sequential data set BACKUP;

  • Restore of selected printout spool files from the BACKUP data set into COMSPL;

  • List and additional information of selected printout spool files in the COMSPL on the system printer;

  • List and additional information of selected printout spool files in the BACKUP data set on the system printer.

  • Initialization of COMSPL.

TUMSUTIL can be run in parallel with the Com-plete nucleus for print, backup and list requests (for the restore request there is a restriction). Any printout spool file which is stored in COMSPL according to the data organization of the COMSPL may be processed.

Any printout spool file may be selected using the SYSIN control file. However, in the case of print, backup and restore requests, the request will be terminated for the erroneous part of the printout spool file.


Additional Details of TUMSUTIL Facilities

The list directories on the COMSPL and BACKUP data sets provide the following information:

  • List name

  • Form

  • Disposition

  • Account of lines

  • Account of copies

  • Sender (user ID)

  • Output formatting routine (logical driver)

  • Printer's logical name or its terminal ID

  • Date printout was created

  • Time printout was created

Print of printout spool files from COMSPL: each request is separated by a header page for easy identification of the beginning and end of each printout spool file being printed.

Parameter Input

If the header is not to be printed, PARM="NHDR" must be specified in the TUMSUTIL EXEC statement.

With PARM="SCAN", it is possible to check the syntax of the SYSIN control statements against the syntax description of this document for all requests.

The following table summarizes the TUMSUTIL DD/DLBL/TLBL names:

Note:
It is not possible to restore a backup of a spool file with a record size of "n" to a spool dataset with a record size of less than "n".

DD/DLBL/TLBL Description
SYSLST Listing file for the printing of the TUMSUTIL control statements and messages
z/OS default DCB: None
z/VSE DEVADDR=SYSLST
SYSPRINT/SYS003 Printer file for the printing of the printout spool files
z/OS default DCB: RECFM=FBA,LRECL=133
z/VSE DEVADDR=SYS003
COMSPL COMSPL file
z/OS default DCB: none
SYSIN/SYSIPT Sequential file used for the TUMSUTIL control statements
z/OS default DCB: LRECL=80
z/VSE DEVADDR=SYSIPT
BACKUP Sequential file onto which printout spool files are backed-up.
z/OS default DCB: LRECL=n*,RECFM=FB
z/VSE DEVADDR=SYS002,RECSIZE=n*
RESTORE Sequential file from which printout spool files are restored.
z/OS default DCB: LRECL=n*
z/VSE DEVADDR=SYS001,RECSIZE=n*

* "n" represents the record size of the Com-plete spool data set +4.

How To Use TUMSUTIL

The job control language required to execute TUMSUTIL is illustrated below:

//TUMSUTIL    JOB ...job card information...
//TUMSUTIL    EXEC PGM=TUMSUTIL,
// PARM='SCAN,NHDR'
//STEPLIB  DD  DSN=COM.LOAD,DISP=SHR
//SYSLST   DD  SYSOUT=A,DCB(BLKSIZE=133)
//COMSPL   DD  DSN=COM.SPOOL,DISP=SHR
//BACKUP   DD  DSN=...,DCB=(LRECL=n)
//RESTORE  DD  DSN=...,DCB=(LRECL=n)
//SYSIN    DD  *
   control card input
/*
                             (TUMSUTIL Sample z/VSE Job Control)
* $$ JOB JNM=TUMSUTIL,CLASS=...,DISP=D,LDEST=(,...),PDEST=(,...)
* $$ LST CLASS=...,DISP=D
// JOB TUMSUTIL PO UTILITY
// OPTION     SYSPARM='PARM'
*
*  ***    TLBL or DLBL for RESTORE
*
// DLBL   RESTORE,'...',0,SD
// EXTENT SYS001,...,1,0,...,...
// ASSGN  SYS001,DISK,VOL=...,SHR          ASSIGN FOR RESTORE
*
//        TLBL   RESTORE,'...'
//        ASSGN  SYS001,TAPE,...           ASSIGN FOR RESTORE
*
*  ***    TLBL or DLBL for BACKUP
*
// DLBL   BACKUP,'...',0,SD
// EXTENT SYS002,...,1,0,...,...
// ASSGN  SYS002,DISK,VOL=...,SHR          ASSIGN FOR BACKUP
*
//        TLBL   BACKUP,'...'
//        ASSGN  SYS002,TAPE,...           ASSIGN FOR BACKUP
*
*  ***    ASSGN statement for SYSPRINT
*                  (second printer of the partition or SYSLST)
// ASSGN  SYS003,...                       ASSIGN FOR SYSPRINT
* $$ LST DISP=D,CLASS=A,LST=SYS003
*
*  ***    DLBL for Com-plete SPOOL DATASET
*                  (see Com-plete installation specifications)
// DLBL   COMSPL,'...',,VSAM
*
*
// EXEC TUMSUTIL,PARM='...'
   control card input
/*
/*
/&
* $$ EOJ

A description of the DD/DLBL/TLBL statements is given in the preceding section Parameter Input for TUMSUTIL .

Control Card Input

The control card statements used as input from the SYSIN file select the printout spool files to be processed.

Control statement input is required.

The format of each control statement is:

Command, option(s)

Six commands can be used on the control cards to generate the desired request:

INIT to initialize the Com-plete spool data set.
PRINT to print the printout spool files in the COMSPL that meet the selection criteria specified by the options.
LDIR to print a list of the printout spool files in the COMSPL that meet the selection criteria specified by the options.
B to backup the printout spool files in the COMSPL that meet the selection criteria specified by the options.
LBKP to print a list of the printout spool files in the BACKUP data set that meet the selection criteria specified by the options.
R to restore the printout spool files in the BACKUP data set that meet the selection criteria specified by the options.

Note:
When Com-plete is active without batch support, restore is impossible.

The INIT command is used to initialize a Com-plete spool data set. No options may be supplied with the INIT command, instead the number of records to be written is specified via the RECS keyword on the INIT statement itself for example:

INIT RECS=1500

The RECS keyword should specify the total number of records which can be written to the dataset, this is given by (HI-ALLOC-RBA / CISIZE), these values can be obtained from an IDCAMS list of message dataset after allocation.

During initialization, TUMSUTIL will set all records in the message dataset to zero and write a control record containing information about the dataset. This information contains, for instance, the maximum number of printouts which can be contained in the dataset. This is currently set to be the number of records in the dataset divided by 8.

If it is required to change this value then the MAXPO parameter in the Com-plete sysparms must be changed to the required value and a Com-plete PO and MSG COLD-START performed.

The options for other commands may be specified in any combination except that a list number never appears in a list backup request (see description of LNUM option); also there is a restriction on the date and time option (see description of DAT1/2 and TIM1/2 options).

At least one option must be specified.

The format of the options specified in the TUMSUTIL control statements is illustrated below (default values are underlined):

COMP MULTI, SINGLE
LNAM cccccccc (8 characters)
LNUM nnnnnnnn (8 digits)
FORM cccc (4 characters)
DISP D,L,H, <blank>
SUID cccccccc (8 characters)
LDRV cccccccc (8 characters)
DEST cccccccc (8 characters)
DAT1 dd.mm.yy (European), "from" date
mm/dd/yy (American), "to" date
DAT2 dd.mm.yy (European), "from" date
mm/dd/yy (American), "to" date
Tim1 hh:mm, "from" time
Tim2 hh:mm, "to" time

Description of the Options in Detail

COMP=MULTI, SINGLE

This option is not used for LBKP requests.
"MULTI" indicates that Com-plete is active and "SINGLE" that Com-plete is not active.
Note that if Com-plete is active and has batch support, COMP="MULTI" is mandatory.

LNAM=cccccccc

Selects a specific printout spool file with this list name.
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified.
Note that "cccccccc" is the 1 - 8 byte alphanumerical name that the user assigned to the printout spool file when it was created.

LNUM=nnnnnnnn

Selects a specific printout spool file with this list number.
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified. LNUM is never specified on a list backup request.
Note that "nnnnnnnn" is the 1 - 8 digit number that Com-plete assigned to the printout spool file when it was created.

FORM=cccc

Selects a specific printout spool file with this form name.
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified.
Note that "cccc" is a 1 - 4 byte alphanumerical form name.

DISP=D,L,H, <blank>

Selects a specific printout spool file with this disposition.
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified.
Note that "D,L,H,<blank>" is a 1 byte disposition status, where:

D delete and print
L print and keep
H hold
<blank> not specified
SUID=cccccccc

Selects a specific printout spool file with this sender(ID).
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified.
Note that "cccccccc" is the 1 - 8 byte alphanumerical name that is the Com-plete user ID.

LDRV=cccccccc

Selects a specific printout spool file with this output formatting routine.
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified.
Note that "cccccccc" is the 1 - 8 byte alphanumerical name of the output formatting routine the user assigned to the printout spool file when it was created.

DEST=cccccccc

Selects a specific printout spool file with this logical printer name or terminal ID.
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified.
Note that "cccccccc" is the 1 - 8 byte alphanumerical logical printer name to which the user sent the printout spool file when it was created.

DAT1=dd.mm.yy,mm/dd/yy

Selects a specific printout spool file with exactly this creation date.
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified.
Note that "dd.mm.yy" (or "mm/dd/yy") is the 8 byte alphanumerical date assigned to the printout spool file when it was created.

DAT2=dd.mm.yy,mm/dd/yy

Selects a specific printout spool file with exactly this creation date.
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified.
Note that "dd.mm.yy" (or "mm/dd/yy") is the 8 byte alphanumerical date assigned to the printout spool file when it was created.

If both date options are specified, they no longer describe these dates explicitly: they describe a date interval with DAT1 =/< DAT2.

TIM1=hh:mm

Selects a specific printout spool file with exactly this creation time.
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified.
Note that "hh:mm" is the 5 byte time value assigned to the printout spool file when it was created.

TIM2=hh:mm

Selects a specific printout spool file with exactly this creation time.
If this option is omitted, the printout spool file data will be scanned for records meeting the other selection criteria specified.
Note that "hh:mm" is the 5 byte time value assigned to the printout spool file when it was created.

If both time options are specified, they no longer specify exact times: they describe a time interval with TIM1 =/< TIM2.

Examples

The following examples illustrate how the control statements can be used to select the desired options (printout spool files). To print a specific printout spool file, you may specify:

PRINT,LNAM=NG1

To backup all printout spool files that were sent to printer ="Hugo" on February 29, 1988, specify:

B,DEST=HUGO,DAT1=29.02.88
or:
B,DEST=HUGO,DAT1=02/29/88

To restore all printout spool files that were sent from user ID ="Emma" in the period from January 4, 1988 to February 3, 1988, you may specify:

R,SUID=EMMA,DAT1=04.01.88,DAT2=03.02.88

You may also write the control statements in more than one line:

 R,
      SUID=EMMA,
            DAT1=04.01.88,
DAT2=03.02.88.

TUMSUTIL conventions

The following table summarizes the TUMSUTIL coding conventions.

Feature Convention
SYSIN/SYSIPT Control statements in the format:
command,option(s)
PARM/SYSPARM Format: "SCAN","NHDR"
 
SCAN only perform syntax checking
NHDR no header requested (PRINT request only)
User Exits None
Return Codes
00 Normal completion
08 No core available, I/O error on data set