APPC Verbs and Windows Extensions

This topic describes the APPC verbs and Windows extensions that are of particular importance in this version of SNA Server:

APPC Verbs

The following APPC verb descriptions contain important features and should be read before using this version of Windows APPC.

ALLOCATE or MC_ALLOCATE

Issued by the invoking TP, this verb allocates a session between the local LU and partner LU and (in conjunction with RECEIVE_ALLOCATE) establishes a conversation between the invoking TP and the invokable TP. After this verb executes successfully, APPC generates a conversation identifier (conv_id). The conv_id is a required parameter for all other APPC conversation verbs.

For a user or group using TPs, 5250 emulators, or APPC applications, you can assign default local and remote LUs. In this case, the field for LU alias is left blank or null and the default LUs are accessed when the user or group member starts an APPC program. For more information on using default LUs, see the Microsoft SNA Server Administration Guide.

For Windows version 3.x systems, it is recommended that you use WinAsyncAPPC rather than the blocking version of these calls.

RECEIVE_ALLOCATE

Issued by the invokable TP to confirm that it is ready to begin a conversation with the invoking TP that issued ALLOCATE or MC_ALLOCATE. This must be the first APPC verb issued by the invokable TP. The initial state is RESET. If the verb executes successfully (primary_rc is ap_ok), the state changes to RECEIVE.

RECEIVE_AND_POST or MC_RECEIVE_AND_POST

Receives application data and status information asynchronously. This allows the local TP to proceed with processing while data is still arriving at the local LU. RECEIVE_AND_POST and MC_RECEIVE_AND_POST are only supported by the Windows NT, Windows 95, and OS/2 operating systems. For similar functionality under the Windows version 3.x system, use RECEIVE_AND_WAIT or MC_RECEIVE_AND_WAIT in conjunction with WinAsyncAPPC.

While an asynchronous RECEIVE_AND_POST or MC_RECEIVE_AND_POST is outstanding, the following verbs can be issued:

REQUEST_TO_SEND or MC_REQUEST_TO_SEND

GET_TYPE

GET_ATTRIBUTES or MC_GET_ATTRIBUTES

TEST_RTS or MC_TEST_RTS

DEALLOCATE

SEND_ERROR or MC_SEND_ERROR

TP_ENDED

RECEIVE_AND_WAIT or MC_RECEIVE_AND_WAIT

Receives any data that is currently available from the partner TP. If no data is currently available, the local TP waits for data to arrive. For Windows version 3.x systems, it is recommended that you use WinAsyncAPPC rather than the blocking version of this call.

RECEIVE_AND_WAIT and MC_RECEIVE_AND_WAIT have been altered to act like RECEIVE_AND_POST and MC_RECEIVE_AND_POST. While an asynchronous RECEIVE_AND_WAIT or MC_RECEIVE_AND_WAIT is outstanding, the following verbs can be issued:

REQUEST_TO_SEND or MC_REQUEST_TO_SEND

GET_TYPE

GET_ATTRIBUTES or MC_GET_ATTRIBUTES

TEST_RTS or MC_TEST_RTS

DEALLOCATE

SEND_ERROR or MC_SEND_ERROR

TP_ENDED

TP_STARTED

Issued by the invoking TP, this verb notifies APPC that the TP is starting. For a user or group using TPs, 5250 emulators, or APPC applications, you can assign default local and remote APPC LUs. These default LUs are accessed when the user or group member starts an APPC program (a TP, 5250 emulator, or APPC application) and the program does not specify LU aliases. For more information on using default LUs, see the Microsoft SNA Server Administration Guide.

Windows Extensions

Windows APPC provides a complete set of Windows extensions that allow asynchronous communication using Windows version 3.x. These extensions provide maximum programming compatibility between Windows NT, Windows 95, and Windows version 3.x. They include the following:

WinAPPCCancelAsyncRequest

Cancels an outstanding WinAsyncAPPC-based request.

