CPIC [For IBM]

The Common Programming Interface for Communications

Introducing CPI-C

This is a brief overview of the Common Programming Interface for Communications (CPI-C), giving basic information about its purpose, the rationale for its development, some idea of how to use it in applications, and a summary of the advantages (and trade-offs) of CPI-C as an interface for communications.

CPI-C, pronounced sip-ik, provides a straightforward method for developing portable distributed applications. The advantages of portability across platforms and ease of application development maximize the value of CPI-C and the usability of CPI-C applications.

APPC: The Function Behind CPI-C

Advanced Program to Program Communications (APPC) is an implementation of IBM's SNA LU 6.2 communications architecture. An application programming interface (API) is provided for programs to access the functions of APPC. Using this API, one program can maintain a conversation with another and exchange information across a network. The program issues APPC commands, called verbs, in the format designated by the programming interface. This interface also defines the format of the values that are returned to the program.

As APPC was developed, distinct APIs for the numerous platforms emerged. Each API had unique characteristics and its own format for requesting the functions that APPC provides. This complicated the development of distributed applications in a general sense because the application had to be tailored to meet the demands of a particular environment. The need for a standard API that could be utilized on any platform was soon evident.

CPI-C was developed to avoid platform dependencies. Although the actual implementation of CPI-C over APPC may vary from platform to platform, the API is consistent. Consequently, platform-dependent details need not be considered in the development of applications using CPI-C.

For more information, see the education resources listed on the previous page.

APPN: The Network Behind CPI-C

Advanced Peer-to-Peer Networking (APPN) is one of the preferred network choices for CPI-C applications. CPI-C applications also run over OSI networks, and, with technology such as AnyNet, can run over TCP/IP networks as well.

For more information, see the education resources listed on the previous page.

Advantages of CPI-C

Platform independence points to one of CPI-C's main advantages - simplicity. A distributed application developer can utilize CPI-C without needing specific knowledge of how the interface is implemented on a particular platform. The syntax of APPC APIs varies among environments. Some APIs are verb control block structures while others are function calls. Furthermore, the actual APPC API verb names are unique for each environment. Consequently, it requires specific knowledge of the particular platform API to implement a non-CPI-C distributed application. In contrast, a CPI-C application can be developed for any environment based only on a general knowledge of CPI-C since the syntax and structure is standard.

Portability is a second advantage of using CPI-C. Since the programming interface to APPC using CPI-C is consistent across platforms, an application developed for a particular platform can be moved to another environment and run effectively. For example, an OS/2 application which uses standard CPI-C functions can be linked with the appropriate VM CPI-C library and run in the VM environment with no changes to the source code.

A significant feature of CPI-C is that it can communicate with a partner program that is written using either a platform-dependent API or CPI-C. The programming interface being used is transparent to the conversation and to the partner program.

Programming with CPI-C

The syntax of CPI-C is straightforward and lacks the complexities common with many platform-dependent APIs. Function calls are used with particular conversation values passed as parameters.

There is only one set of function calls with CPI-C regardless of the conversation type. This is a further benefit of CPI-C when compared to some platform-dependent APIs. In some platform-dependent APIs, a different set of verbs is used for a mapped conversation than is used for a basic conversation. With CPI-C, mapped is used as the default conversation type unless specifically indicated otherwise using CPI-C's Set Conversation Type (CMSCT) call.

The general format to invoke a CPI-C function is:

     CALL routine_name(parameters, return_code).

Following are the six CPI-C starter set calls:

     CMINIT - Initialize Conversation,
     CMACCP - Accept Conversation,
     CMALLC - Allocate,
     CMSEND - Send Data,
     CMRCV  - Receive, and
     CMDEAL - Deallocate.

As an example, to accomplish the send data function in CPI-C using the C programming language, the CMSEND function must be called with the appropriate parameters. Some of these parameters contain values assigned by the program (input parameters) and others are assigned values by CPI-C as a result of the function execution (output parameters).

     CMSEND (conversation_id,               /* Input  */
             buffer,                        /* Input  */
             &send_length,                  /* Input  */
             &request_to_send_received,     /* Output */
             &return_code);                 /* Output */

The input parameters are values which must be specified before the CPI-C function is called. The primary CPI-C input parameter is the conversation id.

The conversation id is a unique identifier assigned to a conversation as a result of the CMINIT (at the originator) or CMACCP (at the target) call. The conversation id is an input to each succeeding CPI-C call to specify the appropriate conversation.

The partner is specified by:

• a partner logical unit (PLU) name indicating with whom the conversation should be established,
• a mode name indicating the type of session to be used for the conversation, and
• a transaction program (TP) name indicating the transaction program to be started on the partner's computer as a result of this conversation.