|
Cleanup_TP is used to request that APPC/MVS clean
up all conversation resources associated with a transaction program
instance. Conversation resources include network resources, control
blocks, and buffers that are used by APPC/MVS to manage the transaction
program instance and its conversations.
Call Cleanup_TP for one of the following reasons: - The TP requested by an inbound allocate request is not recognized
or not available.
- The transaction scheduler cannot queue or schedule the transaction
program at this time.
- The requesting userid is not authorized to use the transaction
program
- The TP was attached and executed, and has completed normally or
abnormally.
The TP_ID is deleted from the system as a result of this call;
this cleanup process may occur asynchronously.
When calling Cleanup_TP, you can send error log information to a partner TP or system. See Sending Error Log Information for more information.
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: |
No locks held |
Control parameters: |
All parameters must be addressable by the caller
and in the primary address space. |
FormatFigure 1. ATBCTP3
- Cleanup_TP CALL ATBCTP3 (TP_ID,
Condition,
Notify_Type,
Error_Log_Information_Length,
Error_Log_Information,
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.
Note: If you specify a value of zero on the Condition parameter,
you cannot send error log information to partner TPs or systems.
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 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 can attempt to retry the request.
APPC/MVS deallocates the conversation with a sense code of X'084B6031'.
- 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'.
- 7
- User_Not_Authorized_For_TP
Specifies that the user is not
authorized to access the transaction program. APPC/MVS deallocates
the conversation with a sense code of X'080F0983'.
- 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.
- Error_log_information_length
- Supplied parameter
- Type: Integer
- Char Set: N/A
- Length: 4 bytes
Specifies the length of the error log information specified
on the Error_log_information parameter: - If error log information is not to be sent, specify 0 on
this parameter.
- If error log information is to be sent, specify the number
of bytes of error log information provided, in the range 1-512 (decimal).
If you specify a value greater than 512 on the Error_log_information_length
parameter, the system returns return code 16 (decimal) to the caller.
- Error_log_information
- Supplied parameter
- Type: Character string
- Char Set: N/A
- Length: 0-512 bytes
Specifies error log information to be sent to all partner
systems running TPs that have established conversations with the TP
to be cleaned up. This parameter contains information about an error
that occurred while scheduling a TP. The scheduler can send error
log information only when the Condition parameter (for the Cleanup_TP
service) specifies one of the following values: - System
- TP_Not_Available_No_Retry
- TP_Not_Available_Retry
- TPN_Not_Recognized
- Security_Not_Valid
- Sync_Level_Not_Supported_Pgm
- User_Not_Authorized_For_TP
If you do not specify one of the above values on the Condition
parameter, Cleanup_TP does not send error log information, even if
it is specified on this parameter.
- Return_code
- Returned parameter
- Type: Integer
- Char Set: N/A
- Length: 32 bits
When APPC/MVS returns control to your TP, the Return_code
parameter contains one of the following decimal return codes:
Return Code |
Meaning and Action |
---|
0 |
Meaning: Successful completion. All conversations
owned by the transaction program instance will be cleaned up asynchronously.
Action: None required.
|
4 |
Meaning: No conversations exist to be cleaned
up. Action: None required.
|
8 |
Meaning: The TP_ID parameter specified
a TP instance that does not exist. Action: Specify a valid
TP instance on the TP_ID parameter.
|
12 |
Meaning: An asynchronous request failed.
Action: Specify a Notify_Type of None on the call to Cleanup_TP,
then submit the request again. If the problem persists, contact the
IBM Support Center.
|
16 |
Meaning: The Error_log_information_length
parameter contains a value that is greater than 512 (decimal). The
transaction scheduler can only send up to 512 (decimal) bytes of error
log information. Action: Specify a value between 0 and
512 (decimal) on the Error_log_information_length parameter.
|
20 |
Meaning: APPC/MVS was cancelled during
an asynchronous request for this service. Action: Contact
the operator to determine if APPC/MVS can be restarted.
|
32 |
Meaning: The requested service is not supported
in the caller's environment. For example, the caller might be holding
a lock. Action: See the "Environment" section for
the required environment for calling Cleanup_TP. Ensure that the
scheduler calls Cleanup_TP while running in the required environment.
|
44 |
Meaning: APPC/MVS is not active. Action: Contact the operator to determine if APPC/MVS can be
restarted.
|
48 |
Meaning: APPC/MVS services failure. Action: Contact the IBM Support Center.
|
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.
- The Condition parameter defaults to 0 (normal) if an invalid condition
is specified.
- 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.
- Transaction schedulers 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 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.
|