WinAsyncAPPC

The WinAsyncAPPC function provides an asynchronous entry point for all of the APPC verbs. Use this function instead of the blocking versions of the verbs if you run your application and want to use message posting using Windows handles for asynchronous verb completion.

Syntax

  
HANDLE WINAPI WinAsyncAPPC(   
HANDLE hWnd,  
Long lpVcb  
);  

Parameters

hWnd
A window handle that will be used for message posting to notify an application when an APPC verb completes.

lpVcb
Pointer to the verb control block.

Return Value

The return value specifies whether the asynchronous 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 message posting for notification.

Remarks

For an example of how to use this verb in transaction programs (TPs), see the send and receive sample TP (SENDRECV.C located in the APPC 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

  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.

  The exceptions to the preceding paragraph are:

• RECEIVE_AND_POST

• MC_RECEIVE_AND_POST

• RECEIVE_AND_WAIT

• MC_RECEIVE_AND_WAIT

  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

  This allows an application, in particular, a 5250 emulator, 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.

  When the asynchronous operation is complete, the application's window hWnd receives the message returned by RegisterWindowMessage with "WinAsyncAPPC" as the input string. The wParam argument contains the asynchronous task handle returned by the original function call. The lParam argument contains the original VCB pointer and can be dereferenced to determine the final return code.

  As part of the Windows APPC definition, WinAPPCCancelAsyncRequest allows an application to cancel any asynchronous APPC action; but terminates the related conversation or TP as appropriate. Any outstanding operations return with AP_CANCELED as the return code.

  If the function returns successfully, a WinAsyncAPPC message is posted to the application when the operation completes or the conversation is canceled.