Copyright: CPI-C Programmer's Guide
Citation: CPI-C Programmer's Guide


Microsoft SNA Server Master Table of Contents
Microsoft SNA Server

Master Table of Contents

	SNA Server Enhancements Guide
	SNA Server Installation Guide
	SNA Server Administration Guide
	Managing Microsoft SNA Server
	SNA Server Planning Guide
	SNA Server TN3270 Service
	3270/5250 Applet User's Guide
	SNA Server Reference
	SNA Server Glossary
	APPC Programmer's Guide
	CPI-C Programmer's Guide
	LUA Programmer's Guide
	SNA Device Interface Specification
	3270 Emulator Interface Specification
	Comprehensive Index


CPI-C Programmer's Guide Contents
Microsoft SNA Server

CPI-C Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to CPIC

Chapter 2	Writing CPI-C Applications

Chapter 3	CPI-C Calls

Chapter 4	Extensions for the Windows Environment

Appendix A	Common Return Codes

Appendix B	Sample CPI-C TPs in the SDK

List of Figures

List of Tables


CPI-C Programmer's Guide Contents
Microsoft SNA Server

CPI-C Programmer's Guide

Contents

Before You Begin

How to Use This Guide

Document Conventions

Common Abbreviations

Finding Further Information

Chapter 1	Introduction to CPIC

Chapter 2	Writing CPI-C Applications

Chapter 3	CPI-C Calls

Chapter 4	Extensions for the Windows Environment

Appendix A	Common Return Codes

Appendix B	Sample CPI-C TPs in the SDK

List of Figures

List of Tables


CPI-C Programmer's Guide Contents
Microsoft SNA Server

CPI-C Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to CPIC

Windows CPIC Overview

Windows CPI-C Asynchronous Support

Before Using Windows CPIC

Using Asynchronous Call Completion

CPIC Call Summary

Starting a Conversation

Set_Calls to Change Initial Conversation Characteristics

Sending Data

Receiving Data

Confirming Receipt of Data and Reporting Errors

Getting Information

Extract_Calls

Ending a Conversation

Administering Side Information

Initial Conversation Characteristics

Side Information

Configuration

Windows NT Considerations

Windows Considerations

OS/2 Considerations

Chapter 2	Writing CPI-C Applications

Chapter 3	CPI-C Calls

Chapter 4	Extensions for the Windows Environment

Appendix A	Common Return Codes

Appendix B	Sample CPI-C TPs in the SDK

List of Figures

List of Tables


CPI-C Programmer's Guide Contents
Microsoft SNA Server

CPI-C Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to CPIC

Chapter 2	Writing CPI-C Applications

Communication Between TPs

Fundamental Terms for TPs and LUs

Sample TPs Illustrating Fundamental Concepts

Configuring and Controlling TPs

Steps for Creating TPs and the Configuration to Support Them

Designing and Coding TPs

CPIC Calls in C Programs

CPIC and LU 6.2

Conversation States

State Checks

Changing Conversation States

Confirmation Processing

Establishing the Synchronization Level

Sending a Confirmation Request

Receiving a Confirmation Request

Responding to a Confirmation Request

Deallocating the Conversation

Conversation Security

Basic and Mapped Conversations Compared

Logical Records Used in Basic Conversations

An Example of a Mapped Conversation

Using Invoking and Invokable TPs

Invoking TPs

Invoking TPs and Contention

Invokable TPs

Subcategories for Autostarted Invokable TPs

How an Invokable TP is Matched to an Invoking TPs Request

Configuring Invokable TPs

Clients Running Windows NT

Registry Entries for Clients Running Windows NT

Example of Registry Entries for an Invokable TP

Clients Running Windows Version 3.x

Environment Variables for Clients Running Windows Version 3.x

Example of WIN.INI Lines for an Invokable TP

Clients Running OS/2

Environment Variables for OS/2-Based Clients

Clients Running MS-DOS

Configuring an SNA Server to Support TPs

Invoking TPs and the SNA Server Configuration

Invokable TPs and the SNA Server Configuration

Possible Arrangements of TPs Within an SNA Network

TP Name Unique for Each TP

TP Name Not Unique; Local LU Alias Unique

TP Name Not Unique; Local LU Alias Unspecified

Troubleshooting for Invokable TPs

SNA Server Features That Simplify CPIC Configuration

Chapter 3	CPI-C Calls

Chapter 4	Extensions for the Windows Environment

Appendix A	Common Return Codes

Appendix B	Sample CPI-C TPs in the SDK

List of Figures

List of Tables


CPI-C Programmer's Guide Contents
Microsoft SNA Server

CPI-C Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to CPIC

Chapter 2	Writing CPI-C Applications

Chapter 3	CPI-C Calls

Data Types

Symbolic Constants

Strings

Validity of Output Parameters

Accept_Conversation (cmaccp)

Allocate (cmallc)

Cancel_Conversation (cmcanc)

Confirm (cmcfm)

Confirmed (cmcfmd)

Deallocate (cmdeal)

Delete_CPIC_Side_Information (xcmdsi)

Extract_Conversation_Security_Type (xcecst)

Extract_Conversation_Security_User_ID (cmecsu)

Extract_Conversation_State (cmecs)

Extract_Conversation_Type (cmect)

Extract_CPIC_Side_Information (xcmesi)

Extract_Mode_Name (cmemn)

Extract_Partner_LU_Name (cmepln)

Extract_Sync_Level (cmesl)

Extract_TP_Name (cmetpn)

Flush (cmflus)

Initialize_Conversation (cminit)

Prepare_To_Receive (cmptr)

Receive (cmrcv)

Confirmation Processing

Normal Deallocation

ABEND

Errors

Request_To_Send (cmrts)

Send_Data (cmsend)

Send_Error (cmserr)

SEND State

Set_Conversation_Security_Password (cmscsp)

Set_Conversation_Security_Type (cmscst)

Set_Conversation_Security_User_ID (cmscsu)

Set_Conversation_Type (cmsct)

Set_CPIC_Side_Information (xcmssi)

Set_Deallocate_Type (cmsdt)

Set_Error_Direction (cmsed)

Set_Fill (cmsf)

Set_Log_Data (cmsld)

Set_Mode_Name (cmsmn)

Set_Partner_LU_Name (cmspln)

Set_Prepare_To_Receive_Type (cmsptr)

Set_Processing_Mode (cmspm)

Set_Receive_Type (cmsrt)

Set_Return_Control (cmsrc)

Set_Send_Type (cmsst)

Set_Sync_Level (cmssl)

Set_TP_Name (cmstpn)

Specify_Local_TP_Name (cmsltp)

Specify_Windows_Handle (xchwnd)

Test_Request_To_Send_Received (cmtrts)

Wait_For_Conversation (cmwait)

Chapter 4	Extensions for the Windows Environment

Appendix A	Common Return Codes

Appendix B	Sample CPI-C TPs in the SDK

List of Figures

List of Tables


CPI-C Programmer's Guide Contents
Microsoft SNA Server

CPI-C Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to CPIC

Chapter 2	Writing CPI-C Applications

Chapter 3	CPI-C Calls

Chapter 4	Extensions for the Windows Environment

WinCPICCleanup( )

WinCPICIsBlocking( )

WinCPICStartup( )

WinCPICSetBlockingHook( )

WinCPICUnhookBlockingHook( )

Appendix A	Common Return Codes

Appendix B	Sample CPI-C TPs in the SDK

List of Figures

List of Tables


CPI-C Programmer's Guide Contents
Microsoft SNA Server

CPI-C Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to CPIC

Chapter 2	Writing CPI-C Applications

Chapter 3	CPI-C Calls

Chapter 4	Extensions for the Windows Environment

Appendix A	Common Return Codes

Appendix B	Sample CPI-C TPs in the SDK

Building the TPs

TPSETUP

TPSTART

APING and APINGD

Multithreaded APINGD

CPI-C Send and Receive TPs

AREXEC and AREXECD

List of Figures

List of Tables


CPI-C Programmer's Guide Contents
Microsoft SNA Server

CPI-C Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to CPIC

Chapter 2	Writing CPI-C Applications

Chapter 3	CPI-C Calls

Chapter 4	Extensions for the Windows Environment

Appendix A	Common Return Codes

Appendix B	Sample CPI-C TPs in the SDK

List of Figures

Communication Between TPs

Partner TP Invoking Another TP

Subcategories for Invokable TPs

List of Tables


CPI-C Programmer's Guide Contents
Microsoft SNA Server

CPI-C Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to CPIC

Chapter 2	Writing CPI-C Applications

Chapter 3	CPI-C Calls

Chapter 4	Extensions for the Windows Environment

Appendix A	Common Return Codes

Appendix B	Sample CPI-C TPs in the SDK

List of Figures

List of Tables

Set_Calls to Change Initial Conversation Characteristics

Calls to Retrieve Information

Side Information Calls

Initial Conversation Characteristics

Controlling the Characteristics of TPs

Conversation States

Registry Entries for Invokable TPs on Windows NT-Based Clients

Environment Variables for Invokable TPs on Windows-Based Clients

Environment Variables for Invokable TPs on OS/2-Based Clients

Lines in CPICSEND.CFG

Lines in CPICRECV.CFG


Before You Begin
1 of 5

Before You Begin

The Microsoft SNA Server CPIC Programmer's Guide provides information required to develop Clanguage applications that use the Common Programming Interface for Communications (CPIC) to exchange data in a Systems Network Architecture (SNA) environment.

This guide is written for the PC programmer writing applications that use CPIC to exchange data. It provides conceptual information and detailed reference information.

Before reading this guide, you should be familiar with:

Microsoft [image] SNA Server.

One of the following operating environments:

Microsoft Windows NT.

Microsoft Windows [image] version 3.0 or later.

IBM [image] OS/2 [image] version 1.2 or later.

SNA concepts.


How to Use This Guide
Before You Begin	2 of 5

How to Use This Guide

This guide contains the following chapters:

Chapter 1, "Introduction to CPIC"

Introduces the fundamental concepts of CPIC.

Chapter 2, "Writing CPIC Applications"

Contains general information about writing CPIC applications.

Chapter 3, "CPIC Calls"

Describes each CPIC call in detail.

Chapter 4, "Extensions for the Windows Environment"

Provides extensions to the Windows CPIC.

Appendix A, "Common Return Codes"

Lists all of the return codes in integer order.

Appendix B, "Sample CPI-C TPs in the SDK"

Describes the CPI-C TP samples in the SNA Server SDK.


Document Conventions
Before You Begin	3 of 5

Document Conventions

Throughout this manual, the following conventions distinguish elements of text.

Convention	Purpose

bold	Indicates syntax items that must be typed exactly as shown.

italic	Indicates variables.

monospace	Represents examples and program code.

SMALL CAPS	Represent return values and key names, such as CTRL.

UPPERCASE	Represents filenames, paths, volumes, array and structure names, values, and conversation states.

[brackets]	Enclose optional items in syntax statements.

{braces}	Enclose required items in syntax statements.

| (vertical bar)	Stands for OR and separates items in syntax statements.

... (ellipsis)	Indicates that the preceding syntax item can be repeated.
If a punctuation mark precedes the ellipsis, you must include the punctuation when repeating the item.

X'nnnn'	Indicates hexadecimal digits.


Common Abbreviations
Before You Begin	4 of 5

Common Abbreviations

The following is an alphabetical list of common abbreviations used in this manual.

Abbreviation	Meaning

API	application programming interface

APPC	Advanced Program-to-Program Communications

ASCII	American Standard Code for Information Interchange

CPIC	Common Programming Interface for Communications

CSV	Common Service Verb

DFT	distributed function terminal

DLC	data link control

DLL	dynamic-link library

EBCDIC	Extended Binary-Coded Decimal Interchange Code

GDS	general data stream

K	kilobyte

LL	record-length

LU	logical unit

LUA	conventional Logical Unit Application programming interface

MB	megabyte

MDI	multiple document interface

NCP	Network Control Panel

PU	physical unit

PVC	permanent virtual circuit

QLLC	qualified logical link control

RU	request/response unit

RUI	Request Unit Interface

SAA	Systems Application Architecture

SCM	Service Control Manager

SDLC	Synchronous Data Link Control

SLI	Session Level Interface

SNA	Systems Network Architecture

SVC	switched virtual circuit

TP	transaction program

VCB	verb control block

VTAM	Virtual Telecommunications Access Method


Finding Further Information
Before You Begin	5 of 5

Finding Further Information

For information about SNA architecture, refer to your system network documentation.

The following manuals provide additional information about SNA Server application programming interfaces (APIs):

Microsoft SNA Server APPC Programmer's Guide

Microsoft SNA Server LUA Programmer's Guide

Microsoft SNA Server Reference

For more information about SNA and about 3270 information display systems, see the following manuals:

IBM 3270 Information Display System: 3274 Control Unit Description and Programmer's Guide

IBM 3270 Information Display System: Color and Programmed Symbols

IBM 3270 Information Display System: 3274 Control Unit Display Station: Operator's Guide

IBM Systems Network Architecture: Technical Overview

IBM Systems Network Architecture: Concepts and Products

IBM Advanced Communications Function Products Installation Guide

IBM Installation and Resource Definition

IBM 9370 LAN Token Ring Support

IBM SNA Format and Protocol Reference Manual: Architectural Logic

For background information about logical unit (LU) 6.2, Advanced Program-to-Program Communications (APPC), and/or CPIC, see the following manuals:

IBM Systems Network Architecture: Introduction to APPC

IBM Systems Network Architecture: Transaction Programmer's Reference Manual for LU Type 6.2

IBM SNA: Format and Protocol Reference Manual: Architecture Logic for LU Type 6.2

IBM SNA: Formats

IBM SNA: Technical Overview

IBM SNA: ACF/VTAM Programming for LU Type 6.2


Introduction to CPIC
Chapter 1	1 of 18

Introduction to CPIC

This chapter introduces the fundamental concepts of the Common Programming Interface for Communications (CPIC). The following topics are covered:

Windows CPIC overview

Windows CPIC asynchronous support

Using asynchronous call completion

Starting a conversation

Sending and receiving data

Confirming receipt of data and reporting errors

Getting information

Ending a conversation

Initial conversation characteristics

Side information

Configuration

Windows NT considerations

Windows considerations

OS/2 considerations

CPIC is a Systems Application Architecture (SAA) adherent application programming interface (API) that allows peer-to-peer communications among programs in a Systems Network Architecture (SNA) environment. (An API is a facility that provides information and services to programs.)

Through CPIC, programs distributed across a network can work together — communicating with each other and exchanging data — to accomplish a single processing task, such as querying a remote database, copying a remote file, or sending or receiving electronic mail.

These programs communicate as peers, on an equal (rather than hierarchical) basis. Together, programs distributed across a local or wide area network perform distributed processing.


Windows CPIC Overview
Introduction to CPIC	2 of 18

Windows CPIC Overview

In order to provide one common API to port applications from various operating environments to Windows NT and Windows version 3.x, a Windows SNA standard was created. As a direct result of this work, Windows CPIC was developed. The CPIC calls and information presented in this guide represent an evolving Windows CPIC that is composed of CPIC version 1.2 and a set of Windows extensions that allow for multiple applications and asynchronous call completion.

CPIC version 1.0 was first introduced to provide a means by which two applications could speak and listen to each other; in other words, to have a conversation. A conversation is the logical connection between two programs that allows the program to communicate with each other. Programs using CPIC converse with each other by making program calls. These calls are used to establish the full characteristics of the conversation, to exchange data, and to control the information flow between the two programs.

CPIC version 1.1 was extended to include four new areas of function: support for resource recovery (not supported in Windows CPIC), automatic parameter conversion, support for communicating with non – CPIC programs, and local/remote transparency. Built upon CPIC version 1.1, X/Open CPIC provided support for nonblocking calls, the ability to accept multiple conversations, support for data conversion (beyond parameters), and support for security parameters.

CPIC version 1.2 consolidated CPIC version 1.1 and X/Open CPIC by providing function in all the areas described above. Windows CPIC further adds to this functionality by providing a set of extensions for asynchronous communication in addition to the full complement of supported features in CPIC version 1.2 (with the exception of resource recovery).


Windows CPI-C Asynchronous Support
Introduction to CPIC	3 of 18

Windows CPIC Overview

Windows CPI-C Asynchronous Support

Asynchronous call completion returns the initial call immediately so the application can continue with other processes. A program that issues a call and does not regain control until the operation completes is not able to perform any other operations. This type of operation, referred to as blocking, is not suited to a server application designed to handle multiple requests from many clients. In particular, Windows CPIC support related to asynchronous communications includes the following calls and extensions:

Set_Processing_Mode

Specify_Windows_Handle

Wait_For_Conversation

WinCPICSetBlockingHook

WinCPICIsBlocking

WinCPICUnhookBlockingHook

Asynchronous support is appended to the Set_Processing_Mode call and allows you to be notified of call completion on a Windows handle. Through RegisterWindowsMessage with "WinAsyncCPIC" as the string, you pass a Windows handle by which you are notified of call completion. You then make your call, and once it completes, a message is posted to the Windows handle that you passed, notifying you that the call is complete.

With the exception of an asynchronous Receive call that can issue certain other calls while pending, a conversation can have only one incomplete operation at any time. For more information on using an asynchronous Receive call, see "Using Asynchronous Call Completion" later in this chapter. In the case of an incomplete operation, the program can issue Wait_For_Conversation to test for its completion or Cancel_Conversation to end the conversation and the incomplete operation.

The only Windows extensions required for Windows CPIC are for initialization (WinCPICStartup) and termination (WinCPICleanup) purposes. Depending on your application, other Windows extensions may be useful to you, but they are not required. An example of how to use Windows CPIC asynchronous calls and Windows extensions appears in "Using Asynchronous Call Completion" later in this chapter. A complete description of all Windows CPIC calls and extensions appears in Chapter 3, "CPIC Calls" and Chapter 4, "Extensions for the Windows Environment."


Before Using Windows CPIC
Introduction to CPIC	4 of 18

Windows CPIC Overview

Before Using Windows CPIC

The following CPIC calls and Windows enhancements are of particular importance and should be reviewed before using this version of SNA Server:

Set_Processing_Mode (cmspm)

Specifies for the conversation whether subsequent calls will be returned when the operation they have requested is complete (blocking) or immediately after the operation is initiated (nonblocking). A program is notified of the completion of nonblocking calls when it issues Wait_For_Conversation or through a Windows message sent to a WNDPROC identified by hwndNotify in Specify_Windows_Handle. Once the processing mode is set for a conversation, it applies to all subsequent calls on the conversation until the mode is set again.

Specify_Windows_Handle (xchwnd)

Sets the Windows handle to which a message is sent on completion of an operation in nonblocking mode.

Wait_For_Conversation (cmwait)

Waits for the completion of an operation that has been initiated when the processing mode conversation characteristic was set to CM_NON_BLOCKING and CM_OPERATION_INCOMPLETE was returned in the return_code parameter. Use Wait_For_Conversation when running a background thread or a single-threaded application for the Windows NT or Windows version 3.x systems.

Important

An application can set the processing mode by calling Set_Processing_Mode. If the Windows handle is set to NULL, or this call is never issued, then the application must call Wait_For_Conversation to be notified when the outstanding operation completes.

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 lParam argument contains the CM_PTR to the conversation ID specified in the original function call.

WinCPICSetBlockingHook

Allows a Windows CPIC implementation to block CPIC function calls by means of a new function. Blocking calls apply only if you do not use asynchronous calls. If a function needs to block, the blocking call is called repeatedly until the original request completes. This allows Windows to continue to run while the original application waits for the call to return. Note that while inside the blocking call, the application can be re-entered. WinCPICSetBlockingHook is used by Windows version 3.x applications that go into a PeekMessageLoop to make blocking calls without blocking the rest of the system.

Note

By default, Windows NT does not go into a PeekMessageLoop, rather, it actually blocks on an event waiting for the call to complete. The only time it would be necessary to use WinCPICSetBlockingHook for Windows NT is when a single-threaded application for both Windows NT and Windows version 3.x share common source code. In this case, you must explicitly make this call. Contrast with WinCPICIsBlocking and WinCPICUnhookBlockingHook.

WinCPICIsBlocking

Determines if a task is executing while waiting for a previous blocking call to finish. Windows version 3.x goes into a PeekMessageLoop while allowing Windows to continue. Although a call issued on a blocking function appears to an application as though it blocks, the Windows CPIC dynamic link library (DLL) has to relinquish the processor to allow other applications to run. This means that it is possible for the application that issued the blocking call to be re-entered, depending on the message(s) it receives. In this instance, WinCPICIsBlocking can be used to determine whether the application task currently has been re-entered while waiting for an outstanding blocking call to finish.

This extension is intended to provide help to an application written to use the CM_BLOCKING characteristic of the Windows Specify_Processing_Mode function. WinCPICIsBlocking serves the same purpose as InSendMessage in the Windows API.

Applications targeted at Windows version 3.x that support multiple conversations must specify CM_NONBLOCKING in Specify_Processing_Mode so they can support multiple outstanding operations simultaneously. Applications are still limited to one outstanding operation per conversation in all environments. Note that Windows CPIC prohibits more than one outstanding blocking call per thread.

WinCPICUnhookBlockingHook

Removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism.

WinCPICStartup

Allows an application to specify the version of Windows CPIC required and to retrieve details of the specific CPIC implementation.

Important

This function must be called by an application before issuing any further Windows CPIC calls to register the application with a Windows CPIC implementation.

WinCPICCleanup

Terminates and deregisters an application from a Windows CPIC implementation.

Important

This function must be called by an application when finished to deregister the application from the Windows CPIC implementation.

Using Asynchronous Call Completion

With one exception, SNA Server permits one outstanding Windows SNA asynchronous call per connection and one blocking verb per thread. The exception to this guideline is that when issuing an asynchronous Receive call, the following calls can be issued while the Receive is outstanding:

Cancel_Conversation

Deallocate

Request_To_Send

Send_Error

Test_Request_To_Send_Receive

This allows an application, and in particular, a 5250 emulator, to use an asynchronous Receive to receive data. Use of this feature is strongly recommended.

The following example illustrates how to use asynchronous call completion for SNA Server:

void ProcessVerbCompletion (WPARAM wParam LPARAM lParam)

{

for ( i = 0; i<nPendingVerbs; i++ )

if (memcmp  (pPending [i].ConvID, (Conversation_ID) lParam) = = 0)

ProcessCommand  (wParam, lParam);

}

LRESULT CALLBACK SampleWndProc  ( . . .)

