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

!()+ OS 2200 Distributed Data Processing (DDP-PPC) DCA 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 3787 3254-100

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 252.227-7013 and 252.11-15/FAR 52.227-14 and 52.227-19 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 e-mail to aspgpi@unisys.com All 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.

Contents About This Guide :::::::::::::::::::::::::::::::::::::::::::::: xi Section 1. Introduction 1.1. DDP-PPC and the DCA Interface :::::::::::::::: 1-1 1.2. DDP-PPC and the UCS C Language Interface ::::: 1-2 1.3. Status Codes and Error Messages :::::::::::::: 1-3 Section 2. Procedural Overview 2.1. C Language Program Structure :::::::::::::::: 2-1 2.2. Copying Data Packets into C Language Programs 2-5 2.2.1. Choosing a #include PACKETS Element :::::::: 2-6 2.2.2. Choosing a #include TYPEDEFS Element ::::::: 2-7 2.2.3. Choosing a #include EXTERNS Element :::::::: 2-8 2.3. DDP-PPC Function Call Formats :::::::::::::::: 2-9 Section 3. C Language Function Calls 3.1. Aborting a Conversation (ipc_abort) ::::::::::::: 3-1 3.1.1. ipc_abort Format :::::::::::::::::::::::::: 3-1 3.1.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-2 3.1.3. ipc_msg_buffer area ::::::::::::::::::::::: 3-2 3.1.4. ipc_data_pkt Packet ::::::::::::::::::::::: 3-3 3.1.5. ipc_data_packet Additional Information ::::::::: 3-4 3.1.6. ipc_abort Example - Send with No Message ::::: 3-4 3.1.7. ipc_abort Example - Send with Message ::::::: 3-5 3.2. Signing on to DDP-PPC (ipc_bind) ::::::::::::::: 3-6 3.2.1. ipc_bind Format ::::::::::::::::::::::::::: 3-6 3.2.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-6 3.2.3. ipc_signon_pkt Packet :::::::::::::::::::::: 3-7 3.2.4. ipc_bind Example :::::::::::::::::::::::::: 3-7 3.3. Terminating a Conversation (ipc_close) :::::::::: 3-8 3.3.1. ipc_close Format :::::::::::::::::::::::::: 3-8 3787 3254-100 iii

Contents 3.3.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-8 3.3.3. ipc_msg_buffer area ::::::::::::::::::::::: 3-9 3.3.4. ipc_data_pkt Packet ::::::::::::::::::::::: 3-10 3.3.5. ipc_close Example - Send with No Message ::::: 3-11 3.3.6. ipc_close Example - Send with Message :::::::: 3-11 3.4. Responding to an Open or Close with a Close Confirmation (ipc_cls_confirm) :::::::::::::: 3-12 3.4.1. ipc_cls_confirm Format ::::::::::::::::::::: 3-12 3.4.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-13 3.4.3. ipc_msg_buffer area ::::::::::::::::::::::: 3-13 3.4.4. ipc_data_pkt Packet ::::::::::::::::::::::: 3-14 3.4.5. ipc_cls_confirm Example - Send with No Message 3-15 3.4.6. ipc_cls_confirm Example - Send with Message ::: 3-15 3.5. Initiating a DDP-PPC Autodump (ipc_dump) :::::: 3-16 3.5.1. ipc_dump Format :::::::::::::::::::::::::: 3-16 3.5.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-16 3.5.3. ipc_dump Example :::::::::::::::::::::::: 3-17 3.6. Sending an Unsolicited Message (ipc_exception) : 3-18 3.6.1. ipc_exception Format :::::::::::::::::::::: 3-18 3.6.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-19 3.6.3. ipc_msg_buffer area ::::::::::::::::::::::: 3-19 3.6.4. ipc_data_pkt Packet ::::::::::::::::::::::: 3-20 3.6.5. ipc_exception Example - Send with No Message :: 3-21 3.6.6. ipc_exception Example - Send with Message :::: 3-21 3.7. Opening a Conversation (ipc_open) ::::::::::::: 3-22 3.7.1. ipc_open Format :::::::::::::::::::::::::: 3-22 3.7.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-23 3.7.3. ipc_msg_buffer area ::::::::::::::::::::::: 3-23 3.7.4. ipc_data_pkt Packet ::::::::::::::::::::::: 3-24 3.7.5. ipc_open_pkt Packet ::::::::::::::::::::::: 3-25 3.7.6. ipc_open Example - Send with No Message ::::: 3-25 3.7.7. ipc_open Example - Send with Message :::::::: 3-26 3.8. Passing Control to Another Program (ipc_passoff) 3-27 3.8.1. ipc_passoff Format :::::::::::::::::::::::: 3-27 3.8.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-27 3.8.3. ipc_data_pkt Packet ::::::::::::::::::::::: 3-28 3.8.4. ipc_passoff Example ::::::::::::::::::::::: 3-28 3.9. Receiving a Message (ipc_receive) ::::::::::::: 3-29 3.9.1. ipc_receive Format :::::::::::::::::::::::: 3-29 3.9.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-30 3.9.3. ipc_msg_buffer area ::::::::::::::::::::::: 3-30 3.9.4. ipc_data_pkt Packet ::::::::::::::::::::::: 3-31 3.9.5. ipc_rcv_pkt Packet :::::::::::::::::::::::: 3-32 3.9.6. How to Prevent Loss of Data ::::::::::::::::: 3-33 iv 3787 3254-100

Contents 3.9.7. How To Avoid Overlaying Program Areas ::::::: 3-36 3.9.8. ipc_receive Example - Receive New Conversation : 3-37 3.9.9. ipc_receive Example - Receive Existing Conversation :::::::::::::::::::::::::: 3-38 3.10. Responding to an Open or Send with a Reply (ipc_reply) :::::::::::::::::::::::::::::::: 3-39 3.10.1. ipc_reply Format :::::::::::::::::::::::::: 3-39 3.10.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-40 3.10.3. ipc_msg_buffer area ::::::::::::::::::::::: 3-40 3.10.4. ipc_data_pkt Packet ::::::::::::::::::::::: 3-41 3.10.5. ipc_reply Example - Send with No Message ::::: 3-42 3.10.6. ipc_reply Example - Send with Message :::::::: 3-42 3.11. Sending a Message (ipc_send) ::::::::::::::::: 3-43 3.11.1. ipc_send Format :::::::::::::::::::::::::: 3-43 3.11.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-43 3.11.3. ipc_msg_buffer area ::::::::::::::::::::::: 3-44 3.11.4. ipc_data_pkt Packet ::::::::::::::::::::::: 3-44 3.11.5. Message-Blocking Considerations ::::::::::::: 3-46 3.11.6. ipc_send Example ::::::::::::::::::::::::: 3-47 3.12. Signing Off from DDP-PPC (ipc_unbind) ::::::::: 3-48 3.12.1. ipc_unbind Format ::::::::::::::::::::::::: 3-48 3.12.2. ipc_status_pkt Packet :::::::::::::::::::::: 3-48 3.12.3. ipc_unbind Example :::::::::::::::::::::::: 3-49 Section 4. Designing the Application 4.1. Using a Block Diagram to Design the Application : 4-1 4.2. Example Application :::::::::::::::::::::::::: 4-4 4.3. Automatic Scheduling ::::::::::::::::::::::::: 4-13 4.3.1. Automatic Scheduling of Batch Programs ::::::: 4-13 4.3.2. Automatic Scheduling of TIP Transactions ::::::: 4-15 Method 1: Referencing a PROGRAM Record ::: 4-16 Method 2: Defining the Transaction in the ipc_open Request :::::::::::::::::::: 4-18 Section 5. Compiling and Executing the UCS C Language Program 5.1. The Runstream for a DDP-PPC UCS C Language Application ::::::::::::::::::::::::::::::: 5-1 5.2. Banking Considerations ::::::::::::::::::::::: 5-2 3787 3254-100 v

Contents Appendix A. C Language Data Declarations A.1. DATAPKT Data Packet :::::::::::::::::::::::: A-1 A.2. OPENPKT Data Packet :::::::::::::::::::::::: A-3 A.3. RCVPKT Data Packet ::::::::::::::::::::::::: A-4 A.4. RESERVED_AREA and UNSIGNED_BYTE Structure A-5 A.5. SIGNONPKT Data Packet :::::::::::::::::::::: A-6 A.6. STATUSPKT Data Packet :::::::::::::::::::::: A-7 A.7. TIP_NAME Structure :::::::::::::::::::::::::: A-8 Glossary Bibliography vi 3787 3254-100

Figures 3-1. Receiving Messages Larger than Your Input Buffer - Loss of Data. :::::: 3-33 3-2. Receiving Messages Larger Than Your Input Buffer - No Data Loss ::::: 3-35 4-1. DDP-PPC C Language Program-to-Program Block Diagram :::::::::::: 4-2 4-2. Automatic Scheduling of a Batch Program :::::::::::::::::::::::: 4-14 4-3. Scheduling a TIP Program by Referencing a PROGRAM Record :::::::: 4-17 4-4. Scheduling a TIP Transaction Using the TIP$ Format :::::::::::::::: 4-20 3787 3254-100 vii

Tables 2-1. DDP-PPC Functions and Associated C Language Functions Calls and Macros ::::::::::::::::::::::::::::::::::::::::::::::::: 2-1 2-2. DDP-PPC Function Call Descriptions :::::::::::::::::::::::::::::: 2-2 2-3. Function Calls and Their Associated Data Packet Arguments :::::::::: 2-4 3787 3254-100 ix

About This Guide Purpose This programming guide tells you how to structure C language programs that run on the OS 2200 system and interface with the Distributed Data Processing Program to Program Communications (DDP-PPC) software via the distributed communications architecture (DCA) interface. Scope Audience This guide includes the following information: $ It describes DDP-PPC program-to-program DCA function calls that you can use in C language programs. $ It gives the format of each function call. $ It gives an example and description of each function call. $ It includes a working example of a C language program to program application between two hosts. The primary audience for the DDP-PPC C Language Programming Guide is the person or persons responsible for writing C language programs for the OS 2200 system. Prerequisites The person responsible for writing the C language programs should understand: $ DDP-PPC software $ The basic concepts of writing, compiling, and executing C language programs 3787 3254-100 xi

