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.

Tivoli Workload Scheduler for z/OS 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:

EQQUX001 parameters

 JOBNAME   DS   CL8       (Job name)
 JCLLEN    DS   F         (Size, in bytes, of current job stream)
 JCLAREA   DS   n * CL80  (All records in job stream)
 LATEOUT   DS   CL10      (Latest start, format YYMMDDHHMM)
 ESTDUR    DS   CL4       (Estimated duration, format HHMM)
 NUMPS     DS   H         (Number of parallel servers required)
 NUMR1     DS   H         (Amount required of workstation resource 1)
 NUMR2     DS   H         (Amount required of workstation resource 2)
 SPECRES   DS   CL8       (First 8 characters of first special resource name)
 ADID      DS   CL16      (Name of current application)
 MCAUSERF  DS   A         (User field)
 GROUP     DS   CL8       (Name of current authority group)
 RUSER     DS   CL8       (Name of RACF user submitting the job)
 OPERTYPE  DS   CL1       (J for JCL job, S for started task, F for centralized end-to-end job))
 UPDAT     DS   C         (Y or N, defines job origin)
 JCLUSER   DS   CL8       (Last user updating this job)
 JCLUTIME  DS   CL10      (Time of last update, format YYMMDDHHMM)
 OPNUM     DS   F         (Operation number)
 IATIME    DS   CL10      (Occurrence input-arrival time, YYMMDDHHMM)
 OWNER     DS   CL16      (Application owner name)
 SPECNR    DS   H         (Number of special resources)
 SPECBUF   DS   A         (Special resource buffer)
 WSNAME    DS   CL4       (Operation workstation name)
 RETCO     DS   CL4       (Operation error code)
 NEWREC    DS   F         (Number of JCL lines in NEWJCL)
 NEWJCL    DS   n*CL80    (New jclarea)
 USDREC    DS   F         (Number of JCL lines used in NEWJCL)
 XINFO     DS   A         (Extended information address)
 XJNAMLEN  DS   F         (Extended job name length)
 CALTYP    DS   C         (Type of call: N if caller by WASUB, R if caller by WASUJ)
 NOREEX    DS   C         (Type of call: N if first call, Y if second or subsequent calls
 WSCHENV   DS   CL 16     (Scheduling Environment Name)
 OCCPTR    DS   A         (Address of occurrence data)
 OPRPTR    DS   A         (Address of operation data)
 USRFNR    DS   F         (Number of user fields)
 USRFAREA  DS   A         (User fields area address)

Note:

EQQUX001 is also called when a job is resubmitted to perform a Restart and Cleanup. In this case, JCL changes are ignored. The JCL area is passed to the exit but no changes are applied. Only the exit's user ID and return code information is processed.

JOBNAME

The name of the job that is about to be submitted.

JCLLEN

The size, in bytes, of the job.

JCLAREA

The JCL records in the job.

LATEOUT

The latest-start-time value that Tivoli Workload Scheduler for z/OS has calculated for the job.

ESTDUR

The estimated duration of this job.

NUMPS

The number of parallel servers required.

NUMR1

The amount of workstation resource 1 required.

NUMR2

The amount of workstation resource 2 required.

SPECRES

The 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 dataset. 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

The name of the application that the job is part of.

MCAUSERF

A user field that is also passed to the EQQUX000 exit. Tivoli Workload Scheduler for z/OS does not use or update the MCAUSERF field.

GROUP

The name of the authority group that the current operation belongs to.

RUSER

The 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.

You can also use this parameter to modify the user submitting a job with a centralized script. If you use this keyword to specify the name of the user who submits the specified script or command on a Windows fault-tolerant workstation, you can:

Associate this user name to the Windows workstation in the USRREC initialization statement.
Set LOCALPSW(YES) in the TOPOLOGY statement, then use the user utility to define the name and password of the user in a local file on the Windows workstation.

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 Tivoli Workload Scheduler for z/OS 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 Tivoli Workload Scheduler for z/OS-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 Tivoli Workload Scheduler for z/OS started task.

OPERTYPE

Has the value J for a JCL job, S for a started task, or F for a centralized end-to-end job.

UPDAT

Has the value Y if the current job was retrieved from the EQQJSnDS data set. In all other cases, UPDAT has the value N.

JCLUSER

The name of the last TSO user to update the current job. This parameter is meaningful only if UPDAT has a value Y.

JCLUTIME

The date and time of the last update to the current job. This parameter is meaningful only if UPDAT has a value Y.

OPNUM

The operation number of the operation representing this job.

IATIME

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

OWNER

The name of the owner of the current application.

SPECNR

The number of special resource names in SPECBUF.

SPECBUF

An 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

The name of the operation workstation.

RETCO

The name of a field that can be used by the User Exit to stop submission and set the related error code. Refer to the description of the SUBFAILACTION keyword in Defining initialization statements for more details.

NEWREC

The 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 keyword is used and the NEWREC value provided by Tivoli Workload Scheduler for z/OS to the exit is equal to zero, the scheduler does not have enough storage to build the new JCLAREA.

NEWJCL

The area where the enlarged JCL is copied. It is provided by Tivoli Workload Scheduler for z/OS to the exit to allow the JCL size increase.

USDREC

The number of lines that belong to the enlarged JCL that is copied into the new jclarea.

XINFO

The 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

The 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.

WSCHENV

The scheduling environment name currently stored in the CP operation record. This value can be modified by the exit.

OCCPTR

The address of the common data of record CPLREC3C.

OPRPTR

The address of the common data of record CPLREC3P.

USRFNR

The number of user field records in USRFAREA.

USRFAREA

The address of the user field area. It is laid out as follows:

USRFAREA

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