{

if (msg = = uAsyncCPIC )   {

ProcessVerbCompletion  (wParam, lParam);

}

else switch  (msg)  {

  case WM_USER:

Initialize_Conversation  ( lpConvId,  "GORDM",  &lError  );

if  ( lError  ! = CM_OK )   {

ErrorDisplay ( ) ;

break ;

}

Set_Processing_Mode  ( lpConvId,  CM_NON_BLOCKING,  &lError  ) ;

if  ( lError ! = CM_OK )  {

ErrorDisplay ( ) ;

break ;

}

Allocate  ( lpConvId,  &lError )  ;

switch  ( lError )  {

case CM_OK:

break ;

case CM_OPERATION_INCOMPLETE:

memcopy  (pPending [nPending ++].ConvId,  lpConvId,  sizeof  (C) ;

break ;

default:

ErrorDisplay ( ) ;

}

break ;

}

WinMain  ( . . . )

{

if  ( ( WinCPICStartup  ( . . . )  =  =  FALSE  )   {

return FALSE;

}

uAsyncCPIC = RegisterWindowMessage  ("WinAsyncCPIC"");

Specify_Windows_Handle  (hwndSample) ;

while  (GetMessage  ( . . . )   )   {

. . . . .

}

WinCPICCleanup  ( . . . )

}

For more information on CPIC calls and the Windows extensions, see Chapter 3, "CPIC Calls" and Chapter 4, "Extensions for the Windows Environment." For additional information on using CPIC, see the IBM Systems Application Architecture Common Programming Interface Communications Reference, part number SC26-4399-04.


CPIC Call Summary
Introduction to CPIC	5 of 18

CPIC Call Summary

This section briefly describes each CPIC call. The CPIC calls are grouped by function. The total functionality of a call may be broader than this summary indicates. The calls are grouped in categories according to the function they perform. There are calls that start and stop a conversation, send and receive data, get information, and get side information. For a detailed explanation of a particular call, see Chapter 3, "CPIC Calls."

The names of the calls are pseudonyms. The actual C function names appear in parentheses after the pseudonym. For example, Initialize_Conversation is the pseudonym for a call. The actual function name is cminit.


Starting a Conversation
Introduction to CPIC	6 of 18

CPIC Call Summary

Starting a Conversation

The calls in this category are used to start a conversation between two programs. For more information on this subject, see "How Programs Get Started" in Chapter 2.

Initialize_Conversation (cminit)

Issued by the invoking program to obtain a conversation ID and to set the initial values for the conversation’s characteristics. The initial values are derived from side information associated with the symbolic destination name or are CPIC defaults.

Initialize_Conversation sets the default characteristics of a conversation. There are several calls that begin with Set_. These calls let you override the default conversation characteristics.

Set_ Calls to Change Initial Conversation Characteristics

After issuing Initialize_Conversation, the invoking program can issue any of the following calls to change the initial conversation characteristics. These calls cannot be issued after Allocate has been issued.

Set_ Calls to Change Initial Conversation Characteristics

Call	Sets

Set_Conversation_Type (cmsct)	Conversation type

Set_Mode_Name (cmsmn)	Mode name

Set_Partner_LU_Name (cmspln)	Partner LU name

Set_TP_Name (cmstpn)	Program name

Set_Return_Control (cmsrc)	Return control

Set_Sync_Level (cmssl)	Synchronization level

Set_Conversation_Security_Type (cmscst)	Conversation security type

Set_Conversation_Security_User_ID (cmscsu)	Security user ID

Set_Conversation_Security_Password (cmscsp)	Security password

Allocate (cmallc)

Issued by the invoking program to allocate a conversation with the partner program, using the current conversation characteristics. CPIC also may start a session between the local LU and partner LU if one does not already exist. The type of conversation allocated depends on the conversation type characteristic — Mapped or Basic.

Accept_Conversation (cmaccp)

Issued by the invoked program to accept the incoming conversation and set certain conversation characteristics. Upon successful execution of this call, CPIC generates a conversation identifier.


Sending Data
Introduction to CPIC	7 of 18

CPIC Call Summary

Sending Data

The following calls are used to send data to the partner program.

Set_Send_Type (cmsst)

Sets the conversation’s send type. The send type specifies how data will be sent by Send_Data. The send type can specify that only data be sent or, in addition to sending data, CPIC execute the equivalent of Flush, Confirm, Prepare_To_Receive, or Deallocate. The send type value affects all subsequent Send_Data calls. It can be changed by reissuing Set_Send_Type.

Send_Data (cmsend)

Puts data in the local LU’s send buffer for transmission to the partner program. The data collected in the local LU’s send buffer is transmitted to the partner LU (and partner program) when one of the following occurs:

The send buffer fills up.

The local program issues a Flush, Confirm, or Deallocate call or other call that flushes the LU’s send buffer. (Some send types, set by Set_Send_Type, include flush functionality.)

Flush (cmflus)

Sends the contents of the local LU’s send buffer to the partner LU (and program). If the send buffer is empty, no action takes place.

Confirm (cmcfm)

Sends the contents of the local LU’s send buffer and a confirmation request to the partner program and waits for confirmation.

Set_Prepare_To_Receive_Type (cmsptr)

Sets the conversation’s prepare-to-receive type, which specifies whether subsequent Prepare_To_Receive calls will include Flush or Confirm functionality. The prepare-to-receive type affects all subsequent Prepare_To_Receive calls. It can be changed by reissuing Set_Prepare_To_Receive_Type.

Prepare_To_Receive (cmptr)

Changes the state of the conversation for the local program from SEND to RECEIVE, making it possible for the local program to begin receiving data. Before changing the conversation state, this call performs the equivalent of the Flush or Confirm call.

Request_To_Send (cmrts)

Notifies the partner program that the local program wants to send data. The partner program may or may not act on this request.


Receiving Data
Introduction to CPIC	8 of 18

CPIC Call Summary

Receiving Data

The following calls or extensions allow a program to receive data from its partner program.

Set_Receive_Type (cmsrt)

Sets the conversation’s receive type, which specifies whether a program issuing a Receive call will wait for data to arrive if data is not available. The receive type value affects all subsequent Receive calls. It can be changed by reissuing Set_Receive_Type.

Receive (cmrcv)

Issuing this call while the conversation is in RECEIVE state causes the local program to receive any data that is currently available from the partner program. If no data is available and the receive type is set to CM_RECEIVE _AND_WAIT, the local program waits for data to arrive. If the receive type is set to CM_RECEIVE_IMMEDIATE, the program does not wait.

Issuing this call while the conversation is in SEND or SEND-PENDING state is allowed only if the receive type is set to CM_RECEIVE_AND_WAIT. This flushes the LU’s send buffer and changes the conversation state to RECEIVE. The local program then begins to receive data.

Set_Fill (cmsf)

Used in a Basic conservation, this call sets the conversation’s fill type, which specifies whether programs will receive data in the form of logical records or as a specified length of data. This call has an effect only in Basic conversations. The fill value affects all subsequent Receive calls. It can be changed by reissuing Set_Fill.

Set_Processing_Mode (cmspm)

Specifies for the conversation whether subsequent calls will be returned when the operation they have requested is complete (blocking) or immediately after the operation is initiated (nonblocking). A program is notified of the completion of nonblocking calls when it issues Wait_For_Conversation or through a Windows message sent to a WNDPROC identified by the hwndNotify in Specify_Windows_Handle.

Specify_Windows_Handle (xchwnd)

Sets the Windows handle to which a message is sent on completion of an operation in nonblocking mode. An application can set the processing mode by calling Set_Processing_Mode. If the Windows handle is set to NULL, or this call is never issued, then the application must call Wait_For_Conversation to be notified when the outstanding operation completes.

WinCPICSetBlockingHook

Allows a Windows CPIC implementation to block CPIC function calls by means of a new function. This call must be explicitly called for Windows version 3.x applications to make blocking calls without blocking the rest of the system.

A Windows CPIC implementation has a default mechanism by which blocking CPIC functions are implemented. This function gives the application the ability to execute its own function at blocking time in place of the default function.


Confirming Receipt of Data and Reporting Errors
Introduction to CPIC	9 of 18

CPIC Call Summary

Confirming Receipt of Data and Reporting Errors

The following calls confirm receipt of data or report an error.

Confirmed (cmcfmd)

Replies to a confirmation request from the partner program. It informs the partner program that the local program has not detected an error in the received data. Because the program issuing the confirmation request waits for a confirmation, Confirmed synchronizes the processing of the two programs.

Set_Error_Direction (cmsed)

Specifies whether a program detected an error while receiving data or while preparing to send data. Error direction is relevant only when a program issues Send_Error in SEND-PENDING state — immediately after issuing Receive and receiving data as well as a status_received value of CM_SEND_RECEIVED.

Set_Log_Data (cmsld)

Used in a Basic conversation, this call specifies a log message (log data) and its length to be sent to the partner LU. This call has an effect only in Basic conversations. If present, log data is sent when Send_Error is issued or when the conversation is abnormally deallocated. After the log data is sent, CPIC resets the log data to null and the log data length to 0.

Send_Error (cmserr)

Notifies the partner program that the local program has encountered an application-level error. The local program can use Send_Error to inform the partner program of an error encountered in received data, to reject a confirmation request, or to truncate an incomplete logical record it is sending.


Getting Information
Introduction to CPIC	10 of 18

CPIC Call Summary

Getting Information

The following calls provide information to programs.

Extract_Calls

The Extract_ calls, listed in the following table, retrieve information about the characteristics of a specified conversation.

Calls to Retrieve Information

Call	Retrieves

Extract_Conversation_Security_Type (xcecst)	Security type

Extract_Conversation_Security_User_ID (cmecsu)	Security user ID

Extract_Conversation_State (cmecs)	Conversation state

Extract_Conversation_Type (cmect)	Conversation type

Extract_Mode_Name (cmemn)	Mode name

Extract_Partner_LU_Name (cmepln)	Partner LU name

Extract_Sync_Level (cmesl)	Synchronization level

Test_Request_To_Send_Received (cmtrts)

Determines whether a request-to-send notification has been received from the partner program.


Ending a Conversation
Introduction to CPIC	11 of 18

CPIC Call Summary

Ending a Conversation

The following calls end a conversation.

Set_Deallocate_Type (cmsdt)

Specifies how the conversation is to be deallocated. The deallocation instructions specified by this call take effect when Deallocate is issued or when the send type is set to CM_SEND_AND_DEALLOCATE and Send_Data is issued.

Deallocate (cmdeal)

Deallocates a conversation between two programs. Before deallocating the conversation, this call performs the equivalent of the Flush or Confirm call, depending on the current conversation synchronization level and deallocate type.

Terminate_Application (cmterm)

An extension to SAA CPIC, this call performs the equivalent of stopping and restarting the program without actually stopping the program. The reason for using this call is described in detail in Chapter 3, "CPIC Calls."


Administering Side Information
Introduction to CPIC	12 of 18

CPIC Call Summary

Administering Side Information

The calls summarized in the following table let CPIC applications add, replace, retrieve, or delete side information entries from memory.

Side Information Calls

Call		Action
Set_CPIC_Side_Information (xcmssi)		Add or replace side information entry
Extract_CPIC_Side_Information (xcmesi)		Retrieve side information
Delete_CPIC_Side_Information (xcmdsi)		Delete side information entry


Initial Conversation Characteristics
Introduction to CPIC	13 of 18

Initial Conversation Characteristics

CPIC maintains a set of internal values called characteristics for each conversation. Some characteristics affect the overall operation of the conversation, such as the conversation type. Others affect the behavior of specific calls, such as the receive type.

Many of these characteristics are initially derived from the side information table (described in the next section) in memory. Initialize_Conversation specifies the symbolic destination name (sym_dest_name) associated with the desired side information table entry.

Table 1.1 lists the initial values of the conversation characteristics and tells which call can change a given value. For a complete explanation of a characteristic, see the description of the CPIC call associated with it in Chapter 3, "CPIC Calls."

Table 1.1    Initial Conversation Characteristics

Characteristics		Initial value set by Initialize_Conversation		Initial value set by Accept_Conversation		Can be changed by
Conversation state		CM_INITIALIZE _STATE		CM_RECEIVE _STATE		Depends on call
Conversation type		CM_MAPPED _CONVERSATION		The value specified by the invoking program.		Set_Conversation _Type
Deallocate type		CM_DEALLOCATE _SYNC_LEVEL		CM_DEALLOCATE _SYNC_LEVEL		Set_Deallocate _Type
Error direction		CM_RECEIVE _ERROR		CM_RECEIVE _ERROR		Set_Error_Direction
Fill		CM_FILL_LL		CM_FILL_LL		Set_Fill
Log data		Null		Null		Set_Log_Data
Log data length		0		0		Set_Log_Data
Mode name		The mode name contained in the side information. If no sym_dest_name is specified, this is a null string.		The mode name for the session on which the conversation startup request arrived.		Set_Mode_Name
Mode name length		Length of mode name. If no sym_dest_name is specified, this is 0.		Length of mode name.		Set_Mode_Name
Partner LU name		The partner LU name contained in the side information. If no sym_dest_name is specified, this is a single blank.		The partner LU name for the session on which the conversation startup request arrived.		Set_Partner_LU _Name
Partner LU name length		Length of partner LU name. If no sym_dest_name is specified, this is 1.		Length of partner LU name.		Set_Partner_LU _Name
Prepare-to-receive type		CM_PREP_TO _RECEIVE_SYNC _LEVEL		CM_PREP_TO _RECEIVE_SYNC _LEVEL		Set_Prepare_To _Receive_Type
Receive type		CM_RECEIVE _AND_WAIT		CM_RECEIVE _AND_WAIT		Set_Receive_Type
Return control		CM_WHEN_SESSION _ALLOCATED		Not applicable.		Set_Return_Control
Send type		CM_BUFFER_DATA		CM_BUFFER_DATA		Set_Send_Type
Synchronization level		CM_NONE		The value specified by the invoking program.		Set_Sync_Level
Partner program name		The program name contained in the side information. If no sym_dest_name is specified, this is a single blank.		Not applicable.		Set_TP_Name
Partner program name length		Length of partner program name. If no sym_dest_name is specified, this is 1.		Not applicable.		Set_TP_Name
Security type		The security type contained in the side information.		The value specified by the invoking program.		Set_Conversation _Security_Type
User ID		The user ID contained in the side information. If no sym_dest_name is specified, this is a single blank.		The value specified by the invoking program.		Set_Conversation _Security_User_ID
Table 1.1    Initial Conversation User ID length		Length of user ID. If no sym_dest_name is specified, this is 1.		Length of user ID.		Set_Conversation _Security_User_ID
Password		The password contained in the side information. If no sym_dest_name is specified, this is a single blank.		The value specified by the invoking program.		Set_Conversation _Security_Password
Password length		Length of password. If no sym_dest_name is specified, this is 1.		Length of password.		Set_Conversation _Security_Password


Side Information
Introduction to CPIC	14 of 18

Side Information

The information required for two CPIC programs to communicate is stored as a table, called the side information table, in memory. The table is derived from the symbolic destination name (configured in SNA Server Admin) and from the Set_CPIC_Side_Information, Extract_CPIC_Side_Information, and Delete_CPIC_Side_Information calls.

The side information is maintained by the system administrator. For additional information about configuration, see the Microsoft SNA Server Administration Guide.

If you are developing commercial programs or programs that will be installed on multiple computers within your organization, it is recommended that you include logic that allows a user or system administrator to specify configuration information for each copy of the program.

Each side information entry contains the following fields:

Symbolic Destination Name

This is the sym_dest_name parameter specified by Initialize_Conversation. It is the identifier for the side information entry. The name can be up to eight ASCII characters. See "Set_CPIC_Side_Information (xcmssi)" in Chapter 3 for the allowed characters.

Partner LU Name

This is the name by which the partner LU is known to the local program. It can be an alias of up to 8 ASCII characters or a fully qualified network name of up to 17 characters. See "Set_Partner_LU_Name (cmspln)" in Chapter 3 for the allowed characters.

Partner Program Type and Name

These fields indicate whether the partner program is an application transaction program (TP) or an SNA service TP, and provide the partner program name. An application TP name can contain up to 64 ASCII characters. A service TP name can contain up to four characters. See "Set_TP_Name (cmstpn)" in Chapter 3 for the allowed characters.

Mode Name

This name represents a set of characteristics to be used in an LU-to-LU session. The mode name can contain up to eight ASCII characters. See "Set_Mode_Name (cmsmn)" in Chapter 3 for the allowed characters.

Conversation Security Type

This field indicates whether security will be used and if so, what type.

You can use conversation security to require that the invoking program provide a user ID and password before CPIC will allocate a conversation with the invoked program.

For an invoked program that in turn invokes another program the security type can inform the second invoked program that security has already been verified.

See "Set_Conversation_Security_Type (cmsct)" in Chapter 3 for further information about conversation security.

Security User ID and Password

If you intend to use conversation security, a valid combination of user ID and password is required to access the invoked program. The user ID and password can be up to 10 ASCII characters. See "Set_Conversation_Security_User_ID (cmscsv)" and "Set_Conversation_Security_Password (cmscsp)" in Chapter 3 for the allowed characters.


Configuration
Introduction to CPIC	15 of 18

Configuration

In addition to maintaining the side information (specified by sym_dest_name), the system administrator must define the following entities during configuration:

Modes

Local logical units (LUs)

Partner LUs

Invokable programs

User IDs and passwords

Note

For a user or group that will be using TPs, 5250 emulators, and/or Advanced ProgramtoProgram Communications (APPC) applications, you can assign a default local APPC LU and a remote APPC LU. These default LUs are accessed when the user or group member starts an APPC program (a TP, 5250 emulator, or APPC application) and the program does not specify LU aliases by leaving the field NULL or filling with blanks. For more information, see the Microsoft SNA Server Administration Guide.


Windows NT Considerations
Introduction to CPIC	16 of 18

Windows NT Considerations

This section summarizes things to keep in mind when you are developing programs on a Windows NT-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.

Byte ordering

By default, Intel byte ordering is used. For inline environments, defining NON_INTEL_BYTE_ORDER will do all the required flipping for constants. Nonconstant input parameters in verb control blocks (VCBs) — for example, lengths, pointers, and so on — are always in the native format.

Simultaneous conversations

A program can simultaneously participate in as many as 64 conversations per process.

Packing

For performance reasons, the VCBs are not packed. As a result of this, DWORDs are on DWORD boundaries, WORDs on WORDs, and BYTEs on BYTEs. VCBs should be accessed using the structures provided.

Events

To receive data asynchronously, an event handle is passed in the semaphore field of the VCB. This event must be in the nonsignaled state when passed to CPIC, and the handle must have EVENT_MODIFY_STATE access to the event.

Multiple threads

A TP can have multiple threads that issue verbs. Windows CPIC makes provisions for multithreaded Windows-based processes. A process contains one or more threads of execution. All references to threads refer to actual threads in a multithreaded Windows environment.

Run-time linking

For a TP to be dynamically linked to CPIC at run time, the TP must issue:

LoadLibrary to load WINCPIC.DLL or WINCPIC32.DLL, the dynamic load libraries for WINCPIC.

GetProcAddress to specify WINCPIC as the desired entry point to the dynamic-link library (DLL).

Issue the FreeLibrary call when the CPIC library is no longer required.

Yielding to other components

When processing CPIC and Common Service Verbs (CSVs), 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 the Windows extensions WinCPICSetBlockingHook and WinCPICUnhookBlockingHook.

WinCPICSetBlockingHook allows a Windows CPIC implementation to block CPIC 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)

For more information on using the Windows extensions, see Chapter 4, "Extensions for the Windows Environment."

Terminating applications

In the Windows NT environment, CPIC 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 A  L T  +  f  4  from a user), the application should call WinCPICCleanup. To initiate the call, use WinCPICStartup.

Library name

In preparation for the coexistence of Win16 and Win32 API libraries on the same computer, the Win32 DLL name has been changed from WINCPIC.DLL to WINCPIC32.DLL.

The old DLL name should be used for Win32-based applications that are required to run on SNA Server version 2.0. The new DLL name should be used for Win32-based applications that are intended to run only on SNA Server version 2.1 or later versions.

If you intend your Win32-based application to be used with SNA Server version 2.0, you should link with the library included with SNA Server version 2.0. Otherwise use the new library provided with SNA Server version 2.1.


Windows Considerations
Introduction to CPIC	17 of 18

Windows Considerations

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

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.

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.

Simultaneous conversations

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

Load-time linking

For a program to be dynamically linked to CPIC 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 the above statement for each entry-point needed.)

Link the program to WINCPIC.LIB, which contains the entry-point linkage information for CPIC. If you intend to use CSVs, you must also link to WinCSV.LIB, which contains the entry-point information for CSV.

Run-time linking

For a program to be dynamically linked to CPIC at run time, the program must issue:

LoadLibrary to load WINCPIC.DLL, the dynamic load library for CPIC.

GetProcAddress to specify CPIC as the desired entry point to the DLL.

Issue the FreeLibrary call when the CPIC library is no longer required.

TP names

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

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

Local LUs

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

Yielding to other components

When processing CPIC and CSVs, 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 CPIC implementation to block CPIC 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)

For more information on using Windows CPIC extensions, see Chapter 4, "Extensions for the Windows Environment."

Terminating applications

In the Windows environment, CPIC 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. To initiate the call, use WinCPICStartup.


OS/2 Considerations
Introduction to CPIC	18 of 18

OS/2 Considerations

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

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.

Simultaneous conversations

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

Load-time linking

For a program to be dynamically linked to CPIC 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 the statement above for each entry-point needed.)

Link the program to WINCPIC.LIB, which contains the entry-point linkage information for CPIC.

Run-time linking

For a program to be dynamically linked to CPIC at run time, the program must issue:

DosLoadModule to load CPIC.DLL, the dynamic load library for CPIC.

DosGetProcAddr to specify the desired entry points to the DLL. Each CPIC call is an entry point to the DLL.

Unlinking (the DosFreeModule call) is not supported.

Stack size

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

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

Multiple processes

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

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.

Multiple threads

A program can have multiple threads that issue calls. However, the program cannot issue two calls simultaneously on the same conversation. If CPIC 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.

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 CPIC call within a critical section.

TP names

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

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

Local LUs

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

OS/2 exception TRAP 000D

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

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.


Writing CPI-C Applications
Chapter 2	1 of 28

Writing CPI-C Applications

A processing task accomplished by programs using APPC or CPIC is called a transaction. Consequently, programs that use CPIC are called transaction programs, or TPs. These programs communicate as peers, on an equal (rather than hierarchical) basis. The TPs use CPIC calls to exchange status information and application data. Each TP uses CPIC calls to supply parameters to CPIC, which performs the desired function and returns parameters to the TP.

TPs distributed across a local or wide area network perform distributed transaction processing.

This chapter describes how to write TPs and how to configure the systems on which TPs run. The sections in this chapter cover the following general areas:

Understanding fundamental concepts related to TPs

Designing and coding TPs

Configuring Registry and environment variables for invokable TPs

Configuring SNA Server to work with your TPs


Communication Between TPs
Writing CPI-C Applications	2 of 28

Communication Between TPs

Various hardware and software elements in the SNA environment are required in order for two TPs to communicate with each other. Figure 2.1 illustrates several fundamental elements:

Figure 2.1    Communication Between TPs

Each TP is associated with an LU of type 6.2. The LU allows the TP to access the network. Note that several TPs can be associated with the same LU.

A partner TP can invoke another TP, which, in turn, invokes another TP, and so on. In Figure 2.2, TP A invokes TP B, and TP B invokes TP C.

Figure 2.2    Partner TP Invoking Another TP


Fundamental Terms for TPs and LUs
Writing CPI-C Applications	3 of 28

Communication Between TPs

Fundamental Terms for TPs and LUs

The following terms help to describe some fundamental characteristics of TPs communicating through LUs:

LU-LU Session

The communication between two LUs over a specific connection for a specific amount of time. An LU-LU session is needed before two TPs can interact. One session can be used serially by many pairs of TPs.

An LU 6.2 can have multiple sessions (two or more concurrent sessions with different partner LUs) and parallel sessions (two or more concurrent sessions with the same partner LU).

LUs are configured through the SNA Server Administration program (SNA Server Admin), as are LU-LU pairs and modes; the LU and mode configurations control how many sessions a particular LU-LU pair supports.

LU alias

The string that identifies an LU to a TP. The alias can be as many as eight characters long.

Conversation

The interaction between TPs carrying out a specific task. Each conversation requires an LU-LU session. A TP can be involved in several conversations simultaneously, as shown with TP “B” in Figure 2.2, earlier in this chapter.

Local LU and local TP

An LU and TP working together, when viewed as the “home base” for a particular conversation. From this viewpoint, some other LU and TP are seen as the “partner” or “remote” LU and TP.

Partner LU and partner TP, or remote LU and remote TP

An LU and TP working together, when viewed as being at the far end of a particular conversation.

Mapped conversation

A type of conversation simpler than a Basic conversation, and generally used by application TPs (programs that accomplish tasks for end users). The default for conversation type is Mapped; the conversation type can be changed with the Set_Conversation_Type call. For more information, see "Basic and Mapped Conversations Compared," later in this chapter.

Basic conversation

A type of conversation more complex than a Mapped conversation, and generally used by service TPs (SNA-based programs that provide services to other programs). For a Basic conversation, use Set_Conversation_Type, and specify CM_BASIC_CONVERSATION for the conversation_type. For more information, see "Basic and Mapped Conversations Compared," later in this chapter.

Invoking TP

A TP that can invoke (that is, initiate a conversation with) other TPs. Invoking TPs are generally client-type applications, that is, they work in the same general way that an emulator works. For more information about invoking TPs, see "Invoking TPs," later in this chapter.

Invokable TP

A TP that can be invoked by another TP. Invokable TPs are generally server-type applications, that is, they work in the same general way that an application such as CICS [image] works. Parameters for an invokable TP are configured through Registry or environment variables.

There are several types of invokable TPs:

Operator-started invokable TP

A TP that is started manually in preparation for being invoked.

Autostarted invokable TP

A TP that is automatically started by CPIC when invoked.

Queued TP

A TP that, when invoked multiple times, loads once and then queues up subsequent requests to be dealt with one at a time. All operator-started TPs and some autostarted TPs are queued.

Nonqueued TP

A TP loaded multiple times, once for every time it is invoked. Some autostarted TPs are nonqueued (but no operator-started TPs are nonqueued).

For more information about invokable TPs, see "Invokable TPs," later in this chapter.


Sample TPs Illustrating Fundamental Concepts
Writing CPI-C Applications	4 of 28

Communication Between TPs

Sample TPs Illustrating Fundamental Concepts

A set of sample TPs are provided on the SNA Server CD in the \SDK\SAMPLES directory. Included with the sample code is TPSETUP, a program that simplifies the setting of Registry or environment variables needed by autostarted invokable TPs. Without an interface like that provided by TPSETUP, configuring of such variables can be complicated and errorprone. Therefore, it is recommended that you use code like TPSETUP in installation programs for autostarted invokable TPs.

INSTALL.C (the source code for TPSETUP) can be compiled to work either in the Windows NT environment or in the Windows version 3.x environment.

For information about TPSETUP and about the sample TPs, see Appendix B, "Sample CPIC TPs in the SDK."


Configuring and Controlling TPs
Writing CPI-C Applications	5 of 28

Communication Between TPs

Configuring and Controlling TPs

The characteristics of the TPs and selection of the LUs involved in a conversation are controlled in various ways:

Table 2.1    Controlling the Characteristics of TPs

Characteristic	How the characteristic is controlled
Type of conversation: Basic or Mapped	Written into the code of the TPs. In order for two TPs to communicate successfully, they must both use the same type of conversation, Basic or Mapped. The default for conversation type is Mapped; the type can be changed with the Set_Conversation_Type call. For more information, see "Basic and Mapped Conversations Compared," later in this chapter.
Type of TP: invoking or invokable	Written into the code. Invoking TPs start with Initialize_Conversation and Allocate. Invokable TPs start with Accept_Conversation. For more information, see "Invoking TPs" and "Invokable TPs," later in this chapter.
The local LU alias to be used by an invoking TP	Three options: Configured with a Registry or environment variable Configured (in SNA Server Admin) as the Default Local APPC LU for the user who starts the invoking TP Configured (in SNA Server Admin) as a member of the default outgoing local APPC LU pool For information, see "Invoking TPs and the SNA Server Configuration," later in this chapter.
The symbolic destination name used by an invoking TP	Written into the code, in Initialize_Conversation.
The invokable (partner) TP requested by an invoking TP	Specified within the symbolic destination name, which can be configured through SNA Server Admin.
The LU alias to be used by an invokable TP (from the point of view of the invoking TP, the partner LU alias)	Specified within the symbolic destination name, which can be configured through SNA Server Admin. For information, see "Invoking TPs and the SNA Server Configuration" and "How an Invokable TP is Matched to an Invoking TP's Request," later in this chapter.
Type of autostarted invokable TP: queued or nonqueued	Configured with Registry or environment variables. For more information, see "Configuring Invokable TPs," later in this chapter.
Local LU and remote LU aliases	Configured in SNA Server Admin. For information, see the Microsoft SNA Server Administration Guide.
The pairing of local and remote LUs, and the mode used for each LULU pair	Configured in SNA Server Admin. For information, see the Microsoft SNA Server Administration Guide.


Steps for Creating TPs and the Configuration to Support Them
Writing CPI-C Applications	6 of 28

Communication Between TPs

Steps for Creating TPs and the Configuration to Support Them

The following list shows the general procedure for creating TPs and setting up a configuration to support them:

1.	Write, compile, and link each TP.

2.	Place each TP on an appropriate computer.

For TPs that you will start many times, or that will be started by a user, arrange for the TP to be started easily. That is, for graphical interfaces, create a program icon for starting the TP; for nongraphical interfaces, make sure the TP is in the path.

3.	On one or more SNA servers, configure LUs, modes, LU-LU pairs, and a symbolic destination name for use by the TPs.

For information about how to set up LU-LU pairs to support TPs, see "Using Invoking and Invokable TPs," later in this chapter, as well as the Microsoft SNA Server Administration Guide. For information about symbolic destination names and side information, see "Side Information" in Chapter 1 of this guide, and see the Microsoft SNA Server Administration Guide.

4.	Set any Registry or environment variables needed for the invoking and invokable TPs.

For autostarted invokable TPs, it is recommended that you use the sample TP configuration program, TPSETUP, for this step. When you write an installation program for autostarted invokable TPs, it is recommended that you add code similar to TPSETUP to the installation program.

For information about Registry or environment variables, see "Configuring Invokable TPs" and "Invoking TPs," later in this chapter. For information about TPSETUP, see Appendix B, "Sample CPIC TPs in the SDK."

5.	If the invokable TP is operator-started, start it, or arrange for it to be started when the computer is restarted (and then restart the computer).

If the invokable TP is autostarted, SNA Server will start it when needed.

6.	Start the invoking TP.

The remainder of this chapter discusses the coding and configuration of TPs, and covers the following general topics:

Designing and coding TPs

Configuring Registry and environment variables for invokable TPs

Configuring SNA Server to work with your TPs


Designing and Coding TPs
Writing CPI-C Applications	7 of 28

Designing and Coding TPs

This section provides background information about designing and coding TPs. The following topics are discussed:

CPIC calls in C programs

CPIC and LU 6.2

Conversation states

Confirmation processing

Conversation security

Basic and Mapped conversations

Invoking and invokable TPs


CPIC Calls in C Programs
Writing CPI-C Applications	8 of 28

Designing and Coding TPs

CPIC Calls in C Programs

This implementation of CPI-C is available to programs written in Microsoft C version 5.1 or later.

The WINCPIC.H header file defines the prototypes for each CPI-C function. Other definitions include:

Types specifically defined for use by CPI-C parameters.

The structure of the side information entries.

Symbolic names defined for integer parameters.

The program must include WINCPIC.H and declare the variables to be used in passing parameters on CPI-C calls. Note that you must define WINDOWS, WIN32 or DOS5 before including WINCPIC.H. For example:

Win3.x clients:	#define WINDOWS

#include <wincpic.h>

OS/2 clients:	#define DOS5

#include <wincpic.h>

Win NT clients	#define WIN32

#include <wincpic.h>

In the case of strings, the program must also determine the desired string length.


CPIC and LU 6.2
Writing CPI-C Applications	9 of 28

Designing and Coding TPs

CPIC and LU 6.2

CPIC applications can communicate with non–CPIC LU 6.2 applications, such as APPC.

CPIC supports all functions of LU 6.2 except:

Sync point/back out processing.

PIP data.

LOCKS=LONG.

MAP_NAME.

FMH_DATA.


Conversation States
Writing CPI-C Applications	10 of 28

Designing and Coding TPs

Conversation States

The state of the conversation (as viewed by a particular TP) governs which CPIC calls can be made by the TP at a particular time. For example, a TP cannot issue Send_Data if the conversation is not in SEND or SEND-PENDING state for that TP.

The state of a conversation depends on the TP from which it is viewed. A local TP may view a conversation as being in SEND state while the partner TP views the conversation as being in RECEIVE state. A particular TP may be in several conversations, each of which is in a different state.

The possible conversation states are summarized in Table 2.2.

Table 2.2    Conversation States

State	Description

CONFIRM	The program has received a request for confirmation of receipt of data; it must respond positively or send error information to the partner program.

CONFIRM-DEALLOCATE	The program has received a request for confirmation and must respond positively or send error information. If the program responds positively, the conversation is automatically deallocated.

CONFIRM-SEND	The program has received a request for confirmation; it must respond positively or send error information. After responding, the program can begin to send data.

INITIALIZE	The conversation has been initialized successfully.

RECEIVE	The program can receive application data and status information from the partner program. When the conversation is in RECEIVE state, the program can also send error information and request permission to send data.

RESET	The conversation has not started or has been terminated.

SEND	The program can send data to the partner program and request confirmation. When the conversation is in SEND state, the program can also begin to receive data, which can cause the state to change to RECEIVE.

SEND-PENDING	The program issued a Receive call and received data as well as a send indicator (status_received = CM_SEND_RECEIVED), indicating that the program can begin to send data. This state differs from the SEND state, which occurs when the program receives data on one Receive call and the send indicator on a subsequent Receive call.

State Checks

A state check occurs when a TP issues a CPIC call, and the conversation is not in the appropriate state. For instance, a state check would occur if a TP issued Send_Data while the conversation was in RECEIVE state. When a state check occurs, CPIC does not execute the call; it returns state-check information through the return_code parameter.

Changing Conversation States

A change in the conversation state can result from:

A call made by the local TP.

A call made by the partner TP.

An error condition.

The example that follows shows how CPIC calls can change the state of the conversation from SEND to RECEIVE and from RECEIVE to SEND.

Note

Any TP can potentially send or receive data, regardless of whether the TP is the invoking TP (the TP that started the conversation) or the invokable TP (the TP that responded to a request to start a conversation).

This table shows how the conversation state can change. In this table, each conversation state appears in bold, and precedes the CPIC calls that are used while in that state.

Issued by the invoking TP	Issued by the invokable TP
Conversation state: RESET
Initialize_Conversation
Conversation state: INITIALIZE
Set_Sync_Level
(sync_level=CM_CONFIRM)
Allocate
Conversation state: SEND
Send_Data
Prepare_to_Receive	Conversation state: RESET
	Accept_Conversation
	Conversation state: RECEIVE
	(status_received=    CM_CONFIRM_SEND_RECEIVED)
	Conversation state: CONFIRM-SEND
	Confirm
	Conversation state: SEND
(return_code=CM_OK)	Send_Data
Conversation state: RECEIVE	Confirm
(status_received=   CM_CONFIRM_RECEIVED)
Conversation state: CONFIRM
Request_To_Send
Confirmed
Conversation state: RECEIVE	(return_code=CM_OK)
	(request_to_send_received=   CM_REQ_TO_SEND_RECEIVED)
	Prepare_To_Receive
