Distributed Data Processing (DDP-PPC) OSI Interface C Language

Transcription

1 !()+ OS 2200 Distributed Data Processing (DDP-PPC) OSI Interface C Language Programming Guide Copyright ( 1997 Unisys Corporation. All rights reserved. Unisys is a registered trademark of Unisys Corporation. Level 7R1 September 1997 Printed in U S America Priced Item

2 The names, places, and/or events used in this publication are not intended to correspond to any individual, group, or association existing, living, or otherwise. Any similarity or likeness of the names, places, and/or events with the names of any individual, living or otherwise, or that of any group or association is purely coincidental and unintentional. NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THE DOCUMENT. Any product and related material disclosed herein are only furnished pursuant and subject to the terms and conditions of a duly executed Program Product License or Agreement to purchase or lease equipment. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such License or Agreement. Unisys cannot accept any financial or other responsibility that may be the result of your use of the information in this document or software material, including direct, indirect, special, or consequential damages. You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used. The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions. RESTRICTED - Use, reproduction, or disclosure is subject to the restrictions set forth in DFARS and /FAR & for commercial computer software. Correspondence regarding this publication should be forwarded to Unisys Corporation either by using the Business Reply Mail form included with this document, or by addressing remarks to Unisys Corporation,Tredyffrin/Malvern Product Information, Malvern Development Center, P.O. Box 203, Paoli, PA, 19301, U.S.A.Comments about documentation can also be sent through to: aspgpi@unisys.com Unisys is a registered trademark of Unisys Corporation. All other terms mentioned in this document that are known to be trademarks or service marks have been appropriately capitalized. Unisys Corporation cannot attest to the accuracy of this information. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.

3 Contents About This Guide :::::::::::::::::::::::::::::::::::::::::::::: xvii Section 1. Introduction 1.1. Open System Networking :::::::::::::::::::::: 1-2 The Open Systems Interconnection (OSI) Reference Model :::::::::::::::::::::::::::::::::: 1-2 DDP-PPC and the OSI Model :::::::::::::::::::: 1-3 DDP-PPC and the OSI Interface ::::::::::::::::: 1-4 Session Layer Services ::::::::::::::::::: 1-5 Application Layer Services :::::::::::::::: Overview of Program-to-Program Applications ::: DDP-PPC and the C Language Interface ::::::::: 1-7 Section 2. Procedural Overview 2.1. C Language Program Structure :::::::::::::::: DDP-PPC Function Call Formats :::::::::::::::: 2-3 OSI Functions, C Language Function Calls, and Macros ::::::::::::::::::::::::::::::::: 2-5 DDP-PPC/OSI Data Packets :::::::::::::::::::: Copying Data Packets into C Language Programs 2-8 Choosing a #include PACKETS Element ::::::::::: 2-9 Choosing a #include TYPEDEFS Element :::::::::: 2-9 Choosing a #include EXTERNS Element ::::::::::: Message Buffer Area ::::::::::::::::::::::::: Message Size and Segmentation Considerations :: 2-13 Section 3. DDP-PPC/OSI Function Calls 3.1. Aborting a Conversation (osi_abort) ::::::::::::: 3-2 osi_abort Format :::::::::::::::::::::::::::: 3-2 osi_status_pkt :::::::::::::::::::::::::::::: 3-3 osi_msg_buffer Area ::::::::::::::::::::::::: iii

4 Contents osi_data_pkt :::::::::::::::::::::::::::::::: 3-5 osi_appl_pres_pkt ::::::::::::::::::::::::::: 3-7 osi_abort Example - Send with No Message ::::::: 3-8 osi_abort Example - Send with Message :::::::::: Initiating an Activity (osi_actmgt) ::::::::::::::: 3-11 osi_actmgt Format ::::::::::::::::::::::::::: 3-11 osi_status_pkt :::::::::::::::::::::::::::::: 3-12 osi_msg_buffer Area ::::::::::::::::::::::::: 3-13 osi_data_pkt :::::::::::::::::::::::::::::::: 3-14 osi_activity_pkt :::::::::::::::::::::::::::::: 3-17 osi_actmgt Example - Send with No Message :::::: 3-25 osi_actmgt Example - Send with Message ::::::::: Registering an Application Program with DDP-PPC (osi_ bind) :::::::::::::::::::::::::::::::: 3-27 osi_bind Format ::::::::::::::::::::::::::::: 3-27 osi_status_pkt :::::::::::::::::::::::::::::: 3-28 osi_signon_pkt :::::::::::::::::::::::::::::: 3-29 osi_bind Example :::::::::::::::::::::::::::: 3-30 osi_bind Example (TIP-Called Session Selector Format) ::::::::::::::::::::::::::::::::: Closing a Conversation (osi_close) :::::::::::::: 3-32 osi_close Format :::::::::::::::::::::::::::: 3-32 osi_status_pkt :::::::::::::::::::::::::::::: 3-33 osi_msg_buffer Area ::::::::::::::::::::::::: 3-34 osi_data_pkt :::::::::::::::::::::::::::::::: 3-35 osi_close Example - Send with No Message ::::::: 3-37 osi_close Example - Send with Message :::::::::: Accepting a Close Request (osi_clresp) :::::::::: 3-39 osi_clresp Format ::::::::::::::::::::::::::: 3-39 osi_status_pkt :::::::::::::::::::::::::::::: 3-40 osi_msg_buffer Area ::::::::::::::::::::::::: 3-41 osi_data_pkt :::::::::::::::::::::::::::::::: 3-42 osi_clresp Example - Send with No Message ::::::: 3-44 osi_clresp Example - Send with Message ::::::::: Sending Capability Data (osi_cpdata) :::::::::::: 3-46 osi_cpdata Format ::::::::::::::::::::::::::: 3-46 osi_status_pkt :::::::::::::::::::::::::::::: 3-47 osi_msg_buffer Area ::::::::::::::::::::::::: 3-48 osi_data_pkt :::::::::::::::::::::::::::::::: 3-49 osi_cpdata Example - Send with No Message :::::: 3-52 osi_cpdata Example - Send with Message ::::::::: Sending a Response to Capability Data Received (osi_cpresp) :::::::::::::::::::::::::::::: 3-54 osi_cpresp Format ::::::::::::::::::::::::::: 3-54 iv

5 Contents osi_status_pkt :::::::::::::::::::::::::::::: 3-55 osi_msg_buffer Area ::::::::::::::::::::::::: 3-55 osi_data_pkt :::::::::::::::::::::::::::::::: 3-57 osi_cpresp Example - Send with No Message :::::: 3-59 osi_cpresp Example - Send with Message ::::::::: Creating a New DDP-PPC Dump File (osi_dump) :: 3-61 osi_dump Format :::::::::::::::::::::::::::: 3-61 osi_status_pkt :::::::::::::::::::::::::::::: 3-62 osi_dump Example ::::::::::::::::::::::::::: Passing Control to a Peer Program (osi_gvcntrl) :: 3-63 osi_gvcntrl Format ::::::::::::::::::::::::::: 3-63 osi_status_pkt :::::::::::::::::::::::::::::: 3-64 osi_msg_buffer Area ::::::::::::::::::::::::: 3-65 osi_data_pkt :::::::::::::::::::::::::::::::: 3-66 osi_gvcntrl Example - Send with No Message :::::: 3-68 osi_gvcntrl Example - Send with Message ::::::::: Passing Tokens to a Peer Program (osi_gvtoken) : 3-70 osi_gvtoken Format :::::::::::::::::::::::::: 3-70 osi_status_pkt :::::::::::::::::::::::::::::: 3-71 osi_msg_buffer Area ::::::::::::::::::::::::: 3-72 osi_data_pkt :::::::::::::::::::::::::::::::: 3-73 osi_gvtoken Example - Send with No Message ::::: 3-76 osi_gvtoken Example - Send with Message :::::::: Opening a Conversation (osi_open) ::::::::::::: 3-78 osi_open Format :::::::::::::::::::::::::::: 3-78 osi_status_pkt :::::::::::::::::::::::::::::: 3-79 osi_msg_buffer Area ::::::::::::::::::::::::: 3-80 osi_data_pkt :::::::::::::::::::::::::::::::: 3-81 osi_connect_pkt ::::::::::::::::::::::::::::: 3-85 osi_appl_pres_pkt ::::::::::::::::::::::::::: 3-91 Additional Information for the Application Presentation Packet ::::::::::::::::::::::::::::::::: 3-93 osi_address_pkt ::::::::::::::::::::::::::::: 3-96 osi_open Example - Send with No Message :::::::: osi_open Example - Send with Message :::::::::: Accepting or Rejecting an Open Request (osi_opresp) :::::::::::::::::::::::::::::: osi_opresp Format ::::::::::::::::::::::::::: osi_status_pkt :::::::::::::::::::::::::::::: osi_msg_buffer Area ::::::::::::::::::::::::: osi_data_pkt :::::::::::::::::::::::::::::::: osi_connect_pkt ::::::::::::::::::::::::::::: osi_appl_pres_pkt ::::::::::::::::::::::::::: v

6 Contents Additional Information for the Application Presentation Packet ::::::::::::::::::::::::::::::::: Presentation Context Information ::::::::::: Application Context Information ::::::::::::: osi_address_pkt ::::::::::::::::::::::::::::: osi_opresp Example - Send with No Message :::::: osi_opresp Example - Send with Message ::::::::: Requesting Tokens from a Peer Program (osi_pltoken) :::::::::::::::::::::::::::::: osi_pltoken Format ::::::::::::::::::::::::::: osi_status_pkt :::::::::::::::::::::::::::::: osi_msg_buffer Area ::::::::::::::::::::::::: osi_data_pkt :::::::::::::::::::::::::::::::: osi_pltoken Example - Send with No Message :::::: osi_pltoken Example - Send with Message ::::::::: Receiving a Message from a Peer Program (osi_receive) :::::::::::::::::::::::::::::: osi_receive General Format :::::::::::::::::::: osi_status_pkt :::::::::::::::::::::::::::::: Receive New Format ::::::::::::::::::::::::: osi_status_pkt (Receive New Format) :::::::: osi_msg_buffer Area (Receive New Format) ::: osi_data_pkt (Receive New Format) ::::::::: osi_connect_pkt (Receive New Format) :::::: osi_appl_pres_pkt (Receive New Format) ::::: osi_address_pkt (Receive New Format) :::::: osi_rcv_pkt (Receive New Format) :::::::::: Receive Open Response Format :::::::::::::::: osi_status_pkt (Receive Open Response Format) :::::::::::::::::::::::::::: osi_msg_buffer Area (Receive Open Response Format) :::::::::::::::::::::::::::: osi_data_pkt (Receive Open Response Format) osi_connect_pkt (Receive Open Response Format) :::::::::::::::::::::::::::: osi_appl_pres_pkt (Receive Open Response Format) :::::::::::::::::::::::::::: osi_address_pkt (Receive Open Response Format) :::::::::::::::::::::::::::: osi_rcv_pkt (Receive Open Response Format) : Receive Existing Format ::::::::::::::::::::::: osi_status_pkt (Receive Existing Format) ::::: osi_msg_buffer Area (Receive Existing Format) osi_data_pkt (Receive Existing Format) ::::::: vi

7 Contents osi_appl_pres_pkt (Receive Existing Format) :: osi_rcv_pkt (Receive Existing Format) :::::::: osi_sync_pkt (Receive Existing Format) :::::: osi_activity_pkt (Receive Existing Format) :::: osi_resync_pkt (Receive Existing Format) ::::: osi_receive (Receive New Format) Example :::::::: osi_receive (Receive Open Response and Receive Existing Formats) Example :::::::::::::::::: Resynchronizing a Connection (osi_resync) :::::: osi_resync Format ::::::::::::::::::::::::::: osi_status_pkt :::::::::::::::::::::::::::::: osi_msg_buffer Area ::::::::::::::::::::::::: osi_data_pkt :::::::::::::::::::::::::::::::: osi_resync_pkt :::::::::::::::::::::::::::::: osi_resync Example - Send with No Message :::::: osi_resync Example - Send with Message ::::::::: Sending Normal Data (osi_send) :::::::::::::::: osi_send Format ::::::::::::::::::::::::::::: osi_status_pkt :::::::::::::::::::::::::::::: osi_msg_buffer Area ::::::::::::::::::::::::: osi_data_pkt :::::::::::::::::::::::::::::::: osi_send Example ::::::::::::::::::::::::::: Setting Synchronization Points (osi_sync) :::::::: osi_sync Format ::::::::::::::::::::::::::::: osi_status_pkt :::::::::::::::::::::::::::::: osi_msg_buffer Area ::::::::::::::::::::::::: osi_data_pkt :::::::::::::::::::::::::::::::: osi_sync_pkt ::::::::::::::::::::::::::::::: osi_sync Example - Send with No Message :::::::: osi_sync Example - Send with Message ::::::::::: Sending Typed Data (osi_tpdata) ::::::::::::::: osi_tpdata Format ::::::::::::::::::::::::::: osi_status_pkt :::::::::::::::::::::::::::::: osi_msg_buffer Area ::::::::::::::::::::::::: osi_data_pkt :::::::::::::::::::::::::::::::: osi_tpdata Example :::::::::::::::::::::::::: Deregistering an Application Program from DDP-PPC (osi_unbind) :::::::::::::::::::::: osi_unbind Format ::::::::::::::::::::::::::: osi_status_pkt :::::::::::::::::::::::::::::: osi_unbind Example :::::::::::::::::::::::::: Reporting Errors without Aborting (osi_xrpt) :::::: osi_xrpt Format ::::::::::::::::::::::::::::: osi_status_pkt :::::::::::::::::::::::::::::: vii

8 Contents osi_msg_buffer Area ::::::::::::::::::::::::: osi_data_pkt :::::::::::::::::::::::::::::::: osi_xrpt Example - Send with No Message :::::::: osi_xrpt Example - Send with Message ::::::::::: Section 4. Writing Application Programs 4.1. Sample Program Flow Design :::::::::::::::::: Automatic Scheduling ::::::::::::::::::::::::: 4-5 Automatic Scheduling of Batch Programs ::::::::: 4-5 Automatic Scheduling of TIP Transactions ::::::::: 4-8 Method 1: Referencing a PROGRAM Record ::: 4-9 Method 2: Defining the Transaction Using the TIP$ Called Session Selector Format ::::::::: 4-11 Section 5. Compiling and Executing C Language Application Programs 5.1. Preparing Programs for Execution :::::::::::::: Runstream for a UCS C Language Program-to-Program Application :::::::::::: Banking Considerations ::::::::::::::::::::::: 5-4 Appendix A. Data Packets and Defines A.1. Activity Packet ::::::::::::::::::::::::::::::: A-2 A.2. Address Packet :::::::::::::::::::::::::::::: A-3 A.3. Application Presentation Packet :::::::::::::::: A-5 A.4. Connect Packet :::::::::::::::::::::::::::::: A-7 A.5. Data Packet ::::::::::::::::::::::::::::::::: A-9 A.6. Receive Packet :::::::::::::::::::::::::::::: A-11 A.7. Resynchronization Packet ::::::::::::::::::::: A-12 A.8. Signon Packet ::::::::::::::::::::::::::::::: A-13 A.9. Status Packet :::::::::::::::::::::::::::::::: A-14 A.10. Synchronization Packet ::::::::::::::::::::::: A-15 A.11. TIP Name ::::::::::::::::::::::::::::::::::: A-16 A.12. Reserved Area and Unsigned Byte :::::::::::::: A-17 viii

9 Contents Appendix B. DDP-PPC/OSI Sample Programs B.1. Session Level Entry Primary Program Runstream : B-3 B.2. Session Level Entry Primary Program ::::::::::: B-4 B.3. Session Level Entry Secondary Program Runstream ::::::::::::::::::::::::::::::: B-13 B.4. Session Level Entry Secondary Program :::::::: B-14 B.5. Application Level Entry Primary Program Runstream ::::::::::::::::::::::::::::::: B-22 B.6. Application Level Entry Primary Program ::::::: B-23 B.7. Application Level Entry Secondary Program Runstream ::::::::::::::::::::::::::::::: B-32 B.8. Application Level Entry Secondary Program :::: B-33 Appendix C. DDP-PPC/OSI and ISO Cross-Reference Glossary Bibliography Index ix

10

11 Figures 1-1. The OSI Reference Model :::::::::::::::::::::::::::::::::::::: DDP-PPC in an OSI Network :::::::::::::::::::::::::::::::::::: DDP-PPC and Transport Services :::::::::::::::::::::::::::::::: DDP-PPC C Language Program-to-Program Facility :::::::::::::::::: Typical C Language DDP-PPC Block Diagram :::::::::::::::::::::: Automatic Scheduling of a Batch Program :::::::::::::::::::::::: Scheduling a TIP Program by Referencing an APPLICATION ENTITY Record ::::::::::::::::::::::::::::::::::::::::::::::::: Scheduling a TIP Transaction Using the TIP$ Format :::::::::::::::: Runstream to Compile and Execute a UCS C Language Program-to-Program Application :::::::::::::::::::::::::::::::::::::::::::::: xi

12

13 Tables 2-1. OSI Functions, DDP-PPC C Language Function Calls, and Macros ::::::: DDP-PPC C Language Function Calls and Their Data Packet Arguments :: osi_status_pkt Parameters for osi_abort :::::::::::::::::::::::::: osi_data_pkt Parameters for osi_abort ::::::::::::::::::::::::::: osi_appl_pres_pkt Parameters for osi_abort ::::::::::::::::::::::: osi_abort Example - Send with No Message ::::::::::::::::::::::: osi_abort Example - Send with Message :::::::::::::::::::::::::: osi_status_pkt Parameters for osi_actmgt :::::::::::::::::::::::: osi_data_pkt Parameters for osi_actmgt :::::::::::::::::::::::::: osi_activity_pkt Parameters for osi_actmgt :::::::::::::::::::::::: osi_actmgt Example - Send with No Message :::::::::::::::::::::: osi_actmgt Example - Send with Message ::::::::::::::::::::::::: osi_status_pkt Parameters for osi_bind ::::::::::::::::::::::::::: osi_signon_pkt Parameters for osi_bind :::::::::::::::::::::::::: osi_bind Example :::::::::::::::::::::::::::::::::::::::::::: osi_bind Example (TIP-Called Session Selector Format) :::::::::::::: Relationship of Token Availability :::::::::::::::::::::::::::::::: osi_status-pkt Parameters for osi_close :::::::::::::::::::::::::: osi_data_pkt Parameters for osi_close ::::::::::::::::::::::::::: osi_close Example - Send with No Message ::::::::::::::::::::::: osi_close Example - Send with Message :::::::::::::::::::::::::: osi_status_pkt Parameters for osi_clresp ::::::::::::::::::::::::: osi_data_pkt Parameters for osi_clresp :::::::::::::::::::::::::: osi_clresp Example - Send with No Message ::::::::::::::::::::::: osi_clresp Example - Send with Message ::::::::::::::::::::::::: osi_status_pkt Parameters for osi_cpdata :::::::::::::::::::::::: osi_data_pkt Parameters for osi_cpdata :::::::::::::::::::::::::: osi_cpdata Example - Send with No Message :::::::::::::::::::::: osi_cpdata Example - Send with Message ::::::::::::::::::::::::: osi_status_pkt Parameters for osi_cpresp :::::::::::::::::::::::: osi_data_pkt Parameters for osi_cpresp :::::::::::::::::::::::::: osi_cpresp Example - Send with No Message :::::::::::::::::::::: osi_cpresp Example - Send with Message ::::::::::::::::::::::::: osi_status_pkt Parameters for osi_dump ::::::::::::::::::::::::: osi_dump Example ::::::::::::::::::::::::::::::::::::::::::: Relationship of Token Availablility :::::::::::::::::::::::::::::::: osi_status_pkt Parameters for osi_gvcntrl :::::::::::::::::::::::: osi_data_pkt Parameters for osi_gvcntrl :::::::::::::::::::::::::: osi_gvcntrl Example - Send with No Message :::::::::::::::::::::: osi_gvcntrl Example - Send with Message ::::::::::::::::::::::::: Relationship of Token Availablility :::::::::::::::::::::::::::::::: xiii

14 Tables osi_status_pkt Parameters for osi_gvtoken :::::::::::::::::::::::: osi_data_pkt Parameters for osi_gvtoken ::::::::::::::::::::::::: osi_gvtoken Example - Send with No Message ::::::::::::::::::::: osi_gvtoken Example - Send with Message :::::::::::::::::::::::: osi_status_pkt Parameters for osi_open :::::::::::::::::::::::::: osi_data_pkt Parameters for osi_open ::::::::::::::::::::::::::: osi_connect_pkt Parameters for osi_open :::::::::::::::::::::::: Alternate Class Transports ::::::::::::::::::::::::::::::::::::: osi_appl_pres_pkt Parameters for osi_open ::::::::::::::::::::::: osi_address_pkt Parameters for osi_open :::::::::::::::::::::::: osi_open Example - Send with No Message :::::::::::::::::::::::: osi_open Example - Send with Message :::::::::::::::::::::::::: osi_status_pkt Parameters for osi_opresp :::::::::::::::::::::::: osi_data_pkt Parameters for osi_opresp :::::::::::::::::::::::::: osi_connect_pkt Parameters for osi_opresp :::::::::::::::::::::: osi_appl_pres_pkt Parameters for osi_opresp ::::::::::::::::::::: osi_address_pkt Parameters for osi_opresp ::::::::::::::::::::::: osi_opresp Example - Send with No Message :::::::::::::::::::::: osi_opresp Example - Send with Message ::::::::::::::::::::::::: Relationship of Token Availability :::::::::::::::::::::::::::::::: osi_status_pkt Parameters for osi_pltoken :::::::::::::::::::::::: osi_data_pkt Parameters for osi_pltoken ::::::::::::::::::::::::: osi_pltoken Example - Send with No Message :::::::::::::::::::::: osi_pltoken Example - Send with Message :::::::::::::::::::::::: osi_status_pkt Parameters for osi_receive :::::::::::::::::::::::: osi_data_pkt Parameters for osi_receive (Receive New Format) :::::::: osi_connect_pkt Parameters for osi_receive (Receive New Format) ::::: osi_appl_pres_pkt Parameters for osi_receive (Receive New Format) ::: osi_address_pkt Parameters for osi_receive (Receive New Format) ::::: osi_rcv_pkt Parameters for osi_receive (Receive New Format) ::::::::: osi_data_pkt Parameters for osi_receive (Receive Open Response Format) ::::::::::::::::::::::::::::::::::::::::::::::::: osi_connect_pkt Parameters for osi_receive (Receive Open Response Format) ::::::::::::::::::::::::::::::::::::::::::::::::: osi_appl_pres_pkt Parameters for osi_receive (Receive Open Response Format) ::::::::::::::::::::::::::::::::::::::::::::::::: osi_address_pkt Parameters for osi_receive (Receive Open Response Format) ::::::::::::::::::::::::::::::::::::::::::::::::: osi_rcv_pkt Parameters for osi_receive (Receive Open Response Format) osi_data_pkt Parameters for osi_receive (Receive Existing Format) ::::: osi_appl_pres_pkt Parameters for osi_receive (Receive Existing Format) : osi_rcv_pkt Parameters for osi_receive (Receive Existing Format) :::::: osi_sync_pkt Parameters for osi_receive (Receive Existing Format) ::::: osi_activity_pkt Parameters for osi_receive (Receive Existing Format) ::: osi_resync_pkt Parameters for osi_receive (Receive Existing Format) ::: osi_receive (Receive New Format) Example :::::::::::::::::::::::: osi_receive (Receive Open Response and Receive Existing Formats) Example :::::::::::::::::::::::::::::::::::::::::::::::: osi_status_pkt Parameters for osi_resync ::::::::::::::::::::::::: osi_data_pkt Parameters for osi_resync :::::::::::::::::::::::::: osi_resync_pkt Parameters for osi_resync :::::::::::::::::::::::: xiv

15 Tables osi_resync Example - Send with No Message :::::::::::::::::::::: osi_resync Example - Send with Message ::::::::::::::::::::::::: osi_status_pkt Parameters for osi_send :::::::::::::::::::::::::: osi_data_pkt Parameters for osi_send ::::::::::::::::::::::::::: osi_send Example ::::::::::::::::::::::::::::::::::::::::::: osi_status_pkt Parameters for osi_sync :::::::::::::::::::::::::: osi_data_pkt Parameters for osi_sync :::::::::::::::::::::::::::: osi_sync_pkt Parameters for osi_sync ::::::::::::::::::::::::::: osi_sync Example - Send with No Message :::::::::::::::::::::::: osi_sync Example - Send with Message ::::::::::::::::::::::::::: osi_status_pkt Parameters for osi_tpdata ::::::::::::::::::::::::: osi_data_pkt Parameters for osi_tpdata :::::::::::::::::::::::::: osi_tpdata Example :::::::::::::::::::::::::::::::::::::::::: osi_status_pkt Parameters for osi_unbind ::::::::::::::::::::::::: osi_unbind Example :::::::::::::::::::::::::::::::::::::::::: osi_status_pkt Parameters for osi_xrpt ::::::::::::::::::::::::::: osi_data_pkt Parameters for osi_xrpt :::::::::::::::::::::::::::: osi_xrpt Example - Send with No Message :::::::::::::::::::::::: osi_xrpt Example - Send with Message ::::::::::::::::::::::::::: B-1. Conversion Coding from Session Entry to Application Entry ::::::::::: B-1 C-1. Relationship between DDP-PPC Functions and OSI Services ::::::::::: C-1 C-2. Relationship between OSI Services and DDP-PPC Functions ::::::::::: C-2 C-3. Relationship between OSI Parameters and DDP-PPC C Language Members ::::::::::::::::::::::::::::::::::::::::::::::: C xv

16

17 About This Guide This guide is one of a series designed to instruct and guide you in using Unisys Distributed Data Processing Program-to-Program Communications (DDP-PPC) in an Open Systems Interconnection (OSI) network. The DDP-PPC/OSI interface lets users write program-to-program C language application programs in a network that adheres to OSI standards. Universal Compiling System (UCS) C language program-to-program applications can exchange data in batch, demand, or transaction processing (TIP) environments with similar programs in the same or in remote systems in an OSI network. Purpose The purpose of this guide is to instruct an applications programmer how to: $ Use a Unisys-supplied header file to include DDP-PPC/OSI C language interface pre-written data packets in a C language application program. $ Write a C language application program using the DDP-PPC/OSI C interface data packets and unique function calls. $ Compile the program using the UCS C compiler. $ Link the applications object module with the DDP-PPC supplied object modules. $ Execute a run of the object element. Scope This guide provides detailed information on DDP-PPC/OSI C function calls and data packets. It describes how to organize the calls and packets so users can write customized C applications that can exchange data between programs in the same or on remote nodes of a multihost OSI network. Audience This person is typically a C programmer with several years of experience in the language. He or she must have a thorough background in communications, as well as a working knowledge of the session service definition xvii

18 About This Guide If this person will be writing applications using the application-layer service entry, rather than the session-layer service entry, then he or she must also have a working knowledge of the presentation service definition and the Association Control Service Element (ACSE) service definition. This person must also be able to encode user data as defined by the presentation protocol specification and user information as defined by the ACSE protocol specification using the Basic Encoding Rules for Abstract Syntax Notation One (ASN.1). Prerequisites To understand this guide, you must know the C programming language as well as the open systems interconnection services and protocol as described in the International Standards Organization (ISO) documents listed in the Bibliography. How to Use This Guide Programmers should use this guide to learn how to design and construct program-to-program applications in an OSI environment. The guide shows you how to use C language #include statements and macros to insert and set information packets in your program. Use this guide also to learn how to compile, link, and execute the application program. Organization Section 1. Introduction Explains open systems interconnection and how DDP-PPC supports an OSI interface. Describes what you can do with a DDP-PPC/OSI C application. Gives an overview of how to write a DDP-PPC C language program for the OSI interface. Discusses interaction with communications elements. Section 2. Procedural Overview Describes the structure of a DDP-PPC C application program used in an OSI environment. Section 3. DDP-PPC/OSI Function Calls Describes, in alphabetical order, each of the DDP-PPC/OSI C function calls and its associated data packets. Section 4. Writing Application Programs Discusses how to design and construct OSI application programs that can transfer data between programs in the same or remote hosts in an OSI environment using C function calls. xviii

19 About This Guide Section 5. Compiling and Executing C Language Application Programs Describes the executive control language (ECL) runstream to compile and execute the DDP-PPC/OSI C programs. Appendix A. Data Packets and Defines Contains the data packets and defines to be included in the application program as the header file. Appendix B. DDP-PPC/OSI Sample Programs Contains a working example of a DDP-PPC application. Appendix C. DDP-PPC/OSI and ISO Cross-Reference Shows the relationship between the DDP-PPC/OSI functions and the OSI services invoked. Related Product Information Note: For all manuals, use the version that corresponds to the release level of the product software in use on the system. OS 2200 Distributed Data Processing (DDP-PPC/DDP-FJT) Messages Reference Manual ( ) This document lists and explains messages and program error codes for DDP-PPC. OS 2200 Distributed Data Processing Program to Program Communications (DDP-PPC) Implementation and Administration Guide ( ) This manual describes how to configure DDP-PPC, Communications Management System (CMS 1100) software, and Telcon software for a DDP-PPC network. It also describes how to collect, log, trace, and dump information that can help Unisys support personnel diagnose a problem reported in a user communication form (UCF). OS 1100 Universal Compiling System (UCS) C Programming Reference Manual, Volume 1: C Language and Library ( ) Describes the syntax and structure for writing C language statements and how to combine them into subroutines for UCS C language programs. OS 1100 Universal Compiling System (UCS) C Programming Reference Manual, Volume 2: Compiler and System Interface ( ) Describes how to compile UCS C language programs xix

20 About This Guide Notation Conventions C language is a case-sensitive programming language. Therefore, follow these notation conventions: $ Enter as uppercase any commands and keywords that appear as uppercase, and spell them exactly as shown in the examples following each function call description in Section 3. For example: $ Enter as lowercase any commands and keywords that appear as lowercase, and spell them exactly as shown in the examples following each function call description in Section 3. For example: New Features and Changes This release provides the following enhancements and changes: $ New limitations and other considerations for DuBank address ranges and multiactivity programs $ A new osi_address_pkt parameter that can be used in the osi_open function $ A new osi_status_packet version that is used with the new osi_address_pkt parameter xx

21 Section 1 Introduction The Distributed Data Processing Program-to-Program/Open Systems Interconnection (DDP-PPC/OSI) C language interface enables the exchange of data between programs in the same or remote hosts in an OSI network. This interface permits communication between any computer systems that use the international standards for OSI and also provide a user-callable program application or session layer interface. This section provides an overview of: $ Open System Networking, including the OSI Reference Model $ Program-to-program applications $ The DDP-PPC C language interface

22 Open System Networking 1.1. Open System Networking Communication networks that interconnect systems having different architectures are possible because the manufacturers of these systems have agreed to adhere to a set of standards. As communication networks have become commonplace, national and international organizations have recognized the need to establish such standards to allow a cooperative exchange of information in open system networks. The Open Systems Interconnection (OSI) Reference Model Although systems from various manufacturers may have different architectures, all communication systems perform the same functions. By looking at the functions performed rather than their implementation, you can more easily understand how DDP-PPC fits into the OSI network. International standards for open system networking are based on the OSI reference model, a conceptual model for a communications network developed by the International Standards Organization (ISO). This model represents each system in a network as a logical series of seven functional layers (see Figure 1-1). Each layer interfaces with the layer below and the layer above. Message Path Common Protocol Layers Application Presentation Session Transport Network Data Link Physical Originating System Receiving System Figure 1-1. The OSI Reference Model Each logical layer represents a single service performed by the system. Because different systems perform these services in different ways, these logical layers may or may not correspond to physical components of the system. A hardware or software entity can overlap layers or include more than one layer by performing more than one service

23 Open System Networking Hardware or software components that perform comparable services within a single layer of the model but on different systems in the network are called peer entities. Asetofrules for communication between peer entities is called a peer protocol. The peer protocols for each layer are independent of the protocols of any other layer. According to the model, when different systems in an OSI network agree on the peer protocols, peer entities across the network can exchange information, regardless of the internal functioning of each system. That is, application programs on one system can exchange messages with application programs on any system in the network regardless of system architecture. DDP-PPC and the OSI Model Figure 1-2 represents DDP-PPC in an OSI network. Message Path Common Protocol Layers DDP-PPC Transport Services Application Presentation Session Transport Network Data Link Physical Originating System Receiving System Figure 1-2. DDP-PPC in an OSI Network In an OS 2200 system, DDP-PPC performs the application, presentation, and session layer processes ((see Figure 1-3) as follows: $ The application layer provides the means to establish an association between itself and another application program for the purpose of exchanging information. $ The presentation layer provides translation between data formats. $ The session layer coordinates the exchange of information between the end-user applications. Either Communications Management System (CMS 1100) or Telcon in the distributed communication processor (DCP) front-end processor performs the functions of the lowest four layers (transport services). Some of the functions transport services performs are message routing, device connection, and transmission error detection

24 Open System Networking Host A Application Program Host B Application Program File Transport Services DDP-PPC CMS 1100 Host LAN Connection Transport Services TELCON OSITS X.25 PSCS OSI-PDN Figure 1-3. DDP-PPC and Transport Services When you use DDP-PPC/OSI applications in a network with only OS 2200 or U Series, you can use one of three kinds of transport: $ Open Systems Interconnection (OSI) $ Distributed Communications Architecture (DCA) $ Transmission Control Protocol/Internet Protocol (TCP/IP) When you use DDP-PPC/OSI applications in a network with foreign hosts, you normally use the OSI transport protocols but, depending on the foreign system, may also be able to use TCP/IP transport protocols. The software that provides OSI Transport Layer Services is located in CMS 1100 or in the DCP. Depending on your configuration, you may use either of these transport service providers or, in some cases, both. If you want to use DDP-PPC/OSI with a foreign vendor using TCP/IP Transport Services, that vendor must have implemented RFC 1006, which allows OSI Transport Layer Services to be mapped onto TCP/IP. DDP-PPC and the OSI Interface The two interface points into OSI services for all user functions are: $ Application layer services $ Session layer services The function call is the same for both interfaces. Specify a parameter (osi_service_entry) at connection establishment to determine the interface for the remainder of the connection

25 Open System Networking Session Layer Services The session layer services entry is for programmers who want to write their own application and presentation layers, or who want direct access to the OSI session layer services. When you request the session layer entry, only the services the session layer provides are accessible. DDP-PPC does not provide any services of the application or presentation layers when you select session layer entry. Application Layer Services When you select the application layer entry, DDP-PPC provides the OSI ACSE and presentation layer services. These consist of: $ All ACSE services $ Negotiation of presentation context lists $ Generation of all ACSE and presentation layer protocol except user data However, when you specify the application level entry, the application program may still have to perform some of the following presentation layer functionality, depending on which user data type is used: $ Encode the user data with the correct transfer syntax before requesting any DDP-PPC/OSI services. This involves coding the data according to the rules of the selected transfer syntax. DDP-PPC expects the data to be encoded correctly as it has no way of verifying the encoding. The application program should use the presentation context list, negotiated during connection establishment, when encoding the data. $ Decode any user data received in a message from DDP-PPC and return the appropriate presentation layer error messages if it encounters errors during the decoding

26 Overview of Program-to-Program Applications 1.2. Overview of Program-to-Program Applications The DDP-PPC C language program-to-program facility passes data between programs in the same host or remote hosts using Unisys DCA or OSI protocol (see Figure 1-4). (This data may include status or informational messages, control information, records from a file, etc.) Computer A Computer B C Program A Data C Program B Data C Program C Figure 1-4. DDP-PPC C Language Program-to-Program Facility

27 DDP-PPC and the C Language Interface 1.3. DDP-PPC and the C Language Interface You can use the DDP-PPC/OSI C language interface with programs compiled with the UCS C compiler. A program compiled under the UCS C compiler produces an object module. This object must be statically or dynamically linked with the DDP-PPC OSI interface object module, OSI-UCSIF-OM. This module converts the C language function calls into DDP-PPC format

28

29 Section 2 Procedural Overview This section discusses procedures for writing OSI/DDP-PPC C language programs. The following topics are discussed: $ C language program structure (Section 2.1) $ DDP-PPC function call formats (Section 2.2) $ Copying data packets into C language programs (Section 2.3) $ The message buffer area (Section 2.4) $ Message size and segmentation considerations (Section 2.5)

30 C Language Program Structure 2.1. C Language Program Structure Although DDP-PPC C language programs are similar to conventional programs, they require certain additional features to perform in an OSI network. These features are: $ DDP-PPC/OSI function calls $ DDP-PPC/OSI data packets

31 DDP-PPC Function Call Formats 2.2. DDP-PPC Function Call Formats Function calls: $ Are the program s means of transferring data between programs $ Always contain arguments that reference data packets (see Table 2-2) Data packets consist of control information and data needed for program-to-program communications.the basic format for all function calls is: where: function Is the name of the DDP-PPC function the application program requested (see Table 2-1). arg Is the name of the data packet storage area. The arguments are positional. Code them in the order in which they are shown in each function call described in this section. After processing a function call, DDP-PPC returns a general status code, a detailed status code, and, possibly, a specific error code. The DDP-PPC/DDP-FJT Messages Reference Manual explains these codes. DDP-PPC returns the codes to the program in two ways: 1. In the osi_status_pkt class_code, detail_status, and specific_error fields. 2. As a function return value when the DDP-PPC function call or macro call is coded as an assignment to a variable. The value returned is an integer with a value of (class_code * detail_status). Note: The specific error is not part of the function return value

32 DDP-PPC Function Call Formats The following example checks the status of the OSI_BIND macro call using both of the above methods: Method 1 Method

33 DDP-PPC Function Call Formats OSI Functions, C Language Function Calls, and Macros Table 2-1 lists the OSI functions used in an OSI network and their associated DDP-PPC/OSI C language function calls. Section 3 describes each of these functions in detail. Table 2-1. OSI Functions, DDP-PPC C Language Function Calls, and Macros Function Function Call Macro Abort the conversation osi_abort OSI_ABORT Initiate an OSI activity osi_actmgt OSI_ACTMGT Register with DDP-PPC (initiate a session) osi_bind OSI_BIND Close the connection osi_close OSI_CLOSE Accept a close request osi_clresp OSI_CLRESP Send capability data osi_cpdata OSI_CPDATA Send a response to capability data osi_cpresp OSI_CPRESP Create new dump file osi_dump OSI_DUMP Pass all available tokens to a peer osi_gvcntrl OSI_GVCNTRL Pass a combination of tokens to the peer osi_gvtoken OSI_GVTOKEN Open the conversation osi_open OSI_OPEN Accept or reject an open osi_opresp OSI_OPRESP Request a combination of tokens from the peer osi_pltoken OSI_PLTOKEN Receive messages osi_receive OSI_RECEIVE Reset synchronization points osi_resync OSI_RESYNC Send messages osi_send OSI_SEND Set synchronization points osi_sync OSI_SYNC Send typed data osi_tpdata OSI_TPDATA Release DDP-PPC resources (terminate a session) osi_unbind OSI_UNBIND Report errors - no abort osi_xrpt OSI_XRPT

34 DDP-PPC Function Call Formats DDP-PPC/OSI Data Packets Each function call references a set of data packets. Data packets contain the information DDP-PPC needs to execute its various functions. Table 2-2 lists the C function calls and their associated data packets. Appendix A shows the data packets in detail. Table 2-2. DDP-PPC C Language Function Calls and Their Data Packet Arguments Function Call Data Packets Referenced in Arguments osi_abort ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt, (int)&osi_appl_pres_pkt); osi_actmgt ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt, (int)&osi_activity_pkt); osi_bind ((int)&osi_status_pkt, (int)&osi_signon_pkt); osi_close ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt); osi_ciresp ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt); osi_cpdata ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt); osi_cpresp ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt); osi_dump ((int)&osi_status_pkt); osi_gvcntrl ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt); osi_gvtoken ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt); osi_open ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt, (int)&osi_connect_pkt, (int)&osi_appl_pres_pkt, (int)&osi_address_pkt); osi_opresp ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt, (int)&osi_connect_pkt, (int)&osi_appl_pres_pkt, (int)&osi_address_pkt); osi_pltoken ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt); osi_receive ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt, (int)&osi_connect_pkt, (int)&osi_appl_pres_pkt, (int)&osi_address_pkt, (int)&osi_rcv_pkt, (int)&osi_sync_pres_pkt, (int)&osi_activity_pkt, (int)&osi_resync_pkt); continued

