ATBCMAS— Cleanup_Address

Note: The ATBCAS1 call is the preferred programming interface for this service.

Cleanup_Address_Space can be used to request APPC/MVS to clean up all APPC/MVS resources for an address space. APPC/MVS cleans up all conversation resources for all transaction programs that are associated with the address space at the time the Cleanup_Address_Space was issued.

The Cleanup_Address_Space service can be invoked by a transaction scheduler subordinate address space for a transaction program or job that terminates normally or abnormally.

APPC/MVS deletes the TP_ID or TP_IDs from the system as a result of this call; this cleanup process might occur asynchronously.

Environment

Authorization:

Supervisor state or PSW key 0-7

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. ATBCMAS - Cleanup_Address_Space Service

CALL ATBCMAS (ASCB_ptr,
              Condition,
              Return_code
             );

Parameters

ASCB_ptr

Supplied parameter

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

Specifies the pointer to the address space control block (ASCB) for the address space to be cleaned up. All conversations for all transaction program instances associated with this address space are to be deallocated. Invokers of this service can get this value from the PSAAOLD field in the PSA for the current address space or from the RMPLASCB field in the RMPL, resource manager parameter list. If this parameter is set to zero, the home address space of the program that issued the Cleanup_Address_Space call will be used as the default address space.

Condition

Supplied parameter

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

Specifies the deallocation condition that has occurred. This field is used to generate 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).

Return_code

Returned parameter

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

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

Decimal: Meaning
0: Request accepted. All conversations owned by the address space are cleaned up asynchronously.
4: No conversations exist to be cleaned up.
8: The ASCB_ptr supplied does not point to a valid ASCB.
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

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.
When no APPC resources are to be cleaned up, Cleanup_Address_Space might access fields located through the ASCB_Ptr parameter before it establishes recovery (to improve performance). If an incorrect ASCB_ptr is passed to ATBCMAS, the caller may abend with completion code X'0C4' when ATBCMAS uses the passed value to get addressability to fields in the ASCB.
The Condition parameter defaults to zero (normal) if an incorrect condition is specified.
Transaction schedulers that call the Cleanup_Address_Space 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.
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.