Receive
(status_received=    CM_CONFIRM_SEND_RECEIVED)
Conversation state: CONFIRM-SEND
Confirmed
Conversation state: SEND	(return_code=CM_OK)
	Conversation state: RECEIVE
Send_Data
Deallocate
	Receive
	(status_received=   CM_CONFIRM_DEALLOC_RECEIVED)
	Conversation state: CONFIRM-DEALLOCATE
	Confirmed
(return_code=CM_OK)	Conversation state: RESET
Conversation state: RESET
Initial States

Before the conversation is allocated, the state is RESET for both TPs.

In the example, after the conversation is allocated, the initial state is SEND for the invoking TP and RECEIVE for the invokable TP.

Changing to RECEIVE State

The Prepare_To_Receive call allows a TP to change the conversation from SEND to RECEIVE state. This call:

Flushes the local LU’s send buffer.

Since the synchronization level is set to CM_CONFIRM, Prepare_To_Receive sends a CM_CONFIRM_SEND indicator to the partner TP through the status_received parameter of a Receive call. This indicator tells the partner program that a Confirmed response is expected before the partner program can begin to send data.

Changing to SEND State

The Request_To_Send call informs the partner TP (for which the conversation is in SEND state) that the local TP (for which the conversation is in RECEIVE state) wants to send data. This request is communicated to the partner TP through the request_to_send_received parameter of the Confirm call. (The request_to_send_received parameter is also returned to Send_Data and other calls.)

When the partner TP issues the Prepare_To_Receive call, the conversation state changes to RECEIVE for the partner TP, making it possible for the local TP to send data.

Important

Issuing Request_To_Send does not change the state of the conversation. Upon receiving a request to send, the partner TP is not required to change the conversation state; it can ignore the request.


Confirmation Processing
Writing CPI-C Applications	11 of 28

Designing and Coding TPs

Confirmation Processing

Using confirmation processing, a TP sends a confirmation request with the data; the partner TP confirms receipt of the data or indicates that an error occurred. Each time the two TPs exchange a confirmation request and response, they are synchronized.

Note

Although the example in this section does not show this, any TP can potentially send or receive data, regardless of whether the TP is the invoking TP or the invokable TP.

The following example illustrates confirmation processing.

Issued by the invoking TP	Issued by the invokable TP
Initialize_Conversation
Set_Sync_Level  (sync_level=CM_CONFIRM)
Allocate
Send_Data
Confirm
	Accept_Conversation
	Receive (data_received=    CM_COMPLETE_DATA_RECEIVED) (status_received=    CM_CONFIRM_RECEIVED)
	Confirmed
(return_code=CM_OK)
Send_Data
Deallocate
	Receive
	(status_received=    CM_CONFIRM_DEALLOC_RECEIVED)
	Confirmed
(return_code=CM_OK)
The following sections describe the steps used for confirmation processing.

Establishing the Synchronization Level

The Set_Sync_Level call lets you override the default synchronization level of the conversation. The synchronization level is one of the conversation’s characteristics. There are two possible synchronization levels:

CM_CONFIRM, under which the programs can request confirmation of receipt of data and respond to such requests

CM_NONE, the default, under which confirmation processing does not occur

The Initialize_Conversation call sets the default characteristics of a conversation. There are several calls that begin with Set_. These calls let you override the default conversation characteristics.

Sending a Confirmation Request

Issuing the Confirm call has two effects:

It flushes the local LU’s send buffer (which sends any data contained in the buffer to the partner program).

It sends a confirmation request, which the partner program receives through the status_received parameter of a Receive call.

After issuing Confirm, the local TP waits for confirmation from the partner TP.

Receiving a Confirmation Request

The status_received parameter of the Receive call indicates any future action required by the local program.

In the example in “Confirmation Processing” earlier in this chapter, the first Receive has a status_received of CM_CONFIRM_RECEIVED, indicating that a confirmation is required before the partner program can continue.

Responding to a Confirmation Request

The partner TP issues the Confirmed call to confirm receipt of data. This frees the local TP to resume processing.

Deallocating the Conversation

Because the synchronization level of the conversation is set to CM_CONFIRM, Deallocate sends a confirmation request with the data flushed from the buffer.

For the second Receive call, status_received is CM_CONFIRM_ DEALLOC_RECEIVED, indicating that the partner program requires a confirmation, generated by the Confirmed call, before the conversation can be deallocated.


Conversation Security
Writing CPI-C Applications	12 of 28

Designing and Coding TPs

Conversation Security

You can use conversation security to require that the invoking TP provide a user ID and password before CPIC will allocate a conversation with the invokable TP.

For the invoking TP, conversation security is activated and configured (with user ID and password) through the symbolic destination name in SNA Server Admin, or by the following calls, which override the symbolic destination name:

Set_Conversation_Security_Type

Set_Conversation_Security_User_ID

Set_Conversation_Security_Password

For the invokable TP, conversation security is activated and configured through Registry or environment variables on the computer where the invokable TP is located.

With communication involving more than two TPs, the verification of a user ID and password can be passed from one TP to another. Suppose that TP A invokes TP B, which requires security information, and TP B in turn invokes TP C, which also requires security information. TP B can inform TP C that conversation security has already been verified.

For information about the Registry or environment variables affecting conversation security, see "Configuring Invokable TPs," later in this chapter. For information about symbolic destination names and side information, see "Side Information Calls" in Chapter 1 of this guide, and see the Microsoft SNA Server Administration Guide.


Basic and Mapped Conversations Compared
Writing CPI-C Applications	13 of 28

Designing and Coding TPs

Basic and Mapped Conversations Compared

The default for conversation type is Mapped; to change to a Basic conversation, use Set_Conversation_Type, and specify CM_BASIC_CONVERSATION for the conversation_type. For definitions of Basic and Mapped conversations, see "Fundamental Terms for TPs and LUs," earlier in this chapter.

The following table offers some guidelines for choosing between Basic and Mapped conversations for your TPs.

Characteristic	Basic conversations	Mapped conversations
Common use	Generally used for service TPs.	Generally used for application TPs.
Partnering	Must be used to communicate with an existing TP that uses Basic verbs.	Must be used to communicate with an existing TP that uses Mapped verbs.
Sending and receiving method	Before a TP can begin a send operation, it must convert data records into logical records. The TP does this by adding a 2byte prefix that indicates the length of the record. A TP can send several logical records at one time. When a partner TP receives logical records, it must reconstruct them into usable data records. For more information, see "Logical Records Used in Basic Conversations," later in this chapter.	A TP sends data one record at a time. Neither the sending TP nor the receiving TP needs to convert data records to or from different forms.
Abnormal termination	In the Deallocate call, a TP can indicate whether an error or ABEND (abnormal program termination) was caused by a TP or by a program using the TP.	A TP can indicate an error or ABEND, but cannot tell whether a problem was caused by a TP or by a program using a TP.
	A TP can indicate whether an ABEND was caused by a timeout or by a critical error.	A TP cannot indicate the cause of an ABEND.
Logging of errors	For an error or ABEND, a TP can send an error message, in the form of a general data stream (GDS) error log variable, to the local log and to the partner LU.	For an error or ABEND, a TP cannot send an error message to the local log or to the partner LU.
Logical Records Used in Basic Conversations

Logical records are sent and received in Basic conversations only.

A TP can send or receive multiple logical records with a single Send_Data or Receive call. A TP can also send or receive a logical record in successive portions—beginning, middle, and end.

A logical record is made up of:

A 2-byte record-length (LL) field.

A data field that can range in length from 0 bytes through 32,765 bytes.

The LL field contains a hexadecimal value; this value is the length of the data field plus two bytes (for the LL field). For example, if a record contains 228 bytes of application data, the logical record length would be 230. The LL field would be X'00E6', the hexadecimal equivalent of 230. If the length of the data field is 0, the value contained in the LL field is X'0002'.

Logical records are sent from or received in a data buffer established by the TP. In the data buffer, the LL field must not be in Intel byte-swapped format. For example, a length of 230 must be X'00E6' (not X'E600').

The LL field cannot be X'0000' or X'0001', which allow less than the 2 bytes required for the LL field itself. The LL field also cannot be greater than or equal to X'8000', which is equivalent to decimal 32,768, and therefore allows for a data field greater than 32,765 and/or an LL field greater than 2.

Setting the most significant bit of the LL field to 1 indicates that the information contained in this logical record is continued in the next logical record.

An Example of a Mapped Conversation

For background information about Mapped conversations, see "Basic and Mapped Conversations Compared," earlier in this chapter.

The following example of a Mapped conversation shows the CPIC calls used to start a conversation, exchange data, and end the conversation. Call parameters are in parentheses.

Issued by the invoking TP	Issued by the invokable TP
Initialize_Conversation
Allocate
Send_Data
Deallocate	Accept_Conversation
	Receive
	(data_received=
	CM_COMPLETE_DATA_RECEIVED)
	(return_code=
	CM_DEALLOCATED_NORMAL)
The following sections describe the calls that are used in a Mapped conversation.

Calls for Starting a Mapped Conversation

To start a conversation, the invoking program issues the following calls:

Initialize_Conversation

Requests CPIC to set the values defining the characteristics of the conversation.

The Initialize_Conversation call specifies a symbolic destination name, which is associated with an entry in a side information table in memory. The side information specifies partner program, partner LU, mode, security, and so forth.

Allocate

Requests that CPIC establish a conversation between the invoking TP and the invokable TP.

The invokable TP issues the Accept_Conversation call, which informs CPIC that it is ready to begin a conversation with the invoking program.

Calls for Sending Data in a Mapped Conversation

The Send_Data call puts one data record (a record containing application data to be transmitted) in the send buffer of the local LU. The transmission of the data to the partner TP does not happen until one of the following events occurs:

The send buffer fills up.

The sending TP makes a call that forces CPIC to flush the buffer (send data to the partner TP).

In addition to the data record, the send buffer also contains the allocation request (which precedes the data record).

In the preceding example, Deallocate flushes the send buffer, sending the allocation request and data to the partner program. (Among other calls that flush the buffer are Confirm and Flush.)

Calls for Receiving Data in a Mapped Conversation

The Receive call receives the data record and status information from the partner program. If no data or status information is currently available, the local program, by default, waits for data to arrive.

The data_received parameter of Receive tells the program whether it received data and if so, whether the data is complete or not.

Calls for Ending a Mapped Conversation

To end a conversation, one of the TPs issues Deallocate, which causes CPIC to deallocate the conversation between the two TPs.


Using Invoking and Invokable TPs
Writing CPI-C Applications	14 of 28

Designing and Coding TPs

Using Invoking and Invokable TPs

There are two kinds of TPs: TPs that can invoke (that is, initiate a conversation with) other TPs, and TPs that can be invoked. A TP that can invoke another TP is called an invoking TP, and a TP that can be invoked is called an invokable TP.

The following sections describe how:

Invoking TPs request invokable TPs.

Invokable TPs identify themselves to SNA Server in preparation for being invoked.

An invokable TP is matched to an invoking TP’s request.

For information about how to configure LUs to support TPs, see "Configuring an SNA Server to Support TPs," later in this chapter, and the Microsoft SNA Server Administration Guide.


Invoking TPs
Writing CPI-C Applications	15 of 28

Designing and Coding TPs

Invoking TPs

An invoking TP can be located on any system on the SNA network. An invoking TP identifies itself by issuing Initialize_Conversation.

Initialize_Conversation specifies the name of the invoking TP and the symbolic destination name to be used. A local LU alias can be specified for the invoking TP by using a Registry or environment variable, as shown in the following table.

Operating system on computer that contains invoking TP		Location and name of variable
Windows NT		Location in Registry: HKEY_LOCAL_MACHINE    SYSTEM     CurrentControlSet       Services         SnaBase           Parameters Variable:TPname:REG_SZ:localLUalias
Windows version 3.x		Section and variable in WIN.INI file: [ApplicationName] APPCLLU=localLUalias
OS/2		Section and variable in SNA.INI file: [ApplicationName] APPCLLU=localLUalias Alternatively, this can be configured through set commands, either at the command prompt or in CONFIG.SYS.
If the local LU alias is not specified in a Registry or environment variable, SNA Server must be configured to supply one, through one of two types of “default” local LU; otherwise, Initialize_Conversation will fail. For more information, see "Invoking TPs and the SNA Server Configuration," later in this chapter.

Next, the symbolic destination name specified in Initialize_Conversation provides the name of the invokable (or partner) TP and the partner LU alias (the LU alias to be used by the invokable TP). With this information available, the invoking TP can issue the Allocate call.

After a TP successfully issues an Allocate call, an allocation request flows. For more information about what happens after an invoking TP requests an invokable TP, see "How an Invokable TP is Matched to an Invoking TP's Request," later in this chapter.

Invoking TPs and Contention

The following information applies only to cases where LUs are communicating in complex ways (such as chains of LUs) over multiple sessions. In such cases, two LUs may attempt to allocate a conversation on the same session at the same time. If this happens, one LU must win (the contention winner) and one must lose (the contention loser). The contention-winner LU and the contention-loser LU are determined for each session when the session is established. During that particular session, the contention-loser LU must receive permission from the contention-winner LU before allocating a conversation. In contrast, the contention-winner LU on that session allocates a conversation as needed.

Note that when two LUs are communicating over multiple sessions, one LU may be the contention winner for some of the sessions, and the other LU the contention winner for others.

An invoking TP will operate best if the number of concurrent Allocate requests that the TP will issue is matched by the number of sessions on which the local LU is the contention winner. The choice of contention winner is controlled through the modes configured at the two ends of the communication. For SNA Server, the mode is configured in SNA Server Admin. A mode must be configured to work with the mode on the remote system in order for communication to begin between two LUs. For more information about modes, see the Microsoft SNA Server Administration Guide.


Invokable TPs
Writing CPI-C Applications	16 of 28

Designing and Coding TPs

Invokable TPs

An invokable TP is a TP that can be invoked by another TP. Invokable TPs are written or configured (through Registry or environment variables) to supply their names to SNA Server, as a notification that they are available for incoming requests. SNA Server invokable TPs can be run on any SNA Server or client running Windows NT, Windows version 3.x, or OS/2.

There are two types of invokable TPs:

Operator-started invokable TPs

An operator-started invokable TP must be started by an operator before the TP can be invoked. When the operator-started invokable TP is started, it notifies SNA Server of its availability by issuing an Accept_Conversation call. The Accept_Conversation call causes the name of the invokable TP to be communicated to all the SNA servers in the domain, along with the alias of an associated LU, if one has been configured through a Registry or environment variable.

Autostarted invokable TPs

An autostarted invokable TP can be started by SNA Server when needed. The TP must be registered (through Registry entries or environment variables) on its local system, so that it can be identified to the SnaBase component of the SNA Server client software. The registered information defines the TP as autostarted, and must specify the TP name. The registered information may also specify the local LU alias that the invokable TP will use.

The recommended method for setting Registry or environment variables for autostarted invokable TPs is to use the sample TP configuration program, TPSETUP, or similar code written into your own installation program. For more information about Registry or environment variables for invokable TPs, see "Configuring Invokable TPs," later in this chapter. For information about TPSETUP, see Appendix B, "Sample CPIC TPs in the SDK."

If no local LU alias is registered with autostarted TPs, the resulting SNA Server configuration can be more flexible in responding to invoking requests. For more information about such flexible configurations, see "TP Name Not Unique; Local LU Alias Unspecified" later in this chapter.

After an autostarted invokable TP is started by SNA Server, the TP issues Accept_Conversation (just as an operator-started TP does). Accept_Conversation must provide the same TP name as was registered for the TP.

Autostarted TPs must be configured (through Registry or environment variables) to be either queued or non-queued. All operator-started TPs act as queued TPs.

Queued TPs (including all operator-started TPs)

If an autostarted TP is configured as queued, or if the TP is operator-started, incoming allocation requests are queued, and then sent only when the invokable TP issues Accept_Conversation. For autostarted invokable TPs, if a copy of the TP is not yet running, one is started when the first incoming allocation request specifies that TP.

Note

For the Windows NT system, only one copy of a service can be running at any given time; this means that all autostarted TPs that run as services under Windows NT must be queued. To write an autostarted TP so it will run under Windows NT as a service and also run in a “nonqueued” way, write a multithreaded program with an Accept_Conversation always outstanding.

Nonqueued TPs

If an autostarted TP is configured as nonqueued, every time an Allocate is received for the TP, a new copy will be started. Nonqueued TPs should process the conversation they have been allocated and then exit, since they will not receive any additional Allocate requests.

Subcategories for Autostarted Invokable TPs

Figure 2.3 shows subcategories for invokable TPs.

Figure 2.3    Subcategories for Invokable TPs

1. The concept of a TP “running as a service” or “running as an application” is distinct from a “service TP” or an “application TP.” “Service TP” and “application TP” are SNA terms that describe how a TP is used — either as a supportive “service” program for other APPC programs, or directly by a user, as an application. For detailed information about Windows NT-based services and applications, see the documentation for Windows NT and for Win32. 2. To write an autostarted TP so it will run under Windows NT as a service and also run in a “nonqueued” way, write a multithreaded program with an Accept_Conversation always outstanding. For more information, see the previous section. 3. To run an autostarted TP as an application under Windows NT, make sure the TPSTART program is always started before the TP. For more information, see Appendix B, "Sample CPI-C TPs in the SDK."


How an Invokable TP is Matched to an Invoking TP’s Request
Writing CPI-C Applications	17 of 28

Designing and Coding TPs

How an Invokable TP is Matched to an Invoking TP’s Request

Each SNA server maintains a list of available invokable TP names, and any LU aliases to be associated with the TP names. This information is obtained as follows:

For autostarted invokable TPs, Registry or environment variables identify a TP name containing a maximum of 8 characters, and may specify an associated LU. This information is sent from the client to the server that sponsors the client. (A client learns about the domain through a sponsor connection to a server; clients must establish the sponsor connection before proceeding with any other tasks.)

For operator-started invokable TPs, a TP name (consisting of a maximum of 64 characters) is specified in Specify_Local_TP_Name (or, for OS/2 only, by setting APPCTPN=TPname). The TP name is truncated to 8 characters and sent from the client to the server that sponsors the client, along with the alias of an associated LU, if one has been configured through a Registry or environment variable.

Note

If you want a TP name to be unique, it is recommended that you limit the name to eight characters or less, or else make the name unique within the first eight characters. This is because the preliminary routing of allocation requests is carried out using the first eight characters. Although further matching is later carried out between the full TP names, it is inefficient to allow the preliminary routing to succeed when in some cases the later matching will fail.

The next step in the matching of invoking and invokable TPs is the creation of a side information table from the parameters in the symbolic destination name. Next, the invoking TP issues the Allocate call, and an allocation request flows to the partner LU specified in the side information table, stating the name of the invokable TP that has been requested (also listed in the side information table).

When an allocation request arrives, the SNA server compares the requested invokable TP name, as well as the LU alias, to the list of available invokable TPs (which may include associated LU aliases). The comparison can be modified by Registry variables, named in a later paragraph, but by default is carried out as follows:

Although the TP name requested in the symbolic destination name can be as long as 64 characters, any name received through a Registry or environment variable is 8 characters or less. Therefore, only the first 8 characters of TP names are used in comparisons.

The comparison is carried out first on both the TP name and the LU alias. An invokable TP for which there is a match on both TP name and LU alias will be chosen ahead of a TP for which no LU alias has been configured (through a Registry or environment variable). A TP for which no LU alias has been configured can be matched with any request that specifies that TP name, since there cannot be a mismatch based on LU alias.

The comparison of requested and available TP names is carried out in a specific order:

1.	The SNA server first checks for operator-started invokable TPs on the local system (the SNA server itself).

2.	If no match is found, the SNA server checks for autostarted invokable TPs on the local system (the SNA server itself).

3.	If no match is found, the SNA server checks for operator-started invokable TPs on other SNA servers or clients.

4.	If no match is found, the SNA server checks for autostarted invokable TPs on other SNA servers or clients.

This comparison can be modified somewhat by Registry entries for the SnaServr service. The entries are called DloadMatchTPOnly and DloadMatchLocalFirst, and are described in the Microsoft SNA Server Reference.

If a match is found, the SNA server signals the system containing the requested TP to connect to that SNA server. If no match is found, the SNA server rejects the incoming request.

For suggestions about specific ways to handle TP names and LU aliases, see "Possible Arrangements of TPs Within an SNA Network," later in this chapter.

Note

Because of the way CPIC works, an allocation request will not flow until local data buffers are full, or a confirm or flush call is made. This may mean that the allocation request does not flow until some time after the Allocate call is made. Therefore, any allocation failure caused by the rejection of the allocation request at the partner LU will be observed as the failure of a later call with one of the allocation failure return codes.


Configuring Invokable TPs
Writing CPI-C Applications	18 of 28

Configuring Invokable TPs

The following sections tell how to configure invokable TPs for the various SNA Server client types.


Clients Running Windows NT
Writing CPI-C Applications	19 of 28

Configuring Invokable TPs

Clients Running Windows NT

On clients running Windows NT, invokable TPs are configured through the Registry.

Note

With Windows NT, the recommended method for setting Registry variables for autostarted invokable TPs is to use the sample TP configuration program, TPSETUP (compile INSTALL.C, the source code for TPSETUP, for the Windows NT environment). When you write an installation program for autostarted invokable TPs, it is recommended that you add code similar to TPSETUP to the installation program. For information about TPSETUP, see Appendix B, "Sample CPIC TPs in the SDK."

For clients running Windows NT, it is recommended that autostarted invokable TPs be written as Windows NT services. As part of a setup program written to install your TPs, be sure to include code like that in TPSETUP.  Among other things, TPSETUP shows how to use the CreateService function when installing a TP. For important information about how services work under Windows NT, see the documentation for Windows NT and for Win32.

Table 2.3 lists the Registry entries used for the types of invokable TPs that can be run on Windows NT-based clients:

Table 2.3    Registry Entries for Invokable TPs on Windows NT-Based Clients

Type of TP		Location in Registry		Possible registry entries (some are otional)
Autostarted invokable TP running as a service on a Windows-NT based client		HKEY_LOCAL_MACHINE   SYSTEM     CurrentControlSet       Services         TPName         (and subkeys)		Registry entries created by the CreateService call, including entries that specify the path, display name, and other characteristics of the service. PLUS Linkage OtherDependencies:REG_MULTI_SZ:SnaBase Parameters SNAServiceType:REG_DWORD:0x5 LocalLU:REG_SZ:LUalias Parameters:REG_SZ:ParameterList Timeout:REG_DWORD:number AcceptNames:REG_SZ:TPNameList ConversationSecurity:REG_SZ:{ YES | NO } AlreadyVerified:REG_SZ:{ YES | NO } **Username1:REG_SZ:Password1** ... UsernameX:REG_SZ:PasswordX**
Autostarted invokable TP running as an application* on a Windows-NT based client		HKEY_LOCAL_MACHINE   SYSTEM     CurrentControlSet       Services         SnaBase           Parameters             TPs               TPName                 Parameters		SNAServiceType:REG_DWORD:{ 0x5 | 0x6 } PathName:REG_EXPAND_SZ:path LocalLU:REG_SZ:LUalias Parameters:REG_SZ:ParameterList TimeOut:REG_DWORD:number AcceptNames:REG_SZ:TPNameList ConversationSecurity:REG_SZ:{ YES | NO } AlreadyVerified:REG_SZ:{ YES | NO } **Username1:REG_SZ:Password1** ... UsernameX:REG_SZ:PasswordX**
Operator-started invokable TP running as a service on a Windows-NT based client		HKEY_LOCAL_MACHINE  SYSTEM     CurrentControlSet       Services         TPName           (and subkeys)		Registry entries created by the CreateService call, including entries that specify the path, display name, and other characteristics of the service. PLUS Linkage OtherDependencies:REG_MULTI_SZ:SnaBase Parameters SNAServiceType:REG_DWORD:0x1A LocalLU:REG_SZ:LUalias Timeout:REG_DWORD:number ConversationSecurity:REG_SZ:{ YES | NO } AlreadyVerified:REG_SZ:{ YES | NO } **Username1:REG_SZ:Password1** ... UsernameX:REG_SZ:PasswordX**
Operator-started invokable TP running as an application on a Windows-NT based client		HKEY_LOCAL_MACHINE  SYSTEM     CurrentControlSet       Services         SnaBase           Parameters             TPs               TPName                 Parameters		SNAServiceType:REG_DWORD:0x1A LocalLU:REG_SZ:LUalias TimeOut:REG_DWORD:number ConversationSecurity:REG_SZ:{ YES | NO } AlreadyVerified:REG_SZ:{ YES | NO } **Username1:REG_SZ:Password1** ... UsernameX:REG_SZ:PasswordX**
* Before an autostarted TP can be started as an application on a Windows NT-based client , the TPSTART program must be started. For more information, see Appendix B, "Sample CPI-C TPs in the SDK." ** AlreadyVerified and username/password entries are used only if ConversationSecurity is set to YES.
For important information about TPSETUP, see the note in the previous section.

Registry Entries for Clients Running Windows NT

The following list gives details about the Registry entries shown in Table 2.3.

Note

The following list shows possible Registry entries; use only the entries that apply to your TP, as shown in Table 2.3.

OtherDependencies:REG_MULTI_SZ:SnaBase

For a TP running as a service, ensures that the SnaBase service will be started before the TP is started. This entry belongs under the Linkage subkey.

SNAServiceType:REG_DWORD:{ 0x5 | 0x6 | 0x1A }

Indicates the type of TP. Use a value of 0x5 for an autostarted queued TP, 0x6 for an autostarted nonqueued TP, and 0x1A for an operator-started TP.

See Table 2.3 for the correct location for this entry.

Note that the value for an autostarted TP running as a service must be 0x5, because these TPs are always queued, as described in "Invokable TPs," earlier in this chapter.

PathName:REG_EXPAND_SZ:path

For an autostarted TP running as an application, specifies the path and filename of the TP. The data type of REG_EXPAND_SZ means that the path can contain an expandable data string; for example, %SystemRoot% represents the directory containing the Windows NT system files. (Note that for a TP running as a service, an equivalent entry is inserted by the CreateService call; no additional path entry is needed.)

LocalLU:REG_SZ:LUalias

Specifies the alias of the local LU to be used when this TP is started on this computer. See Table 2.3 for the correct location for this entry.

Parameters:REG_SZ:ParameterList

Lists parameters to be used by the TP. Separate parameters with spaces. See Table 2.3 for the correct location for this entry.

Note

When using SNA Server version 2.0 with Win32, be sure to get patch 26. This patch causes the parameter arguments in the Parameters Registry entry to be passed to the invokable TP in the order expected when parsing the command line (that is, as an array of ASCII strings). Patch 26 is available on the MSSNA CompuServe [image] forum Library #2 as SNA20.P26.

Timeout:REG_DWORD:number

Specifies the time, in milliseconds, that an Accept_Conversation will wait before timing out. Specify number in decimal; the Registry editor converts this to hexadecimal before displaying. See Table 2.3 for the correct location for this entry. The default is infinity (no limit).

AcceptNames:REG_SZ:TPNameList

With Windows NT, used for autostarted TPs only; lists additional names under which the invokable TP can be invoked. Separate TP names with spaces. The default is none. If an invokable TP does not issue a Specify_Local_TP_Name for each name configured under AcceptNames in the Registry, that TP will fail.

ConversationSecurity:REG_SZ:{ YES | NO }

Indicates whether this TP supports conversation security. See Table 2.3 for the correct location for this entry. The default is NO.

AlreadyVerified:REG_SZ:{ YES | NO }

Indicates whether this TP can be invoked with a user ID and password that have already been verified. AlreadyVerified is ignored if ConversationSecurity is set to NO.

For a diagram of three TPs in a conversation, where the third TP could have been invoked with a password that is already verified by the second TP, see Figure 2.2, earlier in this chapter. The following table shows the requirements for using password verification in a chain of TPs:

First TP (an invoking TP)		Second TP (invokable TP that confirms password and then invokes another TP)		Third and subsequent TPs (invokable TPs that invoke other TPs)
—		ConversationSecurity setting must be YES		ConversationSecurity setting must be YES
—		AlreadyVerified setting can be YES or NO		AlreadyVerified setting must be YES
Symbolic destination name or Set_Conversation _Security_Type in this TP specifies Program for the security type; as a result, the TP passes along the user ID and password supplied in the symbolic destination name (or through calls*)		Symbolic destination name or  Set_Conversation_Security _Type in this TP specifies Same for the security type; as a result, after confirming the user ID and password, the TP passes along the user ID and an already- verified flag		Symbolic destination name or Set_Conversation_Security _Type in this TP specifies Same  for the security type; as a result, the TP passes along the user ID as received, along with the already-verified flag
* Set_Conversation_Security_User_ID or Set_Conversation_Security_Password will overwrite the user ID and password specified in the symbolic destination name.
If you set AlreadyVerified to NO, this TP cannot join in a chain of conversations where password verification is already done. (The exception to this is when ConversationSecurity is set to NO, in which case the TP could be the final TP in such a chain, since it will perform no checking.)