About This Guide How to Use This Guide To write DDP-PPC C language programs for the DCA interface, use this guide as follows: $ Read Section 1 for an overview of DDP-PPC C Language. $ Use Section 2 as a guide for programming the C language DCA function calls. $ Refer to Section 3 for the structure of the C language DCA data packets that Unisys supplies with the product. $ Refer to Section 4 for a working example of a DDP-PPC C language program. Page headings are located in the upper, outer corner of each page to help you quickly determine the major topic covered on that page. Organization Section 1. Introduction This section gives you a brief overview of the Unisys DDP-PPC systems software product and how it is used to send messages throughout a distributed data communications network using the DCA interface. Section 2. Procedural Overview This section $ Lists the DDP-PPC functions and their associated C language function calls and descriptions $ Gives the header elements and #includes for copying data packets into C language programs Section 3. C Language Function Calls This section describes the DDP-PPC C language function calls, including: $ Function call operation $ Function call format $ Descriptions of data packets used by the function call $ Examples of use Section 4. Designing the Application This section discusses using a block diagram to determine program activity and gives an example of a working C language program. xii 3787 3254-100

About This Guide Section 5. Compiling and Executing the UCS C Language Program This section gives the run stream and banking considerations for compiling, linking, and executing a UCS C language program for the DCA interface. Appendix A. C Language Data Declarations This appendix lists the C Language data declarations (packets and TIP_NAME structure) used by the DCA interface. 3787 3254-100 xiii

