JCL requirements for Transparent Mode
To implement Transparent Mode, JCL will need to be modified. QUICKSTART Transparent Mode was designed to be used with the DB2 Call Attach Facility, BATCHCAF, provided with QUICKSTART. To specify the DB2 Subsystem and DB2 Plan names requires either a DSNPARMS DD card or the QSCTRL1 SYSIN cards of DB2= and PLAN=. See The-DSNPARMS-DD-card-for-DB2-users-only.
All QUICKSTART steps require the QSTART DD card from which the dataset high level qualifier is used to build the dynamically allocated datasets that QUICKSTART uses to save Working Storage. Or, as part of QUICKSTART customization, the dataset high level qualifier can be set to a default value so that the DD card is not required. Run the QSMENU CLIST, option CONFIGURE, to see if a default value has been set.
In addition, QUICKSTART modules must be made available to the application (usually via the STEPLIB DD) and output files must have proper dispositions (see JCL requirements and restarting Applications in the main QUICKSTART manual).
Two additional JCL changes are required. The first JCL change alters the PGM= parameter of the JCL EXEC card. Alter this to specify PGM=QSTART. Your application name will be given to QUICKSTART via the QSCTRL1 DD card. Any parms provided on the EXEC card will remain the same.
The second JCL change is the specification of the QSREPT and QSCTRL1 DD cards. The QSREPT is a SYSOUT dataset whose purpose is to provide a simple report showing the options chosen. The QSCTRL1 DD will tell QUICKSTART the name of the main COBOL program and any COBOL subprograms which QUICKSTART is to control. It also can specify which DDs should not be automatically repositioned by QUICKSTART. A good example is a parameter file which only contains one record. If the main program READs this file during the initialization of the application, it would be undesirable to have this file repositioned as the application would return an AT END condition during restart, likely causing another application ABEND.
The QSCTRL1 DD also specifies which external event signals a new LUW, a READ of the driver file or a DB2 COMMIT. If a driver file is chosen, the number of READs which should occur between invocations of CKPTRTN can be specified. This parameter is used when the LUW is very small to minimize checkpoint overhead.
Lastly, the QSCTRL1 DD specifies when QUICKSTART will restore Working Storage during a restart. The four choices are:
- IMMEDIATE—Working Storage should be restored at the very beginning of the Procedure Division of the main program. This option should be used when no onetime Working Storage initialization code is executed.
- FIRST—Working Storage should be restored upon the first READ of the Driver file.
- n—Working Storage should be restored upon the nth READ of the Driver file.
- COMMIT—Working Storage should be restored upon the application’s first DB2 COMMIT.
The QSCTRL1 control cards can be placed in any 80 character parameter member or can be coded in-stream. A parameter member can be generated in TSO by using the QSMENU CLIST. All examples below are shown in-stream for visual ease.
“Before” QUICKSTART example:
//STEP1 EXEC PGM=YOURPROG,PARM=(parm1,parm2,...)
//STEPLIB DD DSN=PROD.LOADLIB,DISP=SHR
//INFILE DD DSN=PROD.INPUT.FILE,DISP=SHR
//OUTFILE DD DSN=PROD.OUTPUT.FILE,DISP=(NEW,CATLG),...
//REPORT DD SYSOUT=*
“After” QUICKSTART example:
//STEP1 EXEC PGM=QSTART,PARM=(parm1,parm2,...)
//STEPLIB DD DSN=QSTART.LOADLIB,DISP=SHR
// DD DSN=PROD.LOADLIB,DISP=SHR
// DD DSN=DSNT.DSNLOAD,DISP=SHR
//INFILE DD DSN=PROD.INPUT.FILE,DISP=SHR
//OUTFILE DD DSN=PROD.OUTPUT.FILE,DISP=(MOD,CATLG,CATLG),...
//REPORT DD SYSOUT=*
//QSTART DD DSN=hlq.ANY.NAME,
// UNIT=SYSDA,SPACE=(TRK,0)
//DSNPARMS DD DSN=hlq.DSN.planname.jobname,
// UNIT=SYSDA,SPACE=(TRK,0)
//QSREPT DD SYSOUT=*
//QSCTRL1 DD *
MAINPROG=YOURPROG
SUBPROG=PRODSUB1
SUBPROG=PRODSUB2
DRIVERDD=INFILE
WSRESTORE=IMMEDIATE
EXCLUDEDD=REPORT
CALLCKPTAFTER=1000
The previous example executes a main program YOURPROG which in turn CALLs two subprograms to be under QUICKSTART’s control, PRODSUB1 and PRODSUB2. The Driver file has a DDName of INFILE. Working storage is to be restored immediately upon restart. The file with DDName REPORT is not to be under QUICKSTART’s control. Lastly, every 1000 READs to INFILE will cause the Checkpoint Routine to be CALLed by QUICKSTART for checkpoint processing.
The QSCTRL1 parameters are defined in the following table:
PARAMETER=value | Description |
|---|---|
MAINPROG=progname | The COBOL main program. This is required and must occur only once |
SUBPROG=progname | A COBOL subprogram to be under QUICKSTART control. Optional. Multiple SUBPROG cards may be coded |
DRIVERDD=ddname or DRIVERDD=ddname | Specifies the DDName of the input sequential file which “drives” the application. If not coded, it is assumed that the applications issues SQL COMMIT statements. This parm is ignored when WSRESTORE=COMMIT is coded. REREAD is optional. If present, specifies that the DRIVERDD file contains a variable number of records in an LUW. Hence the application must first READ the data to detect a new LUW. In this case, the application will notify QUICKSTART of the new LUW by issuing a DB2 COMMIT. If an ABEND occurs in the new LUW, QUICKSTART will re position the file on the first record of the LUW. |
WSRESTORE= | Designates when Working Storage is to be restored during restart. Default is IMMEDIATE. |
WSRESTORE=IMMEDIATE | Restore Working Storage immediately upon restart. Use this when the program does not initialize Working Storage variables that need to be restored. |
WSRESTORE=FIRST or WSRESTORE=n | Restore Working Storage upon first READ of driver file. or Restore Working Storage upon nth READ of driver file. |
WSRESTORE=COMMIT | Restore Working Storage upon first DB2 COMMIT. Use this when a DB2 Cursor drives the application. To use, insert a DB2 COMMIT just prior to the DB2 OPEN Cursor command. (There should also be another DB2 COMMIT at the end of the LUW to cause checkpoints to occur.) The application must be using QUICKSTART's CALL Attach Facility, BATCHCAF. |
EXCLUDEDD=ddname | Specifies DDName of file to ignore for restartability purposes. This parameter is optional. Multiple EXCLUDEDD cards may be specified. |
CALLCKPTAFTER=nnnnnnnn | Specifies the number of READs of the driver file which should be issued between invocations of CKPTRTN. Defaults to 1000. CALLCKPTAFTER=EXIT |
RERUN | Use this card ONLY when a restart is NOT desired. Use of this card will always cause a rerun rather than a restart. |
CKPTRTN=name | Name of Checkpoint Module to be internally invoked. Default is CKPTRTN. Use QSNODBMS for non-DBMS applications or KSDSRTN for VSAM applications. |
ISXRST=name | Name of Module to determine if a restart is to occur. Default is QSISXRST. Use QSISXRNO for non-DBMS applications or KSISXRST for VSAM applications. |
PARM=/parm/ | Parm to be sent to application. Parm must start and end with a delimiter of your choice. |
DB2=ssid | Name of DB2 SubSystem ID to connect to. 1-4 characters. Not valid with QSATTACH. |
PLAN=planname | Name of DB2 plan to open. 1-8 characters. |
SQLIGNORE=nnn | Informs QUICKSTART's DB2 Call Attach not to report errors when this negative SQLCODE (nnn) is encountered. Up to 30 cards may be specified. Do not specify the minus sign when coding this parm. |
TIMEOVER=nnn | Indicates the number of minutes that the QUICKSTART-calculated expected end of the job will be allowed to vary from the norm. For example, a job step that normally runs 40 minutes has been estimated by QUICKSTART to run for 50 minutes. If the TIMEOVER value is specified as 5, the job step will be flagged as LATE. However, if for the same job step with the same estimated run time the TIMEOVER value was set to 15, the job step will be considered ON-TIME. Valid values for this option are 1 to 999. |
PERCENTOVER=nn | Similar to the TIMEOVER option, the PERCENTOVER option indicates, based upon prior run times, the percent variation allowed for the job step’s execution |
OPERACTN=WTO|NDEL | This option indicates, when either the TIMEOVER or PERCENTOVER threshold has been met, the action to be taken. If OPERACTN=WTO, a QST130I message will be issued to the operator. If OPERACTN=NDEL, the same QST130I message will be issued but will be issued as non-deletable to prevent it from rolling off the operator console. In the case of either option, the message will be issued at 5-minute intervals until either the job step falls back under its threshold or the job step ends. If no OPERACTN is specified, the job step will be flagged as running late and its status can be seen on the Active Job ISPF panels using the QSMENU CLIST. |
ABENDAFTER=nnnnnn | To assist in the testing of the restartability of application programs without having to make coding changes, this option can be used to force an intentional ABEND of the program after the indicated number of LUWs are processed. For example, if the Transparent Mode application uses the DRIVERDD to control checkpoint frequency (i.e., define the Logical Unit of Work) and ABENDAFTER=5678, QUICKSTART will force an intentional U2000 ABEND after the 5,678th read of the DRIVERDD. For applications that do not have a DRIVERDD, the ABENDAFTER value identifies the number of SQL statements processed by BATCHCAF, QUICKSTART’s DB2 Call Attach Facility. |
CKPTFREQ=cccc | For applications using QUICKSTART’s Transparent Mode, this value will set the initial checkpoint frequency for the application. The default (unless changed during QUICKSTART installation) is CKPTFREQ=T010. For DB2 applications, this value is used to populate the CKPTCNTL_FREQ column in the Checkpoint Control Table the very first |
Multiple control parms may be coded on one statement, however, there is no continuation of a single parameter across multiple statements. An '*' in column one designates a comment. Only the first MAINPROG or WSRESTORE parm will be honored. No intervening spaces are allowed between the keyword, the equal sign, and the operand. The parameter cards for the QSCTRL1 DD card can be generated by invoking the QSMENU CLIST and selecting option 4. All information needed will be prompted for including an output file name to store the generated card images (80 byte LRECL).
Related topic