If you are configuring a TP that may sometimes need to confirm a password and sometimes accept an already-verified flag, set AlreadyVerified to YES and configure the UsernameX variable appropriately. In this case, whenever the TP is invoked without the already-verified flag being set, AlreadyVerified is ignored; verification is attempted with the user ID and password configured for the TP.

If you set AlreadyVerified to YES, make sure that ConversationSecurity is also set to YES.

See Table 2.3 for the correct location for AlreadyVerified. The default is NO.

Username1:REG_SZ:Password1...UsernameX:REG_SZ:PasswordX

Sets one or more usernames and passwords to be compared with those sent by the invoking TP. The username and password can each be as many as 10 characters. Both parameters are case sensitive.

See Table 2.3 for the correct location for this entry. This variable is ignored if conversation security is not activated or if the password has already been verified, as described for the AlreadyVerified entry.

Example of Registry Entries for an Invokable TP

For an autostarted invokable TP called BounceTP and running as a service, the following Registry entries might be added to a Windows NT-based client. The entries would be added to HKEY_LOCAL_MACHINE\SYSTEM\    CurrentControlSet\Services, under the subkeys shown in bold.

Note

In the following list, the parameters listed directly under the BounceTP key (such as DisplayName and ErrorControl) are service parameters created when TPSETUP (or similar code) is run to install the TP. TPSETUP or similar code should be used to create these variables (they should not be set manually). For more information about TPSETUP, see Appendix B, "Sample CPIC TPs in the SDK."

BounceTP

DisplayName:REG_SZ:BounceTP

ErrorControl:REG_DWORD:0x1

ImagePath:REG_EXPAND_SZ:c:\sna\system\bouncetp.exe

ObjectName:REG_SZ:LocalSystem

Start:REG_DWORD:0x3

Type:REG_DWORD:0x10

Linkage

OtherDependencies:REG_MULTI_SZ:SnaBase

Parameters

SNAServiceType:REG_DWORD:0x5

LocalLU:REG_SZ:JohnDoe

Parameters:REG_SZ:Arg1 Arg2 Arg3

Timeout:REG_DWORD:0x100

ConversationSecurity:REG_SZ:yes

AlreadyVerified:REG_SZ:no

JohnDoe:REG_SZ:SecretPassword


Clients Running Windows Version 3.x
Writing CPI-C Applications	20 of 28

Configuring Invokable TPs

Clients Running Windows Version 3.x

On clients running Windows version 3.x, invokable TPs are configured through entries in the WIN.INI file.

Note

With Windows version 3.x, the recommended method for setting environment variables for autostarted invokable TPs is to use the sample TP configuration program, TPSETUP (compile INSTALL.C, the source code for TPSETUP, for the  Windows version 3.x environment). When you write an installation program for autostarted invokable TPs, it is recommended that you add code similar to TPSETUP to the installation program. For information about TPSETUP, see Appendix B, "Sample CPIC TPs in the SDK."

Table 2.4 lists the section headings and environment variables used (in the WIN.IN file) for invokable TPs on clients running Windows version 3.x:

Table 2.4    Environment Variables for Invokable TPs on Windows-Based Clients

Type of TP		Section in WIN.INI listing TP names only		Section and possible environment variables defining TP (some variables are optional)
Autostarted invokable TP on  a client running Windows version 3.x		[SNAServerAutoTPs] TPName1=SectionName1 ... TPNameX=SectionNameX		[SectionName1] PathName=path LocalLU=LUalias Parameters=ParameterList TimeOut=number Queued={ yes | no } AcceptNames=TPNameList ConversationSecurity={ yes | no } AlreadyVerified={ yes | no }* Username1=Password1* ... UsernameX=PasswordX*
Operator-started invokable TP on  a client running Windows version  3.x		[SNAServerAutoTPs] TPNameN=SectionNameN ... TPNameX=SectionNameX		[SectionNameN] LocalLU=LUalias TimeOut=number Queued=operator AcceptNames=TPNameList ConversationSecurity={ yes | no } AlreadyVerified={ yes | no } *Username1=Password1* ... UsernameX=PasswordX*
*AlreadyVerified and username/password lines are used only if ConversationSecurity is set to yes.
Environment Variables for Clients Running Windows Version 3.x

The following list shows the correct form for the sections and entries to add to the WIN.INI file for autostarted invokable TPs on a client running Windows version 3.x. The section headings are shown enclosed in square brackets; include the brackets when adding the section to the WIN.INI file.

Note

The following list shows possible environment variables; use only the variables that apply to your TP, as shown in Table 2.4.

[SNAServerAutoTPs]

TPNameX=SectionNameX

For all TPs (despite the inclusion of “Auto” in the section name). Associates TPnameX with SectionNameX. Additional lines may follow TPNameX=SectionNameX, each one using the same syntax to name a different TP and the section containing the information for that TP.

[SectionName]

Forms a section heading for entries applying to one TP; SectionName must match a section name listed under [SNAServerAutoTPs].

PathName=path

Specifies the full path and filename of the executable. The default is TPNAME.EXE.

LocalLU=LUalias

Specifies the alias of the local LU to be used when this TP is started on this computer.

Parameters=ParameterList

Lists strings to be passed as command line parameters for the TP. Separate parameters with spaces. The default is no parameters.

Timeout=number

Specifies the time, in milliseconds, that an Accept_Conversation will wait before timing out. The default is infinity (no limit).

Queued={ yes | no }Queued=operator

Specifies the type of TP: yes for an autostarted queued TP, no for an autostarted nonqueued TP, or operator for an operator-started TP (which must always be queued). The default is yes.

AcceptNames=TPNameList

Lists additional names under which the invokable TP can be invoked. Separate TP names with spaces. The default is none. If an invokable TP does not issue a Specify_Local_TP_Name for each name configured under AcceptNames in the Registry, that TP will fail.

ConversationSecurity={ yes | no }

Indicates whether this TP supports conversation security. The default is no.

AlreadyVerified={ yes | no }

Indicates whether this TP can be invoked with a user ID and password that have already been verified. AlreadyVerified is ignored if ConversationSecurity is set to no.

For detailed information about the AlreadyVerified variable, see the description for it under "Registry Entries for Clients Running Windows NT," earlier in this chapter.

The default is no.

Username1=Password1*...UsernameX=PasswordX*

Sets one or more usernames and passwords to be compared with those sent by the invoking TP. The username and password can each be as many as 10 characters. Both parameters are case sensitive. This variable is ignored if conversation security is not activated or if the password has already been verified, as described for the AlreadyVerified entry.

Translating SNA Service TP Names to ASCII for WIN.INI or SNA.INI

For SNA service TPs on SNA Server clients running Windows version 3.x or OS/2, the line naming the TP in the WIN.INI or SNA.INI file (respectively) must specify the TP name in ASCII. The following paragraphs tell how to convert a TP name to this form. The line should be placed in the [SNAServerAutoTPs] section of the file, as shown in Table 2.4 (earlier in this chapter) or Table 2.5 (later in this chapter).

An SNA service TP name is normally up to 4 bytes in length; the first byte is a hexadecimal number in the range 0x00 to 0x3F, and the remaining bytes are EBCDIC characters. The first byte defines the function class of the TP. Therefore, to convert a service TP name to an ASCII form, convert the first byte as shown in the following table, and convert the EBCDIC values to ASCII letter equivalents.

First byte of TP name (hexadecimal number)	ASCII character equivalent for WIN.INI
0x07	DDM
0x20	DIA
0x21	SNAD
0x24	FS
0x30	PO
All others	UN
For example, a service TP name of 0x21 0xD7 0xD7 is equivalent to SNADPP (0x21 converts to SNAD and each 0xD7 converts to “P”).

Example of WIN.INI Lines for an Invokable TP

For autostarted invokable TPs called BounceTP and TestTP, on a client running Windows version 3.x, the following WIN.INI lines might be added:

[SNAServerAutoTPs]

BounceTP=bnceprms

TestTP=testprms

[bnceprms]

PathName=c:\sna\wbounce.exe

LocalLU=Eric

Parameters=/t

timeout=60000

queued=yes

[testprms]

PathName=c:\sna\testtp.exe

LocalLU=LU1

Parameters=/v

timeout=60000

queued=no


Clients Running OS/2
Writing CPI-C Applications	21 of 28

Configuring Invokable TPs

Clients Running OS/2

On OS/2-based clients, invokable TPs are configured through entries in the SNA.INI file. Table 2.5 lists the section headings and environment variables used:

Table 2.5    Environment Variables for Invokable TPs on OS/2-Based Clients

Type of TP		Section in SNA.INI listing TP names only		Section and possible environment variables defining TP (some variables are optional)
Autostarted invokable TP  on a client  running OS/2		[SNAServerAutoTPs] TPName1=SectionName1 ... TPNameX=SectionNameX		[SectionName1] PathName=path LocalLU=LUalias Parameters=ParameterList TimeOut=number Queued={ yes | no } AcceptNames=TPNameList ConversationSecurity={ yes | no } AlreadyVerified={ yes | no } *Username1=Password1* ... UsernameX=PasswordX* Environment=VariableList NewScreenGroup={ 1 | 0 } IconFile=path SessionType=number PgmControl=number InitXPos=number InitYPos=number InitXSize=number InitYSize=number
Operator-started invokable TP on a client running OS/2		[SNAServerAutoTPs] TPNameN=SectionNameN ... TPNameX=SectionNameX		[SectionNameN] LocalLU=LUalias TimeOut=number Queued=operator AcceptNames=TPNameList ConversationSecurity={ yes | no } AlreadyVerified={ yes | no } *Username1=Password1* ... UsernameX=PasswordX*
*AlreadyVerified and username/password lines are used only if ConversationSecurity is set to yes.
Environment Variables for OS/2-Based Clients

The following list shows the correct form for the sections and entries to add to the SNA.INI file (located in the root SNA Server directory) for autostarted invokable TPs on an OS/2-based client. The section headings are shown enclosed in square brackets; include the brackets when adding the section to the SNA.INI file.

Note

The following list shows possible environment variables; use only the variables that apply to your TP, as shown in Table 2.5.

[SNAServerAutoTPs]

TPNameX=SectionNameX

For all TPs (despite the inclusion of “Auto” in the section name). Associates TPnameX with SectionNameX. Additional lines may follow TPNameX=SectionNameX, each one using the same syntax to name a different TP and the section containing the information for that TP.

[SectionName]

Forms a section heading for entries applying to one TP; SectionName must match a section name listed under [SNAServerAutoTPs].

PathName=path

Specifies the full path and filename of the executable. The default is TPNAME.EXE.

LocalLU=LUalias

Specifies the alias of the local LU to be used when this TP is started on this computer.

Parameters=ParameterList

Lists strings to be passed as command line parameters for the TP. Separate parameters with spaces. The default is no parameters.

Timeout=number

Specifies the time, in milliseconds, that an Accept_Conversation will wait before timing out. The default is infinity (no limit).

Queued={ yes | no }Queued=operator

Specifies the type of TP: yes for an autostarted queued TP, no for an autostarted nonqueued TP, or operator for an operator-started TP (which must always be queued). The default is yes.

AcceptNames=TPNameList

Lists additional names under which the invokable TP can be invoked. Separate TP names with spaces. The default is none. If an invokable TP does not issue a Specify_Local_TP_Name for each name configured under AcceptNames in the Registry, that TP will fail.

ConversationSecurity={ yes | no }

Indicates whether this TP supports conversation security. The default is no.

AlreadyVerified={ yes | no }

Indicates whether this TP can be invoked with a user ID and password that have already been verified. AlreadyVerified is ignored if ConversationSecurity is set to no.

For detailed information about the AlreadyVerified variable, see the description for it under "Registry Entries for Clients Running Windows NT," earlier in this chapter.

The default is no.

Username1=Password1*...UsernameX=PasswordX*

Sets one or more usernames and passwords to be compared with those sent by the invoking TP. The username and password can each be as many as 10 characters. Both parameters are case sensitive. This variable is ignored if conversation security is not activated or if the password has already been verified, as described for the AlreadyVerified entry.

Environment=VariableList

For an autostarted TP, lists the variables to be set in the TP’s environment. Separate multiple variables with spaces.

NewScreenGroup={ 1 | 0 }

For an autostarted TP, specifies 1 to indicate that the TP runs in the foreground, or 0 to indicate that the TP runs in the background. The default is 1 (foreground).

IconFile=path

For an autostarted TP, specifies the full path and filename of the icon file. The default is no icon file.

SessionType=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 0.

PgmControl=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 32768.

InitXPos=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 80.

InitYPos=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 80.

InitXSize=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 470.

InitYSize=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 330.

Note

SessionType, PgmControl, InitXPos, InitYPos, InitXSize, and InitYSize are filled directly into the STARTDATA structure passed to the OS/2 DosStartSession call for the new session.

Translating SNA Service TP Names to ASCII

For SNA service TPs on SNA Server clients running OS/2, the line naming the TP in the SNA.INI file must specify the TP name in ASCII. For information about how to convert an SNA service TP name to an ASCII form, see "Translating SNA Service TP Names to ASCII for WIN.INI or SNA.INI," earlier in this chapter.


Clients Running MS-DOS
Writing CPI-C Applications	22 of 28

Configuring Invokable TPs

Clients Running MS-DOS

SNA Server does not support invokable TPs on MS-DOS – based clients.


Configuring an SNA Server to Support TPs
Writing CPI-C Applications	23 of 28

Configuring an SNA Server to Support TPs

The following sections describe how the SNA Server configuration works with invoking and invokable TPs.


Invoking TPs and the SNA Server Configuration
Writing CPI-C Applications	24 of 28

Configuring an SNA Server to Support TPs

Invoking TPs and the SNA Server Configuration

In order for an SNA server to support the beginning of the invoking process, the following parameters must be configured correctly:

If the invoking TP specifies the LU alias that it uses (in a Registry or environment variable), that LU alias must match a local APPC LU alias on the supporting SNA server. If the invoking TP does not specify a local LU alias, one of two methods for designating a default LU must be carried out on the supporting SNA server. One method is to assign a default local APPC LU to the user or group that starts the invoking TP (that is, the user or group logged on at the system from which Initialize_Conversation is issued). The other method is to designate one or more LUs as members of the default outgoing local APPC LU pool. SNA Server first attempts to determine the default local APPC LU of the user who started the TP, then attempts to assign an available LU from the default outgoing local APPC LU pool; if these attempts fail, SNA Server rejects the request.

In most situations, the supporting SNA server must contain an appropriate connection to another system (host or peer). Sometimes, for testing purposes, the SNA server contains two local LUs paired together (for invoking and invokable TPs that are in the same domain); in this situation, a connection to a host or peer is not necessary.

The partner LU alias specified in the symbolic destination name must match an LU alias that is paired with the local LU alias used by the invoking TP.

The preceding parameters support the beginning of the invoking process. In order for the invoking process to successfully complete, additional parameters must be configured as described in the next section.


Invokable TPs and the SNA Server Configuration
Writing CPI-C Applications	25 of 28

Configuring an SNA Server to Support TPs

Invokable TPs and the SNA Server Configuration

In order for an SNA server to receive allocation requests from an invoking TP on another system, and then route those requests to an invokable TP, certain parameters must be configured correctly:

The SNA server must have a connection to the system from which the invoking TP’s request is sent.

The SNA server must have a remote LU capable of receiving the incoming request. This remote LU can be configured either explicitly or implicitly.

When configured explicitly, there is an explicit match between a remote LU alias on the SNA server and the alias of the LU that conveys the invoking TP’s request.

When configured implicitly, an implicit incoming remote LU (with its implicit incoming mode) is used. This means that several items must work together. First, the LU alias specified in the incoming request (the LU alias requested for the invokable TP) must match a local LU alias on the SNA server receiving the request. Second, the local LU on the SNA server must have an implicit incoming remote LU assigned to it. The properties of the implicit incoming remote LU will be used for that LU-LU session. For more details about how an implicit incoming remote LU works, see the Microsoft SNA Server Administration Guide.

Appropriate local LUs must be defined in the SNA Server configuration. For descriptions of several ways to set up these local LUs, see the next section.


Possible Arrangements of TPs Within an SNA Network
Writing CPI-C Applications	26 of 28

Configuring an SNA Server to Support TPs

Possible Arrangements of TPs Within an SNA Network

If your SNA Server installation contains multiple systems (clients and/or SNA servers), you can place a given invokable TP on more than one system. When an invoking request is received in such an installation, there will (potentially) be a choice of systems on which to run the invokable TP. You can maintain specific control over this choice; alternatively, by following the instructions in "TP Name Not Unique; Local LU Alias Unspecified" (later in this chapter), you can allow the choice to be made randomly by SNA Server (to distribute the load).

You can maintain specific control over this choice of system by setting up invokable TPs with unique names, or by setting up each invokable TP to run only with a specific, unique LU alias. With this arrangement, the information provided for the invoking TP (in the symbolic destination name) will specify the particular system on which the invokable TP should run.

You can avoid controlling this choice of system, and allow the choice to be made randomly by SNA Server, by setting the DloadMatchLocalFirst Registry entry to NO, as described in the Microsoft SNA Server Reference, and using invokable TPs that leave the local LU alias unspecified. Then, when an incoming request is received, it is routed randomly, rather than preferentially to the local SNA server; in addition, no matter what LU alias is requested for the invokable TP, there cannot be a mismatch. SNA Server will start one instance of the requested TP, choosing randomly among the available systems.

The following sections describe some of the possible arrangements that can be made for the running of TPs.

TP Name Unique for Each TP

If you want to specify the intended system where the invokable TP will run, one way to do it is to use a unique TP name for each invokable TP. In this arrangement, the invoking TP identifies the intended invokable TP (and system) simply by naming the TP. This makes it unnecessary for an invokable TP to specify any LU alias in Registry or environment variables.

TP Name Not Unique; Local LU Alias Unique

If you want to specify the intended system where the invokable TP will run, another way to do it (besides using unique TP names) is to give the same name to multiple invokable TPs, but associate each TP with a unique local LU alias. To do this, configure each invokable TP (through Registry or environment variables) to use a unique local LU alias. Then set up the invoking TPs so that each one is routed not only to the correct TP name but also to the correct partner LU alias for the intended invokable TP.

TP Name Not Unique; Local LU Alias Unspecified

If it does not matter which system an invokable TP runs on, use the same name for multiple invokable TPs, and in addition, do not specify an LU alias in the Registry or environment variables for the TPs. In such a situation, in the list of available invokable TP names on an SNA server, there are no associated LU aliases. Thus, a request received from an invoking TP is matched only on the TP name, without regard to the LU alias.

In such a situation, if you set the DloadMatchLocalFirst Registry entry to NO, as described in the Microsoft SNA Server Reference, SNA Server randomly routes the request to one of the available TPs. This spreads the processing load out among multiple systems, and provides hot backup (the ability to take systems on- and offline without disrupting service).


Troubleshooting for Invokable TPs
Writing CPI-C Applications	27 of 28

Configuring an SNA Server to Support TPs

Troubleshooting for Invokable TPs

If there are difficulties with starting an invokable TP, but SNA Server seems to be running smoothly otherwise, there may be a mismatch between the information for the invokable TP, the invoking TP, and/or LUs in the SNA Server configuration. That is, there may be a mismatch between the symbolic destination parameters, the Registry or environment variables, and LU aliases specified in SNA Server Admin. For details about how to specify LU aliases in SNA Server Admin, see the Microsoft SNA Server Administration Guide.


SNA Server Features That Simplify CPIC Configuration
Writing CPI-C Applications	28 of 28

Configuring an SNA Server to Support TPs

SNA Server Features That Simplify CPIC Configuration

There are several features in SNA Server that can simplify configuration for APPC and CPIC:

The implicit incoming remote LU and the implicit incoming mode, which allow SNA Server to accept requests that arrive by unrecognized remote LUs and modes.

The default local APPC LU and the default remote APPC LU, which allow LU aliases to be associated with user or group names, simplifying the routing of incoming requests and the configuration of client systems.

The default outgoing local APPC LU pool, which allows LUs to be allocated dynamically to any invoking TP that does not specify a local LU.

Automatic partnering, which automatically creates LU-LU pairs and assigns modes to the pairs.

For more information about these features, see the Microsoft SNA Server Administration Guide.


CPI-C Calls
Chapter 3	1 of 50

CPI-C Calls

This chapter describes the CPI-C calls. The following information is supplied for each CPI-C call:

The pseudonym for the call and in parentheses the actual C function name. This information is contained in the section heading.

A definition of the call.

A list of the parameters used by the call and the data type for each parameter. The prototype of each function is declared in the WINCPIC.H file.

A description of each input and output parameter. The parameter names are pseudonyms. The actual names for these parameters are declared by the application program. The description includes the possible values of the parameter.

The conversation state(s) in which the call can be issued.

The state(s) to which the conversation can change upon return from the call. Conditions that do not cause a state change are not noted. For example, parameter checks and state checks do not cause a state change.

Additional information describing the use of the call.


Data Types
CPI-C Calls	2 of 50

Data Types

The data types for the parameters supplied to and received from CPI-C are established as symbolic constants by #define statements in the WINCPIC.H file. For example CM_INT32 represents signed long int and CM_PTR represents far *. Using symbolic constants improves the portability of CPI-C applications.

