2 New Win32 CPIC APIs: Asynch Verb Completion Via WinNT Events

 Last reviewed: February 1, 1996
Article ID: Q140555
The information in this article applies to:
  • Microsoft SNA Server for Windows NT, version 2.11

SUMMARY

The following two new Win32 CPIC API Calls have been added to SNA Server 2.11 to enable asynchronous verb completion using Windows NT Events:

  • WinCPICSetEvent()
  • WinCPICExtractEvent()

This article discusses the way CPIC verbs in general complete asynchronously and how two new API calls complete asynchronously.

MORE INFORMATION

Currently, CPIC verbs complete asynchronously by posting a message to a window. There is one such window for each CPIC application. Each CPIC conversation can have one asynchronous verb outstanding at any time. When a verb completes, the posting to the window takes as parameters the CPIC conversation ID of the verb which has completed, and the return code of the verb.

This new specification addresses the new requirement to allow CPIC verbs running on Win32 to complete asynchronously through events, in common with the other SNA Server asynchronous interfaces.

The prototypes are: 

   /* Set_Conversation_Event */
   VOID WinCPICSetEvent(unsigned char CM_PTR, /*conversation_ID*/
   CM_EVENT_HANDLE CM_PTR, /* event handle */
   CM_RETURN_CODE CM_PTR); /* return_code  */
The parameters for this verb are:
  • Conversation ID, which is the ID of the conversation for which this event is used.
  • Event handle, which is the handle of the event which is to be cleared when an asynchronous verb on the conversation completes. This parameter can replace an already-defined event, or remove an already-defined event (by having NULL as the parameter).
  • Error code, which returns the error PROGRAM_PARAMETER_CHECK if any of the parameters are invalid.

Prototypes continued: 

   /* Extract_Conversation_Event */
   VOID WinCPICExtractEvent(unsigned char CM_PTR /*conversation_ID*/
   CM_EVENT_HANDLE CM_PTR, /* event handle */
   CM_RETURN_CODE CM_PTR); /* return_code  */
The parameters for this verb are:
  • Conversation ID, which is the ID of the conversation for which the event handle is being extracted.
  • Event handle, which returns the event handle being used by this conversation. If no handle has been registered, it returns NULL.
  • Error code, which returns the error PROGRAM_PARAMETER_CHECK if any of the parameters are invalid.

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. Once the verb has completed, the application must then call cmwait() to determine the return code for the asynchronous verb.

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 which the application has registered with the CPIC library.

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

An application can discover the event handle being used for a CPIC conversation with the call WinCPICExtractEvent().

Internal Changes:

Asynchronous event completion inside the CPIC library is done by a macro COMPLETE_ASYNC_VERB. This is changed to first check whether there is an event handle associated with the conversation. If there is, it clears this event. If there is not, it posts a message to a window as before.

The conversation control block is changed to have a field to contain the event.

Microsoft has updated the following files to add the two new Win32 CPIC API calls: 

   LIBS\WIN32\WCPIC32.DLL
   LIBS\WINB32\WCPIC32.LIB
   LIBS\WIN32\WINCPIC.DLL
   LIBS\WIN32\WINCPIC.LIB
   LIBS\WIN32\SNATRC.DLL
   LIBS\WIN95\SNATRC.DLL

STATUS

This feature is included in the latest U.S. Service Pack for SNA Server for Windows NT, version 2.11. For information on obtaining the Service Pack, query on the following word in the Microsoft Knowledge Base (without the spaces): 

   S E R V P A C K

KBCategory: kbnetwork kbbug2.11
KBSubcategory: ntnetserv
Additional reference words: prodsna 2.11

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: February 1, 1996
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.