# DIGITAL TCP/IP Services for OpenVMS

# System Services and C Socket Programming

# October 1997

This book describes how to use DIGITAL TCP/IP Services for OpenVMS to build C Socket and system services application interfaces.

Revision Information: This is a revised manual.

Operating Systems: OpenVMS Alpha Versions 6.2, 7.0, 7.1 OpenVMS VAX Versions 6.2, 7.0, 7.1

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

Digital Equipment Corporation Maynard, Massachusetts

October 1997

Digital Equipment 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 DIGITAL or an authorized sublicensor.

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

© Digital Equipment Corporation 1997. All rights reserved. The following are trademarks of Digital Equipment Corporation: ACMS, DECdtm, DDCMP, DEC, DECnet, DECNIS, DECserver, DECsystem, DECwindows, DIGITAL, DNA, InfoServer, LAT, OpenVMS, PATHWORKS, POLYCENTER, ULTRIX, VAX, VAXstation, VMS, VMScluster, and the DIGITAL logo.

The following are third-party trademarks:

CRAY is a registered trademark of Cray Research, Inc.
HP and Hewlett-Packard are registered trademarks of Hewlett-Packard Company.
IBM and OS/2 are registered trademarks of International Business Machines Corporation.
MS-DOS is a registered trademark of Microsoft Corporation.
Macintosh is a registered trademark of Apple Computer, Inc.
MultiNet is a registered trademark of TGV, Inc.
OSF/1 is a registered trademark of Open Software Foundation, Inc.
OSI is a registered trademark of CA Management, Inc.
PATHways is a registered trademark of The Wollongong Group.
PostScript is a registered trademark of Adobe Systems, Inc.
SCO is a trademark of Santa Cruz Operations, Inc.
Sun, NFS, and PC-NFS are registered trademarks of Sun Microsystems, Inc.
TCPware is a registered trademark of Process Software Corporation.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd.
All other trademarks and registered trademarks are the property of their respective holders.

ZK6529

This document is available on CD-ROM.

# Contents

# Preface

This book describes how to use DIGITAL TCP/IP Services for OpenVMS to build C Socket and system services application interfaces.

# Intended Audience

This book 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.

# Document Structure

This book 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 OpenVMS 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.

# Terminology

This manual uses the following terminology:

- The abbreviation for the product's name is UCX.
- 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
- Software components
  - Auxiliary server is the DIGITAL TCP/IP Services for OpenVMS implementation of the UNIX 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 is the TELNET software that emulates IBM 3270 model terminals.
- UNIX operating system
  UNIX refers to UNIX Version 4.3 of the Berkeley Software Distribution (BSD). The DIGITAL UNIX operating system is fully compatible with UNIX BSD Version 4.3.
- Networking terms
  - 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 Agency (DARPA) 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

For a complete list of acronyms used throughout this and other manuals in the DIGITAL TCP/IP Services for OpenVMS documentation set, see the DIGITAL TCP/IP Services for OpenVMS Concepts and Planning guide.

# Conventions

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

Convention | Meaning
--- | ---
UPPERCASE TEXT | Indicates names of OpenVMS and UCX 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.
italic type | 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 optional elements. You can enter as many as you want.
{ } | In command format descriptions, indicates you must enter at least one listed element.

# Related Documents

The following manuals provide additional information about planning your network and configuring and managing UCX:

- DIGITAL TCP/IP Services for OpenVMS Concepts and Planning
- DIGITAL TCP/IP Services for OpenVMS Management

For a complete list of all manuals in the DIGITAL TCP/IP Services for OpenVMS documentation set, see the DIGITAL TCP/IP Services for OpenVMS Concepts and Planning guide.

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

    http://www.openvms.digital.com

# Reader's Comments

DIGITAL welcomes your comments on this manual or any of the DIGITAL TCP/IP Services for OpenVMS documents. Send us your comments through any of the following channels:

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

# How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Location | Call | Fax | Write
--- | --- | --- | ---
U.S.A. | DECdirect 800-DIGITAL 800-344-4825 | Fax: 800-234-2298 | Digital Equipment Corporation Mailstop: TAY2-2/11D 153 Taylor Street Littleton, MA 01460
Puerto Rico | 787-781-0505 | Fax: 787-749-8300 | Local DIGITAL subsidiary
Canada | DTN: 621-6005 800-DIGITAL | Fax: 613-592-1946 | Digital Equipment of Canada, Ltd. Box 13000 Kanata, Ontario, Canada K2K2A6 Attn: CICC
International | --- | --- | Local DIGITAL subsidiary or approved distributor
Internal Orders | DTN: 261-2010 603-791-2010 | Fax: 800-741-6970 | U.S. Software Supply Business Digital Equipment Corporation 8 Cotton Road Nashua, NH 03063-1260

