Error_Extract

Returns detailed information about errors indicated by APPC/MVS error return codes. Error_Extract provides reason codes and messages that describe errors that the local system finds, and error log information and a product set ID for errors that a remote TP or system finds and reports. Error_Extract returns error information only for the last APPC TP conversation service or CPI Communications call that completed processing for that conversation.

See Diagnosing Problems with APPC/MVS TPs for more information about how to use the Error_Extract service.

Requirements

Authorization:

Supervisor state or problem state, any PSW key

Dispatchable unit mode:

Task or SRB mode

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:

No locks held

Control parameters:

All parameters must be addressable by the caller and in the primary address space.

Format

The figure below shows the syntax of the CALL statement for the Error_Extract service. You must code all parameters on the CALL statement in the order shown.

Figure 1. ATBEES3 - LU 6.2 Error_Extract

CALL ATBEES3(
        Conversation_ID,
        Service_name,
        Service_reason_code,
        Message_text_length,
        Message_text,
        Error_log_product_set_ID_length,
        Error_log_product_set_ID,
        Error_log_information_length,
        Error_log_information,
        Reason_code,
        Return_code
       );

Parameters

The following section describes the parameters you specify when calling the Error_Extract service.

Conversation_ID

Supplied parameter

Type: Character string
Char Set: N/A
Length: 8 bytes

Conversation_ID specifies the conversation ID associated with the conversation for which you want to return problem determination information. The conversation ID, sometimes called a resource identifier, identifies a conversation to the system.

If APPC/MVS cannot establish a conversation, APPC/MVS still assigns a conversation ID to the allocate request. Your application specifies that conversation ID on this parameter.

Service_name

Returned parameter

Type: Character
Char Set: EBCDIC
Length: 8 bytes

Service_name specifies the name of the conversation callable service for which Error_Extract is returning error information. The name appears in the same format in which the call is coded (for example, for a Send request, the name is ATBSEND). Error_Extract returns a value on this parameter only when APPC/MVS returns an error return code to the caller of the service in error.

Service_reason_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 4 bytes

Service_reason_code specifies the reason code for the call to the APPC/MVS conversation service in error (the service specified on the Service_Name parameter). Error_Extract returns a value on this parameter only when Error_Extract receives a zero return code.

Message_text_length

Returned parameter

Type: Integer
Char Set: N/A
Length: 4 bytes

Message_text_length indicates the total number of characters that appear in the message specified on the Message_text parameter. Error_Extract returns a value on this parameter only when APPC/MVS returns an error return code to the caller of the service in error.

Message_text

Returned parameter

Type: Character
Char Set: EBCDIC
Length: 256 bytes

Message_text contains a message that describes an error on the call to the service specified on the Service_name parameter. Your application can write this message to the output stream. Error_Extract returns a value on this parameter only when APPC/MVS returns an error return code to the caller of the service in error. If APPC/MVS is the partner system that supplies this message text, the data returned for this parameter will appear as a message in the format ATB8xxxxI. See Error_Extract (ATB8) Messages for explanations of messages returned by APPC/MVS.

Error_log_product_set_ID_length

Returned parameter

Type: Integer
Char Set: N/A
Length: 4 bytes

Error_log_product_set_ID_length is the length of the value returned on the Error_Log_Product_Set_ID parameter.

If no product set ID information is available from the partner system, APPC/MVS sets the value on this parameter to zero.
If product set ID information is available from the partner system, APPC/MVS sets the value on this parameter to a number from 1 through 256.
If more than 256 bytes of product set ID information is available, APPC/MVS returns only the first 256 bytes of that information.

Error_log_product_set_ID

Returned parameter

Type: Character
Char Set: N/A
Length: 256 bytes

Error_log_product_set_ID identifies the partner product that provided error log information, which is specified on the Error_log_information parameter for this service. APPC/MVS returns a value on this parameter only when the Return_code parameter specifies a zero value and the value returned on the Error_Log_Product_Set_ID_Length parameter is greater than zero. If the product set ID is more than 256 bytes long, APPC/MVS returns only the first 256 bytes of the product set ID.

For information about the format of a product set ID, see the descriptions of the Product Set ID (X'10') and the Product Identifier (X'11') MS Common Subvectors in SNA Formats.

Error_log_information_length

Returned parameter

Type: Integer
Char Set: N/A
Length: 4 bytes

Error_log_information_length specifies the length of the log information received from a partner TP or system. If no error log information is available from the partner TP or system, APPC/MVS sets the value on this parameter to zero.

Error_log_information

Returned parameter

Type: Character
Char Set: N/A
Length: 512 bytes

Error_log_information contains a message that describes an error found by a partner system or TP. APPC/MVS returns a value in this field only when the Error_log_information_length parameter specifies a non-zero value (indicating that APPC/MVS received error log information from a partner TP or system). Error_Extract returns a value on this parameter only when APPC/MVS returns an error return code to the caller of the service in error. If APPC/MVS is the partner system that supplies this error log information, the data returned for this parameter will appear as a message in the format ASBxxxxxI or ATB7xxxxI. See Error_Extract Error Log Information (ASB, ATB7) Messages for explanations of messages returned by APPC/MVS.

Reason_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 4 bytes

Reason_code contains additional information about the result of the call to Error_Extract, when the Return_code parameter contains a value other than zero or 64 (decimal).

See Return and Reason Codes for valid reason codes.

Return_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 4 bytes

Return_code specifies the result of the call to Error_Extract. If the return_code parameter contains zero or 64 (decimal), there is no reason code. For other return codes, check the Reason_code parameter for additional information about the result of the call.

See Return and Reason Codes for valid reason codes.

Return and Reason Codes

When the Error_Extract service returns control to your program, the Return_code and Reason_code parameters contain one of the following sets of values:

Return Code (decimal)	Reason Code (decimal)	Meaning and Action
0	—	Meaning: The call completed successfully. System Action: The system continues processing. Application Programmer Response: None required.
4	42	Meaning: A TP called the Error_Extract service to return information for an APPC/MVS service that Error_Extract does not support. System Action: Error_Extract does not return any error information for the specified conversation. Application Programmer Response: Ensure that your TP calls Error_Extract for a supported MVS TP conversation service or CPI Communications call that receives an error return code. Also ensure that the conversation ID specified on the call to Error_Extract is the same as the conversation ID specified on the call to the service that received the error return code.
8	22	Meaning: The conversation ID specified on the call to Error_Extract is not valid. System Action: Error_Extract does not return any error information for the specified conversation. Application Programmer Response: Validate that the conversation ID is the same as the conversation ID specified on the call to the service in error. If so, validate that the conversation was not deallocated normally. If the problem persists, ensure that the address space from which the Error_Extract was called was not cleaned up.
16	8	Meaning: The caller held one or more locks when it called Error_Extract. System Action: Error_Extract does not return any error information for the specified conversation. Application Programmer Response: Issue the SETLOCK assembler macro to release all held locks held before calling Error_Extract.
32	16	Meaning: An internal error occurred in APPC/MVS. System Action: Error_Extract does not return any error information for the specified conversation. Application Programmer Response: Ask the system programmer to contact the IBM Support Center. Tell the system programmer to provide the Support Center with the record that APPC/MVS writes to the logrec data set.
64	—	Meaning: APPC/MVS is not active. System Action: Error_Extract cannot return any error information for the specified conversation. Application Programmer Response: Ask the operator to enter a START APPC command to start APPC/MVS.

Restrictions

Programs that call the Error_Extract 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.