Get_Attributes

Related to:

LU 6.2 (MC_)Get_Attributes
CPI Communications Extract_Conv_State (CMECS), Extract_Mode_Name (CMEMN), Extract_Part_LU_Name (CMEPLN), Extract_Sync_Level (CMESL)

Call the Get_Attributes service to determine certain attributes of the conversation specified by the conversation specified by the Conversation_ID parameter. This service is most useful when issued for an inbound conversation; the returned parameters provide important information about the attributes with which the conversation was allocated. Some of the data returned by Get_Attributes can be obtained only through this service. However, several fields provide information that is also available from other APPC/MVS services. For example, you can determine the conversation_type returned by Get_Attributes by calling the Get_Type service.

Requirements

Authorization:

Supervisor state or problem state, any PSW key

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.

Format

Figure 1. ATBGTA6 —LU 6.2 Get_Attributes

CALL ATBGTA6(
        Conversation_id,
        Partner_LU_name,
        Mode_name,
        Sync_level,
        Conversation_correlator,
        LUW_id,
        TP_name_length,
        TP_name,
        Local_LU_name,
        Conversation_type,
        User_id,
        Profile,
        User_token,
        Conversation_state,
        Total_timeout_value
        Return_code
       );

Parameters

Conversation_id

Supplied parameter

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

Conversation_ID specifies the conversation ID of the conversation for which you want to time VTAM APPCCMD requests issued during APPC/MVS conversation callable services. Specify the conversation_id that was returned from the Allocate, CMINIT, CMACCP, Get_Conversation. or Receive_Allocate call.

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 Partner_LU_name can be one of the following:

A VTAM generic resource name
If the partner LU is a member of a generic resource group, the Partner_LU_name might be the 1- to 8-byte generic resource name of the group.
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. The network-LU-name portion may be a VTAM generic resource name, or a specific LU name.
A Type A character string that is 1 to 8 bytes in length. This string represents the network LU name.

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
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 binary zeroes.

LUW_id

Returned parameter

Type: Structure
Char set: N/A
Length: 26 bytes

LUW_id contains the logical unit of work (LUW) identifier. The LUW identifier is used by some logical units for accounting purposes. If the value returned on the Sync_level parameter is syncpt, a protected LUW_id is returned in this parameter. If no LUW identifier is present, this field contains binary zeroes.

TP_name_length

Returned parameter

Type: Integer
Length: 32 bits

TP_name_length contains the length of the data in the TP_name parameter. If the conversation_id parameter specifies an outbound conversation, this field is set to zero.

TP_name

Returned parameter

Type: Character string
Char Set: 00640 or Type A (Type A if the partner TP is protected by RACF)
Length: 1-64 bytes

When the conversation_id parameter specifies an inbound conversation, TP_name contains the name of the local TP for this conversation. If you called the Register_For_Allocates service to become a server of inbound allocate requests, this parameter contains the TP name specified in the FMH-5 that contained the request. When the conversation_id parameter specifies an outbound conversation, this field is not set.

Local_LU_name

Returned parameter

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

Local_LU_name specifies the name of the local LU from which the conversation is initiated.

Conversation_type

Returned parameter

Type: Integer
Length: 32 bits

Conversation_type specifies how the data sent on this conversation is to be formatted.

Valid values for this parameter are:

Value: Meaning
0: Basic_conversation
Specifies that, in this conversation, the calling program and its partner will format their data into separate logical records before sending it. Each record begins with a 2-byte length field (LL) that specifies the amount of data in the record.
1: Mapped_conversation
Specifies that, in this conversation, the calling program and its partner will rely on APPC to format the data they send.

User_id

Returned parameter

Type: Character string
Char Set: No restriction (Type A if APPC/MVS manages the partner LU)
Length: 10 bytes (left-justified if the user ID is less than 10 bytes)

If the Conversation_id parameter specifies an inbound conversation, User_id returns the user ID associated with the inbound allocate request. If the Conversation_id parameter specifies an outbound conversation, this field contains blanks.

Profile

Returned parameter

Type: Character string
Char Set: No restriction (Type A if APPC/MVS manages the partner LU)
Length: 10 bytes (left-justified if the profile name is less than 10 bytes)

If the Conversation_id parameter specifies an inbound conversation, profile contains the RACF group name associated with the inbound allocate request. When the Conversation_id parameter specifies an outbound conversation, this field contains blanks.

User_token

Returned parameter

Type: Structure
Char Set: N/A
Length: 80 bytes

If the Conversation_id parameter specifies an inbound conversation, User_token contains the RACF UTOKEN that identifies the user associated with the inbound allocate. This token is encrypted.

If the conversation_id parameter specifies an outbound conversation, this field is blanks. No UTOKEN is returned for an outbound conversation.

Conversation_state

Returned parameter

Type: Integer
Length: 32 bits

Conversation_state specifies the current state of the conversation, which is one of the following:

Value: Conversation State
2: Initialize
3: Send
4: Receive
5: Send-Pending
6: Confirm
7: Confirm-Send
8: Confirm-Deallocate
9: Defer-Receive
10: Defer-Deallocate
11: Sync-Point
12: Sync-Point-Send
13: Sync-Point-Deallocate

For descriptions, see APPC/MVS TP Conversation States.

Total_Timeout_Value

Returned parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Specifies IN SECONDS the APPC conversational timeout value that was set for this conversation. This timeout value may have been set by either the Allocate or Set_Timeout Service earlier. If set, this paramater combines the Timeout_Value_Minutes and Timeout_Value_Seconds values together. The minimum value to be returned is zero (the timer has not been set or has been reset off). The maximum value that can be returned is 86459 seconds (Timeout_Value_Minutes maximum value + Timeout_Value_Seconds maximum value, converted into seconds).

Return_code

Returned parameter

Type: Integer
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_Attributes.

Return Codes

Valid return code values for the Return_code parameter are:

Table 1. Return Codes for the Get_Attributes 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.
24	Value: Program_parameter_check Meaning: The system detected a program parameter check. System Action: The system returns this return code to the caller of the APPC service in error. 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.
100	Value: Take_backout Meaning: This value is returned only when all of the following conditions are true: The Sync_level is set to syncpt. The conversation is not in Initialize state. The program is using protected resources that must be backed out. System Action: The system returns this return code to the caller of the service. Application Programmer Response: Before it can use this conversation or any other protected conversations associated with the current context again, the local TP must issue a Backout call to restore all protected resources to their status as of the last synchronization point.

Restrictions

TPs that call the Get_Attributes 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.