HP TCP/IP Services for OpenVMS

Sockets API and System Services Programming

Order Number: BA548--90002

January 2005

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

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

Software Version: HP TCP/IP Services for OpenVMS Version 5.5

Operating Systems: OpenVMS I64 Version 8.2 OpenVMS Alpha Version 8.2

Hewlett-Packard Company Palo Alto, California

Confidential computer software. Valid license from HP 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.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

UNIX is a registered trademark of The Open Group.

Microsoft, Windows and Windows NT are US registered trademarks of Microsoft Corporation.

Printed in the US

ZK6529

The HP TCP/IP Services for OpenVMS documentation is available on CD-ROM.

Contents Index

Preface

The HP TCP/IP Services for OpenVMS product is the HP implementation of the TCP/IP networking protocol suite and internet services for OpenVMS Alpha, OpenVMS I64, 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.

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.
Chapter 3 discusses information to consider when writing portable network applications using the Sockets API for IPv4 and IPv6.
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 the HP OpenVMS System Services Reference manual.
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 describes how to modify a network application so that it can operate in an IPv6 networking environment.

Related Documentation

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

Table 1 TCP/IP Services Documentation
Manual Contents

Compaq TCP/IP Services for OpenVMS Concepts and Planning This manual provides conceptual information about TCP/IP networking on OpenVMS systems, including general planning issues to consider before configuring your system to use the TCP/IP Services software.
This manual also describes the manuals in the TCP/IP Services documentation set and provides a glossary of terms and acronyms for the TCP/IP Services software product.

HP TCP/IP Services for OpenVMS Release Notes The release notes provide version-specific information that supersedes the information in the documentation set. The features, restrictions, and corrections in this version of the software are described in the release notes. Always read the release notes before installing the software.

HP TCP/IP Services for OpenVMS Installation and Configuration This manual explains how to install and configure the TCP/IP Services product.

HP 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.

HP TCP/IP Services for OpenVMS Management This manual describes how to configure and manage the TCP/IP Services product.
Use this manual with the HP TCP/IP Services for OpenVMS Management Command Reference manual.

HP TCP/IP Services for OpenVMS Management Command Reference This manual describes the TCP/IP Services management commands.
Use this manual with the HP TCP/IP Services for OpenVMS Management manual.

HP 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.

HP TCP/IP Services for OpenVMS UNIX Command Equivalents Reference Card This reference card contains information about commonly performed network management tasks and their corresponding TCP/IP management and UNIX command formats.

HP 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.

HP TCP/IP Services for OpenVMS Sockets API and System Services Programming This manual describes how to use the Berkeley Sockets API and OpenVMS system services to develop network applications.

HP 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.

HP 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.

HP TCP/IP Services for OpenVMS Guide to SSH This manual describes how to configure, set up, use, and manage the SSH for OpenVMS software.

HP 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 IPv6 network.

**Table 1 TCP/IP Services Documentation**
Manual	Contents
Compaq TCP/IP Services for OpenVMS Concepts and Planning	This manual provides conceptual information about TCP/IP networking on OpenVMS systems, including general planning issues to consider before configuring your system to use the TCP/IP Services software. This manual also describes the manuals in the TCP/IP Services documentation set and provides a glossary of terms and acronyms for the TCP/IP Services software product.
HP TCP/IP Services for OpenVMS Release Notes	The release notes provide version-specific information that supersedes the information in the documentation set. The features, restrictions, and corrections in this version of the software are described in the release notes. Always read the release notes before installing the software.
HP TCP/IP Services for OpenVMS Installation and Configuration	This manual explains how to install and configure the TCP/IP Services product.
HP 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.
HP TCP/IP Services for OpenVMS Management	This manual describes how to configure and manage the TCP/IP Services product. Use this manual with the HP TCP/IP Services for OpenVMS Management Command Reference manual.
HP TCP/IP Services for OpenVMS Management Command Reference	This manual describes the TCP/IP Services management commands. Use this manual with the HP TCP/IP Services for OpenVMS Management manual.
HP 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.
HP TCP/IP Services for OpenVMS UNIX Command Equivalents Reference Card	This reference card contains information about commonly performed network management tasks and their corresponding TCP/IP management and UNIX command formats.
HP 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.
HP TCP/IP Services for OpenVMS Sockets API and System Services Programming	This manual describes how to use the Berkeley Sockets API and OpenVMS system services to develop network applications.
HP 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.
HP 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.
HP TCP/IP Services for OpenVMS Guide to SSH	This manual describes how to configure, set up, use, and manage the SSH for OpenVMS software.
HP 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 IPv6 network.