About This Guide Related Product Information The following manuals provide related information you may find helpful. Use the version of the manual that corresponds to the software level in use at your site. DCP Series TCP-IP Stack Installation, Configuration, and Operations Guide (3781 5546) This manual describes the Telcon network definition statements required to configure the Telcon TCP-IP Stack program product used with a distributed communications processor in a (Transmission Control Protocol/Internet Protocol (TCP/IP) network. OS 2200 Distributed Data Processing Program to Program Communications (DDP-PPC) Implementation and Administration Guide (3787 3270) Describes procedures to configure and operate in a DDP environment on OS 2200 systems. It lists the hardware and software requirements. It tells how to $ Initialize and terminate the DDP environment $ Manage normal DDP activity $ Perform error recovery and diagnostic procedures OS 2200 Distributed Data Processing (DDP-PPC/DDP-FJT) DCA Interface COBOL Programming Guide (3787 3510) This manual describes how to write COBOL programs for use with the DDP-PPC Distributed Communications Architecture (DCA) interface. OS 2200 Distributed Data Processing (DDP-PPC/DDP-FJT) Messages Reference Manual (3787 3528) Lists the error messages and status codes for DDP-PPC and DDP-FJT products. OS 2200 Distributed Data Processing (DDP-PPC) OSI Interface C Language Programming Guide (3787 3288) This manual describes how to write C language programs for use with the DDP-PPC Open Systems Interconnection (OSI) interface. OS 2200 Distributed Data Processing (DDP-PPC) OSI Interface COBOL Programming Guide (3787 3296) This manual describes how to write COBOL programs for use with the DDP-PPC Open Systems Interconnection (OSI) interface. OS 2200 Distributed Data Processing (DDP-PPC) TCP/IP Interface C Language Programming Guide (4173 5127) This manual describes how to write C language programs for use with the DDP-PPC TCP/IP interface. xiv 3787 3254-100

About This Guide OS 2200 Distributed Data Processing (DDP-PPC) TCP/IP Interface COBOL Programming Guide (3789 6651) This manual describes how to write COBOL programs for use with the DDP-PPC TCP/IP interface. OS 2200 Distributed Data Processing (DDP-PPC) TCP/IP Interface FORTRAN Programming Guide (3789 6669) This manual describes how to write COBOL programs for use with the DDP-PPC TCP/IP interface. 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 2. 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 2. For example: 3787 3254-100 xv

Section 1 Introduction 1.1. DDP-PPC and the DCA Interface Distributed Data Processing Program to Program Communications (DDP-PPC) is a systems software product used to handle and control data throughout a distributed data communications network. It accepts function calls from a C language program compiled in the Universal Compiling System (UCS) extended mode and uses the distributed communications architecture (DCA) interface to: $ Communicate with other application programs $ Update records on the same or a remote host $ Pass data between programs quickly and easily DDP-PPC, as part of Unisys Distributed Communications Architecture (DCA), is similar in structure to the International Standards Organization (ISO) open systems interconnection architecture. The internal design of DDP-PPC follows the layering of a functional services concept as defined by the open systems interconnection (OSI) basic reference model. DDP-PPC provides layers 5, 6, and 7. DDP-PPC supports only two-way alternate conversations. In a DDP-PPC two-way alternate conversation, a logical data token exists, which the application programs can pass back and forth. Only one of the application programs at a time possesses the data token, and only the application program possessing the token can send messages. The program that possesses the data token is called the primary or sending program. The program that does not possess the data token is called the secondary or receiving program. 3787 3254-100 1-1

DDP-PPC and the UCS C Language Interface 1.2. DDP-PPC and the UCS C Language Interface Application programs compiled with the C language program-to-program interface: $ Run on OS 2200 systems that support UCS (extended mode) $ Communicate with peer programs written in other languages $ Communicate with peer programs residing in local or remote hosts or nodes The DDP-PPC software product provides a library that contains the DCA C language interface object module and several elements that can be included to facilitate coding of your application program. This library includes $ Data packets and function call macros for calling DDP-PPC (contained in file SYS$LIB$*DDP-PPC-3). $ The DDP-PPC DCA interface object module IPC-UCSIF-OM (normally contained in relocatable file SYS$LIB$*DDP-1.IPC-UCSIF-OM). This interface accepts the C language macros/function calls and transfers the information supplied by your program to DDP-PPC. (Compilingthese modules is discussed in Section 5.) 1-2 3787 3254-100

Status Codes and Error Messages 1.3. Status Codes and Error Messages For additional information about the status codes and error messages that DDP-PPC returns to the C language programs, see the DDP-PPC/DDP-FJT Messages Reference Manual. 3787 3254-100 1-3

Section 2 Procedural Overview 2.1. C Language Program Structure Though DDP-PPC C Language programs are similar to conventional programs, certain additional features are required to perform in a DCA network. These features consist of: $ DDP-PPC/DCA function calls or macros $ DDP-PPC/DCA data packets Table 2-1 lists the DDP-PPC functions used in a DCA network and their associated C Language function calls and macros. Table 2-1. DDP-PPC Functions and Associated C Language Functions Calls and Macros Function Function Call Macro Abort the conversation ipc_abort IPC_ABORT Register with DDP-PPC (initiate a session) ipc_bind IPC_BIND Close the connection ipc_close IPC_CLOSE Accept a close request ipc_cls_confirm IPC_CLSCONFIRM Request a DDP dump ipc_dump IPC_DUMP Request exception interrupt ipc_exception IPC_EXCEPTION Open the conversation ipc_open IPC_OPEN Passoff to another program ipc_passoff IPC_PASSOFF Receive messages ipc_receive IPC_RECEIVE Reply to message received ipc_reply IPC_REPLY Send messages ipc_send IPC_SEND Release DDP-PPC resources (terminate a session) ipc_unbind IPC_UNBIND 3787 3254-100 2-1

C Language Program Structure Table 2-2 lists: $ The C language program to program function calls for DDP-PPC $ The category for each function call $ The action of each function call Table 2-2. DDP-PPC Function Call Descriptions Function Call Category Action ipc_abort Conversation Unconditionally terminates a conversation. Releases all DDP-PPC resources related to the conversation and notifies the peer application program that it terminated the conversation. ipc_bind Registration Signs the application program on to DDP-PPC. Returns a user-id that all subsequent function calls in the conversation must supply. ipc_close Output Normally terminates a conversation with a DDP-PPC application program. ipc_cls_confirm Output Lets an application program reply to an ipc_close or ipc_open function call and normally terminates the conversation. ipc_dump Registration Allows a user program to initiate a DDP-PPC autodump. The dump provides a snapshot of the DDP-PPC data banks. It does not provide dump information for any user program data banks. ipc_exception Output Lets the secondary application program interrupt the primary application program. The primary program must receive the exception message before it can issue any more ipc_send function calls. ipc_open Output Initiates a conversation with another application program. The destination application program may reside on the same host or a remote host. The destination application program s response establishes the conversation. continued 2-2 3787 3254-100

C Language Program Structure Table 2-2. DDP-PPC Function Call Descriptions (cont.) Function Call Category Action ipc_passoff Conversation Lets the calling application program substitute another application program for itself in an existing conversation. ipc_receive Input Transfers text from a DDP-PPC network message buffer to a user supplied buffer. Messages reside on a first-in, first-out queue created during conversation establishment. The application must poll the queue for messages. ipc_reply Output Lets an application program respond to a request for a single response from the sending application program. ipc_send Output Lets the primary application program send messages to its paired application program in an established session. The messages are either sent immediately or queued into blocks. The primary application program can pass the data token on an ipc_send function and become the secondary application program. ipc_unbind Registration Releases all DDP-PPC resources associated with an application program. This release may also include the abnormal termination of all conversations in which the application program participates. 3787 3254-100 2-3

C Language Program Structure Each function call references a set of data packets. Data packets contain the information that DDP-PPC needs to execute its various functions. Table 2-3 lists the C function calls and the data packets referenced by each call. Table 2-3. Function Calls and Their Associated Data Packet Arguments Function Call ipc_abort ipc_bind ipc_close ipc_cls_confirm ipc_dump ipc_exception ipc_open ipc_passoff ipc_reply ipc_receive ipc_send ipc_unbind Data Packets Referenced in Arguments ((int)&ipc_status_pkt, (int)ipc_msg_buffer, (int)&ipc_data_pkt); ((int)&ipc_status_pkt, (int)&ipc_signon_pkt); ((int)&ipc_status_pkt, (int)ipc_msg_buffer, (int)&ipc_data_pkt); ((int)&ipc_status_pkt, (int)ipc_msg_buffer, (int)&ipc_data_pkt); ((int)&ipc_status_pkt); ((int)&ipc_status_pkt, (int)ipc_msg_buffer, (int)&ipc_data_pkt); ((int)&ipc_status_pkt, (int)ipc_msg_buffer, (int)&ipc_data_pkt, (int)&ipc_open pkt); ((int)&ipc_status_pkt, (int)&ipc_data_pkt); ((int)&ipc_status_pkt, (int)ipc_msg_buffer, (int)&ipc_data_pkt), ((int)&ipc_status_pkt, (int)ipc_msg_buffer, (int)&ipc_data_pkt; (int)&ipc_rcv_pkt); ((int)&ipc_status_pkt, (int)ipc_msg_buffer, (int)&ipc_data_pkt); ((int)&ipc_status_pkt); 2-4 3787 3254-100

Copying Data Packets into C Language Programs 2.2. 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 (IPC-UCINCLD/PACKETS) $ Declaring typedefs for the packet data structures (IPC-UCINCLD/TYPEDEFS) $ Declaring external packet variables (IPC-UCINCLD/EXTERNS) To access the header elements, use the file inclusion statement #include. The format is where PPC-COPY Is the @use name for the include file. An @USE statement must be used in the ECL stream to enable the compiler to equate this name to the DDP-PPC copy file (see Section 5). IPC-UCINCLD Is the element name within the DDP-PPC include file that indicates the element for the DDP-PPC/DCA C language interface. hdrname Indicates the specific name of the IPC-UCINCLD element to include. The name you use depends on which specific header element you want to include. The names are PACKETS TYPEDEFS EXTERNS 3787 3254-100 2-5

Copying Data Packets into C Language Programs 2.2.1. Choosing a #include PACKETS Element The PACKETS element defines and declares the required macro definitions, data packet structures, and storage assignments necessary to use the DDP-PPC/DCA interface. If this element is used, it includes the TYPEDEFS and FUNCTIONS elements. You do not need to code the storage assignment statements or the function calls, except for the ipc_msg_buffer. In our examples, we use ipc_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: or 2-6 3787 3254-100

Copying Data Packets into C Language Programs 2.2.2. Choosing a #include TYPEDEFS Element The TYPEDEFS element should be used if you only want to include the data packet structures. It uses the C language construct to describe the DDP-PPC/DCA packets. If this statement is used, you must code the storage assignment statements and the function calls. In our examples, we use ipc_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, and then use them in the function call. For example: or 3787 3254-100 2-7

Copying Data Packets into C Language Programs 2.2.3. Choosing a #include EXTERNS Element The EXTERNS element should be used if you want packet declarations for externally defined packets. If this element is used, it also includes the TYPEDEFS and FUNCTIONS 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: or All include elements test to see if they have previously been defined to avoid duplicate definitions, 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 of how the OS 2200 system stores and retrieves data (such as the TAB and NULL characters). 2-8 3787 3254-100

DDP-PPC Function Call Formats 2.3. DDP-PPC Function Call Formats Function calls: $ Are your program s means of transferring data between programs $ Always contain arguments that reference data packets (see Table 2-3) 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 requested by your application program. arg Is a pointer to a data packet storage area or message buffer. These packets consist of control information and data needed for program-to-program communications.the arguments are positional. You must code them in the order 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. These codes are explained in the DDP-PPC/DDP-FJT Messages Reference Manual. DDP-PPC returns the codes to the program in two ways: 1. In the ipc_status_pkt, information can be found in the 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 * 1000 + detail_status). 3787 3254-100 2-9

