Job-submit exit (User Exit 1)

User Exit 1 is called when HCL Workload Automation for Z is about to submit a batch job or start a started task. You can use this exit to:
  • Modify the JCL stream. However, you cannot increase the number of JCL records, unless you use the OPCOPTS EXIT01SZ parameter.
  • Modify the user that submits jobs. For detailed information about this use, see Normal production jobs.
  • Make the same user own both the stand-alone cleanup job and the original job.

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

Editing the exit

User Exit 1 includes the header file exit1.h, which contains the following routines:
void updateRUser(char *newRUser[], struct exit1Struct *params)
To update the RACF user that will submit the job. The newRUser input must end with the end-of-text character \0, which corresponds to byte 0. It can be up to 8 characters excluding the end-of-text character. The params input is the same as the input passed to the routine exit1do.
void updateWSchEnv(char *newWSchEnv[], struct exit1Struct *params)
To update the scheduling environment name. The newWSchEnv input must end with the end-of-text character \0, which corresponds to byte 0. It can be up to 16 characters excluding the end-of-text character. The params input is the same as the input passed to the routine exit1do.
int updateMsgClass(char newMsgClass, struct exit1Struct *params)
To update the message class of the JCL. If you did not add any new step, the routine updates the jclArea otherwise it updates the newJcl area. Ensure that the JCL contains the string MSGCLASS=. This routine returns 0. If an error occurs, it returns -1.
int insertStepJCL(char *newStep[], struct exit1Struct *params)
To insert a new step at the bottom of the JCL. The string newStep can be up to 80 characters and must end with the end-of-text character \0, which corresponds to byte 0. The newJcl area and the parameter usdRec will be updated.

It returns 0. If an error occurs, it returns -1 and a WTO message is issued.

The header contains also the struct exit1Struct structure, which is provided as an input to the exit1do 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 1 parameters

User Exit 1 has the following structure:
struct exit1Struct{
char jobName[JOBNAME_LEN+1]; //Job Name
int jclLen; //Size, in bytes, of current job stream
char *jclArea; //All records in job stream
char lateOut[LATEOUT_LEN+1]; //Latest start, format YYMMDDHHMM
char estDur[ESTDUR_LEN+1]; //Estimated duration, format HHMM
short int numPS; //Number of parallel servers required
short int numR1; //Amount required of workstation resource 1
short int numR2; //Amount required of workstation resource 2
char specRes[SPECRES_LEN+1]; //First 8 characters of first special resource name
char adid[ADID_LEN+1]; //Name of current application
void *mcaUserF; //Address set by the User in the Exit 0
char group[GROUP_LEN+1]; //Name of current authority group
char *rUser; //Pointer to Name of RACF user submitting the job
char operType; /*J for JCL job, S for started task, F for centralized end-to-end
job and for jobs that run on zcentric workstations*/
char updat; //Y or N, defines job origin
char jclUser[JCLUSER_LEN+1]; //Last user updating this job
char jclUTime[JCLUTIME_LEN+1]; //Time of last update, format YYMMDDHHMM
int opNum; //Operation number
char iaTime[IATIME_LEN+1]; //Occurrence input-arrival time, YYMMDDHHMM
char owner[OWNER_LEN+1]; //Application owner name
short int specNr; //Number of special resources
void *specBuf; //Special resource buffer
char wsName[WSNAME_LEN+1]; //Operation workstation name
char retCo[RETCO_LEN+1]; //Operation error code
int newRec; //Number of JCL lines in NEWJCL
char *newJcl; //New jclarea
int *usdRec; //Number of JCL lines used in NEWJCL
void *xInfo; //Extended information address
int xJNamLen; //Extended job name length
char calTyp; //Type of caller: N if called by WASUB, R if called by WASUJ
char noReEx; //Type of call: N if first call, Y if second or subsequent calls
char *wSchEnv; //Pointer to Scheduling Environment Name
void *occPtr; //Address of occurrence data
void *oprPtr; //Address of operation data
int usrFNr; //Number of user fields
void *usrFArea; //User field area address
} ;

#define JOBNAME_LEN 8
#define LATEOUT_LEN 10
#define ESTDUR_LEN 4
#define SPECRES_LEN 8
#define ADID_LEN 16
#define GROUP_LEN 8
#define RUSER_LEN 8
#define JCLUSER_LEN 8
#define JCLUTIME_LEN 10
#define IATIME_LEN 10
#define OWNER_LEN 16
#define WSNAME_LEN 4
#define RETCO_LEN 4
#define WSCHENV_LEN 16

where:
JOBNAME
Name of the job that is about to be submitted.
JCLLEN
Size, in bytes, of the job.
JCLAREA
JCL records in the job.
LATEOUT
Latest-start-time value that HCL Workload Automation for Z has calculated for the job.
ESTDUR
Estimated duration of this job.
NUMPS
Number of parallel servers required.
NUMR1
Amount of workstation resource 1 required.
NUMR2
Amount of workstation resource 2 required.
SPECRES
First 8 characters of the special resource name.
Note: When an operation is defined with more than one special resource, the SPECRES parameter contains the resource which is physically first in the ADR record in the EQQADDS data set. This is initially the special resource defined first for this operation, but is subject to change any time that a user adds or removes a special resource from the operation.
ADID
Name of the application that the job is part of.
MCAUSERF
A user field that is also passed to the User Exit 0. HCL Workload Automation for Z does not use or update the MCAUSERF field.
GROUP
Name of the authority group to which the current operation belongs.
RUSER
Name of the RACF® user that owns the job. This parameter contains 8 blanks when the exit is called. The exit can update this parameter, if required, to cause the job to be submitted under the specified user ID.

The returned RUSER value is stored in the CP file. It guarantees that, whenever a stand-alone cleanup job is submitted, it has the same owner as the original job.

This parameter is supported even if the job is sent to another system via a submit/release data set. So, there is a possibility that the SUBMIT SUBTASK of the controller or of the tracker which is submitting a given job may abend while executing under that RUSER-supplied user ID rather than under the user ID associated with the HCL Workload Automation for Z started task. If this should occur, DUMPTASK may fail with an ABEND913 if the user ID in control does not have WRITE access to the SYSMDUMP data set. For this reason, SYSMDUMP data sets should be defined with a UACC of UPDATE, that is they should be WRITE-ENABLED to all user IDs under which an HCL Workload Automation for Z-scheduled job might possibly be submitted.

If RUSER is blank and the job card does not specify the USER keyword, the job is submitted with the authority of the HCL Workload Automation for Z started task.

OPERTYPE
Can have one of the following values:
F
A job that runs on z-centric and dynamic workstations.
J
A JCL job.
S
A started task.
UPDAT
Has the value Y if the current job was retrieved from the EQQJSnDS data set. In all other cases, has the value N.
JCLUSER
Name of the latest TSO user to update the current job. This parameter is meaningful only if UPDAT is set to Y.
JCLUTIME
Date and time of the latest update to the current job. This parameter is meaningful only if UPDAT is set to Y.
OPNUM
Number of the operation representing the job.
IATIME
Input-arrival time of the application occurrence to which this job belongs.
OWNER
Name of the owner of the current application.
SPECNR
Number of special resource names in SPECBUF.
SPECBUF
Address to a buffer that contains a number of 64-byte fields. The number of 64-byte fields in the buffer is indicated by SPECNR. The first 44 bytes of each field contain the name of the special resource; the last 20 bytes of each field are reserved for future use.
WSNAME
Name of the operation workstation.
RETCO
Name of a field that can be used by the User Exit to stop submission and set the related error code. For more details, see the description of the SUBFAILACTION parameter in JTOPTS.
NEWREC
Size of the new JCLAREA. It is expressed in number of JCL lines, each of which has a length of 80 bytes. The JCLAREA value is provided to the exit by the scheduler and cannot be changed. If the OPCOPTS EXIT01SZ parameter is used and the NEWREC value provided by HCL Workload Automation for Z to the exit is equal to zero, the scheduler does not have enough storage to build the new JCLAREA.
NEWJCL
Area where the enlarged JCL is copied. It is provided by HCL Workload Automation for Z to the exit to allow the JCL size increase.
USDREC
Number of lines that belong to the enlarged JCL that is copied into the new JCLAREA.
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.
CALTYP
Type of caller. Can have one of the following values:
N
The exit is called by the EQQWASUB module.
R
The exit is called by the EQQWASUJ module.
NOREEX
Type of call. Can have one of the following values:
N
It is the first call.
Y
It is the second or subsequent call.
WSCHENV
Scheduling environment name currently stored in the CP operation record. This value can be modified by the exit.
OCCPTR
Address of the common data of record CPLREC3C.
OPRPTR
Address of the common data of record CPLREC3P.
USRFNR
Number of user field records in USRFAREA.
USRFAREA
Address of the user field area, as in the following example:
USRFAREA
USRFNAME DS   CL16         (User field name)
USRFVAL  DS   CL54         (User field value)