BATCHOPT

Purpose

The BATCHOPT statement defines run-time options for HCL Workload Automation for Z batch jobs. BATCHOPT is defined in its own member of the EQQPARM library. The member is referenced by HCL Workload Automation for Z batch jobs at run time.

Parameters

CALENDAR(calendar name|DEFAULT)

Defines the HCL Workload Automation for Z default calendar. You can specify a name, from 1 to 16 characters, referencing a calendar in the calendar database.

The HCL Workload Automation for Z planning functions use this calendar:

• During long-term plan batch processing, to determine run days for an application if no calendar is specified in the application description.
• When extending the current plan, if the specified input parameters indicate that only work days are considered in the extension period.
• During long-term plan processing and Mass Update, to validate that the EVERY options specified for an application run cycle is consistent with the application calendar work day end time.

If no default calendar is specified, or if the specified calendar does not exist in the calendar database, a calendar with the name DEFAULT is used as the default calendar. If no calendar with the name DEFAULT exists, all days are considered work days and the work day end time is set to 00.00.

If the specified calendar does not exist in the calendar database, Mass Update does not check for the EVERY options.

CHECKSUBSYS(YES|NO)

Controls whether the daily planning program checks that it can synchronize with the processing in the controller address space. The synchronization is performed using ENQ locking with scope SYSTEMS. The synchronization can fail because:

• The controller is not started.
• The controller is not executing within the same GRS complex as the daily planning program.
• The SUBSYS keyword does not identify the correct controller.

If NO is specified or defaulted, the last two cases will result in a corrupt status record in the checkpoint file, and the new current plan will not be taken over by the controller. Manual recovery is then required, and the current plan files might be corrupted.

Specify YES for the daily planning program to end if the HCL Workload Automation for Z controller specified by the SUBSYS keyword cannot be reached when daily planning requests the subsystem to prepare for the planning process. When NO is specified or defaulted, the daily planning program continues to process if the controller cannot be reached. Ensure this only occurs because the subsystem is not started.

CKPTREFRESH(YES|NO)

This parameter can be used to refresh the checkpoint data set during a daily plan extend or replan from the old entries that are not "in use" any more.

Note: The default value is NO and the checkpoint data set keeps a record for each remote destination defined in the ROUTOPTS and connected at least once with the Controller. Thus, if you are going to add some new destinations or change some names already defined in the ROUTOPTS statements, it would be advisable to set this parameter to YES at least once, after completing the planned changes. Message EQQN036I can help to determine when the 1000 limit is getting close and suggest that it is time to refresh the checkpoint data set.

CPDATASPACE(YES|NO)

Specify YES for the daily planning program to load portions of the in-storage operations and occurrences into the data space, when building the network of data to simulate the scheduling.

Setting this parameter to YES is particularly helpful when you generate a current plan including more than one million operations, because it optimizes the use of storage. With a CP of this size, you must also:

• Allocate the following data sets as extended VSAM:
  • EQQACPDS
  • EQQCP1DS
  • EQQCP2DS
  • EQQNCPDS
  • EQQSCPDS
• In the batch jobs of the daily plan, allocate the EQQDIN data set with DSNTYPE LARGE.

Note: If the current plan was generated with BATCHOPT CPDATASPACE(YES), the MCPDATASPACE parameter in JTOPTS must also be set to YES.

For more details, see Managing a current plan with more than one million operations.

This setting does not affect the final content of the NCP. When the daily planning program terminates, the data space is deleted.

CRITOPMSGS(NO|YES)

This parameter is used to filter the messages that are issued for operations that are missing the deadline. Specify YES to issue missing deadline messages that refer only to operations with the CRITICAL field set to P or W. Specify NO to issue missing deadline messages that refer to any types of operation. The default is NO.

DATEFORM(date format in reports|YY/MM/DD)

Specifies the date format used in reports. You can specify any combination of century (CC), year (YY), month (MM), and day (DD). CC is optional. You can also use the day number (DDD) from the Julian calendar rather than month and day. The delimiter can be any character other than C, Y, M, or D. However, if you specify CCYYMMDD, in any order, you cannot use delimiters.

