SNAP-IX CPI-C Programmer's Guide
BeforeYou Begin
Prerequisite Knowledge
Intended Audience
About This Book
Organization of This Book
Typographic Conventions
Graphic Conventions
SNAP-IX Publications
Publications for Users
Publications for Administrators
Publications for Programmers
Related Publications
1 Concepts
1.1 What Is CPI-C?
1.1.1 SNAP-IX CPI-C Option Set Support
1.1.2 Communication between Programs
1.1.3 Logical Unit 6.2
1.1.4 Sessions
1.1.5 Conversations
1.1.6 Contention
1.1.7 Characteristics
1.1.8 CPI-C Calls
1.1.9 The Conversation Process
1.1.10 Conversation Types
1.2 A Simple Mapped Conversation
1.2.1 Starting a Conversation
1.2.2 Sending Data
1.2.3 Receiving Data
1.2.4 Ending a Conversation
1.3 Confirmation Processing
1.3.1 Establishing the Synchronization Level
1.3.2 Sending a Confirmation Request
1.3.3 Receiving a Confirmation Request
1.3.4 Responding to a Confirmation Request
1.3.5 Deallocating the Conversation
1.4 Conversation States
1.4.1 The Program's View of the Conversation
1.4.2 State Changes
1.4.3 State Checks
1.5 Changing Conversation States
1.5.1 Initial States
1.5.2 Changing to Receive State
1.5.3 Changing to Send State
1.6 Side Information
1.7 Basic Conversations
1.7.1 Logical Records
1.7.2 Error Log Data
1.8 Multiple Conversations
1.9 Overview of Conversation Security
1.9.1 Conversation Security for Multiple Conversations
1.9.2 Already-Verified Conversation Security
1.10 Nonblocking Operation
1.11 CPI-C and LU 6.2
2 Writing CPI-C Applications
2.1 CPI-C Call Summary
2.1.1 Starting a Conversation
2.1.2 Sending data
2.1.3 Receiving Data
2.1.4 Converting Data Between ASCII and EBCDIC
2.1.5 Confirming Receipt of Data and Reporting Errors
2.1.6 Issuing Calls in Nonblocking Mode
2.1.7 Issuing Calls in Blocking Mode
2.1.8 Getting Information
2.1.9 Ending a Conversation
2.1.10 Administering Side Information
2.2 Initial Conversation Characteristics
2.3 Side Information
2.3.1 Local LU Alias
2.3.2 Partner LU Name
2.3.3 Partner Program Type and Name
2.3.4 Mode Name
2.3.5 Conversation Security Type
2.3.6 Security User ID and Password
2.3.7 Application-Specified Side Information
2.4 Configuration
2.5 Specifying the Local TP Name
2.5.1 Specify_Local_TP_Name
2.5.2 Context
2.5.3 APPCTPN Environment Variable
2.5.4 Default Value
2.6 Specifying the Local LU
2.6.1 Set_Local_LU_Name
2.6.2 Context
2.6.3 APPCLLU Environment Variable
2.6.4 Side Information
2.6.5 Default Local LU
2.6.6 Control Point LU
2.7 How Programs Get Started
2.7.1 Invoked Program: Automatically Started
2.7.2 Invoked Program: User-Started
2.8 Solaris Considerations
2.8.1 CPI-C Header File
2.8.2 Single-Threaded Applications
2.8.3 Multithreaded Applications
2.8.4 Multiple Processes
2.8.5 Compiling and Linking the CPI-C Application
2.9 Java CPI-C Considerations
2.9.1 Using Java CPI-C Classes
2.9.2 Usage Example
2.9.3 Compiling and Linking the Java CPI-C Application
2.9.4 Running the Java CPI-C Application
2.10 Windows Considerations
2.10.1 Windows CPI-C Files
2.10.2 Function Prototypes
2.10.3 Multiple Processes and Multiple Conversations
2.10.4 Windows Function Calls
2.10.5 Blocking Calls
2.10.6 Terminating Applications
2.10.7 Compiling and Linking CPI-C Applications
2.11 Writing Portable Applications
3 CPI-C Calls
3.1 Information Provided for CPI-C Calls
3.1.1 Data Types
3.1.2 Data Structures
3.1.3 Symbolic Constants
3.1.4 Strings
3.1.5 Validity of Returned Parameters
3.2 Information Provided for Windows Function Calls
3.3 Accept_Conversation (cmaccp)
3.3.1 Function Call
3.3.2 Function Call for Java CPI-C
3.3.3 Supplied Parameters
3.3.4 Returned Parameters
3.3.5 State When Issued
3.3.6 State Change
3.3.7 Usage Notes
3.4 Accept_Incoming (cmacci)
3.4.1 Function Call
3.4.2 Function Call for Java CPI-C
3.4.3 Supplied Parameters
3.4.4 Returned Parameters
3.4.5 State When Issued
3.4.6 State Change
3.4.7 Usage Notes
3.5 Allocate (cmallc)
3.5.1 Function Call
3.5.2 Function Call for Java CPI-C
3.5.3 Supplied Parameters
3.5.4 Returned Parameters
3.5.5 State When Issued
3.5.6 State Change
3.5.7 Usage Notes
3.6 Cancel_Conversation (cmcanc)
3.6.1 Function Call
3.6.2 Function Call for Java CPI-C
3.6.3 Supplied Parameters
3.6.4 Returned Parameters
3.6.5 State When Issued
3.6.6 State Change
3.6.7 Usage Notes
3.7 Check_For_Completion (cmchck)
3.7.1 Function Call
3.7.2 Supplied Parameters
3.7.3 Returned Parameters
3.7.4 State When Issued
3.7.5 State Change
3.7.6 Usage Notes
3.8 Confirm (cmcfm)
3.8.1 Function Call
3.8.2 Function Call for Java CPI-C
3.8.3 Supplied Parameters
3.8.4 Returned Parameters
3.8.5 State When Issued
3.8.6 State Change
3.8.7 Usage Notes
3.9 Confirmed (cmcfmd)
3.9.1 Function Call
3.9.2 Function Call for Java CPI-C
3.9.3 Supplied Parameters
3.9.4 Returned Parameters
3.9.5 State When Issued
3.9.6 State Change
3.9.7 Usage Notes
3.10 Convert_Incoming (cmcnvi)
3.10.1 Function Call
3.10.2 Function Call for Java CPI-C
3.10.3 Supplied Parameters
3.10.4 Returned Parameters
3.10.5 State When Issued
3.10.6 State Change
3.10.7 Usage Note
3.11 Convert_Outgoing (cmcnvo)
3.11.1 Function Call
3.11.2 Function Call for Java CPI-C
3.11.3 Supplied Parameters
3.11.4 Returned Parameters
3.11.5 State When Issued
3.11.6 State Change
3.11.7 Usage Note
3.12 Deallocate (cmdeal)
3.12.1 Function Call
3.12.2 Function Call for Java CPI-C
3.12.3 Supplied Parameters
3.12.4 Returned Parameters
3.12.5 State When Issued
3.12.6 State Change
3.12.7 Usage Notes
3.13 Delete_CPIC_Side_Information (xcmdsi)
3.13.1 Function Call
3.13.2 Supplied Parameters
3.13.3 Returned Parameters
3.13.4 State When Issued
3.13.5 State Change
3.13.6 Usage Notes
3.14 Extract_Conversation_Context (cmectx)
3.14.1 Function Call
3.14.2 Function Call for Java CPI-C
3.14.3 Supplied Parameters
3.14.4 Returned Parameters
3.14.5 State When Issued
3.14.6 State Change
3.14.7 Usage Notes
3.15 Extract_Conversation_Security_Type (xcecst)
3.15.1 Function Call
3.15.2 Supplied Parameters
3.15.3 Returned Parameters
3.15.4 State When Issued
3.15.5 State Change
3.16 Extract_Conversation_Security_User_ID (cmecsu)
3.17 Extract_Conversation_Security_User_ID (xcecsu)
3.18 Extract_Conversation_State (cmecs)
3.18.1 Function Call
3.18.2 Function Call for Java CPI-C
3.18.3 Supplied Parameters
3.18.4 Returned Parameters
3.18.5 State When Issued
3.18.6 State Change
3.19 Extract_Conversation_Type (cmect)
3.19.1 Function Call
3.19.2 Function Call for Java CPI-C
3.19.3 Supplied Parameters
3.19.4 Returned Parameters
3.19.5 State When Issued
3.19.6 State Change
3.20 Extract_CPIC_Side_Information (xcmesi)
3.20.1 Function Call
3.20.2 Supplied Parameters
3.20.3 Returned Parameters
3.20.4 State When Issued
3.20.5 State Change
3.20.6 Usage Notes
3.21 Extract_Local_LU_Name (cmelln)
3.21.1 Function Call
3.21.2 Function Call for Java CPI-C
3.21.3 Supplied Parameters
3.21.4 Returned Parameters
3.21.5 State When Issued
3.21.6 State Change
3.21.7 Usage Notes
3.22 Extract_Maximum_Buffer_Size (cmembs)
3.22.1 Function Call
3.22.2 Function Call for Java CPI-C
3.22.3 Supplied Parameters
3.22.4 Returned Parameters
3.22.5 State When Issued
3.22.6 State Change
3.23 Extract_Mode_Name (cmemn)
3.23.1 Function Call
3.23.2 Function Call for Java CPI-C
3.23.3 Supplied Parameters
3.23.4 Returned Parameters
3.23.5 State When Issued
3.23.6 State Change
3.24 Extract_Partner_LU_Name (cmepln)
3.24.1 Function Call
3.24.2 Function Call for Java CPI-C
3.24.3 Supplied Parameters
3.24.4 Returned Parameters
3.24.5 State When Issued
3.24.6 State Change
3.25 Extract_Security_User_ID (cmesui or cmecsu)
3.25.1 Function Call
3.25.2 Function Call for Java CPI-C
3.25.3 Supplied Parameters
3.25.4 Returned Parameters
3.25.5 State When Issued
3.25.6 State Change
3.25.7 Usage Notes
3.26 Extract_Sync_Level (cmesl)
3.26.1 Function Call
3.26.2 Function Call for Java CPI-C
3.26.3 Supplied Parameters
3.26.4 Returned Parameters
3.26.5 State When Issued
3.26.6 State Change
3.27 Extract_TP_Name (cmetpn)
3.27.1 Function Call
3.27.2 Function Call for Java CPI-C
3.27.3 Supplied Parameters
3.27.4 Returned Parameters
3.27.5 State When Issued
3.27.6 State Change
3.28 Flush (cmflus)
3.28.1 Sources of Buffered Data
3.28.2 Function Call
3.28.3 Function Call for Java CPI-C
3.28.4 Supplied Parameters
3.28.5 Returned Parameters
3.28.6 State When Issued
3.28.7 State Change
3.29 Initialize_Conversation (cminit)
3.29.1 Function Call
3.29.2 Function Call for Java CPI-C
3.29.3 Supplied Parameters
3.29.4 Returned Parameters
3.29.5 State When Issued
3.29.6 State Change
3.29.7 Usage Notes
3.30 Initialize_For_Incoming (cminic)
3.30.1 Function Call
3.30.2 Function Call for Java CPI-C
3.30.3 Supplied Parameters
3.30.4 Returned Parameters
3.30.5 State When Issued
3.30.6 State Change
3.31 Prepare_To_Receive (cmptr)
3.31.1 Function Call
3.31.2 Function Call for Java CPI-C
3.31.3 Supplied Parameters
3.31.4 Returned Parameters
3.31.5 State When Issued
3.31.6 State Change
3.31.7 Usage Notes
3.32 Receive (cmrcv)
3.32.1 How a Program Receives Data
3.32.2 Function Call
3.32.3 Function Call for Java CPI-C
3.32.4 Supplied Parameters
3.32.5 Returned Parameters
3.32.6 State When Issued
3.32.7 State Change
3.32.8 Usage Notes
3.33 Release_Local_TP_Name (cmrltp)
3.33.1 Function Call
3.33.2 Function Call for Java CPI-C
3.33.3 Supplied Parameters
3.33.4 Returned Parameters
3.33.5 State When Issued
3.33.6 State Change
3.33.7 Usage Notes
3.34 Request_To_Send (cmrts)
3.34.1 Action of the Partner Program
3.34.2 When the Local Program Can Send Data
3.34.3 Function Call
3.34.4 Function Call for Java CPI-C
3.34.5 Supplied Parameters
3.34.6 Returned Parameters
3.34.7 State When Issued
3.34.8 State Change
3.34.9 Usage Notes
3.35 Send_Data (cmsend)
3.35.1 Function Call
3.35.2 Function Call for Java CPI-C
3.35.3 Supplied Parameters
3.35.4 Returned Parameters
3.35.5 State When Issued
3.35.6 State Change
3.35.7 Usage Notes
3.36 Send_Error (cmserr)
3.36.1 Function Call
3.36.2 Function Call for Java CPI-C
3.36.3 Supplied Parameters
3.36.4 Returned Parameters
3.36.5 State When Issued
3.36.6 State Change
3.36.7 Usage Notes
3.37 Set_Conversation_Context (cmsctx)
3.37.1 Function Call
3.37.2 Function Call for Java CPI-C
3.37.3 Supplied Parameters
3.37.4 Returned Parameters
3.37.5 State When Issued
3.37.6 State Change
3.37.7 Usage Notes
3.38 Set_Conversation_Security_Password (cmscsp)
3.38.1 Function Call
3.38.2 Function Call for Java CPI-C
3.38.3 Supplied Parameters
3.38.4 Returned Parameters
3.38.5 State When Issued
3.38.6 State Change
3.38.7 Usage Notes
3.39 Set_Conversation_Security_Password (xcscsp)
3.40 Set_Conversation_Security_Type (cmscst)
3.40.1 Function Call
3.40.2 Function Call for Java CPI-C
3.40.3 Supplied Parameters
3.40.4 Returned Parameters
3.40.5 State When Issued
3.40.6 State Change
3.40.7 Usage Notes
3.41 Set_Conversation_Security_Type (xcscst)
3.42 Set_Conversation_Security_User_ID (cmscsu)
3.42.1 Function Call
3.42.2 Function Call for Java CPI-C
3.42.3 Supplied Parameters
3.42.4 Returned Parameters
3.42.5 State When Issued
3.42.6 State Change
3.42.7 Usage Notes
3.43 Set_Conversation_Security_User_ID (xcscsu)
3.44 Set_Conversation_Type (cmsct)
3.44.1 Function Call
3.44.2 Function Call for Java CPI-C
3.44.3 Supplied Parameters
3.44.4 Returned Parameters
3.44.5 State When Issued
3.44.6 State Change
3.44.7 Usage Notes
3.45 Set_CPIC_Side_Information (xcmssi)
3.45.1 Function Call
3.45.2 Supplied Parameters
3.45.3 Returned Parameters
3.45.4 State When Issued
3.45.5 State Change
3.45.6 Usage Notes
3.46 Set_Deallocate_Type (cmsdt)
3.46.1 Function Call
3.46.2 Function Call for Java CPI-C
3.46.3 Supplied Parameters
3.46.4 Returned Parameters
3.46.5 State When Issued
3.46.6 State Change
3.46.7 Usage Notes
3.47 Set_Error_Direction (cmsed)
3.47.1 Function Call
3.47.2 Function Call for Java CPI-C
3.47.3 Supplied Parameters
3.47.4 Returned Parameters
3.47.5 State When Issued
3.47.6 State Change
3.47.7 Usage Notes
3.48 Set_Fill (cmsf)
3.48.1 Function Call
3.48.2 Function Call for Java CPI-C
3.48.3 Supplied Parameters
3.48.4 Returned Parameters
3.48.5 State When Issued
3.48.6 State Change
3.48.7 Usage Notes
3.49 Set_Local_LU_Name (cmslln)
3.49.1 Function Call
3.49.2 Function Call for Java CPI-C
3.49.3 Supplied Parameters
3.49.4 Returned Parameters
3.49.5 State When Issued
3.49.6 State Change
3.49.7 Usage Notes
3.50 Set_Log_Data (cmsld)
3.50.1 Function Call
3.50.2 Function Call for Java CPI-C
3.50.3 Supplied Parameters
3.50.4 Returned Parameters
3.50.5 State When Issued
3.50.6 State Change
3.50.7 Usage Notes
3.51 Set_Mode_Name (cmsmn)
3.51.1 Function Call
3.51.2 Function Call for Java CPI-C
3.51.3 Supplied Parameters
3.51.4 Returned Parameters
3.51.5 State When Issued
3.51.6 State Change
3.51.7 Usage Notes
3.52 Set_Partner_LU_Name (cmspln)
3.52.1 Function Call
3.52.2 Function Call for Java CPI-C
3.52.3 Supplied Parameters
3.52.4 Returned Parameters
3.52.5 State When Issued
3.52.6 State Change
3.52.7 Usage Notes
3.53 Set_Prepare_To_Receive_Type (cmsptr)
3.53.1 Function Call
3.53.2 Function Call for Java CPI-C
3.53.3 Supplied Parameters
3.53.4 Returned Parameters
3.53.5 State When Issued
3.53.6 State Change
3.53.7 Usage Notes
3.54 Set_Processing_Mode (cmspm)
3.54.1 Function Call
3.54.2 Supplied Parameters
3.54.3 Returned Parameters
3.54.4 State When Issued
3.54.5 State Change
3.54.6 Usage Notes
3.55 Set_Receive_Type (cmsrt)
3.55.1 Function Call
3.55.2 Function Call for Java CPI-C
3.55.3 Supplied Parameters
3.55.4 Returned Parameters
3.55.5 State When Issued
3.55.6 State Change
3.55.7 Usage Notes
3.56 Set_Return_Control (cmsrc)
3.56.1 Function Call
3.56.2 Function Call for Java CPI-C
3.56.3 Supplied Parameters
3.56.4 Returned Parameters
3.56.5 State When Issued
3.56.6 State Change
3.56.7 Usage Notes
3.57 Set_Send_Type (cmsst)
3.57.1 Function Call
3.57.2 Function Call for Java CPI-C
3.57.3 Supplied Parameters
3.57.4 Returned Parameters
3.57.5 State When Issued
3.57.6 State Change
3.57.7 Usage Notes
3.58 Set_Sync_Level (cmssl)
3.58.1 Function Call
3.58.2 Function Call for Java CPI-C
3.58.3 Supplied Parameters
3.58.4 Returned Parameters
3.58.5 State When Issued
3.58.6 State Change
3.58.7 Usage Notes
3.59 Set_TP_Name (cmstpn)
3.59.1 Function Call
3.59.2 Function Call for Java CPI-C
3.59.3 Supplied Parameters
3.59.4 Returned Parameters
3.59.5 State When Issued
3.59.6 State Change
3.59.7 Usage Notes
3.60 Specify_Local_TP_Name (cmsltp)
3.60.1 Function Call
3.60.2 Function Call for Java CPI-C
3.60.3 Supplied Parameters
3.60.4 Returned Parameters
3.60.5 State When Issued
3.60.6 State Change
3.60.7 Usage Notes
3.61 Specify_Windows_Handle (xchwnd)
3.61.1 Function Call
3.61.2 Supplied Parameters
3.61.3 Returned Parameters
3.61.4 State When Issued
3.61.5 State Change
3.62 Test_Request_to_Send_Received (cmtrts)
3.62.1 Function Call
3.62.2 Function Call for Java CPI-C
3.62.3 Supplied Parameters
3.62.4 Returned Parameters
3.62.5 State When Issued
3.62.6 State Change
3.63 Wait_For_Conversation (cmwait)
3.63.1 Function Call
3.63.2 Supplied Parameters
3.63.3 Returned Parameters
3.63.4 State When Issued
3.63.5 State Change
3.63.6 Usage Notes
3.64 WinCPICCleanup
3.64.1 Function Call
3.64.2 Supplied Parameters
3.64.3 Returned Values
3.65 WinCPICIsBlocking
3.65.1 Function Call
3.65.2 Supplied Parameters
3.65.3 Returned Values
3.66 WinCPICSetBlockingHook
3.66.1 Function Call
3.66.2 Supplied Parameters
3.66.3 Returned Values
3.66.4 Usage
3.67 WinCPICStartup
3.67.1 Function Call
3.67.2 Supplied Parameters
3.67.3 Returned Values
3.68 WinCPICUnhookBlockingHook
3.68.1 Function Call
3.68.2 Supplied Parameters
3.68.3 Returned Values
3.69 WinCPICSetEvent
3.69.1 Function Call
3.69.2 Supplied Parameters
3.69.3 Returned Parameters
3.69.4 Usage Notes
3.70 WinCPICExtractEvent
3.70.1 Function Call
3.70.2 Supplied Parameters
3.70.3 Returned Parameters
3.70.4 Usage Notes
4 Sample CPI-C Transaction Programs
4.1 Processing Overview
4.2 Pseudocode
4.2.1 CSAMPLE1 (Invoking Program)
4.2.2 CSAMPLE2 (Invoked TP)
4.3 Testing the TPs
5 Sample Java CPI-C Transaction Program
5.1 Overview
5.2 Compiling, Linking, and Running the Sample Program
Appendix A: Common Return Codes
A.1 Return Codes from Any Partner Program
A.2 Non-CPI-C LU 6.2 Partner Program
Appendix B: Conversation State Changes
Index