35 DDP-PPC Function Call Formats Table 2-2. DDP-PPC C Language Function Calls and Their Data Packet Arguments (cont.) Function Call Data Packets Referenced in Arguments osi_resync ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt, (int)&osi_resync_pkt); osi_send ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt); osi_sync ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt, (int)&osi_sync_pkt); osi_tpdata ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt); osi_unbind ((int)&osi_status_pkt); osi_xrpt ((int)&osi_status_pkt, (int)osi_msg_buffer, (int)&osi_data_pkt);

36 Copying Data Packets into C Language Programs 2.3. Copying Data Packets into C Language Programs DDP-PPC contains several header elements (.h elements) in the SYS$LIB$*DDP-PPC-3 file. The file contains elements for: $ Defining packet variables and allocating storage (OSI-UCINCLD/PACKETS) $ Declaring typedefs for the packet data structures (OSI-UCINCLD/TYPEDEFS) $ Declaring external packet variables (OSI-UCINCLD/EXTERNS) To access the header elements, use the file inclusion statement #include. The format is: where: PPC-COPY Is name for the include file. You must use statement in the ECL stream so the compiler can equate this name to the DDP-PPC copy file (see Section 5). OSI-UCINCLD Is the element name within the DDP-PPC include file that indicates the element for the DDP-PPC/OSI C language interface. hdrname Indicates the specific name of the OSI-UCINCLD element to include. The name you use depends on which specific header element you want to include. Valid names are:

