Interface to the exit

The operation-initiation exit is invoked in task mode, problem state, and key 8 and the job-step task is APF-authorized. The active task runs with the same access authority as the job-step task. The exit must restore this state before returning to its caller.

Control is passed to the exit using the BAL instruction. The exit must return to its caller using the address and addressing mode passed to it in general register 14.

The exit is entered in AMODE 31 but must switch to AMODE 24 before performing any input or output operations, and then switch back to AMODE 31 before returning to the caller.

If the exit abends, it is flagged as not executable; Tivoli Workload Scheduler for z/OS does not try to call the exit again.

When the exit is entered, register 1 contains the address of the parameter list. Each address in this list is used to locate the parameter value. These parameters are passed to the exit:

EQQUX009 parameters

DEST      DS  CL8  (The user-defined destination ID)
MCAUSERF  DS  A    (Address set by the user in the EQQUX000 exit)
OPCTOKEN  DS  F    (Token used to uniquely identify the operation)
WSNAME    DS  CL4  (Workstation name)
ADID      DS  CL16 (Application name)
IA        DS  CL10 (Input arrival date and time, format YYMMDDHHMM)
OPNUM     DS  CL3  (Operation number)
JOBNAME   DS  CL8  (Job name)
AREALEN   DS  F    (Length of the data area passed, zero if no data)
DATAP     DS  A    (Address of the data passed from JBLIB/JSFILE)
RETC      DS  F    (Return code set by the exit)

DEST

Defines the user-defined destination ID from the workstation of the current operation.

MCAUSERF

Is a user field that lets you allocate resources in the start/stop exit, EQQUX000, that this exit can later use. This field contains the value set by the EQQUX000 exit. Tivoli Workload Scheduler for z/OS does not use or update this field.

OPCTOKEN

Contains the token assigned for the current operation. This should be stored by you and used as input when you invoke OPSTAT to uniquely identify an operation.

WSNAME

Identifies the workstation name for the current operation.

ADID

The application name for the current operation.

IA®

Contains the input arrival date and time for the current operation in the format YYMMDDHHMM.

OPNUM

The operation number of the current operation.

JOBNAME

The job name defined for the current operation

AREALEN

Contains the length of the data area pointed to by DATAP. If the length is zero, no data has been passed.

DATAP

The address of an area that contains the data passed to the exit from the JCL library or the job-setup file. The data can have any format; it would probably not be z/OS® JCL.

RETC

The return code set by the exit. These values are valid:

0: Normal return, Tivoli Workload Scheduler for z/OS processing continues.
4: Operation failed. Tivoli Workload Scheduler for z/OS will take the action specified by the SUBFAILACTION keyword of the JTOPTS statement.
8: Communication failure. Tivoli Workload Scheduler for z/OS will automatically generate an offline event for all workstations connected to this destination. The exit will not be called again for this destination until the workstation status is reported as active. The status of the operation that the exit was processing is set according to the SUBFAILACTION keyword.

If the exit returns a value in RETC that is not considered valid, it will be ignored, and Tivoli Workload Scheduler for z/OS will treat the RETC as if 0 had been returned. In this case message EQQF010I is issued to the controller message log.

If the exit abends, it is flagged as not executable, and message EQQF011 is issued. The status of the operation that the exit was processing is set according to the SUBFAILACTION keyword.