Macros
This topic describes the macros provided to help in the development of user exits.
Introduction
Some macros are provided to help in the development of user exits. With the inclusion of Job User Descriptors as part of the Job Action Language, the process to further customize BMC ThruPut Manager has been made much simpler. In many cases, a single exit to set a value in a Job User Descriptor is all that is needed to be able to take installation unique actions with the Job Action Language. The macros provided make this type of action a simple exercise.
Considerations
The following macros are provided:
- DTMSTART: Provides addressability and register usage.
- DTMSTOP: Terminates exit processing.
- DTMBWA: Begins dynamic work-area definitions.
- DTMEWA: Ends dynamic work-area definitions and generates DSECT mappings.
These macros are designed to provide the following programming structure:
DTMSTART
your code
DTMSTOP
your static storage definitions (constants)
DTMBWA
your dynamic storage definitions
DTMEWA
your DSECTS (if any)
ENDThese macros are not automatically installed. To restore them, please refer to the Installer's Guide documentation.
DTMBWA
Begin Work Area
Description
This macro defines the beginning of the work-area DSECT mapping.
The macro expansion causes a LTORG to be generated (if requested) followed by a DSECT definition.
Two save areas are generated following the DSECT definition to be used as save areas for this module.
DTMBWA | [LTORG=YES] [PATCH=YES] |
LTORG=YESCauses a LTORG to be generated.
PATCH=YESCauses a 50-byte patch area to be generated.
25 half-words are defined.
All your work area field definitions must follow this macro.
DTMEWA
End Work Area
Description
This macro generates an equate to define the work area length. It also generates the DTM DSECTS.
DTMEWA , |
This macro does not require operands.
DTMSTART
Macro to provide addressability and register usage
Description
This macro provides addressability to the following BMC ThruPut Manager areas:
- UXPCOMMP Common Parameter list.
- UXPUSERP Common Communication Area.
- UXPVARLP Exit-specific Parameter Area.
- UXPINTFP Message Routine Address List.
- UXCUJDSC User Job Descriptor Area.
- UXPnnJUP Job User Data Field (nn represents the exit number).
This macro also generates the code to perform standard IBM save area linkage.
name1 DTMSTART | [DEFAULT={YES | NO}] [,BASE={R12 | Ra}] [,COMMP={R10 | Rb}] [,USERP={R9 | Rc}] [,VARLP={R8 | Rd}] [,INTFP={R7 | Re}] [,USERJD={R6 | Rf}] [,USERJP={R5 | Rg}] [,WKDSECT=name-of-DSECT] [,XITNUM=nn] |
name1CSECT name for the module. This must be specified.
DEFAULTUse to indicate whether or not you want all the above areas mapped automatically.
YESAny of the above areas that you do not code will be mapped using the default register.
This is the default.
XITNUM must be coded if YES is used.
NOOnly the areas specifically coded will be mapped.
COMMPRequests addressability to Common Parameter Area UXPCOMMP.
RaA unique general purpose register from R2 to R12.
USERPRequests addressability to Common Communication Area UXPUSERP.
RbA unique general purpose register from R2 to R12.
VARLPRequests addressability to Exit-specific Parameter Area UXPVARLP.
RcA unique general purpose register from R2 to R12.
If this keyword is coded and DEFAULT=NO is coded, then XITNUM must also be specified.
INTFPRequests addressability to Message Routine Address List UXPINTFP.
RdA unique general purpose register from R2 to R12.
USERJDRequests addressability to User Job Descriptors UXCUJDSC.
ReA unique general purpose register from R2 to R12.
USERJPRequests addressability to Job User Data Field UXnnJUP.
RfA unique general purpose register from R2 to R12.
If this keyword is coded and DEFAULT=NO is coded, then VARLP and XITNUM must be coded.
WKDSECTAllows you to name the DSECT that is to map the work area.
name-of-DSECTSelf-explanatory.
This keyword must be specified if DTMBWA and DTMEWA macros are coded.
XITNUMRequire to map the exit-specific parameter area.
This keyword must be coded if DEFAULT=YES is coded (or defaulted).
nnThe exit number.
It is used to create the name of the Exit-Specific Parameter Area DSECT, as well as the name of the Job User Data Area.
The TM Exit Data Area pointed to by UXPDATAP is not defined in this macro. If you are providing data to your exits using the DATA keyword it is your responsibility to load the address of this field in your exit logic.
On entry the register usage is as follows:
R1 UXPL pointer
R13 4K work area
R14 Return address
R15 Base registerThe Job User Data Field pointer is applicable to the following exits:
- All Job-related Exits: 1, 2, 3, 4, 5, 6, 7, 8, 9, and 19.
- Exit 13-JOB DISPLAY Command.
- Exit 14-JVL Format.
The User Job Descriptors pointer is applicable to the following exits:
- All Job-related Exits: 1, 2, 3, 4, 5, 6, 7, 8, 9, and 19.
The defaults for register usage can simply be overridden by specifying the keyword with the register you want to use.
Example
MYMODULE DTMSTART DEFAULT=YES,WKDSECT=TMAREA,VARLP=R2,XITNUM=03This will result in all areas being mapped. Your work area will be named TMAREA. Default registers for addressability will be used with the exception of the Exit-specific Parameter Area. Register 2 will be used instead of 8.
DTMSTOP
Stop Exit Processing
Description
- This macro causes restoration of the callers registers and sets a return code prior to returning to caller.
DTMSTOP | [{RC=value | (Rn)}] |
RCIndicates that the return code is to be provided as an operand.
valueA return code value.
Values of 0, 2, 4 and 12 are valid return codes. Exit 19 also accepts a value of 16.
RnIndicates the general purpose register where the return code is to be found.