DPROUT(daily plan report ddname|SYSPRINT)

Specifies the ddname that HCL Workload Automation for Z uses when producing daily-planning reports.

DYNAMICADD(NO|YES)

DYNAMICADD determines if HCL Workload Automation for Z creates a special resource during planning, if an operation needs a resource that is not defined in the special resource database.

Specify YES if you want HCL Workload Automation for Z to create a resource in the current plan. The special resource database is not updated.

Specify NO if HCL Workload Automation for Z is not to dynamically create a resource. HCL Workload Automation for Z plans the operation as if it does not use the resource.

A dynamically created resource has these values:

Special resource

The name specified by the allocating operation.

Text

Blank.

Specres group ID

Blank.

Hiperbatch

No.

Used for

Both planning and control.

On error

Blank. If an error occurs, HCL Workload Automation for Z uses the value specified in the operation details or, if this field is blank, the value of the ONERROR keyword of RESOPTS.

Default values

The resource has these default values for quantity and availability:

Quantity

The amount specified in the first allocating operation. The quantity is increased if more operations plan to allocate the special resource at the same time. HCL Workload Automation for Z increases the quantity only for dynamically created resources to avoid contention.

Available

Yes.

Intervals

No intervals are created. The default values specify the quantity and availability.

Workstations

The resource has default value *, which means all workstations. Operations on all workstation can allocate the resource.

Also see the DYNAMICADD keyword of RESOPTS in the list of RESOPTS Parameters, which controls the dynamic creation of undefined special resources in the current plan.

HDRS(list of report header lines|blank)

Defines a list of character strings containing report headers. The maximum length of each report header is 120 bytes. The batch job does not use more than three report headers. blank represents a blank line and is the default report header.

If you use the HCL Workload Automation for Z Japanese language feature, you can specify report headers in DBCS format.

IGNOREDEADL(YES|NO)

When setting this keyword to YES, any operation in the current plan will have the deadline forced to the CP tail end date and time, (that is, after the planning end) except operations that are set as critical or suppress-if-late jobs. This implies that their deadlines are completely ignored in the calculation of latest start times. The immediate consequence is that, in a critical network, operations not set as suppress-if-late, will result being late based on the deadline of the critical job. This parameter does not affect occurrence deadlines because automatic setting occurs at operation level.

If you set this parameter to YES, the same behaviour also applies to any dynamic change using modify current plan (that is, dynamic occurrence addition, occurrence modification and so on). To return to the previous behaviour, a new current plan must be created specifying NO or using the default value.

If the deadline is manually anticipated, this causes a recalculation of the latest start time for eligible operations within the occurrence (that is, affected operations and internal predecessors). Eligible operations are ALL the operations, if IGNOREDEADL value is set to NO, and critical jobs and suppress-if-late jobs when IGNOREDEADL is set to YES. For performance reasons, external predecessors are not affected by the deadline change until DP batch runs.

Any attempt to manually change deadlines for non eligible operations is ignored by MCP engine. For operations that have their deadline forced to the CP tail end using the parameter IGNOREDEADL, message EQQM225W will not be issued.

JRUNHISTORY(YES|NO, CONTINUE|STOP)

The JRUNHISTORY parameter contains two keyword values:

• The first keyword value defines whether the daily planning batch process backs up the old current plan on Generation Data Group (GDG) data sets. Specify YES to request the backup, that is necessary to populate the history DB2® tables used by the Dynamic Workload Console reporting feature. Use the default value NO to skip the backup.
• The second keyword value is ignored if you specify NO as first keyword value. It defines whether the daily planning job continues when an error occurs during the backup process:

  CONTINUE

  The daily plan batch job continues and a warning message is issued. The occurrences that were removed from the current plan will not be archived.

  STOP

  The daily plan batch job fails. This is the default.

KEEPCOMPDEPS(NO|YES)

This keyword determines the permanence of external dependencies on a completed operation that belongs to occurrences that are still active when a daily plan job is submitted (either extended or replanned). When a plan is extended or a replan is performed, using this parameter you can maintain dependencies between two operations that belong to different occurrences when the predecessor operation has completed. Normally, the dependency is removed after the run of a plan job, even though the completed operation is still in the plan because it belongs to an active occurrence.