DDP-PPC Function Call Formats The following is an example of checking the status of the IPC_BIND macro call using both of the above methods: Method 1 Method 2 2-10 3787 3254-100

Section 3 C Language Function Calls 3.1. Aborting a Conversation (ipc_abort) The ipc_abort function call unconditionally terminates a conversation. The primary application program or its peer can issue this function call. It releases all resources pertaining to the aborted conversation. DDP-PPC then refuses all further commands related to the aborted conversation. Data that is queued to DDP-PPC or CMS queues from previous functions may be lost. 3.1.1. ipc_abort Format or The ipc_status_pkt argument references the data structures defined for the user-id and the status codes. On completion of this ipc_abort function call, DDP-PPC returns the status codes for you to test. The ipc_msg_buffer argument references the storage area you defined for the output message buffer. Referencing this area on an abort permits you to send a message along with the abort request. ipc_msg_buffer is the name used in all examples. You may specify your own name in the data structures for this area, but because the function call arguments are positional, you must specify this name as the second argument in the function call or specify it in the macro call. The ipc_data_pkt argument references the data structure for the conversation-id and information concerning the data to be sent. Insert the conversation-id obtained from the ipc_open or ipc_receive call (in receive new mode) before issuing the ipc_abort call. 3787 3254-100 3-1

Aborting a Conversation (ipc_abort) 3.1.2. ipc_status_pkt Packet The ipc_status packet is shown in Appendix A. The ipc_abort function call uses the following status packet parameters: ipc_status_pkt Member class_code detail_status user_id specific_error Description A general status code returned by DDP-PPC. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. A detailed status returned by DDP-PPC. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. A unique user identifier supplied by the application program. Always use the one that DDP-PPC returned on the last ipc_bind function call. This value must remain unchanged as long as this application program is signed on to DDP-PPC. This field contains specific information about an error returned by this function call. A zero in this field indicates that no specific information is available. Refer to the DDP-PPC/DDP-FJT Messages Reference Manualfor more information about these error codes. 3.1.3. ipc_msg_buffer area This is a storage area for user data to be sent with the ipc_abort function call. It must be specified as a data structure in this application program. 3-2 3787 3254-100

