Interface to the exit
The JCL-variable-substitution 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.
The exit is called using the BASSM instruction and must return to its caller using the address and addressing mode passed to it in general register 14. The recommended method is to restore all registers to their values on entry to the exit and return to the caller using a BSM 0,14 instruction.
If the exit is entered in AMODE 31, it must switch to AMODE 24 before performing any input or output operations, and then switch back to AMODE 31 before returning to the caller.
If the exit abends, it is flagged as not executable, and message EQQJ518E is issued. Tivoli Workload Scheduler for z/OS does not try to call the exit again.
Parameters passed to the exit all reside below the 16 MB line. Also, addresses passed to the exit are addresses of areas below the 16 MB line.
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 this exit:
VARNAME DS CL8 (Name of variable for substitution)
VARTAB DS CL16 (JCL-variable-table name)
VARLGTH DS F (Required length of variable value)
VARDEF DS CL44 (Variable default value as defined in table)
VARNVAL DS CL44 (Variable value, set by exit)
VAROPRP DS A (Address of operation data)
VARWSP DS A (Address of workstation data)
VAROCCP DS A (Address of occurrence data)
VARDWEEK DS CL1 (Day of week: 1-7, where 1 is Monday)
VARWEEKY DS CL2 (Week of year)
VARRETC DS F (Return code, set by exit)
MCAUSERF DS A (Address set by the user in the EQQUX000 exit)
VARJCL DS CL80 (Current JCL line where this variable was found)
VARFIRST DS A (Address of the first JCL line for the job)
VARLINES DS F (Number of JCL lines in the job)
VARUFLN DS F (Number of user fields)
VARUFLB DS A (Address of user fields buffer)
- VARNAME
- The name of the variable for substitution.
- VARTAB
- The name of the JCL-variable table.
- VARLGTH
- The required length of the variable value or X'00' if a length is not defined for the variable.
- VARDEF
- The default value of the variable as defined in the variable table, left-justified and padded with X'40'.
- VARNVAL
- The value of the variable set by the exit.
- VAROPRP
- The address of operation data. The storage at this address is mapped by the program-interface (PIF) segment CPOP.
- VARWSP
- The address of workstation data. The storage at this address is mapped by the PIF segment WSCOM.
- VAROCCP
- The address of occurrence data. The storage at this address is mapped by the PIF segment CPOC.
- VARDWEEK
- The day of the week when the exit is called. It is a numeric value from 1 to 7, where 1 is Monday.
- VARWEEKY
- The number of the current week in the year. It is a numeric value from 1 to 53 and is calculated according to the international standard ISO 8601.
- VARRETC
- The return code set by the exit. These values are valid:
- 0
- Variable processing normal.
- 8
- Stop tailoring. If the exit was called at job submission, the operation is set to ended-in-error. If it was called at setup via the online dialogs, an error message is issued at the terminal.
- MCAUSERF
- A user field that lets you allocate resources in the start/stop exit, EQQUX000, that this exit can later use. This field contains the address that is set in EQQUX000. Tivoli Workload Scheduler for z/OS does not use or update this field.
- VARJCL
- The JCL line where this variable was found. It is set to blank characters if you are submitting a job definition contained in the SCRPTLIB library.
- VARFIRST
- The address of the first JCL line. It is set to zero if you are submitting a job definition contained in the SCRPTLIB library.
- VARLINES
- The number of JCL lines. It is set to zero if you are submitting a job definition contained in the SCRPTLIB library.
- VARUFLN
- The number of user field records in USRFAREA.
- VARUFLB
- 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)
- The exit is not called for setup JCL variables that are defined as promptable.
- If a value is set in the VARNVAL field, it is used by Tivoli Workload Scheduler for z/OS only if VARRETC is zero.
- The value passed backed to Tivoli Workload Scheduler for z/OS in the VARNVAL field must satisfy verification rules defined for the variable.
- The variable value is taken from the data in the VARNVAL field up to the first X'40'.