Order Number: AA--LU51K--TE

This manual describes how to use DIGITAL TCP/IP Services for OpenVMS to develop network-based applications using the OpenVMS system services interface or the C socket interface.

Revision Information: This is a revised manual.

Operating Systems: OpenVMS Alpha Versions 7.1, 7.2 OpenVMS VAX Versions 7.1, 7.2

Software Version: DIGITAL TCP/IP Services
for OpenVMS Version 5.0

Compaq Computer Corporation Houston, Texas

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

© Compaq Computer Corporation 1999. All rights reserved.

The following are trademarks of Compaq Computer Corporation: ACMS, Alpha, Compaq, DEC C++, DECdtm, DEC Fortran, DDCMP, DEC, DECnet, DECNIS, DECserver, DECsystem, DIGITAL, DIGITAL UNIX, DNA, InfoServer, LAT, OpenVMS, PATHWORKS, POLYCENTER, ULTRIX, VAX, VAX Ada, VAX BASIC, VAX BLISS-32, VAX C, VAX COBOL, VAX Pascal, VAXstation, VMS, VMScluster, and the DIGITAL logo.

The following are third-party trademarks:

IBM and OS/2 are registered trademarks of International Business Machines Corporation.

Sun, NFS, and PC-NFS are registered trademarks of Sun Microsystems, Inc.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.

All other trademarks and registered trademarks are the property of their respective holders.

ZK6529

This document is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents

Index

The DIGITAL 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, DIGITAL TCP/IP Services for OpenVMS 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 DIGITAL TCP/IP Services for OpenVMS to develop network-based applications using the OpenVMS system services interface or the C Socket interface.

Intended Audience

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

New and Changed Features

DIGITAL TCP/IP Services for OpenVMS Version 5.0 provides a new kernel based on the IPv4 kernel ported from Compaq's DIGITAL UNIX Version 4.0D. ¹

Other new features include:

• Dynamic Host Configuration Protocol (DHCP) that allows the system manager to provide dynamic allocation of IP addresses from a single OpenVMS host.
• Gateway routing daemon (GATED) server and a comprehensive suite of interior and exterior routing protocols that offer advanced routing options.
• Classless Inter-domain routing (CIDR) that allows networks to be built with variable-length subnetworks.
• PathMTU discovery, a mechanism that allows an IP host to determine the most efficient packet size for use on a particular path between the source to the destination host.
• UNIX management utilities to assist with the management of OpenVMS systems in a mixed UNIX and OpenVMS environment.
• New implementations of NTP, SNMP, and BIND.
• Improved online help and a new message database for use with the OpenVMS Help Message utility (MSGHLP).

Changes to this document include:

• Instructions on how to compile and link the Compaq C language programs using either Berkeley Software Distribution (BSD) socket programming interface Version 4.3 or Version 4.4.
• New socket options for the IO$SENSEMODE/IO$SENSECHAR and IO$SETMODE/IO$SETCHAR system services and the getsockopt() and setsockopt() C Socket routines.
• Instructions on how to send and receive IP multicast datagrams.
• Support for 64-bit addressing on OpenVMS Alpha systems.
• Support for the ioctl() routine.
• File names that reflect the TCPIP identifier.
• Improvements to the accuracy and readability of the document.

Document Structure

This manual contains the following chapters and an appendix:

• Chapter 1 describes the application programming interfaces that DIGITAL TCP/IP Services for OpenVMS supports.
• Chapter 2 describes the client/server calling sequence for both TCP and UDP and provides examples of C Socket and OpenVMS system services routines to help network programmers write internet applications.
• Chapter 3 describes how to use the $QIO system services and data structures to write an internet application program.
• Chapter 4 provides detailed use and reference information about the OpenVMS system services routines that network programmers use to write internet applications.
• Chapter 5 discusses information to consider when writing C Socket programs for portable internet applications.
• Chapter 6 provides detailed use and reference information about C Socket routines that network programmers use to write portable internet applications.
• Chapter 7 lists the C Socket error codes and the equivalent OpenVMS system services error codes.
• Appendix A contains examples of some application programs.

Related Documentation

Table 1 lists the manuals available with this version of DIGITAL TCP/IP Services for OpenVMS.

Table 1 DIGITAL TCP/IP Services for OpenVMS Documentation

Manual	Contents
DIGITAL 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 DIGITAL TCP/IP Services for OpenVMS.
DIGITAL TCP/IP Services for OpenVMS Installation and Configuration	This manual explains how to install and configure the DIGITAL TCP/IP Services for OpenVMS layered application product.
DIGITAL TCP/IP Services for OpenVMS User's Guide	This manual describes how to use the applications available with DIGITAL TCP/IP Services for OpenVMS such as remote file operations, e-mail, TELNET, TN3270, and network printing. This manual also explains how to use these services to communicate with systems on private internets or on the worldwide Internet.
DIGITAL TCP/IP Services for OpenVMS Management	This manual describes how to configure and manage the DIGITAL TCP/IP Services for OpenVMS product. Use this manual with the DIGITAL TCP/IP Services for OpenVMS Management Command Reference manual.
DIGITAL TCP/IP Services for OpenVMS Management Command Reference	This manual describes the DIGITAL TCP/IP Services for OpenVMS management commands. Use this manual with the DIGITAL TCP/IP Services for OpenVMS Management manual.
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.
DIGITAL TCP/IP Services for OpenVMS System Service and C Socket Programming	This manual describes how to use the OpenVMS system services and C Socket programming interfaces to develop network-based applications.
DIGITAL TCP/IP Services for OpenVMS eSNMP Programming and Reference	This manual describes the Extensible Simple Network Management Protocol (eSNMP), the eSNMP application programming interface (API), and how to build additional subagents to manage vendor-specific equipment.

