unisys ClearPath Enterprise Servers Communications Application Program Interface (COMAPI) User s Guide 8R2 September

Transcription

1 unisys ClearPath Enterprise Servers Communications Application Program Interface (COMAPI) User s Guide 8R2 September

2 NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such 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, 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. Notice to U.S. Government End Users: This software and any accompanying documentation are commercial items which have been developed entirely at private expense. They are delivered and licensed as commercial computer software and commercial computer software documentation within the meaning of the applicable acquisition regulations. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data rights clauses. Unisys and other Unisys product and service names mentioned herein, as well as their respective logos, are trademarks or registered trademarks of Unisys Corporation. All other trademarks referenced herein are the property of their respective owners.

3 Contents Section 1. An Overview of Communications Application Program Interface (COMAPI) 1.1. COMAPI Components Background Run Communication Protocols Supported Key Features of COMAPI Simple Procedure Calls Improved Data Transfer Efficiency Conversational Mode Transactions Simple Configuration of Multiple Applications Features not Supported by COMAPI Relationship between COMAPI and Communication Services Relationship between COMAPI and Communications Interface for Transaction Applications (CITA) New Features in COMAPI Level 8R COMAPI Operator Command Timestamps Section 2. Setting Up the COMAPI Components 2.1. COMAPI Release Tape Process Overview Generating COMAPI Updating the COMAPICALLER library module Specifying File Security Installing COMAPI Additional Installation Modes Setting Security Privileges for COMAPI Privileges Required for -COMAPI Configuring the COMAPI COMAPI Configuration File or Element COMAPI Configuration Statements Configuring COMAPI in Communication Services CMS1100/CPComm Migration Section 3. Managing the Background Run 3.1. Starting the Background Run Network Administrator Privileges Starting the Background Run with a Processor Call iii

4 Contents 3.2. Terminating the Background Run Using a System E Keyin User Commands to the Background Run ABORT Command BRKPT Command DUMP Command ENTITY Command ERROR Command HELP Command LOG Command STATUS Command STATUS ACTIVITY Command STATUS IA Command STATUS MULTICAST Command STATUS PORTS Command STATUS RUNS Command STATUS SOCKETS Command TERM Command Section 4. Designing Your Application 4.1. Key Concepts Communications Options for Transaction Applications Session Tables LRCT Blocking and Nonblocking Modes COMAPI Support for Programming Languages Other Than COBOL Setting the Correct Values for COBOL Parameters (Copy Element) Considerations for Acquiring and Releasing Queue Banks Using Special COMAPI Features Using a Proxy Listener for a Group of Session Tables Inheriting a Connection Application-to-Application Data Transfers Sessions Shared Among Activities Multicast Programming SSL/TLS Protocols Over TCP/IP Linking Your Program Calling COMAPI Directly Calling COMAPI Using the BSD/UNIX Socket Library Calling COMAPI Using the Call Router Handling Contingencies Handling Session Events Recovering from Errors Using DEBUG Mode iv

5 Contents Section 5. TCP Calls 5.1. TCP_ACCEPT Accepting Connect Requests TCP_BEQUEATH Passing Ownership of the Connection TCP_BORROWQB Acquiring a Queue Bank TCP_CHGSECURITY Changing Security of a Connection TCP_CLOSE Releasing a Session Table TCP_CONNECT Establishing a Connection with a Peer Application TCP_DEREGISTER Disconnecting from COMAPI TCP_DISCONNECT Terminating the Connection with the Peer TCP_EVENT Passing an Event to a Session Table TCP_GETCERT Getting the Certificate of a Connection TCP_GETHOSTNAME Getting Remote Peer Name TCP_GETOPTS Retrieving Options for a Session Table TCP_GETREMIP Getting IP Addresses for a Remote Peer TCP_INHERIT Accepting Ownership from another Activity or Run TCP_LISTEN Establishing a Listen for OPEN Requests TCP_QBRECEIVE Accepting the Data in a Queue Bank TCP_QBRECVALL Accepting All Outstanding Data and Events TCP_QBREPLY Sending the Data in a Queue Bank to a Connection Not Owned by this Application TCP_QBSEND Sending the Data in a Queue Bank TCP_RECEIVE Accepting Data from the Peer TCP_REGISTER Registering an Application for TCP Sessions TCP_REPLY Sending Data to a Connection Not Owned by This Application TCP_RESCIND Rescinding a Listen TCP_RESUME Resuming Input from the Peer Application TCP_RETURNQB Returning a Queue Bank TCP_SELECT Selecting the Status of Certain Sessions TCP_SEND Sending Data TCP_SESSION Acquiring a Session Table TCP_SETOPTS Setting Options for a Session Table TCP_STOP Stopping Input from the Peer Application v

