Interface to the exit

The JCL-imbed exit is invoked in task mode, problem state, and key 8. 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.

The exit is called using the BASSM instruction and must return to its caller using the address and addressing mode passed to it in general register 14. The recommended method is to restore all registers to their values on entry to the exit and return to the caller using a BSM 0,14 instruction.

If the exit is entered in AMODE 31, it 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, and message EQQJ616E is issued. Tivoli Workload Scheduler for z/OS does not try to call the exit again.

Parameters passed to the exit reside below the 16 MB line. Also, addresses passed to the exit are addresses of areas below the 16 MB line.

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 this exit:

JCL-imbed exit parameters

JOBNAME    DS  CL8   (Job name)
IOAREA     DS  A     (Address of JCL buffer area)
IOAREAL    DS  F     (Size of JCL buffer area)
DATAL      DS  F     (Amount of data returned)
ADID       DS  CL16  (Name of current application)
WSDP       DS  A     (Address of workstation data)
OCCP       DS  A     (Address of occurrence data)
OPRP       DS  A     (Address of operation data)
WEEKD      DS  CL1   (Day of week: 1-7, where 1 is Monday)
WEEKY      DS  CL2   (Week of year)
RC         DS  F     (Return code)
MCAUSERF   DS  A     (Address set by the user in the EQQUX000 exit)

JOBNAME

The name of the job that is to be submitted.

IOAREA

The address of a buffer, allocated by IBM Tivoli Workload Scheduler for z/OS, where JCL records for the current job must be placed. JCL records must be placed consecutively in this buffer with no intervening space between records.

IOAREAL

The amount of space, in bytes, in the IOAREA buffer. In the current implementation, this value is always 32768 for each call to the exit. This is enough space to return up to 409 JCL-card images for each call to the exit.

DATAL

The amount of data returned by the exit. This cannot be a negative value or a value greater than the IOAREAL value. A zero value is valid on the last call.

ADID

The name of the current application.

WSDP

The address of the workstation data. The storage at this address is mapped by the program-interface (PIF) segment WSCOM.

OCCP

The address of the occurrence data. The storage at this address is mapped by the PIF segment CPOC.

OPRP

The address of the operation data. The storage at this address is mapped by the PIF segment CPOP.

WEEKD

The day of the week when the exit is called. It is a numeric value from 1 to 7, where 1 is Monday.

WEEKY

The number of the current week in the current year. It is a numeric value from 1 to 53, and is calculated according to the international standard ISO 8601. This standard uses a cycle of five “week-in-year” values to determine in which week the first of January falls. The cycle is 53, 52, 1, 1, 1. The current cycle started in 1988. That is, the first of January 1988 was in week 53 of 1987. The first of January 1989 was in week 52 of 1988, and the first of January 1990 was in week 1 of 1990.

RC

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

0: Normal return. The amount of data returned by the last call to the exit is given in DATAL. The exit will be called again to return more JCL records for the current job. The total amount of data returned by the exit must be less than 256 KB. This is 3276 JCL records.
4: End of data reached for current job. The amount of data returned by the last call to the exit is given in DATAL. The exit will not be called again for the current job.
8: The job could not be found in any input data set. The exit will not be called again for the current job.

MCAUSERF

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