HP-UX SNAplus2 CPI-C Programmer’s Guide HP-UX 11i Manufacturing Part Number: J2744-90021 E0603 United States © Copyright 2003 © Hewlett-Packard Company, 2003. All rights reserved.
Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material.
Trademark Notices ActivePerl is a registered trademark of ActiveState Tool Corporation Apple and Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries. AppleShare is a registered trademark of Apple Computer, Inc. CHAMELEON is a trademark of NetManage, Inc. DIGITAL and PATHWORKS are trademarks of Digital Equipment Corporation. DiskAccess is a registered trademark of Intergraph. EXCURSION is a trademark of Digital Equipment Corporation.
SunForum is a registered trademark of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark in the United States and other countries, licensed exclusively through The Open Group. VERITAS is a registered trademark of VERITAS Software Corporation. VERITAS File System is a trademark of VERITAS Software Corporation. WinDD is a trademark of Tektronix, Inc. X Window System is a trademark of the Massachusetts Institute of Technology.
Contents 1. Concepts What Is CPI-C?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNAplus2 CPI-C Option Set Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Communication between Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical Unit 6.2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sessions . . . . . .
Contents Already-Verified Conversation Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Nonblocking Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 CPI-C and LU 6.2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 2. Writing CPI-C Applications CPI-C Call Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Default Local LU. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Control Point LU. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 How Programs Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Invoked Program: Automatically Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Returned Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . State When Issued . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . State Change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Function Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call for Java CPI-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplied Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returned Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . State When Issued . . . . .
Contents Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delete_CPIC_Side_Information (xcmdsi) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplied Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returned Parameters . . . .
Contents State When Issued . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . State Change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Extract_CPIC_Side_Information (xcmesi) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplied Parameters . . . .
Contents Extract_Security_User_ID (cmesui or cmecsu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call for Java CPI-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplied Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returned Parameters . . . . . . . . . . .
Contents State Change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initialize_For_Incoming (cminic). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Function Call for Java CPI-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplied Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returned Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . State When Issued . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . State Change. . . . . . . . . .
Contents State Change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Set_Conversation_Security_Password (xcscsp) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Set_Conversation_Security_Type (cmscst) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call. . . . . . . . . . . . . . .
Contents Function Call for Java CPI-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplied Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returned Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . State When Issued . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . State Change. . . . . . . . . .
Contents State Change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Set_Mode_Name (cmsmn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents State When Issued . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . State Change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Set_Return_Control (cmsrc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call. . .
Contents Function Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call for Java CPI-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplied Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returned Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . State When Issued . . . . .
Contents Returned Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WinCPICStartup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents B. Conversation State Changes Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 22
Before You Begin This book is a guide for developing C-language or Java application programs that use Common Programming Interface for Communications (CPI-C) to exchange data in a Systems Network Architecture (SNA) environment. The SNAplus2 implementation of CPI-C is based on IBM's implementation of CPI-C in its OS/2 products (with modifications for the HP-UX environment).
Prerequisite Knowledge Before reading this manual, you should have a knowledge of the following subjects: For Unix • The C compiler cc • HP-UX version 10.10 or later For Java CPI-C: For Windows • The Java Virtual Machine version 1.1.6 • The Java compiler javac • HP-UX version 11i or later • The Microsoft Visual C++ Version 4 compiler • Microsoft Windows NT (Version 3.
Intended Audience The primary audience for this manual is the programmer writing application programs that use CPI-C to exchange data. This manual provides conceptual information for programmers who are not familiar with CPI-C, and detailed reference information for experienced CPI-C programmers.
About This Book This section explains how information is organized and presented in this book. Organization of This Book This book is organized as follows: 26 • Chapter 1, Concepts, introduces the fundamental concepts of CPI-C. It is intended for programmers who are not familiar with CPI-C. • Chapter 2, Writing CPI-C Applications, contains general information a CPI-C programmer needs when writing CPI-C Applications. • Chapter 3, CPI-C Calls, describes each CPI-C call in detail.
Typographic Conventions Table 1, Typographic Conventions, shows the typographic styles used in this document. Table 1 Typographic Conventions Special Element Sample of Typography Document title SNAplus2 Administration Guide File or path name cmc.
For Windows This symbol is used to indicate the start of a section of text that applies to the Win32 client which runs on the Microsoft NT (Version 3.51 or later) and Windows 95 operating systems. SNAplus2 also provides a Win16 client which runs on Microsoft Windows 3.1 and Windows for Workgroups 3.11, but the Win16 client is not documented in this book.
Related Publications For information about SNA or LU 6.2 architecture, refer to these IBM documents: • IBM Systems Network Architecture Concepts and Products, GC30-3072 • IBM Systems Network Architecture: APPN Architecture Reference, SC30-3422. • IBM Common Programming Interface Communications Specification, SC31-6180 • IBM Systems Network Architecture: LU 6.
1 Concepts This chapter introduces the fundamental concepts of CPI-C in a distributed processing environment.
Concepts 32 • An example of a simple mapped conversation • Confirmation processing • Conversation states • How to change conversation states • Side information • Basic conversations • Multiple conversations • Conversation security • Nonblocking operation • CPI-C and LU 6.
Concepts What Is CPI-C? What Is CPI-C? CPI-C stands for Common Programming Interface for Communications. CPI-C is a portable application programming interface, or API, that enables peer-to-peer communications among programs in an SNA environment. CPI-C enables application programs distributed across a network to work together.
Concepts What Is CPI-C? the functions. The mapping between the X/Open functions and the IBM CPI-C 2.0 functions is shown in Table 1-1, “Mapping Between X/Open Functions and IBM CPI-C 2.0 Functions.” Table 1-1 Mapping Between X/Open Functions and IBM CPI-C 2.0 Functions X/Open Function IBM CPI-C 2.
Concepts What Is CPI-C? Figure 1-1 Communication between Programs Program B Program A LU2 LU1 Conversation Session Logical Unit 6.2 Each program is associated with a logical unit (LU), which is the program's access point into the network. CPI-C uses LU type 6.2, which supports peer-to-peer communications between LUs. Several programs can be associated with the same LU.
Concepts What Is CPI-C? Conversations The communication between the two programs occurs as a conversation within the LU-to-LU session. A program can be involved in several conversations simultaneously. Contention When both LUs attempt to allocate a conversation on the same session at the same time, one must win (the contention winner) and one must lose (the contention loser).
Concepts What Is CPI-C? The Conversation Process A conversation begins when both of the following happen: • One program (the invoking program) instructs SNAplus2 to start another program (the invoked program) and allocate a conversation between the two programs. • The invoked program notifies SNAplus2 that it is ready to communicate with the invoking program. During the conversation, the two programs exchange status information and application data.
Concepts A Simple Mapped Conversation A Simple Mapped Conversation The example below charts a simple mapped conversation. It shows the CPI-C calls used to start the conversation, exchange data, and end it. The arrow indicates the flow of data. Some call parameters and some return codes are also shown, enclosed in parentheses.
Concepts A Simple Mapped Conversation • Allocate, which requests that SNAplus2 establish a conversation between the invoking program and the invoked program. The invoked program issues the Accept_Conversation call, which informs SNAplus2 that the invoked program is ready to begin a conversation with the invoking program. Sending Data The Send_Data call puts one data record (containing application data to be transmitted) into the local LU's send buffer which already contains the allocation request.
Concepts Confirmation Processing Confirmation Processing When a program sends data to its partner program, it can also request the partner program to confirm that it has received the data successfully. The receiving program must either confirm receipt of the data or indicate that an error has occurred. The two programs are synchronized each time they exchange a confirmation request and response. This is illustrated in Table 1-3, “Confirmation Processing.
Concepts Confirmation Processing Table 1-3 Confirmation Processing (Continued) Invoking Program Invoked Program Receive (status_received=CM_CONFIRM_DEALLOC_RECEIVED) Confirmed ← (return_code=CM_OK) Establishing the Synchronization Level The synchronization level is one of the conversation's characteristics.
Concepts Confirmation Processing In the previous example, the first Received call has a status_received of CM_CONFIRM_RECEIVED, indicating that a confirmation is required before the partner program can continue. Responding to a Confirmation Request The invoked program issues the Confirmed call to confirm receipt of data; this frees the invoking program to resume processing.
Concepts Conversation States Conversation States The state of the conversation governs which CPI-C calls can be issued by the program. For instance, a program cannot issue the Send_Data call if the conversation is not in Send or Send-Pending state. Possible conversation states are summarized in the list below. Reset The conversation has not started or has been terminated. Initialize The conversation has been initialized successfully.
Concepts Conversation States For Unix Initialize-Incoming The program has successfully issued Initialize_For_Incoming and obtained a conversation ID. It can now issue Accept_Incoming to accept an incoming conversation. For Windows Pending-Post End of Section The description of each CPI-C call includes information about the conversation states in which it can be issued. For a table of which verbs can be issued in each conversation state, see Appendix B, “Conversation State Changes.
Concepts Changing Conversation States Changing Conversation States In Table 1-4, Changing Conversation States, the conversation states appear in the left and right margins. This table shows how CPI-C calls can change the state of the conversation from Send to Receive and from Receive to Send.
Concepts Changing Conversation States Table 1-4 State Changing Conversation States (Continued) Invoking Program Invoked Program State Send (return_code=CM_OK) Receive Send_Data Confirm ← Receive (status_received= CM_CONFIRM_RECEIVED) Confirm Request_To_Send Confirmed → Receive (return_code=CM_OK) (request_to_send_receive d= CM_REQ_TO_SEND_RECEIVED) Prepare_To_Receive ← Receive (status_received= CM_CONFIRM_SEND_REC EIVED) 46 Chapter 1
Concepts Changing Conversation States Table 1-4 State Changing Conversation States (Continued) Invoking Program Invoked Program State ConfirmSend Confirmed → Send (return_code=CM_OK) Receive Send_Data Deallocate → Receive (status_received= CM_CONFIRM_DEALLOC_RECE IVED) Confirm-Deall ocate Confirmed ← Reset (return_code=CM_OK) Reset Initial States Before the conversation is allocated, both programs are in Reset state.
Concepts Changing Conversation States After the conversation is allocated, the initial state is Send for the invoking program and Receive for the invoked program. Changing to Receive State The Prepare_To_Receive call enables a program to change the conversation from Send to Receive state. This call does the following: • It flushes the local LU's send buffer.
Concepts Side Information Side Information The information required for two programs to communicate is stored in CPI-C side information entries in the SNAplus2 configuration file. Each side information entry is identified by a Symbolic Destination Name, which is the sym_dest_name parameter specified by the Initialize_Conversation call. The parameter sym_dest_name is an 8-byte ASCII character string and can contain any displayable characters.
Concepts Basic Conversations Basic Conversations Basic conversations are normally used by service programs. These are programs that provide services to other local programs. They are more complex than mapped conversations but provide an experienced LU 6.2 programmer with a greater degree of control over the transmission and handling of data. This section summarizes the characteristics of basic conversations. Logical Records In a basic conversation, data is sent in the form of logical records.
Concepts Basic Conversations Bit 0 of byte 0 of the LL (the most significant bit) is used to indicate length continuation (segmentation). The following example shows ten bytes of data (each data byte has the value DD) split into three GDS segments. The first and second segments each contain four bytes of data, and the last segment contains two bytes of data.
Concepts Multiple Conversations Multiple Conversations A program can be involved in several conversations simultaneously. Each conversation requires an LU-to-LU session. Multiple conversations are not supported if the application uses a dependent LU (for more information, see “Specifying the Local LU” in Chapter 2). A common use of multiple conversations is to have an invoked program invoke another program, which, in turn, invokes another program, and so on.
Concepts Overview of Conversation Security Overview of Conversation Security You can use conversation security to require that the invoking program provide a user ID and password before CPI-C allocates a conversation with the invoked TP. In configuring the invoked TP, the System Administrator indicates whether to use conversation security. If so, the invoking TP must provide a user ID and password when allocating a conversation with the invoked program.
Concepts Overview of Conversation Security • Each time the program successfully issues Accept_Conversation or Accept_Incoming, CPI-C assigns a new context ID to the conversation. The program can determine the value of this context ID by issuing Extract_Conversation_Context with the appropriate conversation ID. • The program's “current context” is normally the context ID associated with the most recent Accept_Conversation or Accept_Incoming.
Concepts Overview of Conversation Security • If the program specifying “already verified” was itself invoked by another program, as described in “Conversation Security for Multiple Conversations”, CPI-C sends the user ID from the current conversation context. • Otherwise, CPI-C takes the HP-UX user name with which the program is running, truncated to 10 characters if necessary, and uses this as the conversation security user ID.
Concepts Nonblocking Operation Nonblocking Operation This section does not apply to Java CPI-C. Java CPI-C functions always operate in blocking mode; that is, the function does not return control to the application until the requested processing has completed. By default, CPI-C functions operate in blocking mode; that is, the function does not return control to the application until the requested processing has completed.
Concepts Nonblocking Operation Table 1-5 Nonblocking Operation (Continued) Invoking Program Invoked Program Receive (data_received=CM_C OMPLETE_DATA_RECEIV ED) (status_received=CM _CONFIRM_RECEIVED) Wait_For_Conversation [Application is suspended until processing for the previous Confirm has completed] Confirmed ← (Wait_For_Conversation returns, return_code=CM_OK, conversation_return_code=CM_OK) Send_Data Deallocate → (return_code=CM_OPERATION_INCOMPLETE) [Application performs other processing not relat
Concepts Nonblocking Operation Table 1-5 Nonblocking Operation (Continued) Invoking Program Invoked Program Check for Completion (return_code=CM_OK) Wait_For_Conversation (return_code=CM_OK, conversation_return_code=CM_OK) [Conversation is now deallocated.] The following steps explain the processing shown in the previous example. 1. After allocating the conversation and sending some data, the invoking program issues Set_Processing_Mode to set the processing mode to CM_NON_BLOCKING.
Concepts Nonblocking Operation CM_OK indicates that Wait_For_Conversation completed successfully; the conversation return_code of CM_OK indicates that the Confirm function (for which it was waiting) completed successfully. 6. After sending additional data, the invoking program then issues Deallocate, which returns CM_OPERATION_INCOMPLETE. This indicates that the function was issued successfully and is operating in nonblocking mode.
Concepts Nonblocking Operation • Cancel_Conversation • Deallocate As an alternative to using Specify_Windows_Handle or WinCPICSetEvent() as described previously, the application can use Wait_For_Conversation, as for HP-UX systems. This function is provided for Windows systems to assist in migrating applications from other operating system environments. However, the use of blocking functions such as Wait_For_Conversation in the Windows environment is strongly discouraged.
Concepts CPI-C and LU 6.2 CPI-C and LU 6.2 CPI-C applications can communicate with non-CPI-C LU 6.2 applications, such as APPC. CPI-C does not support the following features that are included in some LU 6.2 implementations: • Sync Point/Back Out processing • PIP data • LOCKS=LONG • MAP_NAME • FMH_DATA These must not be used in LU 6.2 applications if CPI-C is to communicate with them.
Concepts CPI-C and LU 6.
2 Writing CPI-C Applications This chapter contains information you will need when writing CPI-C application programs.
Writing CPI-C Applications For Unix For Windows • Initial conversation characteristics • Side information • Configuration • Specifying the TP name and local LU name for a CPI-C program • How programs get started • HP-UX systems considerations • Java CPI-C considerations • Windows considerations End of Section • 64 Writing portable applications Chapter 2
Writing CPI-C Applications CPI-C Call Summary CPI-C Call Summary This section briefly describes each CPI-C call. They are grouped by function. For a more detailed explanation of a particular call, see Chapter 3, “CPI-C Calls.” The “names” of the calls are pseudonyms. The actual C function names appear in parentheses after the pseudonym. For example Initialize_Conversation is the pseudonym for a call. The actual function name is cminit.
Writing CPI-C Applications CPI-C Call Summary Initialize_For_Incoming (cminic) This call is used by the invoked program to obtain a conversation ID for an incoming conversation which it will later accept with Accept_Incoming. This enables the program to issue Accept_Incoming in nonblocking mode, if required, instead of using Accept_Conversation which always operates in blocking mode.
Writing CPI-C Applications CPI-C Call Summary Allocate (cmallc) This call is issued by the invoking program to allocate a conversation with the partner program, using the current conversation characteristics. The type of conversation allocated depends on the conversation type characteristic (mapped or basic). Accept_Conversation (cmaccp) This call is issued by the invoked program to accept the incoming conversation and set certain conversation characteristics.
Writing CPI-C Applications CPI-C Call Summary If the send type (specified by the Set_Send_Type call) includes the function of the Flush, Confirm, Prepare_To_Receive, or Deallocate call, the data is transmitted to the partner LU (and partner program) immediately.
Writing CPI-C Applications CPI-C Call Summary Set_Prepare_To_Receive_Type (cmsptr) This call sets the conversation's prepare-to-receive type, which specifies whether subsequent Prepare_To_Receive calls will include Flush or Confirm functionality. The prepare-to-receive type affects all subsequent Prepare_To_Receive calls. It can be changed by issuing the Set_Prepare_To_Receive_Type call again.
Writing CPI-C Applications CPI-C Call Summary Converting Data Between ASCII and EBCDIC For Unix The following calls enable a program to translate local data from ASCII to EBCDIC before sending it to the partner program, or translate data received from the partner program from EBCDIC to ASCII. The program needs to use these functions only if the partner program requires data to be in EBCDIC. Convert_Incoming (cmcnvi) This call converts an EBCDIC data string into ASCII.
Writing CPI-C Applications CPI-C Call Summary Set_Log_Data (cmsld) This call specifies a log message (log data) and its length to be sent to the partner LU. This call only has an effect in basic conversations. If present, log data is sent when the Send_Error call is issued or when the conversation is abnormally deallocated. After the log data is sent CPI-C resets the log data to null and the log data length to 0 (zero).
Writing CPI-C Applications CPI-C Call Summary appropriate conversation; the program then calls Wait_For_Conversation to get the results of the nonblocking function. This call enables the program to check for completion of nonblocking functions without having to suspend (unlike Wait_For_Conversation, which suspends until a function has completed).
Writing CPI-C Applications CPI-C Call Summary WinCPICSetBlockingHook() Specifies the blocking procedure that CPI-C uses while processing blocking calls; this replaces CPI-C's default blocking procedure. The blocking procedure is called repeatedly until CPI-C has finished processing the call. WinCPICUnhookBlockingHook() Unregisters the blocking procedure specified by a previous WinCPICSetBlockingHook() call, so that CPI-C reverts to using the default blocking procedure.
Writing CPI-C Applications CPI-C Call Summary Table 2-2 Extract_* Calls and Actions (Continued) Call Retrieves Extract_Mode_Name (cmemn) Mode name Extract_Partner_LU_Name (cmepln) Partner LU name Extract_TP_Name (cmetpn) TP name that was specified on the incoming Allocate request Extract_Sync_Level (cmesl) Synchronization level Test_Request_to_Send_Received (cmtrts) This call determines whether a request-to-send notification has been received from the partner program.
Writing CPI-C Applications CPI-C Call Summary WinCPICCleanup For Windows This call unregisters the application as a Windows CPI-C application, after it has finished issuing CPI-C calls. A Windows CPI-C application must use this call before terminating, and must not issue any other CPI-C calls after it has issued this call. End of Section Administering Side Information These functions are not available in Java CPI-C.
Writing CPI-C Applications Initial Conversation Characteristics Initial Conversation Characteristics CPI-C maintains a set of internal values, called characteristics, for each conversation. Some characteristics affect the overall operation of the conversation, such as the conversation type. Others affect the operation of specific calls, such as the receive type. Many of these characteristics are initially derived from the side information stored in the SNAplus2 configuration file; see “Side Information”.
Writing CPI-C Applications Initial Conversation Characteristics Table 2-4 Changing Initial Conversation Characteristics (Continued) Accept_Conversation sets: CM_RECEIVE_STATE Initialize_For_Incoming sets: CM_INITIALIZE_INCOMING_STATE Accept_Incoming sets: CM_RECEIVE_STATE Can be changed by: Many CPI-C calls; see the State Change sections at the end of each CPI-C call description in Chapter 3, “CPI-C Calls,” for information about state changes resulting from the call.
Writing CPI-C Applications Initial Conversation Characteristics Table 2-4 Changing Initial Conversation Characteristics (Continued) Fill Initialize_Conversation sets: CM_FILL_LL Accept_Conversation sets: CM_FILL_LL Initialize_For_Incoming sets: CM_FILL_LL Accept_Incoming sets: (Not changed) Can be changed by: Set_Fill Log Data Initialize_Conversation sets: Null string Accept_Conversation sets: Null string Initialize_For_Incoming sets: Null string Accept_Incoming sets: (Not changed) Can b
Writing CPI-C Applications Initial Conversation Characteristics Table 2-4 Changing Initial Conversation Characteristics (Continued) Initialize_For_Incoming sets: (Not set) Accept_Incoming sets: The mode name for the session the conversation start-up request arrived on. Can be changed by: Set_Mode_Name Partner LU Name Initialize_Conversation sets: The partner LU name from the side information, or a single blank if no sym_dest_name is specified.
Writing CPI-C Applications Initial Conversation Characteristics Table 2-4 Changing Initial Conversation Characteristics (Continued) Initialize_Conversation sets: CM_RECEIVE_AND_WAIT Accept_Conversation sets: CM_RECEIVE_AND_WAIT Initialize_For_Incoming sets: CM_RECEIVE_AND_WAIT Accept_Incoming sets: (Not changed) Can be changed by: Set_Receive_Type Return Control Initialize_Conversation sets: CM_WHEN_SESSION_ALLOCATED Accept_Conversation sets: (Not applicable) Initialize_For_Incoming sets: (
Writing CPI-C Applications Initial Conversation Characteristics Table 2-4 Changing Initial Conversation Characteristics (Continued) Can be changed by: Set_Conversation_Security_Type Security User ID Initialize_Conversation sets: The user ID contained in the side information, or a single blank if no sym_dest_name is specified. Accept_Conversation sets: The value specified by the invoking program.
Writing CPI-C Applications Initial Conversation Characteristics Table 2-4 Changing Initial Conversation Characteristics (Continued) Accept_Incoming sets: (Not applicable) Can be changed by: Set_TP_Name TP Name of the Invoked Program (As Seen by the Invoked Program) Initialize_Conversation sets: (Not applicable) Accept_Conversation sets: The value specified by the invoking program. Initialize_For_Incoming sets: (Not set) Accept_Incoming sets: The value specified by the invoking program.
Writing CPI-C Applications Side Information Side Information The information required for two programs to communicate is stored in CPI-C side information entries in the SNAplus2 configuration file. You will need to coordinate with your System Administrator to ensure that it contains what you need. For additional information about configuration, refer to the SNAplus2 Administration Guide.
Writing CPI-C Applications Side Information Partner LU Name This is the name by which the partner LU is known to the local program. It can be an alias of up to eight ASCII characters or a fully qualified network name of up to 17 characters. For the allowed characters, see “Set_Partner_LU_Name (cmspln)” in Chapter 3. Partner Program Type and Name These fields indicate whether the partner program is an application program or SNA service program, and the partner program name.
Writing CPI-C Applications Side Information Application-Specified Side Information NOTE The functions described in this section are not available in Java CPI-C. A Java CPI-C application cannot maintain its own CPI-C side information entries. However, it can override individual parameters in the side information, or determine their values, by using Set_* or Extract_* functions for each required parameter.
Writing CPI-C Applications Side Information • 86 If the side information entry in the configuration file contains a user ID of more than eight characters, you cannot extract it using Extract_CPIC_Side_Information. You must use the Extract_Security_User_ID call. (This does not apply to the password, because CPI-C does not allow the application to extract it.
Writing CPI-C Applications Configuration Configuration The following are considerations when configuring SNAplus2: • In addition to maintaining the side information (specified by sym_dest_name), the System Administrator must define the following entities during configuration to enable CPI-C applications to use SNAplus2's LU 6.2 services: — Modes — Local LUs — Partner LUs — Invokable TPs — Security user IDs and passwords For further information, refer to the SNAplus2 Administration Guide.
Writing CPI-C Applications Specifying the Local TP Name Specifying the Local TP Name When a program issues the Initialize_Conversation, Initialize_Conversation_For_Incoming, or Accept_Conversation call, the CPI-C library generates an instance of a transaction program (TP). You can specify the name of this TP in a number of different ways, described below. The methods are listed in order of precedence.
Writing CPI-C Applications Specifying the Local TP Name APPCTPN Environment Variable The TP name can be specified using the APPCTPN environment variable. For Unix On HP-UX systems the TP name is specified in the APPCTPN environment variable. This environment variable can be set in the following ways: • The program can issue a putenv() call • You can set it in the HP-UX shell.
Writing CPI-C Applications Specifying the Local LU Specifying the Local LU The local LU that an invoking CPI-C TP uses can be specified in a number of ways which are described below. NOTE The local LU for an invoked TP is not specified like this, but is defined by the partner LU value specified in the allocate request. If the LU specified is a dependent LU, multiple concurrent conversations are not supported (because dependent LUs cannot support multiple sessions).
Writing CPI-C Applications Specifying the Local LU Context If there is another TP from which the context is copied, the local LU name is taken from that other TP. For more information about context, see “Multiple Conversations” in Chapter 1. APPCLLU Environment Variable The local LU alias can be specified using the APPCLLU environment variable.
Writing CPI-C Applications Specifying the Local LU Default Local LU Local LUs can be configured to be a part of the default pool of APPC LUs. If no other local LU alias is specified, any suitable LU from this pool is used. Control Point LU SNAplus2 normally has one control point (CP) LU defined on each node. If no other local LU alias is defined then the CP LU is used.
Writing CPI-C Applications How Programs Get Started How Programs Get Started A conversation occurs between an invoking program and an invoked program. The invoking program is started by a user entering a command or by a batch command. The invoked program can either be started manually by a user or automatically by SNAplus2.
Writing CPI-C Applications How Programs Get Started inbound allocation request is received. This timeout value does not apply to a nonqueued program, because the program is always started in response to an inbound allocation request and so there is always one pending. Invoked Program: User-Started If an invoked program is configured to be started by a user, the user can start the invoked program either before or after the invoking program.
Writing CPI-C Applications HP-UX Considerations HP-UX Considerations For Unix This section summarizes the information you need to consider when writing CPI-C applications for HP-UX systems. This includes applications that: • Are single-threaded • Are multithreaded • Use multiple processes If you are writing Java CPI-C applications, see “Java CPI-C Considerations”. CPI-C Header File The header file to be used with CPI-C applications is /usr/include/sna/cmc.h.
Writing CPI-C Applications HP-UX Considerations • Signal-based scheduling mode provides binary compatibility for existing SNAplus2 Release 4 and SNAplus2 Release 5 applications. It is not recommended for new applications because support for signal-based scheduling mode may be discontinued in future versions of SNAplus2. Application Scheduling Mode To receive notification of SNA events in application scheduling mode, the application accesses the file descriptor on which SNA events arrive.
Writing CPI-C Applications HP-UX Considerations NOTE 1. In general, SNA_GET_FD() returns the same file descriptor each time you call it. However, you should call it before each call to select() or poll(), because there are some situations (such as when your application has issued the fork() call, or in error cases) when the file descriptor may change. 2. The SNA event handler processes internal control messages between SNAplus2 components, in addition to processing the completion of CPI-C functions.
Writing CPI-C Applications HP-UX Considerations The following restrictions apply to SIGPOLL() usage: • Applications must not permanently disable this signal. The sighold() and sigrelse() signal calls can be used to protect a critical region of code, provided that no SNA verbs are issued between sighold() and sigrelse(). • Applications must preserve the address of the SNAplus2 signal catchers returned by the sigset() call when adding signal catchers to applications.
Writing CPI-C Applications HP-UX Considerations Two or more instances of the same program can run as different processes, but each instance will be assigned its own conversation_ID. You can write an application in which one process contains many conversations, each with its own conversation_ID. However, you need to design the application carefully to avoid “deadlock” situations, in which a CPI-C call is unable to complete because of the state of other conversations in the same process.
Writing CPI-C Applications HP-UX Considerations Back Level Applications New applications will use dynamic libraries in /opt/sna/lib/hpux32 or /opt/sna/lib/hpux64 as described above. SNAplus2 release 6.2 also includes a set of dynamic libraries to support existing applications that have been built with previous versions of SNAplus or SNAplus2 on PA-Risc systems. These libraries are on /opt/sna/lib or /opt/sna/lib/pa20_64.
Writing CPI-C Applications Java CPI-C Considerations Java CPI-C Considerations This section summarizes the information you need to consider when writing Java CPI-C applications. Using Java CPI-C Classes The Java CPI-C package is named COM.ibm.eNetwork.cpic.
Writing CPI-C Applications Java CPI-C Considerations Table 2-5 Java CPI-C Constants (Continued) Parameter Length Java CPI-C Constant Symbolic Destination Name Length CM_SDN_SIZE Transaction Program (TP) Name length CM_TPN_SIZE Parameter Type Classes Many parameters used in CPI-C functions take one of a set of two or more defined values. In the Java CPI-C package, each of these parameter types is defined as a class containing the valid values.
Writing CPI-C Applications Java CPI-C Considerations Returns true if the value stored in the object is equal to the supplied integer value int_value. boolean equals(supplied_object) Returns true if the value stored in the object is equal to the value stored in the supplied parameter supplied_object. supplied_object must itself be an instance of one of the Java CPI-C parameter classes.
Writing CPI-C Applications Java CPI-C Considerations CPICReturnCode cpicReturn = new CPICReturnCode(); cpicReturn.intValue(0); Step 2. Issue the function call: cpicObject.cminit(bConversationId, sSymbolicDestination, cpicReturn); Step 3. Test the return code against a specific value: if (cpicReturn.intValue() != CPICReturnCode.CM_PARAMETER_ERROR) . . . Alternatively, check whether the return code is CM_OK: try { cpicReturn.isOK(); } catch(CPICReturncode c) { . . .
Writing CPI-C Applications Java CPI-C Considerations Run the application using the Java interpreter java in the normal way.
Writing CPI-C Applications Windows Considerations Windows Considerations For Windows This section summarizes processing considerations you need to be aware of when developing programs on a Windows client. Windows CPI-C Files The header file to be used with Windows CPI-C applications is wincpic.h, which contains the definitions of all CPI-C entry points, and the defined constants for supplied and returned parameter values at the Windows CPI-C interface.
Writing CPI-C Applications Windows Considerations WinCPICStartup() Registers the application as a Windows CPI-C user, and determines whether the CPI-C software supports the level of function required by the application. WinCPICCleanup() Unregisters the application when it has finished using CPI-C. WinCPICIsBlocking() Checks whether there is a blocking call outstanding for this application. For more information about the circumstances in which this call may be required, see “Blocking Calls”.
Writing CPI-C Applications Windows Considerations Blocking Calls This section describes how blocking CPI-C calls (calls issued with the conversation's processing mode set to CM_BLOCKING) operate in the Win32 environment if the calling application is single-threaded. (Typically, a Win32 application would use multiple threads to avoid the problem of a blocking verb blocking the entire application.
Writing CPI-C Applications Windows Considerations • Issue CPI-C calls on other conversations for which the processing mode is CM_NON_BLOCKING Default Blocking Function The standard blocking function used by the Windows CPI-C library is as follows: BOOL DefaultBlockingHook (void) { MSG msg; /* get the next message if any */ if ( PeekMessage (&msg,0,0,PM_NOREMOVE) ) { if ( msg.
Writing CPI-C Applications Windows Considerations Compiler Options for Structure Packing The structures supplied and returned on some CPI-C calls are not packed. Do not use compiler options that change this packing method. BYTE parameters are on BYTE boundaries, WORD parameters are on WORD boundaries, and DWORD parameters are on DWORD boundaries. Header Files The header file to be included in Windows CPI-C applications is named wincpic.h.
Writing CPI-C Applications Writing Portable Applications Writing Portable Applications The following guidelines are provided for writing CPI-C applications that they are portable to other operating system environments or other CPI-C implementations: • Include the CPI-C header file without any pathname prefix. Use include options on the compiler to locate the file (see the appropriate section for your operating system, earlier in this chapter).
Writing CPI-C Applications Writing Portable Applications use in other Java CPI-C environments. You may want to restrict the use of these functions to a few specific routines, to allow easier modification. • 112 The Java CPI-C class includes some CPI-C functions not described in this manual, which are defined as part of the Java class but not supported.
3 CPI-C Calls This chapter describes the CPI-C function calls and the additional Windows-specific function calls used by CPI-C applications.
CPI-C Calls 114 • An explanation of the information provided for the calls • The call descriptions Chapter 3
CPI-C Calls Information Provided for CPI-C Calls Information Provided for CPI-C Calls The following information is supplied for each CPI-C call described in this chapter: • The pseudonym for the call, followed by the actual C function name in parentheses (this information is in the section heading). • The function prototype for the call, including the parameters used by the call and the data type for each parameter. The prototype of each function is declared in the file /usr/include/sna/cmc.
CPI-C Calls Information Provided for CPI-C Calls To improve the portability of CPI-C applications, the data types for the parameters supplied to, and received from, CPI-C are established as symbolic constants by #define statements in the CPI-C header file. For example, CM_INT32 represents a 32-bit integer type; CM_PTR represents a pointer type, “*” on HP-UX and Win32 systems. This chapter uses these symbolic constants to identify the data types for supplied and returned parameters.
CPI-C Calls Information Provided for CPI-C Calls CM_MAPPED_CONVERSATION represents the integer 1. For the sake of portability and readability, use only the symbolic constants when writing programs. Strings All strings are in ASCII format when passed across the CPI-C interface. Validity of Returned Parameters The parameters returned by CPI-C are valid only if the CPI-C call is executed successfully, as indicated by a return code of CM_OK.
CPI-C Calls Information Provided for Windows Function Calls Information Provided for Windows Function Calls For Windows The following information is supplied for each of the Windows-specific function calls described in this chapter: • The name of the call; unlike the CPI-C function calls, these calls do not have pseudonyms. • A description of the call. • The function prototype for the call, including the parameters used by the call and the data type for each parameter.
CPI-C Calls Accept_Conversation (cmaccp) Accept_Conversation (cmaccp) The Accept_Conversation call is issued by the invoked program to accept the incoming conversation and set certain conversation characteristics. For a list of initial conversation characteristics, see Chapter 2, “Writing CPI-C Applications.” Upon successful execution of this call, CPI-C generates an 8-byte conversation identifier.
CPI-C Calls Accept_Conversation (cmaccp) CM_PROGRAM_STATE_CHECK This value indicates one of the following conditions: • No incoming Allocate request was received within the timeout period specified in the configuration. • The application has not specified any local TP names (or, for HP-UX systems, has released all specified names). The application must have at least one local TP name before issuing this call.
CPI-C Calls Accept_Conversation (cmaccp) Usage Notes The TP name can be specified in a number of ways. For more information about specifying local TP names, see “Specifying the Local TP Name” in Chapter 2. Before issuing Accept_Conversation, the program can issue Specify_Local_TP_Name to indicate one or more TP names for which it will accept incoming Allocates (these names are in addition to names defined in other ways such as the APPCTPN environment variable).
CPI-C Calls Accept_Incoming (cmacci) Accept_Incoming (cmacci) For Unix The Accept_Incoming call is issued by the invoked program to accept an incoming conversation that has previously been initialized with Initialize_For_Incoming, and to set certain conversation characteristics. For a list of initial conversation characteristics, see “Initial Conversation Characteristics” in Chapter 2.
CPI-C Calls Accept_Incoming (cmacci) return_code Possible values are: CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid. CM_PROGRAM_STATE_CHECK One of the following occurred: • The conversation specified by conversation_ID is not in Initialize-Incoming state. • No incoming Allocate request was received within the timeout period specified in the configuration.
CPI-C Calls Accept_Incoming (cmacci) CM_OPERATION_INCOMPLETE CM_OPERATION_NOT_ACCEPTED CM_PRODUCT_SPECIFIC_ERROR State When Issued The conversation must be in Initialize-Incoming state. State Change If the call is successful, the conversation changes to Receive state. If the call fails, the state remains unchanged. Usage Notes Issuing Initialize_For_Incoming followed by Accept_Incoming is equivalent to issuing Accept_Conversation.
CPI-C Calls Accept_Incoming (cmacci) conversation, but the program's current context is not changed. To use the new context, the program must issue Extract_Conversation_Context for this conversation_ID to get the value of the conversation's context, and Set_Conversation_Context to set the program's current context to this value.
CPI-C Calls Allocate (cmallc) Allocate (cmallc) The Allocate call is issued by the invoking program to allocate a conversation with the partner program, using the current conversation characteristics. CPI-C can also allocate a session between the local LU and partner LU if one does not already exist. The type of conversation allocated is based on the conversation type characteristic—mapped or basic.
CPI-C Calls Allocate (cmallc) Supplied Parameters The supplied parameter is: conversation_ID This is the conversation identifier. The value of this parameter is returned by the Initialize_Conversation call. Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. return_code Possible values are: CM_OK The call executed successfully.
CPI-C Calls Allocate (cmallc) CM_PRODUCT_SPECIFIC_ERROR State When Issued The conversation must be in Initialize state. State Change State changes, summarized in Table 3-1, “State Changes for the Allocate Call,” are based on the value of the return_code parameter.
CPI-C Calls Cancel_Conversation (cmcanc) End of Section Cancel_Conversation (cmcanc) The Cancel_Conversation call ends a specified conversation, canceling any incomplete operation (a previous call that returned with CM_OPERATION_INCOMPLETE) on this conversation, and ends the session that the conversation was using.
CPI-C Calls Cancel_Conversation (cmcanc) Function Call for Java CPI-C public native void cmcanc ( byte[] conversation_ID, CPICReturnCode return_code ); Supplied Parameters The supplied parameter is: conversation_ID This is the identifier for the conversation. The value of this parameter is returned by the Initialize_Conversation, Initialize_For_Incoming, or Accept_Conversation call.
CPI-C Calls Cancel_Conversation (cmcanc) Usage Notes The partner program is notified of the end of the conversation with the return code CM_DEALLOCATED_ABEND.
CPI-C Calls Check_For_Completion (cmchck) Check_For_Completion (cmchck) For Unix This function is not available in Java CPI-C. The Check_For_Completion call checks whether a previous call that returned with CM_OPERATION_INCOMPLETE has since completed.
CPI-C Calls Check_For_Completion (cmchck) This value is relevant only if the return_code parameter is set to CM_OK. return_code Possible values are: CM_OK The call executed successfully. A previously outstanding call on the conversation specified by conversation_ID has completed. CM_PROGRAM_STATE_CHECK There are no previously incomplete calls outstanding.
CPI-C Calls Check_For_Completion (cmchck) If more than one call has completed since the application last issued Check_For_Completion or Wait_For_Conversation, issuing Check_For_Completion more than once does not necessarily return information about additional calls; it simply indicates that at least one call has completed, and therefore a subsequent Wait_For_Conversation call will return immediately and not block.
CPI-C Calls Confirm (cmcfm) Confirm (cmcfm) The Confirm call sends the contents of the local LU's send buffer and a confirmation request to the partner program and waits for confirmation. In response to the Confirm call, the partner program normally issues the Confirmed call to confirm that it has received the data without error. (If the partner program encounters an error, it issues the Send_Error call or uses the Deallocate call to abnormally deallocate the conversation.
CPI-C Calls Confirm (cmcfm) Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. request_to_send_received This is the request-to-send-received indicator. Possible values are: CM_REQ_TO_SEND_RECEIVED The partner program has issued the Request_To_Send call, which requests the local program to change the conversation to Receive state.
CPI-C Calls Confirm (cmcfm) • 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. For an explanation of the following return codes, see Appendix A, “Common Return Codes.
CPI-C Calls Confirm (cmcfm) State Change State changes, summarized in Table 3-2, “State Changes for the Confirm Call,” are based on the value of the return_code parameter.
CPI-C Calls Confirm (cmcfm) Table 3-2 State Changes for the Confirm Call return_code New state CM_OK (Call issued in Send state) No change CM_OK (Call issued in Send-Pending state) Send CM_PROGRAM_ERROR_PURGING CM_SVC_ERROR_PURGING Receive CM_CONVERSATION_TYPE_MISMATCH CM_PIP_NOT_SPECIFIED_CORRECTLY CM_SECURITY_NOT_VALID CM_SYNC_LEVEL_NOT_SUPPORTED_PGM CM_SYNC_LEVEL_NOT_SUPPORTED_LU CM_TPN_NOT_RECOGNIZED CM_TP_NOT_AVAILABLE_NO_RETRY CM_TP_NOT_AVAILABLE_RETRY CM_RESOURCE_FAILURE_NO_RETRY CM_RESOURC
CPI-C Calls Confirmed (cmcfmd) Confirmed (cmcfmd) The Confirmed call 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, the Confirmed call synchronizes the processing of the two programs.
CPI-C Calls Confirmed (cmcfmd) CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid. CM_PROGRAM_STATE_CHECK When the program issued this call the conversation was not in Confirm, Confirm-Send, or Confirm-Deallocate state. For an explanation of the following return codes, see Appendix A, “Common Return Codes.
CPI-C Calls Confirmed (cmcfmd) Usage Notes The following sections describe additional usage information for the Confirmed call.
CPI-C Calls Confirmed (cmcfmd) Chapter 3 • CM_CONFIRM_SEND_RECEIVED • CM_CONFIRM_DEALLOC_RECEIVED 143
CPI-C Calls Convert_Incoming (cmcnvi) Convert_Incoming (cmcnvi) For Unix The Convert_Incoming call converts a character string from EBCDIC to ASCII. If the partner application sends data consisting of EBCDIC character strings, the local application can use Convert_Incoming to convert these strings to ASCII. (CPI-C parameters other than the data in Send_Data and Receive calls, such as mode_name and TP_name, are always specified in ASCII and do not require conversion.
CPI-C Calls Convert_Incoming (cmcnvi) ! # $ @ \ { } ~ ` (backward quotation mark) | (solid vertical bar) [brvbar] (broken vertical bar) ¬ (NOT character) ¢ (cent) The contents of this string (up to the number of characters specified in string_length) will be replaced by the ASCII string resulting from the conversion. string_length This is the number of characters to be converted (1–32,767).
CPI-C Calls Convert_Incoming (cmcnvi) State Change There is no state change. Usage Note When data is being received in buffer format in a basic conversation (as specified by the Set_Fill call), the data buffer can contain multiple logical records, each consisting of a two-byte or four-byte header (LLID) followed by data. The application must extract and convert each data string separately (not including the headers).
CPI-C Calls Convert_Outgoing (cmcnvo) Convert_Outgoing (cmcnvo) For Unix The Convert_Outgoing call converts a character string from ASCII to EBCDIC. If the partner application requires data consisting of EBCDIC character strings, the local application can use Convert_Outgoing to convert data from ASCII to EBCDIC before sending it. (CPI-C parameters other than the data in Send_Data and Receive calls, such as mode_name and TP_name, are always specified in ASCII and do not require conversion.
CPI-C Calls Convert_Outgoing (cmcnvo) ! # $ @ \ { } ~ ` (backward quotation mark) | (solid vertical bar) [brvbar] (broken vertical bar) ¬ (NOT character) ¢ (cent) The contents of this string (up to the number of characters specified in string_length) will be replaced by the EBCDIC string resulting from the conversion. string_length This is the number of characters to be converted (1–32,767).
CPI-C Calls Convert_Outgoing (cmcnvo) State Change There is no state change. Usage Note When data is being sent in buffer format in a basic conversation (as specified by the Set_Fill call), the data buffer can contain multiple logical records, each consisting of a two-byte or four-byte header (LLID) followed by data. The application must convert each data string separately (not including the headers).
CPI-C Calls Deallocate (cmdeal) Deallocate (cmdeal) The Deallocate call deallocates a conversation between two programs. Before deallocating the conversation, this call performs the equivalent of either the Flush call or the Confirmed call, depending on the current conversation synchronization level and deallocate type. The deallocate type is set by the Set_Deallocate_Type call.
CPI-C Calls Deallocate (cmdeal) Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. return_code Possible values are: CM_OK The call executed successfully, the conversation is deallocated. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid.
CPI-C Calls Deallocate (cmdeal) CM_SVC_ERROR_PURGING CM_SYNC_LVL_NOT_SUPPORTED_PGM CM_SYNC_LVL_NOT_SUPPORTED_LU CM_TP_NOT_AVAILABLE_NO_RETRY CM_TP_NOT_AVAILABLE_RETRY CM_TPN_NOT_RECOGNIZED CM_PROGRAM_ERROR_PURGING CM_RESOURCE_FAILURE_NO_RETRY CM_RESOURCE_FAILURE_RETRY State When Issued The conversation can be in one of the states shown in Table 3-4, Conversation States When Issuing the Deallocate Call, when the program issues the Deallocate call.
CPI-C Calls Deallocate (cmdeal) Table 3-5 State Changes for the Deallocate Call (Continued) return_code New state CM_CONVERSATION_TYPE_MISMATCH CM_PIP_NOT_SPECIFIED_CORRECTLY CM_SECURITY_NOT_VALID CM_SYNC_LEVEL_NOT_SUPPORTED_PGM CM_SYNC_LEVEL_NOT_SUPPORTED_LU CM_TPN_NOT_RECOGNIZED CM_TP_NOT_AVAILABLE_NO_RETRY CM_TP_NOT_AVAILABLE_RETRY Reset CM_RESOURCE_FAILURE_NO_RETRY CM_RESOURCE_FAILURE_RETRY Reset CM_DEALLOCATED_ABEND CM_DEALLOCATED_ABEND_SVC CM_DEALLOCATED_ABEND_TIMER Reset All others No chan
CPI-C Calls Delete_CPIC_Side_Information (xcmdsi) Delete_CPIC_Side_Information (xcmdsi) This function is not available in Java CPI-C. The Delete_CPIC_Side_Information call deletes a side information entry that the application has previously specified using Set_CPIC_Side_Information, or specifies that an entry in the configuration file is no longer available for use by this application. This entry is identified through the symbolic destination name.
CPI-C Calls Delete_CPIC_Side_Information (xcmdsi) CM_PROGRAM_PARAMETER_CHECK The sym_dest_name parameter has specified a nonexistent side information entry. CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued The call is not associated with a conversation. State Change There is no state change. Usage Notes This call does not modify the side information held in the configuration file; the change applies only to this application.
CPI-C Calls Extract_Conversation_Context (cmectx) Extract_Conversation_Context (cmectx) For Unix The Extract_Conversation_Context call returns the context for a specified conversation. This enables the program to set its current context to the required value (using Set_Conversation_Context) before starting a new conversation, to ensure that the new conversation uses the same context.
CPI-C Calls Extract_Conversation_Context (cmectx) context_ID This parameter contains the context of the specified conversation. It is valid only if the return_code parameter is CM_OK. context_ID_length This parameter contains the length of context_ID (1–32 bytes). It is valid only if the return_code parameter is CM_OK. return_code Possible values are: CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid.
CPI-C Calls Extract_Conversation_Context (cmectx) • When a CPI-C call that assigns a new context completes in nonblocking mode. For example, if Accept_Incoming completes immediately with return_code CM_OK, the program's current context is set to the context of the new conversation; however, if Accept_Incoming returns CM_OPERATION_INCOMPLETE, a subsequent Wait_For_Conversation that returns the result of Accept_Incoming does not change the program's current context.
CPI-C Calls Extract_Conversation_Security_Type (xcecst) Extract_Conversation_Security_Type (xcecst) This function is not available in Java CPI-C. The Extract_Conversation_Security_Type call returns the security type for a specified conversation. This call is provided for compatibility with X/Open CPI-Cand with the Windows CPI-C specification; it is not included in IBM CPI-C 2.0.
CPI-C Calls Extract_Conversation_Security_Type (xcecst) “Concepts.” If program A invokes program B with a valid user ID and password, and program B in turn invokes program C, then if program B specifies the value CM_SECURITY_SAME, CPI-C will send an already-verified indicator to the LU for program C. This indicator tells program C not to require the password (if program C is configured to accept an already-verified indicator).
CPI-C Calls Extract_Conversation_Security_Type (xcecst) State Change There is no state change.
CPI-C Calls Extract_Conversation_Security_User_ID (cmecsu) Extract_Conversation_Security_User_ID (cmecsu) For Unix This call is the Windows CPI-C equivalent of the HP-UX CPI-C call Extract_Security_User_ID (cmesui). The two calls are used in exactly the same way, except that the names are different.
CPI-C Calls Extract_Conversation_Security_User_ID (xcecsu) Extract_Conversation_Security_User_ID (xcecsu) This function is not available in Java CPI-C. This call returns the user ID being used in a specified conversation. The call provides compatibility for applications using the X/Open CPI-C definition. It has been incorporated into IBM CPI-C 2.0 as the call Extract_Security_User_ID (cmesui). Use cmesui whenever possible to enable greater portability of your program to other platforms.
CPI-C Calls Extract_Conversation_State (cmecs) Extract_Conversation_State (cmecs) The Extract_Conversation_State call returns the state of the specified conversation.
CPI-C Calls Extract_Conversation_State (cmecs) CM_RECEIVE_STATE CM_SEND_PENDING_STATE CM_CONFIRM_STATE CM_CONFIRM_SEND_STATE CM_CONFIRM_DEALLOCATE_STATE return_code Possible values are: CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid. For an explanation of the following return codes, see Appendix A, “Common Return Codes.
CPI-C Calls Extract_Conversation_Type (cmect) Extract_Conversation_Type (cmect) The Extract_Conversation_Type call returns the conversation type (mapped or basic) of the specified conversation.
CPI-C Calls Extract_Conversation_Type (cmect) CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid. CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued The conversation can be in any state except Reset. State Change There is no state change.
CPI-C Calls Extract_CPIC_Side_Information (xcmesi) Extract_CPIC_Side_Information (xcmesi) This function is not available in Java CPI-C. The Extract_CPIC_Side_Information call returns the side information for an entry number or symbolic destination name. This call is provided for compatibility with X/Open CPI-Cand with the Windows CPI-C specification; it is not included in IBM CPI-C 2.0.
CPI-C Calls Extract_CPIC_Side_Information (xcmesi) sym_dest_name This parameter specifies the symbolic destination name to search for. It is an 8-byte ASCII character string and can contain any displayable characters. side_info_entry_length For Unix This value must always be set to sizeof(SIDE_INFO)(). For Windows This value must always be set to 124.
CPI-C Calls Extract_CPIC_Side_Information (xcmesi) example, if the hexadecimal representation of the name is 0x21F0F0F8, set the TP_name parameter to the 8–character string “21F0F0F8”. The first character (represented by two bytes) must be a hexadecimal value in the range 0x0–0x3F, excluding 0x0E and 0x0F; the remaining characters (each represented by two bytes) must be valid EBCDIC characters. side_info_entry.TP_name TP name of the target TP. side_info_entry.
CPI-C Calls Extract_CPIC_Side_Information (xcmesi) side_info_entry.security_user_ID User ID used to access the partner TP. This parameter is not required if the conversation_security_type parameter is set to XC_SECURITY_NONE. For compatibility with X/Open CPI-C, this verb only returns eight characters for the user ID, although security user IDs can be up to 10 characters.
CPI-C Calls Extract_CPIC_Side_Information (xcmesi) Usage Notes If the security user ID in the side information is not set, the security user ID field is returned filled with spaces.
CPI-C Calls Extract_Local_LU_Name (cmelln) Extract_Local_LU_Name (cmelln) The Extract_Local_LU_Name call returns the following for a specified conversation: • The alias of the local LU • The length of the alias of the local LU This call is not part of the standard CPI-C specification, and may not be available in other implementations. In particular, it is not supported in other Java CPI-C implementations.
CPI-C Calls Extract_Local_LU_Name (cmelln) Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. lu_alias This parameter specifies the starting address of the LU alias. return_code Possible values are: CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid.
CPI-C Calls Extract_Maximum_Buffer_Size (cmembs) Extract_Maximum_Buffer_Size (cmembs) For Unix The Extract_Maximum_Buffer_Size call returns the maximum size of a CPI-C data buffer. This defines the maximum amount of data that can be sent in one Send_Data call or received in one Receive call. SNAplus2 CPI-C (including previous versions) always uses a data buffer size of 32,767 bytes.
CPI-C Calls Extract_Maximum_Buffer_Size (cmembs) CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued This call is not associated with any conversation. State Change There is no state change.
CPI-C Calls Extract_Mode_Name (cmemn) Extract_Mode_Name (cmemn) The Extract_Mode_Name call returns the mode name and mode name length for a specified conversation.
CPI-C Calls Extract_Mode_Name (cmemn) mode_name_length This parameter specifies the length of the mode name. return_code Possible values are: CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid. CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued The conversation can be in any state except Reset. State Change There is no state change.
CPI-C Calls Extract_Partner_LU_Name (cmepln) Extract_Partner_LU_Name (cmepln) The Extract_Partner_LU_Name call returns the partner LU name and partner LU name length for a specified conversation. This can be an alias name of up to eight bytes or a fully qualified network name of up to 17 bytes.
CPI-C Calls Extract_Partner_LU_Name (cmepln) partner_LU_name This parameter specifies the variable containing the partner LU name. (The program must supply a pointer to a suitable variable.) partner_LU_name_length This parameter specifies the length of the partner LU name. return_code Possible values are: CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid.
CPI-C Calls Extract_Security_User_ID (cmesui or cmecsu) Extract_Security_User_ID (cmesui or cmecsu) The Extract_Security_User_ID call returns the user ID being used in a specified conversation. For Windows This call is named Extract_Conversation_Security_User_ID, with the pseudonym cmecsu, for compatibility with the Windows CPI-C interface.
CPI-C Calls Extract_Security_User_ID (cmesui or cmecsu) security_user_ID This specifies the user ID used to establish the conversation. security_user_ID_length This specifies the length of security_user_ID. The range for this value is 1–10 characters (HP-UX systems), or 1–8 characters (Windows systems). If the security_user_ID_length is set to 0 (zero), the security_user_ID_length parameter is ignored; this is equivalent to setting security_user_ID to a null string.
CPI-C Calls Extract_Sync_Level (cmesl) Extract_Sync_Level (cmesl) The Extract_Sync_Level call returns the synchronization level for a specified conversation.
CPI-C Calls Extract_Sync_Level (cmesl) CM_CONFIRM return_code The programs can perform confirmation processing. Possible values are: CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid. CM_PROGRAM_STATE_CHECK The conversation specified by conversation_ID is in Initialize-Incoming state. CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.
CPI-C Calls Extract_TP_Name (cmetpn) Extract_TP_Name (cmetpn) The Extract_TP_Name call returns the TP name and TP name length of the invoked TP for a specified conversation. An application that has used the Specify_Local_TP_Name call to accept incoming Allocates for more than one TP name, and has subsequently issued Accept_Conversation or Accept_Incoming to accept an incoming Allocate, can use this call to determine which TP name was specified on the incoming Allocate.
CPI-C Calls Extract_TP_Name (cmetpn) Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. TP_name This parameter specifies the starting address of the TP name. TP_name_length This parameter specifies the length of the TP name. return_code Possible values are: CM_OK The call executed successfully.
CPI-C Calls Flush (cmflus) Flush (cmflus) The Flush call 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. Sources of Buffered Data Data processed by the Send_Data call 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 the Set_Send_Type call, include flush functionality.
CPI-C Calls Flush (cmflus) Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. return_code Possible values are: CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid. CM_PROGRAM_STATE_CHECK The conversation was not in Send or Send-Pending state when the program issued this call.
CPI-C Calls Initialize_Conversation (cminit) Initialize_Conversation (cminit) The Initialize_Conversation call is issued by the invoking program to obtain an 8-byte conversation ID and to set the initial values for the conversation's characteristics. The initial values are CPI-C defaults or are derived from side information associated with the symbolic destination name. For more information about initial values and side information, see Chapter 2, “Writing CPI-C Applications.
CPI-C Calls Initialize_Conversation (cminit) The parameter is an 8-byte ASCII character string and can contain any displayable characters. This parameter can also be set to eight spaces. In this case, the invoking program must issue the following calls before issuing the Allocate call: • Set_Mode_Name • Set_Partner_LU_Name • Set_TP_Name For more details about the side information entry, see Appendix A, “Common Return Codes.
CPI-C Calls Initialize_Conversation (cminit) State When Issued The conversation is in Reset state. State Change If the return_code is CM_OK, the conversation changes to Initialize state. For other return codes, the conversation state remains unchanged. Usage Notes If the side information contains a value that is not valid for a conversation characteristic, or if a Set_* call sets it to a value that is not valid, then the error is returned on the Allocate call.
CPI-C Calls Initialize_For_Incoming (cminic) Initialize_For_Incoming (cminic) For Unix The Initialize_For_Incoming call is issued by the invoked program to obtain an 8-byte conversation ID. The program then accepts the conversation using the Accept_Incoming call. Issuing Initialize_For_Incoming followed by Accept_Incoming is equivalent to issuing Accept_Conversation.
CPI-C Calls Initialize_For_Incoming (cminic) CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued The conversation is in Reset state. State Change If the return_code is CM_OK, the conversation changes to Initialize state. Otherwise the conversation state remains unchanged.
CPI-C Calls Prepare_To_Receive (cmptr) Prepare_To_Receive (cmptr) The Prepare_To_Receive call changes the state of the conversation for the local program from Send to Receive.
CPI-C Calls Prepare_To_Receive (cmptr) Function Call for Java CPI-C public native void cmptr ( byte[] conversation_ID, CPICReturnCode return_code ); Supplied Parameters The supplied parameter is: conversation_ID This is the identifier for the conversation. The value of this parameter is returned by the Initialize_Conversation, Initialize_For_Incoming, or Accept_Conversation call.
CPI-C Calls Prepare_To_Receive (cmptr) The following 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_PREP_TO_RECEIVE_SYNC_LEVEL, and the conversation's synchronization level is set to CM_CONFIRM. For an explanation of them, see Appendix A, “Common Return Codes.”.
CPI-C Calls Prepare_To_Receive (cmptr) Table 3-6 State Changes for the Prepare_To_Receive Call (Continued) return_code New state CM_CONVERSATION_TYPE_MISMATCH CM_PIP_NOT_SPECIFIED_CORRECTLY CM_SECURITY_NOT_VALID CM_SYNC_LEVEL_NOT_SUPPORTED_PGM CM_SYNC_LEVEL_NOT_SUPPORTED_LUCM_ TPN_NOT_RECOGNIZED CM_TP_NOT_AVAILABLE_NO_RETRY CM_TP_NOT_AVAILABLE_RETRY Reset CM_DEALLOCATED_ABEND CM_RESOURCE_FAILURE_NO_RETRY CM_RESOURCE_FAILURE_RETRY Reset CM_DEALLOCATED_ABEND_SVC CM_DEALLOCATED_ABEND_TIMER Reset All
CPI-C Calls Receive (cmrcv) Receive (cmrcv) The Receive call receives any data that is currently available from the partner program. If no data is currently available and the receive type (set by the Set_Receive_Type call) 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.
CPI-C Calls Receive (cmrcv) — 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.
CPI-C Calls Receive (cmrcv) Supplied Parameters The supplied parameters are: conversation_ID This is the identifier for the conversation. The value of this parameter was returned by the Initialize_Conversation, Initialize_For_Incoming, or Accept_Conversation call. requested_length This indicates the maximum number of bytes of data the local program is to receive. The range for this value is 0–32,767. buffer This is the address of the buffer to contain the data received by the local program.
CPI-C Calls Receive (cmrcv) • A change to another conversation state, based on the return_code, status_received, and data_received parameters • 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.
CPI-C Calls Receive (cmrcv) received data was truncated, the length of the data will be less than requested_length.) Upon receiving this value, the local program normally reissues the Receive call to receive the next part of the record. CM_NO_DATA_RECEIVED The program did not receive data. NOTE If the return_code parameter is set to CM_OK, status information may be available through the status_received parameter.
CPI-C Calls Receive (cmrcv) CM_CONFIRM_DEALLOC_RECEIVED The partner program has issued the Deallocate call 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 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.
CPI-C Calls Receive (cmrcv) This value is not relevant if the return_code parameter is set to one of the following: return_code • CM_PROGRAM_PARAMETER_CHECK • CM_PROGRAM_STATE_CHECK Possible values are: CM_OK The call executed successfully. CM_UNSUCCESSFUL The receive type is set to CM_RECEIVE_IMMEDIATE, and no data or status information is currently available from the partner program. CM_DEALLOCATED_NORMAL The conversation has been deallocated normally.
CPI-C Calls Receive (cmrcv) • 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 • The basic 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.
CPI-C Calls Receive (cmrcv) State When Issued 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. For Windows If the application successfully issues the Receive call in nonblocking mode, the conversation changes state twice. On the initial return of the call, the conversation changes to Pending-Post state.
CPI-C Calls Receive (cmrcv) Call Issued in Receive State The state changes shown in Table 3-7, State Changes When the Receive Call Is Issued in Receive State, can occur when the Receive call is issued with the conversation in Receive state and the return_code is CM_OK.
CPI-C Calls Receive (cmrcv) Table 3-8 State Changes When the Receive Call Is Issued in Send State data_received status_received New state CM_NO_DATA_RECEIVED CM_SEND_RECEIVED No change Call Issued in Send-Pending State The state changes shown in Table 3-9, State Changes When the Receive Call Is Issued in Send-Pending State, can occur when the Receive call is issued with the conversation in Send-Pending state and the return_code is CM_OK.
CPI-C Calls Receive (cmrcv) • Table 3-10 The status_received parameter indicates a change to a confirm state, as shown in Table 3-10, “State Changes When the Receive Call Is Issued in Any Allowable State.
CPI-C Calls Receive (cmrcv) Errors The state changes shown in Table 3-11, State Changes Caused by a Data Transmission Error, can occur when a data transmission error is encountered. (This is indicated by one of the following return codes: CM_PROGRAM_ERROR_PURGING, CM_PROGRAM_ERROR_NO_TRUNC, CM_SVC_ERROR_PURGING, or CM_SVC_ERROR_NO_TRUNC.
CPI-C Calls Receive (cmrcv) to 0), the data_received parameter is set to CM_COMPLETE_DATA_RECEIVED with the received_length parameter set to 0 (zero). In a basic conversation in which data is available and the fill characteristic is set to CM_FILL_LL, the data_received parameter is set to CM_INCOMPLETE_DATA_RECEIVED. If the fill characteristic is set to CM_FILL_BUFFER, the data_received is set to CM_DATA_RECEIVED.
CPI-C Calls Release_Local_TP_Name (cmrltp) Release_Local_TP_Name (cmrltp) For Unix The Release_Local_TP_Name call is issued by a program to indicate that it will no longer accept incoming Allocate requests for a TP name. The TP name may have been specified using any of the methods described in “Specifying the Local TP Name” in Chapter 2.
CPI-C Calls Release_Local_TP_Name (cmrltp) CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK One of the following has occurred: • The value specified by TP_name is not a TP name associated with this program • The value specified by TP_name_length is out of range CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued This call is not associated with a conversation. State Change There is no state change.
CPI-C Calls Request_To_Send (cmrts) Request_To_Send (cmrts) The Request_To_Send call notifies the partner program that the local program wants to send data.
CPI-C Calls Request_To_Send (cmrts) Supplied Parameters The supplied parameter is: conversation_ID This is the identifier for the conversation. The value of this parameter was returned by the Initialize_Conversation, Initialize_For_Incoming, or Accept_Conversation call. Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful.
CPI-C Calls Request_To_Send (cmrts) Usage Notes 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.
CPI-C Calls Send_Data (cmsend) Send_Data (cmsend) The Send_Data call puts data in the local LU's send buffer for transmission to the partner program. The data collected in the local LU's send buffer is transmitted to the partner LU (and partner program) when one of the following occurs: • The send buffer fills up. • The local program issues a Flush, Confirm, or Deallocate call or other call that flushes the LU's send buffer. (Some send types, set by the Set_Send_Type call, include flush functionality.
CPI-C Calls Send_Data (cmsend) Supplied Parameters The supplied parameters are: conversation_ID This is the identifier for the conversation. The value of this parameter was returned by the Initialize_Conversation, Initialize_For_Incoming, or Accept_Conversation call. buffer This parameter specifies the address of the buffer containing the data to be put in the local LU's send buffer. send_length This is the number of bytes of data to be put in the local LU's send buffer.
CPI-C Calls Send_Data (cmsend) CM_OK The call executed successfully.
CPI-C Calls Send_Data (cmsend) CM_OPERATION_INCOMPLETE CM_OPERATION_NOT_ACCEPTED CM_PIP_NOT_SPECIFIED_CORRECTLY CM_PRODUCT_SPECIFIC_ERROR CM_PROGRAM_ERROR_PURGING CM_RESOURCE_FAILURE_NO_RETRY CM_RESOURCE_FAILURE_RETRY CM_SECURITY_NOT_VALID CM_SVC_ERROR_PURGING CM_SYNC_LVL_NOT_SUPPORTED_PGM CM_SYNC_LVL_NOT_SUPPORTED_LU CM_TP_NOT_AVAILABLE_NO_RETRY CM_TP_NOT_AVAILABLE_RETRY CM_TPN_NOT_RECOGNIZED State When Issued The conversation must be in Send or Send-Pending state when the program issues this call.
CPI-C Calls Send_Data (cmsend) Usage Notes The LU does not automatically perform any conversion between ASCII and EBCDIC on the string of data to be sent. For Unix If the remote program requires data to be sent in EBCDIC, the local program can use the Convert_Outgoing call to convert the data to EBCDIC before sending it. For Windows If the remote program requires data to be sent in EBCDIC, the local program can use the CSV CONVERT verb to convert the data to EBCDIC before sending it.
CPI-C Calls Send_Error (cmserr) Send_Error (cmserr) The Send_Error call notifies the partner program that the local program has encountered an application-level error. The local program can use the 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.
CPI-C Calls Send_Error (cmserr) conversation_ID This is the identifier for the conversation. The value of this parameter was returned by the Initialize_Conversation, Initialize_For_Incoming, or Accept_Conversation call. Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. request_to_send_received This is the request-to-send-received indicator.
CPI-C Calls Send_Error (cmserr) CM_RESOURCE_FAILURE_NO_RETRY CM_RESOURCE_FAILURE_RETRY CM_SECURITY_NOT_VALID CM_SVC_ERROR_PURGING CM_SYNC_LVL_NOT_SUPPORTED_PGM CM_SYNC_LVL_NOT_SUPPORTED_LU CM_TP_NOT_AVAILABLE_NO_RETRY CM_TP_NOT_AVAILABLE_RETRY CM_TPN_NOT_RECOGNIZED Receive state or Pending-Post state If the call is issued in Receive state or Pending-Post state, the following return codes are possible: CM_OK Because incoming information is purged when the Send_Error call is issued in Receive state or Pend
CPI-C Calls Send_Error (cmserr) CM_DEALLOCATED_ABEND_TIMER CM_PIP_NOT_SPECIFIED_CORRECTLY CM_SECURITY_NOT_VALID CM_SYNC_LVL_NOT_SUPPORTED_PGM CM_SYNC_LVL_NOT_SUPPORTED_LU CM_TPN_NOT_RECOGNIZED CM_TP_NOT_AVAILABLE_NO_RETRY CM_TP_NOT_AVAILABLE_RETRY Send-Pending state If the call is issued in Send-Pending state, the following return codes are possible: CM_OK The call executed successfully. For an explanation of the following return codes, see Appendix A, “Common Return Codes.
CPI-C Calls Send_Error (cmserr) CM_OPERATION_NOT_ACCEPTED See Appendix A, “Common Return Codes.” CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID is not valid. CM_PROGRAM_STATE_CHECK The conversation state is not Send, Receive, Confirm, Confirm-Send, Confirm-Deallocate, or Send-Pending. State When Issued The conversation can be in any state except Initialize, Initialize-Incoming, or Reset. State Change The new state is determined by the return_code parameter.
CPI-C Calls Send_Error (cmserr) Table 3-13 State Changes for the Send_Error Call (Continued) return_code New state CM_PROGRAM_ERROR_PURGING CM_SVC_ERROR_PURGING Receive All others No change Usage Notes The following sections describe additional usage information for the Send_Error call. Sending Log Data In basic conversations, the local program can use the Set_Log_Data call to specify error log data to be sent to the partner LU.
CPI-C Calls Send_Error (cmserr) Send-Pending State If the conversation is in Send-Pending state, the local program can issue the Set_Error_Direction call 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.
CPI-C Calls Set_Conversation_Context (cmsctx) Set_Conversation_Context (cmsctx) For Unix The Set_Conversation_Context call sets the program's current context to a value that was previously returned on an Extract_Conversation_Context call. This enables the program to start a new conversation using the same context as a previous one. For more information about conversation contexts, see “Multiple Conversations” in Chapter 1.
CPI-C Calls Set_Conversation_Context (cmsctx) Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. return_code Possible values are: CM_OK The call executed successfully.
CPI-C Calls Set_Conversation_Context (cmsctx) is set to the context of the new conversation; however, if Accept_Incoming returns CM_OPERATION_INCOMPLETE, a subsequent Wait_For_Conversation that returns the result of Accept_Incoming does not change the program's current context. The program must use Extract_Conversation_Context and Set_Conversation_Context to set the current context to the correct value.
CPI-C Calls Set_Conversation_Security_Password (cmscsp) Set_Conversation_Security_Password (cmscsp) The Set_Conversation_Security_Password call is issued by the invoking program to specify the password required to access the invoked program. This call has an effect on the conversation only if the conversation security type is CM_SECURITY_PROGRAM or CM_SECURITY_PROGRAM_STRONG (HP-UX systems), or XC_SECURITY_PROGRAM (Windows systems).
CPI-C Calls Set_Conversation_Security_Password (cmscsp) security_password This specifies the password required to access the partner program. This parameter is a character string of 1–10 characters(HP-UX systems), or 1–8 characters (Windows systems), and is case-sensitive. It must match the password for the user ID configured for the partner program. The following characters are allowed: • Uppercase and lowercase letters • Numerals 0–9 • Special characters $, #, @, and .
CPI-C Calls Set_Conversation_Security_Password (cmscsp) • The conversation's security type is not set to CM_SECURITY_PROGRAM or CM_SECURITY_PROGRAM_ST RONG CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued The conversation must be in Initialize state. State Change There is no state change. Usage Notes A user ID is required in addition to the password.
CPI-C Calls Set_Conversation_Security_Password (xcscsp) Set_Conversation_Security_Password (xcscsp) This function is not available in Java CPI-C. This call is issued by the invoking program to specify the password required to access the invoked program. The xcscsp call provides compatibility for applications using the X/Open CPI-C definition. It has been incorporated into IBM CPI-C 2.0 as the call Set_Conversation_Security_Password (cmscsp).
CPI-C Calls Set_Conversation_Security_Type (cmscst) Set_Conversation_Security_Type (cmscst) The Set_Conversation_Security_Type call is 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 the Initialize_Conversation call. This call cannot be issued after the Allocate has been issued.
CPI-C Calls Set_Conversation_Security_Type (cmscst) CM_SECURITY_SAME The invoked program uses conversation security, and is configured to accept an already-verified indicator (as described in “Overview of Conversation Security” in Chapter 1). The user ID from the local program's current context (at the time the Allocate call is issued) will be sent to the invoked program, together with an already-verified indicator. This indicator tells the invoked program not to require the password.
CPI-C Calls Set_Conversation_Security_Type (cmscst) CM_OK The call executed successfully. CM_PROGRAM_STATE_CHECK The conversation is not in Initialize state. CM_PROGRAM_PARAMETER_CHECK The value specified by conversation_ID or conversation_security_type is not valid. CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued The conversation must be in Initialize state. State Change There is no state change.
CPI-C Calls Set_Conversation_Security_Type (xcscst) Set_Conversation_Security_Type (xcscst) This function is not available in Java CPI-C. This call is 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 the Initialize_Conversation call. The call provides compatibility for applications using the X/Open CPI-C definition.
CPI-C Calls Set_Conversation_Security_User_ID (cmscsu) Set_Conversation_Security_User_ID (cmscsu) The Set_Conversation_Security_User_ID call is issued by the invoking program to specify the user ID required to access to the invoked program. It overrides the initial user ID from the side information specified by the Initialize_Conversation call. This call cannot be issued after the Allocate call has been issued.
CPI-C Calls Set_Conversation_Security_User_ID (cmscsu) The following characters are allowed: • Uppercase and lowercase letters • Numerals 0–9 • Special characters $, #, @, and . (period) security_user_ID_length This specifies the length of security_user_ID. This range for this value is 1–10 characters (HP-UX systems), or 1–8 characters (Windows systems). If the length is 0 (zero), the security_user_ID parameter is ignored; this is equivalent to setting security_user_ID to a null string.
CPI-C Calls Set_Conversation_Security_User_ID (cmscsu) State When Issued The conversation must be in Initialize state. State Change There is no state change. Usage Notes If the return code is not CM_OK, the security_user_ID and security_user_ID_length conversation characteristics are unchanged. A user ID that is not valid is not detected until the allocation request, generated by the Allocate call, is sent to the partner LU. The error is returned to the invoking program on a subsequent call.
CPI-C Calls Set_Conversation_Security_User_ID (xcscsu) Set_Conversation_Security_User_ID (xcscsu) This function is not available in Java CPI-C. This call is issued by the invoking program to specify the user ID required to access the invoked program. The xcscsu call provides compatibility for applications using the X/Open CPI-C definition. It has been incorporated into IBM CPI-C 2.0 as the call Set_Conversation_Security_User_ID (cmscsu).
CPI-C Calls Set_Conversation_Type (cmsct) Set_Conversation_Type (cmsct) The Set_Conversation_Type call is issued by the invoking program to define a conversation as being mapped or basic. This call overrides the default conversation type established by the Initialize_Conversation call. The default conversation type is CM_MAPPED_CONVERSATION. This call cannot be issued after the Allocate has been issued.
CPI-C Calls Set_Conversation_Type (cmsct) Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. return_code Possible values are: CM_OK The call executed successfully. CM_PROGRAM_STATE_CHECK The conversation is not in Initialize state.
CPI-C Calls Set_Conversation_Type (cmsct) State Change There is no state change. Usage Notes If the return code is not CM_OK, the conversation_type conversation characteristic is unchanged.
CPI-C Calls Set_CPIC_Side_Information (xcmssi) Set_CPIC_Side_Information (xcmssi) This function is not available in Java CPI-C. The Set_CPIC_Side_Information call specifies a side information entry for use by this application. A CPI-C side information entry associates a set of conversation characteristics with a symbolic destination name. Side information entries are defined in the SNAplus2 configuration file.
CPI-C Calls Set_CPIC_Side_Information (xcmssi) side_info_entry This parameter specifies the contents of a side information entry, as follows. Each field in the structure must be left-justified. Pad fields on the right with spaces as necessary. side_info_entry.sym_dest_name Symbolic destination name which identifies the side information entry. The parameter sym_dest_name is an 8-byte ASCII character string and can contain any displayable characters. side_info_entry.
CPI-C Calls Set_CPIC_Side_Information (xcmssi) Set_CPIC_Side_Information is the only CPI-C call that lets you specify an SNA service TP as the partner program. See the description of the TP_name_type parameter above for more information on how to specify the TP name. side_info_entry.mode_name Name of the mode used to access the target TP. For a mapped conversation, the mode name SNASVCMG is reserved for SNA internal use; the Allocate call will fail if you use this name.
CPI-C Calls Set_CPIC_Side_Information (xcmssi) password across the network in clear text format. This value can be used only if the remote system supports password substitution. For Unix XC_SECURITY_NONE Equivalent to CM_SECURITY_NONE XC_SECURITY_SAME Equivalent to CM_SECURITY_SAME XC_SECURITY_PROGRAM Equivalent to CM_SECURITY_PROGRAM End of Section side_info_entry.security_user_ID User ID used to access the partner TP.
CPI-C Calls Set_CPIC_Side_Information (xcmssi) CM_OK The call executed successfully. CM_PROGRAM_PARAMETER_CHECK One of the following has occurred: • A value specified in the side_info_entry structure is not valid • The first character of the side_info_entry contains a space CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued The conversation can be in any state. State Change There is no state change.
CPI-C Calls Set_Deallocate_Type (cmsdt) Set_Deallocate_Type (cmsdt) The Set_Deallocate_Type call specifies how the conversation is to be deallocated. This call overrides the default deallocate type established by the Initialize_Conversation or Accept_Conversation call. The default deallocate type is CM_DEALLOCATE_SYNC_LEVEL.
CPI-C Calls Set_Deallocate_Type (cmsdt) 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 may be purged. For a basic conversation in Send state, logical record truncation may occur.
CPI-C Calls Set_Deallocate_Type (cmsdt) by the Initialize_Conversation call and can be overridden by the Set_Sync_Level call. If the synchronization level of the conversation is set to the default, CM_NONE, 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.
CPI-C Calls Set_Deallocate_Type (cmsdt) • The deallocate_type parameter specifies CM_DEALLOCATE_CONFIRM, but the conversation's synchronization level is set to CM_NONE CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued The conversation can be in any state except Reset. State Change There is no state change. Usage Notes If the return_code is not CM_OK, the deallocate_type conversation characteristic is unchanged.
CPI-C Calls Set_Error_Direction (cmsed) Set_Error_Direction (cmsed) The Set_Error_Direction call specifies whether a program detected an error while receiving data or while preparing to send data. This call overrides the default error direction established by the Initialize_Conversation or Accept_Conversation call. The default error direction is CM_RECEIVE_ERROR.
CPI-C Calls Set_Error_Direction (cmsed) CM_RECEIVE_ERROR An error occurred in the data received from the partner program. CM_SEND_ERROR An error occurred while the local program prepared to send data to the partner program. Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. return_code Possible values are: CM_OK The call executed successfully.
CPI-C Calls Set_Error_Direction (cmsed) 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.
CPI-C Calls Set_Fill (cmsf) Set_Fill (cmsf) The Set_Fill call 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. It overrides the default fill established by the Initialize_Conversation or Accept_Conversation call. The default fill is CM_FILL_LL. The fill value affects all subsequent Receive calls. It can be changed by issuing the Set_Fill call again.
CPI-C Calls Set_Fill (cmsf) end of the data. Data is received without regard for the logical-record format. CM_FILL_LL Data is received in logical-record format.
CPI-C Calls Set_Fill (cmsf) State Change There is no state change. Usage Notes If the return_code is not CM_OK, the fill conversation characteristic is unchanged.
CPI-C Calls Set_Local_LU_Name (cmslln) Set_Local_LU_Name (cmslln) The Set_Local_LU_Name call is issued by the invoking program to specify the local LU for a conversation. This call overrides the system-defined Local LU derived from the side information when Initialize_Conversation was issued, and any Local LU specified by the APPCLLU environment variable. This call cannot be issued after the Allocate has been issued. Issuing this call has no effect on the side information itself.
CPI-C Calls Set_Local_LU_Name (cmslln) lu_alias This parameter specifies the starting address of the LU alias. The LU alias can contain up to eight ASCII characters. lu_alias_length This parameter specifies the length of the LU alias. The range for this value is 0–8 bytes. If lu_alias_length is 0 (zero), the LU alias is set to all zeros. Returned Parameters After the verb executes, SNAplus2 returns the following parameters: return_code Possible values are: CM_OK The call executed successfully.
CPI-C Calls Set_Local_LU_Name (cmslln) Usage Notes If the return_code is not CM_OK, the lu_alias conversation characteristic is unchanged. Specifying a value for lu_alias that is not valid (a name that is not permitted by the configuration file) is not detected until the Allocate call is issued.
CPI-C Calls Set_Log_Data (cmsld) Set_Log_Data (cmsld) The Set_Log_Data call 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 (zero).
CPI-C Calls Set_Log_Data (cmsld) The program must format the error data as a General Data Stream (GDS) error log variable. For further information, refer to the IBM publication IBM Systems Network Architecture: LU 6.2 Reference: Peer Protocols. log_data_length This parameter specifies the length of the log data. The range for this value is 0–512 bytes. A length of 0 (zero) indicates that there is no log data.
CPI-C Calls Set_Log_Data (cmsld) Usage Notes If the return_code is not CM_OK, the log_data and log_data_length conversation characteristics are unchanged.
CPI-C Calls Set_Mode_Name (cmsmn) Set_Mode_Name (cmsmn) The Set_Mode_Name call is 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 the Allocate has been issued. Issuing this call has no effect on the side information itself.
CPI-C Calls Set_Mode_Name (cmsmn) • Numerals 0–9 The value of mode_name must match the name of a mode associated with the partner LU during configuration. For a mapped conversation, the mode name SNASVCMG is reserved for SNA internal use; the Allocate call will fail if you use this name. You are recommended not to use SNASVCMG in a basic conversation, or CPSVCMG (another SNA reserved name) in either type of conversation. mode_name_length This parameter specifies the length of the mode name.
CPI-C Calls Set_Mode_Name (cmsmn) State When Issued The conversation must be in Initialize state. State Change There is no state change. Usage Notes If the return_code is not CM_OK, the mode_name conversation characteristic is unchanged. Specifying a value for mode_name that is not valid (a name that is not permitted by the configuration file) is not detected until the Allocate call is issued.
CPI-C Calls Set_Partner_LU_Name (cmspln) Set_Partner_LU_Name (cmspln) The Set_Partner_LU_Name call is 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 the Allocate has been issued. Issuing this call has no effect on the side information itself.
CPI-C Calls Set_Partner_LU_Name (cmspln) • An alias consisting of 1–8 ASCII characters. • A fully qualified network name consisting of 2–17 ASCII characters. A period (.) separates the network ID (which can be 0–8 characters) from the network LU name (which can be 1–8 characters). If the network ID is zero characters long, the period is still required. If the partner LU is specified by its alias, this must match the alias defined for a partner LU in the SNAplus2 configuration.
CPI-C Calls Set_Partner_LU_Name (cmspln) State Change There is no state change. Usage Notes If the return_code is not CM_OK, the partner_LU_name conversation characteristic is unchanged. Specifying a value for partner_LU_name that is not valid (a name not permitted by the configuration) is not detected until the Allocate call is issued.
CPI-C Calls Set_Prepare_To_Receive_Type (cmsptr) Set_Prepare_To_Receive_Type (cmsptr) The Set_Prepare_To_Receive_Type call specifies how the subsequent Prepare_To_Receive calls will be executed. It overrides the default prepare-to-receive processing established by the Initialize_Conversation or Accept_Conversation call. 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.
CPI-C Calls Set_Prepare_To_Receive_Type (cmsptr) CM_PREP_TO_RECEIVE_CONFIRM This value sends 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 This value sends the partner program the contents of the local LU's send buffer and changes the conversation to Receive state.
CPI-C Calls Set_Prepare_To_Receive_Type (cmsptr) return_code Possible values are: CM_OK The call executed successfully.
CPI-C Calls Set_Processing_Mode (cmspm) Set_Processing_Mode (cmspm) This function is not available in Java CPI-C. Java CPI-C functions always operate in blocking mode; that is, the function does not return control to the application until the requested processing has completed. The Set_Processing_Mode call specifies whether subsequent CPI-C calls will return when the required operation is complete (blocking mode), or return immediately even if the operation is not complete (nonblocking mode).
CPI-C Calls Set_Processing_Mode (cmspm) End of Section The processing mode affects all subsequent CPI-C calls. It can be changed by issuing the Set_Processing_Mode call again. Function Call void cmspm ( unsigned char CM_PTR CM_INT32 CM_PTR CM_RETURN_CODE CM_PTR ); conversation_ID, processing_mode, return_code Supplied Parameters The supplied parameters are: conversation_ID This is the identifier for the conversation.
CPI-C Calls Set_Processing_Mode (cmspm) For an explanation of the following return codes, see Appendix A, “Common Return Codes.” CM_OPERATION_NOT_ACCEPTED CM_PRODUCT_SPECIFIC_ERROR State When Issued The conversation can be in any state except Reset. State Change There is no state change. Usage Notes If the return_code is not CM_OK, the processing_mode conversation characteristic is unchanged.
CPI-C Calls Set_Receive_Type (cmsrt) Set_Receive_Type (cmsrt) The Set_Receive_Type call 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 issuing the Set_Receive_Type call again.
CPI-C Calls Set_Receive_Type (cmsrt) CM_RECEIVE_AND_WAIT 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 The local program receives any data currently available from the partner program. If no data is available, the local program does not wait.
CPI-C Calls Set_Return_Control (cmsrc) Set_Return_Control (cmsrc) The Set_Return_Control call is issued by the invoking program to specify whether the Allocate call returns immediately if a session is not available, or waits for a session to be allocated. This call overrides the default return control established by the Initialize_Conversation call. By default, CPI-C waits for the session to be allocated. This call cannot be issued after the Allocate call has been issued.
CPI-C Calls Set_Return_Control (cmsrc) CM_IMMEDIATE The LU allocates a contention winner session, if one is immediately available, and returns control to the program. CM_WHEN_SESSION_ALLOCATED The LU does not return control to the program until it allocates a session or encounters certain errors. If a session is not available, the program waits for one. (If the session limit is 0, the LU returns control immediately.
CPI-C Calls Set_Return_Control (cmsrc) Usage Notes If the return_code is not CM_OK, the return_control conversation characteristic is unchanged. If the LU is unable to allocate a session, the notification is returned on the Allocate call.
CPI-C Calls Set_Send_Type (cmsst) Set_Send_Type (cmsst) The Set_Send_Type call specifies how data will be sent by the next Send_Data call. It overrides the default send type established by the Initialize_Conversation or Accept_Conversation call. 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 issuing the Set_Send_Type call again.
CPI-C Calls Set_Send_Type (cmsst) CM_SEND_AND_FLUSH The data pointed to by the Send_Data call is to be sent immediately. This is equivalent to Send_Data, with the send_type set to CM_BUFFER_DATA, followed by Flush. CM_SEND_AND_CONFIRM The data is to be sent immediately with a request for confirmation. This is equivalent to Send_Data, with the send_type set to CM_BUFFER_DATA, followed by Confirm.
CPI-C Calls Set_Send_Type (cmsst) • The value specified by conversation_ID or send_type is not valid • 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 For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued The conversation can be in any state except Reset. State Change There is no state change.
CPI-C Calls Set_Sync_Level (cmssl) Set_Sync_Level (cmssl) The Set_Sync_Level call is 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.
CPI-C Calls Set_Sync_Level (cmssl) CM_CONFIRM The programs can perform confirmation processing. A third level, sync point, is provided by some CPI-C implementations, but is not supported by SNAplus2 CPI-C. Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. return_code Possible values are: CM_OK The call executed successfully.
CPI-C Calls Set_Sync_Level (cmssl) State When Issued The conversation must be in Initialize state. State Change There is no state change. Usage Notes If the return_code is not CM_OK, the sync_level conversation characteristic is unchanged.
CPI-C Calls Set_TP_Name (cmstpn) Set_TP_Name (cmstpn) The Set_TP_Name call is issued by the invoking program to specify the partner 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. This call functions differently from Specify_Local_TP_Name.
CPI-C Calls Set_TP_Name (cmstpn) TP_name This parameter specifies the starting address of the partner program name. The program name can contain up to 64 characters. The following characters are allowed: • Uppercase and lowercase letters • Numerals 0–9 and .
CPI-C Calls Set_TP_Name (cmstpn) CM_PRODUCT_SPECIFIC_ERROR For an explanation of this return code, see Appendix A, “Common Return Codes.” State When Issued The conversation must be in Initialize state. State Change There is no state change. Usage Notes If the return_code is not CM_OK, the TP_name conversation characteristic is unchanged.
CPI-C Calls Specify_Local_TP_Name (cmsltp) Specify_Local_TP_Name (cmsltp) The Specify_Local_TP_Name call is issued by a CPI-C application to specify a local TP name for which it will accept incoming Allocate requests. Instead of using this call, you can set the local TP name in other ways such as by using the APPCTPN environment variable. For more information about setting the local TP name, see “Specifying the Local TP Name” in Chapter 2.
CPI-C Calls Specify_Local_TP_Name (cmsltp) TP_name This parameter specifies the starting address of the TP name. The name can contain up to 64 characters. The following characters are allowed: • Uppercase and lowercase letters • Numerals 0–9 • The special characters: . < > ( ) + - & *; / , % _ ? : ' = " You cannot use the Specify_Local_TP_Name call to specify the name of an SNA service TP, which contains characters that are not allowed for this call.
CPI-C Calls Specify_Local_TP_Name (cmsltp) State Change There is no state change. Usage Notes If the return_code is not CM_OK, the TP names for which this program will accept incoming Allocate requests are unchanged. If an Accept_Incoming call is outstanding at the time this call is issued, it will not accept an incoming Allocate for the name specified on this call. However, subsequent Accept_Conversation or Accept_Incoming calls will accept incoming Allocates for this name.
CPI-C Calls Specify_Windows_Handle (xchwnd) Specify_Windows_Handle (xchwnd) For Windows The Specify_Windows_Handle call is issued by a CPI-C application to specify a Windows handle to which CPI-C will send a message each time a nonblocking CPI-C function completes. This provides an alternative mechanism to using Wait_For_Conversation (as on HP-UX systems) to wait for completion of the function.
CPI-C Calls Specify_Windows_Handle (xchwnd) Function Call void xchwnd ( HWND CM_RETURN_CODE CM_PTR ); hwnd, return_code Supplied Parameters The supplied parameter is: hwnd A window handle that CPI-C will use to post a message indicating that a nonblocking function has completed. Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful.
CPI-C Calls Test_Request_to_Send_Received (cmtrts) Test_Request_to_Send_Received (cmtrts) The Test_Request_to_Send_Received call determines whether a request-to-send notification has been received from the partner program.
CPI-C Calls Test_Request_to_Send_Received (cmtrts) CM_REQ_TO_SEND_RECEIVED 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 The partner program has not issued the Request_To_Send call. This value is not relevant if the return_code parameter contains a value other than CM_OK. return_code Possible values are: CM_OK The call executed successfully.
CPI-C Calls Wait_For_Conversation (cmwait) Wait_For_Conversation (cmwait) This function is not available in Java CPI-C. Java CPI-C functions always operate in blocking mode; that is, the function does not return control to the application until the requested processing has completed. The Wait_For_Conversation call waits for completion of a previous CPI-C call that returned CM_OPERATION_INCOMPLETE.
CPI-C Calls Wait_For_Conversation (cmwait) Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful. conversation_ID This is the identifier for the conversation on which the outstanding call completed. conversation_return_code This is the return code from the completed call (which previously returned CM_OPERATION_INCOMPLETE).
CPI-C Calls Wait_For_Conversation (cmwait) State Change If return_code is set to CM_OK, the state change depends on the outstanding call that completed, and on the return code from that call (the conversation_return_code parameter on this call). For more information, see the description of the specific call. If return_code is not CM_OK, there is no state change.
CPI-C Calls WinCPICCleanup WinCPICCleanup For Windows The application uses this function to unregister as a Windows CPI-C user, after it has finished issuing CPI-C calls. Function Call BOOL WINAPI WinCPICCleanup (void); Supplied Parameters There are no supplied parameters for this call. Returned Values The return value from the function is one of the following: TRUE The application was unregistered successfully.
CPI-C Calls WinCPICIsBlocking WinCPICIsBlocking For Windows The application uses this function to check whether there is a blocking CPI-C call outstanding (a call issued with the conversation's processing mode set to CM_BLOCKING). For more information about blocking calls, see “Windows Considerations” in Chapter 2. Function Call BOOL WINAPI WinCPICIsBlocking (void); Supplied Parameters There are no supplied parameters for this function.
CPI-C Calls WinCPICSetBlockingHook WinCPICSetBlockingHook For Windows The application uses this call to specify its own blocking function, which CPI-C will use instead of the default blocking function. For more information about how the blocking function operates, and on the functions it must perform, see “Blocking Calls” in Chapter 2.
CPI-C Calls WinCPICSetBlockingHook • WinCPICUnhookBlockingHook() (described below), to stop using the current blocking function and return to the default blocking function.
CPI-C Calls WinCPICStartup WinCPICStartup For Windows The application uses this function to register as a Windows CPI-C user, and to determine whether the CPI-C software supports the Windows CPI-C version that it requires. Function Call int WINAPI WinCPICStartup ( WORD LPWCPICDATA wVersionRequired; lpData; ) typedef struct { WORD wVersion; char szDescription[128]; } WCPICDATA; Supplied Parameters The supplied parameter is: wVersionRequired The version of Windows CPI-C that the application requires.
CPI-C Calls WinCPICStartup Returned Values The return value from the function is one of the following: 0 (zero) The application was registered successfully, and the Windows CPI-C software supports either the version number specified by the application or a lower version. The application should check the version number in the WCPICDATA structure (see the description that follows) to ensure that it is high enough.
CPI-C Calls WinCPICStartup attempt to use features that are not supported by the returned version number. If it cannot do this because it requires features not available in the lower version, it should fail its initialization and not attempt to issue any CPI-C calls. szDescription A text string describing the Windows CPI-C software.
CPI-C Calls WinCPICUnhookBlockingHook WinCPICUnhookBlockingHook For Windows The application uses this call to remove its own blocking function, which it has previously specified using WinCPICSetBlockingHook(), and revert to using CPI-C's default blocking function. Function Call BOOL WINAPI WinCPICUnhookBlockingHook (void); Supplied Parameters There are no supplied parameters for this function.
CPI-C Calls WinCPICSetEvent WinCPICSetEvent For Windows The application uses this function to associate an event handle with verb completion for the specified conversation. Function Call VOID WINAPI WinCPICSetEvent ( unsigned char CM_PTR HANDLE CM_PTR CM_INT32 CM_PTR ); conversation_ID, event_handle, return_code Supplied Parameters The supplied parameters are: conversation_ID This is the identifier for the conversation for which this event is used.
CPI-C Calls WinCPICSetEvent CM_OPERATION_NOT_ACCEPTED This value indicates that a previous operation on this conversation is incomplete and the WinCPICSetEvent() call was not accepted. Usage Notes When a verb is issued on a nonblocking conversation, it returns CM_OPERATION_INCOMPLETE if it is going to complete asynchronously. If an event has been registered with the conversation, then the application can call WaitForSingleObject() or WaitForMultipleObjects() to be notified of the completion of the verb.
CPI-C Calls WinCPICExtractEvent WinCPICExtractEvent For Windows The application uses this function to determine the event handle being used for a CPI-C conversation. Function Call VOID WINAPI WinCPICExtractEvent ( unsigned char CM_PTR HANDLE CM_PTR CM_INT32 CM_PTR ); conversation_ID, event_handle, return_code Supplied Parameters The supplied parameter for this function is: conversation_ID This is the identifier for the conversation for which this event is used.
CPI-C Calls WinCPICExtractEvent notified of the completion of the verb. WinCPICExtractEvent() enables a CPI-C application to determine this event handle. When the verb has completed, the application must call Wait_for_Conversation to determine the return code for the asynchronous verb. The Cancel_Conversation function can be called to cancel an operation and conversation.
CPI-C Calls WinCPICExtractEvent 316 Chapter 3
4 Sample CPI-C Transaction Programs This chapter describes the SNAplus2 sample CPI-C transaction programs, which illustrate the use of CPI-C calls in HP-UX applications.
Sample CPI-C Transaction Programs For information on using CPI-C calls in a Java application, see Chapter 5, “Sample Java CPI-C Transaction Program.
Sample CPI-C Transaction Programs Processing Overview Processing Overview The programs presented in this chapter enable you to browse through a file on another system. The user is presented with a single data block at a time, in hexadecimal and character format. After each block, a user can request the next block, request the previous block, or quit. CSAMPLE1 (the invoking program) sends a file name to CSAMPLE2 (the invoked program).
Sample CPI-C Transaction Programs Pseudocode Pseudocode This section contains the pseudocode for the transaction programs, CSAMPLE1 and CSAMPLE2. The sample programs are provided as csample1.c and csample2.c, in the directory /opt/sna/samples.
Sample CPI-C Transaction Programs Pseudocode endif if (conversing) read file block send data (file block) endif else if deallocate received set conversing false endif end while conversing close file Chapter 4 321
Sample CPI-C Transaction Programs Testing the TPs Testing the TPs After examining the source code for CSAMPLE1 and CSAMPLE2, you may want to test the programs. Although CPI-C is normally used for communications between programs on separate computers, you may find it convenient to run both programs on the same computer for testing purposes. To compile and link the programs for HP-UX systems, take the following steps. Step 1. Copy the three files csample1.c, csample2.
Sample CPI-C Transaction Programs Testing the TPs Step 4. Configure a symbolic destination name on the source computer. Do the following: • For Name, specify CPICTEST • For Local LU, select Local LU alias and specify TPLU1 as the LU alias. • For Partner LU, specify the fully-qualified name netname.TPLU2, where netname is the SNA network name of the target computer. • For Mode, specify LOCMODE. • For Partner TP, specify TPNAME2. Leave the default values for other parameters. Step 5.
Sample CPI-C Transaction Programs Testing the TPs csample1 /usr/jim/myfile Step 10. Enter F or B to display blocks of the requested file. Use Q to end the invoking program; the invoked program will end as well.
5 Sample Java CPI-C Transaction Program This chapter describes the SNAplus2 sample Java CPI-C transaction program JPing, which illustrates the use of CPI-C calls in a Java Chapter 5 325
Sample Java CPI-C Transaction Program application. For information on using CPI-C calls in a standard C program, see Chapter 4, “Sample CPI-C Transaction Programs.
Sample Java CPI-C Transaction Program Overview Overview The sample Java CPI-C program, JPing (in the file /opt/sna/samples/JPing.java) is a simple Java implementation of the standard APPC function aping, which is used to check connectivity with a remote node. For more information about aping, refer to the SNAplus2 Administration Command Reference.
Sample Java CPI-C Transaction Program Compiling, Linking, and Running the Sample Program Compiling, Linking, and Running the Sample Program After examining the source code for JPing, you may want to build and test the program. Before compiling and linking the application, specify the directory where Java classes are stored. To do this, set and export the environment variable CLASSPATH to /opt/sna/java/cpic.jar. To compile and link the program, take the following steps. Step 1. Copy the file JPing.
Sample Java CPI-C Transaction Program Compiling, Linking, and Running the Sample Program Leave the default values for other parameters. Run the application using the Java interpreter java in the normal way. Use the following command: java JPing [-s sym_dest_name] [-n num_iterations] [-d data_len] The -s option indicates the symbolic destination name to be used by the program. If you do not specify this option, the default is JPING. The -n option indicates the number of ping iterations to be performed.
Sample Java CPI-C Transaction Program Compiling, Linking, and Running the Sample Program 330 Chapter 5
A Common Return Codes This appendix describes the return codes that are common to several CPI-C calls. The return codes are listed in alphabetical order. Return codes generated when the partner program is a non-CPI-C LU 6.2 program are listed separately.
Common Return Codes Call-specific return codes are described in the documentation for the individual calls in Chapter 3, “CPI-C Calls.
Common Return Codes Return Codes from Any Partner Program Return Codes from Any Partner Program The following return codes can occur with any partner program. (Other return codes, which can only occur when the partner program is not a CPI-C program, are listed separately.) CM_ALLOCATION_FAILURE_NO_RETRY The conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error.
Common Return Codes Return Codes from Any Partner Program • The local program issued the Cancel_Conversation call, which cancels all outstanding asynchronous CPI-C calls on the conversation. CM_DEALLOCATED_NORMAL This return code does not indicate an error.
Common Return Codes Return Codes from Any Partner Program End of Section CM_OPERATION_NOT_ACCEPTED The call cannot be issued because of one of the following conditions: • For Unix At a later time, the application can issue Check_For_Completion to determine whether an outstanding nonblocking call has completed, Wait_For_Conversation to wait for it to complete, or Cancel_Conversation to cancel the outstanding call and end the conversation.
Common Return Codes Return Codes from Any Partner Program CM_PRODUCT_SPECIFIC_ERROR When CPI-C generates a CM_PRODUCT_SPECIFIC_ERROR return code, it makes an entry in the log file indicating the cause of the error and any action required. Refer to the SNAplus2 Administration Guide for more information about interpreting these messages. CM_PROGRAM_ERROR_NO_TRUNC The partner program has issued the Send_Error call while in Send state or in Send-Pending state with the error direction set to CM_SEND_ERROR.
Common Return Codes Return Codes from Any Partner Program • The partner program did not deallocate the conversation before terminating normally. CM_RESOURCE_FAILURE_RETRY The conversation was terminated prematurely because of a temporary condition, such as modem failure. Retry the conversation. CM_SECURITY_NOT_VALID The user ID or password specified in the allocation request was not accepted by the partner LU.
Common Return Codes Return Codes from Any Partner Program For Unix • The program issued Check_For_Completion, and no outstanding nonblocking function had completed on any of the program's conversations.
Common Return Codes Non-CPI-C LU 6.2 Partner Program Non-CPI-C LU 6.2 Partner Program The following return codes can occur when the partner program is a non-CPI-C LU 6.2 program, for example an APPC TP. The verbs described in these paragraphs are LU 6.2 verbs. CM_DEALLOCATED_ABEND_SVC The conversation has been deallocated for one of the following reasons: • The partner program has issued the DEALLOCATE verb with TYPE set to ABEND_SVC.
Common Return Codes Non-CPI-C LU 6.2 Partner Program CM_SVC_ERROR_TRUNC The partner program (or partner LU) in a basic conversation issued a SEND_ERROR verb with the TYPE parameter set to SVC while in Recieve or Confirm state, before finishing sending a complete logical record. The local program may have received the first part of the logical record.
B Conversation State Changes Table B-1, Conversation State Changes, shows the conversation states in which each CPI-C function call can be issued, and the state change which occurs on completion of the call.
Conversation State Changes In some cases, the state change depends on the return code from the call; in most cases, there is no state change for non-OK return codes. Where no return codes are shown, a return code of CM_OK causes the state change shown, and any non-OK return code causes no state change (except as described in the note that follows). Where there are different state changes according to the return code, the applicable values are listed in the Return codes column.
Conversation State Changes For Unix Pending-Post state does not apply to HP-UX systems. All references to this state should be ignored. For Unix Initialize-Incoming state does not apply to Windows systems. All references to this state should be ignored. The Windows-specific function calls are not associated with a particular conversation, and have no effect on conversation states. They are not listed in this appendix.
Conversation State Changes Table B-1 CPI-C Call and primary_ rc Values Conversation State Changes (Continued) State in Which Issued Rese t (T) Init (I) InitInc (II) Send (S) Send Pend (SP) Recv (R) Conf m (C) Conf m Send (CS) Conf m Deal l (CD) Pend Post (PP) Check_Fo r_Comple tion T I II S SP R C CS CD X Confirm X X X X X X X X CM_OK S S (Program error, R R SVC error) Confirme d X X X X X X R S T X Convert_ Incoming , T I II S SP R C CS CD X T T
Conversation State Changes Table B-1 CPI-C Call and primary_ rc Values Conversation State Changes (Continued) State in Which Issued Rese t (T) (Program error, Init (I) InitInc (II) Send (S) Send Pend (SP) Recv (R) Conf m (C) Conf m Send (CS) Conf m Deal l (CD) Pend Post (PP) R R R R R R R R R X X X X X X X SVC error) Deallocat e (other) X CM_OK T T (Program error, R R SVC error) Delete_C PIC_ T I II S SP R C CS CD X X X X S SP R C CS CD X Side_Info
Conversation State Changes Table B-1 CPI-C Call and primary_ rc Values Extract_ Conversa tion_ Conversation State Changes (Continued) State in Which Issued Rese t (T) Init (I) InitInc (II) Send (S) Send Pend (SP) Recv (R) Conf m (C) Conf m Send (CS) Conf m Deal l (CD) Pend Post (PP) X I II S SP R C CS CD X X I II S SP R C CS CD X X I II S SP R C CS CD X T I II S SP R C CS CD X X I II S SP R C CS CD X Security_ Type Extract_ Conversa tion_ State
Conversation State Changes Table B-1 CPI-C Call and primary_ rc Values Conversation State Changes (Continued) State in Which Issued Rese t (T) Init (I) InitInc (II) Send (S) Send Pend (SP) Recv (R) Conf m (C) Conf m Send (CS) Conf m Deal l (CD) Pend Post (PP) T I II S SP R C CS CD X Extract_ Mode_Na me X I II S SP R C CS CD X Extract_ Partner_ X I X S SP R C CS CD X X I II S SP R C CS CD X Extract_ Sync_Lev el X I X S SP R C CS CD X Extract_
Conversation State Changes Table B-1 CPI-C Call and primary_ rc Values Conversation State Changes (Continued) State in Which Issued Rese t (T) Init (I) InitInc (II) Send (S) Send Pend (SP) Recv (R) Conf m (C) Conf m Send (CS) Conf m Deal l (CD) Pend Post (PP) Initialize _Convers ation I X X X X X X X X X Initialize _For_Inc oming II X X X X X X X X X Prepare_ To_Recei ve X X X X X X X X See funct ion X X X X CM_OK, Program error, SVC error Receive (receive ty
Conversation State Changes Table B-1 CPI-C Call and primary_ rc Values Conversation State Changes (Continued) State in Which Issued Rese t (T) Init (I) InitInc (II) Send (S) Send Pend (SP) Recv (R) Conf m (C) Conf m Send (CS) Conf m Deal l (CD) Pend Post (PP) X X X See funct ion See funct ion See funct ion X X X X I X X X X X X X X X Request_ To_Send X X X S SP R C CS CD PP Send_Da ta X X X See funct ion See funct ion X X X X X Send_Err or X X X CM_
Conversation State Changes Table B-1 CPI-C Call and primary_ rc Values Conversation State Changes (Continued) State in Which Issued Rese t (T) Init (I) InitInc (II) Send (S) Send Pend (SP) Recv (R) Conf m (C) Conf m Send (CS) Conf m Deal l (CD) Pend Post (PP) X I II S SP R C CS CD X X I X X X X X X X X X I X X X X X X X X X I X X X X X X X X Set_Conv ersation_ Type X I X X X X X X X X Set_CPI C_Side_ T I II S SP R C CS CD X Set_Conv
Conversation State Changes Table B-1 CPI-C Call and primary_ rc Values Conversation State Changes (Continued) State in Which Issued Rese t (T) Init (I) InitInc (II) Send (S) Send Pend (SP) Recv (R) Conf m (C) Conf m Send (CS) Conf m Deal l (CD) Pend Post (PP) Set_Deall ocate_Ty pe X I II S SP R C CS CD X Set_Erro r_Directi on X I II S SP R C CS CD X Set_Fill X I II S SP R C CS CD X Set_Loca l_ X I X X X X X X X X Set_Log_ Data X I II S SP R C
Conversation State Changes Table B-1 CPI-C Call and primary_ rc Values Conversation State Changes (Continued) State in Which Issued Rese t (T) Init (I) InitInc (II) Send (S) Send Pend (SP) Recv (R) Conf m (C) Conf m Send (CS) Conf m Deal l (CD) Pend Post (PP) Set_Proc essing_M ode X I II S SP R C CS CD X Set_Recei ve_Type X I II S SP R C CS CD X Set_Retu rn_Contr ol X I X X X X X X X X Set_Send _Type X I II S SP R C CS CD X Set_Sync _Level X I X X
Conversation State Changes Table B-1 CPI-C Call and primary_ rc Values Conversation State Changes (Continued) State in Which Issued Rese t (T) Wait_For _Convers ation Init (I) InitInc (II) Send (S) Send Pend (SP) Recv (R) Conf m (C) Conf m Send (CS) Conf m Deal l (CD) Pend Post (PP) Can be issued in any state; new state depends on the outstanding call that completed, and the return code from that call. See the information for the appropriate call.
Conversation State Changes 354 Appendix B
Index A Accept_Conversation, 119 Accept_Incoming, 122 Allocate call, 126 allocating a conversation confirming the allocation, 128 errors, 128 using Allocate call, 126 application program interface, 33 application scheduled mode, 95 application TP, 37 ASCII-EBCDIC data conversion, 70 B basic conversation characteristics of, 50 types, 37 blocking calls, Windows, 108 blocking mode, 56 buffer size, 175 C Cancel_Conversation, 129 Check_For_Completion, 132 CM_ALLOCATION_FAILURE_NO_RETRY , 333 CM_ALLOCATION_FAIL
Index password, 232 type, 236, 239 user ID, 240 conversation state changes, 44, 342 changing, 45 description, 43 getting, 164 initial, 47 conversation type basicSee also basic conversation, 37 mappedSee also mapped conversation, 37 setting, 244 with Allocate call, 126 with Extract_Conversation_Type call, 166 conversations, multiple, 52 conversion between ASCII and EBCDIC, 221 conversion between EBCDIC and ASCII, 211 Convert_Incoming call, 144 Convert_Outgoing call, 147 converting data between ASCII and EBCD
Index logical records, 50, 259 logical unit (LU) local LU, 36 LU 6.
Index Set_Processing_Mode, 277 Set_Receive_Type, 280 Set_Return_Control, 282 Set_Send_Type, 285 Set_Sync_Level, 288 Set_TP_Name, 291 side information, 154, 168, 247 signal-based scheduling mode, 96 sigpoll signal, 97 sleep call (HP-UX), 98 Specify_Local_TP_Name, 294 Specify_Windows_Handle, 297 state changes, 342 state of a conversationSee conversation state, 164 symbolic constants, 116 symbolic destination name, 83, 154, 247 synchronization level and Extract_Sync_Level, 183 establishing, 41 setting, 288 sy