For additional information about the DIGITAL TCP/IP Services for OpenVMS products and services, access the DIGITAL OpenVMS World Wide Web site at the following URL:

http://www.openvms.digital.com

You might find the Internetworking with TCP/IP: Principles, Protocols, and Architecture by Douglas Comer useful if you are looking for a comprehensive overview of the TCP/IP protocol suite.

Terminology

DIGITAL TCP/IP Services for OpenVMS Version 5.0 completes the change initiated several releases ago when the product name changed from "ULTRIX Connection (UCX)" to "DIGITAL TCP/IP Services for OpenVMS." To complete this change, the identifier "UCX" is replaced with "TCPIP" in the following cases:

• Registered product facility code
• Management command prompt
• All messages, examples, and banners
• All product file names and databases
• All logical names, except those retained for compatibility
• All associated product documentation

DIGITAL TCP/IP Services for OpenVMS is used to mean both:

• DIGITAL TCP/IP Services for OpenVMS Alpha
• DIGITAL TCP/IP Services for OpenVMS VAX

The auxiliary server is the DIGITAL TCP/IP Services for OpenVMS implementation of the UNIX internet daemon (inetd).

NFS is the DIGITAL TCP/IP Services for OpenVMS implementation of the NFS protocols, including the NFS server, the NFS client, and PC-NFS.

TN3270 means the TELNET client software that emulates IBM 3270 model terminals.

The term UNIX refers to the DIGITAL UNIX operating system. DIGITAL UNIX is fully compatible with Version 4.3 and Version 4.4 of the Berkeley Software Distribution (BSD).

Host and node both mean a system connected to an internet.

The term Internet refers to the global interconnection of networks, as defined by RFC 1208, which consists of large networks using TCP/IP to provide universal connectivity, reaching the Defense Advanced Projects Research Internet, MILNET, NSFnet, CERN, and many worldwide universities, government research labs, military installations, and business enterprises.

The term internet refers to private interconnected networks that use TCP/IP to connect together and function as one, virtual network.

Acronyms

The following acronyms are frequently used in this manual:

BIND	Berkeley Internet Name Domain
FTP	File Transfer Protocol
LPD	Line Printer Daemon Protocol
LPR	Line Printer Protocol
RCP	Remote Copy
REXEC	Remote Executive
RFC	Request for Comments
RLOGIN	Remote Login
RSH	Remote Shell
SMTP	Simple Mail Transfer Protocol
TCP/IP	Transmission Control Protocol/Internet Protocol

Conventions

All IP addresses in this manual represent fictitious addresses. The following conventions apply to this manual.

Convention	Meaning
UPPERCASE TEXT	Indicates names of OpenVMS and DIGITAL TCP/IP Services for OpenVMS commands, options, utilities, files, directories, hosts, and users.
lowercase special type	Indicates UNIX system output or user input, commands, options, files, directories, utilities, hosts, and users.
bold text	Indicates a new term.
italic text	Indicates a variable.
[Return]	Indicates that you press the Return key.
[Ctrl/] x	Indicates that you press the Control key while you press the key noted by x.
[ ]	In command format descriptions, indicates the enclosed element is optional. You can enter as many as you want.
{ }	In command format descriptions, indicates you must enter at least one listed element. For readability, each element is either listed on a separate line or separated by vertical bars (|). Unless otherwise instructed, use a space to separate these elements when using them with commands.
...	Horizontal ellipsis points in examples indicate additional optional arguments have been omitted.
. . .	Vertical ellipsis points indicate omission of items from a code example or display example; the items are omitted because they are not important to the topic being discussed.

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How To Order Additional Documentation

Visit the OpenVMS Documentation World Wide Web site at the following URL to learn how to order additional documentation:

http://www.openvms.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

The DIGITAL TCP/IP Services for OpenVMS socket interface allows programmers to write network-based applications that are independent of the underlying communication facilities. This means that the system can support communication networks that use different sets of protocols, naming conventions, and hardware platforms.

The DIGITAL TCP/IP Services for OpenVMS product supports two socket communication application programming interfaces (APIs):

• OpenVMS system services
• C Socket

Each step in the C Socket 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
• Flexibility
• Support for many different programming languages, including the following:

  MACRO-32	VAX BLISS-32
  DEC C	VAX COBOL
  DEC Fortran	VAX Pascal
  VAX Ada	VAX PL/1
  VAX BASIC

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

1.1.1 Using 64-Bit Addresses (Alpha Only)