# Chapter 1
Sockets Programming Interfaces

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 Sockets

# 1.1 OpenVMS System Services

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

- Faster application performance
- Flexibility
- Support for many different programming languages, including the following:

  MACRO-32 | VAX BLISS
  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.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 other platforms

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

# 1.3 Location of Application Development Files

Table 1-1 and Table 1-2 describe where to find the definition files and routine libraries 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
--- | ---
UCX$INETDEF.ADA | ADA definitions file
UCX$INETDEF.FOR | Fortran definitions file
UCX$INETDEF.H | C definitions file
UCX$INETDEF.MAR | MACRO definitions file
UCX$INETDEF.PAS | Pascal definitions file
UCX$INETDEF.PLI | PL/I definitions file
UCX$INETDEF.R32 | BLISS definitions file
UCX$INETDEF.BAS | BASIC definitions file

Table 1-2 C Socket Routine Libraries --- SYS$LIBRARY:
File | Description
--- | ---
UCX$IPC_SHR.EXE | C Socket run-time library
UCX$IPC.OLB | C Socket object library

Table 1-3 and Table 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 --- UCX$EXAMPLES:
File | Description
--- | ---
UCX$UDP_SERVER_IPC.C¹ UCX$UDP_CLIENT_IPC.C | Examples of a UDP/IP client and server using the IPC socket interface.
UCX$UDP_SERVER_QIO.C UCX$UDP_CLIENT_QIO.C | Examples of a UDP/IP client and server using QIO calls.
UCX$UDP_CLIENT_QIO.MAR UCX$UDP_SERVER_QIO.MAR | UDP client and server MACRO example

¹See Appendix A for a printed example of this program.

Table 1-4 TCP Programming Examples --- UCX$EXAMPLES:
File | Description
--- | ---
UCX$IOCTL_ROUTINE.C | An implementation of the UNIX ioctl call. This is not intended to be a full ioctl implementation. Only the functions related to inet are of interest.
UCX$TCP_SERVER_IPC.C¹ UCX$TCP_CLIENT_IPC.C¹ | Examples of a TCP/IP client and server using the IPC socket interface.
UCX$TCP_SERVER_IPC_AUXS.C¹ | An example of a TCP/IP server using the IPC socket interface which accepts a connection from the auxiliary server.
UCX$TCP_SERVER_QIO.C¹ UCX$TCP_CLIENT_QIO.C | Examples of a TCP/IP client and server using QIO calls.
UCX$TCP_SERVER_QIO_2ND.C UCX$TCP_CLIENT_QIO_2ND.C | Another example of a TCP/IP client and server using QIO calls.
UCX$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.
UCX$TCP_SERVER_QIO_AUXS_2ND.C UCX$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.
UCX$TCP_SOCKET_QIO_3RD.H UCX$TCP_SOCKET_QIO_3RD.C UCX$TCP_SERVER_QIO_3RD.C UCX$TCP_CLIENT_QIO_3RD.C | Module UCX$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 UCX$TCP_SERVER_QIO_3RD.C and UCX$TCP_CLIENT_QIO_3RD.C build with module UCX$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 UCX$TCP_SOCKET_QIO_3RD.C.
UCX$TCP_CLIENT_QIO.MAR UCX$TCP_SERVER_QIO.MAR | TCP client and server MACRO example
UCX_SECURITY_DRIVER.MAR | Internet security driver example

¹See Appendix A for a printed example of this program.

> Note

> The symbols UCX$, INET$, and INET_PROTYP$ are used throughout this book. The examples were left unchanged for compatibility with the include files delivered with this product.

# Chapter 2
Writing Internet Applications

You can use either the OpenVMS system services or the C Socket interface to write TCP/IP applications that run on your corporate internet. These applications consist of a series of system calls that perform tasks, such as creating a socket. These system calls are direct entry points that the client and server processes use to obtain services from the kernel software. System calls look and behave exactly like other procedural calls, taking arguments and returning one or more results. These arguments can contain values or pointers to objects in the application program.

This chapter describes the process followed by communicating client and server machines. This is the same process that an application developer follows when using system calls to write internet applications. The chapter also includes C Socket and OpenVMS system services example routines for each step in the communication process.

> Note

> The OpenVMS and C Socket programming examples are located in the UCX$EXAMPLES library.

# 2.1 The Client/Server Communication Process

