Job-library-read exit (User Exit 2)

The job-library-read exit (User Exit 2) is called when HCL Workload Automation for Z is about to retrieve a batch job that does not exist in the EQQJSnDS data set. The exit is used to create a job stream to be submitted to JES by HCL Workload Automation for Z.

If the exit abends, it is flagged as not executable and HCL Workload Automation for Z does not try to call the exit again.

HCL Workload Automation for Z invokes the User Exit 2 in AMODE 31 and RMODE 24.

You can use User Exit 2 to:

Perform the functions described in Utility functions included in the user exits.
Retrieve a job, as described in Retrieving a job.

Retrieving a job

When the User Exit 2 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 User Exit 2 exit is 608 000 bytes. This corresponds to a job of 7599 card images. When the 608 000 byte limit is reached, HCL Workload Automation for Z issues message EQQJ582, 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.

Editing the exit

User Exit 2 includes the header file exit2.h, which contains the following routines:

void updateRetCode (unsigned char newRetCode, struct exit2struct *params): To update the return code of the exit. The params input is the same as the input passed to exit2do.
void updateDataL(int newDataL, struct exit2Struct *params): To update the DataL field of the exit.
void updateErrData(char *newErrData[], struct exit2Struct *params): To update the errData field of the structure (max 78 characters).

The header contains also the struct exit2Struct structure, which is provided as an input to the exit2do routine. Each string in the data structure is expanded by 1 character to reserve space for the end-of-text character \0, which corresponds to byte 0.

User Exit 2 parameters

User Exit 2 has the following structure:

struct exit2Struct{
char type; //Constant = J
char func; //Constant = G
char jobName[JOBNAME_LEN+1]; //Job Name
void *ioArea; //Address of I/O Area
int ioAreaL; //Size of I/O Area
unsigned char retCode; //Return Code
int dataL; //Amount of data returned
char errData[ERRDATA_LEN+1]; //Error Message returned
char adid[ADID_LEN+1]; //Name of current application
void *usrArea; //User field, 0 at first call
char jclUser[JCLUSER_LEN+1]; //Last User updating this job
int opNum; //Operation Number
char iaTime[IATIME_LEN+1]; //Occurrence input-arrival time, YYMMDDHHMM
void *varOccP; //Address of occurrence data if operation is in CP
void *varOprP; //Address of operation data if operation is in CP
void *varWsP; //Address of workstation data if operation is in CP
void *mcaUserF; //Address set by the User in the Exit 0
void *occPtr; //Address of occurrence data
void *oprPtr; //Address of operation data
void *wsPtr; //Address of workstation data
char authGrou[AUTHGROU_LEN+1]; //Authority group
unsigned char memPro; //Indicator of memory problems
void *taskPtr; //Address of TCB of caller task
void *xInfo; //Extended information address
int XJNamLen; //Extended Job Name length
int usrFNr; //Number of User fields
void *usrFArea; //User fields area address
} ;
#define JOBNAME_LEN 8
#define ERRDATA_LEN 78
#define ADID_LEN 16
#define JCLUSER_LEN 8
#define IATIME_LEN 10
#define AUTHGROU_LEN 8

where:

TYPE

Present only for compatibility reasons.

FUNC

Present only for compatibility reasons.

JOBNAME

Name of the job that is to be submitted.

IOAREA

Address of a buffer that is allocated by HCL Workload Automation for Z, where JCL records for the current job must be placed.

IOAREAL

Amount of space, in bytes, in the IOAREA buffer

RETCODE

Set by the exit to one of the following values:

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. HCL Workload Automation for Z attempts to retrieve the JCL from EQQJBLIB.
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

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

ERRDATA

User message area where you can describe a problem found in the exit. The text is issued in message EQQJ576 if return code 242 is set by the exit, or in message EQQJ580 if return code 241 is set.

ADID

Name of the current application.

USRAREA

It is zero the first time the exit is called to retrieve a job. The exit can set this parameter to any value. HCL Workload Automation for Z 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

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

OPNUM

Operation number of the operation representing this job.

IATIME

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

VAROCCP

Address of occurrence data. The storage at this address is mapped by the segment CPOC of the program interface (PIF).

VAROPRP

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

VARWSP

Address of workstation data. The storage at this address is mapped by the PIF segment CPWS.

Note: VAROCCP, VAROPRP, and VARWSP contain valid addresses only if the exit is invoked for operations that are present in the current plan. The addresses contain zero when you edit JCL from the long-term plan dialog or when adding an occurrence via the MCP dialog.

MCAUSERF

User field where you can allocate resources in the start/stop exit (User Exit 0) that this exit can later use. For example, you can decide to open files for JCL retrieval in the start type call to User Exit 0, instead of opening them each time User Exit 2 is called. HCL Workload Automation for Z does not use or update this field. The MCAUSERF field is valid when the controller is active.

OCCPTR

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

OPRPTR

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

WSPTR

Address of workstation data. The storage at this address is mapped by the PIF segment CPWS.

Note: OCCPTR, OPRPTR, and WSPTR always contain valid addresses. The data in these areas is read from the application description and workstation description databases, if the operation associated with the JCL does not exist in the current plan.

AUTHGROU

Name of the authority group.

MEMPRO

Indicator of memory problems. 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 scheduler for the last time (before return code 4 is set)
When an error occurs that does not allow HCL Workload Automation for Z to acquire further memory, HCL Workload Automation for Z informs the exit by setting MEMPRO to either of the following values:

X'04'

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

X'08'

If there is not enough storage available (EQQJ577 issued)

TASKPTR

Address of the task control block of the caller task.

XINFO

Address of the data specified in the Extended Info field of the Current Plan for the corresponding operation. If its value is 0, no extended information is available in the current plan.

XJNAMLEN

Length that you specify in the Operation Extended Name field of the Current Plan for the corresponding operation. It is a sub-field of the extended information available in the current plan.

USRFNR

Number of user fields records in USRFAREA.

USRFAREA

Address of the user fields area, as in the following example:

USRFAREA

USRFNAME DS   CL16         (User field name)
USRFVAL  DS   CL54         (User field value)