Note: You cannot use the Error_Extract conversation service to diagnose
errors in calls to the Get_TP_Properties service.
Equivalent to:
- LU 6.2 Get_TP_Properties
- (No CPI equivalent)
Returns information pertaining to the transaction program issuing
the call.
This service requires TP resources to be associated with the calling
address space to complete successfully. This service should be issued
after issuing one of the following services that will associate TP
resources to the calling address space:
- CMINIT
- Allocate
- Register_For_Allocate
- Define_Local_TP
This service may also be issued:
- After the transaction scheduler XCF message user routine has received
an Allocate TP request message to obtain information pertaining to
the transaction program represented by the received message.
- When an application program begins executing as the result of
a transaction scheduler receiving and processing an Allocate TP request.
- Before the Get_Conversation or CPI Accept_Conversation (CMACCP)
services.
Requirements
Authorization: |
Supervisor state or problem state, any PSW key |
Dispatchable unit mode: |
Task or SRB mode |
Cross memory mode: |
PASN = HASN = SASN or PASN ¬= HASN ¬= 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. ATBGTP4
- LU 6.2 Get_TP_PropertiesCALL ATBGTP4(
Own_TP_name_length,
Own_TP_name,
Own_fully_qualified_LU_name,
User_id,
Profile,
LUW_id,
Vote_Read_Only_Permitted,
Wait_For_Outcome,
Action_If_Problems,
Return_code
);
Parameters
- Own_TP_name_length
- Returned parameter
- Type: Integer
- Char Set: N/A
- Length: 32 bits
Own_TP_name_length specifies the length of data contained
in the Own_TP_name parameter. If the Own_TP_name parameter does not
contain a TP_name on return from this service, Own_TP_name_length
is set to zero.
- Own_TP_name
- Returned parameter
- Type: Character string
- Char Set: 00640 or Type A
- Length: 64 bytes
Own_TP_name specifies the name of the local program as specified
in the FMH-5 allocation request. This parameter will only contain
a return value if the local program was started as the result of an
attach request from a partner program. If this is not the case, there
is no TP name to be returned, and Own_TP_Name_Length is set to zero.
- Own_fully_qualified_LU_name
- Returned parameter
- Type: Character string
- Char Set: Type A
- Length: 17 bytes
Own_fully_qualified_LU_name specifies the network-qualified
name of the local logical unit.
- User_id
- Returned parameter
- Type: Character string
- Char Set: No restriction
- Length: 10 bytes
User_id specifies the userid that is associated with the
caller's address space. If the address space contains a scheduled
transaction program, the User_id parameter contains the userid that
accompanied the inbound transaction program request.
- Profile
- Returned parameter
- Type: Character string
- Char Set: No restriction
- Length: 10 bytes
Profile specifies the RACF group name associated with the
caller's address space. If the address space contains a scheduled
transaction program, the profile parameter contains the RACF group
name that accompanied the inbound transaction program request. If
the inbound request did not include a profile, the profile parameter
contains the default profile for the transaction program that issued
the request.
- LUW_id
- Returned parameter
- Type: Structure
- Char Set: N/A
- Length: 26 bytes
LUW_id specifies the logical unit of work (LUW) identifier.
The LUW identifier is used by some logical units for accounting purposes.
If no LUW identifier is present, this field will contain binary zeroes.
Note: A LUW_id for protected resources (such as a protected conversation)
is called a protected LUW_id. Because a TP might have more than one
protected LUW_id associated with it, APPC/MVS does not return a protected
LUW_id in this parameter, even if one exists and no LUW_id for unprotected
resources exists. To obtain the protected LUW_id of a protected conversation,
use the Get_Attributes service.
- Vote_Read_Only_Permitted
- Returned parameter
- Type: Integer
- Char Set: N/A
- Length: 32 bits
Vote_Read_Only_Permitted specifies whether the local LU
may vote read only in a sync point operation. This syncpt option can
be set by calling the Set_Syncpt_Options service.
Possible
returned values for this parameter are:
- Value
- Meaning
- 1
- NO
Specifies that voting read only in a sync point operation
is not allowed.
- 2
- YES
Specifies that voting read only in a sync point operation
is allowed.
- Wait_For_Outcome
- Returned parameter
- Type: Integer
- Char Set: N/A
- Length: 32 bits
Wait_For_Outcome specifies whether the outcome of the sync
point operation at all subordinate resources in the distributed transaction
must be known before control is returned to the program. This syncpt
option can be set by calling the Set_Syncpt_Options service.
Possible
returned values for this parameter are:
- Value
- Meaning
- 1
- NO
Specifies that the transaction program need not wait for
the outcome of the syncpoint before regaining control.
- 2
- YES
Specifies that the transaction program must wait for the
outcome of the syncpoint before regaining control.
- Action_If_Problems
- Returned parameter
- Type: Integer
- Char Set: N/A
- Length: 32 bits
Action_If_Problems specifies the action to be taken with
protected resources if the LU learns of a problem at a point in the
sync point operation when it does not know whether to commit or backout.
This syncpt option can be set by calling the Set_Syncpt_Options service.
Possible
returned values for this parameter are:
- Value
- Meaning
- 1
- Commit
Specifies that the transaction program should commit
its resources in the event of a problem where it is unsure whether
it should commit or backout,
- 2
- Backout
Specifies that the transaction program should backout
its resources in the event of a problem where it is unsure whether
it should commit or backout,
- 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_TP_Properties.
Return Codes
Valid return
code values for the Return_code parameter are:
Table 1. Return Codes for the Get_TP_Properties ServiceReturn 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 Product-Specific Errors for
more information about product-specific errors.
|
25 |
Value: Program_state_check Meaning: The program called a service
under conditions in which the call is not valid; for example: - APPC/MVS might not recognize the program as a local TP.
- APPC/MVS might have encountered temporary environmental conditions
that prevent it from obtaining the requested information.
The program 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.
Application
Programmer Response: Design the program to re-issue
the call; this error condition might be temporary.
|
Restrictions
Transaction programs that
call the Get_TP_Properties 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.