TP Profile Conversion Exit

z/OS MVS Programming: Writing Transaction Schedulers for APPC/MVS

TP Profile Conversion Exit

z/OS MVS Programming: Writing Transaction Schedulers for APPC/MVS
SA23-1398-00

The transaction scheduler TP profile conversion exit is established when the transaction scheduler invokes the Identify service, specifying the exit name. The TP profile conversion exit allows a transaction scheduler to convert the contents of a TP Profile when the first inbound allocate request arrives for the TP. The exit then returns the converted form of the TP profile, which APPC/MVS saves and uses on subsequent inbound requests.

Environment

This exit is invoked on each inbound request for a TP profile that has not been previously converted and saved. The exit receives control in the following environment:

Authorization:

Supervisor state and PSW key 1

Dispatchable unit mode:

Task mode

Cross memory mode:

PASN = HASN = APPC

AMODE:

31-bit

ASC mode:

Primary or access register (AR)

Storage key:

TCB protect key:

Interrupt status:

Enabled

Locks:

The exit does not hold any locks on entry.

Subpool limitations:

The TP profile conversion exit receives control after the unconverted TP profile is retrieved on an inbound request. The exit cannot invoke wait routines.

Exit Recovery

The caller of the exit routine should establish its own recovery environment before calling the exit routine. The exit routine should also establish its own recovery environment and, within its recovery, request a tailored dump. Before each exit routine returns control to its caller, the exit routine must delete the recovery environment it established and free all storage it obtained. If the exit routine does not establish its own recovery environment, the caller does the following when the exit routine ends abnormally:

Writes a logrec data set error record, and
Writes a dump.

The dump and the logrec data set error record might not contain enough information to diagnose the error.

For more information on providing recovery, see z/OS MVS Programming: Authorized Assembler Services Guide.

Programming Requirements

To preserve the registers of the caller, the exit routine must follow the linkage conventions described in “Linkage Conventions” in z/OS MVS Programming: Assembler Services Guide.

Installation

The TP profile conversion exit must reside in LPA or in the LNKLST concatenation. It must be a reentrant and reusable module. See the PROGxx or LNKLSTxx parmlib member description in z/OS MVS Initialization and Tuning Reference for more information about the LNKLST concatenation.

Entry Specifications

APPC/MVS passes information to the TP profile conversion exit in registers and in a parameter list.

Registers on Entry

On entry to the extract exit, the registers contain the following information:

Register	Contents
GPR 0	Does not contain any information for use by the exit.
GPR 1	The address of the parameter list described in Parameter List Contents.
GPRs 2-12	Do not contain any information for use by the exit.
GPR 13	The address of a standard 18-word save area.
GPR 14	The return address.
GPR 15	The entry point address.

Parameter List Contents

The parameter list is pointed to by GPR 1, and is mapped by the ATBDFTPE mapping macro. It contains such information as:

Parameters: Any data specified on the Scheduler_TP_profile_exit_data parameter of the Identify call.
TP_profile_key_pointer: The address of the TP profile key. Mapped by ATBDFTP mapping macro.
TP_profile_pointer: The address of the unconverted TP profile as retrieved from DASD. Mapped by ATBDFTP mapping macro.
Conv_data_pointer: The address that is to contain the converted TP profile. APPC/MVS obtains and frees this storage.
Conv_data_length: The length that is available for saving a converted TP profile. The converted TP profile must not exceed this length.

Return Specifications

Before returning control to its caller, the exit must place the length of the converted TP profile in the Conv_data_length field, if the conversion was successful. Also, the exit must ensure that the register contents are as follows:

Contents

GPRs 0-14

The exit must restore the contents to what they were when the exit received control.

GPR 15

One of the following return code values:

Value: Meaning
0 (0): Conversion was successful. APPC/MVS saves a copy of the converted TP profile.
4 (4): Conversion was unsuccessful; the conversion exit did not convert the profile. APPC/MVS saves a copy of the unconverted TP profile.
12 (C): Conversion was unsuccessful; the conversion exit encountered a syntax error. APPC/MVS does not save a copy of the TP profile.