Distributed Data Processing (DDP-PPC) TCP/IP Interface COBOL

!()+ OS 2200 Distributed Data Processing (DDP-PPC) TCP/IP Interface COBOL Programming Guide Copyright ( 1997 Unisys Corporation. All rights reserved. Unisys is a registered trademark of Unisys Corporation. Level 7R1 September 1997 Priced Item Printed in U S America 3789 6651v100

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 :::::::::::::::::::::::::::::::::::::::::::::: xiii Section 1. Introduction 1.1. DDP-PPC and the COBOL Interface ::::::::::::: 1-1 1.2. The TCP/IP Interface ::::::::::::::::::::::::: 1-2 1.3. Overview of Program-to-Program Applications ::: 1-3 1.4. Migration from DDN 1100 4R1 to DDP-PPC 6R1 and Higher ::::::::::::::::::::::::::::::::::: 1-4 Section 2. Procedural Overview 2.1. DDP-PPC COBOL Program Structure ::::::::::: 2-1 2.2. Copying Information Packets ::::::::::::::::::: 2-3 2.2.1. Using the COBOL COPY DDN-PKTS Statement ::: 2-3 2.2.2. Sample Information Packets Produced from Copy Verbs :::::::::::::::::::::::::::::::: 2-3 2.2.3. Sample Initialization Packets ::::::::::::::::: 2-3 2.2.4. Additional Working-Storage Items ::::::::::::: 2-6 2.3. COBOL Verbs and Function Calls ::::::::::::::: 2-7 2.3.1. Function Calls ::::::::::::::::::::::::::::: 2-7 2.3.2. COPY Verbs :::::::::::::::::::::::::::::: 2-9 2.3.3. Initializing Packet Field Values :::::::::::::::: 2-9 Section 3. Using DDP-PPC TCP/IP Function Calls 3.1. COBOL COPY Verbs and Function Calls :::::::::: 3-1 3.2. Terminating a Conversation (DDN-ABORT) ::::::: 3-3 3.3. Closing a Conversation (DDN-CLOSE) ::::::::::: 3-7 3.4. Interrupting Current Processing without Closing (DDN-INT-PROCESS) ::::::::::::::::::::::: 3-9 3.5. Opening a Conversation (DDN-OPEN) ::::::::::: 3-11 3.6. Replacing a Program in a Conversation (DDN-PASSOFF) ::::::::::::::::::::::::::: 3-16 3789 6651v100 iii

Contents 3.7. Receiving a Message from a Host (DDN-RECEIVE) 3-20 3.8. Sending a Message (DDN-SEND) ::::::::::::::: 3-24 3.9. Detaching an Application Program from DDP-PPC (DDN-SIGNOFF) ::::::::::::::::::::::::::: 3-26 3.10. Attaching an Application Program to DDP-PPC (DDN-SIGNON) :::::::::::::::::::::::::::: 3-27 Section 4. Designing and Writing the Application 4.1. Using a Block Diagram :::::::::::::::::::::::: 4-1 4.2. Creating a Flow Diagram :::::::::::::::::::::: 4-4 4.3. Using the Message Buffer Area ::::::::::::::::: 4-7 4.3.1. Formatting and Defining the Buffer Area :::::::: 4-7 4.3.2. Referencing the Buffer Area :::::::::::::::::: 4-7 4.4. Writing a Program-to-Program Application ::::::: 4-9 4.4.1. General Considerations ::::::::::::::::::::: 4-9 4.4.2. Receiving Data from a Remote Host ::::::::::: 4-9 Method 1 :::::::::::::::::::::::::::::: 4-10 Method 2 :::::::::::::::::::::::::::::: 4-10 4.4.3. Closing a Conversation ::::::::::::::::::::: 4-12 Section 5. Compiling and Executing Programs 5.1. Preparing Programs for Execution :::::::::::::: 5-1 5.1.1. Calling TCP/IP functions only ::::::::::::::::: 5-1 5.1.2. Calling TCP/IP and TAS Program Callable-Functions :::::::::::::::::::::: 5-1 5.2. Run Streams for DDP-PPC COBOL Programs ::::: 5-2 5.3. Banking Considerations ::::::::::::::::::::::: 5-4 5.3.1. UCS COBOL :::::::::::::::::::::::::::::: 5-4 5.3.2. ASCII COBOL ::::::::::::::::::::::::::::: 5-5 Appendix A. Conventions for Naming Hosts A.1. Introduction ::::::::::::::::::::::::::::::::: A-1 A.2. Host Identifiers ::::::::::::::::::::::::::::::: A-1 Appendix B. Program-to-Program Example B.1. Sample Program Run Streams ::::::::::::::::: B-1 B.2. Primary (Sending) Program Example ::::::::::: B-3 iv 3789 6651v100

Contents B.3. Secondary (Receiving) Program Example :::::::: B-7 Glossary Bibliography 3789 6651v100 v

Figures 1-1. Capabilities of the Program-to-Program Facility ::::::::::::::::::::: 1-3 2-1. COBOL Verbs and Function Calls :::::::::::::::::::::::::::::::: 2-7 2-2. Referencing Information Packets through Function Call USING Clauses :: 2-8 3-1. Typical Block Diagram for Program-to-Program Passoff Succession :::: 3-17 4-1. Typical Program-to-Program Block Diagram ::::::::::::::::::::::: 4-2 4-2. Typical Procedure Division Program-to-Program Flow Diagram (Part 1) :: 4-5 4-3. Typical Procedure Division Program-to-Program Flow Diagram (Part 2) :: 4-6 5-1. Compile, Collect, and Execute Stream for an ASCII COBOL Application Program :::::::::::::::::::::::::::::::::::::::::::::::: 5-3 5-2. Compile, Link, and Execute Stream for a UCS COBOL Application Program :::::::::::::::::::::::::::::::::::::::::::::::: 5-4 3789 6651v100 vii

Tables 1-1. Comparison of the DDN 1100 4R1 and DDP-PPC 6R1 TCP/IP Interface :: 1-4 3-1. Copy Verbs and Associated Function Calls and Information Packets ::::: 3-1 3-2. Copy Verbs and Associated Error Codes :::::::::::::::::::::::::: 3-4 3789 6651v100 ix

Examples B-1. ASCII COBOL Compile and Collect Stream for Primary Program :::::::: B-1 B-2. UCS COBOL Compile and Link Stream for Primary Program ::::::::::: B-2 3789 6651v100 xi

About This Guide Purpose This guide is designed to instruct and guide you in using the Unisys OS2200 Distributed Data Processing Program-to-Program Communications (DDP-PPC) TCP/IP COBOL interface. It tells you how to write COBOL application programs that let you exchange data between programs on the host or on remote hosts. The DDP-PPC TCP/IP COBOL interface was previously part of the DDN 1100 product. This guide instructs an applications programmer how to: $ Use a Unisys-supplied COBOL copy library to insert pre-written information packets and function calls into an ASCII or Universal Compiling System (UCS) COBOL program $ Write a COBOL application program using the COBOL information packets and function calls $ Compile the program $ Execute the program Scope This guide provides detailed information on COBOL function calls and information packets. It describes how to organize the calls and packets to enable users to write customized COBOL applications that can exchange data between programs in a multihost network. The material covered in this Guide was previously contained in the OS1100 Defense Data Network (DDN 1100) COBOL Programming Guide. Audience The primary audience for this programming guide is the applications programmer. This person is typically a COBOL programmer with several years of experience. The person might have a limited knowledge of communications and is dependent on reading this documentation to be able to write a COBOL application with program-to-program communications. The secondary audience for this guide is the site administrator. 3789 6651v100 xiii

About This Guide This person typically has network and data base management experience. The site administrator is responsible for installing and implementing new hardware and software, network management, data bases, and security. Prerequisites To use this manual, you must understand distributed data processing concepts and know how to write standard COBOL programs. How to Use This Guide Programmers should use this guide to learn how to design and construct program-to-program applications. The guide shows you how to use COBOL COPY verbs and function calls to insert and set information packets in your program. Use this guide also to learn how to compile, link, and execute your application program. Organization Section 1. Introduction Gives an overview of DDP-PPC, TCP/IP, and features of the COBOL interface. Also gives a brief overview of program-to-program applications and how to migrate programs written for the DDN 1100 4R1 interface to the DDP_PPC 6R1 (and higher) TCP/IP interface. Section 2. Procedural Overview Discusses conventional COBOL versus DDP-PPC COBOL program structure. Describes how you use the working storage section and the procedure division in program-to-program applications. Section 3. Using DDP-PPC TCP/IP Function Calls Describes the COBOL function calls and the information packets that let you transfer data between COBOL programs in the same or remote hosts. Tells how to sign on and off; open, close, or abort a conversation; and interrupt a process without closing the conversation. Section 4. Designing and Writing the Application Discusses how to design the application and construct a basic program-to-program application. Section 5. Compiling and Executing Programs Describes the executive control language run stream used to compile, collect or link, and execute the programs. xiv 3789 6651v100

About This Guide Appendix A. Conventions for Naming Hosts Discusses how to name hosts and OS 2200 elements. Appendix B. Program-to-Program Example Contains a working example of a DDP-PPC TCP/IP COBOL program-to-program application. 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. The following manuals provide related information you may find helpful: OS 1100 Communications Management System (CMS 1100) Configuration Reference Manual (7830 9853) An alphabetical reference manual that describes the network definition statements you use to configure CMS 1100. OS 1100 Communications Management System (CMS 1100) Installation and Configuration Guide (7830 9846) Describes the installation and configuration process to install and configure CMS 1100. Explains the concepts, the tasks that form the process, and the key requirements for configuring protocols and features. OS 2200 Distributed Data Processing (DDP-PPC/DDP-FJT) DCA Interface COBOL Programming Guide (3787 3510) Describes how to structure COBOL programs that run on the OS 2200 system and interface with the DDP-PPC software via the Distributed Communications Architecture (DCA) interface. OS 2200 Distributed Data Processing (DDP-PPC/DDP-FJT) Messages Reference Manual (3787 3528) Describes the status codes, error messages, and informational messages for DDP-PPC and DDP-FJT. OS 2200 Distributed Data Processing (DDP-PPC) OSI Interface COBOL Programming Guide (3787 3296) Describes how to write DDP-PPC/OSI application programs in COBOL to exchange data in a network that adheres to open systems interconnection standards. 3789 6651v100 xv

About This Guide OS 2200 Distributed Data Processing (DDP-PPC) TCP/IP Interface C Language Programming Guide (4173 5127) Describes how to write customized C language applications that can exchange data with other programs in the same or remote computers in a multihost TCP/IP network. OS 2200 Distributed Data Processing (DDP-PPC) TCP/IP Interface FORTRAN Programming Guide (3789 6669) Describes how to write customized FORTRAN applications that can exchange data with other programs in the same or remote computers in a multihost TCP/IP network. OS 2200 Distributed Data Processing Program-to-Program Communications (DDP-PPC) Implementation and Administration Guide (3787 3270) Describes procedures for configuring and operating in a DDP environment on OS 2200 systems. It lists the hardware and software requirements and tells how to: $ Initialize and terminate the DDP-PPC environment $ Manage normal DDP-PPC activity $ Perform error recovery and diagnostic procedures OS 2200 TCP/IP Application Services (TAS) COBOL Programming Guide (3787 3205) Previous title: OS 1100 Defense Data Network (DDN 1100) COBOL Programming Guide. Describes how to write customized COBOL applications that can transfer files or process mail in a multihost TCP/IP network. OS 2200 TCP/IP Application Services (TAS) FORTRAN Programming Guide (3787 3247) Previous title: OS 1100 Defense Data Network (DDN 1100) FORTRAN Programming Guide. Describes how to write customized FORTRAN applications that can transfer files or process mail in a multihost TCP/IP network. xvi 3789 6651v100

Section 1 Introduction 1.1. DDP-PPC and the COBOL 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. The DDP-PPC COBOL interface accepts function calls from a COBOL program to: $ Communicate with other application programs $ Update records on the same or a remote host $ Pass data between programs quickly and easily The DDP-PPC COBOL interface uses either ASCII COBOL or Universal Compiling System (UCS) COBOL. The interface provides COPY verbs that are used in your application program to provide information packets and issue requests (function calls) to DDP-PPC. Application programs compiled with the COBOL program-to-program interface: $ Run on OS 2200 systems $ Communicate with peer programs written in COBOL or other languages $ Communicate with peer programs residing on local or remote hosts or nodes The DDP-PPC COBOL interface described in this guide uses the TCP/IP protocol for program-to-program communications. DDP-PPC also provides COBOL interfaces that use: $ Unisys Distributed Communications Architecture (DCA) protocol $ Open Systems Interconnection (OSI) protocol Those interfaces are described in the DDP-PPC/DDP-FJT DCA Interface COBOL Programming Guide and the DDP-PPC OSI Interface COBOL Programming Guide. DDP-PPC also provides FORTRAN and C language interfaces for program-to-program communications in a TCP/IP network. These interfaces are described in the DDP-PPC TCP/IP Interface FORTRAN Programming Guide and the DDP-PPC TCP/IP C Language Programming Guide respectively. 3789 6651v100 1v1

The TCP/IP Interface 1.2. The TCP/IP Interface TCP/IP is a set of layered communications protocols originally defined by the Advanced Research Project Agencies (ARPA) of the United States Department of Defense (DoD). The Transmission Control Protocol/Internet Protocol (TCP/IP) element provides reliable communication between pairs of processes (applications). Thus, TCP/IP serves as the basis for the DoD concept of interprocess communications in communications systems. TCP/IP implements the transport layer in the hierarchy of layered protocols. It provides reliable connection-oriented, ordered, full-duplex data transfer, with capabilitiesfor flow control. TCP/IP, therefore, compensates for environments in which loss, damage, duplicated, or out-of-sequence data, and network congestion might otherwise occur. Consequently, it is well-suited to support military, governmental, and commercial applications. 1v2 3789 6651v100

Overview of Program-to-Program Applications 1.3. Overview of Program-to-Program Applications The DDP-PPC TCP/IP program-to-program facility allows COBOL language application programs to pass data between programs in the same host or remote hosts in the network. For example, data may be status or informational messages, control information, or records from a file. This permits multiple message switching, status monitoring, or access to individual records of multiple files. Figure 1-1 shows the capabilities of the program-to-program facility. DDP-PPC TCP/IP Network Host Computer A Host Computer B COBOL Program A Data COBOL Program B Data COBOL Program C Figure 1-1. Capabilities of the Program-to-Program Facility Program-to-program facilities allow you to reconstruct files on the local host by using data gathered from many records, elements, or files on remote hosts. This eliminates duplication of large amounts of unnecessary and unwanted data. It also eliminates the need to use transportable mass storage devices, such as tapes or disks, to transfer data between hosts. The program-to-program facility lets you: $ Open, close, and terminate conversations $ Send and receive messages $ Access records at multiple sites to form a master file $ Access data bases at multiple sites for simultaneous real-time updates $ Attach and detach applications to DDP-PPC $ Interrupt current processing $ Replace a program in a conversation 3789 6651v100 1v3

Migration from DDN 1100 4R1 to DDP-PPC 6R1 and Higher 1.4. Migration from DDN 1100 4R1 to DDP-PPC 6R1 and Higher The DDP-PPC TCP/IP COBOL Programming interface was previously a component of DDN 1100. DDN 1100 4R1 and DDP-PPC 5R1 used the GASIF interface to CMS. The GASIF interface is replaced by TSAM for DDP-PPC 6R1and higher. As a result, you may need to make certain changes in your TCP/IP programming application. (You must at least recompile current applications to pick up the new data and open packet sizes.) Table 1-1 summarizes the differences in the TCP/IP COBOL interface between DDN 1100 4R1 and DDP-PPC 6R1and higher and describes the changes required in your application. Table 1-1. Comparison of the DDN 1100 4R1 and DDP-PPC 6R1 TCP/IP Interface DDN 1100 4R1 TCP/IP passes an open-id indication to the application after a passive open is issued. The application then loops, waiting for an open- indication to be returned. The host name field in the open packet is 24 characters long. An ASCII dotted-decimal local internet address is returned on an open-id. An ASCII dotted-decimal remote internet address is returned on an open-indication. DDP-PPC 6R1 The open-id is now returned to the user when an open indication arrives for the TSU. Therefore, the application must now loop waiting for the open-id after issuing a passive open. The host name field in the open packet has been increased to 255 characters to support domain names. (A domain name specifies the logical internet name whereas the host name is specified in internet physical address format.) Two fields have been added to the data packet: DDN-DOMAIN-HOST-INFO (contains the domain name) DDN-DOMAIN-HOST-LENGTH (contains the length of the domain name) DDP-PPC requests the domain name resolver to determine if the local or remote internet address has an associated domain name. If there is an associated domain name and the receive-event is an open-id, the user receives the local internet address and the local domain name. If there is an associated domain name and the receive-event is an open-indication, the user receives the remote internet address and the remote domain name. Current applications can therefore continue to function, and new ones can opt to use the associated domain name. (Current applications must recompile their programs to pick up the new data and open packet sizes.) continued 1v4 3789 6651v100

Migration from DDN 1100 4R1 to DDP-PPC 6R1 and Higher Table 1-1. Comparison of the DDN 1100 4R1 and DDP-PPC 6R1 TCP/IP Interface (cont.) DDN 1100 4R1 Since the GASIF interface sends TCP/IP data over a DCA session, errors are returned as data on a subsequent receive function. DDP-PPC 6R1 Errors are returned both when the function is issued and on the subsequent receive function. There are also additional error codes and some error codes are different than before. These are documented in the DDP-PPC/DDP-FJT Messages Reference Manual and returned to the application as received by DDP-PPC. 3789 6651v100 1v5

Section 2 Procedural Overview 2.1. DDP-PPC COBOL Program Structure Though DDP-PPC COBOL programs are similar to conventional programs, certain additional features are required. For example, you must: $ Include information packets and any other necessary working-storage areas in the data division of your program $ Use the COBOL COPY verb to copy verbs and function calls into the procedure division The following example shows the DDP-PPC COBOL program structure. The WORKING-STORAGE SECTION and PROCEDURE DIVISION in the example are unique to a DDP-PPC program. DDP Cobol Program Structure 3789 6651v100 2v1

DDP-PPC COBOL Program Structure 2v2 3789 6651v100

Copying Information Packets 2.2. Copying Information Packets The working-storage section of the data division supplies DDP-PPC with the information needed to control data transfer between programs. This section contains 01-, 02-, 04-, and 88-level data description items in information packet formats. These packets correspond to the USING clause parameters of the DDP-PPC function calls discussed in Section 3. 2.2.1. Using the COBOL COPY DDN-PKTS Statement You use information packets to supply the data transfer control information. These packets are constructed for you using standard data descriptions. Copy these packets into your working-storage section from the COBOL copy library using the COPY DDN-PKTS statement in the procedure division of the program. (See 2.3.) The COPY statements place all the necessary data descriptions into your working-storage section when the program is compiled. 2.2.2. Sample Information Packets Produced from Copy Verbs The following example shows the information packets produced by copying DDN-PKTS into the working-storage section of a DDP-PPC application program. All the fields and parameters forming the information packets are described in detail with the related function calls in Section 3. 2.2.3. Sample Initialization Packets The DDP-PPC TCP/IP packets contain several fields that are not required each time that you issue a function. Each command packet has an associated initialization packet that you can use to clear unused fields before specifying any parameters and issuing a function call. You can tell DDP-PPC TCP/IP to ignore specific fields by: $ Setting them to a value, usually spaces or zeroes, on a field-by-field basis $ Initializing the entire packet and then resetting specific fields to the desired values These initialization packets are shown in the following example. Initialization Packets 3789 6651v100 2v3

Copying Information Packets 2v4 3789 6651v100

Copying Information Packets 3789 6651v100 2v5

Copying Information Packets 2.2.4. Additional Working-Storage Items You also use the working-storage section to define message areas and to store error messages. These areas and values are specific to your program and are not supplied through COPY verb statements. You must define a message buffer area. All program-to-program commands reference this area to transfer data. The maximum buffer size is 8232 characters. See 4.3 for a discussion on alternative ways to define this area. Example: Depending on your application, optionally include: $ Storage areas to hold conversation-id and status information supplied by DDP-PPC $ The name of the destination host computer on which the destination program resides (the program with which you are going to have a conversation) $ Offset and text length values to define your data messages $ Data messages and error messages 2v6 3789 6651v100

COBOL Verbs and Function Calls 2.3. COBOL Verbs and Function Calls Application programs use conventional COBOL verbs for input/output data transfers and procedure division manipulations. They also use conventional verbs to set information fields in the working-storage section information packets. See Figure 2-1. Data Files COBOL I/O Verb COBOL Application Program DDP-PPC TCP/IP COBOL Function Call Status Data TCP/IP COBOL Interface Element DDP-PPC CMS TCP/IP Network Figure 2-1. COBOL Verbs and Function Calls 2.3.1. Function Calls Special function calls are used for DDP-PPC applications. Use these function calls to: $ Enter the COBOL applications interface element $ Pass control information that is in your program $ Issue requests to DDP-PPC. Figure 2-2 shows how a function call references information packets. In this case, it shows how to use a standard COBOL MOVE verb to set an information packet field before issuing the call. 3789 6651v100 2v7

COBOL Verbs and Function Calls DATA DIVISION... WORKING-STORAGE SECTION. 01 DDN-STATUS-PKT.... 01 DDN-SIGNON-PKT. 02 DDN-PROGRAM-NAME.... 01 DDN-OPEN-PKT.... 01 DDN-RECEIVE-PKT.... 01 DDN-DATA-PKT.... PROCEDURE DIVISION. MOVE 'MYPROGRAM' TO DDN-PROGRAM-NAME. CALL 'DDN$SIGNON' USING DDN-STATUS-PKT, DDN-SIGNON-PKT. Figure 2-2. Referencing Information Packets through Function Call USING Clauses The format for a function call is: where: function Is the name of the DDP-PPC function call requested by your application program. USING Is the clause that references information packets or buffer areas in your working-storage section. Parameters in the USING list are positional. You must code them in the order shown in each function call. param Is the name of the information packet or buffer area in your working-storage section. Function call statements always contain USING clauses that reference information packets or buffer areas contained in your working-storage section. (See Table 3-1.) The information packets consist of control information and data needed for program communications. The buffer areas are used to pass data between DDP-PPC and your program. 2v8 3789 6651v100

COBOL Verbs and Function Calls After processing a function call, DDP-PPC returns both a general, a detailed status code, and a specific error code. The general status code, or class code, gives a classification value. The detailed status code gives an expanded description of the error that occurred. The specific error code provides additional error information, such as the error code DDP-PPC received from CMS. These codes are explained in the DDP-PPC/DDP-FJT Messages Reference Manual. 2.3.2. COPY Verbs Use the COPY verb in the procedure division of the application program whenever you want to issue a function call. The expansion in your program ensures the correct order of the operands in the call. The format for a COPY statement is: where: text-name Is the name of the function or information packet. This is an example of a COPY verb used to produce a DDP-PPC function call with its information packets referenced: This produces: ZDDDDDDDDDD? ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD? @DDDDDDDDDDDDDDDDDY@DDDDDDDDDDDDDDDDDY 2.3.3. Initializing Packet Field Values The DDP-PPC packets contain several fields that you do not require each time that you issue a function. You can tell DDP-PPC to ignore specific fields by: $ Setting them to a value, usually spaces or zeros, on a field-by-field basis $ Initializing the entire packet and then resetting specific fields to the desired values To initialize the packet and reset specific fields, perform the following steps: 1. Initialize or reinitialize all the allocated packets using a supplied set of packets that are pre-set to the required DDPvPPC initialization values. You can include this set of packets in you program by issuing the following statement: 3789 6651v100 2v9

COBOL Verbs and Function Calls 2. Set the default values for the DDP-PPC control packets by initializing individual packets: 3. The packet to be used in the function can then be initialized by assigning the initialization packet to it. For example, the DDN-OPEN-PKT can be initialized by coding the following in the main program: As a general practice, after you have moved the desired values into their respective fields, issued a command, and control has returned for the next operation, you should reinitialize all unused fields before issuing a different command. Without reinitialization, the command may generate an error message or produce unexpected results. 2v10 3789 6651v100

Section 3 Using DDP-PPC TCP/IP Function Calls This section describes the usage of each COBOL COPY verb with its associated information packets. Table 3-1 lists the COPY verbs, function calls, and information packets in the order you would use the commands in a typical program. 3.1. COBOL COPY Verbs and Function Calls You can use COBOL COPY verbs or code your own COBOL function calls to issue program-to-program commands from your COBOL program. You can direct these commands to the same host or to any remote host defined in the network. When you use a COBOL COPY verbs, the associated function call referencing the required information packets replaces the COPY verb when the program is compiled. You can code the function call yourself, but you must then supply the information packet names in the correct sequential order shown in Table 3-1. See 2.2 and 2.3 for a discussion on how to use function calls, information packets, and COPY verbs. Unused fields should be cleared before specifying any parameters and issuing a function call. You can use the initialization packets provided by DDP-PPC to initialize the fields. Table 3-1. Copy Verbs and Associated Function Calls and Information Packets Function COPY Verb Function Call Information Packets Referenced in USING Clause by COPY Verb/Function Attach an application to DDP-PPC Open a conversation with a host or wait for another host to open a conversation COPY DDN-SIGNON DDN$SIGNON DDN-STATUS-PKT DDN-SIGNON-PKT COPY DDN-OPEN DDN$OPEN DDN-STATUS-PKT DDN-MSG-BUFFER DDN-DATA-PKT DDN-OPEN-PKT Send a message COPY DDN-SEND DDN$SEND DDN-STATUS-PKT DDN-MSG-BUFFER DDN-DATA-PKT continued 3789 6651v100 3v1

COBOL COPY Verbs and Function Calls Table 3-1. Copy Verbs and Associated Function Calls and Information Packets (cont.) Function COPY Verb Function Call Information Packets Referenced in USING Clause by COPY Verb/Function Receive a message COPY DDN-RECEIVE DDN$RECEIVE DDN-STATUS-PKT DDN-MSG-BUFFER DDN-DATA-PKT DDN-RECEIVE-PKT Interrupt current processing without terminating a conversation (Telnet only) Replace a program in a conversation Terminate a conversation abnormally Close a conversation normally Detach an application from DDP-PPC COPY DDN-INT-PROCESS DDN$INTPROC DDN-STATUS-PKT DDN-MSG-BUFFER DDN-DATA-PKT COPY DDN-PASSOFF DDN$PASSOFF DDN-STATUS-PKT DDN-DATA-PKT COPY DDN-ABORT DDN$ABORT DDN-STATUS-PKT DDN-MSG-BUFFER DDN-DATA-PKT COPY DDN-CLOSE DDN$CLOSE DDN-STATUS-PKT DDN-MSG-BUFFER DDN-DATA-PKT COPY DDN-SIGNOFF DDN$SIGNOFF DDN-STATUS-PKT Note: In the following subsections, the formats of the DDN-STATUS-PKT and DDN-DATA-PKT packets are the same for each COPY verb/function call. For each COPY verb, the field definitions for those packets only describe the fields used for that particular COPY verb/function call. 3v2 3789 6651v100

Terminating a Conversation (DDN-ABORT) 3.2. Terminating a Conversation (DDN-ABORT) Function Use the DDN-ABORT copy verb to abnormally terminate a conversation in progress. The associated function call references the DDN-STATUS-PKT and DDN-DATA-PKT information packets. It also references the DDN-MSG-BUFFER working-storage area. Format or DDN-STATUS-PKT Packet Field definitions returned by DDP-PPC: DDN-PKT-ID DDN-ERR-FUNCTION DDN-CLASS-CODE DDN-DETAIL-STATUS DDP-PPC places DDN$ in this field after a successful function call. Redefines DDN-PKT-ID. When an error is encountered, an error code value is placed in this field. The value indicates which copy verb/function call had the error (see Table 3-2). DDP-PPC returns a general status code in this field to classify the status of error found. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. DDP-PPC returns a detailed status code in this field to identify the specific status or error encountered. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. continued 3789 6651v100 3v3

Terminating a Conversation (DDN-ABORT) continued DDN-SPECIFIC-ERROR DDN-STATUS-REDEF DDN-SIGNON-ID Contains more specific information about the error returned by this function call. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. Redefines the DDN-STATUS-GROUP field to allow a COBOL program to reference the DDN-CLASS-CODE and DDN-DETAIL-STATUS fields as one field. DDP-PPC returns a signon-id to identify the program when a DDN-SIGNON is issued. You must supply this value (in the same DDN-SIGNON-ID field) for all subsequent DDP-PPC function calls. Table 3-2. Copy Verbs and Associated Error Codes COPY Verb Error Code DDN-OPEN 0 DDN-SEND 1 DDN-CLOSE 2 DDN-ABORT 7 DDN-RECEIVE 16 DDN-SIGNON 17 DDN-SIGNOFF 18 DDN-PASSOFF 20 DDN-INT-PROCESS 25 DDN-MSG-BUFFER This is a required storage area for messages. The DDN-ABORT copy verb and associated function call reference this area. You must code this area in the working-storage section of the application program. See subsection 4.3 for details on specifying the size of this message buffer area. 3v4 3789 6651v100

Terminating a Conversation (DDN-ABORT) DDN-DATA-PKT Packet Field definitions set by user: DDN-CONV-ID Conversation-id. Required. Specify the same conversation-id value returned in this field by DDP-PPC on DDN-OPEN call completion. You do not have to set this field unless you have modified it since DDN-OPEN call completion. DDN-TEXT-LEN Text length. Required. Specify a value of 0. 3789 6651v100 3v5

Terminating a Conversation (DDN-ABORT) Example The following example shows the lines of code you insert in the procedure division: Procedure Typical Procedure Division Statements 1. Set text length. MOVE 0 TO DDN-TEXT-LEN. 2. Issue the function call. COPY DDN-ABORT. 3v6 3789 6651v100

Closing a Conversation (DDN-CLOSE) 3.3. Closing a Conversation (DDN-CLOSE) Function Use a DDN-CLOSE copy verb to close the conversation normally. The associated function call references the DDN-STATUS-PKT and DDN-DATA-PKT information packets. It also references the DDN-MSG-BUFFER working-storage area. Format or DDN-STATUS-PKT Packet See 3.2 for a description of the DDN-STATUS-PKT fields. DDN-MSG-BUFFER This is a required storage area for messages. Although the DDN-CLOSE copy verb and associated function call reference this area, no data is transferred on the close call. You must code this area in the working-storage section of the application program. See 4.3 for details on specifying the size of this message buffer area. DDN-DATA-PKT Packet 3789 6651v100 3v7

Closing a Conversation (DDN-CLOSE) Field definitions set by user: DDN-CONV-ID Conversation-id. Required. Specify the same conversation-id value returned in this field by DDP-PPCon DDN-OPEN call completion. You do not have to set this field unless you have modified it since DDN-OPEN call completion. DDN-TEXT-LEN Required. Specify a value of 0. Example The following example shows the lines of code you insert in the procedure division: Procedure Typical Procedure Division Statements 1. Set text length. MOVE 0 TO DDN-TEXT-LEN. 2. Issue the function call. COPY DDN-CLOSE. 3v8 3789 6651v100

Interrupting Current Processing without Closing (DDN-INT-PROCESS) 3.4. Interrupting Current Processing without Closing (DDN-INT-PROCESS) Function Use a DDN-INT-PROCESS copy verb to interrupt current processing without closing the conversation. The associated function call references the DDN-STATUS-PKT and DDN-DATA-PKT information packets. It also references the DDN-MSG-BUFFER working-storage area. Format or DDN-STATUS-PKT Packet See 3.2 for a description of the DDN-STATUS-PKT fields. DDN-MSG-BUFFER This is a required storage area for messages. Although the DDN-INT-PROCESS copy verb and associated function call reference this area, no data is transferred on the interrupt call. You must code this area in the working-storage section of the application program. See 4.3 for details on specifying the size of this message buffer area. DDN-DATA-PKT Packet 3789 6651v100 3v9

Interrupting Current Processing without Closing (DDN-INT-PROCESS) Field definitions set by user: DDN-CONV-ID Required. Specify the same value returned by DDP-PPC in this field on DDN-OPEN function call completion. You do not have to set this field unless you have modified it since your DDN-OPEN. DDN-TEXT-LEN Required. Specify a value of 0. Example The following example shows the lines of code you insert in the procedure division: Procedure Typical Procedure Division Statements 1. Set text length. MOVE 0 TO DDN-TEXT-LEN. 2. Issue the function call. COPY DDN-INT-PROC. 3v10 3789 6651v100

Opening a Conversation (DDN-OPEN) 3.5. Opening a Conversation (DDN-OPEN) Function Use a DDN-OPEN copy verb in the active mode to establish a conversation with a host. Use a DDN-OPEN copy verb in the passive mode to establish a listening post for conversations initiated by any host in the network. Use it in the open passive specific mode when you want to establish a listening post for a subsequent conversation initiated by a specific host. The associated function call references the DDN-STATUS-PKT, DDN-OPEN-PKT, and DDN-DATA-PKT information packets. It also references the DDN-MSG-BUFFER working-storage area. Format or DDN-STATUS-PKT Packet See 3.2 for a description of the DDN-STATUS-PKT fields. DDN-MSG-BUFFER This is a required storage area for messages. Although the DDN-OPEN copy verb and associated function call reference this area, no data is transferred on the open call. You must code this area in the working-storage section of the application program. See 4.3 for details on specifying the size of this message buffer area. DDN-DATA-PKT Packet 3789 6651v100 3v11

Opening a Conversation (DDN-OPEN) Field definitions set by user: DDN-TEXT-LEN Required. Specify a value of 0. Field definitions returned by DDP-PPC: DDN-CONV-ID DDP-PPC returns a conversation-id. Save the conversation-id when you are using multiple conversations. DDN-OPEN-PKT Packet 3v12 3789 6651v100

Opening a Conversation (DDN-OPEN) Field definitions set by user: DDN-OPEN-TYPE Required. Set to 0 for open active. Set to 2 for open passive or 1 for open passive specific. DDN-LOCAL-PORT DDN-REMOTE-PORT DDN-HOST-ID-LEN DDN-HOST-ID DDN-OPEN-PROTOCOL Required if DDN-OPEN-TYPE is set to 2 (open passive) or 1 (open passive specific). Set to id of port on local host to open. For compatibility with other systems, you should use port numbers greater than 1024.* Required if DDN-OPEN-TYPE is set to 0 (open active) or 1 (open passive specific). Set to id of port on target host. For compatibility with other systems, you should use port numbers greater than 1024.* Required if DDN-OPEN-TYPE is set to 0 or 1 (open active or open passive specific). Specify the length of the host-id character string. Required if DDN-OPEN-TYPE is set to 0 or 1 (open active or open passive specific). Specify the host-id in the form of a domain name or an Internet physical address (n1-n2-n3-n4), where each n ranges from 0 to 255. See Appendix A for host-id naming conventions. Required. Set to 4 for Telnet protocol. Set to 5 for transmission control protocol (TCP). *When you are connected to a host other than a Unisys host, you must specify the numbering system used on that host. Examples The following shows the lines of code you insert in your program for an Open Active: Procedure Typical Procedure Division Statements 1. Set text length. MOVE 0 TO DDN-TEXT-LEN. 2. Set to active. MOVE 0 TO DDN-OPEN-TYPE. 3. Set remote port. MOVE 1075 TO DDN-REMOTE-PORT. 4. Set host-id length. MOVE 7 TO DDN-HOST-ID-LEN. 5. Specify host name. MOVE REMOTEB TO DDN-HOST-ID. 6. Set for Telnet. MOVE 4 TO DDN-OPEN-PROTOCOL. 7. Issue the function call. COPY DDN-OPEN. 3789 6651v100 3v13

Opening a Conversation (DDN-OPEN) The following shows the lines of code you insert in your program for an Open Passive: Procedure Typical Procedure Division Statements 1. Set text length. MOVE 0 TO DDN-TEXT-LEN. 2. Set to passive. MOVE 2 TO DDN-OPEN-TYPE. 3. Set local port. MOVE 1275 TO DDN-LOCAL-PORT. 4. Set for Telnet. MOVE 4 TO DDN-OPEN-PROTOCOL. 5. Issue the function call. COPY DDN-OPEN. 3v14 3789 6651v100

Opening a Conversation (DDN-OPEN) The following shows the lines of code you insert in your program for an Open Passive Specific: Procedure Typical Procedure Division Statements 1. Set text length. MOVE 0 TO DDN-TEXT-LEN. 2. Set to passive specific. MOVE 1 TO DDN-OPEN-TYPE. 3. Set local port. MOVE 1275 TO DDN-LOCAL-PORT. 4. Set remote port. MOVE 1280 TO DDN-REMOTE-PORT. 5. Set host-id length. MOVE 7 TO DDN-HOST-ID-LEN. 6. Specify host name. MOVE REMOTEA TO DDN-HOST-ID. 7. Set for Telnet. MOVE 4 TO DDN-OPEN-PROTOCOL. 8. Issue the function call. COPY DDN-OPEN. Additional Discussion You can select two distinct conversation protocol types: $ Transmission Control Protocol (TCP) $ Telnet protocol In a TCP conversation, data transfers are asynchronous. The lower layers of the TCP/IP interface software block the user messages and may even fragment them in transmission. Messages are received in the order sent, but a message may be delivered in its entirety or in fragments. An application program must recognize individual messages, so it can deblock the delivered data and reassemble messages from fragmented deliveries. If a message contains noncharacter data (such as binary integer), the application program compensates for the fact that the ninth bit is dropped in transit. In a Telnet conversation, the data transfer may be either synchronous or asynchronous. Telnet is a line-oriented protocol that expects a single line of ASCII character data. A carriage return and line feed character terminates each message. The only supported transmission mode is full-duplex. 3789 6651v100 3v15

Replacing a Program in a Conversation (DDN-PASSOFF) 3.6. Replacing a Program in a Conversation (DDN-PASSOFF) Function A DDN-PASSOFF copy verb replaces a program with a different program in a conversation. The replacement program must already have issued a DDN-SIGNON call in the same host as the present program. The replacement program is called the processor. When two programs are already engaged in a conversation, each program can give the right to another program to replace it in the conversation. The conversation remains the same, only the participating programs change. If a program is involved in more than one concurrent conversation, not all conversations need to be passed off. Each conversation can be passed off individually. Figure 3-1 shows a block diagram of a typical passoff operation. In this illustration, primary program A in host A initially establishes a conversation with secondary program B in host B. At a user-designated time, the send/receive conversation loop is terminated, and program A performs a passoff request to program C. Control of the conversation is then transferred from Program A to Program C. Since Program A has no other conversations, it detaches from DDP-PPC. Program C, which is already attached to DDP-PPC, receives control of the conversation. The conversation continues uninterrupted, but now it exists between primary program C and secondary program B. Later, secondary program B terminates its receive/send loop, passes off to program D, and detaches program B from DDP-PPC. Again, the conversation continues, but it now exists between primary program C and secondary program D. 3v16 3789 6651v100

Replacing a Program in a Conversation (DDN-PASSOFF) Host A Host B Program A Program B SIGNON SIGNON OPEN RECEIVE (NEW) RECEIVE (EXISTING) SEND (REPLY) Loop SEND RECEIVE (EXISTING) Participating Programs A-B RECEIVE (EXISTING) SEND (REPLY) Loop PASSOFF SIGNOFF Program C Loop SIGNON SEND RECEIVE (EXISTING) Participating Programs C-B RECEIVE (EXISTING) SEND (REPLY) RECEIVE (EXISTING) Loop SEND PASSOFF SIGNOFF Program D SIGNON RECEIVE (EXISTING) SEND (REPLY) Loop SEND RECEIVE (EXISTING) Participating Programs C-D RECEIVE (EXISTING) SEND (REPLY) Loop CLOSE RECEIVE (EXISTING) RECEIVE (EXISTING) SEND (END) SIGNOFF SIGNOFF Figure 3-1. Typical Block Diagram for Program-to-Program Passoff Succession The associated function call references the DDN-STATUS-PKT and DDN-DATA-PKT information packets. Format or 3789 6651v100 3v17

Replacing a Program in a Conversation (DDN-PASSOFF) DDN-STATUS-PKT Packet See 3.2 for a description of the DDN-STATUS-PKT fields. DDN-DATA-PKT Packet Field definitions set by user: DDN-CONV-ID DDN-SUCC-ID Conversation-id. Required. Specify the same conversation-id value returned in this field by DDP-PPC on DDN-OPEN call completion. You do not have to set this field unless you have modified it since DDN-OPEN call completion. Successor-id. Required. Specify the signon-id returned in the DDN-STATUS-PKT on the DDN-SIGNON call of the successor application program. 3v18 3789 6651v100

Replacing a Program in a Conversation (DDN-PASSOFF) Example The following example shows the lines of code you insert in the procedure division: Procedure Typical Procedure Division Statements 1. Set successor-id. MOVE DDN-SIGNON-ID TO DDN-SUCC-ID. 2. Issue the function call. COPY DDN-PASSOFF. 3789 6651v100 3v19

Receiving a Message from a Host (DDN-RECEIVE) 3.7. Receiving a Message from a Host (DDN-RECEIVE) Function A DDN-RECEIVE copy verb accepts messages from a local or remote host. The associated function call references the DDN-STATUS-PKT, DDN-RECEIVE-PKT and DDN-DATA-PKT information packets. Note that when you issue a DDN-RECEIVE after a DDN-OPEN, the data that DDP-PPC returns will overwrite the DDN-DATA-PKT packet. Therefore, you should: $ Save the DDN-DATA-PKT packet before issuing a DDN-RECEIVE $ Restore the DDN-DATA-PKT packet after issuing a DDN-RECEIVE It also references the DDN-MSG-BUFFER working-storage area. Format or DDN-STATUS-PKT Packet See 3.2 for a description of the DDN-STATUS-PKT fields. DDN-MSG-BUFFER This is a required storage area for messages. The DDN-RECEIVE copy verb and associated function call reference this area to transfer the data. You must code this area in the working-storage section of the application program. See 4.3 for details on specifying the size of this message buffer area. DDN-DATA-PKT Packet 3v20 3789 6651v100

Receiving a Message from a Host (DDN-RECEIVE) Field definitions set by user: DDN-CONV-ID DDN-BUFFER-OFFSET DDN-TEXT-LEN Conversation-id. Required. Specify the same conversation-id value returned in this field by DDP-PPC on DDN-OPEN call completion. You do not have to set this field unless you have modified it since DDN-OPEN call completion. Required. Specify the offset, in characters, from beginning of DDN-MSG-BUFFER where text is to be stored. Required. Specify the length in characters of the text to be received. DDN-READ-START Required. This value must be 0 or a multiple of 4. DDN-RELEASE-MSG Required. Specify 1 to release the message from the DDP-PPC queue; specify 0 to hold the message. If you release the message, you cannot issue another receive for that message. If you hold the message, you must issue another receive with DDN-RELEASE-MSG set to 1 (to free the message from the DDP-PPC queue, thus allowing you to access the next message on the queue with a subsequent receive). 3789 6651v100 3v21

Receiving a Message from a Host (DDN-RECEIVE) Field definitions returned by DDP-PPC: DDN-LOCAL-HOST-NAME DDN-LOCAL-DOMAIN-HOST- NAME DDN-LOCAL-DOMAIN-HOST- LENGTH DDN-REMOTE-HOST-NAME DDN-REMOTE-DOMAIN-HOST- NAME DDN-REMOTE-DOMAIN-HOST- LENGTH The name of the local host in Internet physical address format. Returned when DDN-RCV-EVENT is DDN-OPEN-ID. The name of the local domain host. Returned when DDN-RCV-EVENT is DDN-OPEN-ID. The length of the local domain host name. Returned when DDN-RCV-EVENT is DDN-OPEN-ID. The name of the remote host in Internet physical address format. Returned when DDN-RCV-EVENT is DDN-OPEN-IND. The name of the remote domain host. Returned when DDN-RCV-EVENT is DDN-OPEN-IND. The length of the remote domain host name. Returned when DDN-RCV-EVENT is DDN-OPEN-IND. Note: See Appendix A for host-id naming conventions and 4.4 for details on restoring the receiving packet. DDN-RECEIVE-PKT Packet 3v22 3789 6651v100

Receiving a Message from a Host (DDN-RECEIVE) Field definitions set by user: DDN-WAIT-TIME DDN-CONV-TYPE DDN-RCV-PROGRAM-NAME Required. Set this field to the time, in seconds, that you want to remain in a receive loop before receiving a No Message status. Required. Specify 4 for Telnet and 5 for TCP. See 3.5for additional information. Required. Set this field to the name used for DDN-PROGRAM-NAME in DDN-SIGNON-PKT. Field definitions returned by DDP-PPC: DDN-RCV-REASON DDN-RCV-EVENT DDN-RCV-REMOTE-PORT DDN-TOTAL-MSG-LEN DDN-RCV-TELNET-IND Posts errors encountered during a receive. Indicates the state of the conversation. Indicates the port number on the remote host. Returned when DDN-RCV-EVENT is DDN-OPEN-IND. Indicates the total length, in characters, of the message received in the DDP-PPC buffer (not the length of the current message increment). Contains indicators only when using Telnet. Example The following example shows the lines of code you insert in the procedure division: Procedure Typical Procedure Division Statements 1. Set buffer offset. MOVE 20 TO DDN-BUFFER-OFFSET. 2. Set text length. MOVE 80 TO DDN-TEXT-LEN. 3. Set read start. MOVE 0 TO DDN-READ-START. 4. Release the message. MOVE 1 TO DDN-RELEASE-MSG. 5. Set wait time. MOVE 10 TO DDN-WAIT-TIME. 6. Set for Telnet. MOVE 4 TO DDN-CONV-TYPE. 7. Set name of program to receive. MOVE MYPROGRAM TO DDN-RCV-PROGRAM NAME. 8. Issue the function call. COPY DDN-RECEIVE. 3789 6651v100 3v23

Sending a Message (DDN-SEND) 3.8. Sending a Message (DDN-SEND) Function Use a DDN-SEND copy verb to send messages to a local or remote host. The associated function call references the DDN-STATUS-PKT and DDN-DATA-PKT information packets. It also references the DDN-MSG-BUFFER working-storage area. Format or DDN-STATUS-PKT Packet See 3.2 for a description of the DDN-STATUS-PKT fields. DDN-MSG-BUFFER This is a required storage area for messages. The DDN-SEND copy verb and associated function call reference this area to transfer the data. You must code this area in the working-storage section of the application program. See 4.3 for details on specifying the size of this message buffer area. DDN-DATA-PKT Packet 3v24 3789 6651v100

Sending a Message (DDN-SEND) Field definitions set by user: DDN-CONV-ID DDN-BUFFER-OFFSET DDN-TEXT-LEN Conversation-id. Required. Specify the same conversation-id value returned in this field by DDP-PPC on DDN-OPEN call completion. You do not have to set this field unless you have modified it since DDN-OPEN call completion. Required. Specify offset, in characters, from beginning of DDN-MSG-BUFFER where text to be sentis located. Required. Specify length in characters of text to be sent. Example The following example shows the lines of code you insert in the procedure division: Procedure Typical Procedure Division Statements 1. Set buffer offset. MOVE 20 TO DDN-BUFFER-OFFSET. 2. Set text length. MOVE 132 TO DDN-TEXT-LEN. 3. Issue the function call. COPY DDN-SEND. 3789 6651v100 3v25

Detaching an Application Program from DDP-PPC (DDN-SIGNOFF) 3.9. Detaching an Application Program from DDP-PPC (DDN-SIGNOFF) Function Use a DDN-SIGNOFF copy verb to detach your application program from DDP-PPC. The associated function call references the DDN-STATUS-PKT information packet. Format or DDN-STATUS Packet See 3.2 for a description of the DDN-STATUS-PKT fields. Example The following example shows the lines of code you insert in the procedure division: Procedure Typical Procedure Division Statements 1. Issue the function call. COPY DDN-SIGNOFF. 3v26 3789 6651v100

Attaching an Application Program to DDP-PPC (DDN-SIGNON) 3.10. Attaching an Application Program to DDP-PPC (DDN-SIGNON) Function A DDN-SIGNON copy verb attaches your application program to DDP-PPC. The associated function call references the DDN-STATUS-PKT and DDN-SIGNON-PKT information packets. Format or DDN-STATUS-PKT Packet Field definitions returned by DDP-PPC: DDN-PKT-ID DDN-ERR-FUNCTION DDN-CLASS-CODE DDN-DETAIL-STATUS DDP-PPC places DDN$ in this field after a successful function call. Redefines DDN-PKT-ID. When an error is encountered, an error code value is placed in this field. The value indicates which copy verb/function call had the error (see Table 3-2). DDP-PPC returns a general status code in this field to classify the status of error found. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. DDP-PPC returns a detailed status code in this field to identify the specific status or error encountered. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. continued 3789 6651v100 3v27

Attaching an Application Program to DDP-PPC (DDN-SIGNON) continued DDN-SPECIFIC-ERROR DDN-STATUS-REDEF DDN-SIGNON-ID Contains more specific information about the error returned by this function call. The error codes are described in the DDP-PPC/DDP-FJT Messages Reference Manual. Redefines the DDN-STATUS-GROUP field to allow a COBOL program to reference the DDN-CLASS-CODE and DDN-DETAIL-STATUS fields as one field. DDP-PPC returns a signon-id to identify the program when DDN-SIGNON is issued. You must supply this value (in the same DDN-SIGNON-ID field) for all subsequent DDP-PPC function calls. DDN-SIGNON-PKT Packet Field definitions set by user: DDN-PROGRAM-NAME Required. Specify up to 12 ASCII characters for the name you want to assign to your applications program. Example The following example shows the lines of code you insert in the procedure division: Procedure Typical Procedure Division Statements 1. Set program name. MOVE MYPROGRAM TO DDN-PROGRAM-NAME. 2. Issue the function call. COPY DDN-SIGNON. 3v28 3789 6651v100

Section 4 Designing and Writing the Application 4.1. Using a Block Diagram When designing a DDP-PPC COBOL application, you should always lay out a block diagram of what you want to do. The description in this section is a basic conversation between two programs in two separate host computers. The numbers in parentheses in the following description are keyed to the circled numbers in the basic block diagram (Figure 4-1) and the expanded flow diagram (Figure 4-2 and Figure 4-3). This example: $ Ataches to DDP-PPC $ Opens a conversation with another program $ Sends a message to the other program $ Receives a reply $ Terminates the conversation $ Receives a close confirm $ Detaches from DDP-PPC The sender of the data is the primary program, and the receiver is the secondary program. 3789 6651v100 4v1

Using a Block Diagram Primary Program Secondary Program 1A SIGNON (Host Z) 1B SIGNON (Host M) 2A ACTIVE OPEN REMOTE PORT=X LOCAL PORT=0 HOST ID=M 2B PASSIVE OPEN REMOTE PORT=0 LOCAL PORT=X 3B1 RECEIVE RCV-EVENT=Open identifier 3A RECEIVE RCV-EVENT=Open identifier 3B2 RECEIVE RCV-EVENT=Open indicator 4A SEND Loop (If status NE OK then error routine) 4B RECEIVE Loop (Until RCV-EVENT NE Data indicator) 5A CLOSE (When completed processing) 5B If RCV-EVENT= Close indicator then go to CLOSE 6A RECEIVE (Close confirm indicator)* 6B CLOSE 7A SIGNOFF 7B SIGNOFF * The primary program should be prepared to accept either a close indicator or a close confirm indicator. The primary program (sender): $ Signs on to DDP-PPC (1A) Figure 4-1. Typical Program-to-Program Block Diagram $ Issues an active open to establish a connection with the secondary program (2A) $ Enters a receive mode loop to await an open establishment acknowledgement from the secondary program (3A) $ Receives the open establishment acknowledgement and begins to send data (4A) 4v2 3789 6651v100

Using a Block Diagram The secondary program (receiver): $ Signs on to DDP-PPC (1B) $ Enters a passive open mode to accept connection requests (2B) Note: The secondary program must be active with a listening port available before the primary program sends an open request. $ Enters a receive mode loop, waiting for a connection request from any sending program (3B1, 3B2) $ Receives the open connection request (as a result of a primary program performing an active open) (2A), and enters a receive mode loop awaiting data from the primary program (4B) After sending the last message, the primary program terminates the conversation with a close (5A). If the receive event from the primary program indicates a close (5B), the secondary program closes the conversation (6B). The primary program receives confirmation of the close (6A). Both programs now perform a signoff request to their respective hosts to detach from DDP-PPC (7A, 7B). 3789 6651v100 4v3

Creating a Flow Diagram 4.2. Creating a Flow Diagram Once you design the basic block diagram, you can create a flow diagram by filling in the blocks with COBOL procedure statements (as shown in Figure 4-2 and Figure 4-3) according to the requirements defined for each copy verb. In most cases, you fill in the blocks by taking the example given under each copy verb in 3.2 through 3.10 and placing it in the appropriate block. Some changes from the example might have to be made, depending on whether you are in the primary or secondary program. To keep the flow diagram as simple as possible, error/status checking routines are not shown. See the examples in subsections B.2 and B.3 for a complete working example. 4v4 3789 6651v100

Creating a Flow Diagram Primary Program Secondary Program 1A SIGN-ON-RT. 1B SIGN-ON-RT. MOVE 'ACT1' TO DDN-PROGRAM-NAME. MOVE 'RCV1' TO DDN-PROGRAM-NAME. COPY DDN-SIGNON. COPY DDN-SIGNON. 2A OPEN-RT. (Active) 2B OPEN-RT. (Passive) MOVE 0 TO DDN-TEXT-LEN. MOVE 0 TO DDN-OPEN-TYPE. MOVE 280 TO DDN-REMOTE-PORT. MOVE 12 TO DDN-HOST-ID-LEN. MOVE 'HOST-ID-SYS1' TO DDN-HOST-ID. MOVE 4 TO DDN-OPEN-PROTOCOL. MOVE 0 TO DDN-TEXT-LEN. MOVE 2 TO DDN-OPEN-TYPE. MOVE 280 TO DDN-LOCAL-PORT. MOVE 4 TO DDN-OPEN-PROTOCOL. COPY DDN-OPEN. COPY DDN-OPEN. IF NOT DDN-OK PERFORM ERROR-RT. (See 3A1) 3B1 IF NOT DDN-OK PERFORM ERROR-RT. (See 2B1) RECEIVE-OPEN-ID. 3A RECEIVE-RT. MOVE 0 TO DDN-BUFFER-OFFSET. MOVE 256 TO DDN-TEXT-LEN. MOVE 0 TO DDN-READ-START. MOVE 1 TO DDN-RELEASE-MSG. MOVE 60 TO DDN-WAIT-TIME. MOVE 4 TO DDN-CONV-TYPE. MOVE 'ACT1' TO DDN-RCV-PROGRAM-NAME. COPY DDN-RECEIVE. IF NOT DDN-OK PERFORM ERROR-RT. (See 3A1) MOVE 0 TO DDN-BUFFER-OFFSET. MOVE 256 TO DDN-TEXT-LEN. MOVE 0 TO DDN-READ-START. MOVE 1 TO DDN-RELEASE-MSG. MOVE 10 TO DDN-WAIT-TIME. MOVE 4 TO DDN-CONV-TYPE. MOVE 'RCV1' TO DDN-RCV-PROGRAM-NAME. COPY DDN-RECEIVE. IF DDN-NO-MSG OR NOT DDN-OPEN-ID PERFORM RECEIVE-OPEN-ID. IF DDN-OK IF NOT DDN-OPEN-ID PERFORM ERROR-RT. (See 2B1) 3B2 RECEIVE-OPEN-IND. COPY DDN-RECEIVE. IF DDN-NO-MSG OR NOT DDN-OPEN-IND PERFORM CLOSE-RT. IF DDN-CLOSE-IND PERFORM CLOSE-RT. IF NOT DDN-OK PERFORM ERROR-RT. Legend Program to program flow Intraprogram flow Figure 4-2. Typical Procedure Division Program-to-Program Flow Diagram (Part 1) 3789 6651v100 4v5

Creating a Flow Diagram Primary Program Secondary Program 4A SEND-MSG-LOOP. 4B RECEIVE-MSG-RT. MOVE 0 TO DDN-BUFFER-OFFSET. MOVE 256 TO DDN-TEXT-LEN. COPY DDN-RECEIVE. COPY DDN-SEND. 5A CLOSE-RT. MOVE 0 TO DDN-TEXT-LEN. COPY DDN-CLOSE. 5B IF DDN-DATA-IND * GO TO RECEIVE-MSG-RT. (Process the message) 6A RECEIVE-CLOSE-CONFIRM-RT. 6B CLOSE-RT. COPY DDN-RECEIVE. MOVE 0 TO DDN-TEXT-LEN. COPY DDN-CLOSE. 7A SIGN-OFF-RT. RECEIVE-CLOSE-CONFIRM-RT. COPY DDN-SIGNOFF. COPY DDN-RECEIVE. 8A EXIT-RT. EXIT. IF NOT DDN-CLOSE-CONFIRM. 7B SIGN-OFF-RT. COPY DDN-SIGNOFF. 8B EXIT-RT. EXIT. 3A1 ERROR-RT. 2B1 ERROR-RT. DISPLAY ERROR-MSG. DISPLAY EROR-MSG. 3A2 ABORT-RT. 2B2 ABORT--RT. COPY DDN-ABORT. COPY DDN-ABORT. Legend Program to program flow Intraprogram flow Figure 4-3. Typical Procedure Division Program-to-Program Flow Diagram (Part 2) 4v6 3789 6651v100

Using the Message Buffer Area 4.3. Using the Message Buffer Area DDP-PPC uses the message buffer area of your program to exchange data. This is the interface area that DDP-PPC uses to transfer messages. When you issue a COPY verb, DDP-PPC uses DDN-MSG-BUFFER in the function call as the name of the message buffer area. You must define this area in working-storage to meet the needs of your application. You can alternatively format and define this area to meet your own preferences. For example, you can define separate input and output buffers. You can also directly reference display messages, text messages, or error messages without moving them into the message buffer before issuing the COPY verb or function call. 4.3.1. Formatting and Defining the Buffer Area You can format your own message buffer area by using standard data descriptions to define the buffer in your working-storage section. You can define a single buffer for both input and output. For example: You can also define separate input and output buffers. For example: The maximum buffer size is 8232 characters. 4.3.2. Referencing the Buffer Area After you have formatted and defined the message buffer areas, you must reference the names you assigned to these areas in the USING phrase of the function call. To do this, use copy verbs with a REPLACING phrase as follows: This automatically gives you the correct format and parameter sequence. It also ensures that the names you assigned to the message buffer area are placed correctly in the function call. 3789 6651v100 4v7

Using the Message Buffer Area For output messages, you can also directly reference data definition messages in the working-storage section. Using this method, you do not need to move the message into the message buffer area before issuing the copy verb or function call. For example: Replacing the name of the message buffer area with the name of the message text, a DDN$OPEN copy verb looks like: Producing the function call: 4v8 3789 6651v100

Writing a Program-to-Program Application 4.4. Writing a Program-to-Program Application This subsection describes the more important factors to consider when writing a DDP-PPC program-to-program application. It does not contain a complete description of the fields that need to be set. 4.4.1. General Considerations Consider the following when writing a program-to-program application: $ Check the DDN-STATUS-PKT after every DDP-PPC function call to determine the success or failure of the function. $ Set the DDN-WAIT-TIME field in the DDN-RECEIVE-PKT to allow adequate time to receive data from a remote host. Consider network traffic and resources when specifying the time-out value. $ If the peer application is waiting for a response from your application, ensure that your application is not processing for a time period that exceeds the peer application time-out value. This may indicate that your application did not receive a message. $ Check the DDN-RCV-EVENT field in the DDN-RECEIVE-PKT after every DDN-RECEIVE function call to determine the processing that the application should do next. $ The application must restore the DDN-DATA-PKT after receiving a DDN-OPEN-ID or DDN-OPEN-IND in the DDN-RCV-EVENT field of the DDN-RECEIVE-PKT. DDP-PPC returns the DDN-LOCAL-HOST-NAME when the DDN-RCV-EVENT value is DDN-OPEN-ID and returns the DDN-REMOTE-HOST-NAME when the DDN-RCV-EVENT value is DDN-OPEN-IND. These host names overlay most of the DDN-DATA-PKT. $ Initialize unused fields in the packets. 4.4.2. Receiving Data from a Remote Host When you are receiving data from a remote host, consider the following: $ Data is stream-oriented $ Data may be segmented or concatenated Depending on resources and network traffic, data received may be: $ One message sent from the remote host $ Multiple messages sent from the remote host $ A partial message sent from the remote host 3789 6651v100 4v9

Writing a Program-to-Program Application The application must be able to handle data segments and concatenated data. Using the DDN-TEXT-LEN field in the DDN-DATA-PKT, the application indicates how much data DDP-PPC can give the application. The actual length of the data received is returned in the DDN-TOTAL-MSG-LEN field of the DDN-RECEIVE-PKT. Although the length of the data received may be larger, DDP-PPC never returns more data than the application requests. You can handle this situation in two ways: Method 1 1. Set the DDN-TEXT-LEN field in the DDN-DATA-PKT to a value above 8232 (the maximum size that the program product TCP-IP can give to DDP-PPC). 2. Set DDN-RELEASE-MSG to 1 to release the data from the input queue. 3. Issue a DDN-RECEIVE. 4. Parse the data based on the value in the DDN-TOTAL-MSG-LEN field of the DDN-RECEIVE-PKT to determine if more than one message or a partial message was received. This is the most efficient method of exchanging data with a remote application. For example, assume that the application: $ Expects 200-character messages $ Sets DDN-TEXT-LEN to 8232, DDN-RELEASE-MSG to 1, DDN-BUFFER-OFFSET to 0, and DDN-READ-START to 0 $ Issues a DDN-RECEIVE Then, if the DDN-TOTAL-MSG-LEN is: $ 200, the application receives one message sent from the remote application. $ 400, the application receives 400 characters and processes the data as two separate messages sent from the remote application. $ 100, the application receives 100 characters, which is a partial message sent from the remote application. The application should then issue a DDN-RECEIVE function call to receive the next message segment. Method 2 1. Set the DDN-TEXT-LEN field of the DDN-DATA-PKT to the size of the message that the remote application sends. 2. Set the DDN-RELEASE-MSG field to 0 to keep the data in the input queue. 3. Issue a DDN-RECEIVE function call. 4. Use the length returned in DDN-TOTAL-MSG-LEN to determine if DDP-PPC received more than one message. This determines how many more, if any, DDN-RECEIVE functions you must issue before releasing the data from the input queue. 4v10 3789 6651v100

Writing a Program-to-Program Application Then, if the DDN-TOTAL-MSG-LEN field is: $ Greater than DDN-TEXT-LEN, the application must: 1. Initially set the DDN-READ-START field to 0. 2. Set DDN-BUFFER-OFFSET to indicate where to place the data in the application s buffer. 3. Increment DDN-READ-START by DDN-TEXT-LEN for each DDN-RECEIVE function until all data is received. 4. Issue another DDN-RECEIVE function with DDN-READ-START set to the offset in the input queue where the receive is to start. (DDN-READ-START must be a multiple of 4.) 5. When all data is received: a. Set DDN-RELEASE-MSG to 1. b. Set DDN-TEXT-LEN to 0. c. Issue a DDN-RECEIVE function to remove the data from the input queue. $ Equal to DDN-TEXT-LEN, the application received an entire message sent from the remote application and must: 1. Set DDN-RELEASE-MSG to 1. 2. Set DDN-TEXT-LEN to 0. 3. Issue a DDN-RECEIVE function to remove the data from the input queue. $ Less than DDN-TEXT-LEN. Then the application received a partial message sent from the remote application and must: 1. Set DDN-RELEASE-MSG to 1. 2. Set DDN-TEXT-LEN to 0. 3. Issue a DDN-RECEIVE function to remove the partial message from the input queue. If DDP-PPC received a partial message, your application must prepare the next DDN-RECEIVE function to handle the next segment of the message. Set the DDN-BUFFER-OFFSET field to indicate where to place the next segment in the application s buffer and issue the DDN-RECEIVE function. The value in the DDN-TOTAL-MSG-LEN field for the current DDN-RECEIVE determines what you do next. That is, the application follows the previous rules, depending on whether the current DDN-TOTAL-MSG-LEN field is greater than, equal to, or less than DDN-TEXT-LEN. 3789 6651v100 4v11

Writing a Program-to-Program Application For example, assume that the application: $ Expects 200-character messages $ Sets DDN-TEXT-LEN to 200, DDN-RELEASE-MSG to 0, DDN-BUFFER-OFFSET to 0, and DDN-READ-START to 0 $ Issues a DDN-RECEIVE Then, if the DDN-TOTAL-MSG-LEN is: $ 200, the application receives the entire message, but must issue another DDN-RECEIVE with DDN-RELEASE-MSG set to 1 to release the message from the input queue. $ 400, the application processes the 200 characters, then sets DDN-RELEASE-MSG to 1, sets DDN-READ-START to 200, issues a DDN-RECEIVE to get the last 200 characters, and releases the data from the queue. $ 100, the application sets DDN-RELEASE-MSG to 1, sets DDN-TEXT-LEN to 0, and issues a DDN-RECEIVE function to release the partial message from the input buffer. At this point, the application can process this partial message or issue a DDN-RECEIVE function call to receive the next message segment. 4.4.3. Closing a Conversation To close a conversation, the application acting as the primary program must: 1. Issue a DDN-CLOSE function. 2. Check the DDN-STATUS-PKT to ensure that the close function was successful. 3. Issue a DDN-RECEIVE function. The application then: 1. Receives a DDN-CLOSE-IND, DDN-CLOSE-CONF, or DDN-ABORT-IND in the DDN-RCV-EVENT field of the DDN-RECEIVE-PKT. 2. If the application received a DDN-CLOSE-IND in step one, then it should continue to issue DDN-RECEIVE functions until the DDN-RCV-EVENT field contains a DDN-CLOSE-CONF or DDN-ABORT-IND. The conversation is then closed. 4v12 3789 6651v100

Section 5 Compiling and Executing Programs 5.1. Preparing Programs for Execution After you write your COBOL application programs, you compile, collect or link, and execute the COBOL programs the same as any other ASCII or UCS COBOL program. There are only three special requirements: 5.1.1. Calling TCP/IP functions only 1. If you use the supplied COBOL COPY elements in your program, you must issue the following statements before compiling your program: 2. You must include relocatable or object module elements when you collect each program into an absolute or output object module element. For ASCII COBOL, include DDN$COBPPPC. For UCS COBOL, include UCSINTFPPPP. Before running your ASCII COBOL application, keep these precautions in mind: $ You must follow the recommended MAP instructions in the collection of your programs. Failure to follow these instructions can corrupt data banks, resulting in the abnormal termination of your program. $ All buffer addresses, message lengths, user-ids, and conversation-ids must be correct. Errors passed to DDP-PPC can cause an abnormal termination of your program. 5.1.2. Calling TCP/IP and TAS Program Callable-Functions 1. Issue the following before compiling: 2. If calling TCP/IP and TAS DDN$COBPPPC program-callable functions from within the same program, instead of including for ASCII COBOL, include TCP$COBPPP from the SYS$LIB$*DDP-PPC-1 library. 3789 6651v100 5v1

Run Streams for DDP-PPC COBOL Programs 5.2. Run Streams for DDP-PPC COBOL Programs Follow these steps to compile, collect or link, and execute a DDP-PPC COBOL program: 1. Obtain a clean compilation of the COBOL application program using the DDP-PPC supplied COBOL copy elements. 2. Collect (@MAP) or link (@LINK) the relocatable or object module application element obtained from the compilation along with the relocatable or object module DDP-PPC COBOL interface elements into one absolute or output object module element in a program file. 3. Then, execute the program (@XQT) using the absolute or output object module element name of the file and element you supplied on the @MAP or @LINK statement. The DDP-PPC COBOL interface elements are supplied on your release tape. They are installed in the file SYS$LIB$*DDP-PPC-4. To copy them into your own file, change the COB$PF and PPPCLIB @USE statements accordingly. In the sample streams, uppercase letters must be entered exactly as shown. Lowercase letters are names that you can select. See Appendix Afor file-naming conventions. Figure 5-1 shows a sample stream to: $ Compile an ASCII COBOL application program using DDP-PPC supplied COBOL copy elements $ Collect the application program and DDP-PPC COBOL interface relocatable elements into an absolute program $ Execute the absolute program For ASCII COBOL transaction processing (TIP) application programs, you can use the same procedure as you would use for non-tip application programs. 5v2 3789 6651v100

Run Streams for DDP-PPC COBOL Programs Figure 5-1. Compile, Collect, and Execute Stream for an ASCII COBOL Application Program Notes: If the FLAGGER option is not set during your ACOB compilation, do not specify the RN options on the ACOB statement. ** These elements are no longer required. However, for compatibility purposes, they can remain in the map stream. Figure 5-2 shows a sample stream to: $ Compile a UCS COBOL application program using DDP-PPC supplied COBOL copy elements $ Link the application program and DDP-PPC COBOL interface object module element into an output object module element $ Execute the output object module 3789 6651v100 5v3

Banking Considerations Figure 5-2. Compile, Link, and Execute Stream for a UCS COBOL Application Program Note that Steps 2 and 3 in Figure 5-2 use the UCS static linking capability. Alternatively, you can use dynamic linking, which is faster. To use dynamic linking, replace Steps 2 and 3 with the following: $ Copy the UCSINTFPPPP object module from SYS$LIB$*DDP-PPC-4 to the same file that contains the UCS COBOL compiler output object module. $ Execute the UCS COBOL compiler output object module, as follows: 5.3. Banking Considerations 5.3.1. UCS COBOL Consider the following when using UCS COBOL: $ Banks that contain the message buffer and packets must not be greater than 262 words. $ The entire message buffer must reside in one data bank. $ The packets and message buffer may reside in the same bank or different banks. 5v4 3789 6651v100

Banking Considerations 5.3.2. ASCII COBOL Consider the following when using ASCII COBOL $ The entire message buffer must reside in one data bank. $ The packets and message buffer may reside in the same bank or different banks. 3789 6651v100 5v5

Appendix A Conventions for Naming Hosts A.1. Introduction Hosts can be local or remote. The local host is the system on which your program is running. A remote host is any system in the network, other than your local host. A.2. Host Identifiers Each host system has its own host identifier (host-id). To define a host-id, you can choose from two format types: $ Internet physical address This format is always valid for specifying a host-id. $ Logical host name This format is valid depending on how your site administrator configured the Telcon software. An internet physical address format host-id is: where n1 can range from 0 through 223, and n2 through n4 can range from 0 through 255. (n3 is currently always 0.) For example: Always include the dashes when you use this format. 3789 6651v100 Av1

Host Identifiers A domain name: $ Can be up to 255 characters $ Can include alphanumerics as well as the minus sign (-) and the period (.) For example: This particular logical name represents the geographical location and system number of the host. The logical name translates to the physical address of the host. So, if you define a logical name, you can then specify a host-id by using either the logical host name or the physical address. You use host-ids in some commands. If you omit a host-id in a command, the local host-id is assumed by default. You can obtain host-id information from your site administrator. Notes: 1. Non-OS 2200 hosts sometimes use periods rather than dashes in the physical address format host-id. However, all host-ids entered in TCP-IP commands must contain dashes. Using periods causes an error message. 2. Throughout this manual, when we refer to the local host, we are referring to the OS 2200 host. Av2 3789 6651v100

Appendix B Program-to-Program Example Subsections B.1 through B.3 contain an example of a program-to-program application. Example B-1 is the ASCII COBOL compile and collect stream for the primary program of the program-to-program application shown in subsection B.2. The example in subsection B.2 is the primary (sending) program, and the example in subsection B.3 is the secondary (receiving) program. B.1. Sample Program Run Streams Example B-1. ASCII COBOL Compile and Collect Stream for Primary Program 3789 6651v100 Bv1

Sample Program Run Streams Example B-2 is the UCS COBOL compile and link stream for the primary program of the program-to-program application shown in subsection B.2. Example B-2. UCS COBOL Compile and Link Stream for Primary Program Bv2 3789 6651v100

Primary (Sending) Program Example B.2. Primary (Sending) Program Example The following example is the primary (sending) program of a program-to-program application. The program: $ Lets you enter the the number of messages to send to the secondary program $ Attaches to DDP-PPC $ Opens a conversation with the secondary program $ Sends the number of messages requested when it receives an open-id, indicating that the connection with the secondary program is established $ Performs a close after the messages have been sent $ Signs off when a close-confirm is received $ Detaches from DDP-PPC If any errors are encountered, appropriate messages are displayed on the printer. Source Code Listing for Primary Program 3789 6651v100 Bv3

Primary (Sending) Program Example Bv4 3789 6651v100

Primary (Sending) Program Example 3789 6651v100 Bv5

Primary (Sending) Program Example Bv6 3789 6651v100

Secondary (Receiving) Program Example B.3. Secondary (Receiving) Program Example The following example is a secondary (receiving) program of a program-to-program application. The program: $ Attaches to DDP-PPC $ Performs an open passive and goes into a receive state to await an open active from a primary program $ Receives the open active request from the primary program $ Receives the number of messages sent $ Closes its side of the conversation $ Detaches from DDP-PPC If any errors are encountered, appropriate messages are displayed on the printer. Source Code Listing for Secondary Program 3789 6651v100 Bv7

Secondary (Receiving) Program Example Bv8 3789 6651v100

Secondary (Receiving) Program Example 3789 6651v100 Bv9

Secondary (Receiving) Program Example Bv10 3789 6651v100

Secondary (Receiving) Program Example 3789 6651v100 Bv11

Glossary A abort absolute To terminate a program or processor immediately due to an error, operator keyin, or command. An element type for an OS 2200 program file. An absolute element is an executable machine-language element produced by the OS 2200 collector or linker from relocatable elements or object modules. absolute element An element containing a complete program in executable form. alphanumeric character string A string that contains letters, digits, special characters, and the space character. American Standard Code for Information Interchange (ASCII) A standard character code set for use by data processing systems. It defines an eight-bit code for each character in a limited set characters. This character set includes graphic characters (such as uppercase and lowercase letters, and punctuation marks) and control characters (such as the line-feed and the start-of-entry characters). ASCII See American Standard Code for Information Interchange. ASCII COBOL The COBOL programming language used to write programs for the OS 2200 ASCII COBOL compiler (ACOB). ASCII COBOL conforms to American National Standards Institute (ANSI-1974) standards. Symbolic elements written in the COBOL language, then compiled by the ASCII COBOL compiler, produce relocatable elements that use the ASCII character code set. 3789 6651v100 Glossaryv1

Glossary C CCITT See Consultative Committee for International Telegraph and Telephone. checkpoint marker Coding used to indicate error recovery restart points in case of failure during data transmission. In an OSI environment, this is known as a serial point synchronization number. CMS 1100 See Communications Management System software. collect To use the OS 2200 collector (MAP processor) to process relocatable elements and produce absolute elements. Collect and map are used synonymously in OS 2200 documentation. collector The OS 2200 MAP processor, which processes relocatable elements and produces absolute elements. The collector is a component of the OS 2200 system control software. Communications Management System software (CMS 1100) An OS 2200 software product that provides communications and network capabilitiesfrom an OS 2200 system to a network or to local terminals and devices on the system. configuration The arrangement of a computer system or network as defined by the nature, number, and the chief characteristics of its functional units. The term may refer to a hardware or a software configuration. This can also refer to the devices and programs that make up a system, subsystem, or network. Consultative Committee for International Telegraph and Telephone (CCITT) An international advisory committee that proposes worldwide communications standards. D DCA DCP DDN See distributed communications architecture. See distributed communications processor. See defense data network. Glossaryv2 3789 6651v100

Glossary DDN 1100 See TCP/IP Application Services (TAS). DDP See distributed data processing. DDP-PPC See Distributed Data Processing Program-to-Program Communications software. DDP-PPC application A user-written program that uses DDP-PPC. defense data network (DDN) An X.25 public data network (PDN) that allows communication with other hosts using the transmission control protocol/internet protocol (TCP/IP). Originally defined for the data network of the United States Department of Defense. Distributed Communications Architecture (DCA) The proprietary architecture for Unisys computer systems; the Unisys network architecture that draws together all aspects of the communications products by defining a set of logical concepts and rules (protocols and interfaces). These guidelines are used in the design of hardware, software, and network products. distributed communications processor (DCP) A programmable communications processor hardware unit that executes Telcon and DCP operating system (DCP/OS) software and serves as a communications subsystem that provides connections between hosts in a network; a modular communications processor that can be tailored to the needs of a broad range of users who implement Unisys distributed communications architecture. It performs the network management function, rather than the host. distributed data processing (DDP) The capability for users at one computer system to execute programs and access files on other computer systems that are connected in the same network. Distributed Data Processing Program-to-Program Communications (DDP-PPC) software The OS 2200 software product that provides distributed data processing services for OS 2200 systems. It is the base product required on any OS 2200 system to execute any other OS 2200 software product that provides distributed data processing capability. domain name A descriptive, easy-to-use identifier that specifies the logical internet name of the local or remote domain. 3789 6651v100 Glossaryv3

Glossary E element Part of an OS 2200 program file that can be referenced by a unique name and type. There are four element types: symbolic, relocatable, absolute, and omnibus. error code A number that identifies a particular type of program error. The meanings of DDP-PPC error codes are in the Distributed Data Processing (DDP-PPC/DDP-FJT) Messages Reference Manual. H heterogeneous network A network comprised of hosts using different operating systems; in this case, both OS 2200 and non-os 2200 hosts. homogeneous network A network comprised of hosts using different operating systems; in this case, OS 2200 systems. host host-id A computer system, personal computer, or work station connected to a data transmission facility (a data transmission network in the case of DDP-PPC) that executes application or system programs on behalf of its users. The identifier for a local or remote host in the network, defined in the CMS configuration and specified in internet physical address format or in logical host name format. I interface (1) A facilityprovided by a software product to enable a computer user or program to use the product or exchange input and output with the product. (2) A hardware component that links two other hardware components; a portion of a hardware component where it links to another hardware component. International Standards Organization (ISO) The organization that established international standards for computer network architecture. ISO developed the OSI Reference Model, a seven-layered model for communications processing. internet The DoD network of host connections using the suite of TCP/IP protocols. Glossaryv4 3789 6651v100

Glossary internet physical address A host-id specified in a format that consists of a network number, a host number, and an interface message processor number, each separated by a hyphen or period. Often associated with a logical host name for ease of use. internet protocol (IP) One element of transmission control protocol/internet protocol (TCP/IP). Internet protocol (IP) is the standard used for sending the basic unit of data (an IP datagram) through a Defense Data Network (DDN) internet. See also transmission control protocol/internet protocol (TCP/IP). ISO See International Standards Organization. L LAN See local area network. Linking System (link) A component of the Universal Compiling System (UCS) that links separately compiled routines (object modules) so that they can execute as one program. The Linking System software also permits object modules to be executed in the UCS environment. local area network (LAN) A group of interconnected workstations and supporting devices with high-speed, short-range communications capability within the group. A Unisys USERNET system is an example of a local area network. A local area network can be part of a DDP-PPC network. local host The host to which you are physically attached. logical host name A descriptive, easy-to-use host-id that is associated with, and translates to, an internet physical address. For example, three hosts at a site in New York could be given the logical host names of NY01, NY02, and NY03. M 3789 6651v100 Glossaryv5

Glossary map (1) To transform a particular computer system s file structure and attributes to or from a common format, called a virtual file. This enables a computer system that has an OSI software product to send all or part of a file to another computer system that has an OSI software product. The receiving computer system can then manipulate this file to conform to its own file structure and attributes. (2) To use the OS 2200 collector (MAP processor) to process relocatable elements and produce absolute elements. Mapand collect are used synonymously in OS 2200 documentation. N network Two or more independent computers (hosts) that are logically or geographically separated and electronically linked by communications lines or data communications devices for the purpose of exchanging information. network definition statement (NDS) A formatted statement that names and defines a network entity for CMS 1100 or Telcon. CMS 1100 NDS and Telcon NDS formats are different. In older manuals, an NDS may be called a system configuration statement (SCS). O object module element An element containing part of a program in a form that is combined with other object module elements to produce an executable program (output object module element). An object module element is the output of a language processor and the input to a collection or linkage process. omnibus OSI An element type for an OS 2200 program file. Programmers specify an omnibus element type when absolute, relocatable, or symbolic is not appropriate. See Open Systems Interconnection. Open Systems Interconnection (OSI) A network architecture developed by the International Standards Organization (ISO) and other standards organizations that enables computers made by different companies to communicate with each other. Glossaryv6 3789 6651v100

Glossary P packet switching A data conversion routine usually used in public data networks to split a message into uniformly sized packets for transmission and restored at the destination to its original form. PDN protocol See public data network. A set of rules which controls network communication by defining the structure, content, sequencing procedures, and error detection and recovery techniques for data transmission. public data network (PDN) A network of line connections to various points furnished by a regulated carrier such as a telephone company. A communication network developed for the transmission of data and usually made accessible only to subscribers who share the network. Q qualifier A prefix for a file name on an OS 2200 system. An asterisk (*) character separates the qualifier and the rest of the file name. R relocatable element An element containing part of a program in relocatable binary form that is combined with other relocatable elements to produce an executable program (absolute element). A relocatable element is the output of a language processor and input to a collection process. remote host Any host in the network other than the one to which you are physically attached. run stream (runstream) A series of OS 2200 executive control language statements and any input, data, or programs associated with them. 3789 6651v100 Glossaryv7

Glossary S SDF session See system data format. A logical connection between two network-addressable units (termination systems, end users, and so forth) that can be activated, tailored to provide various protocols, and deactivated, as requested. The session activation request and response can determine options for the rate and concurrency of data exchange, the control of contention and error recovery, and the characteristics of the data stream. Sessions compete for network resources, such as the links within the path control network. source host The host that sends a file or records in any transfer operation. symbolic element An element type for an OS 2200 program file. A symbolic element can contain a source program or subprogram written in a programming language, directives to an OS 2200 software processor, executive control language statements, or input for a program or OS 2200 software processor. Symbolic elements contain text in system data format (SDF). Typically, OS 2200 text editors create symbolic elements. system data format (SDF) A sequential record format used by OS 2200 software for store data. SDF recognizes data records and control records. Data records contain the data (the text of a record, for example). Control records provide special control information about the data, such as line numbers, page, and size. Symbolic elements are assumed to use SDF. T TAS TCP/IP See TCP/IP Application Services. See transmission control protocol/internet protocol. TCP/IP Application Services (TAS) TCP/IP Application Services software. An OS 2200 software product that communicates with other hosts in an X.25 public data network (PDN) or in a local area network (LAN) using the transmission control protocol/internet protocol (TCP/IP), originally defined for the data network of the United States Department of Defense (DoD). This product was previously called DDN 1100. Glossaryv8 3789 6651v100

Glossary Telcon TIP A Unisys program product that is a distributed communications operating system for implementation of distributed communications architecture (DCA). The software resides and executes in a distributed communications processor (DCP). Transaction processing; allows the execution of transaction processing programs. These programs may be written in assembler language or in a high-level compiler language. OS 2200 TIP provides a general transaction processing capability that allows a remote terminal operator to initiate the execution of a preregistered program at the central computer site. Once in execution, the transaction program has access to the full capabilities of the OS 2200 executive system, as well as to the specialized capabilities and services of TIP. transmission control protocol/internet protocol (TCP/IP) Data transmission protocols originally defined for the United States Department of Defensedatanetwork. U UCS UDLC See Universal Compiling System. See universal data link control. Universal Compiling System (UCS) A set of OS 2200 software products that provide extended mode (virtual addressing) capability, a standardized system library, a linking system, compilers, and application development tools. UCS enables applications written in various programming languages to access the same files and databases. Universal Compiling System COBOL (UCS COBOL) An implementation of the COBOL programming language as defined by the X3.23 1985 American National Standard for use with the OS 2200 UCS COBOL compiler (UCOB). universal data link control (UDLC) The Unisys line control method for data transfer over communication lines. user name A 1- to 20-character name that identifies you on your host. 3789 6651v100 Glossaryv9

Glossary X X.25 public data network A packet-switched public data network that conforms to Consultative Committee for International Telegraph and Telephone (CCITT) standard X.25, which defines a protocol for communication between packet-switched public data networks and devices operating in packet-switched mode. Glossaryv10 3789 6651v100

Bibliography OS 1100 ASCII COBOL Programming Reference Manual (UP-8582). Unisys Corporation. OS 1100 Communications Management System (CMS 1100) Configuration Reference Manual (7830 9853). Unisys Corporation. OS 1100 Communications Management System (CMS 1100) Installation and Configuration Guide (7830 9846). Unisys Corporation. OS 1100/DCP Series Open Systems Communications Software Conceptual Overview (7831 5835). Unisys Corporation. OS 2200 Distributed Data Processing (DDP-PPC) DCA Interface C Language Programming Guide (3787 3254). Unisys Corporation. OS 2200 Distributed Data Processing (DDP-PPC/DDP-FJT) DCA Interface COBOL Programming Guide (3787 3510). Unisys Corporation. OS 2200 Distributed Data Processing (DDP-PPC/DDP-FJT) Messages Reference Manual (3787 3528). Unisys Corporation. OS 2200 Distributed Data Processing (DDP-PPC) OSI Interface C Language Programming Guide (3787 3288). Unisys Corporation. OS 2200 Distributed Data Processing (DDP-PPC) OSI Interface COBOL Programming Guide (3787 3296). Unisys Corporation. OS 2200 Distributed Data Processing (DDP-PPC) TCP/IP Interface C Language Programming Guide (4173 5127). Unisys Corporation. OS 2200 Distributed Data Processing (DDP-PPC) TCP/IP Interface FORTRAN Programming Guide (3789 6669). Unisys Corporation. OS 2200 Distributed Data Processing Program to Program Communications (DDP-PPC) Implementation and Administration Guide (3787 3270). Unisys Corporation. OS 2200 TCP/IP Application Services (TAS) COBOL Programming Guide (3787 3205). Previously titled Defense Data Network (DDN 1100) COBOL Programming Guide. Unisys Corporation. 3789 6651v100 Bibliographyv1

Bibliography OS 2200 TCP/IP Application Services (TAS) FORTRAN Programming Guide (3787 3247). Previously titled Defense Data Network (DDN 1100) FORTRAN Programming Guide. Unisys Corporation. OS 1100 Universal Compiling System (UCS) COBOL Programming Reference Manual (7830 0455). Unisys Corporation. Bibliographyv2 3789 6651v100