Designing installation exits

This topic describes the considerations affecting the design of a BMC ThruPut Manager installation exit.

Introduction

This topic describes the environment provided by BMC ThruPut Manager to help in the development and installation of exits. Before developing an exit, an understanding of the linkages and conventions used is necessary. The conventions are different for the two types of exits:

Job-related Exits.
Function-related Exits

Job-Related Exits

They are invoked by the Job Analyzer.
There is a direct relationship between the job being analyzed and the particular exit.
They are called in protect key 0 supervisor state and are not holding any locks.
The AMODE statement can be used to control the addressing mode of the exit. Unless there are specific reasons to do otherwise, use "AMODE 31".
A number of exits are called prior to the execution of JAL. These Pre-JAL exits can influence the decisions made during JAL execution.
Other exits are called after the execution of JAL. Their main purpose is for clean-up. It is possible to override JAL decisions from these Post-JAL exits.
For the purpose of inter-exit communication, the job-related exits are treated as a set. That is, you can pass data from one exit to the next for a particular job by using User Descriptors. See the section User Descriptors in this topic and Inter-Exit-communication for more information.

Once the analyzing of a job is completed, the process starts all over again for the next job.

Some exits can be called more than once for a job. For example, the DD Exit is invoked as many times as there are DDs in a job.
Some exits might not be called if the job is flushed by a prior exit, or failed on a JCL error by Early Scan.

Function-Related Exits

They are invoked by TMSS.
They are asynchronous from job processing.
They are called in protect key 8.
They can be called more than once, depending on the nature of the exit.
They are independent of each other, so they do not have access to the same user data areas.

Exit Environment

Exit Definition

Exits are defined using the TM EXIT initialization statement.
If you want to use an Exit, you must define it. That is, you cannot dynamically activate it if it has not been defined.
You can define exits as:

–Active

–Inactive

The inactive mode is provided for testing purposes. This allows you to activate the exit dynamically through the TM EXIT command when you are ready to test.
The TM EXIT initialization statement is explained in detail in Installing-activating-and-tracing-installation-exits.
The TM EXIT operator command is explained in detail in Installing-activating-and-tracing-installation-exits.

LOADing the Exits

Job Analyzer exits are LOADed by the Job Analyzer each time a job is processed. These exits are serialized for a job.

TMSS exits are LOADed by the appropriate TMSS tasks (main task, CPS task, Operator Services) only when the task is attached. An exit point is serialized at the task level, but not across tasks.

If the exit cannot be found, the LOAD receives a system 806 abend, and that component terminates.

Invocation of Exits

The following characteristics apply to all exits:

All installation exits are invoked in supervisor state, and must return control in supervisor state.
Installation exits are invoked using the AMODE specified (or defaulted to) when they are written.

The next 4 sections document conventions for:

Registers-Exit invocation.
Registers-Exit return.
Addressing mode.
Parameter list.

Registers - Exit Invocation

When the exit gets control, the registers are set up as shown below.

Registers at Exit Invocation
Registers	Description of Contents
0	Zeroed.
1	The address of a list of pointers as described below. The addresses of all data areas are full words, and can be used in either 24 or 31-bit addressing modes.
2-12	Zeroed.
13	Points to a 4096 byte area reserved for use by the exit as a work area. The 4K work area makes it very easy to write reentrant code and avoid doing GETMAINs or FREEMAINs.
14	Contains the return address in BMC ThruPut Manager and the addressing mode.
15	Contains the entry point address of the exit and the addressing mode.

Registers - Exit Return

When the exit returns control:

Registers at Exit Return
Registers	Description of Contents
0-14	Restored by BMC ThruPut Manager
15	Return code from your exit. BMC ThruPut Manager acts upon it.

You must also ensure that control is returned in supervisor state.

Addressing Mode

You can control the addressing mode of your exits by using the AMODE assembler statement. Unless you have specific, well-understood reasons for using 24-bit addressing, you should use 31-bit addressing.

Parameter List

Upon entry to your exit module, register 1 is loaded with a pointer to a five word list of pointers, mapped by the DTMUXPL macro (shown in the following diagram). The five parameters pointed at by R1 are shown in the table below.

