Extract_Information

Extract_Information is a generalized service that you can use to extract detailed information about the conversations and scheduling of active APPC/MVS transaction programs. Extract_Information returns information that is not available from the Get_Attributes, Get_TP_Properties, or CPI Communications Extract_* calls.

Categories of Information

You can extract two categories of information: scheduling and conversation information, as specified by the Extract_code parameter.

Scheduling Information: The scheduling information that Extract_Information returns depends on the transaction scheduler under which the TP is running:

When the transaction program is running under the APPC/MVS transaction scheduler, you can use Extract_Information to obtain the TP schedule type (standard or multi-trans) and additional information such as the transaction initiator class and times and dates when the TP was scheduled and initiated.
When you request scheduling information for a TP running under another transaction scheduler, that scheduler's extract exit is called to return the requested information. The exit must provide whatever data is required by its published interface. Other transaction schedulers may provide their own format of data or give a return code indicating that no data is provided or that an error occurred. For information about providing an extract exit for a transaction scheduler, see z/OS MVS System Messages, Vol 3 (ASB-BPX).

APPC Conversation Information: When you request APPC conversation information, you might be required to provide a value for the Qualifier_type or Qualifier_value parameter, or both, to indicate whether the request is for information about the caller's own conversation, or the conversation of another transaction program instance (TP_ID), or a specific conversation_id. The caller must be in supervisor state or PSW key 0-7 to:

Request information about a specific TP_ID.
Request information about a specific conversation_id that is not associated with the caller's address space.

When you specify extract_code X'0000' (summary conversation information), the service extracts the following conversation information for the transaction program indicated by Qualifier_type and Qualifier_value:

Total number of conversations.
The total number of conversations associated with the TP_ID, currently active or deallocated. This includes the inbound conversation that might have started the TP, later inbounds that were processed (if the TP is a multi-trans), and all conversations started by issuing an Allocate call.
Total number of allocated conversations (started by a CMALLC or Allocate call).
Total number of Sends (CMSEND and Send_Data calls).
Total amount of data (number of characters of data) sent from the program's send buffers.
Total number of Receives (CMRCV, Receive_Immediate, and Receive_and_Wait calls).
Total amount of data (number of characters of data) received by the program's receive buffers.
Total number of currently active conversations (not deallocated or disconnected).

When you specify extract_code X'0001' (specific conversation information), the service extracts the conversation information shown in Contents of the Extract Buffer for the conversation_id indicated by Qualifier_value.

Requirements

Authorization:

Supervisor state or problem state, any PSW key (see Characteristics and Restrictions).

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31-bit

ASC mode:

Primary or access register (AR)

Interrupt status:

Enabled for I/O and external interrupts

Locks:

Unlocked

Control parameters:

All parameters must be addressable by the caller and in the primary address space, except for the buffer parameter

Format

Figure 1. ATBEXAI - Information Extract Service

CALL ATBEXAI(
        Extract_code,
        Qualifier_type,
        Qualifier_value,
        Access_token,
        Buffer_length,
        Buffer,
        Return_code
       );

Parameters

Extract_code

Supplied parameter

Type: Integer
Length: 32 bits

Specifies the code that identifies the unique information required by the calling program. For TPs running under the APPC/MVS transaction scheduler, specify one of the following values (right-justified):

Extract_code = X'1000': complete scheduling information
Extract_code = X'1001': scheduler name and schedule type only
Extract_code = X'0000': summary conversation information
Extract_code = X'0001': specific conversation information.

For TPs processed by an APPC/MVS server, specify one of the following values:

Extract_code = X'0000': summary conversation information
Extract_code = X'0001': specific conversation information.

For TPs running under other transaction schedulers, you can specify an extract code value in the range X'1000' through X'1FFF' depending on which values the scheduler supports.

Qualifier_type

Supplied parameter

Type: Integer
Length: 32 bits

If you request scheduling information (Extract_code = X'1000' - X'1FFF'):

The APPC/MVS transaction scheduler ignores any values for this parameter.
Other transaction schedulers may accept values for this parameter; for TPs running under another transaction scheduler, any value you specify is passed as input in the EXTRACT_QUALTYPE field to the transaction scheduler extract exit.

