HCL Workload Automation, Version 9.4

Interface to the exit

The job-library-read 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.

If the exit abends, it is flagged as not executable; the agent 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:

EELUX002 parameters

 TYPE      DS   CL1   (Constant = J)
 FUNC      DS   CL1   (Constant = G)
 JOBNAME   DS   CL8   (Job name)
 IOAREA    DS   A     (Address of I/O area)
 IOAREAL   DS   F     (Size of I/O area)
 RETCODE   DS   X     (Return code)
 DATAL     DS   F     (Amount of data returned)
 ERRDATA   DS   CL78  (Error message returned)
 ADID      DS   CL16  (Name of current application)
 USRAREA   DS   A     (User field, 0 at first call)
 JCLUSER   DS   CL8   (Last user updating this job)
 OPNUM     DS   F     (Operation number)
 IATIME    DS   CL10  (Occurrence input-arrival time, YYMMDDHHMM)
 VAROCCP   DS   A     (Address of occurrence data if operation is in CP)
 VAROPRP   DS   A     (Address of operation data if operation is in CP)
 VARWSP    DS   A     (Address of workstation data if operation is in CP)
 MCAUSERF  DS   A     (Address set by the user in the EELUX000 exit)
 OCCPTR    DS   A     (Address of occurrence data)
 OPRPTR    DS   A     (Address of operation data)
 WSPTR     DS   A     (Address of workstation data)
 AUTHGROU  DS   CL8   (Authority group)
 MEMPRO    DS   CL1   (Indicator of memory problems)
 TASKPTR   DS   A     (Address of TCB of caller task)
 XINFO     DS   A     (Extended information address)
 XJNAMLEN  DS   F     (Extended job name length)
 USRFNR    DS   F         (Number of user fields)
 USRFAREA  DS   A         (User fields area address)

JOBNAME

The name of the job that is to be submitted.

IOAREA

The address of a buffer that is allocated by the agent for z/OS, where JCL records for the current job must be placed.

IOAREAL

The amount of space, in bytes, in the IOAREA buffer

RETCODE

Is set by the exit. These values are valid:

0: Normal return.
4: End of data reached for the current job.
16: The job could not be found in any input data set.
20: There is no JCL to be returned by the exit. The agent for z/OS attempts to retrieve the JCL from EELJBLIB.
44: Not enough space. The amount of free space in the IOAREA buffer (as determined by IOAREAL) is not enough to contain the next block of data.
241: I/O error has occurred.
242: An open error has occurred. One or more input data sets could not be opened.

The exit is called again to continue processing the same job when a return code 0 or 44 is returned. All other return codes end processing of the current job.

DATAL

The amount of data returned by the exit when the return code is 0 or 4.

ERRDATA

A user message area where you can describe a problem found in the exit. The text is issued in message EELJ020 if return code 242 is set by the exit or in message EELJ024 if return code 241 is set.

Note: If you modify the message library entry for EELJ020 or EELJ024 to generate a WTO, you must ensure that no more than 70 characters of message text are defined for each line. Reorganize the text, if required. Also, ensure that ERRDATA itself does not exceed 70 characters.

ADID

The name of the current application.

USRAREA

Is zero the first time the exit is called to retrieve a job. The exit can set this parameter to any value. The agent for z/OS does not use or update this parameter.

The exit should use the USRAREA parameter whenever it returns a return code 0 or 44. Normally, the USRAREA parameter is used to contain the address of a work area that the exit has performed a GETMAIN on. This work area should contain enough information to enable the exit to continue processing the same job.

JCLUSER

Is zero the first time the exit is called. The exit should set this parameter to the name of the z/OS user that is used for authority checking when the JCL contains automatic recovery statements.

OPNUM

The operation number of the operation representing this job.

IATIME

The input-arrival time of the application occurrence that this job belongs to.

MCAUSERF

A user field that lets you allocate resources in the start/stop exit, EELUX000, that this exit can later use. For example, it is possible to open files for JCL retrieval in the start type call to EELUX000 instead of opening them each time EELUX002 is called. The agent does not use or update this field. The MCAUSERF field is valid when the agent is active.

AUTHGROU

The name of the authority group.

MEMPRO

The indicator of memory problems.

TASKPTR

The address of the task control block of the caller task.

If the exit needs to access its own files, these files must be opened on the first call for a job (USRAREA value=0) and closed in either of the following ways:

Before returning control to the agent for the last time (before return code 4 is set)
When an error occurs that does not allow the agent to acquire further memory, the agent informs the exit by setting mempro to:
X'04'

If the limit of 608 000 bytes is reached (EELJ025 issued)

X'08'

If there is not enough storage available (EELJ021 issued)

When the EELUX002 exit is called to retrieve a job for the first time, the I/O area is 32 000 bytes. If the exit has retrieved the entire job and it fits in the buffer space available, the exit can update the I/O area, return the amount of data in the job, and set a return code 4.

If the exit has not retrieved the entire job, it can update the I/O area, return the amount of data in the job, and set a return code 0 to indicate that there is more data to be returned. The next time the exit is called, the address and the size of the I/O area will be updated because the I/O area is partly used by data from an earlier call. The exit should continue this process until there is no more data to return and then set a return code 4 to indicate that the entire job has been retrieved.

Because the available space in the buffer is reduced for each call, it is possible that the exit must set a return code 44 to indicate that the amount of free space is not enough. When return code 44 is returned, the exit is called again with a job name of eight equal signs (========). This is a reset call. The exit then prepares to process the job from the beginning.

No data can be returned on the reset call. When the exit is called again after the reset call, the I/O area is 32 000 bytes larger than before. This process of returning a “not-enough-space” condition can be repeated up to 19 times for a job. This means that the maximum buffer size that can be requested by the EELUX002 exit is 608 000 bytes. This corresponds to a job of 7599 card images. When the 608 000 byte limit is reached, the agent issues message EELJ025, and the exit is called a 20th time if MEMPRO is set to 4.

The exit can also get more buffer space by using all available space in the current buffer. When this happens and return code 0 is set, the exit is called again with 32 000 bytes free in the buffer. The reset call is not used in this case; the exit should continue processing the current job normally. Extending the buffer in this manner can be continued to a maximum buffer size of 608 000 bytes.