WinAsyncAPPCEx

The WinAsyncAPPCEx function provides an asynchronous entry point for all of the APPC verbs. Use this function instead of the blocking versions of the verbs to allow multiple sessions to be handled on the same thread using events. This verb is only supported on Microsoft Windows and uses Win32® events.

Syntax

  
    HANDLE WINAPI WinAsyncAPPCEx(   
HANDLEevent_handle,  
longlpVcb);  

Parameters

event_handle
Handle used for event notification using Win32 events.

lpVcb
Pointer to the verb control block.

Return Value

The return value specifies whether the asynchronous resolution request was successful. If the function was successful, the return value is an asynchronous task handle. If the function was not successful, a zero is returned.

When this function returns with a successful value, this does not indicate that the APPC call will ultimately return successfully. It only indicates that it was possible for the APPC library to attempt the APPC call asynchronously using events for notification.

Remarks

This function is intended for use with WaitForSingleObject or WaitForMultipleObjects in the Win32 API. These functions are described in the "Reference" section of the Microsoft Platform SDK documentation.

For an example of how to use this verb in multithreaded TPs, see the multithreaded send and receive sample TPs (MRCV.C, MSEND.C, and MSENDRCV.C located in the MSENDRCV folder) included in the SDK.

APPC verbs used in basic conversations that can block are as follows:

• ALLOCATE

• CONFIRM

• CONFIRMED

• DEALLOCATE

• FLUSH

• PREPARE_TO_RECEIVE

• RECEIVE_ALLOCATE

• RECEIVE_AND_WAIT

• REQUEST_TO_SEND

• SEND_CONVERSATION

• SEND_DATA

• SEND_ERROR

• TP_ENDED

• TP_STARTED

  APPC verbs used in mapped conversations that can block are as follows:

• MC_ALLOCATE

• MC_CONFIRM

• MC_CONFIRMED

• MC_DEALLOCATE

• MC_FLUSH

• MC_PREPARE_TO_RECEIVE

• MC_RECEIVE_AND_WAIT

• MC_REQUEST_TO_SEND

• MC_SEND_CONVERSATION

• MC_SEND_DATA

• MC_SEND_ERROR

• RECEIVE_ALLOCATE

• TP_ENDED

• TP_STARTED

  When using the synchronous or asynchronous versions of a verb, an application can only have one outstanding function in progress on a conversation at a time. An attempt to initiate a second function results in the error code AP_CONV_BUSY.

Note

The exceptions to the preceding paragraph are RECEIVE_AND_POST, MC_RECEIVE_AND_POST, RECEIVE_AND_WAIT, and MC_RECEIVE_AND_WAIT.

Note

To allow full use of the asynchronous support, asynchronously issued RECEIVE_AND_WAIT and MC_RECEIVE_AND_WAIT verbs have been altered to act like the RECEIVE_AND_POST and MC_RECEIVE_AND_POST verbs. Specifically, while an asynchronous version of one of these verbs is outstanding, the following verbs can be issued on the same conversation:

• DEALLOCATE (AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER)

• GET_ATTRIBUTES or MC_GET_ATTRIBUTES

• GET_TYPE

• REQUEST_TO_SEND or MC_REQUEST_TO_SEND

• SEND_ERROR or MC_SEND_ERROR

• TEST_RTS or MC_TEST_RTS

• TP_ENDED

Note

This allows an application, in particular, a server application, to use an asynchronous RECEIVE_AND_WAIT or MC_RECEIVE_AND_WAIT to receive data. While the RECEIVE_AND_POST, MC_RECEIVE_AND_POST, RECEIVE_AND_WAIT, or MC_RECEIVE_AND_WAIT is outstanding, it can still use SEND_ERROR or MC_SEND_ERROR and REQUEST_TO_SEND or MC_REQUEST_TO_SEND. It is recommended that you use this feature for full asynchronous support, and in particular, for support of multiple conversations on the same thread.

When the asynchronous operation is complete, the application is notified through the signaling of the event. Upon signaling of the event, examine the APPC primary return code and secondary return code in the verb control block for any error conditions.