Before Using Windows CPI-C

The following CPI-C calls and Windows extensions are of particular importance and should be reviewed before using this version of SNA Server. Note that the names of the calls are pseudonyms. The actual C function names appear in parentheses after the pseudonym. For example, Set_Processing_Mode is the pseudonym for a call. The actual function name is cmspm.

Set_Processing_Mode (cmspm)

Specifies for the conversation whether subsequent calls will be returned when the operation they request is complete (blocking) or immediately after the operation is initiated (nonblocking). A program is notified of the completion of nonblocking calls when it issues Wait_For_Conversation or through a Windows message sent to a WndProc identified by hwndNotify in Specify_Windows_Handle. When the processing mode is set for a conversation, it applies to all subsequent calls on the conversation until the mode is set again.

Specify_Windows_Handle (xchwnd)

Sets the window handle to which a message is sent on completion of an operation in nonblocking mode.

Wait_For_Conversation (cmwait)

Waits for the completion of an operation that was initiated when the processing mode conversation characteristic was set to CM_NON_BLOCKING and cm_operation_incomplete was returned in the return_code parameter. Use Wait_For_Conversation when running a background thread or a single-threaded application for the Windows NT, Windows 95, or Windows version 3.x systems.

Important An application can set the processing mode by calling Set_Processing_Mode. If the window handle is set to NULL, or this call is never issued, then the application must call Wait_For_Conversation to be notified when the outstanding operation completes.

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 lParam argument contains the CM_PTR to the conversation identifier specified in the original function call.

WinCPICCleanup

Terminates and deregisters an application from a Windows CPI-C implementation.

Important This function must be called by an application when finished to deregister the application from the Windows CPI-C implementation.

WinCPICExtractEvent

Provides a method for an application to determine the event handle being used for a CPI-C conversation.

WinCPICIsBlocking

Determines if a task is executing while waiting for a previous blocking call to finish. Windows version 3.x goes into a PeekMessageLoop while allowing Windows to continue. Although a call issued on a blocking function appears to an application as though it blocks, the Windows CPI-C dynamic-link library (DLL) has to relinquish the processor to allow other applications to run. This means that it is possible for the application that issued the blocking call to be re-entered, depending on the message(s) it receives. In this instance, WinCPICIsBlocking can be used to determine whether the application task currently has been re-entered while waiting for an outstanding blocking call to finish.

This extension is intended to provide help to an application written to use the CM_BLOCKING characteristic of the Windows Specify_Processing_Mode function. WinCPICIsBlocking serves the same purpose as InSendMessage in the Windows API.

Applications targeted at Windows version 3.x that support multiple conversations must specify CM_NONBLOCKING in Specify_Processing_Mode so they can support multiple outstanding operations simultaneously. Applications are still limited to one outstanding operation per conversation in all environments. Note that Windows CPI-C prohibits more than one outstanding blocking call per thread.

WinCPICSetBlockingHook

Allows a Windows CPI-C implementation to block CPI-C function calls by means of a new function. Blocking calls apply only if you do not use asynchronous calls. If a function needs to block, the blocking call 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 call, the application can be re-entered. WinCPICSetBlockingHook is used by Windows version 3.x applications that go into a PeekMessageLoop to make blocking calls without blocking the rest of the system.

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

WinCPICSetEvent

Associates a Win32 event handle with a verb completion.

WinCPICStartup

Allows an application to specify the version of Windows CPI-C required and to retrieve details of the specific CPI-C implementation.

Important An application must call this function to register itself with a Windows CPI-C implementation before issuing any further Windows CPI-C calls.

WinCPICUnhookBlockingHook

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