Generating copies for data store

Both the Joblog retrieval and the Restart and cleanup functions require for job output that an "extra" copy of the JESDS spool data sets be generated for processing by the HCL Workload Automation for Z DATASTORE started task on its reserved destination queue. This data is captured into the DATASTORE SDF and UDF data sets (STRUCTURED and UNSTRUCTURED DATA FILES) and used to create restart JCL and determine what catalog cleanup might be required to restart a specific job at the user-selected restart point.

To generate job output copies, the controller automatically adds statements to each JCL before it submits it, for example: 
//TIVDST00 OUTPUT JESDS=ALL,DEST=HWAFDEST                 INSERTED BY HWA
//TIVDSTAL OUTPUT JESDS=ALL                               INSERTED BY HWA
//TIVDSTUS OUTPUT DEST=HWAFDEST                           INSERTED BY HWA
The type and number of statements vary depending on the characteristics of the JCL, for example:
  • If a user SYSOUT is set to YES at the operation level.
  • If the JESDS keyword is already used by the JCL.
  • If a DEFAULT output is defined in the JCL.

The TIVDSTxx OUTPUT JCL statements are inserted into each job as its JCL is prepared for submission by the PRE-SUBMIT subtask in the HCL Workload Automation for Z Controller. Use the EQQUX013 user exit to select the jobs for which you do not need to generate additional copies, because you do not need to retrieve the joblog and use the restart and cleanup function. The EQQUX013 user exit allows the Work Station Analyzer to return an error code that prevents the jobs that are being submitted from being tailored with the //TIVDSTxx OUTPUT statements. For additional details, refer to Customization and Tuning.

The TIVDST00 statement is inserted into ALL scheduled jobs and started tasks. It generates the extra copy of the JESDS=ALL output required by the HCL Workload Automation for Z Data Store.

If the job did not already contain at least one JESDS=ALL OUTPUT statement, and only the TIVDST00 statement was added, that statement would "hi-jack" the one-and-only "normal" copy of the joblog output to the data store destination. So, in this case, the TIVDSTAL statement is added to make sure there are two copies of this output, one for normal processing and a second one for the data store.

The TIVDSTUS statement is added on a job-by-job basis, depending on whether the operation has cleanup option "USER SYSOUT ==> YES". Its purpose is to generate an extra copy of any user-allocated SYSOUT datasets (//xxxxxxxx DD SYSOUT=*) for the DATASTORE to capture and process. USER SYSOUT is not needed for any HCL Workload Automation for Z R&C processing but users might want to be able to browse it through the "L" row command in the HCL Workload Automation for Z dialogs.

Note:
  1. OUTPUT statements with JESDS=ALL must be inserted after the job card, but prior to any EXEC statements. Because an INCLUDE member might contain an EXEC statement, the default processing is for the HCL Workload Automation for Z pre-submit code to stop scanning the JCL for OUTPUT statements when it encounters the first INCLUDE. Thus, if a given job has OUTPUT statements with JESDS=ALL after an INCLUDE, that statement will not be found by HCL Workload Automation for Z and a TIVDSTAL OUTPUT statement will be inserted when it is not needed. This causes an unwanted extra copy of the JESDS=ALL output to be generated.
  2. OUTPUT statements with JESDS=ALL must be inserted AFTER any JOBLIB or JOBCAT statements. So, if a job has INCLUDES which contain these statements, the TIVDSTxx OUTPUT statement is inserted prior to the JOBLIB/JOBCATs, and the job will fail with a JCL ERROR.

Both of the above reported problems are easily resolved.

If the TIVDSTxx OUTPUT statements are to be inserted AFTER an INCLUDE, put the name of the INCLUDE MEMBER in the RCLSKIP INCLNAME() list in the parmlib member pointed to by the CONTROLLER RCLOPTS SKIPINCLUDE() keyword.

Note:

If a specific INCLUDE member contains both JOBLIB and JOBCAT statements and EXEC statements, the TIVDSTxx OUTPUT statement cannot be validly placed either before, or after that INCLUDE. Thus, the INCLUDE must be broken into two or more separate members and the JCL adjusted appropriately in the job to be scheduled and submitted by HCL Workload Automation for Z.

If, on the other hand, you submit a JCL externally to HCL Workload Automation for Z and not from a controller (for example, via ETT with the jobname replacement option set to YES), you need to add similar statements to the JCL yourself. Otherwise, data store cannot archive the output.

The purpose of the //TIVDSTxx cards, that are added by the controller, is only to create extra copies for data store, without altering the behaviour of the previous job. The //TIVDSTxx cards are reserved and customers should not use this type of names.

This automatic copy generation does not work in the following cases:
  • For a user SYSOUT that is defined in expanded procedures. Data store cannot archive this kind of user SYSOUT.
  • For jobs that end in JCL error when the error type prevents JES from processing the JESDS statement. No copies are generated, neither of the MVS™ joblog nor of the user SYSOUT. Data store cannot archive this type of joblog.
Automatic copy generation requires some additional JCL tailoring by the controller in the following cases:
  • When the submitted JCL refers to a started task. The controller adds a JOB card statement, because the JESDS statement works only if the JOB card is present.
  • Whenever the started task is run by only one procedure, adding the JOB card statement is not enough. The controller also adds a step statement that calls the procedure at the end of the JCL. For example, the controller changes the following JCL: 
    //MYSTC PROC
//MYSTC EXEC PGM=IEFBR14
    to: 
    //MYSTC JOB MSGLEVEL=(1,1)
//TIVDST00 OUTPUT JESDS=ALL,DEST=HWAZDEST             INSERTED BY HWA
//TIVDSTAL OUTPUT JESDS=ALL                           INSERTED BY HWA
//MYSTC PROC
//MYSTC EXEC PGM=IEFBR14
//PEND
//TIVDSPRO EXEC MYSTC
    where the reserved destination is HWAZDEST. The statements in bold are added to the JCL.
Note: When the TIVDSPRO step is added to tailor the JCL, the referback of type STARTING does not work. The STARTING referback can be used when the started task invokes procedures having COND statements that point to original started task JCL. For example, the following started task: 
//FRED     PROC 
//S1        EXEC PGM=IEFBR14 
//S2        EXEC XXXSPRO 
// PEND
where XXXSPRO is: 
//XXXSPRO PROC 
//S1 EXEC PGM=IEFBR14,COND=(0,NE,STARTING.S1) 
//PEND
will be tailored before submission as: 
//FRED     JOB MSGLEVEL=(1,1) 
//FRED     PROC 
//S1        EXEC PGM=IEFBR14 
//S2        EXEC XXXSPRO
//PEND 
//TIVDST00 OUTPUT JESDS=ALL,DEST=HWAZDEST                   INSERTED BY HWA
//TIVDSTAL OUTPUT JESDS=ALL                                 INSERTED BY HWA
//TIVDSPRO EXEC FRED
and this will cause the following JCL error: 
10 IEF645I INVALID REFERBACK IN THE COND FIELD
To avoid this type of problem, you should either not use the STARTING referback, or update the JCL by changing STARTING to TIVDSPRO.