Aborting a Conversation (ipc_abort) 3.1.4. ipc_data_pkt Packet ipc_data_pkt Member conversation_id buf_offset text_length delimiter data_name data_type Description Conversation identifier supplied by the application program. It was one returned by DDP-PPC either on a previous ipc_open function call or an ipc_receive function call with ipc_rcv_pkt.rcv_mode = RCV_NEW. Indicates where in the message buffer the text begins. It must be a 0 or multiple of 4. This parameter is ignored if text_length is set to 0. The number of bytes of transferred user text. Do not use use more than 8200. Always set the text length to 0 if not sending text. Set to the value COMPLETE_MSG to indicate transmission of a complete message (no segmentation). A user-defined numeric name for the data sent. Use a numeric value between 0 and 255 for this field. The type of data sent. Valid values include: ASCII_COMPRESSED (size = 8-bit, value = 129) Indicates that DDP-PPC should compress ASCII data. ASCII_DATA (size = 8-bit, value = 128) Indicates that data type is ASCII. EBCDC_COMPRESSED (size = 8-bit, value = 131) Indicates that DDP-PPC should compress EBCDIC data. EBCDC_DATA (size = 8-bit, value = 130) Indicates that data type is EBCDIC. TRANSPARENT_DATA (size = 8-bit, value = 134) Indicates that data type is transparent (no formatting performed). COMPRESED_TRANS (size = 8-bit, value = 135) Indicates that DDP-PPC should compress but not reformat the data. PADDED_TRANS (size = 9-bit, value = 138) Indicates that DDP-PPC should reformat the data from 9-bit bytes to 8-bit bytes. This is called padding the data and is necessary to send 9-bit bytes over communication networks that only support 8-bit bytes. CMPRSD_PAD_TRANS (size = 9-bit, value = 139) Indicates that DDP-PPC should reformat the data from 9-bit bytes to 8-bit bytes, and also compress the data. 3787 3254-100 3-3

Aborting a Conversation (ipc_abort) 3.1.5. ipc_data_packet Additional Information The data_type field of the ipc_data_pkt identifies the type of data the application program wants to send or receive. The following conditions pertain to the data type specification of the ipc_data_pkt: $ You must supply this field for all output commands that are sending messages. $ When you specify a compressed data_type (129, 131, 135, or 139), DDP-PPC compresses all occurrences of duplicate contiguous bytes in the application program s data buffer. v v The remote host decompresses the data before passing it to the remote application program. This does not apply to local conversations. $ When you specify a 9-bit data_type (138 or 139), DDP-PPC extracts all 9th bits from the application program s data and transfers them separately so that they are not lost: v v v This may make the actual data sent larger than the original data. The remote host restores the 9th bits before passing the data to the remote application program, regardless of the data_type that you specified. This does not apply to local conversations. $ When the application program sends transparent, 9-bit byte (36-bit word) data to a remote application program, the application programs must pack and unpack their own data unless you use a 9-bit transparent data_type (138 or 139). 3.1.6. ipc_abort Example - Send with No Message 3-4 3787 3254-100

Aborting a Conversation (ipc_abort) 3.1.7. ipc_abort Example - Send with Message The preceding ipc_abort example with message performs the following: 1. Assigns the user-id (returned by DDP-PPC on the previous ipc_bind function call). 2. Assigns the conversation-id (returned by DDP-PPC on the ipc_open or an ipc_receive function call in new mode). 3. Sets the buffer offset. 4. Sets the text length. 5. Sets the delimiter for complete message transmission. 6. Sets the data name. 7. Assigns ASCII to the data type. 8. Moves the message into the message buffer. 9. Issues the ipc_abort function call. 3787 3254-100 3-5

Signing on to DDP-PPC (ipc_bind) 3.2. Signing on to DDP-PPC (ipc_bind) The ipc_bind_function call signs the application program on to DDP-PPC. DDP-PPC returns a user-id that you then use on all subsequent commands for this program. 3.2.1. ipc_bind Format or The ipc_status_pkt argument references the data structures for the user-id and status codes. On completion of the function, DDP-PPC returns a user-id in the status packet. Your program must then supply the user-id on all subsequent calls in the conversation. DDP-PPC also returns general and detailed status codes that you should check after completion of each function call. The ipc_signon_pkt argument references the data structure in which you insert the name of your program before issuing the call. 3.2.2. ipc_status_pkt Packet The ipc_status packet is shown in Appendix A. The ipc_signon function call uses the following status packet parameters: ipc_status_pkt Member class_code detail_status user_id specific_error Description A general status code returned by DDP-PPC. The error codes are described in the DDP-PPC-FJT Messages Reference Manual A detailed error code returned by DDP-PPC. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. A unique user identifier returned by DDP-PPC. This field contains specific information about an error returned by this function call. A zero in this field indicates that no specific information is available. Refer to the DDP-PPC/DDP-FJT Messages Reference Manual for more information about these error codes. 3-6 3787 3254-100

Signing on to DDP-PPC (ipc_bind) 3.2.3. ipc_signon_pkt Packet ipc_signon_pkt Member int_ap_name Description The name of the application program registering to DDP-PPC. Can be from 1 to 12 ASCII characters within the following set: A-Z, a-z, 0-9, -, and $. Left justify and blank fill the unused portion of this field. 3.2.4. ipc_bind Example The preceding ipc_bind example performs the following: 1. Assigns a name to the application. 2. Issues the ipc_bind function call. 3. Stores the user id returned by DDP-PPC in the variable field user. 3787 3254-100 3-7

Terminating a Conversation (ipc_close) 3.3. Terminating a Conversation (ipc_close) The ipc_close function call terminates a conversation with an application program. It requests a response from the destination application program. The program can issue this function call only when it possesses the data token. 3.3.1. ipc_close Format or The ipc_status_pkt argument references the data structure defined for the user-id and the status codes. On completion of this ipc_close function call, DDP-PPC returns the status codes for you to test. The ipc_msg_buffer argument references the storage area you defined for the output message buffer. Referencing this area on a close permits you to send a message along with the close request. ipc_msg_buffer is the name used in all examples. You may specify your own name in the data structures for this area, but because the function call arguments are positional, you must specify this name as the second argument in the function call or specify it in the macro call. The ipc_data_pkt argument references the data structure for the conversation-id and information concerning the data to be sent. Insert the conversation-id obtained from the ipc_open or ipc_receive call (in receive new mode) before issuing the ipc_close call. 3.3.2. ipc_status_pkt Packet The ipc_status packet is shown in Appendix A. The ipc_close function call uses the following status packet parameters: ipc_status_pkt Member class_code detail_status user_id Description A general status code returned by DDP-PPC. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. A detailed status returned by DDP-PPC. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. A unique user identifier supplied by the application program. Always use the one that DDP-PPC returned on the last ipc_bind function call. continued 3-8 3787 3254-100