Parameter List Pointed at by R1
Name	Type	Length	Description
UXPUSERP	address	4	Pointer to exit communication area.
UXPCOMMP	address	4	Pointer to exit common parameter area.
UXPVARLP	address	4	Pointer to exit-specific parameter area.
UXPINTFP	address	4	Pointer to service routine address list.
UXPDATAP	address	4	Pointer to data provided with the DATA keyword in TM EXIT control statement.

UXPUSERP - Common Communication Area

The first word of the parameter list contains a pointer to an installation exit communication area. This is a 16 byte area with an initial value of binary zeroes. It can only be updated by Exit 10 (TMSS Initialization). The values are then passed to any other exit routines. Its main purpose is to anchor user tables or other type of similar data.

UXPCOMMP - Common Parameter Area

The second word of the parameter list contains the address of a block of data that is common to all exits.

If data is not available or does not apply, the corresponding field is blank or zero.

This data is mapped by the DTMUXCP macro. Refer to the following list of available fields. Note that this is not a mapping of the parameter area. For details of the mapping, refer to an expansion of the macro.

Second Pointer in Parameter List
Macro name: DTMUXCP
Name	Type	Length	Description	Modify?
UXCEXIT#	binary	4	Installation exit number. This lets you differentiate between exit point calls if the same module is given control.	No
UXCJOBNM	char	8	Job Name	No
UXCRDRON	binary	8	Reader 'on' time and date in the same format as the TIME SVC (8 bytes, time in binary hundredths of a second, packed decimal date).	Yes
UXCEJOB#	char	5	JES2 5 character job number. (JES2 V3)	No
UXCJOB#	char	4	JES2 4 character job number.	No
UXCISYS	binary	1	SID where the job was read.	No
UXCTSCAN	char	1	TYPRUN=SCAN. Values can be: N No Y Yes Available only to Job Analyzer exits 1-9 and 19.	No
UXCPGMRN	char	20	Programmer name.	Yes
UXCACCT#	char	20	First 20 bytes of first account field from JOB statement (padded on the right with blanks).	Yes
UXCROOM#	char	4	JES2 room number (might be zero if user did not code one).	Yes
UXCRACFG	char	8	RACF group name.	Yes
UXCRACFU	char	7	RACF userid.	Yes
UXCNOTFY	char	7	TSO NOTIFY userid.	Yes
UXCNJEU	char	8	NJE NOTIFY userid.	Yes
UXCOCLAS	char	1	Original job input class.	Yes
UXCCCLAS	char	1	Current job input class.	Yes
UXCORGND	char	8	Originating node name.	Yes
UXCORGRM	char	8	Originating remote name.	Yes
UXCINDEV	char	8	Input device name.	Yes
UXCORGNN	binary	2	Originating node number.	Yes
UXCORGRN	binary	2	Originating remote number.	Yes
UXCSYSMF	char	4	SMF system id.	Yes
UXCJSTAT	char	4	Job status. Values can be: - OKAY - processed okay so far. - FAIL - failed by installation exit or Early Scan. - FLSH - flushed by installation exit.	No
UXCACCTP	address	4	Pointer to JOB statement account fields. These fields are mapped by the UXP02ACF DSECT generated by the DTMUXP02 macro: - UXP02AFN One byte binary number of account fields. - UXP02AFL 144 byte account field area as described below. The field UXP02AFL mapped by this DSECT contains a variable number of fields in the form: (# of fields),(length-1),(field-1), (length 2),(field-2), ... The number of fields counter and the field lengths are one byte binary numbers. If a length is x’00’, the field is absent (coded as ‘,,’). The length of a field does not include the byte with the length descriptor. This field contains an address for Job-related exits. For the Function-related exits, this field contains binary zeroes	No
UXCSMFXP	address	4	Pointer to SMF common exit parameter area.	No
UXCUJDSC	address	4	Pointer to User Descriptors.	No
UXCRACF8	char	8	8-character RACF user id (available only in exits 1-9 and 19).	Yes
UXCJOBID	char	8	JES2 Job ID.	No

Most of the data in the common parameter list can be modified by the JOB Statement installation exit (Exit 1).

Any modifications are only for the purpose of influencing BMC ThruPut Manager processing. The real fields are not altered. This facility is provided to cover situations where the installation, through system modifications, alters these fields after BMC ThruPut Manager has processed a job. Using this mechanism, it is possible for the installation to present BMC ThruPut Manager with the same alterations.

UXPVARLP - Exit-Specific Parameter Area

The third word points to a block of data that varies depending on the exit. Naturally, this block varies in size from exit to exit.

The detailed description for each of these exit-specific data blocks is contained in the descriptions for each of the exits.

UXPINTFP - Communication Routines

The fourth word points to two addresses which you can use to invoke the BMC ThruPut Manager message routines available in job-related exits. These two routines are provided to allow you to insert messages during job analysis.

If the exit is function-related, no routines are available and the pointer contains zeros.

This list of routine addresses is mapped by the DTMUXIL macro. See below.

Fourth Pointer in Parameter List
Macro Name: DTMUXIL
Name	Type	Length	Description
UXILSYSM	address	4	Address of the routine to insert messages into the job’s System Messages data set.
UXILJOBM	address	4	Address of the routine to insert messages into the job’s JOBLOG.

Calls to these routines must be made in supervisor state, but can be in any AMODE.

These routines run in 31-bit addressing mode, therefore all addresses of data passed to them must be 31-bit addresses.

Control is returned in the caller's AMODE.

UXILSYSM - System Message Routine

The System Messages routine allows an installation exit to issue a message and have it appear in the system messages data set of a job being processed by the Job Analyzer. This routine is necessary because BMC ThruPut Manager normally suppresses any messages being generated for the system messages data set.

Registers upon entry to the routine must be as follows:

System Message Routine Conventions
Registers	Description of Contents
1	Address of the data block that contains the message to be written. The data block contains a record descriptor word (RDW) followed by the message text and is formatted as follows: - Halfword length of the message block including the RDW. - Halfword field of zeroes. Message text to be written to system messages data set. Text can have a maximum length of 133 (if exceeded, the message is truncated). Any use of carriage control is ignored.
13	Is expected to point at a caller-provided standard MVS save area.
14	Address to which the caller expects control to be returned.
15	Must contain the address of the routine.

All other registers are preserved across the call.

When control is returned to the caller, register 15 contains a return code of zero.

UXILJOBM - JOBLOG Messages Routine

The JOBLOG Messages routine allows an installation exit to issue a message to the operator using a WTO, and have it appear in the JOBLOG data set of a job being processed by the Job Analyzer.

This routine is necessary because BMC ThruPut Manager normally suppresses logging of WTO messages in the JOBLOG data set by JES2 during the Job Analysis phase.

Registers upon entry to the routine must be as follows:

JOBLOG Message Communication Routine Conventions
Registers	Description of Contents
0	Is assumed to contain any data associated with the WTO that is to be issued, such as connect id or UCM console id.
1	Address of the message to be issued. The message must be in WTO list format (i.e. generated with MF=L in the caller's routine).
13	Is expected to point at a caller-provided standard MVS save area.
14	Address to which the caller expects control to be returned.
15	Must contain the address of the routine.

All other registers are preserved across the call.

Upon return from the routine, register 15 contains the return code from the WTO SVC.

Registers 0 and 1 contain any data returned by the WTO (such as the connect id).

Return Codes

Your exit can influence further BMC ThruPut Manager processing by setting a return code in register 15.

Return Code Conventions for Job-Related Exits
RC	Meaning
0	Continue processing with the job
4	Installation exit has altered the data passed to it. BMC ThruPut Manager is to use the modified data.
8	Installation exit requests that the job or request be failed. When a job is failed, BMC ThruPut Manager continues to process it, but upon completion, the Job Analyzer fails the job with a JCL error, and queues it for output.
12	Installation exit requests that the job or request be flushed or terminated immediately. The flush capability might be used when a job fails job level security checking, and further processing is not desirable. When a job is flushed during Job Analyzer processing: - No further processing of the job is performed. - The job is failed with a JCL error. - Only exits 1, 6, 7, 8, and 9 are invoked.

Return Code Conventions for Function-Related Exits
RC	Meaning
0	Continue processing as if the exit had not been called.
4	Depends on the particular exit
8	Depends on the particular exit
12	Depends on the particular exit

These return codes are strictly enforced by BMC ThruPut Manager. Any other return code results in a message to the operator:

DTM3200I INVALID RETURN CODE rc, FROM THRUPUT MANAGER USER EXIT nnWhere:

rcIs the return code passed back in register 15.

nnIs the number of the exit producing the invalid return code.

This message is followed by a User 3200 abend, and the component terminates.

Exit Abends

If an installation exit abends during its execution, an SVC dump is generated.

The dump title contains:

The number of the installation exit.
The PSW.
The abend code.

Notes:

An abend in an exit does not cause the exit to be marked "inactive".

An abend in a Job Analyzer exit causes the Job Analyzer initiator and address space to terminate. The job being processed is queued to the same class in which it was being processed, and is held.

An abend in a TMSS task causes the task to terminate and be reattached, unless the internal BMC ThruPut Manager error retry count is exceeded. This is provided to prevent an endless number of exit abends.

User Descriptors

BMC ThruPut Manager provides several User Descriptors that can be used in any way your installation desires. Normally, User Descriptors are given values by your Pre-JAL installation exit(s). These values can then be tested in your JAL and therefore can influence the handling of the job being processed. The meaning of a User Descriptor is left entirely to you.

User Descriptor Types

There are two types of User Descriptor available in exits:

Numeric descriptors. Each numeric descriptor is a fullword. There are 99 numeric User Descriptors, named USERN1 through USERN99. Numeric descriptors are initialized to binary zeros.
Character descriptors. Each character descriptor is 50 bytes long. There are 99 character User Descriptors, named USERC1 through USERC99. Character descriptors are initialized with blanks.

User Descriptor Availability

User Descriptors are available in job-related exits. They are initialized to binary zeroes or blanks each time a new job is processed. The following table indicates the Pre-JAL exits which have access to User Descriptors.

Pre-JAL Exits
No.	Description	Page
1	Job Statement	??
2	EXEC Statement	??
3	DD Statement	??
4	Unit Name/Device Type	??
5	Volume Status	??
19	JECL Inspection	??

User Descriptors are also available to Post-JAL exits. In this case they are normally used to influence the Job Information collection or some clean-up process if necessary. All the Post-JAL exits have access to User Descriptors.

Post-JAL Exits
No.	Description	Page
6	Job Action Modification	??
7	Job Information	??
8	Requeue Message	??
9	Job Termination	??

Locating User Descriptors

User Descriptors are pointed to by the address contained in the UXCUJDSC field in the common parameter list mapped by DTMUXCP macro.

The DTMUJDSC macro maps the area pointed to by this address, as shown below.

Macro Name: DTMUJDSC
User Descriptors
Name	Type	Length	Description
USERN1	binary	4	Numeric descriptor 1.
USERN2	binary	4	Numeric descriptor 2.
. . .
USERN99	binary	4	Numeric descriptor 99.
USERC1	char	50	Character descriptor 1.
USERC2	char	50	Character descriptor 2.
. . .
USERC99	char	50	Character descriptor 99.

Design Considerations

Some points you should keep in mind when writing installation exits:

Installation exits have mapping macros associated with them to make using their parameter lists easier. These mapping macros represent the most current documentation for the parameters. The mappings shown in this guide are intended to illustrate the fields and data available, and are not intended to be definitive. Consult the macro expansion for actual mappings.

Important

If there is a discrepancy between this manual and the macro, the macro is correct.

Installation exits should be reentrant. The 4K work area pointed to by register 13 is provided to simplify the task.
Installation exit routines can have any desired name.
A single installation exit module can serve multiple exit points. For example, module XYZ can receive control as exits 1, 2 and 6. It is then the responsibility of the module to determine the exit point for the particular invocation. The exit number is provided as part of the common data block.
Unless you have specific, well-understood reasons to do otherwise, you should use 31-bit addressing for your exits. This allows some control blocks to be allocated "above the line", and results in more efficient use of storage. Note that it is your responsibility to switch to 24-bit addressing when performing such functions as QSAM I/O.

Sample-installation-exit contains a listing of a sample installation exit, showing the exit linkage and how to assign a value to a User Descriptor.