Example: Assume you have Occurrence A with Operation1 and Operation2, and Occurrence B with Operation1 and Operation2, where Operation1, in both occurrences, is the predecessor of Operation2, and where Operation1 (Occurrence A) is also a predecessor of Operation2 (Occurrence B), thereby creating an external dependency. If Operation1 (Occurrence A) completes and Operation2 (Occurrence A) is in error, then Occurrence A is in error status. Assume also that Operation1 (Occurrence B) is waiting for a time dependency. If you now run a daily plan job, both occurrences remain in the new plan, but the external dependency is removed because the predecessor (Operation1 - Occurrence A) is complete. Using the KEEPCOMPDEPS keyword set to YES, the dependency is maintained in the new plan.

Valid values are:

NO

The default. When the plan is extended, external dependencies on a completed operation are removed, even if the occurrence is still active.

YES

When the plan is extended, external dependencies remain defined on the operation. This facilitates a rerun operation because the dependency does not need to be redefined.

LOGID(ID on track log data set|01)

An identification placed in all records on the track log (EQQTROUT). The length is 2 characters. Valid values are in the numeric range from 01 to 99.

If you have specified the EQQTROUT data set in the daily planning JCL, the job-tracking archive data set (EQQJTARC) is copied to EQQTROUT. NCPTROUT and OCPTROUT keywords specify if current plan records are also copied. If more than one controller is active and the same EQQTROUT data set is used to collect job-tracking information, you can use LOGID to differentiate between the logs from the different controllers.

LTPDEPRES(NO|YES)

This keyword is used by the batch job that extends the long-term plan.

Specify YES if changes to HCL Workload Automation for Z databases are reflected in both the extended part of the LTP and the existing part of the plan. The existing part of the LTP is from the time of the end of the current plan to the end of the LTP. Specify NO if only the extended part of the LTP reflects changes to the databases. The existing part of the LTP is not changed when the batch job is run to extend the LTP.

An LTP occurrence that has been modified through the dialogs or PIF is not affected by changes to the databases, even if you specify LTPDEPRES(YES). During extend processing, an old occurrence can be copied from the old LTP to the new LTP for any of the following reasons:

• A predecessor or successor dependency was added manually to the LTP occurrence.
• A dependency was deleted or a dependency was manually changed.
• The occurrence was manually changed in the LTP.
• The occurrence has a successor that is in the current plan.

LTPDEPRES does not affect the removal of completed occurrences from the LTP. Whenever you run a modify or extend batch job, all completed occurrences, whose input arrival precedes the day on which the earliest uncompleted occurrence exists, are removed from the LTP.

For more information about the long-term plan, see Managing the Workload.

LTPREMSHIFT(number of days|0)

Used in the extension of the long-term plan for dependency management. Normally, at each extension the LTP process removes all the occurrences that precede an FNONC (first not completed occurrence). You can use LTPREMSHIFT to keep the occurrences that completed within a certain number of days before the FNONC.

Specify a number from 0 to 7 to define that the occurrences that completed within that number of days before the FNONC be kept through the LTP extension (that is, copied to the renewed LTP and to the new current plan). The parameter becomes effective at the next DP extension.

MAXOCCNUM(nnnnnnn|32767)

HCL Workload Automation for Z maintains an upper limit on the number of occurrences in the current plan. When this limit is exceeded during the extension of the plan or during its creation, the daily planning batch program fails and no new plan is created. If the keyword is omitted, the limit is 32767 occurrences. It is advisable not to set the parameter to a larger number than required by actual workload needs, due to the increased overhead incurred. Occurrences coming from the old plan remain unaffected.

NCPTROUT(NO|YES)

Defines if HCL Workload Automation for Z copies records from the new current plan to the data set referenced by the EQQTROUT ddname in the daily planning process. If you specify NO, tracklog records are not created for the workstation, occurrence, and operation records updated by the daily planning process when a new current plan is created.

The default value, YES, results in the generation of tracklog records for the corresponding new current plan records.

OCPTROUT(YES|CMP|NO)