37 Copying Data Packets into C Language Programs Choosing a #include PACKETS Element The PACKETS element defines and declares the required macro definitions, data packet structures (see Appendix A), and storage assignments necessary to use the DDP-PPC/OSI interface.when this elementis used, itincludesthe TYPEDEFS elements. You do not need to code the storage assignment statements or the function calls. In our examples, we use osi_msg_buffer as the message buffer name. You can specify your own buffer name, but you must declare the storage assignment for it and then use this name as the argument in the macro. For example, if you select PACKETS, you only need to code the following: or Choosing a #include TYPEDEFS Element Use the TYPEDEFS element if you only want to include the data packet structures. It uses the C language construct to describe the DDP-PPC/OSI packets. If you use this statement, you must code the storage assignment statements and the function calls

38 Copying Data Packets into C Language Programs In our examples, we use osi_msg_buffer as the message buffer name. You can specify your own buffer name, but you must declare the storage assignment for it and then use this name as the argument in the function call. You could also allocate the storage assignments with your own names, then use them in the function call. For example, if you select TYPEDEFS, you need to code the following: or

39 Copying Data Packets into C Language Programs Choosing a #include EXTERNS Element Use the EXTERNS element if you want packet declarations for externally defined packets. When this element is used, it also includes the TYPEDEFS elements. You do not need to allocate the storage assignments in this module or code the function calls. However, you do need to allocate the storage assignment in another module. For example, if you select EXTERNS, you need to code the following in this module: or To avoid duplicate definitions, all include elements test to see if they have been defined previously in case you included them more than once. Notes: $ All areas defined as RESERVED_AREA in the data packet structures in Appendix A should be initialized to octal 0 before the first function call to DDP-PPC is issued and this area should not be used on subsequent function calls. $ C language programmers should especially be aware of implementation differences in how the OS 2200 system stores and retrieves data (such as the TAB and NULL characters)