For additional information about HP OpenVMS products and services, visit the following World Wide Web address:

http://www.hp.com/go/openvms

For a comprehensive overview of the TCP/IP protocol suite, you might find the book Internetworking with TCP/IP: Principles, Protocols, and Architecture, by Douglas Comer, useful.

Reader's Comments

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

Internet openvmsdoc@hp.com

Postal Mail Hewlett-Packard Company
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

For information about how to order additional documentation, visit the following World Wide Web address:

http://www.hp.com/go/openvms/doc/order

Conventions

The name TCP/IP Services means any of the following:

HP TCP/IP Services for OpenVMS Alpha
HP TCP/IP Services for OpenVMS I64
HP 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 type Bold type represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.

italic type Italic type 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 TYPE Uppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Example This typeface indicates code examples, command examples, and interactive screen displays. In text, this type also identifies URLs, UNIX commands and pathnames, PC-based commands and folders, and certain elements of the C programming language.

- 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 HP 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 and OpenVMS I64 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 and OpenVMS I64 systems
Finer granularity of control
Easier asynchronous programming
Support for the following programming languages:
- MACRO-32
- BLISS-32
- Ada
- BASIC
- C
- C++
- COBOL
- Fortran
- Pascal

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

1.3 Application Development Files

TCP/IP Services provides definition files and function libraries 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

**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

TCP/IP Services 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 header 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

TCP/IP Services Related

BITYPES.H Basic integral types

IF.H Structures providing a basic transport mechanism

IF_ARP.H Structures for the Address Resolution Protocol

IF_TYPES.H IANA types

IN.H Internet protocol family

IN6.H Internet V6 protocol family

IN6_MACHTYPES.H Machine-specific internet V6 protocol family

INET.H Internet access

IOCTL.H I/O controls for special files

IP.H Definitions for IPv4

IP6.H Definitions for IPv6

NAMESER.H Definition for maximum domain name size

NETDB.H Network database library information

RESOLV.H Resolver configuration file

SOCKET.H TCP/IP socket definitions

STROPTS.H Streams interface definitions

TCP.H TCP descriptions

__DECC_INCLUDE_PROLOGUE.H TCP/IP Services internal transliterations for IPv6 functions (directed to TCPIP$LIB.OLB)

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 service status codes

STARLET.H System service 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

**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
TCP/IP Services Related
BITYPES.H	Basic integral types
IF.H	Structures providing a basic transport mechanism
IF_ARP.H	Structures for the Address Resolution Protocol
IF_TYPES.H	IANA types
IN.H	Internet protocol family
IN6.H	Internet V6 protocol family
IN6_MACHTYPES.H	Machine-specific internet V6 protocol family
INET.H	Internet access
IOCTL.H	I/O controls for special files
IP.H	Definitions for IPv4
IP6.H	Definitions for IPv6
NAMESER.H	Definition for maximum domain name size
NETDB.H	Network database library information
RESOLV.H	Resolver configuration file
SOCKET.H	TCP/IP socket definitions
STROPTS.H	Streams interface definitions
TCP.H	TCP descriptions
__DECC_INCLUDE_PROLOGUE.H	TCP/IP Services internal transliterations for IPv6 functions (directed to TCPIP$LIB.OLB)
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 service status codes
STARLET.H	System service 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

The header files NAMESER.H and RESOLV.H contain transliterations that intercept calls made to nameserver and resolver API functions and redirect them to TCPIP$LIB.OLB. To use an implementation of these functions other than the one provided by TCP/IP Services, define the following symbols:

For the nameserver API routines, use _TCPIP_NO_NS_TRANSLITERATIONS.
For the resolver API routines, use _TCPIP_NO_RES_TRANSLITERATIONS.

Contents

Index

Internet	openvmsdoc@hp.com
Postal Mail	Hewlett-Packard Company OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

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 type	Bold type represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic type	Italic type 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 TYPE	Uppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
`Example`	This typeface indicates code examples, command examples, and interactive screen displays. In text, this type also identifies URLs, UNIX commands and pathnames, PC-based commands and folders, and certain elements of the C programming language.
-	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.