WinAPPCCancelBlockingCall

Cancels any outstanding blocking operation for its thread.

WinAPPCCleanup

Terminates and deregisters an application from a Windows APPC implementation. When an application is finished, it must call this function to deregister itself from a Windows APPC implementation.

WinAPPCIsBlocking

Determines if a thread is executing while waiting for a previous blocking call to finish.

WinAPPCSetBlockingHook

Allows a Windows APPC implementation to block APPC function calls by means of a new function. This call is used by Windows version 3.x applications to make blocking calls without blocking the rest of the system. Blocking procedures apply only if you do not use asynchronous calls. If a function needs to block, the blocking procedure is called repeatedly until the original request completes. This allows Windows to continue to run while the original application waits for the call to return. Note that while inside the blocking procedure, the application can be re-entered. WinAPPCSetBlockingHook is used by Windows version 3.x applications that go into a PeekMessageLoop to make blocking calls without blocking the rest of the system.

By default, Windows NT and Windows 95 do not go into a PeekMessageLoop; they actually block on an event waiting for the call to complete. The only time you need to use WinAPPCSetBlockingHook for Windows NT or Windows 95 is when a single-threaded application for these systems and Windows version 3.x share common source code. In this case, you must explicitly make this call. Contrast with WinAPPCIsBlocking and WinAPPCUnhookBlockingHook.

WinAPPCStartup

Registers an application and specifies the version of Windows APPC required. An application must call this extension to register itself with a Windows APPC implementation before issuing any further Windows APPC calls.

WinAPPCUnhookBlockingHook

Removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism.

WinAsyncAPPC

Provides an asynchronous version for all of the APPC verbs. It is recommended that you use this extension instead of the blocking versions of the verbs if you run your application under Windows version 3.x. APPC verbs that can block are:

ALLOCATE or MC_ALLOCATE

CONFIRM or MC_CONFIRM

CONFIRMED or MC_CONFIRMED

DEALLOCATE or MC_DEALLOCATE

FLUSH or MC_FLUSH

PREPARE_TO_RECEIVE or MC_PREPARE_TO_RECEIVE

RECEIVE_ALLOCATE

RECEIVE_AND_WAIT or MC_RECEIVE_AND_WAIT

REQUEST_TO_SEND or MC_REQUEST_TO_SEND

SEND_CONVERSATION or MC_SEND_CONVERSATION

SEND_DATA or MC_SEND_DATA

SEND_ERROR or MC_SEND_ERROR

TP_ENDED

TP_STARTED

Limits

SNA Server permits one outstanding Windows APPC asynchronous call per connection and one blocking verb per thread. For example:

void ProcessVerbCompletion (WPARAM wParam, LPARAM lParam)

{ for (i = 0   i < nPendingVerbs; itt)
    if (pPendingVerbs [i].hAsync = = wParam)
        ProcessVCB ( (LPVCB) lParam);
}    . . .

LRESULT CALLBACK SampleWndProc ( ... )
{
    if (msg = = uAsyncAPPC) {
        ProcessVerbCompletion (wParam; lParam);
    }
        else switch (msg) {
        case WM_USER:
            if (hAsync = WinAsyncAPPC (hwnd, &vcb) )
            pPendingVerbs [nPendingVerbs tt].hAsync = .hAsync;

            break;
    }

}

WinMain ( ... )
{
    if ( ( WinAPPCStartup ( ...) = = FALSE ) {
    return FALSE ;

    }

    uAsyncAPPC = RegisterWindowsMessage ("WinAsyncAPPC") ;
    while (GetMessage ( ...)  )  {

    ...
    WinAPPCCleanup ( ... )

}

Note  The exceptions to the rule of one outstanding asynchronous call are RECEIVE_AND_POST, MC_RECEIVE_AND_POST, RECEIVE_AND_WAIT, and MC_RECEIVE_AND_WAIT. While these verbs are outstanding, certain other verbs can also be called.