# Compaq TCP/IP Services for OpenVMS

# Sockets API and System Services Programming

Order Number: AA--LU51L--TE

# January 2001

This manual describes how to use Compaq TCP/IP Services for OpenVMS to develop network applications using Berkeley Sockets or OpenVMS system services.

Revision/Update Information: This manual supersedes the Compaq TCP/IP Services for OpenVMS System Services and C Socket Programming, Version 5.0.

Software Version: Compaq TCP/IP Services for OpenVMS Version 5.1

Operating System: OpenVMS Alpha Versions 7.1 and 7.2-1 OpenVMS VAX Versions 7.1 and 7.2

Compaq Computer Corporation Houston, Texas

© 2001 Compaq Computer Corporation

COMPAQ, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.

OpenVMS and Tru64 are trademarks of Compaq Information Technologies, Inc in the United States and other countries.

UNIX is a trademark of The Open Group in the United States and other countries.

All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK6529

This document is available on CD-ROM.

Contents | Index

# Preface

The Compaq TCP/IP Services for OpenVMS product is the Compaq implementation of the TCP/IP networking protocol suite and internet services for OpenVMS Alpha and OpenVMS VAX systems.

A layered software product, TCP/IP Services provides a comprehensive suite of functions and applications that support industry-standard protocols for heterogeneous network communications and resource sharing.

See the Compaq TCP/IP Services for OpenVMS Installation and Configuration manual for information about installing, configuring, and starting this product.

This manual describes how to use TCP/IP Services to develop network applications using Berkeley Sockets or OpenVMS system services.

# Intended Audience

This manual is intended for experienced programmers who want to write network application programs that run in the TCP/IP Services environment. Readers should be familiar with the C programming language, TCP/IP protocols, and networking concepts.

# Document Structure

This manual contains the following chapters and appendixes:

- Chapter 1 describes the application programming interfaces that TCP/IP Services supports.
- Chapter 2 describes the typical function calls for developing network applications using the TCP and UDP protocols and either the Sockets API or OpenVMS system services programming interface. To help network programmers write internet applications, this chapter provides examples of network applications using the Sockets API and OpenVMS system services.
- Chapter 3 discusses information to consider when writing portable network applications using the Sockets API.
- Chapter 4 contains Sockets API reference information.
- Chapter 5 describes how to use $QIO system services and data structures to write network applications using OpenVMS system services.
- Chapter 6 contains OpenVMS system services and I/O function reference information pertinent to TCP/IP Services. This information supplements the OpenVMS system services programming information contained in OpenVMS System Services Reference.
- Appendix A lists socket options supported by both programming interfaces.
- Appendix B lists IOCTL requests.
- Appendix C describes TCP/IP Services data types.
- Appendix D lists Sockets API error codes and equivalent OpenVMS system services status codes.
- Appendix E contains client/server application examples using the TCP and UDP protocols.

# Related Documentation

Table 1 lists the documents available with this version of TCP/IP Services.

