Asynchronous

You can call the Asynchronous_Manager service either to determine whether there are any asynchronous APPC/MVS calls outstanding in an address space or to clean up an entire TP for which an asynchronous request is outstanding. Asynchronous APPC/MVS calls include any calls that have asynchronous processing specified on the Notify_Type parameter.

The Asynchronous_Manager service is particularly useful in TSO/E environments because TSO/E does not support the invocation of authorized commands or programs while an asynchronous APPC/MVS call is outstanding in the same address space. A program that needs to invoke an authorized command or program could first call the Asynchronous_Manager service to find out if there are any asynchronous calls outstanding in the address space and, if necessary, call Asynchronous_Manager again to clean up the TPs that submitted those calls. For example, you can call the Asynchronous_Manager service to clean up a TP in response to message IKJ56610I, which indicates attempted invocation of an authorized command or program while an asynchronous call is outstanding.

Note that the Asynchronous_Manager service only returns the number of asynchronous calls that are outstanding at the time the Asynchronous_Manager service is called; subsequent asynchronous calls are not reflected. Therefore, the query function of the Asynchronous_Manager service is most effective in an address space with no other tasks performing asynchronous APPC/MVS work.

Requirements

Authorization:

Supervisor state or problem state, any PSW key

Dispatchable unit mode:

Task

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. ATBAMR1 - Asynchronous_Manager

  CALL ATBAMR1 (
                Function,
                Asynchronous_number,
                Return_Code
               );

Parameters

Function

Supplied parameter

Type: Integer
Char Set: N/A
Length: 4 bytes

Specifies the function to be performed. Valid values for this parameter are:

Value: Meaning
1: Query - Asynchronous_Manager returns the number of outstanding asynchronous calls for the address space.
2: Cleanup - Asynchronous_Manager cleans up any TPs that have outstanding asynchronous calls. The cleaned up TPs receive a return code of Deallocated_abend. See Explanations of Return Codes for CPI Communications Services for an explanation of this return code.

Asynchronous_Number

Returned parameter

Type: Integer
Char Set: N/A
Length: 4 bytes

Specifies the number of outstanding asynchronous requests in the address space. This field is not modified for the Cleanup function.

Return_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 4 bytes

The Asynchronous_Manager service may return one of the following values in the Return_code parameter:

Decimal Value: Description
00: The Asynchronous_Manager service query function completed successfully. The Asynchronous_Number parameter contains a valid value.
The Asynchronous_Manager service completed successfully for the cleanup function. No TPs needed to be cleaned up. The Asynchronous_Number parameter is not updated.
04: The Asynchronous_Manager service completed successfully for the cleanup function. A TP was cleaned up. The Asynchronous_Number parameter is not updated.
16: An APPC/MVS service failure occurred.
20: The caller holds a lock or is disabled.
24: The function code is not valid.
32: The Asynchronous_Manager service was invoked for a scheduler address space.
36: The caller is in SRB mode.
44: APPC/MVS is not available.
48: APPC/MVS is ending.

Restrictions

Transaction programs that call the Asynchronous_Manager 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.

When the Asynchronous_Manager has been called to clean up an entire TP for which an asynchronous request is outstanding and a protected conversation is associated with the TP to be cleaned up, APPC takes the following actions against the protected conversation:

Note: The outstanding asynchronous call does not have to be on a protected conversation for the following actions to be taken against a protected conversation associated with the TP to be cleaned up.

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.
Note: When a UR (unit of recovery) is in the backout-required state, no new APPC protected conversations may be allocated or accepted by a transaction program instance associated with the current UR nor may local protected resources associated with the current UR be committed. A Backout call should be issued to backout the local protected resources associated with the current UR. Once the current UR is backed out or the current context is ended, new APPC protected conversations may be associated with a new transaction program instance.
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.