6 Contents Section 6. UDP Calls 6.1. UDP_CLOSE Releasing a Session Table UDP_DEREGISTER Disconnecting from COMAPI UDP_EVENT--Passing an Event to a Session Table UDP_GETHOSTNAME Getting the Remote Peer Name UDP_GETMSGSIZE Finding the Maximum Message Size UDP_GETOPTS Retrieving Options for a Session Table UDP_GETREMIP Getting IP Addresses for the Remote Peer UDP_GETSOURCE Retrieving Filter Options for a Socket UDP_LISTEN Establishing a Listen on a Port UDP_PROBLEMS Notifying Communication Services about Problems Sending Data UDP_QBRECEIVE-Accepting the Data in a Queue Bank or a Chain of Queue Banks UDP_RECEIVE Accepting Data from the Peer UDP_REGISTER Registering an Application for UDP Sessions UDP_REPLY Sending a Reply to a Request for Information UDP_RESCIND Rescinding a Listen UDP_SELECT Selecting the Receive Status of Certain Sessions UDP_SENDTO Sending Data UDP_SESSION Acquiring a Session Table UDP_SETOPTS Setting Options for a Session Table UDP_SETSOURCE Setting Filter Options for a Socket Section 7. COBOL Program Examples 7.1. Example 1: Using UDP_REPLY to Respond to Input Data Example 2: Using TCP_REPLY to Respond to Input Data Example 3: Using TCP_INHERIT to Inherit a Connection Section 8. Diagnostics and Troubleshooting 8.1. Using the SSDA Processor Analyzing a Dump Creating a Snapshot Dump and Performing the Analysis Using the DUMP Program Dump Analysis Commands vi

7 Contents 8.3. Using the TCP/IP RFC SERVER Echo Capabilities (Port 7) Print Generation Capabilities (Port 19) SERVER Commands Reporting a Software Problem to Unisys Submitting Documentation Corrections and Comments to Unisys Section 9. BSD/UNIX Socket Library 9.1. Socket Identifier Error Returns Header Files of Network Addresses IPv4 address format IPv6 address format Initial Timeout Values Socket Function Calls Supported accept bind closesocket connect getaddrinfo gethostbyaddr gethostbyaddr_r gethostbyname gethostbyname_r gethostname getnameinfo getpeername getsockname getsockopt getsourcefilter inet_addr inet_ntoa inet_ntop inet_pton ioctlsocket listen recv recvfrom recvmsg selectsocket send sendmsg sendto SetSockLibDebug setsockopt setsourcefilter shutdown socket vii

8 Contents socketpair WSAStartup WSACleanup WSAGetLastError and WSAGetLastErrorAux Queue Bank Calls qballoc qbfree qbrecv qbsend Data ting across Multiple Hardware Platforms htonl htons ntohl ntohs shtonl shtons sntohl sntohs Socket Function Calls to Support Unique COMAPI Functionality bequeathsocket inheritsocket tcp_event tcp_register udp_event udp_register Socket Function Calls Provided But Not Supported Linking Your Program Appendix A. COMAPI Status Codes Index... 1 viii

9 Figures 1 1. COMAPI Components TCP Socket State and Event Diagram ix

10 Figures x

11 Tables 2 1. COMAPI Release Tape Installation Modes Required Console Privileges LRCT Version 0 Attributes LRCT Version 1 Attributes Application Program Interface Definition Elements Session Table Values Multicast TTL Session Events TCP Calls The Effect of linger_on and linger_time General Session Table Options TCP OPEN Request Values UDP Calls UDP Options Socket Function Calls Queue Bank Calls Data ting Calls Socket Function Calls for Unique Functionality A 1. COMAPI Status Codes... A 2 A 2. COMAPI Typical Auxiliary Statuses for Communication Services Errors... A xi

12 Tables xii

13 Section 1 An Overview of Communications Application Program Interface (COMAPI) Communications Application Program Interface (COMAPI) is a combined extended mode shared subsystem and background run that allows applications to access a communications network. Purpose of This Guide This guide provides task-oriented procedures and reference information for software engineers who need to develop applications that use the services of the COMAPI. Documentation Updates This document contains all the information that was available at the time of publication. Changes identified after release of this document are included in problem list entry (PLE) To obtain a copy of the PLE, contact your Unisys representative or access the current PLE from the Unisys Product Support Web site: Note: If you are not logged into the Product Support site, you will be asked to do so. Section Overview This section presents an overview of COMAPI components Communications protocols supported by COMAPI COMAPI key features The relationship of COMAPI to your Communication Services product, which is Communications Platform (CPComm) or the Communications Platform for Open Systems (CPCOMMOS)

14 An Overview of Communications Application Program Interface (COMAPI) The relationship of COMAPI to Communications Interface for Transaction Applications (CITA) New features in COMAPI 8R2 Notation Conventions This guide uses the following notation conventions. Convention Description lowercase italic constant width UPPERCASE Names of variables to which you must assign values appear in lowercase italics. Computer dialog, both input and output, appears in constant width type. Uppercase font indicates items for which you must choose one of the values shown. For example, given ON OFF, you must enter either ON or OFF. Uppercase font is also used for command and keyword formats. However, you can enter any of these items in either uppercase or lowercase fonts. [ ] Brackets indicate optional fields or subfields. { } Braces enclose two or more fields or subfields and indicate that you must select exactly one of the fields or subfields shown. A vertical line separates exact choices. For example, ON OFF indicates a choice of on or off; and HIGH MEDIUM LOW represents a choice of high, medium, or low COMAPI Components COMAPI provides a new environment and sockets-like interface for application programs. It can handle either Transmission Control Protocol (TCP) or User Datagram Protocol (UDP) connections; and with Communications Interface for Transaction Applications (CITA), it can schedule Transaction Processing (TIP) using the Message Control Bank (MCB) (refer to Figure 1 1). COMAPI consists of two components: The COMAPI shared subsystem A background run that owns all connections to the network