Defines if HCL Workload Automation for Z copies records from the old current plan to the data set referenced by the EQQTROUT ddname in the daily planning process. If you specify YES, tracklog records are created for old current plan record types 01, 02, 03, and 04. Type 03 records carried through to the new current plan for reporting purposes and for pending predecessor occurrences are not copied to the EQQTROUT file, because these records are copied in a subsequent daily plan.

If you specify CMP, the current-plan record type 03 for completed and deleted occurrences is copied, like type 01 and type 04 records.

The default value, NO, defines that HCL Workload Automation for Z does not copy records from the old current plan to EQQTROUT during the daily planning process.

OPERDALL(Y|N)

This parameter is used by the long-term-planning batch jobs when determining the deadline date for an operation that has a deadline day offset greater than zero, relative to the application input-arrival date.

Y means that HCL Workload Automation for Z considers all days (work and free) when determining the deadline date for the operation. N means that only work days are considered.

The calendar you specified in the application description determines if a day is a work day or a free day. If you did not specify a calendar, the default calendar is used.

Note: OPERDALL does not affect occurrence deadlines.

OPERIALL(Y|N)

This parameter is used by the long-term-planning batch jobs when determining the input-arrival date for an operation that has an input-arrival-day offset greater than zero, relative to the application input-arrival date.

Y means that HCL Workload Automation for Z considers all days (work and free) when determining the input-arrival date for the operation. N means that only work days are considered.

Whether a day is a work day or a free day is determined from the calendar specified in the application description. If no calendar is specified, the default calendar is used.

Note: OPERIALL does not affect occurrence input arrival.

OPIADEP(YES|TIME1NO)

How HCL Workload Automation for Z uses the operation IA date and time:

YES

Operation IA, if specified, is used to determine the matching predecessor. This is the default.

TIME

When the operation is time-dependent, the operation IA, if any, is not used to determine the matching predecessor; the occurrence IA is used instead.

NO

Operation IA is never used to determine the matching predecessor; the occurrence IA is used instead.

When you modify the OPIADEP value, to see the updated date for the dependencies resolution it is required that you run a long-term plan MODIFY ALL.

PAGESIZE(page size for reports|55)

Defines the number of lines per page in reports generated by HCL Workload Automation for Z. You can specify a numeric value from 30 to 500.

PLANHOUR(planning period start|6)

Defines the time-of-day in hours when the daily planning period starts. This value must be the same as the value you specified for PLANSTART on the JTOPTS statement.

PREDWS(default predecessor workstation name)

Defines a default predecessor workstation name that is used by daily planning to create an external dependency when a specific predecessor operation cannot be found. This might occur, for example, if an operation has been deleted or a workstation name has been changed. The highest operation number in the predecessor occurrence with a workstation name that matches the PREDWS definition is set up as the predecessor.

If PREDWS is not specified, or if there is no match on the workstation name, the end point in the predecessor occurrence is used to establish the dependency. If the predecessor occurrence contains multiple end points, the end point with the highest operation number is used. The daily planning generates a warning message to identify the occurrences involved in the dependency.

The workstation name can be specified generically.

PREVRES(NO|YES)

Defines if HCL Workload Automation for Z maintains data and produce reports for the previous 24 hours when a daily planning job is run. The default is to produce reports for the previous planning period.

RCLEANUP (YES NO)

The RCLEANUP value must match the RCLEANUP value in the controller OPCOPTS. It specifies if DP batch must create the CP records containing the list of the operinfo associated to the completed occurrence. The controller later deletes this operinfo when the turnover has completed, if RCLEANUP(YES) is specified in the controller OPCOPTS.

REMDSREC (YES NO)

Controls if the daily planning program ignores and does not carry forward any CP16 data store records that accumulated. Typically, use the value NO (this is also the default). If you need to set this parameter to YES, change it back to NO as soon as possible.

CP16 data store records accumulate in several situations, for example when the RCLEANUP parameter of BATCHOPT and the RCLEANUP parameter of OPCOPTS are set to different values. Usually, these two RCLEANUP parameters are either both set to YES or both set to NO. However, if RCLEANUP(YES) is set in BATCHOPT and RCLEANUP(NO) is set in OPCOPTS, the CP16 records accumulate over the period that RCLEANUP(NO) is specified for the controller task. This occurs because the CP16 records are created by the batch job, but they are never processed or deleted by the controller. Later, when you set RCLEANUP(YES) also for the controller, the controller performance might significantly decrease and return to normal after a long time, or the controller might run out of storage and end with ABEND S878.

When you set REMDSREC=YES, accumulated CP16 records are deleted and message EQQ0548I is issued in the message log.

RETAINBIND(days|7)

After an operation is bound in the current plan, the controller sends notifications with the bind result and with the status of the job bound to the engine that requested the bind. On the controller the request for the bind is stored in a bind request record until the last status change is notified. If a notification cannot be sent, the RETAINBIND keyword specifies how many days the bind request record is to be kept after the instance of the job bound is not included anymore in the current plan. The default value is 7.

RESETSRGLOBAVAIL(ALL|YES|NO|NONE)

By setting this parameter, the daily planning batch job resets the global availability of the special resources in the plan. This parameter has no effect on a trial plan.

Valid values are:

ALL

All the special resources present in the current plan or added by the DP batch job will have the global availability reset to blank when a new CP is created by a daily planning EXTEND or REPLAN.

YES

All the special resources present in the current plan or added by the DP batch job that have the global availability set to Yes, will have the global availability reset to blank when a new CP is created by a daily planning EXTEND or REPLAN.

NO

All the special resources present in the current plan or added by the DP batch job that have the global availability set to No, will have the global availability reset to blank when a new CP is created by a daily planning EXTEND or REPLAN.

NONE

The global availability of the special resources is not reset when a new CP is created by a daily planning EXTEND or REPLAN.

SETSRDEFAULT(resource type,used for)

By setting this parameter, the daily planning batch job sets to NO the default availability of the special resources in the plan. You can also specify a value for the Used for field of the special resources. This parameter has no effect on a trial plan.

Valid values for resource type are:

L

Default. The default availability of the special resources present in the current plan or added by the DP batch job is not changed when a new CP is created by a daily planning EXTEND or REPLAN.

N

All the special resources present in the current plan or added by the DP batch job will have the default availability set to N when a new CP is created by a daily planning EXTEND or REPLAN.

Valid values for used for are:

B

All the special resources present in the current plan or added by the DP batch job will have the Used For field set to Both when a new CP is created by a daily planning EXTEND or REPLAN.

C

All the special resources present in the current plan or added by the DP batch job will have the Used For field set to Control when a new CP is created by a daily planning EXTEND or REPLAN.

L

Default. The Used For field of the special resources present in the current plan or added by the DP batch job is not changed when a new CP is created by a daily planning EXTEND or REPLAN.

N

All the special resources present in the current plan or added by the DP batch job will have the Used For field set to None when a new CP is created by a daily planning EXTEND or REPLAN.

P

All the special resources present in the current plan or added by the DP batch job will have the Used For field set to Plan when a new CP is created by a daily planning EXTEND or REPLAN.

SKIPDYNADDSR(YES NO)

When special resources are dynamically added, but not deleted (DYNAMICDEL is set to NO) the size of the data space continues to increase until the available space is exhausted; the batch job terminates with Abend 01D. To prevent this situation, set this parameter to YES; in this way the daily planning job EXTEND or REPLAN deletes all the special resources that were dynamically added and associated with completed operations.

If you set this parameter to NO (default), the deletion of the dynamically added resources is managed according to the setting of the DYNAMICDEL parameter and the criteria that make the resources eligible for deletion. For more detailed information, see Setting the global values.

SUBSYS(subsystem name|OPCA)

Identifies the name of the controller subsystem for which the batch job is run.

Batch jobs of HCL Workload Automation for Z, for example daily planning or long-term planning, must run on the same system as the controller if global resource serialization (GRS) is not used. If your installation uses GRS, the batch jobs and the controller must run on systems in the same GRS complex.

SMOOTHSUBCONFLEVEL(n)

