Extract Exit

Extract Exit

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

The transaction scheduler extract exit is an optional exit invoked by APPC/MVS to perform one of the following two functions:

Provide information requested by a call to the Extract_Information service (ATBEXAI). When a transaction program calls ATBEXAI for information about how it was scheduled, the appropriate transaction scheduler extract exit is driven. The output from this exit is defined by the transaction scheduler. If the exit is not supplied by the transaction scheduler, the transaction program receives a return code indicating that no information was returned.
The extract exit is also invoked when APPC/MVS needs to determine which transaction program is requesting APPC services. The extract exit is invoked for this reason only when the request is coming from an address space that has more than one TP_ID associated with it, (namely, a transaction scheduler address space). The extract exit is driven to allow the transaction scheduler to specify a TP_ID. It is used when a transaction program in the transaction scheduler address space, or when the transaction scheduler issues one of the following service calls:
- Allocate (unless a TP_ID is specified)
- Get_TP_Properties
- Get_Conversation
The exit is invoked only when there are two or more TPs associated with the address space.

The extract exit for a transaction scheduler is established when the transaction scheduler invokes the Identify service. If the transaction scheduler does not supply this exit, requests from the transaction scheduler address space for the above service calls are rejected when more than one TP_ID is associated with the address space. If any of the above service calls are issued from the scheduler address space in SRB mode, the exit will need a mechanism to determine the TP_ID when a TCB is not available.

Environment

The transaction scheduler extract exit is given control on the same dispatchable unit that invoked the particular service: Allocate, Get_TP_Properties, Get_Conversation, or Extract_Information. Note that these services support SRB mode callers. Therefore, if the service is invoked from the transaction scheduler address space in SRB mode, the exit is driven in SRB mode as well, and is restricted in the services that it can issue. For example, the exit cannot issue SVCs, nor issue a WAIT or SUSPEND macro, because the exit might be invoked on the synchronous path of an asynchronous service.

The exit receives control in the following environment:

Authorization:

Supervisor state and PSW key 1

Dispatchable unit mode:

Task or SRB

Cross memory mode:

PASN = APPC, HASN = caller's HASN, SASN = caller's PASN

AMODE:

31-bit

ASC mode:

Primary

Storage key:

Interrupt status:

Enabled

Locks:

The exit does not hold any locks on entry.

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 the storage that 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

This exit must reside in common storage.
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.

Entry Specifications

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

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 a one-word parameter list that contains the address of the scheduler extract control block.
GPRs 2-15	Do not contain any information for use by the exit.

Scheduler Extract Control Block

The scheduler extract control block is in key 1 storage, so its contents are immediately accessible by the exit. The scheduler exit control block contains a service indicator that the exit can use to determine what processing needs to be done:

Indicator: Meaning
Get_Info: The extract exit was invoked to supply information requested by a caller of the Extract_Information service.
Get_TP_ID: The extract exit was invoked because APPC/MVS could not determine which TP_ID to use for a service call.

The scheduler extract exit control block is mapped by the ATBSECB mapping macro; for detailed information about all of the fields in ATBSECB, see z/OS MVS Data Areas, Vol 1.

Return Specifications

On return, the extract exit does not have to place any information in the GPRs. However, depending on the service indicator, the extract exit must place values in certain fields before returning to its caller:

For a Get_Info call, the scheduler exit control block contains the address of a temporary buffer in which the extract exit should return whatever data is required by its published interface.
The extract exit also must set the Return_Code field to one of the values that APPC/MVS returns for the Extract_Information service.
For a Get_TP_ID call, the scheduler exit control block contains a TP_ID field in which the extract exit should return the appropriate transaction program ID; that is, the ID passed to the transaction scheduler on either the inbound Allocate TP request message or the Define_Local_TP service.
The extract exit also must set the Return_Code field to zero (to indicate successful processing) or any non-zero value (to indicate a failure).