15 An Overview of Communications Application Program Interface (COMAPI) Background Run Figure 1 1. COMAPI Components The background run is integral to COMAPI functionality. It owns all connections to the network and works on behalf of your applications to access Communication Services. Multiple Activities from a Single Activity Application A primary benefit of the COMAPI background run is that it can perform multiple functions for a single activity program. For example, in the case of the TCP_CONNECT call, which establishes a connection between your application and a peer application, the background run synchronizes the send and receive function calls that would normally be required through Communication Services. Your application makes a single call, and the background run performs multiple tasks as a result of that call

16 An Overview of Communications Application Program Interface (COMAPI) Output Flow Control Event Logging The background run also handles basic flow control of output and eliminates the need to pace outputs to match the speed of the network. This is accomplished by suspending your program activity when a network blockage occurs and restarting the activity when Communication Services accepts the current output. The background run creates and maintains a log file that contains entries describing unusual events. It also makes entries in the log file on behalf of your application when you request tracing of your connections. Refer to the description in for more information on tracing Communication Protocols Supported COMAPI accesses communications networks through Communication Services. COMAPI supports the following communication protocols: Network Layer Services Internet Protocol (IP), a connectionless network protocol that moves data through multiple network nodes (defined by RFC 791 and RFC 1122) Internet Control Message Protocol (ICMP), a protocol within the Internet layer that enables error messages to be transported to upper layer protocols on behalf of lower-layer protocols (defined by RFC 792, RFC 1122, and RFC 1577) Transport Layer Services Transmission Control Protocol (TCP), a connection-oriented transport protocol (defined by RFC 793 and RFC 1122) User Datagram Protocol (UDP), a connectionless transport protocol (defined by RFC 768 and RFC 1122) 1.3. Key Features of COMAPI This subsection introduces the key interface features of COMAPI Simple Procedure Calls COMAPI provides a set of program-callable procedures that allow applications to access Communication Services. By providing application programmers with a set of basic commands such as LISTEN, CONNECT, SEND, RECEIVE, and DISCONNECT, COMAPI simplifies the task of accessing Communication Services. Application programs must be modified to make the new calls that interface with COMAPI

17 An Overview of Communications Application Program Interface (COMAPI) Improved Data Transfer Efficiency The interface of COMAPI offers improved data transfer efficiency by decreasing the number of hand-offs between different components in the transaction environment. Instead of using position identifiers (PID) to identify TIP end users, COMAPI passes a unique identifier, a socket ID, to the transaction. This socket ID is then used for all subsequent communication with the peer. Transactions using this feature do not use the MCB to send output. Instead a new, simple command calls upon the COMAPI subsystem to perform the output. This bypasses all of the Exec step control and the MCB path on output. Because COMAPI does not rely on the Exec or the MCB to pass data to a peer, path lengths for data output are greatly shortened. However, no data recovery is available unless the application itself provides recovery. Path lengths for both input and output can be drastically reduced when COMAPI uses Communication Services to access the network. If the Communication Services queue bank feature is called correctly, data is never moved for output and need not be moved on input. Instead, the applications merely pass pointers that specify where data is located Conversational Mode Transactions COMAPI provides a conversational mode for TCP/IP connections. Rather than sending just one request per session, transactions can now create conversational loops using the SEND and RECEIVE calls. This allows longer transaction times than were previously possible in CMS Moreover, the transaction environment is maintained during this conversation with no conscious effort on the part of the application programmer. Although Communication Services do provide a conversational mode, it is more complicated than the exchanges handled by COMAPI. Communication Services conversations require that a new transaction be started for each input of a conversation, which means that the previous transaction environment must be saved and then restored for each new input in the conversation Simple Configuration of Multiple Applications Multiple applications that normally must be configured individually in Communication Services using the PROCESS configuration statement can run through COMAPI with no configuration requirements in Communication Services. Once COMAPI is configured in Communication Services, it handles all interaction between your applications and the communications interface

