Get_Conversation

Equivalent to:
  • (No LU 6.2 equivalent)
  • CPI Accept_Conversation (CMACCP)

To be used by an allocated TP to return the conversation ID that the TP will use to reference the conversation on which it was attached, and also to return information pertaining to the specified conversation.

Get_Conversation cannot be issued once activity has begun on the conversation. It is only allowable as the very first call issued for the conversation. After a call has been issued on the conversation, subsequent calls to the Get_Conversation service will return a return code of Program_State_Check.

Requirements

Format

Figure 1. ATBGETC - Get_Conversation
CALL ATBGETC(
        Conversation_id,
        Conversation_type,
        Partner_LU_name,
        Mode_name,
        Sync_level,
        Conversation_correlator,
        Return_code
       );

Parameters

Conversation_id
Returned parameter
  • Type: Character string
  • Char Set: No restriction
  • Length: 8 bytes

Conversation_id, sometimes called the resource identifier, identifies a conversation to the system.

Conversation_type
Returned parameter
  • Type: Integer
  • Char Set: N/A
  • Length: 32 bits

Conversation_type specifies the type of conversation on which the call is issued.

Valid values for this parameter are:
Value
Meaning
0
Basic_conversation
1
Mapped_conversation
Partner_LU_name
Returned parameter
  • Type: Character string
  • Char Set: Type A
  • Length: 17 bytes

Partner_LU_name specifies the name of the LU at which the partner program is located.

The value returned for Partner_LU_name is the network-qualified name of the partner logical unit. The network-qualified name consists of two Type A character strings that represent the network ID and network LU name, respectively. Both strings are between 1 and 8 bytes in length, concatenated together by a period: network_ID.network_LU_name.

If the partner LU is a member of a generic resource group, the network-LU-name portion of Partner_LU_name might be the 1- to 8-byte generic resource name of the group.

Mode_name
Returned parameter
  • Type: Character string
  • Char Set: Type A
  • Length: 8 bytes

Mode_name specifies the mode name designating the network properties for the session to be allocated for the conversation. The network properties include, for example, the class of service to be used.

If Mode_name is less than 8 bytes in length, it is padded on the right with blanks.

Sync_level
Returned parameter
  • Type: Integer
  • Char Set: N/A
  • Length: 32 bits

Sync_level specifies the synchronization level that the local and partner programs can use on this conversation.

Valid values for this parameter are:
Value
Meaning
0
None

Specifies that the programs will not perform confirmation processing on this conversation. The programs will not issue any protocol boundary calls and will not recognize any returned parameters relating to synchronization functions.

1
Confirm

Specifies that the programs can perform confirmation processing on this conversation. The programs may issue protocol boundary calls and will recognize returned parameters relating to confirmation.

2
Syncpt

Specifies that the programs can perform sync point processing on this conversation. The programs can call services and will recognize returned parameters relating to sync point processing.

Conversation_correlator
Returned parameter
  • Type: Character string
  • Char Set: N/A
  • Length: 8 bytes

Conversation_correlator specifies further qualification of the LU work identifier (LUW_id) and helps restore protected resources to a consistent state following the failure of an LU, session, or conversation.

If there is no conversation correlator for the conversation, this field contains all binary zeroes.

Return_code
Returned parameter
  • Type: Integer
  • Char Set: N/A
  • Length: 32 bits

Return_code specifies the return code that is returned to the local program. In cases where an error code is returned, the program should not examine any other returned variable associated with the call as nothing is placed in the variables.

See Return Codes for descriptions of return codes that can be returned to a caller of Get_Conversation.

Return Codes

Valid return code values for the Return_code parameter are:

Table 1. Return Codes for the Get_Conversation Service
Return Code Value, Meaning, and Action
0 Value: OK

Meaning: The call completed successfully.

System Action: The system continues processing.

Application Programmer Response: None required.
20 Value: Product_specific_error

Meaning: The system found a product-specific error.

System Action: The system might write symptom records, which describe the error, to the logrec data set.

Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format. If necessary, see Diagnosing Product-Specific Errors for more information about product-specific errors.
25 Value: Program_state_check

Meaning: The local TP called a service while running in a state in which the call is not valid. The TP should not examine any other returned variables associated with the call because nothing is placed in those variables.

System Action: The state of the conversation remains unchanged. For a list of states that are valid for each call, see APPC/MVS Conversation State Table. The conversation was in send state and the TP started, but the TP did not finish sending a logical record.

Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format.

Restrictions

Transaction programs that call the Get_Conversation 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.

Parent topic: APPC/MVS TP Conversation Callable Services