If you request summary conversation information (Extract_code = X'0000'), the following values are acceptable:

Qualifier_type = 0
Specifies conversation information about the caller. Qualifier_value should be ignored.
Qualifier_type = 1
Specifies conversation information about a specified TP_ID. Qualifier_value must be the specified TP_ID. To use this value of Qualifier_type, the caller must be in supervisor state or PSW key 0-7.

If you request conversation-specific information (Extract_code = X'0001'), APPC/MVS ignores the Qualifier_type.

Qualifier_value

Supplied parameter

Type: Character
Char Set: No restriction
Length: 8 bytes

The meaning of Qualifier_value is determined by the values you specify for Extract_code and Qualifier_type. Depending on those values, APPC/MVS treats Qualifier_value as follows:

If you request complete scheduling information (Extract_code = X'1000'), Qualifier_value is ignored.
If you request summary conversation information (Extract_code = X'0000'), the value in Qualifier_value is determined by the value you specify for Qualifier_type.
If you request specific conversation information (Extract_code = X'0001'), Qualifier_value contains the identifier of the conversation (conversation_id) for which information is to be extracted. To request information about a conversation_id that is not associated with the caller's address space, the caller must be in supervisor state or PSW key 0-7.

When specified with a valid scheduler Extract_code for TPs running under another transaction scheduler, any value is passed as input in the EXTRACT_QUALTYPE field to the transaction scheduler extract exit.

Access_token

Supplied parameter

Type: Integer
Length: 32 bits

Access_token specifies the Access List Entry Token (ALET) of the address space or data space in which the buffer resides for Information_Extract calls.

APPC/MVS always uses Access_token together with the address of the buffer to resolve addressing to the transaction program's data. To specify that the buffer address passed should not be ALET qualified, an Access_token value of zero should be supplied. APPC/MVS will then consider the buffer to reside in the primary address space of the caller.

The Access_token can:

Represent an entry on the dispatchable unit access list (DU-AL)
Represent an entry on the caller's primary address access list (PASN-AL), only if the entry points to a SCOPE=COMMON data space.

The Access_token cannot:

Be the value 1 (which indicates "secondary ASID")
Represent an entry on the caller's PASN-AL that does not point to a SCOPE=COMMON data space.

For more information about ALETs for SCOPE=COMMON data spaces, see Features of the MVS-Specific Services.

Buffer_length

Supplied/Returned parameter

Type: Integer
Length: 32 bits

Specifies the length of the buffer where the information is to be returned.

Buffer_length will be updated to indicate the actual amount of the buffer used to return the data. This will be less than or equal to the Buffer_length that was supplied.

Buffer

Returned parameter

Type: Character string
Char Set: No restriction
Length: 0-32767 bytes

Specifies the buffer to contain extracted data. For information on the format of the extracted data that is returned, see Contents of the Extract Buffer.

Return_code

Returned parameter

Decimal Value

Description

0

Successful processing.

4

Buffer length too small. Only partial information is returned.

8

No information is returned for one of the following reasons:

The caller is not a transaction program
No transaction program was executing in the specified address space
No scheduler extract exit was defined for the scheduler of this transaction program.

12

The Extract_code was incorrect or unsupported.

16

Extract_Information service failure.

20

The caller is disabled or holds a lock.

28

An incorrect version of ATBATP was used to call Extract_Information.

36

The calling program specified incorrect or inconsistent parameters, or parameters it was not authorized to use.

44

APPC/MVS is not active.

48

The Qualifier_value was not valid.

Characteristics and Restrictions

The caller must be in supervisor state or PSW key 0-7 to do the following:
- Request summary conversation information (Extract_code = X'0000') about a specific TP_id (Qualifier_type = 1)
- Request information about a specific Conversation_id that is not associated with the caller's address space.
A program requiring information for a particular TP_id must extract it before the TP is terminated (Cleanup_Address_Space call is issued). Conversation information must be extracted before the conversation is deallocated. APPC conversation information is kept in real time and not logged by APPC/MVS.
The totals for conversation information are running totals (they are not reset after extraction). This service does not change or alter the contents of the data extracted.
Transaction programs that call the Extract_Information service while in task mode should not have any enabled unlocked task (EUT) functional recovery routines (FRRs) established. For more information about EUT FRRs, see the section on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide.