18 An Overview of Communications Application Program Interface (COMAPI) Features not Supported by COMAPI COMAPI does not provide Demand mode traffic handling A COMPOOL interface An access list feature (although the user application might retrieve the peer IP address and port number to perform security checks in the application) 1.4. Relationship between COMAPI and Communication Services Communication Services represents either Communications Platform (CPComm) or Communications Platform for Open Systems (CPCommOS). With COMAPI configured to use OS 2200 services, you no longer need to configure applications individually in Communication Services. Instead, you now configure your applications to use COMAPI, which is itself configured in Communication Services, and the background run handles the send and receive loops. This eliminates the problem of running out of space for your programs in Communication Services. Regardless of the number of your applications that make use of COMAPI services, only COMAPI needs to be known to Communication Services Relationship between COMAPI and Communications Interface for Transaction Applications (CITA) CITA uses COMAPI to accept incoming data or connections and pass them to TIP applications using the MCB interface. CITA allows you to listen for incoming data using Communication Services. COMAPI 5R5 and earlier versions included a program named CAS that provided an interface between COMAPI and TIP. CAS is no longer provided with COMAPI. CITA includes the capability provided by CAS and more. Refer to the CITA Configuration and Operations Guide for more information, including how to configure CITA as a replacement for CAS. CITA allows the user to configure a header that defines the length of a message within the incoming byte stream. This feature replaces the functionality provided by RFC 1006, TP0, and TELNET/INT1 in CMS 1100 and Communications Platform/SILAS. If you do not use CITA, you need to develop an equivalent application if you wish to interface with the TIP environment

19 An Overview of Communications Application Program Interface (COMAPI) 1.6. New Features in COMAPI Level 8R COMAPI Operator Command Timestamps This feature adds a timestamp to a prepended existing message that echoes the input command string and the siteid of the user issuing the command. This information is placed in the COMAPI run's PRINT$ file and in the COMAPI LOG file. Time stamping provides a useful debugging aid by helping analysts find the operator command output in a PRINT$ file based on the time the command was issued

20 An Overview of Communications Application Program Interface (COMAPI)

21 Section 2 Setting Up the COMAPI Components This section explains how to perform the following tasks to set up the COMAPI components: Description Determine the files contained on the COMAPI release tape Determine the installation requirements and steps for setting up COMAPI software Subsection Reference Generate COMAPI with COMUS 2.3 Install COMAPI with SOLAR 2.4 Set Security Privileges for COMAPI 2.5 Create a configuration file or element for the COMAPI subsystem and background run 2.6 Configure COMAPI in Communication Services

22 Setting Up the COMAPI Components 2.1. COMAPI Release Tape The COMAPI software release tape contains the files in Table 2 1 in COPY, G format. Table 2 1. COMAPI Release Tape File Name Description 1 CO$UTIL Contains the following elements: The background run s program execution absolute element COMAPI The shared subsystem absolute element COMAPIFGSS INS-MODES execution element UCS header elements The executable elements DUMP-TCP, DUMP-UDP, DUMP, and SERVER The COMAPI execution runstream - STCOMAPI The SOLAR installation elements 2 ADDA Elements specific to a mode A installation. The file is added to the install file, SYS$LIB$*COMAPI. 3 ADDB Elements specific to a mode B installation. The file is added to the install file, SYS$LIB$*COMAPI$B. 4 ADDC Elements specific to a mode C installation. The file is added to the install file, SYS$LIB$*COMAPI$C. 5 ADDD Elements specific to a mode D installation. The file is added to the install file, SYS$LIB$*COMAPI$D. 6 COMAPILIB The COMAPI library file that contains the element CBEP$COMAPI for mode A. 7 COMAPILIBB The COMAPI library file that contains the element CBEP$COMAPI for mode B. 8 COMAPILIBC The COMAPI library file that contains the element CBEP$COMAPI for mode C. 9 COMAPILIBD The COMAPI library file that contains the element CBEP$COMAPI for mode D. 10 TOOLS Contains the following for use with COMAPI mode A: The COMAPI CALLER library module MCB header elements: MCB/H, MCBDEFCOPY/H Example COBOL programs that use COMAPI 11 TOOLB Contains the same elements as the TOOLS file, for use with COMAPI mode B. 12 TOOLC Contains the same elements as the TOOLS file, for use with COMAPI mode C. 13 TOOLD Contains the same elements as the TOOLS file, for use with COMAPI mode D

23 Setting Up the COMAPI Components Table 2 1. COMAPI Release Tape File Name Description 14 BASE The base symbolics file 15 PCF The permanent corrections file 16 RESULTS Compiled elements 2.2. Process Overview The following table lists the tasks involved in setting up the COMAPI software. It is recommended that you perform the steps in the order listed. However, note that some of the steps are optional. Step Task Required? Subsection Reference 1 Generate COMAPI with COMUS. Required only if you need to incorporate site-developed code or code corrections from Unisys Install COMAPI with SOLAR. Always required Set security privileges Always required Create a configuration file or element for the COMAPI subsystem and background run. 5 Add a PROCESS statement to the CPCOMM configuration for COMAPI. Always required 2.6. Always required Generating COMAPI If you need to apply changes to COMAPI, you must generate the software with COMUS. These are the modifications you can make to COMAPI by generating it. Site-developed code: User-written software that supplements COMAPI or replaces part of it Unisys-supplied corrections: Code fixes to resolve problems with the COMAPI software The SO file and the build print file are written to the build output tape. If you want to retain the previous handling of the SO file and print file, you can use the COMUS CO$ADDSTATEMENTS SGS, entered as a permanent or an additional SGS in the COMAPI COMUS build

