Implementing CPI-C Programs

This chapter documents the details of the Personal Communications support for the CPI-C interface. It covers these main areas:

Techniques for compiling and linking CPI-C programs
Methods of preparing and executing CPI-C programs
Features of the CPI-C versions supported by Personal Communications

The Personal Communications implementation of CPIC is designed to be binary compatible with Microsoft SNA Server on Windows machines, and similar to the implementation of the CPIC interface of OS/2 Communication Manager/2.

Note:

Included in this chapter is information on the CPIC API provided by the following systems:

Communications Server running on Windows
SNA Win32 API clients platforms that are delivered with the Communications Server product
Personal Communications for Windows

When there are differences between the support provided by these systems, it is noted.

Writing CPIC Programs

Personal Communications provide a dynamic link library (DLL) file that handles CPIC calls.

The DLL is reentrant; multiple application processes and threads can call the DLL concurrently.

Table 9 shows source module usage of supplied header files and libraries needed to compile and link CPIC programs. Some of the header files may include other required header files.

Table 9. Header Files and Libraries for CPIC
Operating System	Header File	Library	DLL Name
WIN32	WINCPIC.H	WCPIC32.LIB	WCPIC32.DLL

CPI-C Versions

The CPI-C interface has gone through several version changes and extensions. You should be aware of these versions for two reasons:

If you are maintaining or porting an existing program, you need to know which function calls are portable and which you might need to change if you change versions.
If you are writing a new program, you need to be aware when you are writing code that is dependent on a particular version.

CPI-C Conformance Class Support

The following CPI-C 2.1 conformance classes are supported as defined by the IBM® document Common Programming Interface Communications CPI-C Reference Version 2.1 (SC26-4399-08).

For details on which classes are not supported by Communications Server clients, see the notepad icon throughout this chapter.

: This icon denotes important information.

The conversation conformance class allows programs to start and end half-duplex conversations.

Starter Set calls:

CMACCP

Accept_Conversation

CMALLC

Allocate

CMDEAL

Deallocate

CMINIT

Initialize_Conversation

CMRCV

Receive

CMSEND

Send_Data
Advanced Function Calls:

CMCFM

Confirm

CMCFMD

Confirmed

CMECS

Extract_Conversation_State

CMECT

Extract_Conversation_Type

CMEMBS

Extract_Maximum_Buffer_Size

CMEMN

Extract_Mode_Name

CMESL

Extract_Sync_Level

CMFLUS

Flush

CMPTR

Prepare_To_Receive

CMRTS

Request_To_Send

CMSERR

Send_Error

CMSCT

Set_Conversation_Type

CMSDT

Set_Deallocate_Type

CMSF

Set_Fill

CMSLD

Set_Log_Data

CMSMN

Set_Mode_Name

CMSPTR

Set_Prepare_To_Receive_Type

CMSRT

Set_Receive_Type

CMSRC

Set_Return_Control

CMSST

Set_Send_Type

CMSSL

Set_Sync_Level

Required sync_level values:

CM_NONE or CM_CONFIRM

CMSTPN

Set_TP_Name

CMTRTS

Test_Request_To_Send_Received

LU 6.2 conformance class allows a program to use LU 6.2 specific services:

CMEPLN: Extract_Partner_LU_Name
CMSED: Set_Error_Direction
CMSPLN: Set_Partner_LU_Name

The conversation-level non-blocking conformance class allows a program to regain control if a call cannot complete immediately.

CMCANC: Cancel_Conversation
CMSPM: Set_Processing_Mode
CMWAIT: Wait_For_Conversation

The server conformance class allows a program to register multiple transaction program names with CPI-C, to accept multiple incoming conversations, and to manage contexts for different clients.

CMACCI: Accept_Incoming
CMECTX: Extract_Conversation_Context

CMETPN: Extract_TP_Name
CMRLTP: Release_Local_TP_Name
CMINIC: Initialize_For_Incoming
CMSLTP: Specify_Local_TP_Name

The data conversion conformance class routine allows a program to call local routines to change the encoding of a character string from the local encoding to EBCDIC, or vice versa.

CMCNVI: Convert_Incoming
CMCNVO: Convert_Outgoing

The security conformance class allows a program to establish conversations that use access security information in side information or set directly by the program.

CMESUI: Extract_Security_User_ID
CMSCSP: Set_Conversation_Security_Password
CMSCST: Set_Conversation_Security_Type
: Required conversation_security_type values:
: CM_SECURITY_NONE
: CM_SECURITY_PROGRAM
: CM_SECURITY_PROGRAM_STRONG
: CM_SECURITY_SAME
CMSCSU: Set_Conversation_Security_User_ID

Queue-Level Non-Blocking for regain of control if a call cannot complete.

CMCANC: Cancel_Conversation
CMSQPM: Set_Queue_Processing_Mode
CMWCMP: Wait_For_Completion

Callback Function for regaining control if a call cannot complete.

CMCANC: Cancel_Conversation
CMSQCF: Set_Queue_Callback_Function

Secondary Information

allows you to extract secondary error return information.

CMESI: Extract_Secondary_Information

The following Conformance Classes are not supported.

OSI TP services
Recoverable Transactions (for resource recovery interface)
Unchained Transactions (for recoverable transactions)
Distributed Security (user security services of distributed security server)
Directory (user designated information stored in a distributed directory)

CPI-C Functions

All the CPI-C functions supported by Personal Communications are listed in Table 10. Use this table for reference when you are maintaining an old program or when you are writing a new program that must remain compatible with some existing system.

Note:

When writing a CPI-C application for the MS Windows SNA API client, specify the local transaction program via the Specify_Local_TP-Name (cmsltp) call before accepting an incoming conversation via the Accept_Conversation (cmaccp) call.

