Windows NT and Windows 95 Considerations

This topic summarizes things to keep in mind when you are developing programs on a server based on Microsoft® Windows NT® or Windows® 95.

Asynchronous completion notification using message posting
When an asynchronous operation is complete, the application's window hwndNotify receives the message returned by RegisterWindowMessage with "WinAsyncCPIC" as the input string. The wParam value contains the conversation_return_code from the operation that is completing. Its values depend on which operation was originally issued. The IParam argument contains the CM_PTR to the conversation_ID specified in the original function call.
Asynchronous completion notification using Win32 events
When a verb is issued on a non-blocking conversation, it returns CM_OPERATION_INCOMPLETE if it is going to complete asynchronously. If an event has been registered with the conversation, then the application can call WaitForSingleObject or WaitForMultipleObjects to be notified of the completion of the verb. WinCPICExtractEvent allows a CPI-C application to determine this event handle. After the verb has completed, the application must call Wait_for_Conversation to determine the return code for the asynchronous verb. The Cancel_Conversation function can be called to cancel an operation and the conversation itself.

It is the responsibility of the application to reset the event, as it is with other APIs.

If no event has been registered, then the asynchronous verb completes as it does at present, which is by posting a message to the window that the application has registered with the CPI-C library.

Byte ordering
By default, Intel byte ordering is used. For inline environments, defining NON_INTEL_BYTE_ORDER will do all the required flipping for constants. Nonconstant input parameters in verb control blocks (VCBs)—for example, lengths and pointers—are always in the native format.
Events
To receive data asynchronously, an event handle is passed in the semaphore field of the VCB. This event must be in the nonsignaled state when passed to CPI-C, and the handle must have EVENT_MODIFY_STATE access to the event.
Library name
In preparation for the coexistence of Win16 and Win32® API libraries on the same computer, the Win32 DLL name has been changed from WINCPIC.DLL to WINCPIC32.DLL.

The old DLL name should be used for Win32-based applications that are required to run on Microsoft® SNA Server version 2.0. The new DLL name should be used for Win32-based applications that are intended to run only on SNA Server version 2.1 or later versions.

If you intend your Win32-based application to be used with SNA Server version 2.0, you should link with the library included with SNA Server version 2.0. Otherwise use the new library provided with SNA Server version 2.1.

Multiple threads
A TP can have multiple threads that issue verbs. Windows CPI-C makes provisions for multithreaded Windows-based processes. A process contains one or more threads of execution. All references to threads refer to actual threads in a multithreaded Windows environment.
Packing
For performance reasons, the VCBs are not packed. As a result of this, DWORDs are on DWORD boundaries, WORDs on WORDs, and BYTEs on BYTEs. VCBs should be accessed using the structures provided.
Run-time linking
For a TP to be dynamically linked to CPI-C at run time, the TP must issue:

Issue the FreeLibrary call when the CPI-C library is no longer required.

Simultaneous conversations
A program can simultaneously participate in as many as 64 conversations per process.
Terminating applications
In the Windows NT and Windows 95 environments, CPI-C cannot tell when an application terminates. Therefore, if an application must close (for example, it receives a WM_CLOSE message as a result of an ALT+F4 from a user), the application should call WinCPICCleanup.
Yielding to other components
When processing CPI-C and Common Service Verbs (CSV), it may be necessary for the library code to yield to allow another component, such as the SnaBase, to receive messages and pass them to the application. This can be accomplished by using the Windows extensions WinCPICSetBlockingHook and WinCPICUnhookBlockingHook.

WinCPICSetBlockingHook allows a Windows CPI-C implementation to block CPI-C 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. To call WinCPICSetBlockingHook: 

FARPROC WINAPI WinCPICSetBlockingHook (FARPROC 1pBlockFunc)

WinCPICUnhookBlockingHook removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism. To call WinCPICUnhookBlockingHook: 

BOOL WINAPI WinCPICUnhookBlockingHook (void)