24 Setting Up the COMAPI Components Example CO$ADDSTATEMENTS BEFORE-SAVE,ADDTHIS ADDTHIS SO.,<your-file.>" CO$ADDSTATEMENTS BEFORE-SAVE,ADDTHIS ADDTHIS COMAPI$PRT$.,,<print-queue>" To generate COMAPI with modifications, use the procedure described in the COMUS End Use Reference Manual. If you do not need to make any modifications, you can install COMAPI as you received it on the release tape Updating the COMAPICALLER library module If you intend to use the INS-MODES utility to install modes other than mode A and mode B, you can use the following additional SGS during the COMUS generation. (You also can enter this information with the INS-MODES utility when the additional modes are installed). This SGS creates an updated COMAPICALLER library module that can be used for call routing. See for a description of call routing. The format of the SGS is MODES-BDIS letterbdi[,..., letterbdi] where: letter bdi designates an installation mode. It is a single letter from the set {C...Z}. is specified as 020xxxx, where xxxx is four octal digits, representing the application-level BDI of the COMAPI gate bank for the installation mode. Each subfield, consisting of a mode letter and bdi, must be entered together as a single string, without a space or comma between them. The subfields can appear in any order. Multiple SGSs can be given to specify all 24 possible BDIs (for modes C through Z). An example of this SGS is MODES-BDIS J ,Z

25 Setting Up the COMAPI Components Specifying File Security When the COMAPI runstream is started, and when the COMAPI program is running, certain files are cataloged. These files include the runstream print file, the log files, and the diagnostic and dump files. You can specify whether access to the files is public or private. Use the following additional SGS during the COMUS generation. (You also can make this choice with the INS-MODES utility when the additional modes are installed). The format of the SGS is FILESECURITY {PUBLIC PRIVATE} where: PUBLIC specifies that the P option is used on statements, so that files are cataloged with public access. PRIVATE specifies that the P option is absent on statements, so that files are cataloged with private access. An example of this SGS is FILESECURITY PUBLIC In the absence of this SGS, all files are cataloged PRIVATE

26 Setting Up the COMAPI Components 2.4. Installing COMAPI You must use SOLAR to install COMAPI. COMAPI has four installation modes provided by Unisys: mode A, B, C, and D. During the installation process, SOLAR creates the following files on your system from the Unisys provided tape: Table 2 2. Installation Modes Mode A SYS$LIB$*COMAPI SYS$LIB$*COMAPI$LIB SYS$LIB$*RUN$.STCOMAPI SYS$LIB$*COMAPI$TOOLS Mode B SYS$LIB$*COMAPI$B SYS$LIB$*COMAPI$LIB$B SYS$LIB$*RUN$.STCOMAPI-B SYS$LIB$*COMAPITOOL$B Mode C SYS$LIB$*COMAPI$C SYS$LIB$*COMAPI$LIB$C SYS$LIB$*RUN$.STCOMAPI-C SYS$LIB$*COMAPITOOL$C Mode D SYS$LIB$*COMAPI$D SYS$LIB$*COMAPI$LIB$D SYS$LIB$*RUN$.STCOMAPI-D SYS$LIB$*COMAPITOOL$D Refer to the Software Products Installation Guide for more information about installing products with SOLAR Additional Installation Modes In addition to the Unisys supplied modes A through D, COMAPI allows you to install modes C through Z by using a utility called INS-MODES. INS-MODES streamlines the build and installation process, allowing you to make a copy of a COMAPI mode and install it as mode n, where n is a single letter C through Z. There is overlap for modes C and D to support users having their own BDIs for modes C and D from previous levels of The P option specifies that files cataloged by the COMAPI product have PUBLIC access. This is analogous to using the FILESECURITY PUBLIC SGS at COMUS generation time. If the P option is not specified, all files have PRIVATE access

27 Setting Up the COMAPI Components Operation When you execute this command, INS-MODES queries for The name of the COMAPI file to be used as the source for the SOLAR installation. The COMAPI file must be the installed file SYS$LIB$COMAPI or SYS$LIB$COMAPI$B, or the first file from the COMAPI product tape. The letter of the mode (C through Z) you want to install for COMAPI. Each installation mode must be unique. For example, if mode G is already installed, and you specify G, the existing installed mode G is replaced by the new mode G. The user BDI for the COMAPI subsystem for the mode being installed. The mode letters and associated BDIs for all COMAPIs installed on your system. The format of the input is described when this prompt appears. This information is used to generate a customized COMAPICALLER call router library module. See for use of the call router. INS-MODES makes a copy of the input file and modifies some elements, compiles and links these elements, and creates new installation files. INS-MODES then calls SOLAR and installs the new installation files. When the SOLAR installation finishes successfully, the following message appears: The SOLAR install of COMAPI was successful. If an installation error occurs, the following message appears: The SOLAR install of COMAPI has failed. Please check the file, DIAG.PL-DIAGINFO/datetime for a description of the error(s). INS-MODES creates the following files: SYS$LIB$*COMAPI$n. SYS$LIB$*COMAPI$LIB$n. SYS$LIB$*COMAPITOOL$n. SYS$LIB$*RUN$.STCOMAPI-n where n is an alpha character in the range C through Z, indicating the installation mode Setting Security Privileges for COMAPI This subsection describes the security requirements for COMAPI. You use Apex, the Site Management Complex (SIMAN), or Security Administration (either the command line processor SECMGR or the Security Client) to assign security privileges. Refer to the Software Products Installation Guide for detailed information about installing products with Object Module Subsystems

28 Setting Up the COMAPI Components Privileges Required for -COMAPI- The user-id that owns the COMAPI protected fixed-gate shared subsystem (-COMAPI-) must have the privileges listed for COMAPI in Appendix A of the Software Products Installation Guide Configuring the COMAPI COMAPI Configuration File or Element The COMAPI configuration consists of system data format (SDF) ASCII images in a data file or symbolic element. You can create the configuration file or element with any text editor that creates SDF images, including most OS 2200 editors. See Section 3 for detailed information on suggested file names. The configuration must be supplied when starting COMAPI, refer to Section 3.1.2, Starting the Background Run with a Processor Call. COMAPI does not keep the configuration file assigned after it has started; consequently, the file might get rolled out by the next time COMAPI is restarted. You can prevent the file from being rolled out by cataloging the file with the V option, by modifying your file archiving rules, or by periodically assigning the file COMAPI Configuration Statements The configuration file can include any of the following statements. The configuration must include a CPCOMM statement. ADMIN Statement ADMIN [KEYIN,keyin-name] ; [MAX-TCP-BUFFERS,number] ; [MAX-UDP-BUFFERS,number] ; [MAX-TCP-SESSIONS,number] ; [MAX-UDP-SESSIONS,number] ; [MAX-TCP-USERS,number] ; [MAX-UDP-USERS,number] ; [VERIFY-TERM-COMMANDS,{YES NO}] KEYIN,keyin-name Keyin-name is registered with the EXEC using ER KEYIN$. The keyin-name can be up to 8 characters from the set {asterisk, alphabetic, numeric} and the first character cannot be numeric. Default: APIn, where n is an alpha character in the range A through Z, indicating the installation mode. If keyin-name is specified, both keyin-name and * run-id are registered with the EXEC. If keyin-name is the special keyword GENRUNID, only the run-id (without the preceding asterisk) is registered with the EXEC. If the keyin-name is not

29 Setting Up the COMAPI Components specified, both APIn and * run-id are registered with the EXEC. See Section 3 for a complete list of COMAPI user commands. MAX-TCP-BUFFERS,number This parameter determines the number of data buffers in the TCP pool that are available to use for data transfers between the application user and the background run. Because these buffers do not have a very long existence time, there is no need for many buffers. However, there might be a problem if many application programs are receiving data simultaneously and are slow to take this data from the queue. In this case, the application displays a status return of API- NO-BUFFERS on a TCP_RECEIVE call, and input data is lost. If this is a regular occurrence, there may be a need to restart COMAPI with more data buffers configured. Range: 10 1,000 Default: 200 MAX-UDP-BUFFERS,number This parameter determines the number of data buffers in the UDP pool that are used when data is transferred between the application and the background run. Because these buffers do not have a very long existence time, there is no need for many buffers. However, there might be a problem if many application programs are receiving data simultaneously and are slow to take this data from the queue. In this case, the application displays a status return of API-NO-BUFFERS on a SENDTO or RECEIVE call, and input data is lost. If this is a regular occurrence, there may be a need to restart COMAPI with more data buffers configured. Range: 10 1,000 Default: 200 MAX-TCP-SESSIONS,number This parameter restricts the number of TCP sessions in use to the configured value. If a CALL is made to TCP_SESSION and there are no more session tables available, a status of API-NO-BUFFERS is returned to the application program. Range: ,000 Default: 50,000 MAX-UDP-SESSIONS,number This parameter restricts the number of UDP session tables in use to the assigned value. If the application makes a UDP_SESSION call and there are no session tables available, a status of API-NO-BUFFERS is returned to the application. Range: ,000 Default: 10,

30 Setting Up the COMAPI Components MAX-TCP-USERS,number This parameter restricts the number of activities using TCP sessions to the assigned value. If a CALL is made to TCP_REGISTER and there are no more activity identifiers available, a status of API-NO-BUFFERS is returned to the application program. Range: 10 32,000 Default: 1,000 MAX-UDP-USERS,number This parameter restricts the number of activities using UDP sessions to the assigned value. If a CALL is made to UDP_REGISTER and there are no more activity identifiers available, a status of API-NO-BUFFERS is returned to the application program. Range: 10 32,000 Default: 1,000 VERIFY-TERM-COMMANDS,{YES NO} Specifies whether commands that terminate COMAPI (ABORT, ERROR, and TERM) should be confirmed to prevent the accidental termination of COMAPI. If the value is YES, the operator or administrator must enter the termination command twice within 2 minutes. (A warning message is displayed after the first command.) If the value is NO, COMAPI terminates the first time the command is entered. Default: NO CPCOMM Statement CPCOMM,mode NAME,process-name PASSWORD,password Use this statement to configure COMAPI to attach to Communication Services. The mode parameter specifies the mode of Communication Services to which COMAPI should attach. The possible values are MODE-A, MODE-B, MODE-C, MODE-D, MODE-E, MODE-F, MODE-G, MODE-H. Note: The mode you configure must be installed on your system or a COMAPI error occurs. The process-name and password parameters must match the values on the PROCESS statement for the COMAPI process in the Communication Services configuration

31 Setting Up the COMAPI Components ENTITY Statement The ENTITY statement configures COMAPI logging for a specific entity or set of entities. General logging is set to OFF. There are four formats for the ENTITY statement. You can have one ENTITY statement of each format in your configuration. You can change the configured ENTITY values at run time with the ENTITY user command. COMAPI makes a log entry only when the log entry information matches any of the entities specified on any of the four formats. Entity logging and general logging are mutually exclusive. If a LOG statement appears in the configuration, it must be LOG OFF. 1 ENTITY IA,[ip-address],[port-number] ; [IA,[ip-address],[port-number] ; IA,[ip-address],[port-number] ; IA,[ip-address],[port-number]] where: ENTITY IA limits the logging to specific sockets that use the specified address, domain-name, and/or port-number. You can specify a maximum of four IA entities on one ENTITY statement. At least one parameter must be specified. ip-address is IPv4 address, IPv6 address, or 0. If address is not specified, all addresses that match the port-number are used. port-number must be a number from 0 to If port-number is not specified, all port numbers that use the specified address are used. 2 ENTITY PROGRAM,program-name where: ENTITY PROGRAM limits the logging to a specific program. program-name is a maximum of 12 alphanumeric characters plus the hyphen (-) and the dollar sign ($)

32 Setting Up the COMAPI Components 3 ENTITY RUN,runid where: ENTITY RUN runid limits the logging to a specific runid. a maximum of six alphanumeric characters is valid. 4 ENTITY SOCKET,socket-id[,socket-id,socket-id,socket-id] where: ENTITY SOCKET limits the logging to a specific socket-id or a maximum of four socket-ids. socket-id LOG Statement is an octal (leading zero) or decimal number with a prefix of T for TCP or U for UDP. Socket-id can range from 1 to MAX_SESSIONS_TCP or MAX_SESSIONS_UDP. The value from the comapi-session parameter on any COMAPI API call can also be used. The LOG statement configures the COMAPI logging level. Use this statement with caution, because logging affects the performance of the system and COMAPI. Entity logging and general logging are mutually exclusive. If both an ENTITY and a LOG statement appear in the configuration, the LOG statement must be LOG OFF. LOG {OFF LOW MEDIUM HIGH} where: Value OFF LOW MEDIUM HIGH Description COMAPI logging is OFF. This is the default. Sets only general logging to ON. Sets general logging and API logging to ON. Sets general logging and API, RCV, and SEND logging to ON

33 Setting Up the COMAPI Components Value Description General API RCV SEND Logs entries for all users, similar to debug logging for specific users as described in section 4.5.3, Using DEBUG Mode. Logs every user call entry and exit into COMAPI. Logs every receive into COMAPI from the communications products. Logs every send from COMAPI to the communications products Configuring COMAPI in Communication Services To use COMAPI with Communication Services, you must configure COMAPI as a process by including the following statement in the CPComm configuration: PROCESS,process-id PASSWORD,password ; INPUT-QUEUE-THRESHOLDS,50,1000, where process-id and password match the corresponding fields on the CPCOMM statement in the COMAPI configuration (see 2.6.2). Note that the INPUT-QUEUE- THRESHOLDS parameters are essential for effective flow control between COMAPI and Communication Services. Examples: COMAPI Configuration Statement CPCOMM,MODE-A NAME,COMAP1 PASSWORD,COMAP1 CPCOMM Configuration Statement PROCESS,COMAP1 PASSWORD,COMAP1 INPUT-QUEUE-THRESHOLDS,50,1000, CMS1100/CPComm Migration Extra install modes of CPComm (e.g., CMSA-CPCA) allow you to keep legacy application programs that call CMS1100, and route their calls to CPComm. COMAPI also contains legacy calls to CMS1100 as well as calls to CPComm, and allows COMAPI application programs to choose the CMS1100 or CPComm destination via the INTERFACE cell in the LRCT. If you still have a CMS1100 statement in your COMAPI configuration because you have installed one of the CMS1100/CPComm migration modes of CPComm and you also have a CPCOMM statement in your COMAPI configuration, the process names in the NAME fields of the two statements must be different. The reason is: If the CMS1100 migration routes API calls to the same CPComm named on the CPCOMM configuration statement, COMAPI cannot detect that CMS1100 calls and CPComm calls are arriving at the same CPComm

34 Setting Up the COMAPI Components If the CMS1100 migration routes API calls to a different CPComm, no further consideration is necessary. If the CMS1100 migration routes API calls to the same CPComm, a situation may develop where unnecessary duplication of effort is made to establish connections, due to COMAPI s calls through both interfaces. You can use the CPComm migration feature to segregate access to networks driven by a single CPComm. In CPComm, configure the Process named on COMAPI s CPCOMM statement, and also configure the Process named on COMAPI s CMS1100 statement. The two Processes can then be restricted to separate networks by specifying the Process names on separate IP statements. See the Communications Platform Configuration and Operations Guide for details

