OS/2 Considerations

This topic summarizes processing considerations you need to be aware of when developing programs on an OS/2 server, client, or workstation.

Critical sections

Exercise great caution when using critical sections, which are the parts of a program that must run without interruption. A program must not issue a CPI-C call within a critical section.

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 CPIC.[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.

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:

• By the program itself.
• By the operator if the program is operator-started.
• During configuration if the program is automatically started.

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

Multiple processes

Multiple processes cannot have the same conversation identifier. Only the process that issues Initialize_Conversation or Accept_Conversation can use the conversation identifier returned by the call. Another process wanting to use CPI-C must issue Initialize_Conversation or Accept_Conversation to obtain its own conversation identifier.

Two or more instances of the same program can be run as different processes.

One process can engage in multiple conversations, subject to the restrictions described under "Simultaneous conversations" in this topic.

Multiple threads

A program can have multiple threads that issue calls. However, the program cannot issue two calls simultaneously on the same conversation. If CPI-C is issuing a call and another thread of the program issues a call on the same conversation, the thread will hang until the first call completes.

OS/2 exception TRAP 000D

The OS/2 exception TRAP 000D occurs when CPI-C is unable to pass a return code to the local program because the return code pointer parameter supplied to CPI-C is invalid.

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:

• DosLoadModule to dynamically load CPIC.DLL, the CPI-C library.
• DosGetProcAddr to specify the desired entry points to the DLL. Each CPI-C call is an entry point to the DLL.

Unlinking (the DosFreeModule call) is not supported.

Simultaneous conversations

A program can simultaneously participate in as many as 64 conversations for each OS/2 process.

Stack size

The recommended stack size for a program is at least 3000 bytes.

When executing a call, CPI-C uses the calling program's stack. The combination of OS/2 and CPI-C requires 2560 bytes of stack space, and the program requires additional stack space for its variables.

Terminating applications

When an application terminates, it should issue the APPC TP_ENDED verb with the type set to AP_HARD for all active TPs.

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 through the APPCTPN environment variable. For the invoking program, APPCTPN can be set by the operator or by the program itself. 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 be completed unless the allocation request from the invoking program specifies the TP name contained in APPCTPN.

If the invoked program is operator-started, the value of APPCTPN can be set by the operator or by the program. If the program is automatically started, the value of APPCTPN is set when configuring the invokable program. It can also be set by the program itself. 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 from 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.