Contents of the Extract Buffer

Use the following mapping macros for the format and contents of the information extract buffer when Extract_Information is called with the extract codes supported by the APPC/MVS transaction scheduler. These mapping macros are documented in z/OS MVS Data Areas, Vol 1

For this type of extracted information:	Requested through extract code value:	Use this mapping macro:
Complete scheduling information	X'1000'	ATBEXSCH
Scheduler name and type only	X'1001'	ATBEXSCH
Summary conversation information	X'0000'	ATBEXCON
Specific conversation information	X'0001'	ATBEXCOS

For Summary Conversation Information (Extract Code X'0000')

There is no restriction on the largest number that the conversation totals can accumulate. To accommodate multi-trans programs that are started and stay in execution, each count in the “Total amount of data sent” and “Total amount of data received” fields is returned as a normalized, long floating point number in the form X'eekhhhhh hhhhhhhh', where:

‘ee’ consists of a ‘0’ sign bit followed by a 7-bit characteristic (in excess 64 notation)
‘khhhhh hhhhhhhh’ is a normalized hexadecimal fraction in which:
- ‘k’ represents a hexadecimal digit in the range 1-F (except when the floating point value is a “true zero”), and
- Each ‘h’ represents a hexadecimal digit in the range 0-F.

When the hexadecimal value is 0, a “true zero” (X'00000000 00000000') is returned as the floating point representation.

Some examples of typical values returned are:

Packed-decimal representation	64-bit binary representation	Normalized Long FP representation
000000000000000C	0000000000000000	0000000000000000
000000000001000C	00000000000003E8	433E800000000000
000000000002048C	0000000000000800	4380000000000000
999999999999999C	00038D7EA4C67FFF	4D38D7EA4C67FFF0

For Specific Conversation Information (Extract Code X'0001')

Some of the information returned in the extract buffer is:

EXCOS_PLU_LOCATION, which indicates whether the partner LU resides on this system (local) or another system in the network (remote). The possible values are:
0

APPC/MVS could not yet determine the location of the partner LU

1

Remote

2

Local
EXCOS_CONV_KIND, which, for inbound conversations, indicates whether the conversation was processed by an APPC/MVS server or not (probably because a transaction scheduler processed the inbound conversation). For outbound conversations, this field always contains a zero. The possible values are:
0

Not processed by an APPC/MVS server

1

Processed by an APPC/MVS server.
EXCOS_SCHED_NAME, which is the scheduler name. This field contains blanks for conversations not processed by a transaction scheduler, such as:
- Inbound conversations processed by an APPC/MVS server
- Outbound conversations from address spaces not associated with a transaction scheduler (such as a TSO/E user or a batch job).
EXCOS_TP_NAME, which is the name of the partner TP. If the conversation is inbound, this field contains blanks.
EXCOS_LOCAL_TP_NAME, which is the name of the local TP. If the conversation is outbound, this field contains the name of the program that initiated the conversation (through the Allocate service). If the conversation is inbound, this field contains the name of the program that was attached on this LU because of an Allocate call.
EXCOS_CONV_START_TIME:
- For inbound conversations, this field contains the date and time APPC/MVS routed the conversation to an address space for subsequent processing. For conversations processed by APPC/MVS servers, this is when the server received the conversation from an allocate queue (through the Receive_Allocate service). For scheduled conversations, this is when the transaction scheduler directed the allocate request to an initiator address space for processing.
- For outbound requests, this field contains the date and time the local program called the Allocate service to initiate a conversation.
This information appears in the format provided by the STORE CLOCK (STCK) assembler instruction.
EXCOS_LAST_SERVICE_RETURN_CODE, which is the last return code received from a callable service during this conversation. If the return code indicated a product-specific error (decimal 20), the next field in this buffer contains the reason code for the error.
EXCOS_URID, which is the unit of recovery identifier for a protected conversation (conversation with a synchronization level of syncpt).