The most commonly used paradigm in constructing distributed applications is the client/server model. The requester, known as the client, sends a request to a server and waits for a response. The server is an application-level program that offers a service that can be reached over the network. Servers accept requests that arrive over the network, perform their service, and return the result to the client.

In addition to having a client and a server, the connection also has a mode of communication. This variable can be either connection-oriented or connectionless. When writing internet applications, the developer uses the mode of communication required by the application-level service. Therefore, if the application-level service uses the connection-oriented mode of communication, the developer uses the virtual circuit or the Transmission Control Protocol (TCP) approach. If the application-level service uses the connectionless mode of communication, then the developer uses the datagram or the User Datagram Protocol (UDP) approach.

Figure 2-1 shows the communication process for a TCP client/server internet application.

Figure 2-1 TCP Socket Communication Process

In this figure:

1. (1) Server and client create a device socket.
2. (2) Server and client bind the socket name.
3. (3) Server defines a listener.
4. (4) Client sends a connection request.
5. (5) Server accepts the connection request.
6. (6) Server receives device information from the local host.
7. (7) Data exchange takes place.
8. (8) Server and client delete the device socket.

Table 2-1 identifies the basic calling sequence, the C socket routine, and the equivalent system service routine for server applications that use TCP.

Table 2-1 TCP Server Calling Sequence and Related Routines
Task | C Socket Routine | OpenVMS System Service Routine
--- | --- | ---
Create a device socket | socket() | $ASSIGN $QIO(IO$_SETMODE)¹
Bind socket name | bind() | $QIO(IO$_SETMODE)¹
Define listener device socket | listen() | $QIO(IO$_SETMODE)¹
Accept connection request | accept() | $QIO(IO$_ACCESS)
Exchange data | read() recv() recvmsg() | $QIO(IO$_READVBLK)
| write() send() sendmsg() | $QIO(IO$_WRITEVBLK)
Shut down the socket (optional) | shutdown() | $QIO(IO$_DEACCESS|IO$M_SHUTDOWN)
Close and delete the socket | close() | $QIO(IO$_DEACCESS) $DASSGN

¹The $QIO system service calls for creating a socket, binding a socket name, and defining an internet pseudodevice as a listener are listed as three separate calls in this table. You can do all three steps with one IO$_SETMODE call.

Table 2-2 describes the basic calling sequence for client applications that use TCP.

Table 2-2 TCP Client Calling Sequence and Related Routines
Task | C Socket Routine | OpenVMS System Service Routine
--- | --- | ---
Create a device socket | socket() | $ASSIGN $QIO(IO$_SETMODE)¹
Bind socket name | bind() | $QIO(IO$_SETMODE)¹
Connect to server | connect() | $QIO(IO$_ACCESS)
Exchange data | read() recv() recvmsg() | $QIO(IO$_READVBLK)
| write() send() sendmsg() | $QIO(IO$_WRITEVBLK)
Shut down the socket (optional) | shutdown() | $QIO(IO$_DEACCESS|IO$M_SHUTDOWN)
Close and delete the socket | close() | $QIO(IO$_DEACCESS) $DASSGN

¹The $QIO system service calls for creating a socket and binding a socket name are listed as two separate calls in this table. You can do both steps with one IO$_SETMODE call.

Figure 2-2 shows the communication process for a UDP client/server internet application.

Figure 2-2 UDP Socket Communication Process

In this figure:

1. Server and client create a device socket.
2. Server and client bind the socket name.
3. Data exchange takes place.
4. Server and client delete the device socket.

Table 2-3 identifies the basic calling sequence, the system service routine, and the equivalent C Socket routine for server applications that use UDP.

Table 2-3 UDP Server Calling Sequence and Related Routines
Task | C Socket Routine | OpenVMS System Service Routine
--- | --- | ---
Create a device socket | socket() | $ASSIGN $QIO(IO$_SETMODE)¹
Bind socket name | bind() | $QIO(IO$_SETMODE)¹
Specify port for incoming datagrams | recvfrom() | $QIO(IO$_ACCESS)
Exchange data | read() recv() recvfrom() recvmsg() | $QIO(IO$_READVBLK)
| write() send() sendto() sendmsg() | $QIO(IO$_WRITEVBLK)
Shut down the socket (optional) | shutdown() | $QIO(IO$_DEACCESS|IO$M_SHUTDOWN)
Close and delete the socket | close() | $QIO(IO$_DEACCESS) $DASSGN

¹The $QIO system service calls for creating a socket and binding a socket name are listed as two separate calls in this table. You can do both steps with one IO$_SETMODE call.

Next | Contents