Table 10. Personal Communications Client Support of CPI-C Functions
Function	Long Name	Win32 Clients
cmaccp	Accept_Conversation	x
cmacci	Accept_Incoming	x
cmallc	Allocate	x
cmcanc	Cancel_Conversation	x
cmcfm	Confirm	x
cmcfmd	Confirmed	x
cmcnvi	Convert_Incoming	x
cmcnvo	Convert_Outgoing	x
cmdeal	Deallocate	x
xcmdsi	Delete_CPIC_Side_Information	x
cmectx	Extract_Conversation_Context	x
xcecst	Extract_Conversation_Security_Type	x
cmecst	Extract_Conversation_Security_Type	x
cmecs	Extract_Conversation_State	x
cmect	Extract_Conversation_Type	x
xcmesi	Extract_CPIC_Side_Information	x
cmembs	Extract_Maximum_Buffer_Size	x
cmemn	Extract_Mode_Name	x
cmepln	Extract_Partner_LU_Name	x
cmesi	Extract_Secondary_Information	x
cmesui	Extract_Security_User_ID	x
cmecsu	Extract_Security_User_ID	x
xcecsu	Extract_Security_User_ID	x
cmesrm	Extract_Send_Receive_Mode	x
cmesl	Extract_Sync_Level	x
xceti	Extract_TP_ID	x
cmetpn	Extract_TP_Name	x
cmflus	Flush	x
cminit	Initialize_Conversation	x
xcinct	Initialize_Conversation_For_TP	x
cminic	Initialize_For_Incoming	x
cmptr	Prepare_To_Receive	x
cmrcv	Receive	x
cmrcvx	Receive_Expedited	x
cmrltp	Release_Local_TP_Name	x
cmrts	Request_To_Send	x
cmsend	Send_Data	x
cmsndx	Send_Expedited	x
cmserr	Send_Error	x
cmscsp	Set_Conversation_Security_Password	x
xcscsp	Set_Conversation_Security_Password	x
cmscst	Set_Conversation_Security_Type	x
xcscst	Set_Conversation_Security_Type	x
cmscsu	Set_Conversation_Security_User_ID	x
xcscsu	Set_Conversation_Security_User_ID	x
cmsct	Set_Conversation_Type	x
xcmssi	Set_CPIC_Side_Information	x
cmsdt	Set_Deallocate_Type	x
cmsed	Set_Error_Direction	x
cmsf	Set_Fill	x
cmsld	Set_Log_Data	x
cmsmn	Set_Mode_Name	x
cmspln	Set_Partner_LU_Name	x
cmsptr	Set_Prepare_To_Receive_Type	x
cmspm	Set_Processing_Mode	x
cmsqcf	Set_Queue_Callback_Function	x
cmsqpm	Set-Queue_Processing_Mode	x
cmsrt	Set_Receive_Type	x
cmsrc	Set_Return_Control	x
cmssrm	Set_Send_Receive_Mode	x
cmsst	Set_Send_Type	x
cmssl	Set_Sync_Level	x
cmstpn	Set_TP_Name	x
cmsltp	Specify_Local_TP_Name	x
xchwnd*	Specify_Windows_Handle	x
xcstp	Start_TP	x
cmtrts	Test_Request_To_Send_Received	x
cmwcmp	Wait_For_Completion	x
cmwait	Wait_For_Conversation	x
xcendt	End_TP	x
WinCPICCleanup*		x
WinCPICIsBlocking*		-
WinCPICSetBlockingHook*		-
WinCPICStartup*		x
WinCPICUnhookBlockingHook*		-
* indicates: WOSA function for Microsoft Windows
x indicates: Supported function
- indicates: Unsupported function

Specifying Service TP Names

: This function is only supported for Communications Server SNA API clients.

You must use special conventions when specifying a service transaction program name with the CMSTPN and CMSLTP functions. Usually, you specify standard TPs with the CPI-C functions. Service transaction programs are specialized transaction programs that provide common network and system services to other programs or users. Examples of service transaction programs include scheduler programs, directory services, and spoolers.

The conventions for specifying a service transaction program name with the CMSTPN and CMSL transaction program functions are

Specify the name with from two to five bytes of ASCII characters.
Specify the first byte of the name, for example, 0x23, with two bytes of ASCII characters.
- Split the first byte of the name into two nibbles, for example, 2 and 3, and specify them in the low- order nibble of each ASCII byte.
- Set the high-order nibble of each ASCII byte to 1, which indicates that you are specifying a service TP name. Continuing with the example, the first two bytes specified are 0x12 and 0x13.
Specify the remaining zero to three bytes of the name as ASCII characters. For example, 007.

Therefore, specify a service transaction program name of 0x23 007, as 0x12 0x13 007.

Additional Options for Setting Local_LU

CPI-C applications rely on the DEFAULT_LOCAL_LU for use with TP_STARTED. Unless set otherwise, this is always the LOCAL_LU which matches the LOCAL_CP CP_NAME. This is not always what is desired.

Any defined LOCAL_LU can be used in place of the DEFAULT_LOCAL_LU by specifying the LOCAL_LU_ALIAS name of a defined LOCAL_LU in the CPI-C Side Information definition. The LOCAL_LU and CPI-C Side Information configuration's LOCAL_LU_ALIAS names must match exactly. They are case-sensitive and length-sensitive.

Personal Communications also supports the use of the system environment APPCLLU which may be used to refer to any defined LOCAL_LU. The value for APPCLLU must match the LOCAL_LU_ALIAS exactly. It is case-sensitive and length-sensitive (blanks are also counted in the length). CPI-C functions use this value for any Operator_Started TP.