Table 1 TCP/IP Services Documentation
Manual | Contents
--- | ---
DIGITAL TCP/IP Services for OpenVMS Concepts and Planning | This manual provides conceptual information about networking and the TCP/IP protocol including a description of the Compaq implementation of the Berkeley Internet Name Domain (BIND) service and the Network File System (NFS). It outlines general planning issues to consider before configuring your system to use the TCP/IP Services software. This manual also describes the manuals in the documentation set, provides a glossary of terms and acronyms for the TCP/IP Services software product, and documents how to contact the InterNIC Registration Service to register domains and access Request for Comments (RFCs).
Compaq TCP/IP Services for OpenVMS Release Notes | This text file describes new features and changes to the software including installation, upgrade, configuration, and compatibility information. These notes also describe new and existing software problems and restrictions, and software and documentation corrections. Print this text file at the beginning of the installation procedure and read it before you install TCP/IP Services.
Compaq TCP/IP Services for OpenVMS Installation and Configuration | This manual explains how to install and configure the TCP/IP Services layered application product.
DIGITAL TCP/IP Services for OpenVMS User's Guide | This manual describes how to use the applications available with TCP/IP Services such as remote file operations, email, TELNET, TN3270, and network printing. This manual explains how to use these services to communicate with systems on private internets or on the worldwide Internet.
Compaq TCP/IP Services for OpenVMS Management | This manual describes how to configure and manage the TCP/IP Services product. Use this manual with the Compaq TCP/IP Services for OpenVMS Management Command Reference manual.
Compaq TCP/IP Services for OpenVMS Management Command Reference | This manual describes the TCP/IP Services management commands. Use this manual with the Compaq TCP/IP Services for OpenVMS Management manual.
Compaq TCP/IP Services for OpenVMS Management Command Quick Reference Card | This reference card lists the TCP/IP management commands by component and describes the purpose of each command.
Compaq TCP/IP Services for OpenVMS UNIX Command Reference Card | This reference card contains information about commonly performed network management tasks and their corresponding TCP/IP management and Compaq Tru64 UNIX command formats.
DIGITAL TCP/IP Services for OpenVMS ONC RPC Programming | This manual presents an overview of high-level programming using open network computing remote procedure calls (ONC RPC). This manual also describes the RPC programming interface and how to use the RPCGEN protocol compiler to create applications.
Compaq TCP/IP Services for OpenVMS Sockets API and System Services Programming | This manual describes how to use the Sockets API and OpenVMS system services to develop network applications.
Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference | This manual describes the Simple Network Management Protocol (SNMP) and the SNMP application programming interface (eSNMP). It describes the subagents provided with TCP/IP Services, utilities provided for managing subagents, and how to build your own subagents.
Compaq TCP/IP Services for OpenVMS Tuning and Troubleshooting | This manual provides information about how to isolate the causes of network problems and how to tune the TCP/IP Services software for the best performance.
Compaq TCP/IP Services for OpenVMS Guide to IPv6 | This manual describes the IPv6 environment, the roles of systems in this environment, the types and function of the different IPv6 addresses, and how to configure TCP/IP Services to access the 6bone network.

For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:

    http://www.openvms.compaq.com/

For a comprehensive overview of the TCP/IP protocol suite, you might find the following books useful.

- Internetworking with TCP/IP Vol 1: Principles, Protocols,and Architecture by Douglas Comer, Prentice Hall Englewood Cliffs, New Jersey 07632, ISBN 0-13-468505-9.
- UNIX Network Programming Volume 1 Networking APIs: Sockets and XTI by W. Richard Stevens, Prentice Hall PTR, Upper Saddle River, NJ 07458, ISBN 0-13-490012-X.

# Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet | openvmsdoc@compaq.com
Mail | Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

# How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

    http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

# Conventions

TCP/IP Services is used to mean both:

- Compaq TCP/IP Services for OpenVMS Alpha
- Compaq TCP/IP Services for OpenVMS VAX

The following conventions are used in this manual. In addition, please note that all IP addresses are fictitious.

Ctrl/ x | A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x | A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]` | In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
... | A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . . | A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( ) | In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one.
[ ] | In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
| | In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ } | In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold text | This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic text | Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
`Monospace text` | Monospace type indicates code examples and interactive screen displays. This typeface indicates UNIX system output or user input, commands, options, files, directories, utilities, hosts, and users. In the C programming language, this typeface identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
- | A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers | All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

# Chapter 1
Application Programming Interfaces

The application programming interfaces available with Compaq TCP/IP Services for OpenVMS allow programmers to write network applications that are independent of the underlying communication facilities. This means that the system can support communications networks that use different sets of protocols, naming conventions, and hardware platforms.

The TCP/IP Services product supports two network communication application programming interfaces (APIs):

- Berkeley Software Distribution (BSD) Sockets
- OpenVMS system services

# 1.1 BSD Sockets

The Sockets application programming interface (API) supports only the C programming language. The benefits of using this API include:

- Ease of use.
- Portability --- you can create common code for use on UNIX, OpenVMS, and many other platforms.
- 64-bit addressing capability on OpenVMS Alpha systems.

See Chapter 4 for a detailed description of Sockets API functions.

# 1.2 OpenVMS System Services

Each step in the Sockets communications process has a corresponding OpenVMS system service routine. The benefits of using OpenVMS system services include:

- Improved application performance
- 64-bit addressing capability on OpenVMS Alpha systems
- Finer granularity of control
- Easier asynchronous programming
- Support for the following products
  - MACRO-32
  - BLISS-32
  - Compaq Ada
  - Compaq BASIC
  - Compaq C
  - Compaq C++
  - Compaq COBOL
  - Compaq Fortran
  - Compaq Pascal

See Chapter 6 for a detailed description of OpenVMS system service calls.

# 1.3 Application Development Files

TCP/IP Services provides definition files, a shared library file for use in developing network applications and programming example files to assist in learning how to develop network applications.

## 1.3.1 Definition Files

Table 1-1 lists the definition files that are included with TCP/IP Services in the SYS$LIBRARY directory. Specific languages may also supply additional files that define structures related to network programming. Check the documentation for the language you are using.

Table 1-1 Network Definition Files
File | Description
--- | ---
TCPIP$INETDEF.ADA | Ada definition file
TCPIP$INETDEF.BAS | BASIC definition file
TCPIP$INETDEF.FOR | Fortran definition file
TCPIP$INETDEF.H | C and C++ definition file
TCPIP$INETDEF.MAR | MACRO-32 definition file
TCPIP$INETDEF.PAS | Pascal definition file
TCPIP$INETDEF.PLI | PL/I definition file
TCPIP$INETDEF.R32 | BLISS-32 definition file

Compaq provides header files, data types, and support functions to facilitate OpenVMS system services programming. The header files provide definitions for constants. Table 1-2 lists the available files.

Table 1-2 C Language Definition Files
Header File | Description
--- | ---
Common Industry Standard
IN.H | Internet system. Constants, functions, and structures
INET.H | Network address information
NETDB.H | Network database library information
SIGNAL.H | UNIX style signal value definitions
SOCKET.H | BSD Sockets API
OpenVMS Related
DESCRIP.H | OpenVMS descriptor
IOCTL.H | I/O control
IODEF.H | I/O function codes
LIB$FUNCTIONS.H | Run-time library function signatures
SSDEF.H | System services status code
STARLET.H | System services calls
TCPIP$INETDEF.H | TCP/IP network constants, functions, and structures
Standard UNIX
STDIO.H | Standard UNIX I/O functions
STDLIB.H | Standard UNIX library functions
STRING.H | String-handling functions

## 1.3.2 Libraries

Table 1-3 lists the routine libraries included with TCP/IP Services.

Table 1-3 Sockets API Libraries
File | Location | Description
--- | --- | ---
TCPIP$IPC_SHR.EXE | SYS$LIBRARY | Sockets API Run-Time Library
TCPIP$LIB.OLB | TCPIP$LIBRARY | BSD Version 4.4 Sockets object library

## 1.3.3 Programming Examples

Table 1_4 and Table 1-5 summarize the programming examples included with TCP/IP Services in the TCPIP$EXAMPLES directory. Most of these examples consist of a client and a corresponding server. Appendix E contains printed examples of the programs described in Table 1_4 and Table 1-5.

Table 1-4 TCP Programming Examples
File | Description
--- | ---
TCPIP$TCP_SERVER_SOCK.C TCPIP$TCP_CLIENT_SOCK.C | Example TCP/IP client and server using the Sockets API.
TCPIP$TCP_SERVER_SOCK_AUXS.C | Example TCP/IP server using the Sockets API that accepts connections from the auxiliary server.
TCPIP$TCP_SERVER_QIO.C TCPIP$TCP_CLIENT_QIO.C | Example TCP/IP client and server using QIO system services.
TCPIP$TCP_SERVER_QIO_AUXS.C | Example TCP/IP server using QIO system services that accepts connections from the auxiliary server.
TCPIP$TCP_CLIENT_QIO.MAR TCPIP$TCP_SERVER_QIO.MAR | Example TCP/IP client and server using QIO system services and the MACRO-32 programming language.

Table 1-5 UDP Programming Examples
File | Description
--- | ---
TCPIP$UDP_SERVER_SOCK.C TCPIP$UDP_CLIENT_SOCK.C | Example UDP/IP client and server using the Sockets API.
TCPIP$UDP_SERVER_QIO.C TCPIP$UDP_CLIENT_QIO.C | Example UDP/IP client and server using QIO system services.
TCPIP$UDP_CLIENT_QIO.MAR TCPIP$UDP_SERVER_QIO.MAR | Example UDP/IP client and server using QIO system services and the MACRO-32 programming language.

Next | Contents | Index