You can use the Cleanup_Address_Space service 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 is issued.
The Cleanup_Address_Space service may be invoked by a transaction
scheduler subordinate address space for a transaction program or job
that terminates normally or abnormally.
APPC/MVS deletes one or more 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. ATBCAS1
- Cleanup_Address_Space ServiceCALL ATBCAS1 (ASCB_ptr,
Condition,
Notify_Type,
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 resource manager parameter list
(RMPL). 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 may 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 transaction scheduler's subordinate
address space.
All active conversations are deallocated with
Type(Abend_SVC).
- Notify_type
- Supplied parameter
- Type: Structure
- Char Set: N/A
- Length: 4-8 bytes
Specifies the type of processing and notification (synchronous
or asynchronous) requested for this service. Programs can request
asynchronous processing, which returns control to the program immediately
and later notifies the program by ECB when the service is complete.
The possible types are:
- None
No notification is requested. The service is performed
synchronously, and control is returned to the caller when processing
is complete. All returned parameters are set on return to the caller.
To specify no notification, set the parameter value to a four-byte
structure containing binary zeros.
- ECB
Programs can request asynchronous processing by specifying
an ECB to be posted when processing completes. To specify an ECB,
set the parameter to an eight-byte structure containing a fullword
binary one (X'00000001') followed by the address of a fullword
area to be used as the ECB. The ECB must reside in the home address
space.
When you specify an ECB, control is returned before
processing is complete, with only the return code set. If the asynchronous
request was accepted, the return code is set to 0 to indicate that
the service is being processed asynchronously. Other returned parameters
are filled in during asynchronous processing, and the specified ECB
is posted when all returned parameters are set. The completion code
field in the ECB contains the return code for the service.
- Return_code
- Returned parameter
- Type: Integer
- Char Set: N/A
- Length: 32 bits
Cleanup_Address_Space may 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.
- 12
- The asynchronous request failed. Resubmit the request with a
Notify_type of None or report the problem to IBM.
- 20
- APPC/MVS was cancelled during an asynchronous request for this
service.
- 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.
- Cleanup_Address_Space may access fields located through the ASCB_ptr
parameter before it establishes recovery, to improve performance in
the case where no APPC resources must be cleaned up. If an incorrect
ASCB_ptr is passed to Cleanup_Address_Space, the caller might abnormally
end with completion code 0C4 when Cleanup_Address_Space uses the passed
value to get addressability to fields in the ASCB.
- The Condition parameter defaults to 0 (normal) if an invalid condition
is specified.
- If you call the Cleanup_Address_Space 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_Address_Space operation
(APPC/MVS considers all resources associated with the address space
“terminated”). The application's recovery environment must clean
up the waiting ECB.
- Transaction schedulers that call the Cleanup_Address_Space 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 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.