Windows Considerations

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

Asynchronous completion notification

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 will depend on which operation was originally issued. The IParam argument contains the CM_PTR to the conversation_ID specified in the original function call.

Load-time linking

For a program to be dynamically linked to CPI-C at load time, you must do one of the following at link time:

• Insert the following IMPORTS statement in the definition (.DEF) file used to link the program:

  IMPORTS WINCPIC.[entry point to be used]

  (Use this statement for each entry point needed.)

• Link the program to WINCPIC.LIB, which contains the entry-point linkage information for CPI-C. If you intend to use CSV, you must also link to WINCSV.LIB, which contains the entry point information for CSV.

Local LUs

CPI-C does not provide a parameter for a program to specify the local LU it wants to use. The APPCLLU environment variable specifies a local LU. This variable can be set through the application section of the WIN.INI file, as in the following example:

[Application]
APPCTPN=TP1
APPCLLU=LU1
 

Setting APPCLLU is only necessary if the program does not use an LU from the default LU pool.

Packing

VCBs are not packed. As a result, DWORDs and WORDs are on WORD boundaries, and BYTEs are on BYTE boundaries. This means, for example, that there is not a 2-byte gap between the primary and secondary return codes. VCBs should be accessed using the structures provided, and compiler options that change this packing method should be avoided.

Run-time linking

For a program to be dynamically linked to CPI-C at run time, the program must issue:

• LoadLibrary to dynamically load WINCPIC.DLL, the CPI-C library.
• GetProcAddress to specify CPI-C as the desired entry point to the DLL.

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

Simultaneous conversations

A program can participate in as many as 64 conversations simultaneously with the Windows environment. However, if more than one CPI-C application is active at once, the total number of conversations cannot exceed 64.

Terminating applications

In the Windows environment, 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.

TP names

When a program issues Initialize_Conversation or Accept_Conversation, SNA Server generates an instance of a TP.

CPI-C does not provide a parameter for specifying the name of the invoking (Initialize_Conversation) TP instance. Instead, it is provided by setting the APPCTPN variable in the application section of the WIN.INI file, as in the following example:

[MyApplication]
APPCTPN=TP1
 

If APPCTPN is not set, the default value is CPIC_DEFAULT_TPNAME.

For the invoked program, the value of APPCTPN must match the value set by the invoking program. Accept_Conversation cannot complete unless the allocation request from the invoking program specifies the TP name contained in APPCTPN. The invoked program also sets APPCTPN through an application section of the WIN.INI file.

If this variable is not set when the invoked program issues Accept_Conversation, the default value is CPIC_DEFAULT_TP_NAME.

The APPCTPN variable can be an ASCII string from 1 through 64 characters long, consisting of uppercase and lowercase letters, numerals 0 through 9, and special characters, except the space. The APPCTPN variable cannot be set to an SNA service TP name, which contains nonprintable hexadecimal values.

If the invoking program issues multiple Initialize_Conversation calls, it can set APPCTPN to a different value before each call.

Yielding to other components

When processing CPI-C and 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 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)