Terminating a Conversation (ipc_close) continued ipc_status_pkt Member specific_error Description This field contains specific information about an error returned by this function call. A zero in this field indicates that no specific information is available. Refer to the DDP-PPC/DDP-FJT Messages Reference Manualfor more information about these error codes. 3.3.3. ipc_msg_buffer area This is a storage area for user data to be sent with the ipc_close function call. It must be specified as a data structure in this application program. 3787 3254-100 3-9

Terminating a Conversation (ipc_close) 3.3.4. ipc_data_pkt Packet ipc_data_pkt Member conversation_id buf_offset Description Conversation identifier supplied by the application program. It was one returned by DDP-PPC either on a previous ipc_open function call or an ipc_receive function call with ipc_rcv_pkt.rcv_mode = RCV_NEW. Indicates where in the message buffer the text begins. It must be a 0 or multiple of 4. This parameter is ignored if text_length is set to 0. text_length The number of bytes of transferred user text. Do not use use more than 8200. Always set the text length to 0 if not sending text. delimiter Set to the value COMPLETE_MSG to indicate transmission of a complete message. data_name A user-defined numeric name for the data sent. Use a numeric value between 0 and 255 for this field. data_type The type of data sent. Valid values include: ASCII_COMPRESSED (size = 8-bit, value = 129) Indicates that DDP-PPC should compress ASCII data. ASCII_DATA (size = 8-bit, value = 128) Indicates that data type is ASCII. EBCDC_COMPRESSED (size = 8-bit, value = 131) Indicates that DDP-PPC should compress EBCDIC data. EBCDC_DATA (size = 8-bit, value = 130) Indicates that data type is EBCDIC. TRANSPARENT_DATA (size = 8-bit, value = 134) Indicates that data type is transparent (no formatting performed). COMPRESED_TRANS (size = 8-bit, value = 135) Indicates that DDP-PPC should compress but not reformat the data. PADDED_TRANS (size = 9-bit, value = 138) Indicates that DDP-PPC should reformat the data from 9-bit bytes to 8-bit bytes. This is called padding the data and is necessary to send 9-bit bytes over communication networks that only support 8-bit bytes. CMPRSD_PAD_TRANS (size = 9-bit, value = 139) Indicates that DDP-PPC should reformat the data from 9-bit bytes to 8-bit bytes, and also compress the data. dialog Controls both data token possession and demand for a response. It must be set to RESP_HOLD_TOKEN (demand response, hold token). 3-10 3787 3254-100

Terminating a Conversation (ipc_close) 3.3.5. ipc_close Example - Send with No Message 3.3.6. ipc_close Example - Send with Message The preceding ipc_close example with message performs the following: 1. Assigns the user-id (returned by DDP-PPC on the previous ipc_bind function call). 2. Assigns the conversation-id. 3. Sets the buffer offset. 4. Sets the text length. 5. Sets the delimiter for complete message transmission. 6. Sets the data name. 7. Assigns ASCII to the data type. 8. Moves the message into the message buffer. 9. Holds the data token and requests a response. 10. Issues the ipc_close function call. 3787 3254-100 3-11

Responding to an Open or Close with a Close Confirmation (ipc_cls_confirm) 3.4. Responding to an Open or Close with a Close Confirmation (ipc_cls_confirm) The ipc_cls_confirm function call lets an application program respond to an ipc_open or ipc_close function call by terminating the conversation. A program can issue this function call only when it receives an open or close from a peer program. 3.4.1. ipc_cls_confirm Format or The ipc_status_pkt argument references the data structures defined for the user-id and the status codes. On completion of this ipc_cls_confirm function call, DDP-PPC returns the status codes for you to test. The ipc_msg_buffer argument references the storage area you defined for the output message buffer. Referencing this area on a close confirm permits you to send a message along with the close confirm request. ipc_msg_buffer is the name used in all examples. You may specify your own name in the data structures for this area, but because the function call arguments are positional, you must specify this name as the second argument in the function call or specify it in the macro call. The ipc_data_pkt argument references the data structure for the conversation-id and information concerning the data to be sent. Insert the conversation-id obtained from the ipc_open or ipc_receive call (in receive new mode) before issuing the ipc_cls_confirm call. 3-12 3787 3254-100

Responding to an Open or Close with a Close Confirmation (ipc_cls_confirm) 3.4.2. ipc_status_pkt Packet The ipc_status packet is shown in Appendix A. The ipc_cls_confirm function call uses the following status packet parameters: ipc_status_pkt Member class_code detail_status user_id specific_error Description A general status code returned by DDP-PPC. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. A detailed status returned by DDP-PPC. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. A unique user identifier supplied by the application program. Always use the one that DDP-PPC returned on the last ipc_bind function call. This field contains specific information about an error returned by this function call. A zero in this field indicates that no specific information is available. Refer to the DDP-PPC/DDP-FJT Messages Reference Manual for more information about these error codes. 3.4.3. ipc_msg_buffer area This is a storage area for user data to be sent with the ipc_cls_confirm function call. It must be specified as a data structure in this application program. 3787 3254-100 3-13