For applications that run on OpenVMS Alpha systems, input and output operations can be performed directly to and from the P2 or S2 addressable space by means of the 64-bit friendly $QIO and $QIOW system services.

To write data to a remote host, use the $QIO(IO$_WRITEVBLK) function with either the p1 (input buffer) or p5 (input buffer list) parameter. The address you specify for the parameter can be a 64-bit value.

To read data from a remote host, use the $QIO(IO$_READVBLK) function with either the p1 (output buffer) or p6 (output buffer list) parameter. The address you specify for the parameter can be a 64-bit value.

MACRO-32 does not provide 64-bit macros for system services. For more information about MACRO-32 programming support and for 64-bit addressing in general, see the OpenVMS Alpha Guide to 64-Bit Addressing and VLM Features.

For more information about using the $QIO and $QIOW system services for 64-bit addressing, see Chapters 3 and 4.

1.2 C Socket Interface

The C Socket interface supports only the C programming language. The benefits of using this interface include:

• Ease of use
• Portability --- you can create common code for use on UNIX, OpenVMS, and many other platforms

See Chapter 6 for a detailed description of the C Socket routines.

1.3 Location of Application Development Files

Table 1-1 lists the definition files that are included with the product. 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 Internet Definition Files --- SYS$LIBRARY:

File	Description
TCPIP$INETDEF.ADA	Ada definitions file
TCPIP$INETDEF.FOR	Fortran definitions file
TCPIP$INETDEF.H	C definitions file
TCPIP$INETDEF.MAR	MACRO-32 definitions file
TCPIP$INETDEF.PAS	Pascal definitions file
TCPIP$INETDEF.PLI	PL/I definitions file
TCPIP$INETDEF.R32	BLISS-32 definitions file
TCPIP$INETDEF.BAS	BASIC definitions file

Table 1-2 lists the routine libraries included with the product.

Table 1-2 C Socket Routine Libraries

File	Location	Description
TCPIP$IPC_SHR.EXE	SYS$LIBRARY:	C Socket Run-Time Library
TCPIP$LIB.OLB	TCPIP$LIBRARY:	BSD Version 4.4 C Socket object library

Tables 1-3 and 1-4 summarize the programming examples included with the product. Most of these examples consist of a client and a corresponding server. In most cases, you must use the associated client and server programs together. The client or server from one example will not necessarily work with its counterpart from another example.

Table 1-3 UDP Programming Examples --- TCPIP$EXAMPLES

File	Description
TCPIP$UDP_SERVER_IPC.C 1 TCPIP$UDP_CLIENT_IPC.C	Examples of a UDP/IP client and server using the IPC socket interface.
TCPIP$UDP_SERVER_QIO.C TCPIP$UDP_CLIENT_QIO.C	Examples of a UDP/IP client and server using QIO calls.
TCPIP$UDP_CLIENT_QIO.MAR TCPIP$UDP_SERVER_QIO.MAR	UDP client and server MACRO example.

Table 1-4 TCP Programming Examples --- TCPIP$EXAMPLES

File	Description
TCPIP$TCP_SERVER_IPC.C 1 TCPIP$TCP_CLIENT_IPC.C 1	Examples of a TCP/IP client and server using the IPC socket interface.
TCPIP$TCP_SERVER_IPC_AUXS.C 1	An example of a TCP/IP server using the IPC socket interface which accepts a connection from the auxiliary server.
TCPIP$TCP_SERVER_QIO.C 1 TCPIP$TCP_CLIENT_QIO.C	Examples of a TCP/IP client and server using QIO calls.
TCPIP$TCP_SERVER_QIO_2ND.C TCPIP$TCP_CLIENT_QIO_2ND.C	Another example of a TCP/IP client and server using QIO calls.
TCPIP$TCP_SERVER_QIO_AUXS.C	An example of a TCP/IP server using the QIO socket interface that accepts a connection from the auxiliary server.
TCPIP$TCP_SERVER_QIO_AUXS_2ND.C TCPIP$TCP_CLIENT_QIO_AUXS_2ND.C	An example of a TCP/IP client and server using the QIO interface where the auxiliary server is used to establish a connection from the client.
TCPIP$TCP_SOCKET_QIO_3RD.H TCPIP$TCP_SOCKET_QIO_3RD.C TCPIP$TCP_SERVER_QIO_3RD.C TCPIP$TCP_CLIENT_QIO_3RD.C	Module TCPIP$TCP_SOCKET_QIO_3RD.C contains routines that use the OpenVMS System Service interface to replicate the 4BSD UNIX C Socket abstractions. The routines outlined in this module cannot be mixed with the UNIX C socket abstractions. Modules TCPIP$TCP_SERVER_QIO_3RD.C and TCPIP$TCP_CLIENT_QIO_3RD.C build with module TCPIP$TCP_SOCKET_QIO_3RD.C to create simple client and server programs that depict the DIGITAL TCP/IP Services QIO interface through the routines provided in module TCPIP$TCP_SOCKET_QIO_3RD.C.
TCPIP$TCP_CLIENT_QIO.MAR TCPIP$TCP_SERVER_QIO.MAR	TCP client and server MACRO example.