TP Profile Syntax Exit

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

TP Profile Syntax Exit

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

This exit is provided to enable transaction schedulers to check the syntax of scheduling information before it is added to the TP profile data set. The syntax exit, which must be provided along with the scheduler and specified in the TP profile's TPSCHED_EXIT keyword, is invoked on TPADD or TPMODIFY commands by the APPC/MVS administration utility or administration dialog. If no syntax exit is specified, the transaction scheduler information in the TP profile is assumed to apply to the APPC/MVS transaction scheduler, and the APPC/MVS administration utility and JCL converter/interpreter check it for the syntax expected by that scheduler.

If a syntax exit is specified and it finds errors in the transaction scheduler information, the exit can invoke an IBM-supplied message routine (see Profile Syntax Message Routine) to write messages to the SYSPRINT data set and can prevent the profile from being added or modified. The administrator who is creating or modifying the TP profile can then correct the error and try again.

Environment

The syntax exit receives control in the following environment:

Authorization:

Supervisor state and PSW key 1

Dispatchable unit mode:

Task mode

Cross memory mode:

PASN = HASN = SASN

AMODE:

31-bit

RMODE:

ANY

ASC mode:

Primary

Storage key:

TCB protect key:

Interrupt status:

Enabled

Locks:

The exit does not hold locks on entry.

Exit Recovery

The caller of the syntax exit should establish its own recovery environment before calling the exit. The syntax exit should also establish its own recovery environment and, within its recovery, request a tailored dump. Before the exit returns control to its caller, the it must delete the recovery environment it established and free all storage it obtained. If the syntax exit does not establish its own recovery environment, the caller does the following when the exit 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 syntax exit must follow the linkage conventions described in “Linkage Conventions” in z/OS MVS Programming: Assembler Services Guide.

Installation

The syntax exit must meet all the following conditions:

Reside in LPA or in the LNKLST concatenation (for example, SYS1.LINKLIB)
Be in an APF-authorized STEPLIB (see note below)
Be link-edited with attributes reusable and reentrant.

Note: If the exit resides in the LPALST concatenation or in the LNKLST concatenation, the system automatically considers the exit to be authorized.

See z/OS MVS Initialization and Tuning Reference for more information about the LNKLST concatenation and APF-authorized libraries.

Entry Specifications

APPC/MVS passes information to the syntax exit in registers and in the scheduler extract control block.

Registers on Entry

On entry to the syntax 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 72-byte save area.
GPR 14	The return address.
GPR 15	The entry point address.

Parameter List Contents

Figure 1 illustrates the format and content of the parameter list for the TP profile syntax exit.

Figure 1. Parameter List of the TP Profile Syntax Exit

Return Specifications

Before returning control to its caller, the syntax exit must ensure that the register contents are as follows:

Register	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 decimal return code values: Value Meaning 0 No syntax errors encountered; okay to add or modify profile. 4 Syntax errors encountered; fix before adding or modifying profile. 8 Processing error; could not check profile. 12 System error encountered.