Interface to the exit
The job-submit 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.
HCL Workload Automation for Z invokes the exit in the addressing mode defined by the load module's AMODE attribute. When the exit is called in bit addressing mode, the job stream passed to the exit resides above the 16M line. When the exit is called in 24 bit addressing mode, the job stream passed to the exit resides below the 16M line.
Control is passed to the exit using the BASSM instruction. The exit must return to its caller using the address passed to it in general register 14. The exit can return in any addressing mode.
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:
- 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 EQQUX000 exit. 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.
Different ways to set it are suggested in the EQQUX001 sample job contained in the SEQQSAMP library. A code sample extracting the value of the USER parameter from the JOB card is included as well. Refer to the comments in the sample for more details.
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: