HP 9000 Networking XTI Programmer’s Guide HP Part No. B2355-90094 Printed in U.S.A. E1295 Edition 3 © Copyright 1995, Hewlett-Packard Company.
Notice Notice Hewlett-Packard warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.
Preface Preface This guide is meant to be used as an addendum to the X/Open CAE Specification for the X/Open Transport Interface (XTI). Copies of the specification are available as follows: In the U.S.A: X/Open Company Ltd. 1010 El Camino Real Suite 380 Menlo Park, CA 94025 U.S.A. Tel: +1(415)323-7992 Fax: +1(415)323-8204 X/Open Company Ltd. 3141 Fairview Park Drive Suite 670 Falls Church, VA 22042-4501 U.S.A. Tel: +1(703)876-0044 Fax: +1(703)876-0050 In Europe: X/Open Company Ltd.
Preface This guide is for experienced applications programmers with knowledge of the HP-UX operating system and programming environment, the OSI or TCP/IP transport-layer functions, networking concepts, and the X/OPEN specification. Reference guides such as the X/Open Portability Guide, Networking Services can provide you with more information on X/Open. This manual is organized as follows: Chapter 1 XTI over OSI Networks provides OSI-specific information.
What is XTI What is XTI The X/Open Transport Interface (XTI) provides a programmatic interface to the transport layer protocol over an OSI or a TCP/UDP network. XTI calls enable two or more processes on the same or different computers to: • Establish a transport connection • Exchange (send and receive) data • Shutdown the connection An analogy may be drawn between the usage of XTI calls and the usage of the telephone.
Systems Supported Systems Supported HP 9000 systems that provide an XTI programmatic interface are those running Hewlett-Packard’s OSI-based product, OTS/9000, or any of the TCP/IP UDP/IP based products such as LAN/9000. OTS/9000 supports the OSI connection-oriented transport services over CONS, CLNS, and RFC 1006 networks, and the OSI connectionless transport over CLNS networks.
Contents 1 XTI over OSI Networks Summary of Programming Tasks 11 Active and Passive Processing 13 Upgrading from Previous XTI Versions 14 Addressing 15 XTI Supported Options 17 XTI Profile Supported 19 Programming Examples 20 2 XTI over TCP/UDP Networks Summary of TCP/UDP Programming Differences 22 TCP and UDP Addressing 24 Generating XTI states via TCP state bits 25 Special TCP Characteristics 26 T_Optmgmt Requests 27 Tracing and Logging 28 Multiprocess Consideration 29 DRAFT 7
Contents A Supported XTI Calls B Using API Tracing in Your Programs Variables to Set 36 Selecting Types of Tracing 37 Enable API Tracing 38 C API Tracing Using Environment Variables Environment Variable Names 41 8 DRAFT
1 XTI over OSI Networks This chapter provides information to assist you in writing and executing applications for XTI over the OSI transport. For details on using XTI over TCP or UDP, refer to chapter 2.
XTI over OSI Networks OTS/9000 supports both connection-oriented (T_COTS) and connectionless (T_CLTS) OSI transport services through XTI. The transport provider names to be used with t_open are /dev/ositpi for T_COTS, and /dev/osicltpi for T_CLTS.
XTI over OSI Networks Summary of Programming Tasks Summary of Programming Tasks The following list summarizes the tasks you need to perform in order to successfully create and execute your programs. These tasks are discussed in more detail in the following sections. 1 Determine how addressing will be handled. You must configure valid NSAPs for the systems used.
XTI over OSI Networks Summary of Programming Tasks 10 For troubleshooting, use API tracing.
XTI over OSI Networks Active and Passive Processing Active and Passive Processing When you create your programs, decide which processes will be initiating connections and which ones will be accepting connections. Decide how normal requests for disconnects will be handled in order to avoid data loss because OSI transport protocols do not support the orderly release features of XTI. Programs can be managed by designating the paired programs as client and server or active and passive.
XTI over OSI Networks Upgrading from Previous XTI Versions Upgrading from Previous XTI Versions This version of XTI has been changed to support the X/Open XPG4 specifications. This has some implications for applications that were created for OTS versions prior to C.05.00, which were based on X/Open XPG3. These changes may require source code changes, recompilation, and relinking your program to work on the new version.
XTI over OSI Networks Addressing Addressing Before a transport endpoint can be used in an XTI application, a transport selector (t-selector) must be assigned (or bound) to it. With XTI, the application process can bind to either the t-selector only or the t-address (includes t-selector and NSAP) as the source address in t_bind(3). For an XTI server application requiring a combination of CONS, CLNS, or RFC 1006, support for incoming and outgoing connections, use the tselector only format.
XTI over OSI Networks Addressing using the t_connect(3) call. Use the complete t-address for the destination address in t_connect where t_sel_len is the length of the t-selector, and nsel_len is the length of the NSAP. Note that the address is padded with a zero. If the remote system is also running OTS/9000, you can find the configured NSAP in the OSIADMIN screen for the corresponding network under “Subnetwork Configuration.
XTI over OSI Networks XTI Supported Options XTI Supported Options The following tables indicate which XTI options and option values are supported over the OTS transport provider. Level XTI_GENERIC: Option Name Absolute Req’t Negotiable States Default Value Other Supported Values XTI_RCVBUF Yes All 10240 10240 to 26144 The XTI_RCVBUF option is provided to allow T_CLTS applications control the amount of data that is buffered locally before incoming TSDUs will be dropped by the OSI transport.
XTI over OSI Networks XTI Supported Options Level ISO_TP (T_CLTS): Option Name Absolute Req’t Negotiable States Default Value Other Supported Values TCO_PROTECTION User Read-Only T_NOPROTECT - TCO_PRIORITY No Read-Only T_PRIDFLT - TCO_CHECKSUM Yes T_IDLE T_YES T_NO Note on option defaults: Options listed as having a default value T_UNSPEC are determined by the OSI system configuration and negotiation with the peer transport entity.
XTI over OSI Networks XTI Profile Supported XTI Profile Supported The following characteristics are supported by the OTS/9000 transport provider. These correspond to the values returned by the t_info structure by a call to t_getinfo after the transport class has been determined during connection establishment.
XTI over OSI Networks Programming Examples Programming Examples Source code for sample OSI-based XTI programs and additional program examples are included online in /opt/ots/xti/demo.
2 XTI over TCP/UDP Networks This chapter provides information to assist you in writing and executing applications for XTI over TCP/UDP networks. For details on using XTI over OSI, refer to chapter 1.
XTI over TCP/UDP Networks Summary of TCP/UDP Programming Differences Summary of TCP/UDP Programming Differences HP-UX 10.0 supports two Internet protocols over XTI: • Transmission Control Protocol (TCP) • Unit Data Protocol (UDP) The transport provider names are /dev/inet_cots and /dev/inet_clts. You can create the device files /dev/tcp and /dev/udp with the equivalent major and minor numbers as net_cots and net_clts if you prefer these names.
XTI over TCP/UDP Networks Summary of TCP/UDP Programming Differences UDP supports the following profile: UDP Transport Profile info->addr sizeof(struct sockaddr_in) info->options 256 info->tsdu 9216 info->etsdu -2 info->connect -2 info->discon -2 info->servtype T_CLTS info->flags 0 (Where: -2 means unsupported, -1 means indefinite length.) The UDP profile’s addressing and options are similar to TCP’s addressing and options.
XTI over TCP/UDP Networks TCP and UDP Addressing TCP and UDP Addressing The addr field of the struct t_call and struct t_unitdata contains network address information used by the TCP and UDP protocols. The format of these addr fields is a struct netbuf with a buffer containing a socket address structure shown below. Refer to the X/Open CAE Specification for the X/ Open Transport Interface (XTI) for details on netbufs and other XTI structures. #include
XTI over TCP/UDP Networks Generating XTI states via TCP state bits Generating XTI states via TCP state bits TCP uses special messages such as SYN, FIN, and RST to indicate a TCP connection’s state transitions. These TCP states need to be translated into the explicit state transitions specified by XTI.
XTI over TCP/UDP Networks Special TCP Characteristics Special TCP Characteristics TCP does not packetize data; thus, transport service data units (tsdu) are not supported. The T_MORE flag is ignored for non-expedited data and for t_snd() calls with expedited data. The T_MORE flag may be set on return from t_rcv(), which indicates that there is a TCP urgent data byte which has not yet been received.
XTI over TCP/UDP Networks T_Optmgmt Requests T_Optmgmt Requests The following is a list of options supported by XTI over TCP/UDP. Please refer to the X/Open CAE Specification for the X/Open Transport Interface (XTI) for more details.
XTI over TCP/UDP Networks Tracing and Logging Tracing and Logging The XTI and TPI part of HP’s XTI TCP/UDP implementation uses the Streams subsystem’s Logging and Tracing facility strlog. Please refer to Streams/UX for the HP 9000 for information on how to use this utility. The TCP/ IP protocol part of HP’s XTI implementation use the nettl utility for tracing and logging. Please refer to Installing and Administering LAN/9000 for details on using this utility.
XTI over TCP/UDP Networks Multiprocess Consideration Multiprocess Consideration HP’s XTI TCP/UDP IP implementation is fully scalable on multiprocessor systems. A number of special Streams Schedulers, sblksched, let XTI TCP/UDP processes contend for multiple processor (MP) locks. The number of these blocking schedulers is set by the system tunable, NSTRBLKSCHED, in the /stand/system file.
XTI over TCP/UDP Networks Multiprocess Consideration 30
A Supported XTI Calls The following table contains a summary of the supported XTI calls. For complete details on the calls, please refer to your online manpages. Use the command man callname, for example, man t_open.
Supported XTI Calls Table 1 Supported XTI Calls XTI Call Description t_accept accept a connect request t_alloc allocate a data structure for various function arguments t_bind bind an address to a transport endpoint t_close close a transport endpoint and release resources t_connect request a connection with another transport user t_error produces an error message for the latest error on the connection t_free free resources from t_alloc(3) call t_getinfo get protocol-specific service inform
Supported XTI Calls Table 1 Supported XTI Calls XTI Call Description t_sndrel initiate an orderly release t_sndudata send a data unit t_strerror produce an error message string t_sync return current state of the connection t_unbind disable a transport endpoint 33
Supported XTI Calls 34
B Using API Tracing in Your Programs An API tracing facility is provided with the HP XTI library. Tracing can be enabled in your XTI application program, and the tracing output is printed to a trace file. XTI provides different levels of tracing. For example, you can trace procedure entry and exits, error conditions, or both.
Using API Tracing in Your Programs Variables to Set Variables to Set API tracing is controlled by three global variables. The variables are described as follows: Tracing Variable Description xti_trace An integer value which constitutes a bitmask to control the level of tracing performed. By default, this mask is 0. xti_trace_fp A pointer to a UNIX file to receive the tracing output. By default, this is set to stderr.
Using API Tracing in Your Programs Selecting Types of Tracing Selecting Types of Tracing The level of XTI tracing is controlled by the xti_trace variable. The xti_trace variable is defined as a bitmask that can be set to particular values (as defined in the file /usr/include/api_trace.h) and as listed in the table that follows. For example, if you want to trace output parameters only, you would set xti_trace to API_TR_OUTPUT. Trace Value Description API_TR_ENTRY_EXITS Traces procedure entry and exit.
Using API Tracing in Your Programs Enable API Tracing Enable API Tracing To enable API tracing in your program, add the following statements to your program: 1 Include the appropriate definitions by adding these lines: #include extern int xti_trace; extern int xti_trace_max_udata; extern FILE *xti_trace_fp; 2 Within your program, enable tracing and select the level of tracing you want by modifying the value of the xti_trace variable.
C API Tracing Using Environment Variables 39
API Tracing Using Environment Variables Enable API Tracing API tracing for XTI also allows you to control tracing via environment variables. When using this method, you do not need to write any special code in your application to take advantage of API tracing.
API Tracing Using Environment Variables Environment Variable Names Environment Variable Names The names of the available XTI environment variables are as follows: • XTI_TRACE • XTI_TRACE_FILE • XTI_TRACE_MAX_UDATA The effect of these environment variables are shown as follows. XTI_TRACE This value indicates the trace level to be used for each API call. It is actually a set of flags, defined in the file /usr/include/api_trace.h. Default = 0 (trace_off).
API Tracing Using Environment Variables Environment Variable Names XTI_TRACE_MAX_UDATA The maximum amount of user data (in bytes) that will be displayed when parameters are displayed. Default = 16.
