Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Windows CPI-C Overview

  Before Using Windows CPI-C

  Microsoft Windows Graphical Environment and Windows Specific Extensions

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Windows CPI-C Library Installation Checking

  Windows CPI-C Programming Considerations

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Initialize_Conversation (cminit)

  Set_Deallocate_Type (cmsdt)

  Deallocate (cmdeal): Description and Syntax

  Deallocate (cmdeal): Return Codes

  Deallocate (cmdeal): State Changes and Remarks

  Allocate (cmallc)

  Accept_Conversation (cmaccp)

  Cancel_Conversation (cmcanc)

  Wait_For_Conversation (cmwait)

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Set_Conversation_Type (cmsct)

  Set_Mode_Name (cmsmn)

  Set_Partner_LU_Name (cmspln)

  Set_TP_Name (cmstpn)

  Set_Return_Control (cmsrc)

  Set_Sync_Level (cmssl)

  Set_Conversation_Security_Type (cmscst)

  Set_Conversation_Security_User_ID (cmscsu)

  Set_Conversation_Security_Password (cmscsp)

  Calls to Send Data

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Set_Send_Type (cmsst)

  Send_Data (cmsend)

  Flush (cmflus)

  Confirm (cmcfm): Description and Syntax

  Confirm (cmcfm): Return Codes

  Confirm (cmcfm): State Changes and Remarks

  Set_Prepare_To_Receive_Type (cmsptr)

  Prepare_To_Receive (cmptr): Description and Syntax

  Prepare_To_Receive (cmptr): Return Codes

  Prepare_To_Receive (cmptr): State Changes and Remarks

  Request_To_Send (cmrts)

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Calls to Receive Data

  Set_Receive_Type (cmsrt)

  Receive (cmrcv): Description and Syntax

  Receive (cmrcv): Return Codes

  Receive (cmrcv): State Changes

  Receive (cmrcv): Confirmation Processing, Normal Deallocation, and ABEND

  Set_Fill (cmsf)

  Set_Processing_Mode (cmspm)

  Specify_Windows_Handle (xchwnd)

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Confirmed (cmcfmd)

  Set_Error_Direction (cmsed)

  Set_Log_Data (cmsld)

  Send_Error (cmserr): Description and Syntax

  Send_Error (cmserr): Return Codes

  Send_Error (cmserr): State Changes and Remarks

  Calls to Get Information

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Extract_Conversation_Security_Type (xcecst)

  Extract_Conversation_Security_User_ID (cmecsu)

  Extract_Conversation_State (cmecs)

  Extract_Conversation_Type (cmect)

  Extract_Mode_Name (cmemn)

  Extract_Partner_LU_Name (cmepln)

  Extract_TP_Name (cmetpn)

  Extract_Sync_Level (cmesl)

  Specify_Local TP_Name (cmsltp)

  Test_Request_To_Send_Received (cmtrts)

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Calls to Administer Side Information

  Set_CPIC_Side_Information (xcmssi)

  Extract_CPIC_Side_Information (xcmesi)

  Delete CPIC Side Information (xcmdsi)

  Extensions for the Windows Environment

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Overview

  WinCPICCleanup()

  WinCPICIsBlocking()

  WinCPICStartup()

  WinCPICSetBlockingHook()

  WinCPICUnhookBlockingHook()

  Return Codes


Contents for Windows CPI-C Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows CPI-C

  Calls to Start and End a Conversation

  Calls to Change Initial Conversation Characteristics

  Calls to Send Data

  Calls to Receive Data

  Calls to Confirm Receipt of Data and Report Errors

  Calls to Get Information

  Calls to Administer Side Information

  Extensions for the Windows Environment

  Return Codes

  List of Return Codes


Using Help

You can find information in Help by choosing a Help topic or by using the Search feature. To return to the Help contents screen after you read the following instructions, click Back or press B.

For complete instructions on how to use Help, press F1 while Help is active.

To expand a topic list

Click a button showing a closed file folder  [image].

Or press TAB until the intended heading is highlighted, and press ENTER.

To collapse a topic list

Click a button showing an open file folder  [image].

Or press TAB until the intended heading is highlighted, and press ENTER.

To choose a Help topic

Click an underlined topic or a topic with a button  [image].

Or press TAB until the intended topic is highlighted, and then press ENTER.

To return to the previous topic

Click Back or press B.

To use the Search feature

Click Search or press S.

To close Help

From the File menu for Help, choose Exit (ALT, F, X).


Windows CPI-C 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 CPI-C was developed. The CPI-C calls and information presented in this guide represent an evolving Windows CPI-C that is composed of CPI-C version 1.2 and a set of Windows extensions that allow for multiple applications and asynchronous call completion.

Windows CPI-C 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 Windows CPI-C 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.

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

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

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 CPI-C 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" in Before Using Windows CPI-C. 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 CPI-C 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 CPI-C asynchronous calls and Windows extensions appears in "Using Asynchronous Call Completion" in Before Using Windows CPI-C.


Before Using Windows CPI-C

The following CPI-C calls and Windows enhancements are of particular importance and should be reviewed before using this version of Windows CPI-C:

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

WinCPICSetBlockingHook

Allows a Windows CPI-C implementation to block CPI-C 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 WinCPICUnhookBlocking Hook.

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 CPI-C 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 CPI-C 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 CPI-C required and to retrieve details of the specific CPI-C implementation.

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

WinCPICCleanup

Terminates and deregisters an application from a Windows CPI-C implementation.

Important  This function must be called by an application when finished to deregister the application from the Windows CPI-C implementation.

Using Asynchronous Call Completion

With one exception, Windows CPI-C 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 additional information on using CPI-C, see the IBM Systems Application Architecture Common Programming Interface Communications Reference, part number SC26-4399-04.


Microsoft Windows Graphical Environment and Windows-Specific Extensions

This API has been designed for all implementations and versions of the Windows environment from and including version 3.0. It thus provides for Windows CPI-C implementations and Windows CPI-C applications in both 16-bit and 32-bit operating environments.

Windows CPI-C makes provisions for multithreaded Windows-based processes. A process contains one or more threads of execution. In the Win16 nonmultithreaded world, 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. In nonmultithreaded environments (such as version 3.0), use of the term thread refers to a Windows process.

The extensions to the Windows environment included in Windows CPI-C are provided for maximum programming compatibility between Windows version 3.x and Windows NT and optimal application performance in both environments.


Windows CPI-C Library Installation Checking

To detect the presence of any Windows CPI-C implementations on a system, an application that has been linked with the Windows CPI-C import library can attempt to call the WinCPICStartup( ) routine. If you want your application to be a little more sophisticated, have it examine the $PATH environment variable to search for instances of Windows CPI-C API implementations (WINCPIC.DLL). For each instance, it can issue a LoadLibrary( ) call and use the WinCPICStartup( ) routine to discover implementation-specific data.

This version of the Windows CPI-C API specification does not attempt to address explicitly the issue of multiple library/multiple concurrent Windows CPI-C implementations. Nothing in the specification should be interpreted as restricting multiple Windows CPI-C DLLs from being present and from being used concurrently by one or more Windows CPI-C applications.


Windows CPI-C Programming Considerations

This topic describes the following for Windows CPI-C:

•	Byte ordering

•	Pointers

•	Blocking routines

•	Data types

•	Symbolic constants

•	Strings

•	Validity of output parameters

Byte Ordering

The Intel byte ordering is like that of the DEC VAX, and so differs from the Internet and 68000-type processor byte ordering. Take care in your programming to ensure the correct orientation.

Pointers

All pointers used by applications with Windows CPI-C should be FAR.

Blocking Routines

Although blocking functions are supported with Windows CPI-C, you should not use them. Instead you should use the Specify_Windows_Handle function in conjunction with the "WinAsyncCPI-C" Windows message. Applications targeted exclusively for Windows NT and that make use of additional threads to call the blocking routines need not use the Specify_Windows_Handle function.

When using the nonblocking modes, an application can issue only one operation at a time for each conversation. An attempt to initiate a second operation will return the error code CM_CONV_BUSY.

Data Types

The data types for the parameters supplied to and received from Windows 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 Windows CPI-C applications.

For ease of understanding, this specification 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

Most parameters supplied to and returned by Windows CPI-C are 32-bit 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

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

Validity of Output Parameters

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


Accept_Conversation (cmaccp)

Issued by the invoked program to accept the incoming conversation and set certain conversation characteristics.

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 the 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)

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)

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): Description and Syntax

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 CPI-C 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.
See Also

Confirm (cmcfm): Return Codes

Confirm (cmcfm): State Changes and Remarks


Confirm (cmcfm): 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 nonblocking 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.

See Also

Confirm (cmcfm): Description and Syntax

Confirm (cmcfm): State Changes and Remarks


Confirm (cmcfm): State Changes and Remarks

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

See Also

Confirm (cmcfm): Description and Syntax

Confirm (cmcfm): Return Codes


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 nonblocking 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): Description and Syntax

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.
See Also

Deallocate (cmdeal): Return Codes

Deallocate (cmdeal): State Changes and Remarks


Deallocate (cmdeal): 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 nonblocking 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.

See Also

Deallocate (cmdeal): Description and Syntax

Deallocate (cmdeal): State Changes and Remarks


Deallocate (cmdeal): State Changes and Remarks

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

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

See Also

Deallocate (cmdeal): Description and Syntax

Deallocate (cmdeal): Return Codes


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)

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

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)

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)

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)

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

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)

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)

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)

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)

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 nonblocking 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)

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

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): Description and Syntax

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.
See Also

Prepare_To_Receive (cmptr): Return Codes

Prepare_To_Receive (cmptr): State Changes and Remarks


Prepare_To_Receive (cmptr): 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 nonblocking 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.

See Also

Prepare_To_Receive (cmptr): Description and Syntax

Prepare_To_Receive (cmptr): State Changes and Remarks


Prepare_To_Receive (cmptr): State Changes and Remarks

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.

See Also

Prepare_To_Receive (cmptr): Description and Syntax

Prepare_To_Receive (cmptr): Return Codes


Receive (cmrcv): Description and Syntax

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 CPI-C 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.
data_received	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.
	• CM_CONFIRM_SEND_RECEIVED indicates, for the partner program, that the conversation has entered RECEIVE state and a request for confirmation has been received by the local program. For the local program, the conversation is now in CONFIRM-SEND state. The program normally responds by issuing the Confirmed call. Upon successful execution of the Confirmed call, the conversation changes to SEND state for the local program.
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.
See Also

Receive (cmrcv): Return Codes

Receive (cmrcv): State Changes

Receive (cmrcv): Confirmation Processing, Normal Deallocation, and ABEND


Receive (cmrcv): 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.

See Also

Receive (cmrcv): Description and Syntax

Receive (cmrcv): State Changes

Receive (cmrcv): Confirmation Processing, Normal Deallocation, and ABEND


Receive (cmrcv): 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
For information about state changes that can occur when Receive is issued in any allowed state, see Receive (cmrcv): Confirmation Processing, Normal Deallocation, and ABEND.

See Also

Receive (cmrcv): Description and Syntax

Receive (cmrcv): Return Codes

Receive (cmrcv): Confirmation Processing, Normal Deallocation, and ABEND


Receive (cmrcv): Confirmation Processing, Normal Deallocation, and ABEND

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. For more information, see the Windows CSV Specification.

See Also

Receive (cmrcv): Description and Syntax

Receive (cmrcv): Return Codes

Receive (cmrcv): State Changes


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 nonblocking 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)

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 nonblocking 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-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 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. For more information, see the Windows CSV Specification.


Send_Error (cmserr): Description and Syntax

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.
See Also

Send_Error (cmserr): Return Codes

Send_Error (cmserr): State Changes and Remarks


Send_Error (cmserr): 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 nonblocking 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 List of 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 List of 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 List of 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.

See Also

Send_Error (cmserr): Description and Syntax

Send_Error (cmserr): State Changes and Remarks


Send_Error (cmserr): State Changes and Remarks

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 CPI-C. 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

See Also

Send_Error (cmserr): Description and Syntax

Send_Error (cmserr): Return Codes


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)

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

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)

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)

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.
side_info_entry	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 nonexistent partner LU) are not detected until Allocate is issued. The error is returned on a call following Allocate.


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.
deallocate_type	• 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)

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)

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)

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)

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)

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)

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)

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)

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)

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.

If the LU is unable to allocate a session, the notification is returned on the Allocate call.


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

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)

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)

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)

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)

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)

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)

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: Overview

The API extensions described in this Help allow asynchronous verb completion with the Windows CPI-C. 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.

These API extensions 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 optimal application performance in both 16-bit and 32-bit 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 16-bit 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 help provide a definition of the function, syntax, returns, and remarks for using the extension. Corresponding prototypes for each extension are located in the WINCPIC.H header file.


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.

Remarks

Use WinCPICCleanup( ) to indicate deregistration of a Windows CPI-C application from a Windows CPI-C implementation.

See Also

WinCPICStartup( )


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( )

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. For this release of Windows CPI-C, 1.0 is the correct 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

For this release of Windows CPI-C, 1.0 is the correct version number.

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

See Also

WinCPICCleanup( )


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

WinCPICUnhookBlockingHook( )


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( )


List of Return Codes

This topic describes the return codes for Windows CPI-C calls. The return codes are listed in integer order.

Call-specific return codes are described for the individual calls in this help.

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.

25

CM_PROGRAM_STATE_CHECK

The call was not issued in an allowed conversation state.

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.

CM_SYSTEM_EVENT

The Wait_For_Conversation call was being executed when an event (for example, a signal) handled by the program occurred. Wait_For_Conversation returns this return code to allow the program to reissue the Wait_For_Conversation or to perform other processing. It is the responsibility of the event-handling portion of the program to record sufficient information for the program to decide how to proceed upon receipt of this return code. The state of the conversation remains unchanged.


Microsoft Support Services Contents
Microsoft Support Services

  When You Have a Question

  Product Support Within the United States and Canada


When You Have a Question

If you have a question about SNA Server, first look in the product documentation or consult online Help. You can also find late-breaking updates and technical information in the README file that came with your SNA Server disks. If you cannot find the answer, contact the Microsoft Support Network.

Outside the United States, contact Microsoft Product Support Services at the Microsoft subsidiary office that serves your area.

The Microsoft Support Network

The Microsoft Support Network offers you a wide range of choices and access to high-quality, responsive technical support. Microsoft recognizes that support needs vary from user to user; the Microsoft Support Network allows you to choose the type of support that best meets your needs, with options ranging from electronic bulletin boards to annual support programs. For information about support services in the United States and Canada, see Product Support Within the United States and Canada.

Services vary outside the United States and Canada. In other locations, contact a local Microsoft subsidiary for information. The Microsoft Support Network is subject to Microsoft's then-current prices, terms, and conditions, and is subject to change without notice.


Product Support Within the United States and Canada

In the United States and Canada, the following support services are available through the Microsoft Support Network:

Electronic Services

Priority Support

Text Telephone

Other Support Options

Other Microsoft Services


Electronic Services

These services are available 24 hours a day, 7 days a week, including holidays.

Microsoft FastTips

(800) 936-4400 on a touch-tone telephone. Receive automated answers to common questions, and access a library of technical notes, all delivered by recording or fax. You can use the following keys on your touch-tone telephone after you reach FastTips:

To	Press
Advance to the next message	*
Repeat the current message	7
Return to the beginning of FastTips	#
CompuServe

Interact with other users and Microsoft support engineers, or access the Microsoft Knowledge Base to get product information. At any ! prompt, type go microsoft to access Microsoft forums, type go mskb to access the Microsoft Knowledge Base, or type go mssna to access the Microsoft SNA forum. For an introductory CompuServe membership kit, call (800) 848-8199, operator 524.

Microsoft Download Service

Access, via modem, the Driver Library and the most current technical notes (1200, 2400, or 9600 baud; no parity; 8 data bits; 1 stop bit). In the United States, call (206) 936-6735. In Canada, call (905) 507-3022.

Internet

Access the Driver Library and the Microsoft Knowledge Base. The Microsoft Internet FTP archive host, ftp.microsoft.com, supports anonymous login. When logging in as anonymous, you should type your complete electronic mail name as your password.

See also

Priority Support

Text Telephone

Other Support Options

Other Microsoft Services


Priority Support

The Microsoft Support Network offers priority telephone access to Microsoft support engineers 24 hours a day, 7 days a week, except holidays.

In the United States, call (900) 555-2100; $150 (U.S.) per incident. Charges appear on your telephone bill.

In the United States, call (800) 936-5900; $150 (U.S.) per incident, billed to your VISA card, MasterCard, or American Express card.

In Canada, call (800) 668-7975 for more information.

See also

Electronic Services

Text Telephone

Other Support Options

Other Microsoft Services


Text Telephone

Microsoft text telephone (TT/TDD) services are available for the deaf or hard-of-hearing. In the United States, using a TT/TDD modem, dial (206) 635-4948 between 6:00 A.M. and 6:00 P.M. Pacific time, Monday through Friday, excluding holidays. In Canada, using a TT/TDD modem, dial (905) 568-9641 between 8:00 A.M. and 8:00 P.M. Eastern time, Monday through Friday, excluding holidays.

See also

Electronic Services

Priority Support

Other Support Options

Other Microsoft Services


Other Support Options

The Microsoft Support Network offers annual and multiple incident support plans. For information, in the United States, contact the Microsoft Support Network Sales and Information group at (800) 936-3500 between 6:00 A.M. and 6:00 P.M. Pacific time, Monday through Friday, excluding holidays. In Canada, call (800) 668-7975 between 8:00 A.M. and 8:00 P.M. Eastern time, Monday through Friday, excluding holidays.

Electronic Services

Priority Support

Text Telephone

Other Microsoft Services


Other Microsoft Services

Microsoft Solution Providers Program

Microsoft Solution Providers are independent organizations that provide consulting, integration, customization, development, technical support and training, and other services for Microsoft products. These companies are called Solution Providers because they apply technology and provide services to help solve real-world problems.

In the United States, for more information about the Microsoft Solution Providers program or the Microsoft Solution Provider nearest to you, please call (800) 426-9400 between 6:30 A.M. and 5:30 P.M. Pacific time, Monday through Friday, excluding holidays. In Canada, call (800) 563-9048 between 8:00 A.M. and 8:00 P.M. Eastern time, Monday through Friday, excluding holidays.

Microsoft TechNet

Microsoft TechNet is an annual information service created for those who support or educate end users, administer networks or databases, create automated solutions and recommend or evaluate information technology solutions.  Microsoft TechNet gives you the answers you need, when you need them by providing timely, comprehensive and in-depth information on Microsoft products and on supporting and administering Microsoft-based solutions via the monthly Microsoft TechNet CD and monthly TechNet Supplemental (Drivers & Patches) CD.

For more information about Microsoft TechNet, in the United States and Canada, call (800) 344-2121, dept. 3013, between 7:00 A.M. and 7:00 P.M. Central time, Monday through Friday.

See also

Electronic Services

Priority Support

Text Telephone

Other Support Options