SAMGENER — Copying/manipulating sequential files between restarts

SAMGENER is a versatile utility which aids in restartability after ABENDs caused by bad input sequential data or SD37/SB37 conditions on output sequential data. It can also be used to clean up loose ends when a restart will not be attempted by truncating output files at the last checkpoint and copying unprocessed input records to another file for later use.

SAMGENER supports device type switching and/or block size changes by updating the QUICKSTART Checkpoint Datasets with the new positioning information.When this updating needs to occur, SAMGENER looks at the Checkpoint Control Table on your DBMS.

In its simplest form, SAMGENER copies a full output dataset to one with a more generous space allocation. The DDNAME for the SAMGENER input is SYSUT1, the output goes to SYSUT2, and no SYSIN is required. In this form, blocksize changes and device type changes are not allowed.

All other options require the Checkpoint Control Table and the Checkpoint Datasets to be read. The Checkpoint Dataset requires a DDcard with DDName of CKPTSAVE for the “A” dataset and a DDName of CKPTSAVB for the “B” dataset. These should point to the Checkpoint Datasets allocated by QUICKSTART. The names of the datasets are displayed at the top of the ABENDing job's output listing in the QST019I message. The CKPTSAVB DD card is optional and should be provided for additional integrity.

If the Checkpoint Control Table is stored on DB2, a DSNPARMS DD card is needed to tell SAMGENER which DB2 to connect to and which plan to use. See BATCHCAF — DB2 call attach facility interface for details on DSNPARMS, as SAMGENER uses BATCHCAF.

All other options besides simple copying require SYSIN parameters which are described below. The format of the SYSIN cards is free format. Multiple options can be coded on one line, or multiple lines may be used. Only columns 1 through 72 of each SYSIN card will be scanned. The possible SYSIN cards will be described, followed by some examples using each verb.

COPY

This verb will be the first verb for all SYSIN requiring SYSIN processing. All options use as input the SYSUT1 DDcard and output a SYSUT2 dataset for use in restart or rerun.

DD=samddname

This verb specifies the DDName being copied. It is the DDName that the ABENDing program used. SAMGENER uses this to find and update the SAMDEFINITION on the Checkpoint Datasets. This does not refer to a DDName in the SAMGENER JCL.

KEY='20 byte DBMS key'

This verb supplies to SAMGENER the key of the Checkpoint Control Table for the ABENDing program. This key is usually program name + jobname padded with spaces on the end.

EXIT=exitname

This verb specifies a user exit routine to be executed while processing each input file record during the copy process. This is valid only for input sequential files.The exit only gets control on records that have not been processed by the ABENDing application program. That is, all records that have been COMMITted are not subject to alteration by the exit. When the exit receives control, it is passed via the linkage section the data record and a return code field. The record may be analyzed and altered in any way.

The exit routine should set the linkage section return code to 0 if the record should be copied to the output dataset (modified or non-modified). If the return code is set to 04, the record will be written to a DDName of ERRFILE instead of the output file for later processing by the user. If the return code is set to 12, the record is not written to the output file.

If EXIT is COBOL 2, you must use IGZEOPT assembled with RTEREUS=YES.

For LE applications, use LE Runtime option RTEREUS(ON).

COBOL compiler options include the following:

RENT
RES
DATA(24)

Link edit options include the following:

AMODE(24)
RMODE(24)
REUS

A sample exit is in the QUICKSTART SAMPLIB library under the member name of SAMGENXT.

CKPT=nnnnn

This verb is used to override the normal access to the DBMS Checkpoint Control Table to determine the current checkpoint number. The current checkpoint number is very important to choose the proper sequential file positioning information for the copy process. It is important to choose the proper checkpoint number to guarantee synchronization of the DBMS with the sequential files and Working Storage. Only specify this option when the proper checkpoint number is known for sure!

DBMSMOD=accesspgm

This verb supplies the name of a program to SAMGENER which is going to read the DBMS Checkpoint Control Table. The default here is QSRDCKPT. If your shop uses multiple DBMSs or the QUICKSTART installer did not name the access module with this name, this parameter will probably be required.

UNPROCESSED

This verb will copy all records from an input sequential file (SYSUT1) that have not been processed by the batch program. That is, all records after the last checkpoint. If the user exit is specified via the EXIT=parameter, each record will be passed through the exit before being written out.

REREAD

This verb can only be used in conjunction with the UNPROCESSED verb. If specified, will tell SAMGENER that QUICKSTART Transparent Mode was being used and that the beginning of a new LUW was being specified by the application via DB2 COMMITs or via an LUW exit. The application must have used 'DRIVERDD=dddddddd REREAD' in the QSCTRLn DD cards.

This section contains the following topics: