SunLink P2P CPI-C 9.1 Programmer s Manual

Transcription

1 SunLink P2P CPI-C 9.1 Programmer s Manual The Network Is the Computer Sun Microsystems Computer Company 2550 Garcia Avenue Mountain View, CA USA fax Part No.: Revision A, August 1997

2 Copyright 1997 Sun Microsystems, Inc Garcia Avenue, Mountain View, California U.S.A. All rights reserved. This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Parts of this product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U. S. and other countries, exclusively licensed through X/Open Company Ltd. RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR (g)(2)(6/87) and FAR (6/87), or DFAR (b)(6/95) and DFAR (a). Sun, Sun Microsystems, the Sun logo, AnswerBook, SunDocs, SunLink, OpenWindows, and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the U. S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U. S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. The OPEN LOOK and Sun Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun s written license agreements. DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright 1997 Sun Microsystems, Inc., 2550 Garcia Avenue, Mountain View, Californie U.S.A. Tous droits réservés. Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l utilisation, la copie et la décompilation. Aucune partie de ce produit ou de sa documentation associée ne peut être reproduite sous aucune forme, par quelque moyen que ce soit, sans l autorisation préalable et écrite de Sun et de ses bailleurs de licence, s il y en a. Des parties de ce produit pourront être derivées du système UNIX licencié par Novell, Inc. et du système Berkeley 4.3 BSD licencié par l Université de Californie. UNIX est une marque enregistrée aux Etats-Unis et dans d autres pays, et licenciée exclusivement par X/Open Company Ltd. Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun. Sun, Sun Microsystems, le logo Sun, AnswerBook, SunDocs, SunLink, OpenWindows, et Solaris sont des marques déposées ou enregistrées de Sun Microsystems, Inc. aux Etats-Unis et dans d autres pays. Toutes les marques SPARC, utilisées sous licence, sont des marques déposées ou enregistrées de SPARC International, Inc. aux Etats-Unis et dans d autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc. Les utilisateurs d interfaces graphiques OPEN LOOK et Sun ont été développés de Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de pionniers de Xerox Corporation pour la recherche et le développement du concept des interfaces d utilisation visuelle ou graphique pour l industrie de l informatique. Sun détient une licence non exclusive de Xerox sur l interface d utilisation graphique, cette licence couvrant aussi les licenciés de Sun qui mettent en place les utilisateurs d interfaces graphiques OPEN LOOK et qui en outre se conforment aux licences écrites de Sun. CETTE PUBLICATION EST FOURNIE "EN L ETAT" SANS GARANTIE D AUCUNE SORTE, NI EXPRESSE NI IMPLICITE, Y COMPRIS, ET SANS QUE CETTE LISTE NE SOIT LIMITATIVE, DES GARANTIES CONCERNANT LA VALEUR MARCHANDE, L APTITUDE DES PRODUITS A REPONDRE A UNE UTILISATION PARTICULIERE OU LE FAIT QU ILS NE SOIENT PAS CONTREFAISANTS DE PRODUITS DE TIERS. Please Recycle

3 Contents Preface xvii 1. Introduction to CPI-C SunLink LU6.2 CPI-C SunLink LU6.2 API SunLink P2P LU Server SunLink LU6.2 CPI-C Features Sun CPI-C Extensions X/Open CPI-C Extensions Side Information Automatic Character Conversion Unix Security Tracing Unsupported Features SunLink LU6.2 Components sunlu iii

4 1.6.2 sunpu sunpu2.config Basic Message Database (BMD) sunop sunscope Streams Drivers CPI-C Terms and Concepts Communication Across an SNA Network Program Partners and Conversations Operating Environment Side Information Node Services Operating System Program Calls Conversation Characteristics Modifying and Viewing Characteristics Automatic Conversation of Characteristics Non-Blocking Operations Program Flow States and Transitions Getting Started Installing SunLink LU Intra-Node Configuration Starting the SunLink PU2.1 SNA Server Stopping the SunLink PU2.1 SNA Server iv SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

5 3.5 Running the Application Stopping the Application Token Ring Loopback Configuration Token Ring Peer-to-Peer Configuration SunLink PU2.1 Monitoring and Control Using sunscope Configuration Resource Definition Logical Unit (LU) VTAM CICS AS/ Partner Logical Unit (PTNR_LU) VTAM CICS AS/ Mode (MODE) VTAM CICS AS/ Transaction Program (TP) CICS LU Access Security Information (SECURITY) Contents v

6 4.1.6 TP Resource Access Security Information (SEC_ACCESS) Security Session-Level Security Conversation-Level Security Unix-Level Security Using the CPI-C API CPI-C Call Conventions Handling Connections to the SunLink LU6.2 Server Connecting to the SunLink LU6.2 Server Disconnecting From the SunLink LU6.2 Server Avoiding the Use of Open_LU Allocating Conversations Accessing Side Information Accepting Conversations Accepting Multiple Conversations Accepting Conversations for Multiple TPs Handling Multiple Concurrent Conversations Mapped Conversations Sending Data Records Receiving Data Basic Conversations Allocating a Basic Conversation Sending Logical Records vi SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

7 5.7.3 Receiving Data Handling Multiple Connections to SunLink LU6.2 Server(s) Using Select Call to Multiplex LU6.2 Events Multiple Non-Blocking Conversations Mixing Non-Blocking and Blocking Conversations Polling for a Server Response CPI-C Calls SAA CPI-C Calls SunLink CPI-C Extensions X/Open CPI-C Extensions man Pages Accept_Conversation (CMACCP) Allocate (CMALLC) Cancel_Conversation (#CMCANC) Close_LU (*CMCLOS) Confirm (CMCFM) Confirmed (CMCFMD) Convert_Incoming (#CMCNVI) Convert_Outgoing (#CMCNVO) Deallocate (CMDEAL) Extract_Conversation_Security_Profile (#CMECSL) Extract_Conversation_Security_User_ID (#CMECSU) Contents vii

8 6.16 Extract_Conversation_State (CMECS) Extract_Conversation_Type (CMECT) Extract_Mode_Name (CMEMN) Extract_Partner_LU_Name (CMEPLN) Extract_Port_Descriptor (*CMEPD) Extract_Sync_Level (CMESL) Extract_TP_Name (#CMETPN) Flush (CMFLUS) Initialize_Conversation (CMINIT) Open_LU (*CMOPEN) Prepare_To_Receive (CMPTR) Receive (CMRCV) Request_To_Send (CMRTS) Select_LU (*CMSLU) Send_Data (CMSEND) Send_Error (CMSERR) Set_Accept_Processing_Mode (*CMSAPM) Set_Conversation_Security_Password (#CMSCSP) Set_Conversation_Security_Profile (*CMSCSL) Set_Conversation_Security_Type (#CMSCST) Set_Conversation_Security_User_ID (#CMSCSU) Set_Conversation_Type (CMSCT) viii SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

9 6.38 Set_Deallocate_Type (CMSDT) Set_Error_Direction (CMSED) Set_Fill (CMSF) Set_Local_TP_Name (*CMSLT) Set_Log_Data (CMSLD) Set_Mode_Name (CMSMN) Set_Partner_LU_Name (CMSPLN) Set_Prepare_To_Receive_Type (CMSPTR) Set_Processing_Mode (#CMSPM) Set_Receive_Type (CMSRT) Set_Return_Control (CMSRC) Set_Send_Type (CMSST) Set_Sync_Level (CMSSL) Set_TP_Name (CMSTPN) Set_Wait_Timeout (*CMSWTO) Specify_Local_TP_Name (#CMSLTPN) Test_Request_To_Send_Received (CMTRTS) Wait_For_Conversation (#CMWAIT) A. CPI-C Variables and Characteristics A-1 A.1 CPI-C Types A-1 A.1.1 Integers A-1 A.1.2 Character Strings A-1 A.2 Character Sets A-3 B. CPI-C Return Codes B-1 Contents ix

10 B.1 Return Code Description B-1 B.2 CM_ALLOCATE_FAILURE_NO_RETRY B-2 B.3 CM_ALLOCATE_FAILURE_RETRY B-3 B.4 CM_CONVERSATION_TYPE_MISMATCH B-3 B.5 CM_DEALLOCATED_ABEND B-3 B.6 CM_DEALLOCATED_ABEND_SVC B-4 B.7 CM_DEALLOCATED_ABEND_TIMER B-4 B.8 CM_DEALLOCATED_NORMAL B-4 B.9 CM_OK B-5 B.10 CM_OPERATION_INCOMPLETE B-5 B.11 CM_PARAMETER_ERROR B-5 B.12 CM_PIP_NOT_SPECIFIED_CORRECTLY B-5 B.13 CM_PRODUCT_SPECIFIC_ERROR B-6 B.14 CM_PROGRAM_ERROR_NO_TRUNC B-6 B.15 CM_PROGRAM_ERROR_PURGING B-6 B.16 CM_PROGRAM_ERROR_TRUNC B-7 B.17 CM_PROGRAM_PARAMETER_CHECK B-7 B.18 CM_PROGRAM_STATE_CHECK B-8 B.19 CM_RESOURCE_FAILURE_NO_RETRY B-8 B.20 CM_RESOURCE_FAILURE_RETRY B-8 B.21 CM_SECURITY_NOT_VALID B-9 B.22 CM_SVC_ERROR_NO_TRUNC B-9 B.23 CM_SVC_ERROR_PURGING B-9 B.24 CM_SVC_ERROR_TRUNC B-9 x SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

11 B.25 CM_SYNC_LVL_NOT_SUPPORTED_PGM B-10 B.26 CM_TPN_NOT_RECOGNIZED B-10 B.27 CM_TP_NOT_AVAILABLE_NO_RETRY B-10 B.28 CM_TP_NOT_AVAILABLE_RETRY B-11 B.29 CM_UNSUCCESSFUL B-11 C. CPI-C State Tables C-1 C.1 Explanation of State Table Abbreviations C-1 C.1.1 Conversation Characteristics ( ) C-2 C.1.2 Return Code Values [ ] C-3 C Data Received and Status Received { } C-4 C.2 Table Symbols C-5 C.2.1 How to Use the State Table C-5 C Example C-6 D. CPI-C Side Information D-1 D.1 Symbolic Destination File D-1 D.1.1 File Access D-2 D.1.2 File Format D-2 D.2 cpic_read_side_info D-3 E. CPI-C and LU E-1 E.1 CPI-C Features Not Found in LU E-1 E.2 LU6.2 Features Not Found in CPI-C E-2 E.2.1 CPI-C Conversations With LU6.2 Programs E-2 E.3 X/Open Extensions to SAA CPI-C E-2 Contents xi

12 F. CPI-C Include File F-1 G. Sample CPI-C Programs G-1 H. SunLink LU6.2 Configuration Examples H-1 Index Index-1 xii SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

13 Figures Figure 1-1 SunLink P2P LU Application Support Figure 1-2 SunLink P2PLU Components Figure 2-1 Programs Using CPI-C to Converse Through an SNA Network Figure 2-2 Operating Environment of a CPI-C Program Figure 3-1 Intra-Node Configuration Figure 3-2 Token Ring Loopback Configuration Figure 3-3 Token Ring Peer-to-Peer Configuration Figure 4-1 SunLink P2P LU Security Processing Figure 5-1 Logical Record Format xiii

14 xiv SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

15 Tables Table 1-1 Calls Supported by SunLink P2P CPI-C 9.1 API Table 1-2 CPI-C Calls and Functions Table 2-1 Starter-Set and Advanced-Function Calls Table 2-2 SAA CPI-C Characteristics and Default Values Table 2-3 Characteristics and Their Default Values - X/Open CPI-C Table 2-4 Automatic Conversation of Characteristics by CPI-C Table 2-5 CPI-C Conversation States Table 3-1 Initiator and Conversion Programs Table 6-1 SAA CPI-C Calls Table 6-2 SunLink P2P CPI-C 9.1 Extensions Table 6-3 X/Open CPI-C Extensions Table 6-4 Default Values for Conversion Characteristics Table 6-5 Initialized Values After Initialize Conversion Call Table A-1 CPI-C Variable Types A-2 Table A-2 Character Sets and A-4 Table C-1 Conversation Characteristics Abbreviations C-2 xv

16 Table C-2 Return Code Abbreviations C-3 Table C-3 Data Received Abbreviations C-4 Table C-4 Status Received Abbreviations C-5 Table C-5 Symbols Used in the State Table C-5 Table C-6 CPI-C State Table C-7 Table D-1 Directives in the Symbolic Destination File D-2 Table D-2 Symbolic Destination Parameters D-4 xvi SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

17 Preface This book is a reference manual for developers of SunLink P2P CPI-C 9.1 programs on Sun Workstations. SunLink P2P LU offers two application programming interfaces (APIs) for UNIX program developers. These APIs allow program-to-program communication across an IBM SNA network using Logical Unit type 6.2 (LU6.2). SunLink P2P LU supports the standard CPI-C programming interface described in this manual, and also provides a proprietary LU6.2 API. SunLink P2P LU uses the services of the SunLink SNA PU server product to provide peer-to-peer SNA communication support for Unix systems. The SunLink P2P LU SNA product set includes: An SNA interface, made up of SDLC, X.25, IBM Token Ring, and physical device drivers implemented in Unix System V streams A server that controls the SNA interface and provides SNA network access to its client applications The SunLink P2P LU APIs for users who wish to create LU6.2 applications, for example, the SunLink P2P CPI-C 9.1 API described in this document, and the SunLink P2P LU API xvii

18 Who Should Use This Book How This Book Is Organized Programmers can use this book as a guide to the use and features of the API. As a SunLink P2P CPI-C 9.1 programmer, you are expected to be familiar with the C programming language and the Unix operating system. You also should be familiar with the SNA advanced program-to-program communication (APPC) model for distributed transaction processing. This manual is divided into six chapters and eight appendixes, and is structured as follows: Chapter 1, Introduction to CPI-C, introduces the functions and features of SunLink P2P LU It describes how the client/server paradigm is used to allow for distribution of your programs on the local-area network (LAN). It illustrates how programs written using the CPI-C API communicate with peer programs in an SNA environment to provide an APPC application. Chapter 2, CPI-C Terms and Concepts, introduces the CPI-C model and describes the major terms and concepts used in CPI-C. This chapter provides the necessary background information you need to write CPI-C programs. Chapter 3, Getting Started, introduces you to SunLink P2P CPI-C 9.1 application programming. The chapter guides you through the steps necessary to build and run a sample CPI-C APPC application. The sample programs that make up the application are contained in the appendixes, together with the sample SNA configuration. You should work through this chapter carefully. Chapter 4, Configuration, describes how to configure local LU6.2s and define their TPs, partner LUs, and modes. Corresponding VTAM, CICS, and OS/400 configurations are discussed. This chapter is intended for system administrators, but it also must be understood by APPC application developers. Chapter 5, Using the CPI-C API, describes the nature of the CPI-C API and its use. This chapter explains how to organize your program and, with examples, illustrates how the API performs most of the standard LU6.2 operations. Chapter 6, CPI-C Calls, contains detailed manual pages for the CPI-C API calls. xviii SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

19 Related Documentation Appendix A, CPI-C Variables and Characteristics, defines the character sets and data types for the variables and characteristics used throughout this manual. Appendix B, CPI-C Return Codes, describes the CPI-C return_code. Appendix C, CPI-C State Tables, describes the CPI-C state table. Appendix D, CPI-C Side Information, describes the SunLink P2P LU implementation of CPI-C side information. Appendix E, CPI-C and LU6.2, describes the functional relationship between the LU6.2 verbs and the CPI-C calls described in this manual. It also summarizes the functional extensions to CPI-C provided by X/Open. Appendix F, CPI-C Include File, contains the SunLink P2P CPI-C 9.1 include file called suncpic.h. Appendix G, Sample CPI-C Programs, contains the CPI-C sample programs. Appendix H, SunLink LU6.2 Configuration Examples, contains SunLink LU6.2 configuration examples. Sun Documentation SunLink SNA PU Server Configuration and Administration Manual ( ) SunLink P2P LU Programmer s Manual ( ) SunLink SNA End Node Planning and Installation Manual ( ) IBM Documentation IBM Systems Network Architecture Concepts and Products (GC ) IBM Systems Network Architecture Technical Overview (GC ) IBM SNA Transaction Programmer's Reference Manual (GC ). (This document is referred to as [TPRM] in the text.) IBM SNA LU6.2 Reference: Peer Protocols (SC ) Preface xix

20 Typographic Conventions IBM SAA Common Programming Interface Communications Reference, (SC ). (This document is referred to as [CPI-C] in the text.) X/Open Developer's Specification, X/Open Company Ltd., UK, XO/DEV/90/050) The following table describes the typographic changes used in this book. Typeface or Symbol Meaning Example AaBbCc123 AaBbCc123 AaBbCc123 The names of commands, files, and directories; on-screen computer output. What you type, when contrasted with on-screen computer output. Command-line variable: replace with a real name or value. Book titles, new words or terms, words to be emphasized Edit your.login file. Use ls -a to list all files. % You have mail. % su Password: To delete a file, type rm filename. Read Chapter 6 in the User s Guide. These are called class options. You must be root to do this. Acknowledgments Sections of this manual were reproduced from IBM SAA Common Programming Interface Communications Reference with permission. The SunLink P2P CPI-C 9.1 product implementation follows the guidelines provided in the X/Open Developer's Specification from X/Open Company Ltd. xx SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

21 Shell Prompts in Command Examples Table P-1 Shell Prompts Shell Prompt C shell machine_name% C shell superuser machine_name# Bourne shell and Korn shell $ Bourne shell and Korn shell superuser # Ordering Sun Documents SunDocs SM is a distribution program for Sun Microsystems technical documentation. Easy, convenient ordering and quick delivery is available from SunExpress. You can find a full listing of available documentation on the World Wide Web: Table P-2 SunExpress Contact Information Country Telephone Fax United States United Kingdom Canada France Belgium Luxembourg Germany The Netherlands Sweden Switzerland Holland Japan Preface xxi

22 Sun Welcomes Your Comments Please use the Reader Comment Card that accompanies this document. We are interested in improving our documentation and welcome your comments and suggestions. If a card is not available, you can or fax your comments to us. Please include the part number of your document in the subject line of your or fax message. smcc-docs@sun.com Fax: SMCC Document Feedback xxii SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

23 Introduction to CPI-C SunLink LU6.2 CPI-C 1.2 SunLink LU6.2 API The SunLink P2P CPI-C 9.1 application programming interface (API) allows program-to-program communication using the IBM SNA Logical Unit 6.2 (LU6.2). CPI-C is the communication element of IBM SAA Common Programming Interface Communications Reference, see [CPIC]. CPI-C support is available across a wide range of IBM systems, and is becoming increasingly available on other manufacturers computers. The SunLink P2P CPI-C 9.1 is compatible with SAA CPI-C, the C language programs written to an SAA CPI-C interface. It ports readily to the Sun Workstation, and vice-versa. SunLink P2P CPI-C 9.1 follows the guidelines provided in the X/Open Developer's Specification, CPI-C. This specification extends SAA CPI-C to provide the functionality for implementing efficient Unix server applications. In particular, X/Open CPI-C allows a program to accept multiple startup requests and supports non-blocking. Appendix E, CPI-C and LU6.2, describes the X/Open extensions to CPI-C in more detail. The SunLink P2P CPI-C 9.1 API is layered on top of the SunLink P2P LU API. See the SunLink P2P LU Programmer s Manual. The SunLink P2P LU API provides full-featured access to the SunLink P2P LU6.2 server 1-1

24 1 1.3 SunLink P2P LU Server using the IBM SNA Transaction Programmer's Reference Manual architectured LU6.2 verb set. Most of the conversation support provided by the SunLink P2P LU API is available to CPI-C programs. Both CPI-C calls and LU6.2 verbs can be issued by the same program. Appendix E discusses the functional relationship between CPI-C and LU6.2 in more detail. If possible, use the CPI- C interface for basic or mapped conversations. The SunLink P2P LU API should be used for control operator programs. The CPI-C specification does not incorporate control operator verbs. The CPI-C API provides programs with access to the SunLink P2P LU server. The server can support multiple SunLink P2P LU client programs, and client programs can connect to multiple servers. As a TCP/IP network server, the SunLink P2P LU server provides LU6.2 services to its client applications running anywhere in the TCP/IP internetwork. The SunLink P2P LU server co-resides with the SunLink SNA PU server, which provides PU2.1 node services to SunLink P2P LU and the SunLink SNA end-point products such as SunLink 3270 and SunLink 3770/RJE. The SunLink SNA PU server supports token ring, SDLC, Ethernet and X.25 network connections into the SNA backbone network. Figure 1-1 summarizes the environment in which your SunLink P2P CPI-C 9.1 programs run. TPA is a SunLink P2P LU API program. Instances of SunLink P2P CPI-C 9.1 programs are shown as CP1 through CP SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

25 1 CP2 CP1 CP2 TPA TCP/IP CP3 SunLU6.2 CP4 SunPU2.1 TR APPC/PC CICS IBM mainframe AS/400 CPx TPx Conversation - CPI-C program - LU6.2 TP Figure 1-1 SunLink P2P LU Application Support 1.4 SunLink LU6.2 CPI-C Features All CPI-C calls are supported. Some functions are not available. (See Section 1.5, Unsupported Features. ) Table 1-1 lists the calls supported by the SunLink P2P CPI-C 9.1 API. Introduction to CPI-C 1-3

26 1 Table 1-1 Calls Supported by SunLink P2P CPI-C 9.1 API CPI-C Call CMACCP CMALLC CMCFM CMCFMD CMDEAL CMFLUS CMINIT CMPTR CMRCV CMRTS CMSEND CMSERR CMTRTS CMECS CMECT CMEMN CMEPLN CMESL CMSCT CMSDT CMSED CMSF CMSLD CMSMN CMSPLN CMSPTR Function Accept_Conversation Allocate Confirm Confirmed Deallocate Flush Initialize_Conversation Prepare_To_Receive Receive Request_To_Send Send_Data Send_Error Test_Request_To_Send_Received Extract_Conversation_State Extract_Conversation_Type Extract_Mode_Name Extract_Partner_LU_Name Extract_Sync_Level Set_Conversation_Type Set_Deallocate_Type Set_Error_Direction Set_Fill Set_Log_Data Set_Mode_Name Set_Partner_LU_Name Set_Prepare_To_Receive_Type 1-4 SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

27 1 Table 1-1 Calls Supported by SunLink P2P CPI-C 9.1 API (Continued) CPI-C Call CMSRT CMSRC CMSST CMSSL CMSTPN Function Set_Receive_Type Set_Return_Control Set_Send_Type Set_Sync_Level Set_TP_Name Sun CPI-C Extensions SunLink P2P CPI-C 9.1 provides extensions to CPI-C to support the establishment and management of connections to SunLink P2P LU6.2 servers. Additional calls support the use of security profiles. These Sun extensions are noted in the text of this manual by an asterisk prefix (*) X/Open CPI-C Extensions X/Open extensions follow the guidelines provided in the X/Open Developer's Specification, CPI-C. The X/Open extensions primarily allow for non-blocking operation. See Appendix E for more discussion on the X/Open CPI-C extensions. X/Open extensions are noted in the text of this manual by a hash prefix (#). Table 1-2 shows the CPI-C calls and their functions. Table 1-2 CPI-C Calls and Functions CPI-C Call Sun Connection Calls *CMCLOS *CMEPD *CMOPEN *CMSLU *CMSAPM Function Close_LU Extract_Port_Descriptor Open_LU Select_LU Set_Accept_Processing_Mode Introduction to CPI-C 1-5

28 1 Table 1-2 CPI-C Calls and Functions (Continued) CPI-C Call *CMSWTO *CMSLT Sun Conversation Characteristics *CMECSL *CMSCSL X/Open Extensions #CMCANC #CMCNVI #CMCNVO #CMECSU #CMETPN #CMSCSP #CMSCST #CMSCSU #CMSPM #CMSLTP #CMWAIT Function Set_Wait_Timeout Set_Local_TP_Name Extract_Conversation_Security_Profile Set_Conversation_Security_Profile Cancel_Conversation Convert_Incoming Convert_Outgoing Extract_Conversation_Security_User_ID Extract_TP_Name Set_Conversation_Security_Password Set_Conversation_Security_Type Set_Conversation_Security_User_ID Set_Processing_Mode Specify_Local_TP_Name Wait_For_Conversation Side Information SunLink P2P LU allows you to define CPI-C side information in simple Unix files. These files are accessed by the Initialize_Conversation call when a symbolic destination name is specified. Sun recognizes, however, that system administrators may want to maintain side information in a central database. For this reason the side information access routine, cpic_read_side_info, is included so that you may provide your own version. 1-6 SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

29 Automatic Character Conversion Your Unix system uses the ASCII character set, while the LU6.2 protocol requires that certain characteristics are transmitted as EBCDIC characters. The SunLink P2P CPI-C 9.1 API allows you to work with native ASCII characters for all such characteristics, converting them automatically to and from EBCDIC, as required. These characteristics are: Mode name Partner LU name Remote TP name Log data Conversation security user_id Conversation security password Conversation security profile User data must be sent in the character set expected by the remote TP. This could be ASCII or EBCDIC. The X/Open CPI-C extensions include the Convert_Incoming and Convert_Outgoing calls. These are called by the user program to convert user data from and to EBCDIC, respectively Unix Security SunLink P2P LU can be configured to use Unix security mechanisms to enforce conversation-level security. Thus, the user identifier and password (and optional profile) supplied on a conversation startup request is required to correspond, respectively, to a user name and password (and group), defined to Unix. See Chapter 4, Configuration, for more information Tracing SunLink P2P LU incorporates extensive trace capabilities to assist in developing and debugging your programs. Trace points are built into the CPI-C and LU6.2 APIs to provide information about program calls, program errors, exchange of buffers with the SunLink P2P LU server, and internal API errors. Traces may be selectively enabled using external trace flags, and output is written to a unique file. The trace facility is exposed so that you can include trace points in your own programs. Introduction to CPI-C 1-7

30 1 1.5 Unsupported Features 1.6 SunLink LU6.2 Components SunLink P2P LU does not currently support LU6.2 Sync-point services. The SunLink P2P CPI-C 9.1 API, therefore, does not support the SAA Resource Recovery Interface. To develop a SunLink P2P CPI-C 9.1 program, you should be familiar with the SunLink P2P LU components. In particular, you should be aware of the LU6.2 parameters defined in the SunLink SNA PU server. Refer to the SunLink SNA PU Server Configuration and Administration Manual for more information. Figure 1-2 identifies the SunLink P2P LU components, including the SunLink SNA CPI-C 9.1 API. 1-8 SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

31 1 LU6.2 program SunLink LU6.2 API CPI-C program CPI-C API SunLink LU6.2 API sun3270 sunop sunlu6.2 BMD sunscope sunpu2.1 sunpu2.config User Kernel Streams drivers System bus Communication ports Figure 1-2 SunLink P2PLU Components The illustrated components in Figure 1-2 are described in the next subsection sunlu6.2 Your programs connect to the sunlu6.2 daemon process for LU and Presentation Services. The sunlu6.2 daemon interfaces with the sunpu2.1 daemon for network access and to cooperate in control point functions. Introduction to CPI-C 1-9

32 sunpu2.1 The sunpu2.1 daemon process implements the higher-level SNA protocols and services. This process runs in the background in application space. It is responsible for starting the sunlu6.2 daemon and interfaces to the protocol drivers and with its client programs. In addition, the sunpu2.1 daemon processes local operator requests from sunop sunpu2.config The sunpu2.1 and sunlu6.2 daemon processes read a configuration file to determine the configured SNA resources. The configuration file default name is sunpu2.config Basic Message Database (BMD) The SunLink Basic Message Database (BMD) lists all error and informational messages displayed by the SunLink IBM Connectivity software sunop The sunop process implements the Sun local operator interface. This process allows you to monitor and control SNA resources sunscope The sunscope process is a logical data scope, which allows you to monitor the data sent and received on the data links Streams Drivers The serial communication boards and network interface controllers are managed by streams device drivers SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

33 CPI-C Terms and Concepts 2 CPI-C provides a consistent application programming interface for applications that require program-to-program communication. The interface uses SNA LU6.2 to create a rich set of inter-program services, including: Sending and receiving data Synchronizing processing between programs Notifying a partner of errors in the communication This chapter describes the major terms and concepts used in CPI-C. 2.1 Communication Across an SNA Network Figure 2-1 illustrates the logical view of an example SNA network. It includes three logical units (LUs): LU X, LU Y, and LU Z. Each LU is involved in two sessions. A session is the logical connection between two LUs. The network shown in Figure 2-1 is a simple one. In a real network, the number of LUs can be in the thousands. 2-1

34 2 Conversation with Program C Program A Program B Conversation with Program D CPI-C LU X (Type 6.2) SNA Network LU-LU Session LU-LU Session LU-LU Session LU Y LU Z CPI-C Conversation with Program A Conversation with Program B Program C Program D Figure 2-1 Programs Using CPI-C to Converse Through an SNA Network The LUs and the sessions shown in Figure 2-1 are Type 6.2. Although SNA defines many types of LUs, CPI-C only uses LU6.2 sessions. 2-2 SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

35 2 Note The physical network, which includes nodes (processors) and data links between nodes, is not shown in Figure 2-1 because a program using CPI-C does not recognize these resources. A CPI-C program uses the logical network of LUs, which in turn communicates with, and uses, the physical network. For more information about SNA networks, refer to IBM Systems Network Architecture Concepts and Products and IBM Systems Network Architecture Technical Overview. 2.2 Program Partners and Conversations Just as two LUs communicate using LU6.2 sessions, two CPI-C programs exchange data using a conversation. For example, the conversation between Program A and Program C is shown in Figure 2-1 as a single bold line between the two programs. The line indicating the conversation is shown on top of the session because a conversation connects programs over a session. CPI-C supports two types of conversations: Mapped conversations, which allow programs to exchange arbitrary data records in data formats agreed upon by the application programmers. Basic conversations, which allow programmers to exchange data in a standardized format. This format is a stream of data containing 2-byte length fields (referred to as LLs, which specify the amount of data to follow before the next length field. The typical data pattern is LL, data, LL, data. Each grouping of LL, data is referred to as a logical record. Note Because of the detailed manipulation of data and resulting complexity of error conditions, the use of basic conversations is intended for programmers using advanced functions. A more complete discussion of basic and mapped conversations is provided in the Usage Notes section of Send_Data (CMSEND) in Chapter 6, CPI-C Calls. For further information about basic and mapped conversations, refer to the IBM SNA LU6.2 Reference: Peer Protocols and IBM SNA Transaction Programmer's Reference Manual. CPI-C Terms and Concepts 2-3

36 2 Two programs involved in a conversation are called partners in the conversation. If an LU-LU session exists, or can be made to exist, between the nodes containing the partner programs, two CPI-C programs can communicate through an SNA network over a conversation. The terms local and remote are used to differentiate between different ends of a conversation. If a program is being discussed as local, its partner program is said to be the remote program for that conversation. For example, if Program A is being discussed, Program A is the local program and Program C is the remote program. Similarly, if Program C is being discussed as the local program, Program A is the remote program. Thus, a program can be both local and remote for a given conversation, depending on the context. Although program partners are generally thought of as residing in different nodes in a network, the local and remote programs may, in fact, reside in the same node. Two CPI-C programs communicate with each other in the same way, whether they are in the same or different nodes. Note A CPI-C program may establish a conversation with a program that is using the LU6.2 API for a particular environment and not CPI-C. The conversation between Program B and Program D in Figure 2-1 is an example of a CPI-C program communicating with a program that is using a productspecific LU6.2 API. Some restrictions may apply in this situation, since CPI-C does not support all LU6.2 functions. See Appendix E, CPI-C and LU6.2, for a more complete discussion. 2.3 Operating Environment Figure 2-2 provides a more detailed view of the operating environment of Program A, focusing on the node of the network that contains Program A. Lines showing services and connections to different generic components of the node indicate the components used by Program A to establish communication with another program. In Figure 2-2, two lines are connected to the bottom of the Program A block. The line on the right indicates the conversation as previously shown in Figure 2-1. The new line on the left shows Program A s communication with the communication element itself. This line represents a specific set of program 2-4 SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

37 2 calls that can be made using the local system s CPI-C library. The different types of CPI-C calls that a program may make are discussed in Section 2.4, Program Calls. Node environment Node services Side information Program A CPI-C LU X Operating system CPU cycles DASD Memory Conversation with Program C Figure 2-2 Operating Environment of a CPI-C Program In addition to the new line with CPI-C, Figure 2-2 shows three new generic elements in communication with Program A: Side information Node services Operating system CPI-C Terms and Concepts 2-5

38 Side Information For a program to establish a conversation with a partner program, CPI-C requires a certain amount of initialization information, such as the name of the partner program and the name of the LU at the partner s node. CPI-C provides a way to use system-defined values for these required fields; these systemdefined values are called side information. System administrators supply and maintain the side information for CPI-C programs. The side information is accessed by a symbolic destination name. The symbolic destination name, referred to as sym_dest_name in this book, corresponds to an entry in the side information containing some or all of the following seven pieces of information: partner_lu_name Indicates the name of the LU where the partner program is located. This LU name is any name for the remote LU recognized by the local LU for the purpose of allocating a conversation. mode_name Used by LU6.2 to designate the properties for the session that will be allocated for the conversation. The properties include, for example, the class of service to be used on the conversation. The system administrator defines a set of mode names used by the local LU to establish sessions with its partners. TP_name Specifies the name of the remote program. The TP_name stands for transaction program name, which comes from the LU6.2 architecture, where programs are referred to as transaction programs. In this manual, transaction program, application program, and program are synonymous, all denoting a program using CPI-C. See Appendix E for details of how a CPI-C program can interact with non-cpi-c programs. conversation_security_type Specifies the type of security information to be included in the conversation startup request. 2-6 SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

39 2 conversation_security_user_id Specifies the user ID to be supplied in the conversation startup request. This is used by the remote LU to validate access to the remote program. conversation_security_profile Specifies the profile to be supplied with the conversation_security_user_id in the conversation startup request. This is used by the remote LU to qualify the user_id in verifying access to the remote program. Profiles are similar in concept to Unix user groups. conversation_security_password Specifies the password to be supplied with the conversation_security_user_id in the conversation startup request. This is used by the remote LU to validate access to the remote program. Some advanced CPI-C programs supply their own destination information and do not use side information values. Such programs are less dependent on side information definitions and, therefore, can be more flexible. In this case sym_dest_name is left blank. For more information, see Initialize_Conversation (CMINIT) in Chapter Node Services Node services represents a number of utility type functions within the local systems environment that are available for CPI-C. These functions are not related to the actual sending and receiving of CPI-C data, and specific implementations differ from product to product. Node services include the following general functions: Setting and accessing of side information by system administrators This function is required to set up the initial values of side information and allow subsequent modification. It does not refer to individual program modification of the program s copy of the side information using Set calls as described in Section 2.5, Conversation Characteristics. Program-startup processing A program is started either by receipt of notification that the remote program has issued an Allocate call for the conversation or by local (operator) action. In either case, node services sets up the required data CPI-C Terms and Concepts 2-7

40 2 paths and operating environment required by the program and then allows the program to begin execution. In the former case, node services receives the notification, retrieves the name of the program to be started, and then proceeds as if starting a program by local action. Program-termination processing (both normal and abnormal) The program should terminate all conversations before the end of the program. However, if the program does not terminate all conversations, node services will abnormally deallocate any dangling conversations. See Close_LU (CMCLOS) and Deallocate (CMDEAL) in Chapter 6, CPI-C Calls for more information about terminating programs and deallocating conversations Operating System 2.4 Program Calls CPI-C depends on the operating system for the normal execution and operation of the program. CPI-C programs communicate with each other by making program calls. These calls are used to establish the characteristics of the conversation and to exchange data and control information between the programs. (Conversation characteristics are described in greater detail in the next section.) When a program makes a CPI-C call, the program passes characteristics and data to CPI-C using input_parameters. When the call completes, CPI-C passes data and status information back to the program using output_ parameters. The return_code parameter is returned for all CPI-C calls. It indicates whether a call completed successfully or if an error was detected that caused the call to fail. In non-blocking mode, the return_code can also indicate CM_OPERATION_INCOMPLETE, which means that the operation has been initiated but has not yet completed. See Section 2.8, Non-Blocking Operations, for details. 2-8 SunLink P2P CPI-C 9.1 Programmer s Manual August 1997

41 2 CPI-C uses additional output parameters on some calls to pass status information to the program. These parameters include the request_to_send_received parameter, the data_received parameter, and the status_received parameter. The function provided by CPI-C calls can be categorized into two groups: Starter-set calls The Starter-set calls allow for simple communication of data between two programs and assume that the program uses the initial values for the CPI-C conversation characteristics. The Starter-set includes the SunLink P2P LU6.2 CPI-C 9.1 extensions Open_LU and Close_LU. Advanced function calls The advanced function calls are used for more specialized processing than that provided by the default set of characteristic values. The Advancedfunction calls provide a more careful synchronization and monitoring of data. For example, the Set calls allow a program to modify conversation characteristics, and the Extract calls allow a program to examine the conversation characteristics that have been assigned to a given conversation. Most of the X/Open and SunLink P2P LU6.2 CPI-C 9.1 extensions to CPI-C can be considered advanced-function. Table 2-1 lists the two groups of CPI- C calls. Note The breakdown of function between Starter-set and Advanced-function calls is not intended to imply a restriction on how calls may be combined or used. Starter-set calls, for example, are often used together with Advancedfunction calls. The distinction between the two types of calls is intended to aid you and to indicate the relative degree of complexity. CPI-C Terms and Concepts 2-9