The multiplying factor to be applied to sigma (variance of latest start time). It is used to avoid that the delay added by SMOOTHSUBDELAY causes the operation to be submitted too close to its latest start time; this applies only to operations that are neither critical nor urgent. This parameter is meaningful when you set SMOOTHSUBMISSION(YES) in JTOPTS.

It can be an integer from 0 to 5. The value 0 means that the variance is not considered, therefore the operation submission might reach its latest start time. A value of 3 means that the operation submission will not exceed the latest start time minus 3*sigma.

This value does not affect the processing of late operations.

SMOOTHSUBDELAY(nnnn)

This value is stored by the DP batch in the current-plan header to make it available to the controller. Based on this setting, the controller adds a random delay to the submission of operations that are neither urgent nor belonging to a critical path.

It is expressed in seconds, in a range between 0 and 9999 (about 2 hours and 46 minute). The default is 0, meaning that no delay is added. A value greater than 0 means that the controller adds a random delay in submitting operations that are neither urgent nor belonging to a critical path, in a range between 1 second and this value. Latest start time is never exceeded, regardless of the value that you specify for this parameter.

SUCCWS(default successor workstation name)

Defines a default successor workstation name that is used by daily planning to create an external dependency when a specific successor operation cannot be found. This might occur, for example, if an operation has been deleted or a workstation name has been changed. The lowest operation number in the successor occurrence with a workstation name that matches the SUCCWS definition is set up as the successor.

If SUCCWS is not specified, or if there is no match on the workstation name, the starting point in the successor occurrence is used to establish the dependency. If the successor occurrence contains multiple start points, the start point with the lowest operation number is used. The daily planning program generates a warning message to identify the occurrences involved in the dependency.

The workstation name can be specified generically.

TIMEDEPCHK(YES|NO)

When setting this keyword to YES, planned start time calculation for operations that are not time-dependent starts from the beginning of the extend or re-plan interval instead of starting from the Input Arrival Time. This affects the Dynamic Critical Path feature (also known as, Workload Service Assurance), as planned start and end times are used to initiate the estimated start and end times that are responsible for the choice of the critical path among all the possible predecessor paths that start from a critical job.

Moreover, if you specify YES, any new entry added to the critical job table coming from a dynamic addition to the current plan (no planned start time) will have the estimated start time set based on the current date and time if the operation is not time dependent, or on Input Arrival Time if the operation is time dependent and the Input Arrival Time is later than the current date. For example, if the Input Arrival Time is 10:00 AM and the current date is 9:00 AM, the current date is used for operations that are not time-dependent , while for time-dependent operations, the Input Arrival Time is used.

The negative or default value (NO) corresponds to the previous behaviour that calculates estimated start times from Input Arrival Times in any case. To return to the previous behaviour, a new current plan must be created specifying NO for this parameter or using the default. When YES is specified and current date and time is used as estimated start time, this value is saved as planned start time in the operation record. The main reason of this choice is given by the need of using it in the recovery scenarios (controller restart).

Consider also that for any value of this parameter, in case of dynamically added operations, estimated start and end times setting does not cause any update in the estimated times of its predecessors and successors in the critical job table. As soon as a new current plan is created, all these times are recalculated without any additional processing effort. This behavior reflects the original design of the feature with the objective of keeping data updated without heavily affecting performances.

VALEACTION(END|WARN|ABEND)

Defines what action a daily planning batch program takes when its validation code detects an inconsistency in the data.

Specify ABEND if an abnormal end must occur (this is the default value). The daily planning job ends with error code S0C1, and a new current plan is not created. Error information is written to the diagnostic data set, EQQDUMP. The characters VALExxxx follow the invalid operation code (X'0000') and identify the module where the error occurred. The system dump produced at the time of the abend will be needed if the error is to be reported as a program defect.

Specify END if the daily planning job must end. Error information is written to the diagnostic data set, EQQDUMP. A new current plan is not created.

Specify WARN if the daily planning job, where possible, must bypass detected errors. Errors are described in messages that are written to the message log and diagnostic information that is written to EQQDUMP. If errors can be bypassed, a new current plan is created. Check the current plan as soon as possible because it might contain errors. For example, a dependency might not have been resolved.