This section describes API extensions to Windows CPI-C that allow nonblocking or asynchronous verb completion. Asynchronous verbs return control to the program immediately, without waiting for full execution, and must notify the application later when the verb has been completed. An application is also notified in response to the completion of a Wait_For_Conversation call. In contrast, synchronous verbs block—the function call does not return until the call has completed.
Under Microsoft® Windows NT® and Microsoft® Windows® 95, two methods are available for handling asynchronous verb completion:
The first method uses messages posted to a window handle to notify an application of verb completion. This method using window handles and messages is also supported on Windows 3.x. There is one such window for each CPI-C application. Each CPI-C conversation can have one asynchronous verb outstanding at any time. When a verb completes, the posting to the window takes as parameters the CPI-C conversation identifier of the verb that has completed, and the return code of the verb.
The extensions using window handles and message posting described in this section have been designed for all implementations and versions of Microsoft Windows from version 3.0 through the latest versions of Windows NT and Windows 95. They provide compatibility for Windows programming and optimum application performance in the 16-bit operating environment.
A second method using Win32 events for notification is supported on Microsoft® SNA Server version 3.0 and later. The extensions using Win32 events described in this section (WinCPICSetEvent and WinCPICExtractEvent) operate only on Windows NT and Windows 95, and offer the optimum application performance in the 32-bit operating environment. If an event has been registered with the conversation, then an application can call the Win32 WaitForSingleObject or WaitForMultipleObjects function to wait to be notified of the completion of the verb.
Windows CPI-C allows multithreaded Windows-based processes. Multithreading is the running of several processes in rapid sequence within a single program. A process contains one or more threads of execution. The 16-bit Windows environment is not multithreaded. In this instance, a task corresponds to a process with a single thread. All references to threads in this document refer to actual threads in multithreaded Windows environments. Using Win32 events is a common technique used by a multithreaded application that can dedicate a thread or several threads to handle event handling.
The extension descriptions in this section provide a definition of the function, syntax, return values, and remarks for using these Windows extensions in CPI-C programs.