For ease of understanding, this manual presents the data types in absolute (un#defined) terms.

In writing applications, you should use the symbolic constants from the WINCPIC.H file.


Symbolic Constants
CPI-C Calls	3 of 50

Symbolic Constants

Most parameters supplied to and returned by CPI-C are 32bit integers. To simplify coding, the values for these parameters are represented by meaningful symbolic constants, which are established by #define statements in the WINCPIC.H header file. For example, the value CM_MAPPED_CONVERSATION represents the integer 1. For the sake of readability, use only the symbolic constants when writing programs.


Strings
CPI-C Calls	4 of 50

Strings

All strings are in ASCII format when passed across the CPI-C interface.


Validity of Output Parameters
CPI-C Calls	5 of 50

Validity of Output Parameters

The parameters returned by CPI-C are valid only if the CPI-C call is executed successfully, as indicated by a return code of CM_OK.


Accept_Conversation (cmaccp)
CPI-C Calls	6 of 50

Accept_Conversation (cmaccp)

Issued by the invoked program to accept the incoming conversation and set certain conversation characteristics. For a list of initial conversation characteristics, see Chapter 1, "Introduction to CPI-C."

Syntax

conversation_ID	unsigned char far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Returned parameter; specifies the identifier for the conversation. It is used by subsequent CPI-C calls and is returned if the return code is either CM_OK or CM_OPERATION_INCOMPETE. If return code is CM_OPERATION_COMPLETE, the conversation_id can be used by the application to wait for or cancel the conversation.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_STATE_CHECK

Primary return code; there is no incoming conversation (blocking mode only), or no local TP name has been set up.

CM_OPERATION_INCOMPLETE

Primary return code; a nonblocking operation has been started on the conversation but is not complete. The program can issue Wait_For_Conversation to wait for the operation to complete or Cancel_Conversation to cancel the operation (and conversation).

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in RESET state when Accept_Conversation is issued.

If the call is successful, the conversation changes to RECEIVE state. If the call fails, the state remains unchanged.

Remarks

Upon successful execution of this call, CPI-C generates an 8-byte conversation identifier. This identifier is a required parameter for all other CPI-C calls issued by the invoked program on this conversation.

Incoming conversations will be accepted according to the target TP name that they specify, which must match local TP names that have been set up. Local TP names may be set up by implementation-dependent methods, or by the program calling Specify_Local_TP_Name. In this way, a program may have more than one local TP name. The program may call Extract_TP_Name to discover the name specified on the incoming conversation.

The operation is performed in nonblocking mode if the program has called Specify_Local_TP_Name previously; otherwise it is performed in blocking mode.


Allocate (cmallc)
CPI-C Calls	7 of 50

Allocate (cmallc)

Issued by the invoking program to allocate a conversation with the partner program, using the current conversation characteristics. CPI-C may also allocate a session between the local LU and partner LU if one does not already exist.

Syntax

conversation_ID	unsigned char far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the conversation identifier. The value of this parameter was returned by Initialize_Conversation.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_OPERATION_NOT_ACCEPTED

Primary return code; this value indicates that a previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

Primary return code; a nonblocking operation has been started on the conversation but is not complete. The program can issue Wait_For_Conversation to wait for the operation to complete or Cancel_Conversation to cancel the operation (and conversation).

CM_PARAMETER_ERROR

Primary return code; one of the following occurred:

The mode name derived from the side information or set by Set_Mode_Name is not valid.

The mode name is used by SNA service TPs; the invoking program does not have the authority to use this mode name. An example would be SNASVCMG.

The partner program derived from the side information is an SNA service TP; the local program does not have the privilege required to allocate a conversation to an SNA service TP.

The partner program is a service TP, which participates in Basic conversations, but the conversation is set to CM_MAPPED_CONVERSATION.

The partner LU name derived from the side information or set by Set_Partner_LU_Name is not valid.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is not valid, or the address of a variable is invalid.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation is not in INITIALIZE state.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

CM_UNSUCCESSFUL

Primary return code; the conversation’s return-control characteristic is set to CM_IMMEDIATE and the local LU did not have an available contention-winner session.

The following return codes can be generated if the conversation’s return-control type is set to CM_WHEN_SESSION_ALLOCATED.

CM_ALLOCATE_FAILURE_NO_RETRY

Primary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

CM_ALLOCATE_FAILURE_RETRY

Primary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

State Changes

The conversation must be in INITIALIZE state when Allocate is issued.

State changes, summarized in the following table, are based on the value of the return_code parameter.

return_code	New state
CM_OK	SEND
CM_ALLOCATE_FAILURE_NO_RETRY	RESET
CM_ALLOCATE_FAILURE_RETRY	RESET
All others	No change
Remarks

The type of conversation allocated is based on the conversation type characteristic, Mapped or Basic.

Once the conversation has been allocated by this call, the following conversation characteristics cannot be changed:

Conversation type

Mode name

Partner LU name

Partner program name

Return control

Synchronization level

Conversation security

User ID

Password

To send the allocation request immediately, the invoking program can issue Flush or Confirm immediately after Allocate. Otherwise, the allocate request accumulates with other data in the local LU’s send buffer until the buffer is full.

By issuing Confirm after Allocate, the invoking program can immediately determine whether the allocation was successful (if the conversation synchronization level is set to CM_CONFIRM).

If the partner LU rejects the allocation request generated by Allocate, the error is returned to the invoking program on a subsequent call.


Cancel_Conversation (cmcanc)
CPI-C Calls	8 of 50

Cancel_Conversation (cmcanc)

Cancels any outstanding operation on a conversation (an operation returned with CM_OPERATION_INCOMPLETE), and the conversation.

Syntax

conversation_ID	unsigned char far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Returned parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in any state except RESET.

When the return code is CM_OK, the conversation state becomes RESET.

Remarks

Cancel_Conversation can be called while another operation is active for the specified conversation_ID. This allows an application to abort any CPI-C action; but will terminate the conversation. This call can be issued regardless of the current application processing mode. Any outstanding operations will return with CM_DEALLOCATED_ABEND as the return code.

The conversation is terminated by a Deallocate with deallocate_type set to ABEND_SVC. No log_data is sent. The system may be unable to do this immediately, but any delay is transparent to the program.

Note

If Cancel_Conversation is called while there are outstanding Specify_Windows_Handle asynchronous calls, these calls are canceled. The return codes are set to canceled and a completion message is posted.


Confirm (cmcfm)
CPI-C Calls	9 of 50

Confirm (cmcfm)

Sends the contents of the local LU’s send buffer and a confirmation request to the partner program and waits for confirmation. To avoid blocking for clients running Windows version 3.x, use the Specify_Windows_Handle call. For Windows NT, run a background thread for all CPIC communications and preserve the foreground thread for UI only.

Syntax

conversation_ID		unsigned char far *
request_to_send_received		signed long int far *
return_code		signed long int far *
Parameter		Description
conversation_ID		Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
request_to_send_received		Returned parameter; provides the request-to-send-received indicator. The following are possible values: CM_REQ_TO_SEND_RECEIVED indicates that the partner program has issued Request_To_Send, which requests the local program to change the conversation to RECEIVE state. CM_REQ_TO_SEND_NOT_RECEIVED indicates that the partner program has not issued Request_To_Send. This value is not relevant if return_code is set to CM_PROGRAM_PARAMETER_CHECK or CM_PROGRAM_STATE_CHECK.
Return Codes

CM_OK

Primary return code; the call executed successfully. The partner program has issued the Confirmed call.

CM_OPERATION_NOT_ACCEPTED

Primary return code; a previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

Primary return code; the operation has not completed (processing mode is non-blocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation (and conversation). If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID is invalid.

The local program attempted to use Confirm in a conversation with a synchronization level of CM_NONE. The synchronization level must be CM_CONFIRM.

CM_PROGRAM_STATE_CHECK

Primary return code; one of the following occurred:

The conversation was not in SEND or SEND-PENDING state.

The Basic conversation for the local program was in SEND state, and the local program did not finish sending a logical record.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

CM_CONVERSATION_TYPE_MISMATCH

Primary return code; the partner LU or program does not support the conversation type (Basic or Mapped) specified in the allocation request.

CM_PIP_NOT_SPECIFIED_CORRECTLY

Primary return code; the allocation request was rejected by a non – CPI-C LU 6.2 TP. The partner program requires one or more PIP data variables, which are not supported by CPI-C.

CM_SECURITY_NOT_VALID

Primary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

CM_SYNC LEVEL_NOT_SUPPORTED_PGM

Primary return code; the partner program does not support the synchronization level specified in the allocation request.

CM_TPN_NOT_RECOGNIZED

Primary return code; the partner LU does not recognize the program name specified in the allocation request.

CM_TP_NOT_AVAILABLE_NO_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a permanent condition. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

CM_TP_NOT_AVAILABLE_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a temporary condition. The reason for the error may be logged on the remote node. Retry the allocation.

CM_PROGRAM_ERROR_PURGING

Primary return code; one of the following occurred:

While in RECEIVE or CONFIRM state, the partner program issued Send_Error. Data sent but not yet received is purged.

While in SEND_PENDING state with the error direction set to CM_RECEIVE_ERROR, the partner program issued Send_Error. Data was not purged.

CM_RESOURCE_FAILURE_NO_RETRY

Primary return code; one of the following occurred:

The conversation was terminated prematurely because of a permanent condition. Do not retry until the error has been corrected.

The partner program did not deallocate the conversation before terminating normally.

CM_RESOURCE_FAILURE_RETRY

Primary return code; the conversation was terminated prematurely because of a temporary condition, such as modem failure. Retry the conversation.

CM_DEALLOCATED_ABEND

Primary return code; the conversation has been deallocated for one of the following reasons:

The remote program issued Deallocate with the type parameter set to CM_DEALLOCATE_ABEND. If the conversation for the remote program was in RECEIVE state when the call was issued, information sent by the local program and not yet received by the remote program is purged.

The partner program terminated normally but did not deallocate the conversation before terminating.

CM_DEALLOCATED_ABEND_SVC

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner program issued Deallocate with the type parameter set to ABEND_SVC.

The partner program did not deallocate the conversation before terminating.

If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_DEALLOCATED_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner program issued Deallocate with the type parameter set to ABEND_TIMER. If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_SVC_ERROR_PURGING

Primary return code; while in SEND state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC. Data sent to the partner program may have been purged.

State Changes

The conversation can be in SEND or SEND-PENDING state when Confirm is issued.

State changes, summarized in the following table, are based on the value of return_code.

return_code	New state
CM_OK
Call was issued in SEND state	No change
Call was issued in SEND-PENDING state	SEND
CM_PROGRAM_ERROR_PURGING	RECEIVE
CM_SVC_ERROR_PURGING	RECEIVE
CM_CONVERSATION_TYPE_MISMATCH	RESET
CM_PIP_NOT_SPECIFIED_CORRECTLY	RESET
CM_SECURITY_NOT_VALID	RESET
CM_SYNC_LEVEL_NOT_SUPPORTED_PGM	RESET
CM_TPN_NOT_RECOGNIZED	RESET
CM_TP_NOT_AVAILABLE_NO_RETRY	RESET
CM_TP_NOT_AVAILABLE_RETRY	RESET
CM_RESOURCE_FAILURE_NO_RETRY	RESET
CM_RESOURCE_FAILURE_RETRY	RESET
CM_DEALLOCATED_ABEND	RESET
CM_DEALLOCATED_ABEND_SVC	RESET
CM_DEALLOCATED_ABEND_TIMER	RESET
All others	No change
Remarks

In response to Confirm, the partner program normally issues Confirmed to confirm that it has received the data without error. (If the partner program encounters an error, it issues Send_Error or uses Deallocate to abnormally deallocate the conversation.)

The program can issue Confirm only if the conversation’s synchronization level is CM_CONFIRM.

Confirm waits for a response from the partner program. A response is generated by one of the following CPI-C calls in the partner program:

Confirmed

Send_Error

Deallocate with the conversation’s deallocate type set to CM_DEALLOCATE_ABEND


Confirmed (cmcfmd)
CPI-C Calls	10 of 50

Confirmed (cmcfmd)

Replies to a confirmation request from the partner program. It informs the partner program that the local program has not detected an error in the received data. Because the program issuing the confirmation request waits for a confirmation, Confirmed synchronizes the processing of the two programs.

Syntax

conversation_ID	unsigned char far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_OPERATION_NOT_ACCEPTED

Primary return code; a previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

Primary return code; the operation has not completed (processing mode is non-blocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation (and conversation). If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation was not in CONFIRM, CONFIRM-SEND, or CONFIRM-DEALLOCATE state when the program issued this call.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in one of the following states when the program issues Confirmed:

CONFIRM

CONFIRM-SEND

CONFIRM-DEALLOCATE

The new state is determined by the old state — the state of the conversation when the local program issued Confirmed. The old state is indicated by the value of status_received of the preceding Receive call. The following table summarizes the possible state changes when return_code is set to CM_OK.

Old state	New state
CONFIRM	RECEIVE
CONFIRM-SEND	SEND
CONFIRM-DEALLOCATE	RESET
Other return codes result in no state change.

Remarks

A confirmation request is issued by one of the following calls in the partner program:

Confirm.

Prepare_To_Receive if the prepare-to-receive type is set to either CM_PREP_TO_RECEIVE_CONFIRM or to CM_PREP_TO_ RECEIVE_SYNC_LEVEL and the conversation’s synchronization level is set to CM_CONFIRM.

Deallocate if the deallocate type is set to CM_DEALLOCATE_CONFIRM or to CM_DEALLOCATE_SYNC_LEVEL and the conversation’s synchronization level is set to CM_CONFIRM.

Send_Data under the following circumstances:

The send type is set to CM_SEND_AND_CONFIRM.

The send type is set to CM_SEND_AND_PREPARE_TO_RECEIVE and the prepare-to-receive type is set to CM_PREPARE_TO_RECEIVE_ CONFIRM.

The send type is set to CM_SEND_AND_PREPARE_TO_RECEIVE, the prepare-to-receive type is set to CM_PREPARE_TO_RECEIVE_SYNC_ LEVEL, and the synchronization level is set to CM_CONFIRM.

The send type is set to CM_SEND_AND_DEALLOCATE and the deallocate type is set to CM_DEALLOCATE_CONFIRM.

The send type is set to CM_SEND_AND_DEALLOCATE, the deallocate type is set to CM_DEALLOCATE_SYNC_LEVEL, and the synchronization level is set to CM_CONFIRM.

A confirmation request is received by the local program through the status_received parameter of Receive. The local program can issue Confirmed only if the status_received parameter is set to one of the following values:

CM_CONFIRM_RECEIVED

CM_CONFIRM_SEND_RECEIVED

CM_CONFIRM_DEALLOC_RECEIVED


Deallocate (cmdeal)
CPI-C Calls	11 of 50

Deallocate (cmdeal)

Deallocates a conversation between two programs.

Syntax

conversation_ID	unsigned char far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
Return Codes

CM_OK

Primary return code; the call executed successfully; the conversation is deallocated.

CM_OPERATION_NOT_ACCEPTED

Primary return code; a previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

Primary return code; the operation has not completed (processing mode is non-blocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation (and conversation). If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PROGRAM_STATE_CHECK

Primary return code; the following state errors can occur when the deallocate type indicates a normal deallocation (CM_DEALLOCATE_SYNC_LEVEL, CM_DEALLOCATE_FLUSH, CM_DEALLOCATE_CONFIRM):

The conversation is not in SEND or SEND-PENDING state.

For a Basic conversation, the conversation is in SEND state, but the program did not finish sending a logical record.

These return codes can be returned when the deallocate_type is set to CM_DEALLOCATE_CONFIRM or to CM_DEALLOCATE_SYNC_LEVEL and the conversation’s synchronization level is set to CM_CONFIRM.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

CM_CONVERSATION_TYPE_MISMATCH

Primary return code; the partner LU or program does not support the conversation type (Basic or Mapped) specified in the allocation request.

CM_PIP_NOT_SPECIFIED_CORRECTLY

Primary return code; the allocation request was rejected by a non – CPI-C LU 6.2 TP. The partner program requires one or more PIP data variables, which are not supported by CPI-C.

CM_SECURITY_NOT_VALID

Primary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

CM_SYNC LEVEL_NOT_SUPPORTED_PGM

Primary return code; the partner program does not support the synchronization level specified in the allocation request.

CM_TPN_NOT_RECOGNIZED

Primary return code; the partner LU does not recognize the program name specified in the allocation request.

CM_TP_NOT_AVAILABLE_NO_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a permanent condition. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

CM_TP_NOT_AVAILABLE_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a temporary condition. The reason for the error may be logged on the remote node. Retry the allocation.

CM_PROGRAM_ERROR_PURGING

Primary return code; one of the following occurred:

While in RECEIVE or CONFIRM state, the partner program issued Send_Error. Data sent but not yet received is purged.

While in SEND-PENDING state with the error direction set to CM_RECEIVE_ERROR, the partner program issued Send_Error. Data was not purged.

CM_RESOURCE_FAILURE_NO_RETRY

Primary return code; one of the following occurred:

The conversation was terminated prematurely because of a permanent condition. Do not retry until the error has been corrected.

The partner program did not deallocate the conversation before terminating normally.

CM_RESOURCE_FAILURE_RETRY

Primary return code; the conversation was terminated prematurely because of a temporary condition, such as modem failure. Retry the conversation.

CM_DEALLOCATED_ABEND

Primary return code; the conversation has been deallocated for one of the following reasons:

The remote program issued Deallocate with the type parameter set to CM_DEALLOCATE_ABEND, or the remote LU has done so because of a remote program abnormal-ending condition. If the conversation for the remote program was in RECEIVE state when the call was issued, information sent by the local program and not yet received by the remote program is purged.

The remote TP terminated normally but did not deallocate the conversation before terminating. Node services at the remote LU deallocated the conversation on behalf of the remote TP.

CM_DEALLOCATED_ABEND_SVC

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner program issued Deallocate with the type parameter set to ABEND_SVC.

The partner program did not deallocate the conversation before terminating.

If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_DEALLOCATED_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner program issued Deallocate with the type parameter set to ABEND_TIMER. If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_SVC_ERROR_PURGING

Primary return code; while in SEND state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC. Data sent to the partner program may have been purged.

State Changes

Depending on the value of the conversation’s deallocate type (set by Set_Deallocate_Type) parameter, the conversation can be in one of the states indicated in the following table when the program issues Deallocate:

Deallocate type	Allowed state
CM_DEALLOCATE_FLUSH	SEND or SEND-PENDING
CM_DEALLOCATE_CONFIRM	SEND or SEND-PENDING
CM_DEALLOCATE_SYNC_LEVEL	SEND or SEND-PENDING
CM_DEALLOCATE_ABEND	Any except RESET
State changes, summarized in the following table, are based on the value of the return_code parameter.

return_code	New state
CM_OK	RESET
CM_PROGRAM_ERROR_PURGING	RECEIVE
CM_SVC_ERROR_PURGING	RECEIVE
CM_CONVERSATION_TYPE_MISMATCH	RESET
CM_PIP_NOT_SPECIFIED_CORRECTLY	RESET
CM_SECURITY_NOT_VALID	RESET
CM_SYNC_LEVEL_NOT_SUPPORTED_PGM	RESET
CM_TPN_NOT_RECOGNIZED	RESET
CM_TP_NOT_AVAILABLE_NO_RETRY	RESET
CM_TP_NOT_AVAILABLE_RETRY	RESET
CM_RESOURCE_FAILURE_NO_RETRY	RESET
CM_RESOURCE_FAILURE_RETRY	RESET
CM_DEALLOCATED_ABEND	RESET
CM_DEALLOCATED_ABEND_SVC	RESET
CM_DEALLOCATED_ABEND_TIMER	RESET
All others	No change
Remarks

Before deallocating the conversation, this call performs the equivalent of either the Flush or Confirmed call, depending on the current conversation synchronization level and deallocate type. The deallocate type is set by Set_Deallocate_Type.

The partner program receives the deallocation notification through one of the following parameters:

status_received is CM_CONFIRM_DEALLOC_RECEIVED

return_code is CM_DEALLOCATED_NORMAL

return_code is CM_DEALLOCATED_ABEND

After this call has successfully executed, the conversation_ID is no longer valid.

For a Basic conversation, if the conversation’s deallocate type is set to CM_DEALLOCATE_ABEND and the log data length is greater than 0, the local LU writes the log data (specified by Set_Log_Data_Type) to the local error log and to the partner LU. For information about log data, see "Set_Log_Data (cmsld)" later in this chapter.

After Deallocate has been executed, the log data length is set to 0 and the log data is set to null.


Delete_CPIC_Side_Information (xcmdsi)
CPI-C Calls	12 of 50

Delete_CPIC_Side_Information (xcmdsi)

Deletes an entry from the side information table in memory. The side information entry is identified through the symbolic destination name.

Syntax

key_lock	unsigned char far *
sym_dest_name	unsigned char far *
return_code	signed long int far *
Parameter	Description
key_lock	Supplied parameter; this parameter is ignored.
sym_dest_name	Supplied parameter; specifies the symbolic destination name of the entry to be deleted.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the sym_dest_name parameter has specified a nonexistent side information entry.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The call is not associated with a conversation and can be in any state.

There is no state change.

Remarks

The side information entry is removed immediately from the side information table in memory.

While this call is being executed, any calls issued by other CPI-C applications that set or extract side information are suspended. These calls include the following:

Set_CPIC_Side_Information

Extract_CPIC_Side_Information

Initialize_Conversation


Extract_Conversation_Security_Type (xcecst)
CPI-C Calls	13 of 50

Extract_Conversation_Security_Type (xcecst)

Returns the security type for a specified conversation.

Syntax

conversation_ID		unsigned char far *
conversation_security_type		signed long int far *
return_code		signed long int far *
Parameter		Description
conversation_ID		Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
conversation_security_type		Returned parameter; specifies the information the partner LU requires in order to validate access to the invoked program. The following are possible values: CM_SECURITY_NONE indicates that the invoked program uses no conversation security. CM_SECURITY_PROGRAM indicates that the invoked program uses conversation security and thus requires a user ID and password. CM_SECURITY_SAME indicates that the invoked program, invoked with a valid user ID and password, in turn invokes another program (as illustrated in Chapter 2, “Writing CPI-C Applications”). For example, assume that program A invokes program B with a valid user ID and password, and program B in turn invokes program C. If program B specifies the value CM_SECURITY_ SAME, CPI-C will send the LU for program C the user ID from program A and an already-verified indicator. This indicator tells program C not to require the password (if program C is configured to accept an already-verified indicator).
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid, or the address of a variable is invalid.

State Changes

The conversation can be in any state except RESET.

There is no state change.


Extract_Conversation_Security_User_ID (cmecsu)
CPI-C Calls	14 of 50

Extract_Conversation_Security_User_ID (cmecsu)

Returns the user ID being used in a specified conversation.

Syntax

conversation_ID	unsigned char far *
security_user_ID	unsigned char far *
security_user_ID_length	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
security_user_ID	Returned parameter; specifies the user ID that was used to establish the conversation.
security_user_ID_length	Returned parameter; specifies the length of security_user_ID.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

State Changes

The conversation can be in any state except RESET.

There is no state change.

Remarks

The security_user_ID value is not padded with spaces. It is meaningful only up to security_user_ID_length.


Extract_Conversation_State (cmecs)
CPI-C Calls	15 of 50

Extract_Conversation_State (cmecs)

Returns the state of the specified conversation.

Syntax

conversation_ID		unsigned char far *
conversation_state		signed long int far *
return_code		signed long int far *
Parameter		Description
conversation_ID		Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
conversation_state		Returned parameter; specifies the conversation state. The following are possible values: CM_INITIALIZE_STATE CM_SEND_STATE CM_RECEIVE_STATE CM_SEND_PENDING_STATE CM_CONFIRM_STATE CM_CONFIRM_SEND_STATE CM_CONFIRM_DEALLOCATE_STATE
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.


Extract_Conversation_Type (cmect)
CPI-C Calls	16 of 50

Extract_Conversation_Type (cmect)

Returns the conversation type — Mapped or Basic — of the specified conversation.

Syntax

conversation_ID	unsigned char far *
conversation_type	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
conversation_type	Returned parameter; specifies the conversation type. The following are possible values: CM_BASIC_CONVERSATION CM_MAPPED_CONVERSATION
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.


Extract_CPIC_Side_Information (xcmesi)
CPI-C Calls	17 of 50

Extract_CPIC_Side_Information (xcmesi)

Returns the side information for an entry number or symbolic destination name.

Syntax

entry_number	signed long int far *
sym_dest_name	unsigned char far *
side_info_entry	side_info far *
side_info_entry_length	signed long int far *
return_code	signed long int far *
Parameter	Description
entry_number	Supplied parameter; specifies the number (index) of the side information entry to be returned. The first entry is 1. The program can look up the side information entry by the symbolic destination name instead. To accomplish this, set the entry number to 0.
sym_dest_name	Supplied parameter; specifies the symbolic destination name to search for. If entry_number is set to a number greater than 0, this parameter is ignored.
side_info_entry	Returned parameter; specifies the side information entry. For a detailed explanation of the side information entry, see "Set_CPIC_Side_Information (xcmssi)" later in this chapter. Each field in the side information structure is left-justified and padded with spaces on the right as necessary.
side_info_entry_length	Supplied parameter; always 124.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The entry_number has specified a number larger than maximum number of entries in the side information table or a number that is less than 0.

The sym_dest_name parameter is invalid and entry_number is set to 0.

The side_info_entry_length parameter is not set to 124.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

This call is not associated with a conversation and can be in any state.

There is no state change.

Remarks

The security password is never returned. If the security user ID in the side information is not set, the security user ID field is returned as all spaces.


Extract_Mode_Name (cmemn)
CPI-C Calls	18 of 50

Extract_Mode_Name (cmemn)

Returns the mode name and mode name length for a specified conversation.

Syntax

conversation_ID	unsigned char far *
mode_name	unsigned char far *
mode_name_length	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
mode_name	Returned parameter; specifies the starting address of the mode name.
mode_name_length	Returned parameter; specifies the length of the mode name.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.


Extract_Partner_LU_Name (cmepln)
CPI-C Calls	19 of 50

Extract_Partner_LU_Name (cmepln)

Returns the partner LU name and partner LU name length for a specified conversation. This can be an alias name of up to 8 bytes or a fully qualified network name of up to 17 bytes.

Syntax

conversation_ID	unsigned char far *
partner_LU_name	unsigned char far *
partner_LU_name_length	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_ Conversation or Accept_Conversation.
partner_LU_name	Returned parameter; specifies the variable containing the partner LU name. (The program must supply a pointer to a suitable variable.)
partner_LU_name_length	Returned parameter; specifies the length of the partner LU name.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.


Extract_Sync_Level (cmesl)
CPI-C Calls	20 of 50

Extract_Sync_Level (cmesl)

Returns the synchronization level for a specified conversation.

Syntax

conversation_ID	unsigned char far *
sync_level	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
sync_level	Returned parameter; indicates the synchronization level of the conversation. The following are possible values: CM_NONE indicates that the programs will not perform confirmation processing. CM_CONFIRM indicates that the programs can perform confirmation processing.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.


Extract_TP_Name (cmetpn)
CPI-C Calls	21 of 50

Extract_TP_Name (cmetpn)

Returns the TP_name characteristic.

Syntax

conversation_ID	unsigned char far *
TP_name	unsigned char far *
TP_name_length	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
TP_name	Returned parameter; specifies the variable containing the TP name.
TP_name_length	Returned parameter; specifies the length of the TP name.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.

Remarks

For an invoking program, the TP_name characteristic will be the value in the side information referenced in the sym_dest_name parameter of the Initialize_Conversation call. For an invokable program, it is the name specified in the conversation startup request (which will have been matched with a name specified locally or in a Specify_Local_TP_Name call), and will therefore be the same as the TP_name characteristic of the partner program.

The name returned can be up to 64 bytes in length.


Flush (cmflus)
CPI-C Calls	22 of 50

Flush (cmflus)

Sends the contents of the local LU’s send buffer to the partner LU (and program). If the send buffer is empty, no action takes place.

Syntax

conversation_ID	unsigned char far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_OPERATION_NOT_ACCEPTED

Primary return code; a previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

Primary return code; the operation has not completed (processing mode is non-blocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation (and conversation). If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation was not in SEND or SEND-PENDING state when the program issued this call.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in SEND or SEND-PENDING state.

If the call completes successfully, (return_code is CM_OK), the conversation is in SEND state.

Other return codes result in no state change.

Remarks

Data processed by Send_Data accumulates in the local LU’s send buffer until one of the following happens:

The local program issues the Flush call or other call that flushes the LU’s send buffer. (Some send types, set by Set_Send_Type, include flush functionality.)

The buffer is full.

The allocation request generated by Allocate and error information generated by Send_Error are also buffered.


Initialize_Conversation (cminit)
CPI-C Calls	23 of 50

Initialize_Conversation (cminit)

Issued by the invoking program to obtain an 8-byte conversation ID and to set the initial values for the conversation’s characteristics.

Syntax

conversation_ID	unsigned char far *
sym_dest_name	unsigned char far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Returned parameter; specifies the identifier for the conversation. It is used by subsequent CPI-C calls.
sym_dest_name	Supplied parameter; specifies the symbolic destination name — the name associated with a side information entry loaded from the configuration file or defined by Set_CPIC_Side_Information calls. The parameter is an 8-byte ASCII character string. The allowed characters are as follows: Uppercase letters Numerals 0 through 9 This parameter can also be set to 8 spaces. In this case, the invoking program must issue the following calls before issuing Allocate: Set_Mode_Name Set Partner_LU_Name Set_TP_Name See "Set_CPIC_Side_Information (xcmssi)" later in this chapter for more details about the side information entry.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by sym_dest_name does not match a symbolic destination name in the side information table and is not a space.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation is in RESET state.

If the return_code is CM_OK, the conversation changes to INITIALIZE state. For other return codes, the conversation state remains unchanged.

Remarks

The initial values are CPI-C defaults or are derived from side information associated with the symbolic destination name. For more information about initial values and side information, see Chapter 1, "Introduction to CPI-C."

Initial values can be changed by the Set_ calls.

If the side information contains an invalid value or a Set_ call sets a conversation characteristic to an invalid value, the error is returned on the Allocate call.

Upon successful execution of this call, CPI-C generates a conversation identifier. This identifier is a required parameter for all other CPI-C calls issued for this conversation by the invoking program.


Prepare_To_Receive (cmptr)
CPI-C Calls	24 of 50

Prepare_To_Receive (cmptr)

Changes the state of the conversation for the local program from SEND to RECEIVE.

Syntax

conversation_ID	unsigned char far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_OPERATION_NOT_ACCEPTED

Primary return code; a previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

Primary return code; the operation has not completed (processing mode is non-blocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation (and conversation). If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PROGRAM_STATE_CHECK

Primary return code; one of the following occurred:

The conversation state is not SEND or SEND-PENDING

For a Basic conversation, the conversation is in SEND state. However, the program did not finish sending a logical record.

These return codes can occur if the conversation’s prepare-to-receive type is set to CM_PREP_TO_RECEIVE_CONFIRM or if the prepare-to-receive type is set to CM_PRE_TO_RECEIVE_SYNC_LEVEL and the conversation’s synchronization level is set to CM_CONFIRM.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

CM_CONVERSATION_TYPE_MISMATCH

Primary return code; the partner LU or program does not support the conversation type (Basic or Mapped) specified in the allocation request.

CM_PIP_NOT_SPECIFIED_CORRECTLY

Primary return code; the allocation request was rejected by a non – CPI-C LU 6.2 TP. The partner program requires one or more PIP data variables, which are not supported by CPI-C.

CM_SECURITY_NOT_VALID

Primary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

CM_SYNC LEVEL_NOT_SUPPORTED_PGM

Primary return code; the partner program does not support the synchronization level specified in the allocation request.

CM_TPN_NOT_RECOGNIZED

Primary return code; the partner LU does not recognize the program name specified in the allocation request.

CM_TP_NOT_AVAILABLE_NO_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a permanent condition. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

CM_TP_NOT_AVAILABLE_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a temporary condition. The reason for the error may be logged on the remote node. Retry the allocation.

CM_PROGRAM_ERROR_PURGING

Primary return code; one of the following occurred:

While in RECEIVE or CONFIRM state, the partner program issued Send_Error. Data sent but not yet received is purged.

While in SEND-PENDING state with the error direction set to CM_RECEIVE_ERROR, the partner program issued Send_Error. Data was not purged.

CM_RESOURCE_FAILURE_NO_RETRY

Primary return code; one of the following occurred:

The conversation was terminated prematurely because of a permanent condition. Do not retry until the error has been corrected.

The partner program did not deallocate the conversation before terminating normally.

CM_RESOURCE_FAILURE_RETRY

Primary return code; the conversation was terminated prematurely because of a temporary condition, such as modem failure. Retry the conversation.

CM_DEALLOCATED_ABEND

Primary return code; the conversation has been deallocated for one of the following reasons:

The remote program issued Deallocate with the type parameter set to CM_DEALLOCATE_ABEND, or the remote LU has done so because of a remote program abnormal-ending condition. If the conversation for the remote program was in RECEIVE state when the call was issued, information sent by the local program and not yet received by the remote program is purged.

The remote TP terminated normally but did not deallocate the conversation before terminating. Node services at the remote LU deallocated the conversation on behalf of the remote TP.

CM_DEALLOCATED_ABEND_SVC

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner program issued Deallocate with the type parameter set to ABEND_SVC.

The partner program did not deallocate the conversation before terminating.

If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_DEALLOCATED_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner program issued Deallocate with the type parameter set to ABEND_TIMER. If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_SVC_ERROR_PURGING

Primary return code; while in SEND state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC. Data sent to the partner program may have been purged.

State Changes

The conversation can be in SEND or SEND-PENDING state.

State changes, summarized in the following table, are based on the value of the return_code parameter.

return_code	New state
CM_OK	RECEIVE
CM_PROGRAM_ERROR_PURGING	RECEIVE
CM_SVC_ERROR_PURGING	RECEIVE
CM_CONVERSATION_TYPE_MISMATCH	RESET
CM_PIP_NOT_SPECIFIED_CORRECTLY	RESET
CM_SECURITY_NOT_VALID	RESET
CM_SYNC_LEVEL_NOT_SUPPORTED_PGM	RESET
CM_TPN_NOT_RECOGNIZED	RESET
CM_TP_NOT_AVAILABLE_NO_RETRY	RESET
CM_TP_NOT_AVAILABLE_RETRY	RESET
CM_DEALLOCATED_ABEND	RESET
CM_RESOURCE_FAILURE_NO_RETRY	RESET
CM_RESOURCE_FAILURE_RETRY	RESET
CM_DEALLOCATED_ABEND_SVC	RESET
CM_DEALLOCATED_ABEND_TIMER	RESET
All others	No change
Before changing the conversation state, this call performs the equivalent of one of the following:

The Flush call, sending the contents of the local LU’s send buffer to the partner LU (and program), if either of the following conditions is true:

The conversation’s prepare-to-receive type is set to CM_PREP_TO_ RECEIVE_FLUSH.

The conversation’s prepare-to-receive type is set to CM_PREP_TO_RECEIVE_ SYNC_LEVEL and the conversation’s synchronization level is set to CM_NONE.

The Confirm call, sending the contents of the local LU’s send buffer and a confirmation request to the partner program, if either of the following conditions is true:

The conversation’s prepare-to-receive type is set to CM_PREP_TO_ RECEIVE_CONFIRM.

The conversation’s prepare-to-receive type is set to CM_PREP_TO_RECEIVE_ SYNC_LEVEL and the conversation’s synchronization level is set to CM_CONFIRM.

The prepare-to-receive type is set by Set_Prepare_To_Receive_Type; the synchronization level is set by Set_Sync_Level.

The conversation cannot change to SEND (or SEND-PENDING) for the partner program until the partner program receives one of the following values via the status_received parameter of the Receive call:

CM_SEND_RECEIVED

CM_CONFIRM_SEND_RECEIVED and replies with the Confirmed or Send_Error call

Remarks

After this call has successfully executed, the local program can receive data.


Receive (cmrcv)
CPI-C Calls	25 of 50

Receive (cmrcv)

Receives any data that is currently available from the partner program. To avoid blocking for clients running Windows version 3.x, use the Specify_Windows_Handle call. For Windows NT, run a background thread for all CPIC communications and preserve the foreground thread for UI only.

Syntax

conversation_ID		unsigned char far *
buffer		unsigned char far *
requested_length		signed long int far *
data_received		signed long int far *
received_length		signed long int far *
status_received		signed long int far *
request_to_send_received		signed long int far *
return_code		signed long int far *
Parameter		Description
conversation_ID		Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
buffer		Returned parameter; specifies the address of the buffer to contain the data received by the local program. The buffer contains data if the following conditions are true: The data_received parameter is set to a value other than CM_NO_DATA_RECEIVED. The return_code parameter is set to CM_OK or to CM_DEALLOCATED_NORMAL.
requested_length		Supplied parameter; indicates the maximum number of bytes of data the local program is to receive. The range is from 0 through 32,767.
data_received		Returned parameter; indicates whether the program received data. The following are possible values. These codes are not relevant unless return_code is set to CM_OK or CM_DEALLOCATED_NORMAL. CM_DATA_RECEIVED can be returned for a Basic conversation, if the conversation’s fill characteristic is set to CM_FILL_BUFFER, indicating that the program is receiving data independent of its logical format. The local program received data until requested_length or end of data was reached.
		The end of the data is indicated by either a change to another conversation state, based on the return_code, status_received, and data_received parameters or an error condition. If the conversation’s receive type is set to CM_RECEIVE_IMMEDIATE, the data received can be less than requested_length if a smaller amount of data has arrived from the partner program. CM_COMPLETE_DATA_RECEIVED indicates, in a Mapped conversation, that the local program has received a complete data record or the last part of a data record. In a Basic conversation with the fill characteristic set to CM_FILL_LL, this value indicates that the local program has received a complete logical record or the end of a logical record. CM_INCOMPLETE_DATA_RECEIVED indicates, in a Mapped conversation, that the local program has received an incomplete data record. The requested_length parameter specified a value less than the length of the data record (or less than the remainder of the data record if this is not the first Receive to read the record). The amount of data received is equal to the requested_length parameter. In a Basic conversation with the fill characteristic set to CM_FILL_LL, this value indicates that the local program has received an incomplete logical record. The amount of data received is equal to the requested_length parameter. (If the received data was truncated, the length of the data will be less than requested_length.)
		Upon receiving this value, the local program normally reissues Receive to receive the next part of the record. CM_NO_DATA_RECEIVED indicates that the program did not receive data.
		Note that if the return_code parameter is set to CM_OK, status information may be available through the status_received parameter.
received_length		Returned parameter; indicates the number of bytes of data the local program received on this Receive call. If return_code or data_received indicate that the program received no data, this number is not relevant.
status_received		Returned parameter; indicates changes in the status of the conversation. The following are possible values. These codes are not relevant unless return_code is set to CM_OK. CM_NO_STATUS_RECEIVED indicates that no conversation status change was received on this call. CM_SEND_RECEIVED indicates, for the partner program, that the conversation has entered RECEIVE state. For the local program, the conversation is now in SEND state if no data was received on this call, or SEND-PENDING state if data was received on this call. Upon receiving this value, the local program normally uses Send_Data to begin sending data. CM_CONFIRM_DEALLOC_RECEIVED indicates that the partner program has issued Deallocate with confirmation requested. For the local program the conversation is now in CONFIRM-DEALLOCATE state. Upon receiving this value, the local program normally issues the Confirmed call. CM_CONFIRM_RECEIVED indicates that the partner program has issued the Confirm call. For the local program the conversation is in CONFIRM state. Upon receiving this value, the local program normally issues the Confirmed call.
request_to_send_received		Returned parameter; specifies the request-to-send-received indicator. The following are possible values: CM_REQ_TO_SEND_RECEIVED indicates that the partner program has issued the Request_To_Send call, which requests the local program to change the conversation to RECEIVE state.
		CM_REQ_TO_SEND_NOT_RECEIVED indicates that the partner program has not issued the Request_To_Send call. This value is not relevant if the return_code parameter is set to CM_PROGRAM_PARAMETER_CHECK or CM_PROGRAM_ STATE_CHECK.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_OPERATION_NOT_ACCEPTED

Primary return code; a previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

Primary return code; the operation has not completed (processing mode is non-blocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation (and conversation). If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.

CM_UNSUCCESSFUL

Primary return code; the receive type is set to CM_RECEIVE_IMMEDIATE and no data is immediately available from the partner program.

CM_DEALLOCATED_NORMAL

Primary return code; the conversation has been deallocated normally. The partner program issued Deallocate with the conversation’s deallocate type set to CM_DEALLOCATE_FLUSH or CM_DEALLOCATE_SYNC_LEVEL with the synchronization level of the conversation specified as CM_NONE.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID is invalid.

The value specified by requested_length is out of range (greater than 32,767).

If the program receives this return code, the other returned parameters are not valid.

CM_PROGRAM_STATE_CHECK

Primary return code; one of the following occurred:

The receive type is set to CM_RECEIVE_AND_WAIT and the conversation state is not RECEIVE, SEND, or SEND-PENDING.

The receive type is set to CM_RECEIVE_IMMEDIATE and the conversation state is not RECEIVE.

In a Basic conversation, the conversation is in SEND state, the receive type is set to CM_RECEIVE_AND_WAIT, and the program did not finish sending a logical record.

If the program receives this return code, the other returned parameters are not valid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

CM_CONVERSATION_TYPE_MISMATCH

Primary return code; the partner LU or program does not support the conversation type (Basic or Mapped) specified in the allocation request.

CM_PIP_NOT_SPECIFIED_CORRECTLY

Primary return code; the allocation request was rejected by a non – CPI-C LU 6.2 TP. The partner program requires one or more PIP data variables, which are not supported by CPI-C.

CM_SECURITY_NOT_VALID

Primary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

CM_SYNC LEVEL_NOT_SUPPORTED_PGM

Primary return code; the partner program does not support the synchronization level specified in the allocation request.

CM_TPN_NOT_RECOGNIZED

Primary return code; the partner LU does not recognize the program name specified in the allocation request.

CM_TP_NOT_AVAILABLE_NO_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a permanent condition. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

CM_TP_NOT_AVAILABLE_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a temporary condition. The reason for the error may be logged on the remote node. Retry the allocation.

CM_PROGRAM_ERROR_NO_TRUNC

Primary return code; while in SEND state or in SEND-PENDING state with the error direction set to CM_SEND_ERROR, the partner program has issued Send_Error. Data was not truncated.

CM_PROGRAM_ERROR_PURGING

Primary return code; one of the following occurred:

While in RECEIVE or CONFIRM state, the partner program issued Send_Error. Data sent but not yet received is purged.

While in SEND_PENDING state with the error direction set to CM_RECEIVE_ERROR, the partner program issued Send_Error. Data was not purged.

CM_RESOURCE_FAILURE_NO_RETRY

Primary return code; one of the following occurred:

The conversation was terminated prematurely because of a permanent condition. Do not retry until the error has been corrected.

The partner program did not deallocate the conversation before terminating normally.

CM_RESOURCE_FAILURE_RETRY

Primary return code; the conversation was terminated prematurely because of a temporary condition, such as modem failure. Retry the conversation.

CM_DEALLOCATED_ABEND

Primary return code; the conversation has been deallocated for one of the following reasons:

The remote program issued Deallocate with the type parameter set to CM_DEALLOCATE_ABEND, or the remote LU has done so because of a remote program abnormal-ending condition. If the conversation for the remote program was in RECEIVE state when the call was issued, information sent by the local program and not yet received by the remote program is purged.

The remote TP terminated normally but did not deallocate the conversation before terminating. Node services at the remote LU deallocated the conversation on behalf of the remote TP.

CM_DEALLOCATED_ABEND_SVC

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner program issued Deallocate with the type parameter set to ABEND_SVC.

The partner program did not deallocate the conversation before terminating.

If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_DEALLOCATED_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner program has issued Deallocate with the type parameter set to ABEND_TIMER. If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_SVC_ERROR_PURGING

Primary return code; while in SEND state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC. Data sent to the partner program may have been purged.

CM_SVC_ERROR_NO_TRUNC

Primary return code; while in SEND state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC. Data sent to the partner program may have been purged.

CM_PROGRAM_ERROR_TRUNC

Primary return code; in SEND state, before finishing sending a complete logical record, the partner program issued Send_Error. The local program may have received the first part of the logical record through a Receive call.

CM_SVC_ERROR_TRUNC

Primary return code; while in RECEIVE or CONFIRM state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC before it finished sending a complete logical record. The local program may have received the first part of the logical record.

State Changes

The conversation can be in RECEIVE, SEND, or SEND-PENDING state.

If receive_type is set to CM_RECEIVE_IMMEDIATE, the conversation must be in RECEIVE state.

Issuing Receive while the conversation is in SEND or SEND-PENDING state causes the local LU to send the information in its send buffer and a send indicator to the partner program. Based on data_received and status_received the conversation may change to RECEIVE state for the local program.

The new conversation state is determined by:

The state the conversation is in when the program issues the call.

The return_code parameter.

The data_received and status_received parameters.

If no data is currently available and the receive type (set by Set_Receive_Type) is set to CM_RECEIVE_AND_WAIT, the local program waits for data to arrive. If the receive type is set to CM_RECEIVE_IMMEDIATE, the local program does not wait.

The process for receiving data is as follows:

The local program issues a Receive call until it finishes receiving a complete unit of data. The local program may need to issue Receive several times in order to receive a complete unit of data. The data_received parameter indicates whether the receipt of data is finished.

The data received may be:

One data record transmitted in a Mapped conversation.

One logical record transmitted in a Basic conversation with the conversation’s fill characteristic set to CM_FILL_LL.

A buffer of data received independent of its logical-record format in a Basic conversation with the fill characteristic set to CM_FILL_BUFFER.

Once a complete unit of data has been received, the local program can manipulate it.

The local program determines the next action to take based on the control information received through status_received. The local program may have to reissue Receive to receive the control information.

The conversation type is set by Set_Conversation_Type; the fill characteristic is set by Set_Fill.

The following table summarizes the state changes that can occur when Receive is issued with the conversation in RECEIVE state and return_code is CM_OK.

data_received	status_received	New state
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	No change
CM_COMPLETE_DATA_ RECEIVED	CM_NO_STATUS_RECEIVED	No change
CM_INCOMPLETE_DATA_ RECEIVED	CM_SEND_RECEIVED	SEND-PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	SEND
If return_code is set to CM_UNSUCCESSFUL, meaning that the receive_type is set to CM_RECEIVE_IMMEDIATE and no data is available, there is no state change.

The following table summarizes the state changes that can occur when Receive is issued with the conversation in SEND state and return_code is CM_OK.

data_received	status_received	New state
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_COMPLETE_DATA_ RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_INCOMPLETE_DATA_ RECEIVED	CM_SEND_RECEIVED	SEND-PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	No change
The following table summarizes the state changes that can occur when Receive is issued with the conversation in SEND-PENDING state and return_code is CM_OK.

data_received	status_received	New state
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_COMPLETE_DATA_ RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_INCOMPLETE_DATA_ RECEIVED	CM_SEND_RECEIVED	No change
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	SEND
The following sections summarize state changes that can occur when Receive is issued in any allowed state.

Confirmation Processing

The following table summarizes state changes that occur under the following conditions:

The return_code parameter is CM_OK.

The data_received parameter is set to CM_DATA_RECEIVED, CM_COMPLETE_DATA_RECEIVED, or CM_NO_DATA_RECEIVED.

The status_received parameter indicates a change to a CONFIRM state.

status_received	New state
CM_CONFIRM_DEALLOC_RECEIVED	CONFIRM-DEALLOCATE
CM_CONFIRM_SEND_RECEIVED	CONFIRM-SEND
CM_CONFIRM_RECEIVED	CONFIRM
Normal Deallocation

If return_code is set to CM_DEALLOCATED_NORMAL, the conversation changes to RESET state.

ABEND

The following ABEND conditions, indicated by return_code, cause the conversation to change to RESET state:

CM_CONVERSATION_TYPE_MISMATCH

CM_PIP_NOT_SPECIFIED_CORRECTLY

CM_SECURITY_NOT_VALID

CM_SYNC_LEVEL_NOT_SUPPORTED_PGM

CM_TPN_NOT_RECOGNIZED

CM_TP_NOT_AVAILABLE_NO_RETRY

CM_TP_NOT_AVAILABLE_RETRY

CM_DEALLOCATED_ABEND

CM_DEALLOCATED_ABEND_SVC

CM_DEALLOCATED_ABEND_TIMER

CM_SVC_ERROR_TRUNC

CM_RESOURCE_FAILURE_NO_RETRY

CM_RESOURCE_FAILURE_RETRY

Errors

The following table summarizes state changes that occur when a data transmission error is encountered.

return_code	Old state	New state
CM_PROGRAM_ERROR_PURGING	RECEIVE	No change
CM_PROGRAM_ERROR_NO_TRUNC	RECEIVE	No change
CM_SVC_ERROR_PURGING	SEND	RECEIVE
CM_SVC_ERROR_NO_TRUNC	SEND-PENDING	RECEIVE
If the partner program truncates a logical record, the local program receives notification of the truncation through return_code on the next Receive call.

If a program issues Receive with requested_length set to 0, the call is executed as usual. However, data_received and status_received are not set on the same Receive call. (One exception to this situation is the null record sent over a Mapped conversation, described in the next paragraph.)

In a Mapped conversation in which data is available from the partner program, data_received is set to CM_INCOMPLETE_DATA_RECEIVED. If a null record is available (send_length in the Send_Data call issued by the partner program is set to 0), data_received is set to CM_COMPLETE_RECORD_RECEIVED with received_length set to 0.

In a Basic conversation in which data is available and the fill characteristic is set to CM_FILL_LL, data_received is set to CM_INCOMPLETE_ DATA_RECEIVED. If the fill characteristic is set to CM_FILL_BUFFER, data_received is set to CM_DATA_RECEIVED.

The LU does not automatically perform any conversion between EBCDIC and ASCII on the received string of data before putting it in buffer. If necessary, the program can use the CSV CONVERT to translate a string from one character set to the other.


Request_To_Send (cmrts)
CPI-C Calls	26 of 50

Request_To_Send (cmrts)

Notifies the partner program that the local program wants to send data.

Syntax

conversation_ID	unsigned char far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_OPERATION_NOT_ACCEPTED

Primary return code; a previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

Primary return code; the operation has not completed (processing mode is non-blocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation (and conversation). If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation is not in the RECEIVE, SEND, SEND-PENDING, CONFIRM, CONFIRM-SEND, or CONFIRM-DEALLOCATE state.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any of the following states: RECEIVE, SEND, SEND-PENDING, CONFIRM, CONFIRM-SEND, or CONFIRM-DEALLOCATE.

There is no state change.

In response to this request, the partner program can change the conversation to RECEIVE state by issuing one of the following calls:

Receive with receive type set to CM_RECEIVE_AND_WAIT

Prepare_To_Receive

Send_Data with send type set to CM_SEND_AND_PREP_TO_RECEIVE

The partner program can also ignore the request to send.

The conversation state changes to SEND for the local program when the local program receives one of the following values through the status_received parameter of a subsequent Receive call:

CM_SEND_RECEIVED

CM_CONFIRM_SEND_RECEIVED and the local program replies with a Confirmed call

Remarks

The request-to-send notification is received by the partner program through the request_to_send_received parameter of the following calls:

Confirmed

Receive

Send_Data

Send_Error

Test_Request_To_Send_Received

Request-to-send notification is sent to the partner program immediately; CPI-C does not wait until the send buffer fills up or is flushed. Consequently, the request-to-send notification may arrive out of sequence. For example, if the local program is in SEND state and issues the Prepare_To_Receive call followed by the Request_To_Send call, the partner program, in RECEIVE state, may receive the request-to-send notification before it receives the send notification. For this reason, request_to_send can be reported to a program through the Receive call.

Upon receiving a request-to-send notification, the partner LU retains the notification until the partner issues a call that returns request_to_send_received. The LU keeps only one request-to-send notification per conversation. So the local program can issue more Request_To_Send calls than are explicitly handled by the partner TP.


Send_Data (cmsend)
CPI-C Calls	27 of 50

Send_Data (cmsend)

Puts data in the local LU’s send buffer for transmission to the partner program.

Syntax

conversation_ID		unsigned char far *
buffer		unsigned char far *
send_length		signed long int far *
request_to_send_received		signed long int far *
return_code		signed long int far *
Parameter		Description
conversation_ID		Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
buffer		Supplied parameter; specifies the address of the buffer containing the data to be put in the local LU’s send buffer.
send_length		Supplied parameter; specifies the number of bytes of data to be put in the local LU’s send buffer. The range is from 0 through 32,767. For a Mapped conversation, if send_length is set to 0, a null data record is sent to the partner program. For a Basic conversation, if send_length is set to 0, no data is sent. The buffer parameter is not relevant. However, the other parameters are processed.
request_to_send_received		Returned parameter; is the request-to-send-received indicator. The following are possible values: CM_REQ_TO_SEND_RECEIVED indicates that the partner program has issued the Request_To_ Send call, which requests the local program to change the conversation to RECEIVE state. CM_REQ_TO_SEND_NOT_RECEIVED indicates that the partner program has not issued the Request_To_Send call. This value is not relevant if return_code is set to CM_PROGRAM_ PARAMETER_CHECK or CM_PROGRAM_STATE_CHECK.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_OPERATION_NOT_ACCEPTED

Primary return code; a previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

Primary return code; the operation has not completed (processing mode is non-blocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation (and conversation). If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID is invalid.

The value specified by send_length is out of range (greater than 32,767).

This is a Basic conversation and the first 2 bytes of buffer contain an invalid logical record length (X'0000', X'0001', X'8000', or X'8001').

CM_PROGRAM_STATE_CHECK

Primary return code; one of the following occurred:

The conversation state is not SEND or SEND-PENDING.

The Basic conversation is in SEND state and send_type is set to CM_SEND_AND_CONFIRM, CM_SEND_AND_DEALLOCATE, or CM_SEND_AND_PREP_TO_RECEIVE. However, the data does not end on a logical record boundary. This condition is allowed only when deallocate_type is set to CM_DEALLOCATE_ABEND, and the send_type is set to CM_SEND_AND_DEALLOCATE.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

CM_CONVERSATION_TYPE_MISMATCH

Primary return code; the partner LU or program does not support the conversation type (Basic or Mapped) specified in the allocation request.

CM_PIP_NOT_SPECIFIED_CORRECTLY

Primary return code; the allocation request was rejected by a non – CPIC LU 6.2 TP. The partner program requires one or more PIP data variables, which are not supported by CPIC.

CM_SECURITY_NOT_VALID

Primary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

CM_SYNC LEVEL_NOT_SUPPORTED_PGM

Primary return code; the partner program does not support the synchronization level specified in the allocation request.

CM_TPN_NOT_RECOGNIZED

Primary return code; the partner LU does not recognize the program name specified in the allocation request.

CM_TP_NOT_AVAILABLE_NO_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a permanent condition. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

CM_TP_NOT_AVAILABLE_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a temporary condition. The reason for the error may be logged on the remote node. Retry the allocation.

CM_PROGRAM_ERROR_PURGING

Primary return code; one of the following occurred:

While in RECEIVE or CONFIRM state, the partner program issued Send_Error. Data sent but not yet received is purged.

While in SEND_PENDING state with the error direction set to CM_RECEIVE_ERROR, the partner program issued Send_Error. Data was not purged.

CM_RESOURCE_FAILURE_NO_RETRY

Primary return code; one of the following occurred:

The conversation was terminated prematurely because of a permanent condition. Do not retry until the error has been corrected.

The partner program did not deallocate the conversation before terminating normally.

CM_RESOURCE_FAILURE_RETRY

Primary return code; the conversation was terminated prematurely because of a temporary condition, such as modem failure. Retry the conversation.

CM_DEALLOCATED_ABEND

Primary return code; the conversation has been deallocated for one of the following reasons:

The remote program issued Deallocate with the type parameter set to CM_DEALLOCATE_ABEND, or the remote LU has done so because of a remote program abnormal-ending condition. If the conversation for the remote program was in RECEIVE state when the call was issued, information sent by the local program and not yet received by the remote program is purged.

The remote TP terminated normally but did not deallocate the conversation before terminating. Node services at the remote LU deallocated the conversation on behalf of the remote TP.

CM_DEALLOCATED_ABEND_SVC

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner program issued Deallocate with the type parameter set to ABEND_SVC.

The partner program did not deallocate the conversation before terminating.

If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_DEALLOCATED_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner program issued Deallocate with the type parameter set to ABEND_TIMER. If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_SVC_ERROR_PURGING

Primary return code; while in SEND state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC. Data sent to the partner program may have been purged.

State Changes

The conversation must be in SEND or SEND-PENDING state when the program issues this call.

The following tables summarize state changes that are possible when return_code is set to CM_OK.

send_type	Old state	New state
CM_BUFFER_DATA	SEND	No change
	SEND-PENDING	SEND
CM_SEND_AND_FLUSH	SEND	No change
	SEND-PENDING	SEND
CM_SEND_AND_CONFIRM	SEND	No change
	SEND-PENDING	SEND
CM_SEND_AND_PREP_TO_RECEIVE		RECEIVE
CM_SEND_AND_DEALLOCATE		RESET
For a return_code value of CM_PROGRAM_ERROR_PURGING or CM_SVC_ERROR_PURGING, the conversation changes to RECEIVE state. For other non – CM_OK values, the conversation changes to RESET state.

Remarks

The data collected in the local LU’s send buffer is transmitted to the partner LU (and partner program) when one of the following occurs:

The send buffer fills up.

The local program issues a Flush, Confirm, or Deallocate call or other call that flushes the LU’s send buffer. (Some send types, set by Set_Send_Type, include flush functionality.)

The data to be sent can be either:

A complete data record on a Mapped conversation. A complete data record is a string of the length specified by the send_length parameter.

A complete logical record or portion thereof on a Basic conversation. A complete logical record is determined by the LL value. (One logical record can end and a new one begin in the middle of the string of data to be sent.)

The LU does not automatically perform any conversion between ASCII and EBCDIC on the string of data to be sent. If necessary, the program can use the CSV CONVERT to translate a string from one character set to the other.


Send_Error (cmserr)
CPI-C Calls	28 of 50

Send_Error (cmserr)

Notifies the partner program that the local program has encountered an application-level error.

Syntax

conversation_ID		unsigned char far *
request_to_send_received		signed long int far *
return_code		signed long int far *
Parameter		Description
conversation_ID		Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
request_to_send_received		Returned parameter; specifies the request-to-send-received indicator. The following are possible values: CM_REQ_TO_SEND_RECEIVED indicates that the partner program has issued Request_To_Send, which requests the local program to change the conversation to RECEIVE state. CM_REQ_TO_SEND_NOT_RECEIVED indicates that the partner program has not issued Request_To_Send. This value is not relevant if return_code is set to CM_PROGRAM_PARAMETER_CHECK or CM_STATE_CHECK.
Return Codes

The value of return_code varies depending on the conversation state when the call is issued.

SEND State

If the program issues the call with the conversation in SEND state the following return codes are possible:

CM_OK

Primary return code; the call executed successfully.

CM_OPERATION_NOT_ACCEPTED

Primary return code; a previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

Primary return code; the operation has not completed (processing mode is non-blocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation (and conversation). If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

CM_CONVERSATION_TYPE_MISMATCH

Primary return code; the partner LU or program does not support the conversation type (Basic or Mapped) specified in the allocation request.

CM_PIP_NOT_SPECIFIED_CORRECTLY

Primary return code; the allocation request was rejected by a non – CPI-C LU 6.2 TP. The partner program requires one or more PIP data variables, which are not supported by CPI-C.

CM_SECURITY_NOT_VALID

Primary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

CM_SYNC LEVEL_NOT_SUPPORTED_PGM

Primary return code; the partner program does not support the synchronization level specified in the allocation request.

CM_TPN_NOT_RECOGNIZED

Primary return code; the partner LU does not recognize the program name specified in the allocation request.

CM_TP_NOT_AVAILABLE_NO_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a permanent condition. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

CM_TP_NOT_AVAILABLE_RETRY

Primary return code; the partner LU cannot start the program specified in the allocation request because of a temporary condition. The reason for the error may be logged on the remote node. Retry the allocation.

CM_PROGRAM_ERROR_PURGING

Primary return code; one of the following occurred:

While in RECEIVE or CONFIRM state, the partner program issued Send_Error. Data sent but not yet received is purged.

While in SEND_PENDING state with the error direction set to CM_RECEIVE_ERROR, the partner program issued Send_Error. Data was not purged.

CM_RESOURCE_FAILURE_NO_RETRY

Primary return code; one of the following occurred:

The conversation was terminated prematurely because of a permanent condition. Do not retry until the error has been corrected.

The partner program did not deallocate the conversation before terminating normally.

CM_RESOURCE_FAILURE_RETRY

Primary return code; the conversation was terminated prematurely because of a temporary condition, such as modem failure. Retry the conversation.

CM_DEALLOCATED_ABEND

Primary return code; the conversation has been deallocated for one of the following reasons:

The remote program issued Deallocate with the type parameter set to CM_DEALLOCATE_ABEND, or the remote LU has done so because of a remote program abnormal-ending condition. If the conversation for the remote program was in RECEIVE state when the call was issued, information sent by the local program and not yet received by the remote program is purged.

The remote TP terminated normally but did not deallocate the conversation before terminating. Node services at the remote LU deallocated the conversation on behalf of the remote TP.

CM_DEALLOCATED_ABEND_SVC

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner program issued Deallocate with the type parameter set to ABEND_SVC.

The partner program did not deallocate the conversation before terminating.

If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_DEALLOCATED_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner program issued Deallocate with the type parameter set to ABEND_TIMER. If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

CM_SVC_ERROR_PURGING

Primary return code; while in SEND state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC. Data sent to the partner program may have been purged.

RECEIVE State

If the call is issued in RECEIVE state, the following return codes are possible:

CM_OK

Primary return code; because incoming information is purged when the Send_Error call is issued in RECEIVE state, CM_OK is generated instead of the following:

CM_PROGRAM_ERROR_NO_TRUNC
CM_PROGRAM_ERROR_PURGING
CM_SVC_ERROR_NO_TRUNC
CM_SVC_ERROR_PURGING
CM_PROGRAM_ERROR_TRUNC
CM_SVC_ERROR_TRUNC (Basic conversation only)
CM_PRODUCT_SPECIFIC_ERROR
CM_RESOURCE_FAILURE_NO_RETRY
CM_RESOURCE_FAILURE_RETRY

For an explanation of these return codes, see Appendix A, "Common Return Codes."

CM_DEALLOCATED_NORMAL

Primary return code; because incoming information is purged when Send_Error is issued in RECEIVE state, CM_DEALLOCATED_NORMAL is generated instead of the following:

CM_CONVERSATION_TYPE_MISMATCH
CM_PIP_NOT_SPECIFIED_CORRECTLY
CM_SECURITY_NOT_VALID
CM_SYNC_LEVEL_NOT_SUPPORTED_PGM
CM_TPN_NOT_RECOGNIZED
CM_TP_NOT_AVAILABLE_NO_RETRY
CM_TP_NOT_AVAILABLE_RETRY
CM_DEALLOCATED_ABEND
CM_DEALLOCATED_ABEND_SVC
CM_DEALLOCATED_ABEND_TIMER

SEND-PENDING State

If the call is issued in SEND-PENDING state, the following return codes are possible:

CM_OK

Primary return code; the call executed successfully.

CM_PRODUCT_SPECIFIC_ERROR
CM_PROGRAM_ERROR_PURGING
CM_RESOURCE_FAILURE_NO_RETRY
CM_RESOURCE_FAILURE_RETRY
CM_DEALLOCATED_ABEND
CM_DEALLOCATED_ABEND_SVC
CM_DEALLOCATED_ABEND_TIMER
CM_SVC_ERROR_PURGING

For an explanation of these return codes, see Appendix A, "Common Return Codes."

CONFIRM, CONFIRM-SEND, or CONFIRM-DEALLOCATE State

If the call is issued in CONFIRM, CONFIRM-SEND, or CONFIRM-DEALLOCATE state, the following return codes are possible:

CM_OK

Primary return code; the call executed successfully.

CM_PRODUCT_SPECIFIC_ERROR
CM_RESOURCE_FAILURE_NO_RETRY
CM_RESOURCE_FAILURE_RETRY

For an explanation of these return codes, see Appendix A, "Common Return Codes."

Other States

Issuing Send_Error with the conversation in RESET or INITIALIZE state is illegal. The following return codes are possible:

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation state is not SEND, RECEIVE, CONFIRM, CONFIRM-SEND, CONFIRM-DEALLOCATE, or SEND-PENDING.

State Changes

The conversation can be in any state except INITIALIZE or RESET.

The new state is determined by return_code. Possible state changes are summarized in the following table.

return_code	New state
CM_OK	SEND
CM_CONVERSATION_TYPE_MISMATCH	RESET
CM_PIP_NOT_SPECIFIED_CORRECTLY	RESET
CM_SECURITY_NOT_VALID	RESET
CM_SYNC_LEVEL_NOT_SUPPORTED_PGM	RESET
CM_TPN_NOT_RECOGNIZED	RESET
CM_TP_NOT_AVAILABLE_NO_RETRY	RESET
CM_TP_NOT_AVAILABLE_RETRY	RESET
CM_RESOURCE_FAILURE_RETRY	RESET
CM_RESOURCE_FAILURE_NO_RETRY	RESET
CM_DEALLOCATED_ABEND	RESET
CM_DEALLOCATED_ABEND_PROG	RESET
CM_DEALLOCATED_ABEND_SVC	RESET
CM_DEALLOCATED_ABEND_TIMER	RESET
CM_DEALLOCATED_NORMAL	RESET
CM_PROGRAM_ERROR_PURGING	RECEIVE
CM_SVC_ERROR_PURGING	RECEIVE
All others	No change
Upon successful execution of this call, the conversation is in SEND state for the local program and in RECEIVE state for the partner program.

In a Basic conversation, the local program can use Set_Log_Data to specify that error log data be sent to the partner LU and added to the local error log. If the conversation’s log data length characteristic is greater than 0, the LU formats the data and stores it in the send buffer.

After Send_Error is completed the log data length is set to 0 and the log data to null.

If the conversation is in RECEIVE state when the program issues Send_Error, incoming data is purged by CPIC. This data includes:

Data sent by Send_Data.

Confirmation requests.

Deallocation requests if the conversation’s deallocate type is set to CM_DEALLOCATE_CONFIRM or to CM_DEALLOCATE_SYNC_LEVEL with the synchronization level set to CM_CONFIRM.

CPI-C does not purge an incoming request-to-send indicator.

If the conversation is in SEND-PENDING state, the local program can issue Set_Error_Direction to specify whether the error being reported resulted from the received data or from the processing of the local program after successfully receiving the data.

Remarks

The local program can use Send_Error for such purposes as informing the partner program of an error encountered in received data, rejecting a confirmation request, or truncating an incomplete logical record it is sending.

Send_Error flushes the local LU’s send buffer and sends the partner program the contents of the send buffer followed by the error notification.

The error notification is sent to the partner as one of the following return_code values:

CM_PROGRAM_ERROR_TRUNC

CM_PROGRAM_ERROR_NO_TRUNC

CM_PROGRAM_ERROR_PURGING


Set_Conversation_Security_Password (cmscsp)
CPI-C Calls	29 of 50

Set_Conversation_Security_Password (cmscsp)

Issued by the invoking program to specify the password required to gain access to the invoked program.

Syntax

conversation_ID	unsigned char far *
security_password	unsigned char far *
security_password_length	unsigned long int far *
return_code	signed long int far*
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.
security_password	Supplied parameter; specifies the password required to gain access to the partner program. This parameter is a character string of up to eight ASCII characters and is case sensitive. It must match the password for the user ID configured for the partner program. The allowed characters are: Uppercase and lowercase letters. Numerals 0 through 9. Special characters, except the space.
security_password_length	Supplied parameter; specifies the length of security_password. The range is from 1 through 8.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID is invalid.

The value specified by security_password_length is out of range.

CM_PROGRAM_STATE_CHECK

Primary return code; one of the following occurred:

The conversation is not in INITIALIZE state.

The conversation’s security type is not set to CM_SECURITY_PROGRAM.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.

Remarks

This call has an effect on the conversation only if the conversation security type is CM_SECURITY_PROGRAM. It overrides the initial password from the side information specified by Initialize_Conversation. This call cannot be issued after Allocate has been issued.

An invalid password is not detected until the allocation request, generated by Allocate, is sent to the partner LU. The error is returned to the invoking program on a subsequent call.


Set_Conversation_Security_Type (cmscst)
CPI-C Calls	30 of 50

Set_Conversation_Security_Type (cmscst)

Issued by the invoking program to specify the information the partner LU requires in order to validate access to the invoked program. This call overrides the initial security type from the side information specified by Initialize_Conversation. This call cannot be issued after the Allocate has been issued.

Syntax

conversation_ID		unsigned char far *
conversation_security_type		signed long int far *
return_code		signed long int far *
Parameter		Description
conversation_ID		Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.
conversation_security_type		Supplied parameter; specifies the information the partner LU requires in order to validate access to the invoked program. Based on the conversation security established for the invoked program during configuration, use one of the following values: CM_SECURITY_NONE to indicate that the invoked program uses no conversation security. CM_SECURITY_PROGRAM to indicate that the invoked program uses conversation security and thus requires a user ID and password. CM_SECURITY_SAME to specify that the invoked program, invoked with a valid user ID and password, in turn invokes another program (as illustrated in Chapter 2, “Writing CPI-C Applications”). For example, assume that program A invokes program B with a valid user ID and password, and program B in turn invokes program C. If program B specifies the value XC_SECURITY_SAME, CPI-C will send the LU for program C the user ID from program A and an already-verified indicator. This indicator tells program C not to require the password (if program C is configured to accept an already-verified indicator).
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation is not in INITIALIZE state.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID or conversation_security_type is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.

Remarks

If conversation_security_type is set to CM_SECURITY_NONE or CM_SECURITY_SAME, the user ID and password are ignored when the conversation is allocated.


Set_Conversation_Security_User_ID (cmscsu)
CPI-C Calls	31 of 50

Set_Conversation_Security_User_ID (cmscsu)

Issued by the invoking program to specify the user ID required to gain access to the invoked program. This call has an effect on the conversation only if the conversation security type is CM_SECURITY_PROGRAM. It overrides the initial user ID from the side information specified by Initialize_Conversation. This call cannot be issued after Allocate has been issued.

Syntax

conversation_ID	unsigned char far *
security_user_ID	unsigned char far *
security_user_ID_length	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.
security_user_ID	Supplied parameter; specifies the user ID required to gain access to the partner program. This parameter is a character string up to eight ASCII characters and is case sensitive. The allowed characters are: Uppercase and lowercase letters. Numerals 0 through 9. Special characters, except the space.
security_user_ID_length	Supplied parameter; specifies the length of security_user_ID. The range is from 1 through 8.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID is invalid.

The value specified by security_user_ID_length is out of range.

CM_PROGRAM_STATE_CHECK

Primary return code; one of the following occurred:

The conversation is not in INITIALIZE state.

The conversation’s security type is not set to CM_SECURITY_PROGRAM.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.

Remarks

An invalid user ID is not detected until the allocation request, generated by Allocate, is sent to the partner LU. The error is returned to the invoking program on a subsequent call.


Set_Conversation_Type (cmsct)
CPI-C Calls	32 of 50

Set_Conversation_Type (cmsct)

Issued by the invoking program to define a conversation as being Mapped or Basic. This call overrides the default conversation type established by Initialize_Conversation. The default conversation type is CM_MAPPED_CONVERSATION. This call cannot be issued after Allocate has been issued.

Syntax

conversation_ID	unsigned char far *
conversation_type	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.
conversation_type	Supplied parameter; specifies the type of conversation to be allocated by Allocate. Possible values are: CM_BASIC_CONVERSATION CM_MAPPED_CONVERSATION
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation is not in INITIALIZE state.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID or conversation_type is invalid.

The conversation_type parameter specifies a Mapped conversation, but the fill characteristic is set to CM_FILL_BUFFER, which is incompatible with Mapped conversations. Before changing the conversation type to Mapped, you must issue the Set_Fill call to change the fill type to CM_FILL_LL.

The conversation_type parameter specifies a Mapped conversation. However, a previous Set_Log_Data call, allowed only in Basic conversations, is still in effect.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.


Set_CPIC_Side_Information (xcmssi)
CPI-C Calls	33 of 50

Set_CPIC_Side_Information (xcmssi)

Adds or replaces a side information entry in memory. A CPI-C side information entry associates a set of conversation characteristics with a symbolic definition name. This call overrides entries having the same symbolic destination name.

Syntax

key_lock		unsigned char far *
side_info_entry		side_info far *
side_info_entry_length		signed long int far *
return_code		signed long int far *
Parameter		Description
key_lock		Supplied parameter; this parameter is ignored.
side_info_entry		Supplied parameter; specifies the contents of a side information entry. The following table describes the side_info_entry structure, which defines the format of the side information entry:
		Offset		Description		Type		Length
		0		sym_dest_name		unsigned char		8 bytes
		8		partner_LU_name		unsigned char		17 bytes
		25		reserved		unsigned char		3 bytes
		28		TP_name_type		signed long int		32 bits
		32		TP_name		unsigned char		64 bytes
		96		mode_name		unsigned char		8 bytes
		104		conversation_security _type		signed long int		32 bits
		108		security_user_ID		unsigned char		8 bytes
		116		security_password		unsigned char		8 bytes
		The allowed characters for sym_dest_name are the uppercase letters (A through Z) and the numerals 0 through 9.
		Set_CPIC_Side_Information is the only CPI-C call that lets you specify an SNA service TP as the partner program. The SNA convention for naming a service TP is up to four characters. The first character is a hexadecimal byte between X'00' and X'3F'. The remaining characters are translated from ASCII to EBCDIC.
		For the allowed characters for the other fields, see the description of the corresponding Set_ call. For example, for the mode_name field, see the description of the Set_Mode_Name call. Each field in the structure must be left-justified. Pad fields on the right with spaces as necessary.
side_info_entry _length		Supplied parameter; specifies the length of side_info_entry. It is always 124.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

A value specified in the side_info_entry structure is invalid.

The left character of the side_info_entry contains a space.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state.

There is no state change.

Remarks

Invalid string parameters in the side information (for example, specifying a non-existent partner LU) are not detected until Allocate is issued. The error is returned on a call following Allocate.


Set_Deallocate_Type (cmsdt)
CPI-C Calls	34 of 50

Set_Deallocate_Type (cmsdt)

Specifies how the conversation is to be deallocated.

Syntax

conversation_ID	unsigned char far *
deallocate_type	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
deallocate_type	Supplied parameter; specifies how to perform the deallocation. The following are possible values: CM_DEALLOCATE_ABEND indicates that the conversation is to be deallocated abnormally, unconditionally. A program should specify CM_DEALLOCATE_ABEND when it encounters an error preventing the successful completion of a transaction. If the conversation is in SEND state, CPI-C sends the contents of the local LU’s send buffer to the partner program before deallocating the conversation. If the conversation is in RECEIVE state, incoming data can be purged. For  a Basic conversation in SEND state, logical record truncation can occur. CM_DEALLOCATE_CONFIRM is used to send the partner program the contents of the local LU’s send buffer and a request to confirm the deallocation. This request for deallocation confirmation is sent by Deallocate or by Send_Data with the send type set to CM_SEND_AND_DEALLOCATE. The conversation is deallocated normally when the partner program issues Confirmed, responding to the confirmation request.
	CM_DEALLOCATE_FLUSH is used to send the contents of the local LU’s send buffer to the partner program before deallocating the conversation normally.
	CM_DEALLOCATE_SYNC_LEVEL uses the conversation’s synchronization level to determine how to deallocate the conversation. A default synchronization level is established by Initialize_Conversation and can be overridden by Set_Sync_Level. If the synchronization level of the conversation is CM_NONE, the default, and the contents of the local LU’s send buffer are sent to the partner program and the conversation is deallocated normally. If the synchronization level of the conversation is CM_CONFIRM, the contents of the local LU’s send buffer and a request to confirm the deallocation are sent to the partner program. This request for deallocation confirmation is sent by Deallocate or by Send_Data with the send type set to CM_SEND_AND_DEALLOCATE. The conversation is deallocated normally when the partner program issues the Confirmed call, responding to the confirmation request.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID or deallocate_type is invalid.

The deallocate_type parameter specifies CM_DEALLOCATE_ CONFIRM, but the conversation’s synchronization level is set to CM_NONE.

The address of a variable is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.

Remarks

This call overrides the default deallocate type established by Initialize_Conversation or Accept_Conversation. The default deallocate type is CM_DEALLOCATE_SYNC_LEVEL.

The deallocation instructions specified by this call take effect when Deallocate is issued or when the send type is set to CM_SEND_AND_ DEALLOCATE and Send_Data is issued.

You can set deallocate_type to CM_FLUSH if the synchronization level of the conversation is set to CM_NONE or CM_CONFIRM.

The value CM_DEALLOCATE_FLUSH is functionally the same as CM_ DEALLOCATE_SYNC_LEVEL with the conversation’s synchronization level set to CM_NONE.

The value CM_DEALLOCATE_CONFIRM is functionally the same as CM_DEALLOCATE_SYNC_LEVEL with the conversation’s synchronization level set to CM_CONFIRM.


Set_Error_Direction (cmsed)
CPI-C Calls	35 of 50

Set_Error_Direction (cmsed)

Specifies whether a program detected an error while receiving data or while preparing to send data.

Syntax

conversation_ID	unsigned char far *
error_direction	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
error_direction	Supplied parameter; specifies the direction in which data was flowing when the program encountered an error. The following are possible values: CM_RECEIVE_ERROR indicates that an error occurred in the data received from the partner program. CM_SEND_ERROR indicates that an error occurred while the local program prepared to send data to the partner program.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID or error_direction is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.

Remarks

This call overrides the default error direction established by Initialize_Conversation or Accept_Conversation. The default error direction is CM_RECEIVE_ERROR.

Error direction is relevant only when a program issues Send_Error in SEND-PENDING state—immediately after issuing Receive and receiving data (data_received is a value other than CM_NO_DATA_RECEIVED) and a send indicator (status_received is CM_SEND_RECEIVED).

When the conversation is in SEND-PENDING state, the program issues Send_Error if it detects errors in the received data or if an error occurred while the local program prepared to send data. The program must supply the error direction information using Set_Error_Direction before issuing Send_Error because the LU cannot tell which kind of error occurred (receive or send). The new error direction remains in effect until a subsequent Set_Error_Direction changes it.

When Send_Error is issued, the partner program receives one of the following return codes:

CM_PROGRAM_ERROR_PURGING if error_direction is set to CM_RECEIVE_ERROR

CM_PROGRAM_ERROR_NO_TRUNC if error_direction is set to CM_SEND_ERROR


Set_Fill (cmsf)
CPI-C Calls	36 of 50

Set_Fill (cmsf)

Specifies whether programs will receive data in the form of logical records or as a specified length of data. This call is allowed only in Basic conversations.

Syntax

conversation_ID	unsigned char far *
fill	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
fill	Supplied parameter; specifies the form in which programs will receive data. The following are possible choices: CM_FILL_BUFFER indicates that the local program receives data until the number of bytes specified by the requested_length parameter of the Receive call is reached or until the end of the data. Data is received without regard for the logical-record format. CM_FILL_LL indicates that data is received in logical-record format. The data received can be a complete logical record, a portion of a logical record equal to the requested_length parameter of the Receive call, or the end of a logical record.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID or fill is invalid.

The current conversation is Mapped.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.

Remarks

Set_Fill overrides the default fill established by Initialize_Conversation or Accept_Conversation. The default fill is CM_FILL_LL.

The fill value affects all subsequent Receive calls. It can be changed by reissuing the Set_Fill call.


Set_Log_Data (cmsld)
CPI-C Calls	37 of 50

Set_Log_Data (cmsld)

Specifies a log message (log data) and its length to be sent to the partner LU. This call is allowed only in Basic conversations. It overrides the default log data, which is null, and the default log data length, which is 0.

Syntax

conversation_ID	unsigned char far *
log_data	unsigned char far *
log_data_length	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
log_data	Supplied parameter; specifies the starting address of the data to be sent to the partner LU. It can contain up to 512 ASCII characters. The allowed characters are: Uppercase and lowercase letters. Numerals 0 through 9. Special characters. The space.
log_data_length	Supplied parameter; specifies the length of the log data. The range is from 0 through 512 bytes. A length of 0 indicates that there is no log data, and the log_data parameter is ignored.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID is invalid.

The conversation type is set to Mapped.

The value specified by log_data_length is out of range (greater than 512 or less than 0).

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.

Remarks

The log data specified by Set_Log_Data is sent to the partner LU when the local program issues one of the following calls:

Send_Error

Deallocate with the conversation’s deallocate type set to CM_DEALLOCATE_ABEND

Send_Data with the conversation’s send type set to CM_SEND_AND_DEALLOCATE and the deallocate type set to CM_ DEALLOCATE_ABEND

After sending the log data to the partner LU, the local LU resets the log data to null and the log data length to 0.

CPI-C automatically converts the log data from ASCII to other encoding standards, such as EBCDIC, as required.


Set_Mode_Name (cmsmn)
CPI-C Calls	38 of 50

Set_Mode_Name (cmsmn)

Issued by the invoking program to specify the mode name for a conversation. This call overrides the system-defined mode name derived from the side information when the Initialize_Conversation call was issued. This call cannot be issued after Allocate has been issued. Issuing this call has no effect on the side information itself.

Syntax

conversation_ID	unsigned char far *
mode_name	unsigned char far *
mode_name_length	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.
mode_name	Supplied parameter; specifies the starting address of the mode name (the name of a set of networking characteristics defined during configuration). The mode name can contain up to eight ASCII characters. The allowed characters are: Uppercase letters. Numerals 0 through 9. The value of mode_name must match the name of a mode associated with the partner LU during configuration. The mode name cannot be SNASVCMG or CPSVCMG.
mode_name_length	Supplied parameter; specifies the length of the mode name. The range is from 0 through 8 bytes If mode_name_length is set to 0, Set_Mode_Name is ignored.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation is not in INITIALIZE state.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID is invalid.

The value specified by mode_name_length is out of range (greater than 8 or less than 0).

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.

Remarks

Specifying an invalid value for mode_name is not detected until Allocate is issued.


Set_Partner_LU_Name (cmspln)
CPI-C Calls	39 of 50

Set_Partner_LU_Name (cmspln)

Issued by the invoking program to specify the partner LU name. This call overrides the partner LU name derived from the side information when the Initialize_Conversation call was issued. This call cannot be issued after Allocate has been issued. Issuing this call has no effect on the side information itself.

Syntax

conversation_ID		unsigned char far *
partner_LU_name		unsigned char far *
partner_LU_name_length		signed long int far *
return_code		signed long int far *
Parameter		Description
conversation_ID		Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.
partner_LU_name		Supplied parameter; specifies the starting address of the partner LU name. The mode name can contain up to 17 ASCII characters. The allowed characters are: Uppercase letters. Numerals 0 through 9. The partner LU name can be either: An alias consisting of one through eight characters. A fully qualified network name consisting of from 2 through 17 characters. A period separates the network ID (which can be from zero through eight characters) from the network LU name (which can be from one through eight characters). If the network ID is 0 characters long, the period is still required. The partner LU name must match the name of a partner LU established during configuration.
partner_LU_name_length		Supplied parameter; specifies the length of the partner LU name. The range is from 1 through 17.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation is not in INITIALIZE state.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID is invalid.

The value specified by partner_LU_name_length is out of range (greater than 17 or less than 1).

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.

Remarks

Specifying an invalid value for partner_LU_name is not detected until Allocate is issued.


Set_Prepare_To_Receive_Type (cmsptr)
CPI-C Calls	40 of 50

Set_Prepare_To_Receive_Type (cmsptr)

Specifies how the subsequent Prepare_To_Receive calls will be executed. It overrides the default prepare-to-receive processing established by Initialize_Conversation or Accept_Conversation. By default, the prepare-to-receive processing is based on the synchronization level of the conversation.

The prepare-to-receive type affects all subsequent Prepare_To_Receive calls. It can be changed by reissuing Set_Prepare_To_Receive_Type.

Syntax

conversation_ID		unsigned char far *
prepare_to_receive_type		signed long int far *
return_code		signed long int far *
Parameter		Description
conversation_ID		Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
prepare_to_receive_type		Supplied parameter; specifies how subsequent Prepare_To_Receive calls will be executed. The following are possible values: CM_PREP_TO_RECEIVE_CONFIRM is used to send the partner program the contents of the LU’s send buffer and a confirmation request. Upon receipt of confirmation, the conversation changes to RECEIVE state. CM_PREP_TO_RECEIVE_FLUSH is used to send the partner program the contents of the local LU’s send buffer and changes the conversation to RECEIVE state.
		CM_PREP_TO_RECEIVE_SYNC_LEVEL is used by the conversation’s synchronization level to determine prepare-to-receive processing. A default synchronization level is established by Initialize_Conversation and can be overridden by Set_Sync_Level. If the synchronization level of the conversation is CM_NONE, the default, the contents of the local LU’s send buffer are sent to the partner program and the conversation changes to RECEIVE state. If the synchronization level of the conversation is CM_CONFIRM, the contents of the local LU’s send buffer and a request for confirmation are sent to the partner program. The conversation changes to RECEIVE state when the partner program issues Confirmed, responding to the confirmation request.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by prepare_to_receive_type or conversation_ID is invalid.

The prepare_to_receive_type parameter is set to CM_PREP_TO_ RECEIVE_CONFIRM, but the conversation’s synchronization level is set to CM_NONE.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.


Set_Processing_Mode (cmspm)
CPI-C Calls	41 of 50

Set_Processing_Mode (cmspm)

Specifies for the conversation whether subsequent calls will be returned when the operation they have requested is complete (blocking) or immediately after the operation is initiated (nonblocking).

Note

A program is notified of the completion of nonblocking calls when it issues Wait_For_Conversation or through a Windows message sent to a WNDPROC identified by the HWND in the Specify_Windows_Handle call.

Syntax

conversation_ID	unsigned char far *
receive_type	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
receive_type	Supplied parameter; specifies whether subsequent calls on the conversation will be blocking or nonblocking. Possible values are: CM_BLOCKING indicates that subsequent calls will return only when the operation is complete. CM_NON_BLOCKING indicates that subsequent calls will return immediately once the operation has been initiated.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_STATE_CHECK

Primary return code; the previous incomplete operation on the conversation has not yet completed.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID or processing_mode is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.

See Also

Specify_Windows_Handle (xchwnd)

Wait_For_Conversation (cmwait)


Set_Receive_Type (cmsrt)
CPI-C Calls	42 of 50

Set_Receive_Type (cmsrt)

Specifies how the program will receive data on subsequent Receive calls. It overrides the default receive type established by the Initialize_Conversation or Accept_Conversation call. By default, the program waits for data to arrive if it is not available when the Receive call is issued.

The receive type value affects all subsequent Receive calls. It can be changed by reissuing Set_Receive_Type.

Syntax

conversation_ID	unsigned char far *
receive_type	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
receive_type	Supplied parameter; specifies how data is to be received by the program on the subsequent Receive calls. The following are possible values: CM_RECEIVE_AND_WAIT specifies that the local program receives any data that is currently available from the partner program. If no data is currently available, the local program waits for data to arrive. CM_RECEIVE_IMMEDIATE specifies that the local program receives any data currently available from the partner program. If no data is available, the local program does not wait.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID or receive_type is invalid, or the address of a variable is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.


Set_Return_Control (cmsrc)
CPI-C Calls	43 of 50

Set_Return_Control (cmsrc)

Issued by the invoking program to specify when the local LU, acting on the session request from the local program’s Allocate call, should return control to the local program.

Syntax

conversation_ID	unsigned char far *
return_control	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.
return_control	Supplied parameter; specifies when the local LU, acting on the Allocate call, should return control to the local program. The following are allowed values: CM_IMMEDIATE indicates that the LU allocates a contention-winner session, if one is immediately available, and returns control to the program. CM_WHEN_SESSION_ALLOCATED indicates that the LU does not return control to the program until it allocates a session or encounters errors. If a session is not available, the program waits for one. (If the session limit is 0, the LU returns control immediately.)
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation is not in INITIALIZE state.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID or return_control is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.

Remarks

This call overrides the default return control established by Initialize_Conversation. By default, control is returned when the session is allocated. This call cannot be issued after the Allocate call has been issued.

For further information about sessions, see Chapter 2, "Writing CPIC Applications."

If the LU is unable to allocate a session, the notification is returned on the Allocate call.


Set_Send_Type (cmsst)
CPI-C Calls	44 of 50

Set_Send_Type (cmsst)

Specifies how data will be sent by the next Send_Data call. It overrides the default send type established by Initialize_Conversation or Accept_Conversation. The default send type is CM_BUFFER_DATA, indicating that data only (and no control information) is to be sent.

The send_type value affects all subsequent Send_Data calls. It can be changed by reissuing Set_Send_Type.

Syntax

conversation_ID	unsigned char far *
send_type	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
send_type	Supplied parameter; specifies how data is sent by the next Send_Data call. The following are possible values: CM_BUFFER_DATA indicates that the data pointed to by Send_Data is stored in a buffer until the buffer fills up or is flushed. CM_SEND_AND_FLUSH indicates that the data pointed to by Send_Data is to be sent immediately. CM_SEND_AND_CONFIRM indicates that the data is to be sent immediately with a request for confirmation. CM_SEND_AND_PREP_TO_RECEIVE indicates that the data is to be sent immediately along with notification to the partner program that the conversation state for the sending program is changing to RECEIVE. CM_SEND_AND_DEALLOCATE indicates that the data is to be sent immediately along with deallocation notification.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID or send_type is invalid.

The send_type parameter is set to CM_SEND_AND_CONFIRM, but the conversation’s synchronization level is set to CM_NONE.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation can be in any state except RESET.

There is no state change.

Remarks

The send_type values that cause additional information to be sent with the data pointed to by Send_Type let you economize on the number of calls issued. The following table summarizes Send_Data equivalences.

Send_Data with send_type set to this value	Equates to Send_Data with send_type set to CM_BUFFER_DATA followed by
CM_SEND_AND_FLUSH	Flush
CM_SEND_AND_CONFIRM	Confirm
CM_SEND_AND_PREP_TO_RECEIVE	Prepare_To_Receive
CM_SEND_AND_DEALLOCATE	Deallocate


Set_Sync_Level (cmssl)
CPI-C Calls	45 of 50

Set_Sync_Level (cmssl)

Issued by the invoking program to specify the synchronization level of the conversation. The synchronization level determines whether the programs synchronize their processing through the Confirm and Confirmed calls.

This call overrides the synchronization level established by the Initialize_Conversation call. The default synchronization level is CM_NONE, indicating no synchronization. This call cannot be issued after the Allocate call has been issued.

Syntax

conversation_ID	unsigned char far *
sync_level	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.
sync_level	Supplied parameter; specifies the synchronization level of the conversation. The following are possible values: CM_NONE indicates that the programs will not perform confirmation processing. CM_CONFIRM indicates that the programs can perform confirmation processing.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation is not in INITIALIZE state.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID or sync_level is invalid.

The sync_level parameter specifies CM_NONE but one of the following has occurred: the send_type parameter is set to CM_SEND_AND_CONFIRM, or the prepare_to_receive_type parameter is set to CM_PREP_TO_RECEIVE_CONFIRM, or the deallocate_type is set to CM_DEALLOCATE_CONFIRM.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.


Set_TP_Name (cmstpn)
CPI-C Calls	46 of 50

Set_TP_Name (cmstpn)

Issued by the invoking program to specify the partner (invokable) program name. This call overrides the partner program name derived from the side information when the Initialize_Conversation call was issued. This call cannot be issued after the Allocate call has been issued. Issuing this call has no effect on the side information itself.

Syntax

conversation_ID	unsigned char far *
TP_name	unsigned char far *
TP_name_length	signed long int far *
return_code	signed long int far *
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.
TP_name	Supplied parameter; specifies the starting address of the partner program name. The program name can contain up to 64 ASCII characters. The allowed characters are: Uppercase and lowercase letters. Numerals 0 through 9. Special characters, except the space. You cannot use Set_TP_Name to specify the name of an SNA service TP. You can, however, use Set_CPIC_Side_Information to do this. Double-byte character sets, such as Kanji, are not supported.
TP_name_length	Supplied parameter; specifies the length of the partner program name. The range is from 1 through 64.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation is not in INITIALIZE state.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The value specified by conversation_ID is invalid.

The value specified by TP_name_length is out of range (greater than 64 or less than 1).

The address of a variable is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.


Specify_Local_TP_Name (cmsltp)
CPI-C Calls	47 of 50

Specify_Local_TP_Name (cmsltp)

Issued by the program to indicate that it is able to accept incoming conversations that are directed to the name given.

Syntax

TP_name	unsigned char far *
TP_name_length	signed long int far *
return_code	signed long int far *
Parameter	Description
TP_name	Supplied parameter; specifies the starting address of the local TP name. The program name can contain up to 64 ASCII characters. The allowed characters are: Uppercase and lowercase letters. Numerals 0 through 9. Special characters, except the space. You cannot use Specify_Local_TP_Name to specify the name of an SNA service TP. Double-byte character sets, such as Kanji, are not supported.
TP_name_length	Supplied parameter; specifies the length of the local program name. The range is from 1 through 64.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; one of the following occurred:

The TP_name supplied is invalid.

The value specified by TP_name_length is out of range (greater than 64 or less than 1).

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The call is not associated with a particular conversation, and so no state restrictions apply.

There is no state change.

Remarks

A program can issue this call more than once in order to handle incoming conversations with more than one TP name. The program can discover the actual name on the incoming conversation by calling Extract_TP_Name.


Specify_Windows_Handle (xchwnd)
CPI-C Calls	48 of 50

Specify_Windows_Handle (xchwnd)

Sets the Windows handle to which a message is sent on completion of an operation in nonblocking mode.

Syntax

hwndNotify	hwnd
return_code	signed long int far *
Parameter	Description
hwndNotify	Supplied parameter; specifies the Windows handle to be notified when the outstanding operation completes.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

The Windows handle is invalid.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The state change is dependent on the operation that completed and its return code.

Remarks

An application can set the processing mode by calling Set_Processing_Mode. If the Windows handle is set to NULL, or this call is never issued, then the application must call Wait_For_Conversation to be notified when the outstanding operation completes.

When an asynchronous operation is complete, the application’s window hwndNotify receives the message returned by RegisterWindowMessage with "WinAsyncCPI-C" 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 lParam argument contains the CM_PTR to the conversation_ID specified in the original function call.

See Also

Set_Processing_Mode (cmspm)

Wait_For_Conversation (cmwait)


Test_Request_To_Send_Received (cmtrts)
CPI-C Calls	49 of 50

Test_Request_To_Send_Received (cmtrts)

Determines whether a request-to-send notification has been received from the partner program.

Syntax

conversation_ID	unsigned char far *
request_to_send_received	signed long int far *
return_code	signed long int far
Parameter	Description
conversation_ID	Supplied parameter; specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
request_to_send_received	Returned parameter; the request-to-send-received indicator. The following are possible values: CM_REQ_TO_SEND_RECEIVED indicates that the partner program issued Request_To_Send, which requests the local program to change the conversation to RECEIVE state. CM_REQ_TO_SEND_NOT_RECEIVED indicates that the partner program has not issued Request_To_Send. This value is not relevant if return_code contains a value other than CM_OK.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_PROGRAM_PARAMETER_CHECK

Primary return code; the value specified by conversation_ID is invalid, or the address of a variable is invalid.

CM_PROGRAM_STATE_CHECK

Primary return code; the conversation is in a state other than SEND, RECEIVE, or SEND-PENDING.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error occurred and has been logged in the product’s error log.

State Changes

The conversation must be in SEND, RECEIVE, or SEND-PENDING state.

There is no state change.


Wait_For_Conversation (cmwait)
CPI-C Calls	50 of 50

Wait_For_Conversation (cmwait)

Waits for an operation to complete that has been initiated when the processing_mode conversation characteristic was set to CM_NON_BLOCKING and CM_OPERATION_INCOMPLETE was returned in the return_code parameter.

Syntax

conversation_ID		unsigned char far *
conversation_return_code		signed long int far *
return_code		signed long int far *
Parameter		Description
conversation_ID		Returned parameter; specifies the identifier for the conversation on which the operation completed. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.
conversation_return_code		Returned parameter; specifies the return_code from the operation that is completing. Its values will depend on which operation was originally issued.
Return Codes

CM_OK

Primary return code; the call executed successfully.

CM_SYSTEM_EVENT

Primary return code; the wait completed not because the operation completed but because some system event occurred.

CM_PROGRAM_STATE_CHECK

Primary return code; the program has no incomplete operation outstanding.

CM_PRODUCT_SPECIFIC_ERROR

Primary return code; a product-specific error has occurred and has been logged in the product’s error log.

State Changes

The state change is dependent on the operation that completed and its return code.

Remarks

The program must have an incomplete operation outstanding on some conversation.

See Also

Set_Processing_Mode (cmspm)

Specify_Windows_Handle (xchwnd)


Extensions for the Windows Environment
Chapter 4	1 of 6

Extensions for the Windows Environment

This chapter describes API extensions to the Windows CPI-C that allow asynchronous verb completion. Asynchronous verbs return control to the program immediately but complete later — posting a message to a Windows handle or in response to a Wait_For_Conversation call upon completion. Contrast this with synchronous verbs that block. In this case, the function call doesn’t return until the call has completed.

The extensions described in this chapter have been designed for all implementations and versions of the Microsoft Windows graphical environment version 3.0 and later. They provide support for maximum Windows programming compatibility and optimum application performance in both 16bit and 32bit operating environments.

Windows CPI-C allows multithreaded Windows-based processes. Multithreading is the running of several processes in rapid sequence within a single program. A process contains one or more threads of execution. The 16bit Windows environment is not multithreaded. In this instance, a task corresponds to a process with a single thread. All references to threads in this document refer to actual threads in multithreaded Windows environments.

The extensions described in this chapter provide a definition of the function, syntax, returns, and remarks for using the extension.


WinCPICCleanup( )
Extensions for the Windows Environment	2 of 6

WinCPICCleanup( )

Terminates and deregisters an application from a Windows CPI-C implementation.

Syntax

BOOL WINAPI WinCPICCleanup (void)

Returns

The return value specifies whether the deregistration was successful. If the value is not 0, the application was successfully deregistered. The application was not deregistered if a value of 0 is returned.

Use WinCPICCleanup to indicate deregistration of a Windows CPI-C application from a Windows CPI-C implementation.


WinCPICIsBlocking( )
Extensions for the Windows Environment	3 of 6

WinCPICIsBlocking( )

Determines if a task is executing while waiting for a previous blocking call to finish.

Syntax

BOOL WINAPI WinCPICIsBlocking (void)

Returns

The return value specifies the outcome of the function. If the value is not 0, there is an outstanding blocking call awaiting completion. A value of 0 indicates the absence of an outstanding blocking call.

Remarks

This call does not infer any information about a particular conversation; it is only intended to provide help to an application written to use the CM_BLOCKING characteristic of Set_Processing_Mode. WinCPICIsBlocking serves the same purpose as InSendMessage in the Windows API. Applications targeted at Windows version 3.x that support multiple conversations must specify CM_NONBLOCKING in Set_Processing_Mode so they can support multiple outstanding operations simultaneously. Applications are still limited to one outstanding operation per conversation in all environments.

Although a call issued on a blocking function appears to an application as though it blocks, the Windows CPI-C DLL has to relinquish the processor to allow other applications to run. This means that it is possible for the application that issued the blocking call to be re-entered, depending on the message(s) it receives. In this instance, WinCPICIsBlocking can be used to determine whether the application task currently has been re-entered while waiting for an outstanding blocking call to finish. Note that Windows CPI-C prohibits more than one outstanding blocking call per thread.

See Also

Set_Processing_Mode (cmspm)

Specify_Windows_Handle (xchwnd)

WinCPICSetBlockingHook( )

WinCPICUnhookBlockingHook( )


WinCPICStartup( )
Extensions for the Windows Environment	4 of 6

WinCPICStartup( )

Allows an application to specify the version of Windows CPI-C required and to retrieve details of the specific Windows CPI-C implementation. This function must be called by an application before issuing any further Windows CPI-C calls to register itself with a Windows CPI-C implementation.

Syntax

BOOL WINAPI WinCPICStartup (WORD wVersionRequired, LPWCPICDATA)

Parameter	Description
wVersionRequired	Specifies the version of Windows CPI-C support required. The high-order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.
Returns

The return value specifies whether the application was registered successfully and whether the Windows CPI-C implementation can support the specified version number. If the value is 0, it was registered successfully. Otherwise, the return value is one of the following:

WCPICSYSNOTRERADY

The underlying network subsystem is not ready for network communication.

WCPICVERNOTSUPPORTED

The version of Windows CPI-C support requested is not provided by this particular Windows CPI-C implementation.

WCPICINVALID

The Windows CPI-C version specified by the application is not supported by this DLL.

Remarks

In order to support future Windows CPI-C implementations and applications that may have functionality differences from Windows CPI-C version 1.0, a negotiation takes place in WinCPICStartup. An application passes to WinCPICStartup the Windows CPI-C version that it can use. If this version is lower than the lowest version supported by the Windows CPI-C DLL, the DLL cannot support the application and the WinCPICStartup call fails. If the version is not lower, however, the call succeeds and returns the highest version of Windows CPI-C supported by the DLL. If this version is lower than the lowest version supported by the application, the application either fails its initialization or attempts to find another Windows CPI-C DLL on the system.

This negotiation allows both a Windows CPI-C DLL and a Windows CPI-C application to support a range of Windows CPI-C versions. An application can successfully use a DLL if there is any overlap in the versions. The following table illustrates how WinCPICStartup works in conjunction with different application and DLL versions.

Application versions	DLL versions	To WinCPICStartup		From WinCPICStartup		Result
1.0	1.0	1.0		1.0		Use 1.0
1.0, 2.0	1.0	2.0		1.0		Use 1.0
1.0	1.0, 2.0	1.0		2.0		Use 1.0
1.0	2.0, 3.0	1.0		WCPICINVALID		Fail
2.0, 3.0	1.0	3.0		1.0		App Fails
1.0, 2.0, 3.0	1.0, 2.0, 3.0	3.0		3.0		Use 3.0
Details of the actual Windows CPI-C implementation are described in the WHLLDATA structure defined as follows:

typedef struct tagWCPICDATA { WORD wVersion;

char szDescription[WHLLDESCRIPTION_LEN+1];

} WCPICDATA, FAR *LPWCPICDATA;

Having made its last Windows CPI-C call, an application should call the WinCPICCleanup routine.

Each Windows CPI-C implementation must make a WinCPICStartup call before issuing any other Windows CPI-C calls.


WinCPICSetBlockingHook( )
Extensions for the Windows Environment	5 of 6

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. By default in the Windows NT system, blocking calls suspend the calling application’s thread until the request is finished. Therefore, if a single-threaded application is targeted at both the Windows version 3.x and Windows NT systems, and relies on this functionality, it should register a blocking hook even if the default hook will suffice.

Syntax

FARPROC WINAPI WinCPICSetBlockingHook (FARPROC 1pBlockFunc)

Parameter	Description
lpBlockFunc	Specifies the procedure instance address of the blocking function to be installed.
Returns

The return value points to the procedure instance of the previously installed blocking function. The application or library that calls the SetBlockingHook function should save this return value so that it can be restored if needed. (If nesting is not important, the application can simply discard the value returned by WinCPICSetBlockingHook and eventually use WinCPICUnhookBlocking-Hook to restore the default mechanism.)

Remarks

A Windows CPI-C implementation has a default mechanism by which blocking CPI-C functions are implemented. This function gives the application the ability to execute its own function at blocking time in place of the default function.

The default blocking function is equivalent to:

BOOL DefaultBlockingHook (void)  {

MSG msg;

/* get the next message if any */

if ( PeekMessage (&msg,0,0,PM_NOREMOVE)  )  {

if ( msg.message = = WM_QUIT  )

return FALSE;   // let app process WM_QUIT

PeekMessage (&msg,0,0,PM_REMOVE) ;

TranslateMessage (&msg) ;

DispatchMessage (&msg) ;

}

/* TRUE if no WM_QUIT received */

return TRUE;

}

The WinCPICSetBlockingHook function is provided to support applications that require more complex message processing — for example, those employing the multiple document interface (MDI) model or applications with Menu accelerators (TranslateAccelerator).

Blocking functions must return FALSE in response to a WM_QUIT message so Windows CPI-C can return control to the application to process the message and terminate gracefully. Otherwise, the function should return TRUE.

See Also

Set_Processing_Mode (cmspm)

Specify_Windows_Handle (xchwnd)

WinCPICUnhookBlockingHook( )


WinCPICUnhookBlockingHook( )
Extensions for the Windows Environment	6 of 6

WinCPICUnhookBlockingHook( )

Removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism.

Syntax

BOOL WINAPI WinCPICUnhookBlockingHook (void)

Returns

The return value specifies the outcome of the function. It is not 0 if the default mechanism is successfully reinstalled. The value is 0 if the mechanism did not reinstall.

See Also

WinCPICSetBlockingHook( )


Common Return Codes
Appendix A	1 of 1

Common Return Codes

This appendix describes the return codes for CPI-C calls. The return codes are listed in integer order.

Call-specific return codes are described for the individual calls in Chapter 3, "CPI-C Calls."

0

CM_OK

The call executed successfully.

1

CM_ALLOCATION_FAILURE_NO_RETRY

The conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

2

CM_ALLOCATION_FAILURE_RETRY

The conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

3

CM_CONVERSATION_TYPE_MISMATCH

The partner LU or program does not support the conversation type (Basic or Mapped) specified in the allocation request.

5

CM_PIP_NOT_SPECIFIED_CORRECTLY

The allocation request was rejected by a non–CPI-C LU 6.2 TP. The partner program requires one or more PIP data variables, which are not supported by CPI-C.

6

CM_SECURITY_NOT_VALID

The user ID or password specified in the allocation request was not accepted by the partner LU.

8

CM_SYNC_LVL_NOT_SUPPORTED_PGM

The partner program does not support the synchronization level specified in the allocation request.

9

CM_TPN_NOT_RECOGNIZED

The partner LU does not recognize the program name specified in the allocation request.

10

CM_TP_NOT_AVAILABLE_NO_RETRY

The partner LU cannot start the program specified in the allocation request because of a permanent condition. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

11

CM_TP_NOT_AVAILABLE_RETRY

The partner LU cannot start the program specified in the allocation request because of a temporary condition. The reason for the error may be logged on the remote node. Retry the allocation.

17

CM_DEALLOCATED_ABEND

The conversation has been deallocated for one of the following reasons:

The remote program issued Deallocate with the type parameter set to CM_DEALLOCATE_ABEND. If the conversation for the remote program was in Receive state when the call was issued, information sent by the local program and not yet received by the remote program is purged.

The partner program terminated normally but did not deallocate the conversation before terminating.

18

CM_DEALLOCATED_NORMAL

This return code does not indicate an error.

The partner program issued the Deallocate call with deallocate_type set to one of the following:

CM_DEALLOCATE_FLUSH.

CM_DEALLOCATE_SYNC_LEVEL with the synchronization level of the conversation specified as CM_NONE.

19

CM_PARAMETER_ERROR

The local program specified an invalid argument in one of its parameters.

20

CM_PRODUCT_SPECIFIC_ERROR

A product-specific error occurred and has been logged in the product’s error log.

21

CM_PROGRAM_ERROR_NO_TRUNC

While in SEND state or in SEND-PENDING state with the error direction set to CM_SEND_ERROR, the partner program issued Send_Error. Data was not truncated.

22

CM_PROGRAM_ERROR_PURGING

One of the following occurred:

While in RECEIVE or CONFIRM state, the partner program issued Send_Error. Data sent but not yet received is purged.

While in SEND-PENDING state with the error direction set to CM_RECEIVE_ERROR, the partner program issued Send_Error. Data was not purged.

23

CM_PROGRAM_ERROR_TRUNC (for a Basic conversation)

In SEND state, before finishing sending a complete logical record, the partner program issued Send_Error. The local program may have received the first part of the logical record through a Receive call.

24

CM_PROGRAM_PARAMETER_CHECK

A parameter or the address of a variable is invalid. For details, see individual calls in Chapter 3, "CPI-C Calls."

25

CM_PROGRAM_STATE_CHECK

The call was not issued in an allowed conversation state. For details, see individual calls in Chapter 3, "CPI-C Calls."

26

CM_RESOURCE_FAILURE_NO_RETRY

One of the following occurred:

The conversation was terminated prematurely because of a permanent condition. Do not retry until the error has been corrected.

The partner program did not deallocate the conversation before terminating normally.

27

CM_RESOURCE_FAILURE_RETRY

The conversation was terminated prematurely because of a temporary condition, such as modem failure. Retry the conversation.

28

CM_UNSUCCESSFUL

The verb issued by the local program was not executed successfully.

30

CM_DEALLOCATED_ABEND_SVC

The conversation has been deallocated for one of the following reasons:

The partner program issued Deallocate with the type parameter set to ABEND_SVC.

The partner program did not deallocate the conversation before terminating.

If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

31

CM_DEALLOCATED_ABEND_TIMER

The conversation has been deallocated because the partner program issued Deallocate with the type parameter set to ABEND_TIMER. If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

32

CM_SVC_ERROR_NO_TRUNC (for a Basic conversation)

While in SEND state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC. Data was not truncated.

33

CM_SVC_ERROR_PURGING

While in SEND state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC. Data sent to the partner program may have been purged.

34

CM_SVC_ERROR_TRUNC (for a Basic conversation)

While in RECEIVE or CONFIRM state, the partner program (or partner LU) issued Send_Error with the type parameter set to SVC before it finished sending a complete logical record. The local program may have received the first part of the logical record.

CM_NOT ACCEPTED

A previous operation on this conversation is incomplete.

CM_OPERATION_INCOMPLETE

The operation has not completed and is still in progress. The program can issue WAIT_FOR_CONVERSATION to await the completion of the operation, or CANCEL_CONVERSATION to cancel the operation (and conversation). If Specify_Windows_Handle has been called, the application should wait for notification by a windows message and not call Wait_For_Conversation.


Sample CPI-C TPs in the SDK
Appendix B	1 of 8

Sample CPI-C TPs in the SDK

This chapter describes the CPI-C TP samples in the SNA Server SDK. The samples are located in the \SDK\SAMPLES directory on the SNA Server CD.

TP	Description
APING and APINGD	End-to-end connectivity testers
Multithreaded APINGD	Multithreaded connectivity tester that illustrates nonqueued behavior in Windows NT
CPI-C Send and Receive TPs	Simple CPI-C TPs that illustrate the use of asynchronous CPI-C calls
AREXEC and AREXECD	TPs that execute commands on a remote computer and send the output back across the connection
In addition to the TPs, the following supplemental programs are included on the SNA Server CD.

Supplemental program	Description
TPSETUP	Sample installation program, demonstrating an interface that assists in the configuring of autostarted invokable TPs. Located in the \SAMPLES\SDK directory on the CD.
TPSTART	A program required by autostarted invokable TPs that run as applications under Windows NT; installed by SNA Server Setup in the SYSTEM subdirectory of the SNA Server root directory.


Building the TPs
Sample CPI-C TPs in the SDK	2 of 8

Building the TPs

All the sample TPs are built in a similar way, as described in this section. First, set the following environment variables:

Variable	Specify
ISVLIBS	Directory containing the SNA Server Windows NT .LIB files
ISVINCS	Directory containing the WINSNA header files
SAMPLEROOT	Root directory of the sample code
For example, if the two SDK disks are copied with XCOPY into C:\SNASDK, use the following lines to set the variables:

ISVLIBS=C:\SNASDK\WINSNA\LIB\WINNT

ISVINCS=C:\SNASDK\WINSNA\INC

SAMPLEROOT=C:\SNASDK\SAMPLES

Next, run NMAKE on the .MAK file in each directory. For example, for APING and APINGD, type the following:

nmake -f makeping.mak


TPSETUP
Sample CPI-C TPs in the SDK	3 of 8

Building the TPs

TPSETUP

TPSETUP is a program that simplifies the setting of Registry or environment variables needed by autostarted invokable TPs. Without an interface like that provided by TPSETUP, configuring of such variables can be complicated and errorprone. Therefore, it is recommended that you use code like TPSETUP in installation programs for autostarted invokable TPs.

Operation

INSTALL.C, the source code for TPSETUP, can be compiled to work either in the Windows NT environment or in the Windows version 3.x environment. TPSETUP has been constructed so that the program responds correctly in each environment.

For clients running Windows NT, it is recommended that autostarted invokable TPs be written as Windows NT services. For the installation program for such TPs, study the code in INSTALL.C. For example, use the CreateService function or similar code when installing a TP that will run as a service under Windows NT. (For important information about how services work under Windows NT, see the documentation for Windows NT and for Win32 [image].)


TPSTART
Sample CPI-C TPs in the SDK	4 of 8

Building the TPs

TPSTART

An autostarted TP that runs as an application under Windows NT requires the support of the TPSTART program, which is installed with the SNA Server software in the SYSTEM subdirectory of the SNA Server root directory. Therefore, the TPSTART program must be started on a Windows NT-based client before an autostarted TP can be started as an application. Starting TPSTART can be accomplished by using standard Windows NT methods, such as including TPSTART in the Startup group on the client.


APING and APINGD
Sample CPI-C TPs in the SDK	5 of 8

Building the TPs

APING and APINGD

The sample code for APING and APINGD is ported from code on the IBM APPC/CPI-C disk. They are end-to-end connectivity testers; they simply show that the configuration is correct by exchanging a couple of hundred bytes of data across the link. APING is the invoking (local) half and attempts to contact APINGD, which is written here as a Windows NT service so it can be installed as an invokable TP on the remote computer.

Setup

To set up these CPI-C TPs, create an appropriate APPC LU-LU-mode triplet (for example, LUPING-LUPINGD-#INTER), and set up a CPI-C symbolic destination name that contains the configured remote LU and mode. (The TP name for APINGD is APINGD.) Then assign the local APPC LU to the APING TP, either by using a Registry entry of APING:REG_SZ:LocalLUAlias in the SnaBase\Parameters\Clients key, or by assigning the local LU as the default local APPC LU for the user who will run APING.

Input and Output

APING is a console application. The syntax of its command line is

aping [-ssize] [-iiterations] [-cpackets] [-mmode] [-ttpname] PartnerLUName

aping [-ssize] [-iiterations] [-cpackets] SymbolicDestinationName

where

-ssize

Specifies the size, in bytes, of the packet transmitted. The default is 100 bytes.

-iiterations

Specifies the number of iterations to carry out. The default is 2.

-cpackets

Specifies the number of consecutive packets sent by each side. The default is 1.

-mmode

Specifies the mode name. The default is #INTER.

-ttpname

Specifies the TP name of the TP to start on the remote server. The default is APINGD.

PartnerLUName

Specifies the partner LU name of the destination.

SymbolicDestinationName

Specifies the symbolic destination name of the destination.

Output goes to stdout and stderr, and details the timings for each iteration and also the data rates.

Operation

Note that with APINGD, Specify_Local_TP_Name is used to set the local TP name, so Wait_For_Conversation must be used to wait for the Accept_Conversation call to complete, since it will return asynchronously.

The code at the end of APINGD.C is a stub for making any TP into a Windows NT service. There are three routines that are needed: main, ServiceMain, and ControlHandler. See the comment in the file for details of how these work. The TPStart routine is the entry point of the TP proper.

In particular, note that in response to the SERVICE_CONTROL_STOP or SERVICE_CONTROL_SHUTDOWN messages in the ControlHandler routine, action should normally be taken to stop the service, but because each run does not last long with the samples, no such action is taken.


Multithreaded APINGD
Sample CPI-C TPs in the SDK	6 of 8

Building the TPs

Multithreaded APINGD

The version of APINGD provided in the sample code illustrates how to achieve nonqueued behavior from an invokable TP in Windows NT. This means that multiple copies of APING can talk to the same copy of APINGD at the same time. However, you can’t run multiple copies of a Windows NT service. The functionality is achieved by always having a thread with an Accept_Conversation outstanding, so that any incoming attach for APINGD will always be satisfied immediately.

Setup

Setup requirements are the same as for the single-threaded version. Note that the remote LU and mode used should support parallel sessions so that more than one conversation at a time is possible.

Input and Output

These are the same as for the single-threaded version.

Operation

Operation is similar to that of the single-threaded version. The same three routines are used (main, ServiceMain and ControlHandler). ServiceMain calls the TPStart routine. This routine must not return until the service is ready to terminate.

The TPStart routine does some initialization, creates the first conversation thread, and then waits on an event created by the ServiceMain routine. This event is set when the service control manager issues an order to STOP or SHUTDOWN. When the event is set, it calls WinCPICCleanup, which will cancel any active conversations and return outstanding Accept_Conversation calls, thus making all conversation threads exit. It then marks the service as STOPPED.

The ThreadStart routine is the entry point for each of the conversation threads. It issues Accept_Conversation and Wait_For_Conversation, and when this completes, it creates another thread to wait for the next attach while the existing thread services the first attach.


CPI-C Send and Receive TPs
Sample CPI-C TPs in the SDK	7 of 8

Building the TPs

CPI-C Send and Receive TPs

These TPs are CPI-C versions of the APPC send and receive TPs. The sample code illustrate the use of asynchronous CPI-C calls.

Setup

To set up these TPs, create an appropriate APPC LU-LU-mode triplet, and set up a CPI-C symbolic destination name that contains the configured remote LU and mode. (The default symbolic destination name is CPICRECV.) Then assign the local APPC LU to the CPICSEND TP, either by using a Registry entry of CPICSEND:REG_SZ:LocalLUAlias in the SnaBase\Parameters\Clients key, or by assigning the local LU as the default local APPC LU for the user who will run CPICSEND.

For example, use SENDLU-RECVLU-#INTER as your LU-LU-mode triplet. Then create a CPI-C symbolic destination name CPICRECV containing the application TP name CPICRECV, the partner LU alias RECVLU, and the mode name #INTER. Finally, add the intended user to the users list, and assign SENDLU as the user’s default local APPC LU.

Input and Output

CPICSEND and CPICRECV use the files CPICSEND.CFG and CPICRECV.CFG for input. These files should be placed in the directory that the TP (executable) is in. These files are similar to the input files for the APPC send and receive TPs.

The following entries are for CPICSEND only:

Table B.1    Lines in CPICSEND.CFG

Line		Default		Value to supply
ResultFile =		C:\CPICSEND.OUT		Filename to print timings to
NumSends =		2		Number of Send_Data calls per conversation
SendSize =		1024		Size in bytes of data sent each time
ConfirmEvery =		1		Number of Send_Data calls between Confirm calls
SymDestName =		CPICSEND		Symbolic destination name
NumConversations =		—		Number of conversations. This setting must be the same for CPICSEND and CPICRECV (they do not negotiate the number).
WaitMode=		No		Yes or No: Use wait mode with asynchronous call completion. If No, the TPs issue Specify_Windows_Handle with their window handle so that Windows CPI-C will post completion messages to them. If Yes, the TPs issue Specify_Windows_Handle with NULL so that the TPs must then issue the Wait_For_Conversation call to wait for the asynchronous call to complete.
The following entries are for CPICRECV only:

Table B.2    Lines in CPICRECV.CFG

Line		Default		Value to supply
LocalTPName =		CPICRECV		Local TP name to use on Specify_Local_TP_Name call
NumConversations =		—		Number of conversations. This setting must be the same for CPICSEND and CPICRECV (they do not negotiate the number).
WaitMode=		No		YES or No: Use wait mode with asynchronous call completion. If No, the TPs issue Specify_Windows_Handle with their window handle so that Windows CPI-C will post completion messages to them. If Yes, the TPs issue Specify_Windows_Handle with NULL so that the TPs must then issue the Wait_For_Conversation call to wait for the asynchronous call to complete.
As with SENDTP, CPICSEND produces C:\CPICSEND.OUT (by default) with timings of the conversations in it.

Operation

CPICRECV should be started first; it issues Specify_Local_TP_Name to set its local TP name, and then Accept_Conversation to accept a conversation (note that because Specify_Local_TP_Name is issued, the Accept_Conversation will complete asynchronously).

Both TPs issue Specify_Windows_Handle during initialization to set either the window handle or NULL. CPICSEND calls Set_Processing_Mode after completion of Initialize_Conversation to set the processing mode to nonblocking for this conversation.

After each call is issued, the return code is checked; if it is not CM_OPERATION_INCOMPLETE, the call has already completed, so an ASYNC_COMPLETE message is posted to trigger the next call. If WaitMode is set to Yes and the issued call did not complete immediately, then a Wait_For_Conversation call is issued to wait for call completion, at which point an ASYNC_COMPLETE message is posted. If WaitMode is set to No and the issued call did not complete immediately, then Windows CPI-C detects call completion and posts an ASYNC_COMPLETE message. Receipt of the ASYNC_COMPLETE message triggers the next call to be issued.

For CPICSEND, each conversation consists of an Allocate call, followed by a given number of Send_Data calls of given size and interspersed with Confirm calls at a given interval, followed by a Deallocate.

CPICRECV issues Receive on completion of the Accept_Conversation, and then issues either Receive or Confirmed according to the return from the previous Receive.

At any stage, if the TPs encounter an error, they terminate. Use CPI-C API tracing to diagnose problems with the configuration.

Both TPs are built from a single source-code file, CPICSR.C. CPICSEND is compiled only if -DCPICSEND is used on the command line.

The TPs run as Windows NT applications with a minimized window, the title of which displays the status. When the WndProc of this window, TPWndProc, receives the WM_CREATE message for the window, this triggers the issuing of the first call. When TPWndProc receives an ASYNC_COMPLETE message from Windows CPI-C, this triggers the issuing of the next call, dependent on what the previous call was. When the window is closed, WinCPICCleanup is issued to terminate any active conversations.


AREXEC and AREXECD
Sample CPI-C TPs in the SDK	8 of 8

Building the TPs

AREXEC and AREXECD

The sample code for these two TPs provides the ability to execute commands on a remote computer and to send the output back across the connection to the invoking TP. These two TPs aren’t designed to illustrate any ideas that haven’t been covered so far; they are just a good demonstration.

Setup

To set up these CPI-C TPs, create an appropriate APPC LU-LU-mode triplet, and set up a CPI-C symbolic destination name that contains the configured remote LU and mode. (The TP name for AREXECD is AREXECD.) Then assign the local APPC LU to the AREXEC TP, either by using a Registry entry of AREXEC:REG_SZ:LocalLUAlias in the SnaBase\Parameters\Clients key, or by assigning the local LU as the default local APPC LU for the user who will run AREXEC.

Input and Output

AREXEC is a console application. The syntax of its command line is

arexec [-mmode] [-ttpname] destination command

where

-mmode

Specifies the mode name. The default is #INTER.

-ttpname

Specifies the TP name.

destination

Specifies the destination. Can be either a symbolic destination name or a partner LU name.

command

Specifies the command string to execute on the remote computer.

The stdout and stderr from the command executed at the remote end is sent across the link and printed to stdout on the invoking end.

Operation

The AREXECD program is a Windows NT service, with the same routines as in APING, APINGD and multithreaded APINGD. The execution of the command and sending back of data are done in the routine execute_and_send_output in CPICPORT.C. It creates a named pipe and connects to the read end of the pipe. It then creates a process to run the command and gives that process a handle to the write end of the pipe as its stdout and stderr. Then the data is read from the pipe, and Send_Data is used to send it across the link.