40 Message Buffer Area 2.4. Message Buffer Area You need to define a message buffer area. It will contain the data to be given to DDP-PPC for output functions or the data DDP-PPC received for the osi_receive function. The header file include statement does not supply this area. This area does not have to have a specific name, since it is passed as a parameter on all the function calls or macros that require it. In fact, you can define different areas for different types of functions such as input_message_buffer for the osi_receive function, output_message_buffer for the osi_send function, and error_buffer for the osi_abort function. Example:

41 Message Size and Segmentation Considerations 2.5. Message Size and Segmentation Considerations The OSI session layer protocol limits how much user data can be sent on most session services. It imposes these limits at the session layer (called session user data), where the message includes the user data and any additional protocol parameters the DDP-PPC/OSI services generate. The length of the protocol header cannot be determined before it is actually built because many dynamic factors determine its length. Therefore, the user program may get an error indicating that too much data was specified in the message buffer, even though its user data did not exceed the maximum allowed for that function. For example, the osi_open function (using session version 1) is the most susceptible to this type of error because of the 512-byte size limitation and the large amount of protocol header information it generates to open a connection. The normal and typed data session services (using session version 2) allow for the transfer of messages of unlimited size. Since DDP-PPC limits the user program message size for each function to bytes, it supports unlimited-size messages by using OSI session and transport layer segmentation and treating the data passed on each function call as a segment of the larger message. You can send segmented messages on the osi_send and osi_tpdata functions by setting the unit_indicator parameter in osi_data_pkt to 0, OSI_MSG_INCOMPL. This tells DDP-PPC to treat the data passed on this function as a segment of a larger message. DDP-PPC will treat data from subsequent osi_send or osi_tpdata functions in the same manner until one of the functions sets the unit_indicator to 1, OSI_MSG_COMPL, which signifies the end of the large message. DDP-PPC also uses the unit_indicator on the osi_receive function to indicate that the data given to the user program is part of a larger message. It returns a value of OSI_MSG_INCOMPL on subsequent osi_receive functions until it receives an end-of-message indication from the transport layer services. To prevent data loss, the receiving program should be prepared to receive messages as large as bytes if segmentation can be used on the connection, even if the peer program has always sent smaller segments. This is necessary because the OSI protocol does not provide a way to reconstruct the segments on the receiving side the same as they were constructed on the sending side. Consequently, DDP-PPC may receive a message as large as bytes from the lower layers