ATBCMCTU - Cleanup_TP (Unauthorized, for MVS/ESA 4.2)

This section describes the Cleanup_TP (ATBCMCTU) advanced callable service provided with MVS/ESA Version 4 Release 2. The Cleanup_TP service was enhanced for MVS/ESA Version 4 Release 2.2, and renamed ATBCUC1 (see Cleanup_TP). The ATBCMCTU call remains valid in MVS/ESA 4.2.2, but does not contain the enhancements included in ATBCUC1. However, if this call is issued against a TP that has active protected conversations, ATBCMCTU will have the same effect on the protected conversations as ATBCUC1 does.

Note: The ATBCUC1 call is the recommended programming interface for this service.

You can call ATBCMCTU from an unauthorized program to request that the APPC component clean up all conversation resources associated with a transaction program instance that is running in the caller's address space. Conversation resources include network resources, control blocks, and buffers which are used by the APPC component to manage the transaction program instance and its conversations.

ATBCMCTU is an unauthorized version of the ATBCMTP service described in z/OS MVS System Messages, Vol 3 (ASB-BPX).

The primary use for ATBCMCTU is to clean up conversation resources left after testing a TP with the Register_Test and Accept_Test services.

The specified TP_ID is deleted from the system as a result of this call, but cleanup processing occurs asynchronously. Conversations with active APPC requests are not immediately deallocated. After the partner TP responds, APPC/MVS returns a deallocate condition and deallocates the conversation.

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:

Unlocked

Control parameters:

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

Format

Figure 1. ATBCMCTU - Cleanup_TP (Unauthorized Version)

  CALL ATBCMCTU (TP_ID,
                Condition,
                Return_Code
               );

Parameters

TP_ID

Supplied parameter

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

Specifies the transaction program instance which is to be cleaned up. All conversations owned by this transaction program instance are to be deallocated.

Condition

Supplied parameter

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

Specifies the deallocation condition that has occurred. This field is used to determine the type of deallocate and sense code that is issued by the APPC component to the partner transaction program.

Valid values for this parameter are:

Value: Meaning
0: Normal
Specifies that the transaction program completed normally, even though it may have left active conversations. The APPC component deallocates all conversations in a proper state for normal deallocation with DEALLOCATE TYPE(SYNC_LEVEL). All conversations not in the proper state for a normal deallocation are deallocated with TYPE(ABEND_SVC).
1: System
Specifies that the transaction program terminated abnormally. All active conversations are deallocated with TYPE(ABEND_SVC).

Note: If the value is not one of the values listed above, 0 (Normal) is used as the default.

Return_code

Returned parameter

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

ATBCMCTU may return one of the following values in the return code parameter:

Decimal Value: Meaning
0: Request accepted. All conversations owned by the transaction program instance will be cleaned up asynchronously.
4: No conversations exist to be cleaned up.
8: The TP_ID parameter specified a nonexistent transaction program instance or a transaction program not in the caller's home address space.
32: The requested service is not supported in the caller's environment. For example, this return code will be given if the caller invokes any of the transaction scheduler services while holding a system lock.
44: APPC/MVS is not active.
48: APPC/MVS services failure.

Restrictions

Transaction programs that call the Cleanup_TP 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.
Regardless of the condition parameter value specified for this service, APPC/MVS cleans up protected conversations differently, depending on whether a syncpoint operation is in progress. When a syncpoint operation is in progress for the current UR for the context with which the protected conversation is associated, APPC/MVS does not immediately deallocate the conversation. The syncpoint operation is allowed to complete. As part of the syncpoint processing, the protected conversation might be deallocated, in which case no further cleanup is required for that conversation.
If the conversation was not deallocated, however, cleanup processing proceeds in the same manner as it does when a syncpoint operation is not in progress at the time the Cleanup service is issued:
- The protected conversation is deallocated with TYPE(ABEND_SVC).
- The current UR is put into backout-required state.
- If the protected conversation is an inbound conversation, the logical unit of work ID (LUWID) for the next UR is reset.
- The current UR and subsequent units of recovery for the context will not include the protected conversation being cleaned up by this service.