35 Section 3 Managing the Background Run The COMAPI background run, which is installed as part of the SOLAR installation of COMAPI, acts as an interface between the application user and the network. It uses Communication Services to access the network. This section explains how to manage the COMAPI background run by performing the following tasks: Task Command to the Background Run Subsection Start the background run 3.1 Terminate the background run with a system E keyin Terminate the background run immediately with a subsystem dump only Close the current COMAPI breakpointed print$ file and start a new one Create a snapshot dump of the COMAPI subsystem 3.2 ABORT 0 BRKPT DUMP Control Entity logging. ENTITY Terminate the background run with diagnostics. Display description of COMAPI user commands. ERROR HELP Control COMAPI logging. LOG Check the status of the background run. List all sockets owned by a given activity. List the sockets whose LRCTs match a supplied IPv4 or IPv6 address, domain-name, and/or port number. STATUS STATUS ACTIVITY STATUS IA

36 Managing the Background Run Task Command to the Background Run Subsection List multicast IPv4 or Ipv6 addresses that are listening or sockets that are listening on a specific address. List port numbers that are in use by COMAPI or sockets that are using a specific port. List runs that are registered with COMAPI or activities for a specific run. STATUS MULTICAST STATUS PORTS STATUS RUNS List the status of a specific socket. STATUS SOCKETS Terminate the background run without diagnostics. TERM Starting the Background Run The COMAPI background run acts as an interface between your application programs and Communication Services. You can start the background run in two ways. From the operator's console with an ST keyin In demand mode or a batch runstream with a processor call To specify your own configuration file or element, you must use the processor call Network Administrator Privileges The COMAPI background run requires the following privileges: The account number must allow real-time execution. The user-id that starts the background run must have the SSCONSOLE privilege (also known as the ER KEYIN$ privilege), and the same privileges as the owner of the COMAPI protected fixed-gate subsystem as listed in Appendix A of the OS 2200 Software Products Installation Guide ( ). Starting the Background Run with an ST Keyin To start the background run from the operator s console, enter the following keyin: For Mode A ST STCOMAPI

37 Managing the Background Run For Modes B through Z ST STCOMAPI-n where n is an alpha character B through Z, indicating a specific installation mode. These keyins execute the standard COMAPI start runstream, which assumes that your COMAPI configuration is in a data file named either COMAPI*CONFIG or COMAPI*CONFIG$n. See the COMAPI subsystem configuration and background run explanation in Section 2 for more information about configuring COMAPI Starting the Background Run with a Processor Call for Mode A If you want to start COMAPI with a configuration file or element other than COMAPI*CONFIG. or if you want to create your own start runstream, use the following processor call to start COMAPI in mode configuration-file.[element] for Modes B through Z If you want to start COMAPI with a configuration file or element other than COMAPI*CONFIG. or if you want to create your own start runstream, use the following processor call to start COMAPI in mode configuration-file.[element] where: n is an alpha character B through Z, indicating a specific installation mode. P option The P option specifies that files cataloged by the COMAPI product have PUBLIC access. This is analogous to using the FILESECURITY PUBLIC SGS at COMUS generation time. If the P option is not specified, all files have PRIVATE access. If you change the option on the COMAPI processor call line, ensure to make corresponding changes to statements in the start runstream

38 Managing the Background Run The following banner line is displayed for COMAPI: Communications Application Program Interface external-id build-id Mode mode Site site-id (execution creation date) today s date/time Example Communications Application Program Interface 8R2 COMAPI-GEN Mode A Site RS05 ( :45) Wed Sep 23 10:49: Terminating the Background Run Using a System E Keyin Normally, you should use a COMAPI user command to terminate the background run (ABORT, ERROR, or TERM). If these fail, use a system E keyin to stop the run. Do not use the X keyin. Using the X keyin can cause part or all COMAPI functionality to be lost User Commands to the Background Run The following user commands help you to manage the background run. Precede each command with the keyin-name from the ADMIN configuration statement (see section apia STATUS To a demand user must be assigned suitable console privilege. The minimum privilege required varies by command and is shown in Table basic keyin mode 2 limited keyin mode 3 full keyin mode 4 display and keyin mode 5 response console mode Table 3 1. Required Console Privileges Command Minimum Privilege ABORT 4 BRKPT 3 DUMP 3 ENTITY

39 Managing the Background Run Table 3 1. Required Console Privileges Command Minimum Privilege ERROR 4 HELP 2 LOG 3 STATUS 2 STATUS ACTIVITY 3 STATUS IA 3 STATUS MULTICAST 3 STATUS PORTS 3 STATUS RUNS 3 STATUS SOCKET 3 TERM 4 comapib log close CCC102019: Log file closed COMAPI$B*COMAPI$LOG(6). CCC102020: Log file opened COMAPI$B*COMAPI$LOG(7) ABORT Command The ABORT command writes the subsystem contents to a dump file, and then terminates the background run. No other information is saved, and COMAPI does not notify applications that the background run has terminated. The background run performs a DEACT of the COMAPI subsystem when it is restarted after an ABORT command. ABORT apia abort Response CCC102051: Panic dump saved in file COMAPI*COMAPI$DUMP(7) BRKPT Command