RCLOPTS

Purpose

The RCLOPTS statement defines all the options used by HCL Workload Automation for Z during the restart and cleanup functions. It is used only by the controller.

RCLOPTS is defined in the member of the EQQPARM library as specified by the PARM parameter in the JCL EXEC statement.

Note: Because in some cases EQQCLEAN might delete a data set by mistake, it is recommended that you protect critical data sets from deletion by using either the RCLOPTS parameters (DDPROT, DDPRMEM, DSNPROT, DSNPRMEM) or the EQQUXCAT exit.

Format

Parameters

CLNJOBCARD(job card info|ʼOPCʼ)

Defines the Job card to be used by the controller while creating stand-alone cleanup jobs. The default job card is the following:

//jobname JOB ʼOPCʼ

where jobname is built from CLNJOBPX value combining the prefix and a sequential alphanumerical number (for instance EQQCL0005). If you need to change ʼOPCʼ with account information, you can use the CLNJOBCARD keyword that will substitute ʼOPCʼ with the specified value.

It is optional and the default is ʼOPCʼ. The string can be up to 40 characters long.

Do not use it to set the submitter of the stand-alone cleanup job. For that purpose, refer to the RUSER parameter of the job-submit exit.

CLNJOBPX(job name|EQQCL)

Defines the job name prefix to be used for stand alone cleanup.

It is optional and the default is EQQCL.

If specified, it must be five characters long, otherwise the default value is used. In order to track correctly the stand alone cleanup job in a DASD connection, the SU/RE data set must always be defined.

DDALWAYS(DD List)

Defines the list of the DD names that make a step always re-executable. This keyword is optional and valid only for Step Restart; for Job Restart it is ignored.

DDNEVER(DD List)

Defines the list of the DD names that make a step never re-executable. This keyword is optional and valid only for Step Restart; for Job Restart it is ignored.

DDNOREST(DD List)

Defines the list of the DD names that make a step not restartable. This keyword is optional and valid only for Step Restart; for Job Restart it is ignored.

DDPRMEM(member name)

When specified, it contains the name of the partitioned data set member of the parameter library that lists the protected DD names. The syntax in the member is the following:

RCLDDP
DDNAME (list of DD names)

DDPRMEM is mutually exclusive with DDPROT. It can be refreshed using the following MODIFY operator command:

/F procname, PROT(DD=name)

where procname is the HCL Workload Automation for Z JCL procedure name.

DDPROT(DD List)

Defines the list of the DD names that identify the protected data sets. It is optional.

DSNPRMEM (member name)

When specified, it contains the name of the partitioned data set member of the parameter library that lists the protected data set names. The syntax inside the member is the following:

RCLDSNP
DSNAME (list of data set names)

You can use the * (asterisk) as a wild character for partial matching as explained for the DSNPROT keyword. DSNPRMEM is mutually exclusive with DSNPROT. You can refresh the DSN list by changing the DSNPRMEM member name with the following MODIFY operator command:

/F procname, PROT(DS=name)

where procname is the HCL Workload Automation for Z JCL procedure name.

DSNPROT(DSN List)

An optional keyword that defines the list of data set names protected from unintentional deletion. The data sets specified in this list are excluded from the cleanup action list (you will see these data sets marked as X, excluded, in the ISPF panel listing the data sets to be deleted).

You can use the asterisk (*) as a wildcard character for partial matching, provided that you specify it as the last character of the data set name. Any character following the asterisk is ignored. For example, to protect the data set name MYDSN.DATASET and all the GDGs with root MYGDG.ROOT, you can specify the following:

DSNPROT (MYDSN.DATASET,MYGDG.ROOT*)

The result will be that all the GDG data set names MYGDG.ROOT.GnnnnVnn are protected in addition to the data set name MYDSN.DATASET.

If you specify:

DSNPROT (P*.PROD.FILE)

all the files beginning with the letter P are taken into account, regardless of what is specified in the rest of the data set name. It has the same result as if you specify DSNPROT (P*).

DSTCLASS(destination:class)

When you need to have a configuration with the data store subsystem and the tracker with the JCC task active on the same z/OS® system image, there could be compatibility problems if the JCC task options ask HCL Workload Automation for Z to delete the SYSOUT output data sets after the usual analysis. This is because the JCC task might also delete the duplicated SYSOUT copy created for the data store before it has been successfully stored. In this specific configuration, to avoid this problem and to improve the JCC performance that would be scanning the same SYSOUT data sets twice, you need to provide a JES class associated to the tracker destination, to be used for the duplicated copy of the SYSOUT data sets created for data store processing.

The duplicated copy of the SYSOUT will be temporarily added to this class until the data store retrieves, stores, and deletes it. It does not need to be a reserved class: the only mandatory characteristic is that it must not be one of the classes specified in the JCC parameter CHKCLASS. In this way the JCC task will never process the output data sets meant for data store processing.

In a JES3 system, you must define the DSTCLASS as HOLD=EXTWTR and TYPE=PRINT.

