EWTROPTS

Purpose

The EWTROPTS statement defines run-time options for the event-writer task. EWTROPTS is required when you specify OPCOPTS EWTRTASK(YES). This statement is used by a tracker.

EWTROPTS is defined in the member of the EQQPARM library as specified by the EWTRPARM keyword of the OPCOPTS statement.

Parameters

EWSEQNO(event data set sequence number)

Starts an event writer with an event-reader function, where the tracker has a non-DASD connection with the controller. That is, where the tracker is connected by a VTAM®, XCF, or TCP/IP link or where the event writer is started in the same address space as the controller. You cannot specify EWSEQNO where HOSTCON(DASD) is specified on the TRROPTS statement.

EWSEQNO eliminates the need for a separate event-reader task. The event writer writes job-tracking events to the event data set, and also forwards the events to the task handling communication with the controller. This function can enhance performance because HCL Workload Automation for Z need not write events to the event data set and then read them back again.

If the tracker cannot communicate with the controller, the event writer continues to collect events and writes them to the event data set. When the connection is restored, these events are forwarded to the controller for processing.

Valid values for EWSEQNO are from 1 to 16. If any EVENT READERS is configured to this same started task, then the value specified for EWTROPTS EWSEQNO() must be different from any ERDROPTS ERSEQNO() value for this task. If this task has no ERDROPTS statements, then the EWSEQNO entry serves only as a flag and its actual value is not important.

Note: EWSEQNO is not used to build the event-writer ddname in the tracker JCL procedure, as happens with the ERSEQNO keyword of the ERDROPTS statement for a controller. The ddname is always EQQEVDS.

EWWAIT(wait limit|10)

Defines how long the event writer waits (in seconds) before rechecking the submit/release data set after all records are read. The wait-limit value is used only when SUREL(YES) has been specified.

HOLDJOB(USER|YES|NO)

The HOLDJOB keyword tells the HCL Workload Automation for Z event writer whether it should place jobs in hold status as they enter this system so that they can be released at a later time. This might be necessary if some of your HCL Workload Automation for Z-planned jobs are submitted by a non-HCL Workload Automation for Z process. To prevent such jobs from running before their predecessors are complete, they should be held as they enter the system and then released at the correct time.

Use HOLDJOB(NO) when your HCL Workload Automation for Z-planned jobs are always submitted automatically by HCL Workload Automation for Z. This is the preferred method of running jobs because it is the simplest and involves the least overhead. When you specify HOLDJOB(NO), no jobs are held and released.

Use HOLDJOB(USER) if you have HCL Workload Automation for Z-planned jobs that must be submitted by a non-HCL Workload Automation for Z process. When you specify HOLDJOB(USER), you must place all jobs submitted by non-HCL Workload Automation for Z methods in hold status. This means that all such jobs must have the TYPRUN=HOLD parameter on their job cards. These jobs are then released automatically by HCL Workload Automation for Z, as follows:

• Immediately, if the operation options specify HOLD/RELEASE=NO.
• When normal submit criteria are met, if the options of the operation specify HOLD/RELEASE=YES.

Use HOLDJOB(YES), the least preferred of the three options, only if you have HCL Workload Automation for Z-planned jobs that both:

• Cannot be submitted by HCL Workload Automation for Z.
• Do not have TYPRUN=HOLD specified on their job cards.

When you specify HOLDJOB(YES), the HCL Workload Automation for Z event-writer subtask places all jobs that enter the system in hold status. Some jobs are HCL Workload Automation for Z-planned and cannot run immediately; for example, if predecessors are not complete. The event writer must hold all jobs because it cannot determine whether a particular job is HCL Workload Automation for Z-planned or not. (It does not have access to the HCL Workload Automation for Z current plan.)

For each job that enters the system and is held, the event writer creates an event record. The HCL Workload Automation for Z event manager, which processes all event records, checks the current plan to determine which held jobs are HCL Workload Automation for Z-planned and which are not. Non-HCL Workload Automation for Z jobs are immediately released. HCL Workload Automation for Z-planned jobs remain on hold until their predecessors are complete, when they are automatically released.

The result is that:

• HCL Workload Automation for Z-planned jobs are run in the correct sequence according to the current plan.
• Non-HCL Workload Automation for Z jobs are held by the event writer and then released by the event manager when they are found to be non-HCL Workload Automation for Z jobs.

Note:

1. Starting from z/OS V2.2, you can hold jobs until a specific time by setting HOLDUNTL in the new JCL statement SCHEDULE. If you set both the HOLDUNTL and HOLDJOB(YES) parameters, HOLDUNTL is ignored.
2. HCL Workload Automation for Z does not use VTAM®, XCF, or TCP/IP connections to transmit release commands for non-HCL Workload Automation for Z jobs. If you specify HOLDJOB(YES), release commands for held jobs that are not in the current plan are transmitted through NJE to a tracker system. The tracker must be part of the same NJE network as the controller.
3. If you specify HOLDJOB(USER), this value is valid even if the event writer subtask is not active. For HOLDJOB(YES), the default value NO is used when the event writer subtask is not active.

PRINTEVENTS(NO|ALL|END)

Defines how HCL Workload Automation for Z should create print events (type 4).

Specify NO if you do not intend to track print operations. No print events are created.

Specify ALL if print events should reflect the actual print time of operations. Time that an operation is in status I (interrupted) is not included in the total print time. HCL Workload Automation for Z creates print events when an operation is interrupted and when it has completed.

Specify END if print events should be created when SYSOUT printing has completed. END is the initial default value. Use END if you want to track print operations, but the total time need not reflect the actual print time. That is, the total time will include time that the printer was interrupted.

The initial value of PRINTEVENTS remains in effect until an IPL is performed or until you specify the keyword with a different value.

RETCODE(HIGHEST|LAST)

Defines how the event writer creates a return code for a job or started task for the job-end (3J) event record. If you specify HIGHEST, the event writer creates an event record with the highest return code of all the performed steps.

If you specify LAST, the event writer creates an event record with the return code of the last performed step. In detail:

• If all the steps fail, the operation error code is created from the abend code of the last step that failed.
• If all the steps fail, except for the last one, which flushed, the operation error code is created from the abend code of the first step that failed.

The keyword value is valid until you specify a different value and restart HCL Workload Automation for Z.

Note: The JOBRC keyword can be added in the JCLs. If JOBRC is defined in a JCL with the MAXRC or LASTRC value, the value entered for RETCODE is overwritten by the JOBREC value. If JOBRC is defined with the STEP value, it is ignored, and the value entered for RETCODE is used instead.

SDEPFILTER(startpos,stringvalue)

Defines if and how the scheduler must check the JOB card programmer name, to decide if a step-end event has to be produced. It is useful in particular if you use step-level dependency, to avoid specifying STEPEVENTS(ALL), that might affect the scheduler performance.

It consists of two elements:

startpos

An integer from 1 to 20, which is the maximum length of JOB card programmer name.

stringvalue

A character string with a maximum length of 20 characters.

If the programmer name contains special characters, such as an imbedded apostrophe, when specifying startpos consider the final form of the name and exclude control characters. For example, if the programmer name contains 'T.O''NEILL', specify SDEPFILTER(5,NEILL) to filter by NEILL.

If this keyword is omitted, the scheduler does not check the JOB card programmer name; otherwise the scheduler checks it, by using startpos as the start position from which to look for a match with stringvalue.

If a match is found, the step-end event is always produced, independently from other specified criteria, such as the STEPEVENTS value or EQQUX004 exit parameters.

SKIPDATE(yymmdd|860101)

Defines an upper limit on the age of records in the submit/release data set. The event writer does not use records created before the skip-limit date. The skip-limit date is specified in the format yymmdd, where yy is the year, mm the month, and dd the day. The skip-limit value is used only if you specify SUREL(YES).

SKIPTIME(hhmm|0000)

Defines an upper limit on the age of records in the submit/release data set. The event writer does not use records created before the skip-limit time on the skip-limit date. The skip-limit time-of-day is specified in the format hhmm, where hh is the hour in the range 00 to 23, and mm is the minute in the range 00 to 59. The skip-limit value is used only if you specify SUREL(YES).

STEPEVENTS(ALL|NZERO|ABEND)

The step event option defines how ending job steps are processed by HCL Workload Automation for Z.

If you specify ABEND, a step-end event is created and written to the event data set only for abending job steps.

If you specify ALL, a step-end event is created for all ending job steps. Specify this value only if you use one of the following:

• Automatic job recovery, to detect a flushed step or to restrict the recovery action to a step within a JCL procedure.
• Step-level dependency.

This value might affect the scheduler performance, therefore consider using the SDEPFILTER parameter as an alternative.

If you specify NZERO, a step-end event is created for all job steps that end with a nonzero completion code.

Note: The keyword value is valid until you specify a different value and restart HCL Workload Automation for Z.

STEPINFO(YES|NO)

Specify YES to create all the step events related to the jobs you run, and send them to the primary controller. The default is NO.

SUREL(YES|NO)

Specify YES if a controller submits jobs to this system through a submit/release data set. YES can be specified only if OPCHOST(NO) is also specified in the OPCOPTS statement (for details, see OPCOPTS). The submit/release data set is defined by the EQQSUDS ddname.