Environment

Format

CALL ATBCMTP (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 that is to be cleaned up. The transaction program instance does not have to be associated with the caller's address space. 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 APPC/MVS 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 might have left active conversations. APPC/MVS 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, or the transaction program was terminated on behalf of some action by the system (for example, the address space was cancelled or forced). This condition is normally detected by the transaction scheduler's subordinate address space. All active conversations are deallocated with Type(Abend_SVC).

2

TP_Not_Available_No_Retry

Specifies that the transaction scheduler is not able to schedule the transaction because of a condition that is not temporary. The partner should not attempt to retry the request. APPC/MVS deallocates the conversation with a sense code of X'084C0000'.

3

TP_Not_Available_Retry

Specifies that the transaction scheduler is not able to schedule the transaction because of a condition that might be temporary. The partner might attempt to retry the request. APPC/MVS deallocates the conversation with a sense code of X'084B6031'X.

4

TPN_Not_Recognized

Specifies that the transaction scheduler does not recognize the TP_Name passed to it. APPC/MVS deallocates the conversation with a sense code of X'10086021'.

5

Security_Not_Valid

Specifies that the transaction scheduler detected a security violation. APPC/MVS deallocates the conversation with a sense code of X'080F6051'.

6

Sync_Level_Not_Supported_Pgm

Specifies that the transaction program does not support the level of synchronization requested by the sender. APPC/MVS deallocates the conversation with a sense code of X'10086041'.

Return_code

Returned parameter

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

Cleanup_TP might return one of the following decimal values in the return code parameter:

Decimal

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.

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 lock.

44

APPC/MVS is not active.

48

APPC/MVS services failure.

Characteristics and Restrictions

1. Conversations with active APPC requests are not immediately deallocated. Once the partner TP responds, APPC/MVS returns a deallocate condition and deallocates the conversation locally.
2. The Condition parameter defaults to zero (normal) if the specified condition is not valid.
3. If you call the Cleanup_TP service while a unit of work is waiting on an ECB as a result of an asynchronous call, APPC/MVS does not post the ECB after performing the Cleanup_TP operation (APPC/MVS considers all resources associated with the TP “terminated”). The application's recovery environment must clean up the waiting ECB.
4. Transaction schedulers that call the Cleanup_TP service while running in task mode should not have any enabled unlocked task (EUT) functional recovery routines (FRRs) established. For more information about EUT FRRs, see the information on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide.
5. 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.