You should use the same class for all the trackers and systems, as it is in general easier and less exposed to potential error situations. This suggestion becomes a requirement if the configuration is in a JES MAS complex or if the user specified NJE statements to route the output after the job execution.

The keyword value is specified in pairs; the tracker destination followed by the JES class.

Values of destination and class pairs are specified as in this format:

Dest1:Class1

where Dest1 is the tracker destination as specified in the ROUTOPTS statement and Class1 is the JES class to use for the SYSOUT data sets duplicated for the data store processing. A colon separates destination and class values; a comma separates destination and class pairs. The destinations specified must be consistent with those defined in the ROUTOPTS statement. The tracker destination of 8 asterisks (********) identifies the system where the controller and a local tracker run.

Note: This mechanism will allow JCC and data store to work correctly at the same time but it will not prevent the JCC task from deleting the user SYSOUT of the jobs. So, the user SYSOUT, after being checked by JCC, will not be displayed with the rest of the system sysout.

When the scheduler selects an operation for submission, the DSTCLASS() values are checked to determine if a CLASS= parameter has to be inserted in the output JCL statement that is automatically added to the original JCL. Remember to specify a pair in the ********:X format to obtain the CLASS=X parameter generated for jobs scheduled on the same processor as the controller, that is, on computer workstations with blank destination. For example:

RCLOPTS DSTCLASS(********:Q,TRKRSYS1:Q,TRKRSYS2:Q)

This example specifies a pair list suitable for a two-member JES2 MAS, with a tracker on the same LPAR where the controller runs and another tracker on the other LPAR. The tracker destinations are TRKRSYS1 and TRKRSYS2 respectively. If you omit the first pair, jobs scheduled on workstations with blank destinations will be submitted without CLASS=Q added to the generated output statement.

DSTDEST(OPC destination)

Defines the destination required in the JCL to create a sysout copy for data store. Its value must be equal to the data store SYSDEST parameter of the DSTOPTS statement.

The DSTDEST value should be reserved for the scheduler's use.

If the JES2 DESTDEF statement specifies NODENAME=REQUIRED, then the destination specified in the DSTDEST parameter must be defined as JES2. You can dynamically define it as JES by using the following command:

$ADD DESTID(XXXXXXXX),DEST=XXXXXXXX

where XXXXXXXX is the destination specified in the DSTDEST parameter. If JES2 DESTDEF specifies NODENAME=OPTIONAL, then the destination defined on DSTDEST does not need to be specified.

DSTRMM(YES|NO)

If you specify YES, Removable Media Manager (RMM) activates and the cleanup uses RMM API against tape volumes defined to RMM.

DUMMYLASTSTEP(STEPNAME/'IBM50941')

Use this keyword to allow RESTART and CLEANUP function correct handling of temporary data set when they are referenced with DISP=PASS in the last step of the submitted JCL. The problem is that in this specific situation, RESTART and CLEANUP could suggest to delete the wrong data sets. To avoid this problem, you can use one of the following solutions:

(1) Change the disposition to keep, by setting on trackers: OPCOPTS RCLPASS(YES)
OR
(2) Add a new dummy step as the final step to all jobs submitted by HCL Workload Automation for Z (using this keyword).

Solution (1) results in temporary files being retained and this might eventually cause DAD problems as volumes might be become full since these files are not deleted. Use this solution when EWTROPTS RETCODE(LAST) is used.

Solution (2) can be used if EWTROPTS RETCODE(HIGHEST) is used.

If you specify this keyword, a dummy last step is added to each job submitted by HCL Workload Automation for Z as follows:

// STEPNAME  EXEC PGM=IEFBR14,COND=EVEN

where,

STEPNAME: A string of characters with maximum length of 8. If you leave it blank, the default value, IBM50941, is used.

Note:

No check is performed to determine if a last dummy step already exists with the same name.
If an end of job is found within the JCL, all the JCL lines starting from end of job are commented out except the last dummy step you just added.
No check is performed to determine if the maximum number of steps within the JCL has been reached.
If you have a JCL with this problem:
- If the JCL does not need data set cleanup actions, or the JCL has no DISP=PASS files, add the following line to the JCL to prevent the tailoring and comment it out with the asterisk (*):
```
// EQQJHDMY SKIP
```
  You can add this statement anywhere in the JCL, even after the end of the job, except not inside an INCLUDE member or an external or nest procedure. Ensure that there is only one blank between EQQJHDMY and SKIP.
- If cleanup is needed, consider restructuring the JCL to reduce the number of steps.

GDGSIMAUTO (YES|NO)

This keyword applies only to operations having clean up type automatic. It defines if the GDG simulation process is applied when operations are rerun internally and expanded jcl is not used. For details about the GDG simulation process, see Managing the workload - restart and clean up - GDG resolution. When rerun is started by dialogue, the GDG simulation is done accordingly to the dialogue rules that are:

STEP RESTART: Always applied if expanded jcl is not used
JOB RESTART: Never applied

Note that, when we say that the GDG simulation is applied, it means that whenever needed by the submitted job jcl definitions, the GDG data set is simulated. NO is the default. YES means that we apply the GDG simulation process to all operations having automatic clean up type for internal rerun and that expanded jcl is not used.

IMMEDLOGIC(BESTSTEP|FIRSTSTEP)

Defines the logic for running cleanup actions when an operation ends in error and the cleanup type is Immediate. FIRSTSTEP means that the cleanup actions are performed considering the first step as the starting step. However, if the automatic recovery actions suggest a restart step, this will be considered as the starting step.

BESTSTEP means that the cleanup actions are performed considering the best step as the starting step. However, if the automatic recovery actions suggest a restart step, this will be considered as the starting step. For details about how the best step is determined, refer to Managing the Workload.

Note: If you specify BESTSTEP and rerun a job with Cleanup=Immediate without using the Restart and Cleanup-Step Restart path, the cleanup actions might not be coherent with the step range.

JOBLOGRETRIEVAL(ONERROR|ONDEMAND)

This parameter defines the joblog retrieval policy for operations running on computer automatic workstations producing a z/OS Joblog. The valid values are:

ONDEMAND: The default value. The user must explicitly make a request to retrieve the joblog.
ONERROR: After a job runs and ends in error, the joblog is automatically retrieved and sent. Manual changes to the error do not trigger the retrieval process to start.

RESTARTINFORETRIEVAL(ONERROR|ONDEMAND)

To execute restart and cleanup actions on an operation, such as step restart or data set cleanup, the restart information must be extracted from the job logs. This parameter defines the restart information retrieval policy for operations running on computer automatic workstations producing a z/OS job log.

ONDEMAND: The default value. The restart information retrieval process is started as soon as a restart and cleanup action, which requires the restart information, is either requested specifically by a user, or automatically.
ONERROR: The restart information retrieval process is started when an operation ends in error. Manual changes to the error do not trigger the retrieval process to start.

SKIPINCLUDE(member name)

During the JCL tailoring process, the EQQCLEAN pre-step and the //TIVDSTxx OUTPUT statements are added at the beginning of the JCL before the first EXEC statement. They are inserted also before the INCLUDEs that might precede the first EXEC statement, unless they are featured in the SKIPINCLUDE list. In this case, the insertion of the pre-step and other statements is made after the INCLUDEs listed by this keyword. SKIPINCLUDE states the name of the partitioned data set member of the parameter library containing the list of INCLUDE statements that are to be skipped in the JCL tailoring process.

Consider that the scanning of the JCL to be submitted stops at the first INCLUDE statement that precedes the first EXEC statement, which is not listed in the RCLSKIP INCLNAME() list. Thus, if your JCL has OUTPUT statements with JESDS=ALL, which are placed AFTER an INCLUDE, that INCLUDE must be listed in the INCLNAME() list. The subsequent OUTPUT statement is shown and a superfluous TIVDSTAL OUTPUT statement will not be inserted into the JCL.

You should use SKIPINCLUDE if you have a JCL where the first EXEC is preceded by INCLUDEs that contain JCL statements which cannot be placed after an EXEC statement and that do not contain EXEC statements. Examples of JCL statements that cannot be placed after an EXEC statement are JOBLIB and JOBCAT statements, and OUTPUT statements with the JESDS keyword.

This type of INCLUDEs causes an EQQCLEAN step misplacement if you are using normal JCL (expanded JCL usually does not contain INCLUDEs, unless you intentionally add them before you resubmit the JCL).

You can avoid JCL errors caused by the misplacement of EQQCLEAN by inserting these INCLUDEs in the partitioned data set member defined with SKIPINCLUDE.

If an INCLUDE statement contains both JCL statements, which cannot be placed after an exec statement, and an EXEC statement, it must be split into two separate INCLUDEs.

For example, if an INCLUDE statement contains both JOBLIB and EXEC statements, it must be split into two separate INCLUDEs: one with JOBLIB and one with EXECs.

The syntax that is to be used in the partitioned data set member is described in the RCLSKIP statement section.

To refresh SKIPINCLUDE, enter the following MODIFY operator command:

/F procname,SKIPINC(membername)

where procname is the HCL Workload Automation for Z JCL procedure name.

STEPLIB (dsname)

Defines the name of the data set that has to be over written by the one specified in the //STEPLIB DD card of your EQQCLEAN procedure. This keyword is optional, but if you specify it, you must always define a STEPLIB in your EQQCLEAN procedure, as a DD dummy one. If this parameter is not specified, no change would be made to the EQQCLEAN procedure at all.

STEPRESCHK (NO|YES)

Specifies the possibility to select a step restart range overriding the product logic (for example, a possible restart step could be a non-restartable step). If you specify NO, the product logic check is not performed. The default value is YES. This kind of behavior might lead to JCL errors and it is up to the user to decide when the override is needed.