Responding to an Open or Close with a Close Confirmation (ipc_cls_confirm) 3.4.4. ipc_data_pkt Packet ipc_data_pkt Member conversation_id buf_offset text_length delimiter data_name data_type Description Conversation identifier supplied by the application program. It was one returned by DDP-PPC either on a previous ipc_open function call or an ipc_receive function call with ipc_rcv_pkt.rcv_mode = RCV_NEW. Indicates where in the message buffer the text begins. It must be a 0 or multiple of 4. This parameter is ignored if text_length is set to 0. The number of bytes of transferred user text. Do not use use more than 8200. Always set the text length to 0 if not sending text. Set to the value COMPLETE_MSG to indicate transmission of a complete message. A user-defined numeric name for the data sent. Use a numeric value between 0 and 255 for this field. The type of data sent. Valid values include: ASCII_COMPRESSED (size = 8-bit, value = 129) Indicates that DDP-PPC should compress ASCII data. ASCII_DATA (size = 8-bit, value = 128) Indicates that data type is ASCII. EBCDC_COMPRESSED (size = 8-bit, value = 131) Indicates that DDP-PPC should compress EBCDIC data. EBCDC_DATA (size = 8-bit, value = 130) Indicates that data type is EBCDIC. TRANSPARENT_DATA (size = 8-bit, value = 134) Indicates that data type is transparent (no formatting performed). COMPRESED_TRANS (size = 8-bit, value = 135) Indicates that DDP-PPC should compress but not reformat the data. PADDED_TRANS (size = 9-bit, value = 138) Indicates that DDP-PPC should reformat the data from 9-bit bytes to 8-bit bytes. This is called padding the data and is necessary to send 9-bit bytes over communication networks that only support 8-bit bytes. CMPRSD_PAD_TRANS (size = 9-bit, value = 139) Indicates that DDP-PPC should reformat the data from 9-bit bytes to 8-bit bytes, and also compress the data. 3-14 3787 3254-100

Responding to an Open or Close with a Close Confirmation (ipc_cls_confirm) 3.4.5. ipc_cls_confirm Example - Send with No Message 3.4.6. ipc_cls_confirm Example - Send with Message The preceding ipc_cls_confirm with message example performs the following: 1. Assigns the user-id (returned by DDP-PPC on the previous ipc_bind function call). 2. Assigns the conversation-id. 3. Sets the buffer offset. 4. Sets the text length. 5. Sets the delimiter for complete message transmission. 6. Sets the data name. 7. Assigns ASCII to the data type. 8. Moves the message into the message buffer. 9. Issues the ipc_cls_confirm function call. 3787 3254-100 3-15

Initiating a DDP-PPC Autodump (ipc_dump) 3.5. Initiating a DDP-PPC Autodump (ipc_dump) The ipc_dump function call allows a user program to initiate a DDP-PPC autodump. The dump is sent to the DDP$DUMP file. You can then process the contents of the dump file at a later time. See the DDP-PPC Implementation and Administration Guide for more information on dump files. DDP-PPC returns the name of the dump file to the PRINT$ file of the user program and to the log file. The program can issue this function call at any time, even when not signed on to DDP-PPC. 3.5.1. ipc_dump Format or The ipc_status_pkt argument references the data structure defined in your application program for the user-id and the status codes. On completion of this ipc_dump function call, DDP-PPC returns the status codes for you to test. 3.5.2. ipc_status_pkt Packet The ipc_status packet is shown in Appendix A. The ipc_dump function call uses the following status packet parameters: ipc_status_pkt Member class_code detail_status specific_error Description A general status code returned by DDP-PPC. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. A detailed error code returned by DDP-PPC. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. This field contains specific information about an error returned by this function call. A zero in this field indicates that no specific information is available. Refer to the DDP-PPC/DDP-FJT Messages Reference Manual for more information about these error codes. 3-16 3787 3254-100

Initiating a DDP-PPC Autodump (ipc_dump) 3.5.3. ipc_dump Example This example issues the ipc_dump function call. 3787 3254-100 3-17

Sending an Unsolicited Message (ipc_exception) 3.6. Sending an Unsolicited Message (ipc_exception) The ipc_exception function call allows an application program to send an unsolicited message to its peer application program. You can only use this function call: $ When the program does not possess the data token $ When the program possesses the data token but issued a previous ipc_send function call with dialog set to RESP_HOLD_TOKEN and has not received the response. $ When the program issued an ipc_close function call and has not received the close confirm. 3.6.1. ipc_exception Format or The ipc_status_pkt argument references the data structures defined for the user-id and the status codes. On completion of this ipc_exception function call, DDP-PPC returns the status codes for you to test. The ipc_msg_buffer argument references the storage area you defined for the output message buffer. Referencing this area on an exception permits you to send a message along with the abort request. ipc_msg_buffer is the name used in all examples. You may specify your own name in the data structures for this area, but because the function call arguments are positional, you must specify this name as the second argument in the function call or specify it in the macro call. The ipc_data_pkt argument references the data structure for the conversation-id and information concerning the data to be sent. Insert the conversation-id obtained from the ipc_open or ipc_receive call (in receive new mode) before issuing the ipc_exception call. 3-18 3787 3254-100