Marc's Place

1 TCP_IP_Services (1)
The DIGITAL TCP/IP Services for OpenVMS product, often referred
to as "UCX," provides user and network services using the TCP/IP
protocol.

For help on the management commands, type:

$ UCX HELP

2 Product_Overview

The Transmission Control Protocol/Internet Protocol (TCP/IP)
suite is a set of communication protocols that work together to
provide computer networking.

DIGITAL TCP/IP Services for OpenVMS (UCX) is Digital's
implementation of TCP/IP protocols and services for the OpenVMS
operating system. DIGITAL TCP/IP Services for OpenVMS consists of
the following components:

Kernel (see Kernel)
Network services (see Network Services)
Network File System (NFS) (see NFS)
End-user services (see User Services)

3 RFC_Compliance

The body of information called Request For Comments (RFC) is
a series of documents, begun in 1969, that describes Internet
protocols and related experiments. All Internet standards are
written as RFCs.

RFC 1208 defines the Internet. The Internet is the public
network consisting of many large networks that use the TCP/IP
protocol suite. It provides universal connectivity, reaching
the Defense Advanced Projects Research Agency (DARPA) Internet,
MILNET, NSFnet, CREN, and many worldwide universities, government
research labs, military installations, and business enterprises.

In contrast, internet means any interconnected networks using the
TCP/IP protocols, functioning as one, virtual network.

The following RFCs are significant to the various components of
DIGITAL TCP/IP Services for OpenVMS:

Table 3-1 RFCs Used by UCX

Protocol Number Title

ARP RFC 826 Ethernet Address Resolution Protocol: Or
Converting Network Protocol Addresses to
48.bit Ethernet Address for Transmission on
Ethernet Hardware
BOOTP RFC 951 Bootstrap Protocol
RFC 1048 BOOTP Vendor Information Extensions
RFC 1084 BOOTP Vendor Information Extensions
CSLIP RFC 1144 Compressing TCP/IP Headers for Low-Speed
Serial Links
DNS, RFC 819 Domain Naming Convention for Internet User
BIND Applications
RFC 920 Domain Requirements
RFC 974 Mail Routing and the Domain System
RFC 1032 Domain Administrator's Guide
RFC 1033 Domain Administrator's Operations Guide
RFC 1034 Domain Names - Concepts and Facilities
RFC 1035 Domain Names - Implementation and
Specification
RFC 1101 DNS Encoding of Network Names and Other Types
RFC 1183 New DNS RR Definitions
RFC 1400 Transition and Modernization of the Internet
Registration Service
RFC 1535 A Security Problem and Proposed Correction
with Widely Deployed DNS Software
RFC 1536 Common DNS Implementation Errors and Suggested
Fixes
RFC 1537 Common DNS Data File Configuration Errors
RFC 1591 Domain Name System Structure and Delegation
RFC 1597 Address Allocation for Private Internets
RFC 1637 DNS NSAP Resource Records
FTP RFC 959 File Transfer Protocol
ICMP RFC 792 Internet Control Message Protocol
IP RFC 791 Internet Protocol
NTP RFC 1059 Network Time Protocol (Version 1)
Specification and Implementation
RFC 1119 Network Time Protocol (Version 2)
Specification and Implementation
RFC 1305 Network Time Protocol (Version 3)
Specification and Implementation
NFS RFC 1094 NFS: Network File System Protocol
Specification
POP RFC 822 Standard for the Format of ARPA Internet Text
Messages
RFC 1082 Post Office Protocol Version 3: Extended
Service Offerings
RFC 1321 The MD5 Message-Digest Algorithm
RFC 1725 Post Office Protocol (Version 3)
PPP RFC 1331 The Point-to-Point Protocol (PPP) for the
Transmission of Multi-Protocol Datagrams over
Point-to-Point Links
RARP RFC 903 Reverse Address Resolution Protocol
RIP RFC 1058 Routing Information Protocol
RLP RFC 887 Resource Location Protocol
Routing RFC 1112 Host Extensions for IP Multicasting
RPC RFC 1057 RPC: Remote Procedure Call Protocol
Specification Version 2
SLIP RFC 1055 Nonstandard for Transmission of IP Datagrams
Over Serial Lines: SLIP
SMTP RFC 821 Simple Mail Transfer Protocol
RFC 822 Standard for the Format of ARPA Internet Text
Messages
SNMP RFC 1155 Structure and Identification of Management
Information for TCP/IP-Based Internets
RFC 1156 Management Information Base for Network
Management of TCP/IP-Based Internets
RFC 1157 A Simple Network Management Protocol
RFC 1158 Management Information Base for Network
Management of TCP/IP-based Internets: MIB-II
RFC 1212 Concise MIB Definitions
RFC 1213 Management Information Base for Network
Management of TCP/IP-based Internets: MIB-II
RFC 1214 OSI Internet Management: Management
Information Base
RFC 1215 Convention for Defining Traps for Use with the
SNMP
RFC 1442 Structure of Management Information for
Version 2 of the Simple Network Management
Protocol (SNMPv2)
RFC 1514 Host Resource MIB
RFC 1592 Simple Network Management Protocol Distributed
Protocol Interface
Sun RFC 1790 An Agreement between the Internet Society and
ONC Sun Microsystems, Inc. in the Matter of ONC
RPC, RPC and XDR Protocols
XDR
TELNET RFC 854 Telnet Protocol Specification
RFC 855 Telnet Option Specification
RFC 856 Telnet Binary Transmission
RFC 857 Telnet Echo Option
RFC 858 Telnet Suppress Go Ahead Option
RFC 859 Telnet Status Option
RFC 860 Telnet Timing Mark Option
RFC 861 Telnet Extended Options: List Option
TFTP RFC 1350 The TFTP Protocol
TP RFC 868 Time Protocol
TCP RFC 793 Transmission Control Protocol
UDP RFC 768 User Datagram Protocol
XDR RFC 1014 XDR: External Data Representation Standard

3 Kernel

The UCX kernel consists of the following software:

Network device drivers
Serial Line IP (SLIP), Compressed SLIP (CSLIP), and Point-to-
Point Protocol (PPP)
Address Resolution Protocol (ARP)
Routing and transport
Auxiliary Server (INETd)
BIND Resolver (BIND Client)
Application programming interfaces (APIs)
Management tools
Other utilities

4 Network_Device_Drivers

Software drivers connect the communication hardware to the
communication software. Drivers are also called device drivers,
communication drivers, and network drivers. UCX includes the
following network drivers:

o Internet Device Driver (BG Driver) - Software interface
between the OpenVMS operating system and your host's network
controller device, such as an Ethernet controller or an FDDI
controller

o INET Driver - Network interface for customer-developed
applications that use the CMU / TEK $QIO interface

o DNFS Driver - Network interface for the NFS Client

o PWIP Driver - Network interface for PATHWORKS[TM] and
DECnet-Plus for OpenVMS

o TN Driver - Network interface for the TELNET Server

DIGITAL TCP/IP Services for OpenVMS bundles the PATHWORKS[TM]
Internet Protocol (PWIP) Driver and the PATHWORKS network
ancillary control process (ACP). This software provides TCP/IP
options to PATHWORKS clients.

4 SLIP,_CSLIP,_and_PPP

DIGITAL TCP/IP Services for OpenVMS implements the Serial Line
IP (SLIP), Compressed SLIP (CSLIP), and Point-to-Point Protocol
(PPP) protocols. SLIP and PPP are used to create point-to-point
serial connections.

Use SLIP to connect across a serial line, rather than an
Ethernet, FDDI, or Token Ring LAN. Each end of the link requires
SLIP software. You can use any standard OpenVMS terminal device
as a SLIP line.

Use the PPP datalink available with OpenVMS Alpha to connect
point-to-point across a serial line. Making connections with
PPP is similar to connecting with SLIP. With PPP, the network
interface is the modem connection. You can use any standard
OpenVMS terminal device as a PPP line. If the remote system is
configured as a gateway to a network, you can also reach other
systems on the network.

CSLIP provides header compression, especially beneficial for
small packets. Header compression improves packet throughput.

DIGITAL TCP/IP Services for OpenVMS supports the following SLIP
configurations:

o Dedicated (hard-wired)

o Dialups in which the DIGITAL TCP/IP Services for OpenVMS host
originates the connection

o Dialups in which the DIGITAL TCP/IP Services for OpenVMS host
answers calls and establishes remotely initiated connections

SLIP is a packet-framing protocol that defines a sequence of
characters that frame IP packets on a serial line. SLIP has the
following characteristics:

o Provides reliable use of serial lines for connecting TCP/IP
hosts and routers.

o Allows mixes of hosts and routers to communicate. Host-to-
host, host-to-router, and router-to-router are common SLIP
network configurations.

o Allows you to run only one protocol (TCP/IP) over a SLIP
connection.

o Provides no addressing, packet type identification, error
detection, error correction, or compression mechanisms.

DIGITAL TCP/IP Services for OpenVMS supports the following PPP
connections:

o Dedicated, low-speed connections between local hosts, such as
between a laptop computer and an Alpha workstation connected
by a serial line.

o Dialups in which the DIGITAL TCP/IP Services for OpenVMS host
originates the connection

o Dialups in which a remote host to the host system

4 ARP

The Address Resolution Protocol (ARP) implementation dynamically
maps an IP address to the physical hardware address of a
broadcast medium. The broadcast medium can be, for example, an
Ethernet controller, an FDDI controller, a Token Ring controller,
or a terminal server.

ARP is limited to one physical network, and that network must
support hardware broadcast.

4 Routing_and_Transport

DIGITAL TCP/IP Services for OpenVMS implements the following
routing and transport protocols:

Internet Protocol (IP)
Routing Information Protocol (RIP)
Internet Control Message Protocol (ICMP)
Transmission Control Protocol (TCP)
User Datagram Protocol (UDP)

5 IP

The Internet Protocol (IP) software is a connectionless packet
delivery service. An IP datagram is a packet that has no delivery
receipt and is connectionless in that it does not maintain state
information about successive datagrams.

The IP implementation sends or routes data across the network
from its source to its destination by means of internetwork
addressing (IP address).

The IP address identifies the connection between the network
controller of a node and the network cable. It receives data
bits from the physical and data link layers, assembles the bits
into an IP datagram, and chooses the best route to send the
packet to its destination. The IP software also performs packet
fragmentation and re-assembly in the routing process.

5 RIP

The Routing Information Protocol (RIP) implementation enables
hosts to exchange current routing information about hosts and
directly connected networks. With RIP, hosts perform dynamic
routing. The hosts can select to receive or both send and receive
RIP messages.

5 ICMP

The Internet Control Message Protocol (ICMP) implementation
provides a number of diagnostic functions and handles error and
control messages. ICMP reports problems with data delivery to
gateways and hosts.

5 TCP

The Transmission Control Protocol (TCP) implementation provides
connection-oriented, reliable, sequenced data transfers between
hosts. Before the sender transmits data, both participants
must establish a connection. TCP guarantees that data reach its
destination, retransmitting data that does not get through.

5 UDP

The User Datagram Protocol (UDP) implementation provides
connectionless data transfers between hosts. UDP communications
are faster than TCP for applications that do not require delivery
receipts.

4 Auxiliary_Server

DIGITAL TCP/IP Services for OpenVMS implements INETd in the
Auxiliary Server. The Auxiliary Server does the following:

o Eliminates high overhead resulting from non-stop running of
all the services.

o Provides system security through the authentication of clients
when they request service.

o Supports event and error logging.

4 BIND_Resolver

The Berkeley Internet Name Domain (BIND) Service provides
translation of host names into IP addresses and IP addresses
into host names. The BIND Resolver is the client software that
requests host names, addresses, and other network information
from BIND Servers.

4 APIs

DIGITAL TCP/IP Services for OpenVMS includes the following
application programming interfaces (APIs) for customized
applications development:

$QIO
SRI $QIO
Standard C sockets interface and C sockets library
Sun Open Network Computing (ONC) RPC

5 $QIO

This API extends OpenVMS System Services for socket
communications. Sockets provide access to IP, TCP, and UDP. $QIO
supports all programming languages.

You can write programs that implement IP multicasting.

5 SRI_$QIO

This API is an SRI $QIO emulator that translates older, non-UCX
$QIO interfaces (first developed at Stanford Research Institute
(SRI) in 1980 through 1981) into $QIO programming interfaces.

You can write programs that implement IP multicasting.

5 Sockets

The standard C sockets API and C sockets library provide UNIX-
like access to TCP, UDP, and raw IP. The C sockets interface
supports the C programming language, which aids portability of
applications between OpenVMS and UNIX systems.

This API is integrated with both the DEC C run-time library and
VAX C run-time library.

You can write programs that implement IP multicasting.

5 RPC

DIGITAL TCP/IP Services for OpenVMS implements the Sun Open
Network Computing (ONC) Version 4.2 Remote Procedure Calls
(RPCs) Protocol. The set of ONC RPCs is a portable API and
provides an efficient alternative to developing applications
with sockets. You can program with this API using all data types,
regardless of their byte order, floating-point presentation,
string representation, or alignment.

This RPC is backward-compatible with older RPC sources provided
by DIGITAL TCP/IP Services for OpenVMS. DIGITAL TCP/IP Services
for OpenVMS links this API with DECC$SHR (not with VAXCRTL). Note
that:

- OpenVMS VAX systems support both DEC C and VAX C.

- OpenVMS Alpha systems support only DEC C.

4 Management_Tools

DIGITAL TCP/IP Services for OpenVMS (UCX) includes the following
network management tools:

o Management control program with a command-line interface,
event logging, and error and information messages

o Configuration procedure (see the DIGITAL TCP/IP Services for
OpenVMS Installation and Configuration manual)

o Trace utility

o Clean-up utility (see the DIGITAL TCP/IP Services for OpenVMS
Installation and Configuration manual)

o Logical names

o Startup and shutdown procedures

o NSLOOKUP utility

o SNMP and the Extensible SNMP (eSNMP)

o Remote Magnetic Tape (RMT) and Remote CD-ROM (RCD) services

3 Network_Services

DIGITAL TCP/IP Services for OpenVMS offers the following network
services:

o DNS (BIND Server) software for host-name-to-address
translation

o Bootstrap Protocol (BOOTP) Server software for remote booting
of requesting hosts

o Trivial File Transport Protocol (TFTP) server software for
remote booting of requesting hosts

o Network Time Protocol (NTP) software for time synchronization
and authentication

o Portmapper for mapping requesting applications to port numbers

o Simple Network Management Protocol (SNMP) Agent for remote
network management

o Printing services

o Remote Line Printer (LPR) and Line Printer Daemon (LPD)

o PC-NFS Print Server

o TELNET Print Symbiont (TELNETSYM)

4 BIND_Server

The Berkeley Internet Name Domain (BIND) Service (DNS) is an
internet name service that does host-name-to-address lookups
and reverse (address-to-host-name) lookups. The client is called
the Resolver, and the server is known as a BIND Server, a name
server, and DNS (Domain Name Service).

Name servers maintain databases of host names, addresses, mail
records, text records, and other network objects. Name servers
supply this information for client systems, who query the servers
with their BIND Resolver.

4 BOOTP

The Bootstrap Protocol (BOOTP) software is also known as remote
boot. With BOOTP, a diskless host can identify its IP address,
the address of a file server on which it can store and retrieve
data, and the address of the nearest IP gateway.

If BOOTP cannot identify a requesting client, BOOTP ignores the
request.

4 TFTP

The Trivial File Transfer Protocol (TFTP) Server software
is a cost-effective, unsophisticated file transfer service.
It is appropriate for applications that do not need complex
interactions between a client and server. TFTP is small and can
be encoded into read-only memory.

With TFTP, BOOTP can use the same underlying protocols that the
operating system uses once it begins execution. This design
allows one host to bootstrap from a server on another physical
network.

With BOOTP and TFTP, DIGITAL TCP/IP Services for OpenVMS
can download system images and other types of information to
requesting client hosts.

4 NTP

The Network Time Protocol (NTP) implementation synchronizes
timekeeping and provides accurate time stamps. Hosts running
NTP can participate in a TCP/IP network with fully synchronized
time.

4 Portmapper

Each server process listens for connections on a designated port.
A client requesting a particular application can ask for it by
specifying the number of this designated port.

You can configure the following applications to register
themselves with the Portmapper Service:

o Programs that use Sun RPCs

o NFS and PC-NFS (Portmapper required)

o MOUNT (Portmapper required)

4 Printing_Services

DIGITAL TCP/IP Services for OpenVMS offers these network print
services:

o LPR and LPD

o PC-NFS Print Server

o TELNET Print Symbiont (TELNETSYM)

5 LPD_and_LPR

DIGITAL TCP/IP Services for OpenVMS provides network printing
with its Remote Line Printer (LPR) (outbound requests) and Line
Printer Daemon (LPD) (inbound requests) implementations. This
software supports:

o DCL PRINT command to printers on remote hosts (outbound
printing) - including utility queues that let you specify a
particular remote host and printer

o DCL LPQ command for the status of print jobs on remote hosts

o DCL LPRM command to remove print jobs from remote queues

o Retry capability for outbound jobs

o UNIX lpr commands issued from a remote UNIX host to print on
printers at your OpenVMS host

o UNIX lpq commands issued from a remote UNIX host to display
the status of the remote print queue located on your OpenVMS
host

o UNIX lprm commands issued from a remote UNIX host to remove
jobs from a remote print queue on your OpenVMS host

o Identification of PostScript[TM] files

o Print setup utility UCX$LPRSETUP

A print queue is either:

o Local, handling inbound jobs

o Remote, handling outbound jobs for remote printers

5 PC-NFS_Server

The PC-NFS Print Server includes the following features:

o Associating an MS-DOS printer device name with an OpenVMS
print queue on the host where the PC-NFS Server is running

o Printing a file to the associated queue

The features of getting status and deleting job requests have the
following limitations from a PC:

o Users cannot list jobs queued on the PC-NFS Server.

o Users cannot cancel jobs queued on the PC-NFS Server.

o Users cannot get a list of available print queues from the
PC-NFS Server.

o Users cannot get the status of a particular print queue on the
PC-NFS Server.

5 TELNET_Symbiont

The TELNET Print Symbiont (TELNETSYM) provides remote printing
using the TELNET Protocol. This service is achieved by attaching
a printer to a terminal server. TELNETSYM is particularly useful
in configurations with printers attached to terminal servers
that support the TELNET Protocol. TELNETSYM does not work with
terminal servers that use only the LAT Protocol.

TELNETSYM is a true OpenVMS print symbiont that performs all
print formatting. (This implementation differs from the LPD
Protocol, where the receiver of the print job does the print
formatting.) The local OpenVMS system drives the remote printer
as if it were directly connected.

4 SNMP

The Simple Network Management Protocol (SNMP) monitors networks
and remote hosts. DIGITAL TCP/IP Services for OpenVMS implements
the Agent portion of SNMP.

SNMP uses the network management data standard known as the
Management Information Base (MIB). The MIB specifies the data
items that a gateway or network must keep and the allowed
operations. For example, DIGITAL TCP/IP Services for OpenVMS
specifies that SNMP can read, but not modify, the number of
octets that are received. Remote system managers can only query
MIB data.

All SNMP operations relate to fetching and storing MIB data.

4 SNMP_Extensible_Agent_(eSNMP)

DIGITAL TCP/IP Services for OpenVMS provides support for
network management with the Extensible SNMP (eSNMP) software.
Extensibility means that a single agent can support any number of
subagents. The eSNMP software consists of an agent and subagents
that run on all network elements.

A management station is the entity on the TCP/IP network that
runs the agent software and maintains the managed information.
Network elements are entities such as hosts, routers, X
terminals, and terminal servers.

DIGITAL's implementation of the eSNMP software has an agent,
two subagents, and an application programming interface (API)
that enable developers to create subagents that manage other
entities in their networks. The two provided subagents support
the Internet Standard Management Information Base (MIB-II) as
defined by RFC 1213 and a portion of the Host Resource MIB as
defined by RFC 1514.

For complete information about eSNMP functionality, see the
DIGITAL TCP/IP Services for OpenVMS eSNMP Programming and
Reference manual.

3 NFS

The Network File System (NFS) protocols, developed by
Sun Microsystems, Inc., enable internet clients to access remote
files residing on NFS servers. NFS provides "transparent" user
access and is an efficient alternative to moving files physically
across the network.

The NFS component includes the following software:

o File system

o NFS Server

o NFS Client

o PC-NFS Server

4 Server

With the NFS Server running on an OpenVMS system, a remote user
can access files that physically reside locally. The user can
work from any host, irrespective of operating system, that runs
NFS Client.

OpenVMS supports index, relative, and sequential files that have
various record formats. The DIGITAL TCP/IP Services for OpenVMS
implementation of NFS supports the following record formats:

o Fixed length

o Variable length

o Variable with fixed-length control (VFC)

o Stream (including STREAM_LF and STREAM_CR)

o Undefined

4 File_System

The NFS file system is a logical file system. It is a collection
of UNIX-style file systems and OpenVMS file systems that are
organized as a single-level hierarchy. It has these OpenVMS file
system components:

o Top-level (sometimes called root) directory (Master File
Directory [MFD])

o Lower-level directories

o All the files in those directories

o Some internal system files

The container file system (CFS) run-time library is an OpenVMS
run-time library that is used by both the NFS Server process and
DIGITAL TCP/IP Services for OpenVMS to process files within the
container file system.

4 Client

The NFS Client running on OpenVMS makes file-operation requests
by contacting a remote NFS Server. The server then performs the
requested operation. The server host can be any operating system
that runs NFS Server.

The NFS Client supports STREAM_LF formatted files.

4 PC-NFS

The DIGITAL TCP/IP Services for OpenVMS implementation of PC-NFS
provides the following print services to personal computers (PCs)
running NFS Client software.

o Authentication

NFS security is maintained by identifying every user with a
user identification / group identification (UID/GID) pair.
PCs lack this information. A PC that wants to request access
to an NFS Server must first get its UID/GID from a remote
Authentication Server. As an Authentication Server, DIGITAL
TCP/IP Services for OpenVMS stores this information in its
Proxy Database and sends it to requesting PC users.

o Printing

3 User_Services

DIGITAL TCP/IP Services for OpenVMS includes the following client
and server end-user services:

o Finger utility (FINGER command)

o File Transfer Protocol (FTP)

o Simple Mail Transfer Protocol (SMTP) and Post Office Protocol
(POP) services

o Network printing commands: DCL PRINT, LPQ, LPRM

o Remote commands: RCP, RLOGIN, RSH, and REXEC

o TELNET and IBM 3270 model terminal emulation (TN3270)

4 Finger

The Finger utility lets users display information about users on
remote or the local host. In specific, a user can use the FINGER
command to:

o Display brief information about all users on a host

o Display detailed information about one or more specific users
on a host

o Display information about all users logged in to the local
cluster

o Make planning and project information about yourself available
to other Finger users

The user information displayed by the FINGER command may include
the following, depending on the server:

o User name

o Account name

o Program the user is running

o User's home directory

o User's plans, activities, and other information

o User's project

4 FTP

The File Transfer Protocol (FTP) software lets users:

o Transfer remote files bidirectionally from one system to
another

o Set and display the default (working) directory on the local
or remote host

o Display the contents of files on the local or remote host

o List remote directories

o Delete remote files

o Rename remote files

o Perform file transfers using wildcard characters

o Print local files at a remote printer, or remote files at a
local printer

FTP also provides authentication control. Clients must correctly
enter a login name and password to the server before they can
request file transfers.

The FTP Client includes the DCL FTP command and FTP commands
within the FTP utility. These FTP commands offer two command-line
interfaces: UNIX style and OpenVMS style.

5 Anonymous_User_Access

With FTP, users who do not have a login name or password can
access designated remote files on a system using an anonymous
name. Anonymous FTP can be configured as follows:

o Users cannot browse through the remote file system. They have
access only to the anonymous guest, or "home," directory and a
public directory.

The public directory can contain general bulletin information
to which the user has read-only access.

o Users are limited to GET (read) and PUT (copy), with
additional limitations to the files that they can copy, in
the guest directory.

o Users can GET files only from the public directory.

o Users can delete only the files in the guest directory owned
by the anonymous account.

4 Remote_(R)_Commands

DIGITAL TCP/IP Services for OpenVMS includes client and server
implementations of these Berkeley Remote (R) commands: RCP,
RLOGIN, RSH, and REXEC. These services let users gain access
to remote internet hosts.

5 RCP

The RCP command copies files between internet hosts. Users can
copy files:

o From remote hosts

o To remote hosts

o From one remote host to another

As an RCP Server, DIGITAL TCP/IP Services for OpenVMS responds
to any operating system running RCP Client. As a client, DIGITAL
TCP/IP Services for OpenVMS includes the DCL RCP command, which
offers the following options:

o Copy and maintain the same file name.

o Copy and change the file name.

o Preserve the source file's protections.

o Preserve the source file's modification date.

o Log the FTP session.

o Copy all the files under a specified directory and preserve
the directory hierarchy.

If subdirectories exist beneath the source directory, they are
also copied into created subdirectories on the other host.

Depending on how the network manager sets up security, a user can
issue RCP in one of the following ways:

o Without specifying a user name

o Without specifying a user name or a password

o Specifying both user name and password

5 RLOGIN

The RLOGIN command allows server users to log in to a remote host
and work as if they were directly connected. You can configure
RLOGIN to pass security information to the client. This feature
is called RLOGIN proxy. If you do not configure RLOGIN to pass
security information to the client, the remote host prompts the
user for login information.

As an RLOGIN Server, DIGITAL TCP/IP Services for OpenVMS responds
to any operating system running RLOGIN Client. As a client,
DIGITAL TCP/IP Services for OpenVMS includes the DCL RLOGIN
command.

5 RSH

RSH connects a user's terminal to a remote host so that the
user can send a command, shell script, or command procedure for
execution at that system without logging in. Using the /PASSWORD
qualifier invokes REXEC.

5 REXEC

REXEC authenticates and executes the commands that users issue
for execution at a remote host. The authentication is based
on password information stored in the OpenVMS system's User
Authorization File (UAF).

The REXEC feature is useful if the remote host does not have, or
might not have, the authentication information that RSH requires.
Users invoke REXEC by issuing RSH /PASSWORD.

4 SMTP

The Simple Mail Transfer Protocol (SMTP) server and client
software transfers electronic mail messages between systems.
SMTP specifies how these systems interact and the format of the
mail messages they exchange. SMTP uses the OpenVMS Mail utility.

To send mail with SMTP, users issue the DCL MAIL command and
specify the fully qualified Internet address as the destination.
By default, Internet addresses that are not fully qualified
(that is, whose node component does not include a period (.),
such as MALCOLM@PHILOS), are converted to a format for DECnet
transport (for example, PHILOS::MALCOLM). To force messages with
such addresses to be sent over SMTP, do one of the following:

o Specify the fully qualified Internet address (such as
MALCOLM@PHILOS.BU.EDU)

o Prefix the address with SMTP% followed, without a space, by
the destination address, enclosing the address in quotation
marks (for example, SMTP%"MALCOLM@PHILOS")

o Set the logical MAIL$INTERNET_MODE to SMTP and make sure the
MAIL$INTERNET_TRANSPORT logical does not define an alternate
Internet protocol)

With the Post Office Protocol (POP) functionality, you can
receive and send OpenVMS mail from your PC. POP is a mail
repository that accepts and stores your mail even when the PC
is turned off. At your request, the POP server reads mail from
your OpenVMS NEWMAIL folder, then moves the mail to your MAIL
folder.

4 Network_Printing

The Line Printer/Line Printer Daemon (LPR/LPD) of the DIGITAL
TCP/IP Services for OpenVMS software supports the DCL PRINT, lpr,
LPQ, and LPRM commands for remote printing.

The LPR/LPD service allows users to print to queues on remote
hosts. The service also allows users on remote hosts to access
queues on the local host system.

4 TELNET

The TELNET Server and Client software provides remote terminal
connections. With TELNET, users work in remote system accounts as
if their terminals were connected directly to the remote system.

The DIGITAL TCP/IP Services for OpenVMS implementation of the
TELNET Client offers a user simultaneous multiple sessions and
IBM 3270 model terminal emulation (TN3270). The TELNET Client
includes:

o DCL TELNET command

o DCL TN3270

o TELNET commands within the TELNET utility

These TELNET commands offer two command-line interfaces: UNIX
style and OpenVMS style.

2 User_Services

Some of the DIGITAL TCP/IP Services for OpenVMS facilities
provide similar capabilities. The following table helps you
determine the best facility to use for your specific needs and
indicates where to look for information about that facility. The
following table helps you determine the best facility to use for
your specific needs.

Table 1 Facilities to Use for Specific Needs

To obtain user information, if you need to... Use...

Get information about users logged in to a FINGER
remote host, such as their login user names,
current program being used, and last login.
Get information about users logged in to your FINGER/CLUSTER
OpenVMS Cluster.

To copy files, if you need to... Use...

Perform other operations on the files, such FTP
as deleting, renaming, appending, and viewing
files.
Copy multiple files to or from one or more FTP
unrelated directories on the remote host.
Copy every file and subdirectory in a directory RCP
on a host, preserving the directory hierarchy.
Create or delete directories, and display the FTP
contents of directories.
Copy files between two remote hosts. RCP
Perform fast file transfers between two OpenVMS FTP
hosts.
Copy files to and from a remote UNIX system, FTP
preserving RMS file attributes.
Copy files, preserving the protection mode and RCP
modification date.
Copy and work with files using DECnet file FTP
specifications.

To print files, if you need to... Use...

Send local files to a remote host printer. FTP PUT, DCL
PRINT
Send remote files to your local host printer. FTP GET
Send local files to a remote host printer DCL PRINT
or print queue, using the OpenVMS printing
options such as customizing the printed page
with special print forms, specifying the number
of copies to print, and so forth.
Display the status of remote print queue jobs LPQ, LPRM
and cancel print jobs in that queue.
Send remote UNIX files to a local print queue. lpr

To log in to remote accounts, if you need to... Use...

Log in to a remote host that runs Remote (R) RLOGIN
protocols.
Log in to a remote host, using many options TELNET
to customize the session, control output from
the remote host, and negotiate compatibility
differences.
Establish multiple, simultaneous login TELNET
connections with one or more hosts, and toggle
between the sessions.
Log in using IBM 3270 Information System (IDS) TN3270
terminal emulation with a host that uses IBM
3270 model terminals.

To issue remote commands, if you need to... Use...

Issue a command on a remote host, including a RSH, REXEC
command that invokes a remote shell script or
command procedure, with any output displayed at
your terminal.
Issue a command, without specifying user RSH
authentication information, on a remote host
that has authentication files.
Issue a command and password to a host that RSH/PASSWORD
does not have authentication files for you.

To send and receive mail, if you need to... Use...

Send mail to, and receive mail from, a remote MAIL
host using SMTP.
Send and receive OpenVMS mail, at your PC. MAIL, POP

3 Working_with_Files

FTP allows you to establish a session with the remote host and
enter an unlimited number of commands that copy, display, or
manipulate files and directories. The Anonymous FTP feature
allows you to connect to a remote host without specifying user
authentication information. If that feature is not enabled, you
must supply user authentication information for a remote host
only once: when you first establish the FTP connection with the
remote host. FTP allows you to determine or change the working
directory on your host and on the remote host, and to perform
various other operations on files and directories.

In contrast, RCP is limited to copying files. To copy files,
each RCP command that you enter establishes a separate link
for each file transfer with the specified remote host. With
each RCP command, you must specify the remote host to or from
which you want to copy files. As with FTP, RCP has a feature
that allows you to connect to remote hosts without specifying
user authentication information. However, if that feature is not
enabled, you must enter user authentication information with each
RCP command, rather than just once (as with FTP) for any number
of subsequent commands for a connected host.

3 Remote_Logins

The RLOGIN, TELNET, and TN3270 facilities each allow you to log
in to a remote host and enable your terminal to perform as if
directly connected to the remote host. Use RLOGIN for simple
logins in which you do not require much customization or control
of the terminal-to-host interaction. Use TELNET if you want to
use its extensive terminal features and controls, or you want
to open several terminal sessions with one or more remote hosts.
With TELNET's extensive functionality, it can support a wider
variety of terminal features and behaviors between disparate,
otherwise incompatible, systems.

Use TN3270 to connect your terminal to a remote host that
supports IBM 3270 IDS terminals. TN3270 assigns IBM 3270
functions to your DIGITAL keyboard and allows you to redefine
keys.

3 Remote_Commands

RSH and REXEC allow you to send any commands supported by the
remote host operating system. RSH and REXEC issue one command
per link. If user authentication is required, you must enter the
authentication information with each command. There is no REXEC
command. You invoke REXEC when you enter the RSH command with a
password (RSH/PASSWORD).

Note that RLOGIN, TELNET, and TN3270 allow you to log into
a remote host once and then perform any number of commands
supported by the remote host's operating system. TELNET and
TN3270 also allow you to send certain commands to the connected
remote host during a terminal session; however, these are a
limited range of commands dealing with communication between
hosts. They are not operating system commands. For example, you
can send a command that aborts output or interrupts execution of
a command you issued previously.

2 Client-Server

The TCP/IP Services for OpenVMS user services include client
and server software that communicates between host systems.
Your local host includes client software that responds to your
commands by requesting the appropriate services from the remote
host you specify. If the remote host has the appropriate server
software, the server on that host responds with the requested
service.

2 Release_Notes

The DIGITAL TCP/IP Services for OpenVMS Release Notes are in the
file:

SYS$HELP:UCX042.RELEASE_NOTES

2 Getting_Started

The FTP, TELNET, and TN3270 utilities include a wider variety of
commands than do the other user services.

You can start FTP, TELNET, or TN3270 and connect to a remote host
interactively in either of two ways:

o Specify the utility name followed by a Return. The utility's
prompt appears, and you can then enter the CONNECT command.
For example, to start FTP and connect to a remote host named
FATHM, type:

$ FTP <RETURN>
FTP> CONNECT FATHM
.
.
.
FTP>

o Specify the utility name and host name in one line, as in the
following example:

$ FTP FATHM<RETURN>
.
.
.
FTP>

In either case, you are prompted for user authentication
information. (FTP includes a feature that allows you to
connect to a remote host without specifying user authentication
information). You can also start these utilities by using a
command procedure.

Start the Remote (R) and network printer services by specifying
the appropriate command, host name, and parameters or qualifiers
in one command line. If you specify the service command only
(RCP, RSH, RLOGIN, PRINT, LPQ, or LPRM), the service will prompt
you for the information required for the command. The PRINT
command supports remote printing, using TCP/IP protocols and
supporting the DCL PRINT qualifiers, with a few exceptions and
additional features.

When you enter the FINGER command without any host or user
information, the service displays information about users on
your local system. To display information about remote users, you
need to specify the remote host name.

To start MAIL and then send a message to a user on another
internet host, simply start the OpenVMS Mail utility as you
normally do, and use the SEND command with the Internet address
of the remote host, such as in the following example. The Mail
utility will use the SMTP protocol to send the mail.

$ MAIL
MAIL> send <Return>
To: MALCOLM@PHILOS.BU.ORG <Return>
Subj: FINAL EXAMS<Return>

For more help on using DIGITAL TCP/IP Services for OpenVMS
commands, use the DCL HELP TCP_IP_SERVICES command; for example,

$ HELP TCP_IP_SERVICES TELNET

The FTP, TELNET, and TN3270 utilities also provide help at the
utility prompt; for example,

TELNET> HELP

For an introduction to the features and services provided by the
DIGITAL TCP/IP Services for OpenVMS product, see the Overview
topic.

For tutorial information about how to use the various services,
see the individual help topics for those services.

2 Command_Syntax

Help available for general command syntax topics is listed below.

3 Command_Formats

Most UCX command descriptions specify both a DCL-style format
and a UNIX-style format. You can, therefore, type command lines
in either format. For example, the following two command lines
achieve the same results:

TELNET> CONNECT BENTLEY
TELNET> open bentley

3 Abbreviate_Keywords

You can abbreviate commands and qualifiers to the fewest number
of characters, usually three, that uniquely identifies the
keyword. For example, the following two command lines achieve
the same results:

$ RL RENT /USE=BUNNINGS
$ RLOGIN RENT /USER_NAME=BUNNINGS

3 Quotation_Marks

Due to differences in OpenVMS and UNIX syntax, some command
lines require quotation marks for selected keywords. These
requirements apply to case sensitivity, slashes, and certain
special characters (such as &, =, and \).

UNIX is case sensitive; UNIX host names, user names, and
passwords are usually lowercase. All UNIX directory names contain
slashes. For the requirements for individual services, see the
discussion of quotation marks under each major user service topic
(Finger, FTP, R_commands, Network_Terminals, Mail, or Network_
Printing).

3 Name_or_Address

Unless otherwise stated, whenever you specify a host on a command
line, you can use either its relative name or its IP address.
The relative name of a host is a simple name that does not
include the fully qualified domain name. That is, it does not
include one or more periods (.). For example, the relative host
name VENDOR might have a fully qualified domain name such as
VENDOR.GOODS.IGCORP.COM. The following two examples show two
ways to issue the TELNET command to connect to host VENDOR at IP
address 17.22.3.4.

$ TELNET VENDOR
Trying...17.22.3.4
Connected to VENDOR.
Escape character is '^]'.

UNIX V5 (vendor.goods.igcorp.com)
login:

$ TELNET 17.22.3.4
Trying...17.22.3.4
Connected to 17.22.3.4.
Escape character is '^]'.

UNIX V5 (vendor.goods.igcorp.com)
login:

3 File_and_Directory_Names

When you specify OpenVMS directory names and file names, follow
OpenVMS file specification rules, as explained in the OpenVMS
documentation. Likewise, when you specify UNIX directory names and
file names, follow UNIX file specification rules, as explained in
the documentation supplied with the UNIX system.

3 Parameters:_Multiple_Values

To specify multiple values for command parameters, such as host
names and directories, follow these guidelines:

o Separate elements with commas.

o Wildcards are valid.

o A space between multiple elements is optional.

The following FTP GET command copies the files PROJ1.TXT and
GROUP1.TXT, using a comma to separate the file names in the
command line:

FTP> GET PROJ1.TXT, GROUP1.TXT

The following FTP GET command uses the asterisk (*) wildcard to
copy all files starting with the letters "PROJ1":

FTP> GET PROJ1*.*

3 Qualifiers:_Multiple_Values

To specify multiple values for qualifiers, enclose them in
parentheses as follows:

/qualifier=(value1,value2,value3 )

For example, the following LPRM command deletes three jobs from a
remote print queue:

$ LPRM EST_4_1997_Q /ENTRY=(555,556,558)

3 Numeric_Values

Unless stated otherwise, all values are decimal.

3 Brackets_and_Braces

Command format descriptions in this help include braces and
brackets. You should understand the meaning of the braces and
brackets:

o Braces ( { } ) - You must specify:

- At least one of the enclosed values, or

- All of the enclosed values (this case is always noted).
Example 1:

This example shows the format line for the FTP SET DEFAULT
command. The choices for the directory specification parameter
are enclosed in braces, which means that you must specify one
of these values (either an OpenVMS directory name or a UNIX
path name).

FTP> SET DEFAULT /LOCAL {vms_directory_name |
unix/path/name}
Example 2:

In this TELNET example, you must specify either CHAR or LINE.

TELNET> SET MODE {CHAR | LINE}

o Brackets ( [ ] ) - The enclosed values are optional.
Example 1:

The last two parameters for the TELNET CONNECT command are
enclosed in brackets, which means they are optional. In this
example, the port can be specified without a terminal type,
and the host without a port.

TELNET> CONNECT host [ port [terminal_type ] ]
Example 2:

The format of the RSH command shows that all the qualifiers
and the remote_command parameter are optional.

2 NSLOOKUP

The NSLOOKUP Facility lets you interactively query domain name
servers (BIND servers). This tool helps you set up and manage the
BIND server software. You can get the following information:

Host names and addresses on the local domain
Host names and addresses on remote domains
Host names that have mail exchanger (MX records)
Name servers for a specific zone

For information about individual NSLOOKUP commands, type:

$ $ RUN SYS$SYSTEM:UCX$NSLOOKUP
> HELP

3 Starting

Use the following command to start NSLOOKUP:

$ RUN SYS$COMMON:[SYSEXE]UCX$NSLOOKUP.EXE

3 Exiting

To exit from within interactive mode, type:

> <Ctrl/d>

3 Terminating_Lookups

To terminate the current lookup activity, type:

> <Ctrl/c>

3 Command_Guidelines

The command line length must be less than 256 characters.

Unrecognized commands are interpreted as a host name.

3 Modes_of_Operation

NSLOOKUP has two modes:

o Interactive mode

+ Queries name servers for information about hosts and
domains.

+ Asks for a printout of a list of hosts in a domain.

+ Use this mode if you have no arguments to provide. nslookup
queries the default BIND server.

+ To request a query to a specific BIND server, use a hyphen
(-) as the first argumentand the host name or IP address of
the name server as the second argument.

o Non-interactive mode

+ Queries for the name and IP address of a host or domain.

+ Use this mode when the name or IP address of the host that
you are looking up is the first argument.

+ The optional second argument specifies a name server.

2 Tracing

The UCX$TRACE utility lets you trace packet flow between the
local UCX host and remote hosts. You can either monitor all
packet flow or use the various qualifiers to monitor only those
packets of interest.

3 Starting

To start the UCX$TRACE utility use the TCPIPTRACE command:

$ TCPIPTRACE HOST1 /FULL /PACKETS=30

3 Stopping

To stop the UCX$TRACE utility use CTRL/C.

2 Programming_Interfaces

UCX includes a standard C sockets API and a standard Open Network
Computing Remote Procedure Call (ONC RPC) API.

The standard C socket API provides UNIX-style access to the TCP
and UDP transports and to the IP network layer.

The ONC RPC library provides a method of creating communicating
programs without the need to program the details of the transport
protocol being used. The ONC RPC library is divided into calls
frequently used by client programs, calls used to access the
Portmapper utility, and calls frequently used by server programs.
The ONC RPC library also includes XDR routines which provide the
ability to transport data over the network in a standard fashion.

3 RPC_Client_Routines

Client routines allow C programs to make procedure calls to
server programs across the network.

Important: In order to maintain uniqueness for the OpenVMS HELP
utility, some client routines have a "_#" appended at the end. Do
not use the "_#" when coding the routine in a program.

4 auth_destroy

A macro that frees the memory associated with the authentication
handle created by the authnone_create and authunix_create
routines.
Format
#include <rpc/rpc.h>
void auth_destroy(AUTH *auth_handle)

5 Arguments

auth_handle

An RPC authentication handle created by the authnone_create,
authunix_create, or authunix_create_default routine.

5 Description

Frees the memory associated with the AUTH data structure created
by the authnone_create, authunix_create, or authunix_create_
default routine. Be careful not to reference the data structure
after calling this routine.

5 Return_Values

None

4 authnone_create

Creates a authentication handle for passing null credentials and
verifiers to remote systems.

Format

#include <rpc/rpc.h>
AUTH *authnone_create ( )

5 Arguments

None

5 Description

Creates and returns an authentication handle that passes
null authentication information with each remote procedure
call. Use this routine if the server process does not require
authentication information. RPC uses this routine as the default
authentication routine unless you create another authentication
handle using either the authunix_create or authunix_create_
default routine.

5 Return_Values

AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.

4 authunix_create

Creates and returns an RPC authentication handle that contains
UNIX-style authentication information.

Format

#include <rpc/rpc.h>
AUTH *authunix_create(char *host, int uid, int gid, int len,
int *aup_gids );

5 Arguments

host

Pointer to the name of the host on which the information was
created. This is usually the name of the system running the
client process.

uid

The user's user identification.

gid

The user's current group.

len

The number of elements in aup_gids array.

NOTE
This parameters is ignored by UCX's RPC implementation.

aup_gids

A pointer to an array of groups to which the user belongs.

NOTE
This parameters is ignored by UCX's RPC implementation.

5 Description

Implements UNIX-style authentication parameters. The client uses
no encryption for its credentials and only sends null verifiers.
The server sends back null verifiers or optionally a verifier
that suggests a new shorthand for the credentials.

5 Return_Values

AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.

4 authunix_create_default

Returns a default authentication handle.

Format

#include <rpc/rpc.h>
AUTH *authunix_create_default( )

5 Arguments

None

5 Description

Calls the authunix_create routine with the local host name,
effective process ID and group ID, and the process default
groups.

5 Return_Values

AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.

5 Examples

1.auth_destroy(client->cl_auth)
client->cl_auth = authunix_create_default();
This example overrides the default authnone_create action. The
client handle, client, is returned by the clnt_create, clnt_
create_vers, clnttcp_create, or clntudp_create routine.

4 callrpc

Executes a remote procedure call.

Format

#include <rpc/rpc.h>
int callrpc(char *host, u_long prognum, u_long versnum, u_long
procnum, xdrproc_t inproc, char *in, xdrproc_t outproc,
char *out);

5 Arguments

host

A pointer to the name of the host on which the remote procedure
resides.

prognum

The program number associated with the remote procedure.

versnum

The version number associated with the remote procedure.

procnum

The procedure number associated with the remote procedure.

inproc

The XDR routine used to encode the remote procedure's arguments.

A pointer to the remote procedure's arguments.

outproc

The XDR routine used to decode the remote procedure's results.

out

A pointer to the remote procedure's results.

5 Description

Calls the remote procedure associated with prognum, versnum,
and procnum on the host host. This routine performs the same
functions as a set of calls to the clnt_create, clnt_call, and
clnt_destroy routines. This routine returns RPC_SUCCESS if it
succeeds, or the value of enum clnt_stat cast to an integer if it
fails. The routine clnt_perrno is handy for translating a failure
status into a message.

NOTE
Calling remote procedures with this routine uses UDP/IP as
a transport; see clntudp_create for restrictions. You do
not have control of timeouts or authentication using this
routine. If you want to use the TCP transport, use the clnt_
create or clnttcp_create routine.

5 Return_Values

RPC_SUCCESS Indicates success.
clnt_stat Returns a value of type enum clnt_stat cast to
type int containing the status of the callrpc
operation.

4 clnt_broadcast

Executes a remote procedure call that is sent to all locally
connected networks using the broadcast address.

Format

#include <rpc/rpc.h>
enum clnt_stat clnt_broadcast(u_long prognum, u_long versnum,
u_long procnum, xdrproc_t inproc, char * in,
xdrproc_t outproc, char * out, resultproc_t
eachresult);

5 Arguments

prognum

The program number associated with the remote procedure.

versnum

The version number associated with the remote procedure.

procnum

The procedure number associated with the remote procedure.

inproc

The XDR routine used to encode the remote procedure's arguments.

A pointer to the remote procedure's arguments.

outproc

The XDR routine used to decode the remote procedure's results.

out

A pointer to the remote procedure's results.

eachresult

Called each time the routine receives a response. Specify the
routine as follows:

int eachresult(char *resultsp, struct sockaddr_in *addr)

resultsp is the same as the parameter passed to clnt_broadcast(),
except that the remote procedure's output is decoded there. addr
is a pointer to a sockaddr_in structure containing the address of
the host that sent the results.
If eachresult is NULL, the clnt_broadcast routine returns without
waiting for any replies.

5 Description

Performs the same function as the callrpc routine, except that
the call message is sent to all locally connected networks using
the broadcast address. Each time it receives a response, this
routine calls the eachresult routine. If eachresult returns
zero, clnt_broadcast waits for more replies; otherwise it assumes
success and returns RPC_SUCCESS.

NOTE
This routine uses the UDP protocol. Broadcast sockets are
limited in size to the maximum transfer unit of the data
link. For Ethernet, this value is 1400 bytes. For FDDI, this
value is 4500 bytes.

5 Return_Values

RPC_SUCCESS Indicates success.
clnt_stat Returns the buffer of type enum clnt_stat
containing the status of the clnt_broadcast
operation.

4 clnt_call

A macro that calls a remote procedure.

Format

#include <rpc/rpc.h>
enum clnt_stat clnt_call(CLIENT *handle, u_long procnum,
xdrproc_t inproc, char *in, xdrproc_t outproc,
char *out, struct timeval timeout);

5 Arguments

handle

A pointer to a client handle created by any of the client handle
creation routines.

procnum

The procedure number associated with the remote procedure.

inproc

The XDR routine used to encode the remote procedure's arguments.

A pointer to the remote procedure's arguments.

outproc

The XDR routine used to decode the remote procedure's results.

out

A pointer to the remote procedure's results.

timeout

A structure describing the time allowed for results to return to
the client. If you have previously used the clnt_control macro
with the CLSET_TIMEOUT code, this value is ignored.

5 Description

Use the clnt_call macro after using one of the client handle
creation routines. After you are finished with the handle, return
it using the clnt_destroy macro. Use the clnt_perror to print any
errors that occurred.

5 Return_Values

RPC_SUCCESS Indicates success.
clnt_stat Returns the buffer of type enum clnt_stat
containing the status of the clnt_call
operation.

4 clnt_control

A macro that changes or retrieves information about an RPC client
process.

Format

#include <rpc/rpc.h>
bool_t clnt_control(CLIENT *handle, u_int code, char *info);

5 Arguments

handle

A pointer to a client handle created by any of the client handle
creation routines.

code

A code designating the type of information to be set or
retrieved.

info

A pointer to a buffer containing the information for a SET
operation or the results of a GET operation.

5 Description

For UDP and TCP transports specify any of the following for code:

CLSET_TIMEOUT struct Set total timeout
timeval
CLGET_TIMEOUT struct Get total timeout
timeval
CLGET_SERVER_ADDR struct Get server address
sockaddr_
in
CLGET_FD int Get associated socket
CL_FD_CLOSE void Close socket on clnt_destroy
CL_FD_NCLOSE void Leave socket open on clnt_
destroy

If you set the timeout using clnt_control, ONC RPC ignores the
timeout parameter in all future clnt_call calls. The default
total timeout is 25 seconds.

For the UDP transport two additional options are available:

CLSET_RETRY_ struct Set retry timeout
TIMEOUT timeval
CLGET_RETRY_ struct Get retry timeout
TIMEOUT timeval

The timeout value in these two calls is the time that UDP waits
for a response before retransmitting the message to the server.
The default time is 5 seconds. The retry timeout controls when
UDP retransmits the request, the total timeout controls the total
time that the client should wait for a response. For example,
with the default settings, UDP will retry the transmission four
times at 5-second intervals.

5 Return_Values

TRUE Success
FALSE Failure

4 clnt_create_#

Creates a client handle and returns its address.

Format

#include <rpc/rpc.h>
CLIENT *clnt_create(char *host, u_long prognum, u_long
versnum, char *protocol);

5 Arguments

host

A pointer to the name of the remote host.

prognum

The program number associated with the remote procedure.

versnum

The version number associated with the remote procedure.

protocol

A pointer to a string containing the name of the protocol for
transmitting and receiving RPC messages. Specify either tcp or
udp.

5 Description

The clnt_create routine creates an RPC client handle for prognum.
An RPC client handle is a structure containing information about
the RPC client. The client can use the UDP or TCP transport
protocol.

This routine uses the Portmapper. You cannot control the local
port.

The default sizes of the send and receive buffers are 8800 bytes
for the UDP transport, and 4000 bytes for the TCP transport. The
retry time for the UDP transport is five seconds.

Use the clnt_create routine instead of the callrpc or clnt_
broadcast routines if you want to use one of the following:
o The TCP transport
o A non-null authentication
o More than one active client at the same time

You can also use the clnttcp_create routine to use the TCP
protocol, or the clntudp_create routine to use the UDP protocol.

The clnt_create routine uses the global variable rpc_createerr.
rpc_createerr is a structure that contains the most recent
service creation error. Use rpc_createerrif you want the client
program to handle the error. The value of rpc_createerr is set by
any RPC client creation routine that does not succeed.

NOTE
If the requested program is available on the host but the
program does not support the requested version number, this
routine still succeeds. A subsequent call to the clnt_call
routine will discover the version mismatch. Use the clnt_
create_vers routine if you want to avoid this condition.

5 Return_Values

CLIENT * Client handle containing the server
information.
NULL Error occurred while creating the client
handle. Use the clnt_pcreateerror or clnt_
spcreateerror routine to obtain diagnostic
information.

4 clnt_create_vers

Creates a client handle and returns its address. Seeks to use a
server supporting the highest version number within a specified
range.

Format

#include <rpc/rpc.h>
CLIENT *clnt_create_vers(char *host, u_long prognum, u_long
*versnum, u_long min_vers, u_long max_vers, char
*protocol);

5 Arguments

host

A pointer to the name of the remote host.

prognum

The program number associated with the remote procedure.

versnum

The version number associated with the remote procedure. This
value is returned by the routine. The value is the highest
version number supported by the remote server that is in the
range of version numbers specified by min_vers and max_vers. The
argument may remain undefined; see additional information in the
Description section.

min_vers

The minimum acceptable version number for the remote procedure.

max_vers

The maximum acceptable version number for the remote procedure.

protocol

A pointer to a string containing the name of the protocol for
transmitting and receiving RPC messages. Specify either tcp or
udp.

5 Description

The clnt_create_vers routine creates an RPC client handle
for prognum. An RPC client handle is a structure containing
information about the RPC client. The client can use the UDP
or TCP transport protocol.

This routine uses the Portmapper. You cannot control the local
port.

The default sizes of the send and receive buffers are 8800 bytes
for the UDP transport, and 4000 bytes for the TCP transport. The
retry time for the UDP transport is 5 seconds.

The clnt_create_vers routine differs from the standard clnt_
create routine in that it seeks out the highest version number
supported by the server. If the server does not support any
version numbers within the requested range, the routine returns
NULL and the versnum variable is undefined.

The clnt_create_vers routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed.

5 Return_Values

CLIENT * Client handle containing the server
information.
NULL Error occurred while creating the client
handle. Usually the error indicates that the
server does not support any version numbers
within the requested range. Use the clnt_
pcreateerror or clnt_spcreateerror routine to
obtain diagnostic information.

4 clnt_destroy

A macro that frees the memory associated with an RPC client
handle.

Format

#include <rpc/rpc.h>
void clnt_destroy(CLIENT *handle);

5 Arguments

handle

A pointer to a client handle created by any of the client handle
creation routines.

5 Description

The clnt_destroy routine destroys the client's RPC handle by
deallocating all memory related to the handle. The client is
undefined after the clnt_destroy call.

If the clnt_create routine had previously opened the socket
associated with the client handle or the program had used the
clnt_control routine to set CL_FD_CLOSE, this routine closes the
socket. If the clnt_create routine had not previously opened the
socket associated with the client handle or the program had used
the clnt_control routine to set CL_FD_NCLOSE, this routine leaves
the socket open.

5 Return_Values

None

4 clnt_freeres

A macro that frees the memory that was allocated when the remote
procedure's results were decoded.

Format

#include <rpc/rpc.h>
bool_t clnt_freeres(CLIENT *handle, xdrproc_t outproc, char
*out);

5 Arguments

handle

A pointer to a client handle created by any of the client handle
creation routines.

outproc

The XDR routine used to decode the remote procedure's results.

out

A pointer to the remote procedure's results.

5 Description

The clnt_freeres routine calls the xdr_free routine to deallocate
the memory where the remote procedure's results are stored.

5 Return_Values

TRUE Success.
FALSE Error occurred while freeing the memory.

4 clnt_geterr

A macro that returns error information indicating why an RPC call
failed.

Format

#include <rpc/rpc.h>
void clnt_geterr(CLIENT *handle, struct rpc_err *errp);

5 Arguments

handle

A pointer to a client handle created by any of the client handle
creation routines.

errp

A pointer to an rpc_err structure containing information that
indicates why an RPC call failed. This information is the same
information as clnt_stat contains, plus one of the following:
the C error number, the range of server versions supported, or
authentication errors.

5 Description

This macro copies the error information from the client handle
to the structure referenced by errp. The macro is mainly for
diagnostic use.

5 Return_Values

None

4 clnt_pcreateerror

Prints a message explaining why ONC RPC could not create a client
handle.

Format

#include <rpc/rpc.h>
void clnt_pcreateerror(char *sp);

5 Arguments

A pointer to a string to be used as the beginning of the error
message.

5 Description

The clnt_pcreateerror routine prints a message to SYS$OUTPUT. The
message consists of the sp parameter followed by an RPC-generated
error message. Use this routine when the clnt_create, clnttcp_
create, or clntudp_create routine fails.

5 Return_Values

None

4 clnt_perrno

Prints a message indicating why the callrpc or clnt_broadcast
routine failed.
Format
#include <rpc/rpc.h>
void clnt_perrno(enum clnt_stat stat) ;

5 Arguments

stat
A buffer containing status information.

5 Description

Prints a message to standard error corresponding to the condition
indicated by the stat argument.

The data type declaration for clnt_stat in rpc/rpc.h lists the
standard errors.

5 Return_Values

None

4 clnt_perror

Prints a message explaining why an ONC RPC routine failed.
Format
#include <rpc/rpc.h>
void clnt_perror(CLIENT *handle, char *sp);

5 Arguments

handle
A pointer to the client handle used in the call that failed.
sp
A pointer to a string to be used as the beginning of the error
message.

5 Description

Prints a message to standard error indicating why an ONC RPC call
failed. The message is prepended with string sp and a colon.

5 Return_Values

None

4 clnt_spcreateerror

Returns a message indicating why RPC could not create a client
handle.
Format
#include <rpc/rpc.h>
char *clnt_spcreateerror(char *sp);

5 Arguments

sp
A pointer to a string to be used as the beginning of the error
message.

5 Description

The clnt_spcreateerror routine returns the address of a message
string. The message consists of the sp parameter followed by an
error message generated by calling the clnt_sperrno routine. Use
the clnt_spcreateerror routine when the clnt_create, clnttcp_
create, or clntudp_create routine fails.

Use this routine if:
o You want to save the string.
o You do not want to use fprintf to print the message.
o The message format is different from the one that clnt_perrno
supports.

The address that clnt_spcreateerror returns is the address of
its own internal string buffer. The clnt_spcreateerror routine
overwrites this buffer with each call. Therefore, you must copy
the string to your own buffer if you wish to save the string.

5 Return_Values

char * A pointer to the message string terminated
with a NULL character.
NULL The routine was not able to allocate its
internal buffer.

4 clnt_sperrno

Returns a message indicating why the callrpc or clnt_broadcast
routine failed to create a client handle.
Format
#include <rpc/rpc.h>
char *clnt_sperrno(enum clnt_stat stat);

5 Arguments

stat
A buffer containing status information.

5 Description

The clnt_sperrno routine returns a pointer to a string.

Use this routine instead if:
o The server does not have a stderr file; many servers do not.
o You want to save the string.
o You do not want to use fprintf to print the message.
o The message format is different from the one that clnt_perrno
supports.

The address that clnt_sperrno returns is a pointer to the error
message string for the error. Therefore, you do not have to copy
the string to your own buffer in order to save the string.

5 Return_Values

char * A pointer to the message string terminated
with a NULL character.

4 clnt_sperror

Returns a message indicating why an ONC RPC routine failed.
Format
#include <rpc/rpc.h>
char *clnt_sperror(CLIENT *handle, char *sp);

5 Arguments

handle
A pointer to the client handle used in the call that failed.
sp
A pointer to a string to be used as the beginning of the error
message.

5 Description

The clnt_sperror routine returns a pointer to a message string.
The message consists of the sp parameter followed by an error
message generated by calling the clnt_sperrno routine. Use this
routine when the clnt_call routine fails.

Use this routine if:
o You want to save the string.
o You do not want to use fprintf to print the message.
o The message format is different from the one that clnt_perrno
supports.

The address that clnt_sperror returns is a pointer to its own
internal string buffer. The clnt_sperror routine overwrites this
buffer with each call. Therefore, you must copy the string to
your own buffer if you wish to save the string.

5 Return_Values

char * A pointer to the message string terminated
with a NULL character.
NULL The routine was not able to allocate its
internal buffer.

4 clntraw_create

Creates a client handle for memory-based ONC RPC for simple
testing and timing.
Format
#include <rpc/rpc.h>
CLIENT *clntraw_create(u_long prognum, u_long versnum);

5 Arguments

prognum
The program number associated with the remote program.
versnum
The version number associated with the remote program.

5 Description

Creates an in-program ONC RPC client for the remote program
prognum, version versnum. The transport used to pass messages
to the service is actually a buffer within the process's address
space, so the corresponding server should live in the same
address space; see svcraw_create. This allows simulation of
and acquisition of ONC RPC overheads, such as round-trip times,
without any kernel interference.

5 Return_Values

CLIENT * A pointer to a client handle.
NULL Indicates failure.

4 clnttcp_create

Creates an ONC RPC client handle for a TCP/IP connection.
Format
#include <rpc/rpc.h>
CLIENT *clnttcp_create(struct sockaddr_in *addr, u_long
prognum, u_long versnum, int *sockp, u_int sendsize,
u_int recvsize);

5 Arguments

addr
A pointer to a buffer containing the internet address where the
remote program is located.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
sockp
A pointer to the socket number to be used for the remote
procedure call. If sockp is RPC_ANYSOCK, then this routine opens
a new socket and sets sockp.
sendsize
The size of the send buffer. If you specify 0 the routine chooses
a suitable default.
recvsize
The size of the receive buffer. If you specify 0 the routine
chooses a suitable default.

5 Description

Creates an ONC RPC client handle for the remote program prognum,
version versnum at address addr. The client uses TCP/IP as a
transport. The routine is similar to the clnt_create routine,
except clnttcp_create allows you to specify a socket and the send
and receive buffer sizes.

If you specify the port number as zero by using addr->sin_port,
the Portmapper provides the number of the port on which the
remote program is listening.

The clnttcp_create routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed. The
rpc_createerr variable is defined in the CLNT.H file.

The socket referenced by sockp is copied into a private area for
RPC to use. It is the client's responsibility to close the socket
referenced by sockp.

The authentication scheme for the client, client->cl_auth, gets
set to null authentication. The calling program can set this to
something different if necessary.

5 Return_Values

CLIENT * A pointer to the client handle.
NULL Indicates failure.

4 clntudp_bufcreate

Creates an ONC RPC client handle for a buffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
CLIENT *clntudp_bufcreate(struct sockaddr_in *addr, u_long
prognum, u_long versnum, struct timeval wait, register
int *sockp, u_int sendsize, u_int recvsize);

5 Arguments

addr
A pointer to a buffer containing the internet address where the
remote program is located.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
wait
The amount of time used between call retransmission if no
response is received. Retransmission occurs until the ONC RPC
calls time out.
sockp
A pointer to the socket number to be used for the remote
procedure call. If sockp is RPC_ANYSOCK, then this routine opens
a new socket and sets sockp.
sendsize
The size of the send buffer. If you specify 0, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify 0, the routine
chooses a suitable default.

5 Description

Creates an ONC RPC client handle for the remote program prognum,
version versnum at address addr. The client uses UDP as the
transport. The routine is similar to the clnt_create routine,
except clntudp_bufcreate allows you to specify a socket, the UDP
retransmission time, and the send and receive buffer sizes.

If you specify the port number as zero by using addr->sin_port,
the Portmapper provides the number of the port on which the
remote program is listening.

The clntudp_bufcreate routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed. The
rpc_createerr variable is defined in the CLNT.H file.

The socket referenced by sockp is copied into a private area for
RPC to use. It is the client's responsibility to close the socket
referenced by sockp.

The authentication scheme for the client, client->cl_auth, gets
set to null authentication. The calling program can set this to
something different if necessary.

NOTE
If addr->sin_port is 0 and the requested program is
available on the host but the program does not support the
requested version number, this routine still succeeds. A
subsequent call to the clnt_call routine will discover the
version mismatch. Use the clnt_create_vers routine if you
want to avoid this condition.

5 Return_Values

CLIENT * A pointer to the client handle.
NULL Indicates failure.

4 clntudp_create

Creates an ONC RPC client handle for a non-buffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
CLIENT *clntudp_create(struct sockaddr_in *addr, u_long
prognum, u_long versnum, struct timeval wait, register
int *sockp);

5 Arguments

addr
A pointer to a buffer containing the internet address where the
remote program is located.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
wait
The amount of time used between call retransmission if no
response is received. Retransmission occurs until the ONC RPC
calls time out.
sockp
A pointer to the socket number to be used for the remote
procedure call. If sockp is RPC_ANYSOCK, then this routine opens
a new socket and sets sockp.

5 Description

Creates an ONC RPC client handle for the remote program prognum,
version versnum at address addr. The client uses UDP as the
transport. The routine is similar to the clnt_create routine,
except clntudp_create allows you to specify a socket and the UDP
retransmission time.

If you specify the port number as zero by using addr->sin_port,
the Portmapper provides the number of the port on which the
remote program is listening.

The clntudp_create routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed. The
rpc_createerr variable is defined in the CLNT.H file.

The socket referenced by sockp is copied into a private area for
RPC to use. It is the client's responsibility to close the socket
referenced by sockp.

The authentication scheme for the client, client->cl_auth, gets
set to null authentication. The calling program can set this to
something different if necessary.

NOTES
Since UDP/IP messages can only hold up to 8 Kbytes of
encoded data, this transport cannot be used for procedures
that take large arguments or return huge results.

If addr->sin_port is 0 and the requested program is
available on the host but the program does not support the
requested version number, this routine still succeeds. A
subsequent call to the clnt_call routine will discover the
version mismatch. Use the clnt_create_vers routine if you
want to avoid this condition.

5 Return_Values

CLIENT * A pointer to the client handle.
NULL Indicates failure.

4 get_myaddress

Returns the local host's internet address.
Format
#include <rpc/rpc.h>
void get_myaddress(struct sockaddr_in *addr);

5 Arguments

addr
A pointer to a sockaddr_in structure that the routine will load
with the internet address of the host where the local procedure
resides.

5 Description

Puts the local host's internet address into addr without doing
any name translation. The port number is always set to htons
(PMAPPORT).

5 Return_Values

None

4 get_myaddr_dest

Returns the local host's internet address according to a
destination address.
Format
#include <rpc/rpc.h>
void get_myaddr_dest(struct sockaddr_in *addr, struct
sockaddr_in *dest);

5 Arguments

addr
A pointer to a sockaddr_in structure that the routine will load
with the local internet address which would provide a connection
to the remote address specified in dest.
dest
A pointer to a sockaddr_in structure containing an internet
address of a remote host.

5 Description

Since the local host may have multiple network addresses (each
on its own interface), this routine is used to select the local
address which would provide a connection to the remote address
specified in dest.

This is an alternative to gethostbyname, which invokes yellow
pages. It takes a destination (where we are trying to get to) and
finds an exact network match to go to.

5 Return_Values

None
3 RPC_Portmapper_Routines
Portmapper routines allow C programs to access the Portmapper
network service.

Important: In order to maintain uniqueness for the OpenVMS HELP
utility, some XDR routines have a "_#" appended at the end. Do
not use the "_#" when coding the routine in a program.

4 pmap_getmaps_#

Returns a copy of the current port mappings on a remote host.
Format
#include <rpc/pmap_clnt.h>
struct pmaplist *pmap_getmaps(struct sockaddr_in *addr);

5 Arguments

addr
A pointer to a sockaddr_in structure containing the internet
address of the host whose Portmapper you wish to call.

5 Description

A client interface to the Portmapper, which returns a list of the
current ONC RPC program-to-port mappings on the host located at
the internet address addr. The UCX SHOW PORTMAPPER command uses
this routine.

5 Return_Values

struct pmaplist * A pointer to the returned list of server-to-
port mappings on host addr.
NULL Indicates failure.

4 pmap_getmaps_vms

Returns a copy of the current port mappings on a remote UCX host.
Format
#include <rpc/pmap_clnt.h>
struct pmaplist_vms *pmap_getmaps_vms(struct sockaddr_in
*addr);

5 Arguments

addr
A pointer to a sockaddr_in structure containing the internet
address of the UCX host whose Portmapper you wish to call.

5 Description

This routine is similar to the pmap_getmaps routine. However,
pmap_getmaps_vms also returns the process identifiers (PIDs) that
are required for mapping requests to UCX hosts.

5 Return_Values

struct pmaplist * A pointer to the returned list of server-to-
port mappings on host addr.
NULL Indicates failure.

4 pmap_getport

Returns the port number on which the specified service is
waiting.
Format
#include <rpc/pmap_clnt.h>
u_short pmap_getport(struct sockaddr_in *addr, u_long prognum,
u_long versnum, u_long protocol );

5 Arguments

5 Description

A client interface to the Portmapper. This routine returns the
port number on which waits a server that supports program number
prognum, version versnum, and speaks the transport protocol
associated with protocol (IPPROTO_UDP or IPPROTO_TCP).

NOTES
If the requested version is not available, but at least the
requested program is registered, the routine returns a port
number.

The pmap_getport routine returns the port number in host
byte order not network byte order. For certain routines you
may need to convert this value to network byte order using
the htons routine. For example, the sockaddr_in structure
requires that the port number be in network byte order.

5 Return_Values

x The port number of the service on the remote
system.
0 No mapping exists or RPC could not contact the
remote Portmapper service. In the latter case,
the global variable rpc_createerr.cf_error
contains the ONC RPC status.

4 pmap_rmtcall

The client interface to the Portmapper service for a remote call
and broadcast service. This routine allows a program to do a
lookup and call in one step.
Format
#include <rpc/pmap_clnt.h>
enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr, u_long
prognum, u_long versnum, u_long procnum,
xdrproc_t inproc, char * in xdrproc_t outproc,
char * out, struct timeval timeout, u_long
*port );

5 Arguments

addr
A pointer to a sockaddr_in structure containing the internet
address of the host where the remote Portmapper resides.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
procnum
The procedure number associated with the remote procedure.
inproc
The XDR routine used to encode the remote procedure's arguments.
in
A pointer to the remote procedure's arguments.
outproc
The XDR routine used to decode the remote procedure's results.
out
A pointer to the remote procedure's results.
timeout
A timeval structure describing the time allowed for the results
to return to the client.
port
A pointer to a location for the returned port number. Modified
to the remote program's port number if the pmap_rmtcall routine
succeeds.

5 Description

A client interface to the Portmapper, which instructs the
Portmapper on the host at the internet address *addr to make
a call on your behalf to a procedure on that host. Use this
procedure for a ping operation and nothing else. You can use
the clnt_perrno routine to print any error message.

NOTE
If the requested procedure is not registered with the remote
Portmapper, the remote Portmapper does not reply to the
request. The call to pmap_rmtcall will eventually time out.
The pmap_rmtcall does not perform authentication.

5 Return_Values

enum clnt_stat Returns the buffer containing the status of
the operation.

4 pmap_set

Called by the server procedure to have the Portmapper create a
mapping of the procedure's program and version number.
Format
#include <rpc/pmap_clnt.h>
bool_t pmap_set(u_long prognum, u_long versnum, u_long
protocol, u_short port);

5 Arguments

prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.
protocol
The transport protocol that the server procedure uses. Specify
either IPPROTO_UDP or IPPROTO_TCP.
port
The port number associated with the server program.

5 Description

A server interface to the Portmapper, which establishes a mapping
between the triple [prognum,versnum,protocol] and port on the
server's Portmapper service. The svc_register routine calls this
routine to register the server with the local Portmapper.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 pmap_unset

Called by the server procedure to have the Portmapper delete a
mapping of the procedure's program and version number.
Format
#include <rpc/pmap_clnt.h>
bool_t pmap_unset(u_long prognum, u_long versnum);

5 Arguments

prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.

5 Description

A server interface to the Portmapper, which destroys all mapping
between the triple [prognum, versnum, *] and ports on the local
host's Portmapper.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.
3 RPC_Server_Routines
Server routines allow C programs to receive procedure calls from
client programs over the network.

4 registerrpc

Obtains a unique systemwide procedure identification number.
Format
#include <rpc/rpc.h>
int registerrpc(u_long prognum, u_long versnum, u_long
procnum, char *(*progname)(), xdrproc_t inproc, xdrproc_t
outproc );

5 Arguments

prognum
The program number associated with the service procedure.
versnum
The version number associated with the service procedure.
procnum
The procedure number associated with the service procedure.
progname
The address of the service procedure being registered with the
ONC RPC service package.
inproc
The XDR routine used to decode the service procedure's arguments.
outproc
The XDR routine used to encode the service procedure's results.

5 Description

The registerrpc routine performs the following tasks for a
server:
o Creates a UDP server handle. See the svcudp_create routine for
restrictions.
o Calls the svc_register routine to register the program with
the Portmapper.
o Adds prognum, versnum, and procnum to an internal list of
registered procedures. When the server receives a request, it
uses this list to determine which routine to call.

A server should call registerrpc for every procedure it
implements, except for the NULL procedure. If a request arrives
for program prognum, version versnum, and procedure procnum,
progname is called with a pointer to its parameters.

5 Return_Values

0 Indicates success.
-1 Indicates failure.

4 seterr_reply

Fills in the error text in a reply message.
Format
#include <rpc/rpc.h>
void seterr_reply(struct rpc_msg *msg, struct rpc_err *error);

5 Arguments

msg
A pointer to a reply message buffer.
error
A pointer to an rpc_err structure containing the error associated
with the reply message.

5 Description

Given a reply message, seterr_reply fills in the error field.

5 Return_Values

None

4 svc_destroy

A macro that frees the memory associated with an RPC server
handle.
Format
#include <rpc/rpc.h>
void svc_destroy(SVCXPRT *xprt);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.

5 Description

The svc_destroy routine returns all the private data structures
associated with a server handle. If the server handle creation
routine received the value RPC_ANYSOCK as the socket, svc_destroy
closes the socket. Otherwise, your program must close the socket.

5 Return_Values

None

4 svc_freeargs

A macro that frees the memory allocated when the procedure's
arguments were decoded.
Format
#include <rpc/rpc.h>
bool_t svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char
*in);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
inproc
The XDR routine used to decode the service procedure's arguments.
in
A pointer to the service procedure's decoded arguments.

5 Description

The svc_destroy routine returns the memory that the svc_getargs
routine allocated to hold the service procedure's decoded
arguments. This routine calls the xdr_free routine.

5 Return_Values

TRUE Success; memory successfully deallocated.
FALSE Failure; memory not deallocated.

4 svc_getargs

A macro that decodes the service procedure's arguments.
Format
#include <rpc/rpc.h>
bool_t svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);

5 Arguments

5 Description

This routine calls the specified XDR routine to decode the
arguments passed to the service procedure.

5 Return_Values

TRUE Successfully decoded.
FALSE Decoding unsuccessful.

4 svc_getcaller

A macro that returns the address of the client that called the
service procedure.
Format
#include <rpc/rpc.h>
struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.

5 Description

This routine returns a sockaddr_in structure containing the
internet address of the RPC client routine that called the
service procedure.

5 Return_Values

struct sockaddr_ A pointer to the socket descriptor.
in

4 svc_getreqset

Returns data for each server connection.
Format
#include <rpc/rpc.h>
void svc_getreqset(fd_set *rdfds);

5 Arguments

rdfds
A pointer to the read file descriptor bit mask modified by the
select routine.

5 Description

The svc_getreqset routine is for servers that implement custom
asynchronous event processing or that do not use the svc_run
routine. You may only use svc_fdset when the server does not use
svc_run.

You are unlikely to call this routine directly, because the
svc_run routine calls it. However, there are times when you
cannot call svc_run. For example, suppose a program services
RPC requests and reads or writes to another socket at the same
time. The program cannot call svc_run. It must call select and
svc_getreqset.

The server calls svc_getreqset when a call to the select
system call determines the server has received one or more RPC
requests. The svc_getreqset routine reads in data for each server
connection, then calls the server program to handle the data.

The svc_getreqset routine does not return a value. It finishes
executing after all sockets associated with the variable rdfds
have been serviced.

You may use the global variable svc_fdset with svc_getreqset. The
svc_fdset variable is the RPC server's read file descriptor bit
mask.

To use svc_fdset:
1. Copy the global variable svc_fdset into a temporary variable.
2. Pass the temporary variable to the select routine. The select
routine overwrites the variable and returns it.
3. Pass the temporary variable to the svc_getreqset routine.

5 Example

#define MAXSOCK 10
int readfds[ MAXSOCK+1], /* sockets to select from*/
i, j;
for(i = 0, j = 0; i << MAXSOCK; i++)
if((svc_fdset[i].sockname != 0) && (svc_
fdset[i].sockname != -1))
readfds[j++] = svc_fdset[i].sockname;
readfds[j] = 0; /* list of sockets ends with a zero */
switch(select(0, readfds, 0, 0, 0))
{
case -1: /* an error happened */
case 0: /* time out */
break;
default: /* 1 or more sockets ready for reading */
errno = 0;
svc_getreqset(readfds);
if( errno == ENETDOWN || errno == ENOTCONN)
sys$exit( SS$_THIRDPARTY);
}

5 Return_Values

None

4 svc_register

Registers the server program with the Portmapper service.
Format
#include <rpc/rpc.h>
bool_t svc_register(SVCXPRT *xprt, u_long prognum, u_long
versnum, void (*dispatch)(), u_long protocol);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.
dispatch
The address of the service dispatch procedure that the server
procedure calls. The procedure dispatch has the following form:
void dispatch(request, xprt)
struct svc_req *request;
SVCXPRT *xprt;
The svc_run and svc_getreqset call the dispatch routine.
protocol
The protocol that the server procedure uses. Values for this
parameter are zero, IPPROTO_UDP, or IPPROTO_TCP. If protocol is
zero, the service is not registered with the Portmapper service.

5 Description

Associates prognum and versnum with the service dispatch
procedure dispatch. If protocol is non-zero, then a mapping of
the triple [prognum, versnum, protocol] to xprt->xp_port is also
established with the local Portmapper service.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 svc_run

Waits for incoming RPC requests and calls the svc_getreqset
routine to dispatch to the appropriate RPC server program.
Format
#include <rpc/rpc.h>
void svc_run();

5 Arguments

None

5 Description

The svc_run routine calls the select routine to wait for RPC
requests. When a request arrives, svc_run calls the svc_getreqset
routine. Then svc_run calls the select routine again.

The svc_run routine never returns.

You may use the global variable svc_fdset with the svc_run
routine. See the svc_getreqset routine for more information on
svc_fdset.

5 Return_Values

Never returns

4 svc_sendreply

Sends the results of a remote procedure call to an RPC client.
Format
#include <rpc/rpc.h>
bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char
*out);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
outproc
The XDR routine used to encode the server procedure's results.
out
A pointer to the server procedure's results.

5 Description

Called by an ONC RPC service's dispatch routine to send the
results of a remote procedure call.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 svc_unregister

Calls the Portmapper to unregister the specified program and
version for all protocols. The program and version are removed
from the list of active servers.
Format
#include <rpc/rpc.h>
void svc_unregister(u_long prognum, u_long versnum);

5 Arguments

prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.

5 Description

Removes all mapping of the double [prognum, versnum] to dispatch
routines, and of the triple [prognum, versnum, *] to port number.

5 Return_Values

None

4 svcerr_auth

Sends an authentication error to the client.
Format
#include <rpc/rpc.h>
void svcerr_auth(SVCXPRT *xprt, enum auth_stat why);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
why
The reason for the authentication error.

5 Description

Called by a service dispatch routine that refuses to perform a
remote procedure call due to an authentication error.

5 Return_Values

None

4 svcerr_decode

Sends an error code to the client indicating that the server
procedure cannot decode the client's arguments.
Format
#include <rpc/rpc.h>
void svcerr_decode(SVCXPRT *xprt);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.

5 Description

Called by a service dispatch routine that cannot successfully
decode its parameters. See also the svc_getargs routine.

5 Return_Values

None

4 svcerr_noproc

Sends an error code to the client indicating that the server
program does not implement the requested procedure.
Format
#include <rpc/rpc.h>
void svcerr_noproc(SVCXPRT *xprt);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.

5 Description

Called by a service dispatch routine that does not implement the
procedure number that the client requested.

5 Return_Values

None

4 svcerr_noprog

Sends an error code to the client indicating that the server
program is not registered with the Portmapper.
Format
#include <rpc/rpc.h>
void svcerr_noprog(SVCXPRT *xprt);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.

5 Description

Called when the desired program is not registered with the ONC
RPC package. Generally, the Portmapper informs the client when a
server is not registered. Therefore, service implementors usually
do not use this routine.

5 Return_Values

None

4 svcerr_progvers

Sends an error code to the client indicating that the requested
program is registered with the Portmapper but the requested
version of the program is not registered.
Format
#include <rpc/rpc.h>
void svcerr_progvers(SVCXPRT *xprt, u_long low_vers, u_long
high_vers);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
low_vers
The lowest version of the requested program that the server
supports.
high_vers
The highest version of the requested program that the server
supports.

5 Description

Called when the desired version of a program is not registered
with the ONC RPC package. Generally, the Portmapper informs
the client when a requested program version is not registered.
Therefore, service implementors usually do not use this routine.

5 Return_Values

None

4 svcerr_systemerr

Sends an error code to the client indicating that the an error
occurred that is not handled by the protocol being used.
Format
#include <rpc/rpc.h>
void svcerr_systemerr(SVCXPRT *xprt);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.

5 Description

Called by a service dispatch routine when it detects a system
error not covered by any particular protocol. For example, if a
service can no longer allocate storage, it may call this routine.

5 Return_Values

None

4 svcerr_weakauth

Sends an error code to the client indicating that an
authentication error occurred. The authentication information
was correct but was insufficient.
Format
#include <rpc/rpc.h>
void svcerr_weakauth(SVCXPRT *xprt);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.

5 Description

Called by a service dispatch routine that refuses to perform
a remote procedure call due to insufficient (but correct)
authentication parameters. The routine calls svcerr_auth (xprt,
AUTH_TOOWEAK).

5 Return_Values

None

4 svcraw_create

Creates a server handle for memory-based ONC RPC for simple
testing and timing.
Format
#include <rpc/rpc.h>
SVCXPRT *svcraw_create();

5 Arguments

None

5 Description

Creates a in-program ONC RPC service transport, to which it
returns a pointer. The transport is really a buffer within the
process's address space, so the corresponding client should live
in the same address space; see the clntraw_create routine. The
svcraw_create and clntraw_create routines allow simulation and
acquisition of ONC RPC overheads (such as round-trip times),
without any kernel interference.

5 Return_Values

SVCXPRT * A pointer to an RPC server handle for the
in-memory transport.
NULL Indicates failure.

4 svcfd_create

Creates an RPC server handle using the specified open file
descriptor.
Format
#include <rpc/rpc.h>
SVCXPRT *svcfd_create(int fd, u_int sendsize, u_int recvsize);

5 Arguments

fd
The number of an open file descriptor.
sendsize
The size of the send buffer. If you specify 0, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify 0, the routine
chooses a suitable default.

5 Description

Creates an RPC server handle using the specified TCP socket, to
which it returns a pointer. The server should call the svcfd_
create routine after it accepts an incoming TCP connection.

5 Return_Values

SVCXPRT * A pointer to the server handle.
NULL Indicates failure.

4 svctcp_create

Creates an ONC RPC server handle for a TCP/IP connection.
Format
#include <rpc/rpc.h>
SVCXPRT *svctcp_create(int sock, u_int sendsize, u_int
recvsize);

5 Arguments

sock
The socket with which the connection is associated. If sock is
RPC_ANYSOCK, then this routine opens a new socket and sets sock.
If the socket is not bound to a local TCP port, then this routine
binds it to an arbitrary port.
sendsize
The size of the send buffer. If you specify 0, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify 0, the routine
chooses a suitable default.

5 Description

Creates an RPC server handle using the TCP/IP transport, to
which it returns a pointer. Upon completion, xprt->xp_sock is
the transport's socket descriptor, and xprt->xp_port is the
transport's port number. The service is automatically registered
as a transporter (thereby including its socket in svc_fds such
that its socket descriptor is included in all RPC select system
calls).

5 Return_Values

SVCXPRT * A pointer to the server handle.
NULL Indicates failure.

4 svcudp_bufcreate

Creates an ONC RPC server handle for a buffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
SVCXPRT *svcudp_bufcreate(int sock, u_int sendsize, u_int
recvsize);

5 Arguments

sock
The socket with which the connection is associated. If sock is
RPC_ANYSOCK, then this routine opens a new socket and sets sock.
sendsize
The size of the send buffer. If you specify 0, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify 0, the routine
chooses a suitable default.

5 Description

Creates an RPC server handle using the UDP transport, to
which it returns a pointer. Upon completion, xprt->xp_sock is
the transport's socket descriptor, and xprt->xp_port is the
transport's port number. The service is automatically registered
as a transporter (thereby including its socket in svc_fds such
that its socket descriptor is included in all RPC select system
calls).

5 Return_Values

SVCXPRT * A pointer to the server handle.
NULL Indicates failure.

4 svcudp_create

Creates an ONC RPC server handle for a non-buffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
SVCXPRT *svcudp_create(int sock);

5 Arguments

sock
The socket with which the connection is associated. If sock is
RPC_ANYSOCK, then this routine opens a new socket and sets sock.

5 Description

NOTE
Since UDP/IP-based ONC RPC messages can only hold up to 8
Kbytes of encoded data, this transport cannot be used for
procedures that take large arguments or return huge results.

5 Return_Values

SVCXPRT * A pointer to the server handle.
NULL Indicates failure.

4 xprt_register

Adds a socket associated with an RPC server handle to the list of
registered sockets.
Format
#include <rpc/rpc.h>
void xprt_register(SVCXPRT *xprt);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.

5 Description

Activation of a transport handle involves setting the most
appropriate bit for the socket associated with xprt in the svc_
fds mask. When svc_run() is invoked, activity on the transport
handle is eligible to be processed by the server.

The svc_register routine calls this routine; therefore, you are
unlikely to use this routine directly.

5 Return_Values

None

4 xprt_unregister

Removes a socket associated with an RPC server handle from the
list of registered sockets.
Format
#include <rpc/rpc.h>
void xprt_unregister(SVCXPRT *xprt);

5 Arguments

xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.

5 Description

Removes the socket associated with the indicated handle from the
list of registered sockets maintained in the svc_fdset variable.
Activity on the socket associated with xprt will no longer be
checked by the svc_run routine.

The svc_unregister routine calls this routine; therefore, you are
unlikely to use this routine directly.

5 Return_Values

None

4 _authenticate

Authenticates the request message.
Format
#include <rpc/rpc.h>
enum auth_stat _authenticate(struct svc_req *rqst, struct
rpc_msg *msg);

5 Arguments

rqst
A pointer to an svc_req structure with the requested program
number, procedure number, version number, and credentials passed
by the client.
msg
A pointer to an rpc_msg structure with members that make up the
RPC message.

5 Description

Returns AUTH_OK if the message is authenticated successfully. If
it returns AUTH_OK, the routine also does the following:
o Sets rqst->rq_xprt->verf to the appropriate response verifier.
o Sets rqst->rq_client_cred to the "cooked" form of the
credentials.

The expression rqst->rq_xprt->verf must be preallocated, and its
length set appropriately.

The program still owns and is responsible for msg->u.cmb.cred and
msg->u.cmb.verf. The authentication system retains ownership of
rqst->rq_client_cred, the "cooked" credentials.

5 Return_Values

enum auth_stat The return status code for the authentication
checks:
AUTH_OK=0-Authentication checks successful.
AUTH_BADCRED=1-Invalid credentials (seal
broken)
AUTH_REJECTEDCRED=2-Client should begin new
session
AUTH_BADVERF=3-Invalid verifier (seal
broken)
AUTH_REJECTEDVERF=4-Verifier expired or was
replayed
AUTH_TOOWEAK=5-Rejected due to security
reasons
AUTH_INVALIDRESP=6-Invalid response
verifier
AUTH_FAILED=7-some unknown reason
3 RPC_XDR_Routines
XDR routines specify external data representation. They allow C
programmers to describe arbitrary data structures in a system-
independent fashion.

Important: In order to maintain uniqueness for the OpenVMS HELP
utility, some XDR routines have a "_#" appended at the end. Do
not use the "_#" when coding the routine in a program.

4 xdr_accepted_reply

Serializes and deserializes a message-accepted indication in an
RPC reply message.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply
*arp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
arp
A pointer to a buffer to which the message-accepted indication is
written.

5 Description

Used for encoding reply messages. This routine encodes the status
of the RPC call and, in the case of success, the call results
as well. This routine is useful for users who wish to generate
messages without using the ONC RPC package. It returns the
message-accepted variant of a reply message union in the arp
argument.

The xdr_replymsg routine calls this routine.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure to encode the message.

4 xdr_array

Serializes and deserializes the elements of a variable-length
array.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_array(XDR *xdrs, char **arrp, u_int *sizep, u_int
maxsize, u_int elsize, xdrproc_t elproc);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
arrp
A pointer to the pointer to the array.
sizep
A pointer to the number of elements in the array. This element
count cannot exceed the maxsize parameter.
maxsize
The maximum size of the sizep parameter. This value is the
maximum number of elements that the array can hold.
elsize
The size, in bytes, of each of the array's elements.
elproc
The XDR routine to call that handles each element of the array.

5 Description

A filter primitive that translates between variable-length arrays
and their corresponding external representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_authunix_parms

Serializes and deserializes credentials in an authentication
parameter structure.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_authunix_parms (XDR *xdrs, struct authunix_parms
*authp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
authp
A pointer to an authunix_parms structure.

5 Description

Used for externally describing standard UNIX credentials. On a
UCX host this routine encodes the host name, the user ID, and
the group ID. It sets the group ID list to NULL. This routine is
useful for users who want to generate these credentials without
using the ONC RPC authentication package.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_bool

Serializes and deserializes boolean data.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_bool (XDR *xdrs, bool_t *bp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
bp
A pointer to the boolean data.

5 Description

A filter primitive that translates between booleans (integers)
and their external representations. When encoding data, this
filter produces values of either one or zero.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_bytes

Serializes and deserializes a counted byte array.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_bytes (XDR *xdrs, char **bpp, u_int *sizep, u_int
maxsize);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
bpp
A pointer to a pointer to the byte array.
sizep
A pointer to the length of the byte array.
maxsize
The maximum size of the length of the byte array.

5 Description

A filter primitive that translates between a variable-length byte
array and its external representation. The length of the array
is located at sizep; the array cannot be longer than maxsize. If
*bpp is NULL, xdr_bytes allocates maxsize bytes.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_callhdr

Serializes and deserializes the static part of a call message
header.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_callhdr(XDR *xdrs, struct rpc_msg *chdrp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
chdrp
A pointer to the call header data.

5 Description

Describes call header messages. This routine is useful for users
who want to generate messages without using the ONC RPC package.
The xdr_callhdr routine encodes the following fields: transaction
ID, direction, RPC version, server program number, and server
version.

5 Return_Values

TRUE Indicate success.
FALSE Indicates failure.

4 xdr_callmsg

Serializes and deserializes an ONC RPC call message.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsgp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
cmsgp
A pointer to an rpc_msg structure that describes the RPC call
message.

5 Description

This routine is useful for users who want to generate messages
without using the ONC RPC package. The xdr_callmsg routine
encodes the following fields: transaction ID, direction, RPC
version, server program number, server version number, server
procedure number, and client authentication.

The pmap_rmtcall and svc_sendreply routines call xdr_callmsg.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_char

Serializes and deserializes character data.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_char(XDR *xdrs, char *cp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
cp
A pointer to a character.

5 Description

A filter primitive that translates between internal
representations of characters and their XDR representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_double

Serializes and deserializes VAX and IEEE double-precision
floating-point numbers.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_double(XDR *xdrs, double *dp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
dp
A pointer to the double-precision floating-point number.

5 Description

A filter primitive that translates between double-precision
numbers and their external representations.

This routine is actually implemented by four XDR routines:
xdr_ converts VAX D-format floating-point numbers
double_D
xdr_ converts VAX G-format floating-point numbers
double_G
xdr_ converts IEEE T-format floating-point numbers
double_T
xdr_ converts IEEE X-format floating-point numbers
double_X
You can reference these routines explicitly or you can use
compiler settings to control which routine is used when you
reference the xdr_double routine.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_enum

Serializes and deserializes enumerations.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_enum(XDR *xdrs, enum_t *ep);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
ep
A pointer to the enumeration data.

5 Description

A filter primitive that translates between enumerations (actually
integers) and their external representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_float

Serializes and deserializes VAX and IEEE single-precision
floating-point numbers.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_float(XDR *xdrs, float *fp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
fp
A pointer to a single-precision floating-point number.

5 Description

A filter primitive that translates between single-precision
floating-point numbers and their external representations.

This routine is actually implemented by two XDR routines:
xdr_ converts VAX F-format floating-point numbers
float_F
xdr_ converts IEEE T-format floating-point numbers
float_S

You can reference these routines explicitly or you can use
compiler settings to control which routine is used when you
reference the xdr_float routine.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_free

Deallocates the memory associated with the indicated data
structure.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_free(xdrproc_t proc, char *objp);

5 Arguments

proc
The XDR routine for the data structure being freed.
objp
A pointer to the data structure to be freed.

5 Description

Releases memory allocated for the data structure to which objp
points. The pointer passed to this routine is not freed, but what
it points to is freed (recursively). Use this routine to free
decoded data that is no longer needed. Never use this routine for
encoded data.

5 Return_Values

TRUE Indicate success.
FALSE Indicates failure.

4 xdr_hyper

Serializes and deserializes VAX quadwords (known in XDR as hyper-
integers).
Format
#include <ucx$rpcxdr.h>
bool_t xdr_hyper(XDR *xdrs, quad *hp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
hp
A pointer to the hyper-integer data.

5 Description

A filter primitive that translates between hyper-integers and
their external representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_int

Serializes and deserializes integers.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_int(XDR *xdrs, int *ip);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
ip
A pointer to the integer data.

5 Description

A filter primitive that translates between integers and their
external representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_long

Serializes and deserializes long integers.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_long(XDR *xdrs, long *lp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
lp
A pointer to a long integer.

5 Description

A filter primitive that translates between long integers and
their external representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_opaque

Serializes and deserializes opaque structures.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_opaque(XDR *xdrs, char *op, u_int cnt);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
op
A pointer to the opaque data.
cnt
The size of op in bytes.

5 Description

A filter primitive that translates between fixed-size opaque data
and its external representation. This routine treats the data
as a fixed length of bytes and does not attempt to convert the
bytes.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_opaque_auth

Serializes and deserializes ONC RPC authentication information
message.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *authp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
authp
A pointer to an opaque_auth structure describing authentication
information. The pointer should reference data created by the
authnone_create, authunix_create, or authunix_create_default
routine.

5 Description

Translates ONC RPC authentication information messages. This
routine is useful for users who want to generate messages without
using the ONC RPC package.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_pmap_#

Serializes and deserializes Portmapper parameters.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_pmap(XDR *xdrs, struct pmap *regs);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
regs
A pointer to the pmap structure. This structure contains the
program number, version number, protocol number, and port number.

5 Description

Describes parameters to various Portmapper procedures,
externally. This routine is useful for users who want to generate
these parameters without using the Portmapper interface.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_pmap_vms

Serializes and deserializes OpenVMS-specific Portmapper
parameters.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_pmap_vms(XDR *xdrs, struct pmap_vms *regs);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
regs
A pointer to the pmap_vms structure. This structure contains the
program number, version number, protocol number, port number and
the OpenVMS-specific process identification.

5 Description

This routine is similar to xdr_pmap(), except it also includes
the process identification in the pmap_vms structure.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_pmaplist_#

Serializes and deserializes a list of Portmapper port mappings.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rpp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
rpp
A pointer to a pointer to a pmaplist structure containing a
list of Portmapper programs and their respective information.
If the routine is used to decode a Portmapper listing, it sets
rpp to the address of a newly-allocated linked list of pmaplist
structures.

5 Description

Describes a list of port mappings, externally. This routine is
useful for users who want to generate these parameters without
using the Portmapper interface.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_pmaplist_vms

Serializes and deserializes a list of Portmapper port mappings
for OpenVMS systems.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_pmaplist_vms (XDR *xdrs, struct pmaplist_vms
**rpp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
rpp
A pointer to a pointer to a pmaplist_vms structure containing
a list of Portmapper programs and their respective information,
including OpenVMS-specific information.

5 Description

This routine is similar to the xdr_pmaplist routine, except it
also includes the process identification in the pmaplist_vms
structure.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_pointer

Serializes and deserializes indirect pointers and the data being
pointed to.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_pointer(XDR *xdrs, char **objpp, u_int objsize,
xdrproc_t objproc);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
objpp
A pointer to a pointer to the data being converted.
objsize
The size of the data structure in bytes.
objproc
The XDR procedure that filters the structure between its local
form and its external representation.

5 Description

An XDR routine for translating data structures that contain
pointers to other structures, such as a linked list. The xdr_
pointer routine is similar to the xdr_reference routine. The
differences are that the xdr_pointer routine handles pointers
with the value NULL and that it translates the pointer values to
a boolean. If the boolean is TRUE, the data follows the boolean.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_reference

Serializes and deserializes indirect pointers and the data being
pointed to.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_reference(XDR *xdrs, char **objpp, u_int objsize,
xdrproc_t objproc);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
objpp
A pointer to a pointer to the structure containing the data being
converted. If objpp is zero, the xdr_reference routine allocates
the necessary storage when decoding. This argument must be non-
zero during encoding.
objsize
The size of the structure in bytes.
objproc
The XDR procedure that filters the structure between its local
form and its external representation.

5 Description

A primitive that provides pointer chasing within structures.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_rejected_reply

Serializes and deserializes the remainder of an RPC reply message
after the header indicates that the reply is rejected.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply
*rrp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
rrp
A pointer to the rejected_reply structure describing the
rejected-reply message.

5 Description

Describes ONC RPC reply messages. This routine is useful for
users who want to generate messages without using the ONC RPC
package.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_replymsg

Serializes and deserializes the RPC reply header and then calls
the appropriate routine to interpret the rest of the message.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsgp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
rmsgp
A pointer to the rpc_msg structure describing the reply message.

5 Description

Describes ONC RPC reply messages. This routine is useful for
users who want to generate messages without using the ONC RPC
package. This routine interprets the message header and then
calls either the xdr_accepted_reply or the xdr_rejected_reply
routine to interpret the body of the RPC message.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_short

Serializes and deserializes short integers.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_short(XDR *xdrs, short *sp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
sp
A pointer to a short integer.

5 Description

A filter primitive that translates between short integers and
their external representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_string

Serializes and deserializes strings (arrays of bytes terminated
by a NULL character).
Format
#include <ucx$rpcxdr.h>
bool_t xdr_string(XDR *xdrs, char **spp, u_int maxsize);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
spp
A pointer to a pointer to a character string.
maxsize
The maximum size of the string.

5 Description

A filter primitive that translates between strings and their
corresponding external representations. Strings cannot be longer
than the value specified with the maxsize parameter.

While decoding, if *spp is NULL, this routine allocates the
necessary storage to hold the NULL-terminated string and sets
*spp to point to the allocated storage.

This routine is the same as the xdr_wrapstring routine, except
that this routine allows you to specify maxsize.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_u_char

Serializes and deserializes unsigned characters.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_u_char(XDR *xdrs, char *ucp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
ucp
A pointer to a character.

5 Description

A filter primitive that translates between internal
representation of unsigned characters and their XDR
representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_u_hyper

Serializes and deserializes unsigned VAX quadwords (known in XDR
as hyper-integers).
Format
#include <ucx$rpcxdr.h>
bool_t xdr_u_hyper(XDR *xdrs, unsigned quad *uhp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
uhp
A pointer to the unsigned hyper-integer.

5 Description

A filter primitive that translates between unsigned hyper-
integers and their external representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_u_int

Serializes and deserializes unsigned integers.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_u_int(XDR *xdrs, unsigned *uip);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
uip
A pointer to the unsigned integer.

5 Description

A filter primitive that translates between unsigned integers and
their external representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_u_long

Serializes and deserializes unsigned long integers.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
ulp
A pointer to the unsigned long integer.

5 Description

A filter primitive that translates between unsigned long integers
and their external representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_u_short

Serializes and deserializes unsigned short integers.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_u_short(XDR *xdrs, unsigned short *usp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
usp
A pointer to the unsigned short integer.

5 Description

A filter primitive that translates between unsigned short
integers and their external representations.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_union

Serializes and deserializes discriminant unions.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_union(XDR *xdrs, enum *dscmp, char *unp, struct
xdr_discrim *choices, xdrproc_t default);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
dscmp
A pointer to the union's discriminant.
unp
A pointer to the union's data.
choices
A pointer to an array of xdr_discrim structures. Each structure
contains an ordered pair of [value,proc]. The final structure in
the array is denoted by a pointer with the value NULL.
default
The address of the default XDR routine to call if the dscmp
argument is not found in the choices array.

5 Description

A filter primitive that translates between a discriminated union
and its corresponding external representation. The xdr_union
routine first translates the discriminant of the union located at
dscmp. This discriminant is always of type enum_t.

Next, the routine translates the union data located at unp. To
translate the union data the xdr_union routine first searches
the structure pointed to by the choices argument for the union
discriminant passed in the dscmp argument. If a match is found,
the xdr_union routine calls proc to translate the union data.

The end of the xdr_discrim structure array must contain an entry
with the value NULL for proc. If the xdr_union routine reaches
this entry before finding a match, the routine calls the default
procedure (if it is not NULL).

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_vector

Serializes and deserializes the elements of a fixed-length array
(known as a vector).
Format
#include <ucx$rpcxdr.h>
bool_t xdr_vector(XDR *xdrs, char **vecpp, u_int elnum, u_int
elsize, xdrproc_t elproc);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
vecpp
A pointer to a pointer to the array.
elnum
The number of elements in the array.
elsize
The size, in bytes, of each element.
elproc
The XDR routine to handle each element.

5 Description

A routine that calls elproc to prepare the elements of an array
for XDR messages.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdr_void

When there is no data to convert, this routine is passed to ONC
RPC routines that require an XDR procedure parameter.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_void();

5 Description

This routine is used as a placeholder for a program that passes
no data in a remote procedure call. Most client and server
routines expect an XDR routine to be called, even when there
is no data to pass.

5 Return_Values

This routine always returns TRUE.

4 xdr_wrapstring

Serializes and deserializes NULL-terminated strings.
Format
#include <ucx$rpcxdr.h>
bool_t xdr_wrapstring(XDR *xdrs, char **spp);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
spp
A pointer to a pointer to a string.

5 Description

A primitive that calls xdr_string(xdrs, sp, MAXUNSIGNED); where
MAXUNSIGNED is the maximum value of an unsigned integer. This
routine is useful because the ONC RPC client and server routines
pass the XDR stream handle and a single pointer as parameters
to any referenced XDR routines. The xdr_string routine, one
of the most frequently used ONC RPC primitives, requires three
parameters.

While decoding, if *sp is NULL, the necessary storage is
allocated to hold the null-terminated string and *sp is set to
point to it.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdrmem_create

Initializes an XDR stream descriptor for a memory buffer.
Format
#include <ucx$rpcxdr.h>
void xdrmem_create(XDR *xdrs, char *addr, u_int size, enum
xdr_op op);

5 Arguments

xdrs
A pointer to the XDR stream handle being created. The routine
xdrmem_create fills in xdrs with encoding and decoding
information.
addr
A pointer to the memory buffer.
size
The length of the memory buffer.
op
An XDR operation, one of: XDR_ENCODE, XDR_DECODE, and XDR_FREE.

5 Description

The stream handle xdrs is initialized with the operation op, the
buffer addr and size, and the operations context for an xdrmem
stream.

5 Return_Values

None

4 xdrrec_create

Initializes a record-oriented XDR stream descriptor.
Format
#include <ucx$rpcxdr.h>
void xdrrec_create(XDR *xdrs, u_int sendsize, u_int recvsize,
char *tcp_handle, int (*readit)(), int (*writeit)());

5 Arguments

xdrs
A pointer to the XDR stream handle being created. The routine
xdrrec_create fills in xdrs with encoding and decoding
information.
sendsize
The send buffer size.
recvsize
The receive buffer size.
tcp_handle
A pointer to an opaque handle that is passed as the first
parameter to the procedures (*readit)() and (*writeit)().
(*readit)()
Read procedure that takes the opaque handle tcp_handle. The
routine must use the following format:
int readit(char *tcp_handle, char *buffer, u_long len)
where tcp_handle is the client or server handle, buffer is the
buffer to fill, and len is the number of bytes to read. The
readit routine should return either the number of bytes read
or the value -1 if an error occurs.
(*writeit)()
Write procedure that takes the opaque handle tcp_handle. The
routine must use the following format:
int writeit(char *tcp_handle, char *buffer, u_long len)
where tcp_handle is the client or server handle, buffer is the
buffer to write, and len is the number of bytes to write. The
readit routine should return either the number of bytes written
or the value -1 if an error occurs.

5 Description

The stream descriptor for xdrs initializes the maximum allowable
size for a request recvsize and reply sendsize, the addresses of
the routine to perform the read (readit) and write (writeit), and
the TCP handle used for network I/O.

5 Return_Values

None

4 xdrrec_endofrecord

Generates an end-of-record for an XDR record.
Format
#include <ucx$rpcxdr.h>
bool_t xdrrec_endofrecord (XDR *xdrs, bool_t sendnow);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
sendnow
Indicates whether the record should be sent. If sendnow is TRUE,
xdrrec_endofrecord sends the record by calling the writeit
routine specified in the call to xdrrec_create. If sendnow is
FALSE, xdrrec_endofrecord marks the end of the record and calls
writeit when the buffer is full.

5 Description

This routine lets an application support batch calls and
pipelined procedure calls.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdrrec_eof

Moves the buffer pointer to the end of the current record and
returns an indication if any more data exists in the buffer.
Format
#include <ucx$rpcxdr.h>
bool_t xdrrec_eof (XDR *xdrs);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.

5 Description

Returns TRUE if there is no more input in the buffer after
consuming the rest of the current record.

5 Return_Values

TRUE Indicates no more input in the buffer.
FALSE Indicates more input in the buffer.

4 xdrrec_skiprecord

Guarantees proper record alignment during deserialization from an
incoming stream.
Format
#include <ucx$rpcxdr.h>
bool_t xdrrec_skiprecord (XDR *xdrs);

5 Arguments

xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.

5 Description

This routine ensures that the stream is properly aligned in
preparation for a subsequent read. It is recommended that when
a record stream is being used, this routine is called prior to
any operations that would read from the stream.

This routine is similar to the xdrrec_eof routine, except that
this routine does not verify if there is more data in the buffer.

5 Return_Values

TRUE Indicates success.
FALSE Indicates failure.

4 xdrstdio_create

Initializes a stdio XDR stream.
Format
#include <ucx$rpcxdr.h>
void xdrstdio_create (XDR *xdrs, FILE *file, enum xdr_op op);

5 Arguments

xdrs
A pointer to the XDR stream handle being created. The routine
xdrstdio_create fills in xdrs with encoding and decoding
information..
file
A pointer to the FILE structure that is to be associated with the
stream.
op
An XDR operation, one of: XDR_ENCODE, XDR_DECODE, and XDR_FREE.

5 Description

Initializes a stdio stream for the specified file.

5 Return_Values

None
3 System_Services_Routines
System Services routines let you write internet programs. The
$QIO service routine uses internet I/O function codes.

4 $ASSIGN

The Assign I/O Channel service provides a calling process with an
I/O channel. This makes it possible for the calling process to do
I/O operations on the internet pseudodevice.
Format
SYS$ASSIGN devnam, chan, [acmode], [mbxnam]
Returns
OpenVMS usage:longword (unsigned)
type: write only
access: by value
mechanism: 0
Longword condition value. All system services return (by
immediate value) a condition value in R0. Condition values that
can be returned by this service are listed under Condition Values
Returned.

5 Arguments

devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by fixed-length string descriptor
Name of the device to which $ASSIGN is to assign a channel.
The devnam argument specifies the address of a character
string descriptor pointing to the pseudodevice name string. The
character string contains UCX$DEVICE:.
chan
OpenVMS usage:channel
type: word (unsigned)
access: write only
mechanism: by reference
Number of the channel that is assigned. The chan argument is the
address of a word into which $ASSIGN writes the channel number.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the channel. The acmode
argument specifies the access mode. I/O operations on the channel
can be performed only from equal and more privileged access
modes.
mbxnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed length string descriptor
This argument is not used.

5 Description

The $ASSIGN system service establishes a path to a device but
does not check whether the calling process has the capability
to do I/O operations to the device. The device drivers may apply
privilege and protection restrictions. The calling process must
have NETMBX privilege to assign a channel.
System dynamic memory is required for the target device and the
I/O byte-limit quota from the process buffer is used.
When a channel is assigned to UCX$DEVICE:, the internet software
creates a new pseudodevice called BGn, where n is a unique
unit number. The corresponding channel number is used in any
subsequent operation requests for that device.
Channels remain assigned either until they are explicitly
deassigned with the Deassign I/O Channel ($DASSGN) service, or,
if they are user-mode channels, until the image that assigned the
channel exits.
Two programming examples for the $ASSIGN routine follow this
command description. $ASSIGN System Service (MACRO-32) uses
the MACRO-32 programming language and $ASSIGN System Service
(C Programming) uses the C programming language.

5 Condition_Values_Returned

SS$_NORMAL Service successfully completed.
SS$_ACCVIO The caller cannot read the device string or
string descriptor, or the caller cannot write
the channel number.
SS$_DEVALLOC The device is allocated to another process.
SS$_EXQUOTA The process has exceeded its buffered I/O byte
limit (BIOLM) quota.
SS$_IVDEVNAM No device name was specified, the logical name
translation failed, or the device name string
contains invalid characters.
SS$_IVLOGNAM The device name string has a length of zero or
has more than 63 characters.
SS$_NOIOCHAN No I/O channel is available for assignment.
SS$_NOSUCHDEV This warning code indicates that the specified
device does not exist.
Example .titleASAssignystem Service (MACRO-32)
.ident /01/
$inetsymdef ; INET symbols
dev: .ascid /ucx$device:/ ; INET device name
channel: .word 0 ; INET channel
.entry start,^m<>
;
; Assign an INET device
;
$assign_s devnam=dev, chan=channel
.
.
.
.end start
#module assgn_chanGN System Service (C Programming)
/*
**++
**
** This example assigns a channel to INET device
** using system service SYS$ASSIGN
**
**--
*/
/*
** INCLUDE FILES
*/
#include <descrip.h>
assgn_chan(channel)
unsigned short ; /* INET channel */
{
int status ; /* For return status */
/* Descriptor for Inet device name */
$DESCRIPTOR (dev, "UCX$DEVICE:");
/*
** Assign a channel to INET device
*/
status = SYS$ASSIGN( &dev,
&channel,
0,
0) ;
if ((status & 1) == 0) {
printf("Failed to assign channel to INET device \n") ;
return(status) ;
}
return(status) ;
/*
** channel will have the assigned
** channel number
*/
}

4 $CANCEL

This routine cancels all pending I/O requests on a specified
channel.
The equivalent C Socket call is the close() routine.
Format
SYS$CANCEL chan
Returns
OpenVMS usage:longword (unsigned)
type: write only
access: by value
mechanism: 0
Longword condition value. All system services return (by
immediate value) a condition value in R0. Condition values that
can be returned by this service are listed under Condition Values
Returned.

5 Arguments

chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
The channel on which the routine cancels the I/O. The chan
argument is a word containing the channel number.

5 Description

To cancel I/O on a channel, the access mode of the calling
process must be equal to or more privileged than the access mode
of the process that made the original channel assignment.
The $CANCEL service requires system dynamic memory and uses the
process's buffered I/O limit (BIOLM) quota.
Two programming examples for the $CANCEL routine follow this
command description. $CANCEL System Service (MACRO-32) uses
the MACRO-32 programming language and $CANCEL System Service
(C Programming) uses the C programming language.
When a request currently in progress is canceled, the driver is
notified immediately. Actual cancellation may or may not occur
immediately, depending on the logical state of the driver. When
cancellation does occur, the action taken for I/O in progress is
similar to that taken for queued requests. For example:
1. The specified event flag is set.
2. The first word of the IOSB of the I/O request you are
canceling is set to SS$_CANCEL if the I/O request is queued
or to SS$_ABORT if the I/O operation is in progress.
3. If the asynchronous system trap (AST) is specified, it is
queued.
For proper synchronization between this service and the actual
canceling of I/O requests to take place, the issuing process
must wait for the I/O process to complete normally. Note that
the I/O has been canceled. Outstanding I/O requests are canceled
automatically at image exit.

5 Condition_Values_Returned

SS$_NORMAL Service successfully completed.
SS$_ABORT A physical line went down during a network
connect operation.
SS$_CANCEL Warning code. The I/O operation was canceled
by executing a $CANCEL system service.
SS$_EXQUOTA The process has exceeded its buffered I/O
limit (BIOLM) quota.
SS$_INSFMEM Insufficient system dynamic memory is
available to cancel the I/O.
SS$_IVCHAN An invalid channel was specified (that is, a
channel number of zero or a number larger than
the number of channels available).
SS$_NOPRIV The specified channel is not assigned or was
assigned from a more privileged access mode.
Example 1-3 $CANCEL System Service (MACRO-32)
.title Cancel
.ident /01/
$inetsymdef ; INET symbols
dev: .ascid /ucx$device:/ ; INET device name
channel: .word 0 ; INET channel
.entry start,^m<>
;
; Assign an INET device
;
.
.
.
;
; Cancel I/O on INET device
;
$cancel_s chan=channel
.
.
.
.end start
#module cancel_ioCEL System Service (C Programming)
/*
**++
**
** This example cancels all pending I/O requests on the
** specified channel using system service SYS$CANCEL
**
**--
*/
/*
** INCLUDE FILES
*/
cancel_io(chan)
short chan ; /* INET channel on which I/O is to be canceled */
{
int status ; /* For return status */
/*
** Cancel the pending I/Os
*/
(status = SYS$CANCEL(chan)) ;
if ((status & 1) == 0) {
printf("Failed to cancel pending I/Os \n") ;
return(status) ;
}
return(status) ;
}

4 $DASSGN

This service deassigns (releases) an I/O channel that was
acquired using the Assign I/O Channel ($ASSIGN) service.
The equivalent C Socket call is the close() routine.
Format
SYS$DASSGN chan
Returns
OpenVMS usage:longword (unsigned)
type: read/write
access: by value
mechanism: 0
Longword condition value. All system services return (by
immediate value) a condition value in R0. Condition values that
can be returned by this service are listed under Condition Values
Returned.

5 Arguments

chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the I/O channel to be deassigned. The chan argument is
a word containing this number.

5 Description

After all communication is completed, use the $DASSGN system
service to free an I/O channel. A $DASSGN operation issued on
a channel associated with an internet pseudodevice does the
following:
1. Ends all pending operations to send or receive data at $QIO
level ($CANCEL system service).
2. Clears the port associated with the channel. When issuing
the $DASSGN system service for TCP/IP sockets, the socket
remains until the connection is closed on both sides, local
and remote.
3. Ends all communications with the internet pseudodevice that
the I/O channel identifies.
4. Frees the channel associated with the internet pseudodevice.
An I/O channel can be deassigned only from an access mode
equal to or more privileged than the access mode from which
the original channel assignment was made.
I/O channels assigned from user mode are automatically deassigned
at image exit.
Two programming examples for the $DASSGN routine follow this
command description. $DASSGN System Service (MACRO-32) uses
the MACRO-32 programming language and $DASSGN System Service
(C Programming) uses the C programming language.
NOTE
Even after a $DASSGN has been issued, a TCP socket may
remain until the TCP close timeout interval expires.
The default and maximum timeout interval is 10 minutes
if the peer host is not responding or 30 seconds after
acknowledging the socket close. Although, the TCP socket
is open, you cannot make reference to that socket after
issuing a $DASSGN.

5 Condition_Values_Returned

SS$_NORMAL Service successfully completed.
SS$_IVCHAN An invalid channel number was specified (that
is, a channel number of zero or a number
larger than the number of channels available).
SS$_NOPRIV The specified channel is not assigned, or is
assigned from a more privileged access mode.
Example 1-5 $DASSGN System Service (MACRO-32)

.title Dassign
.ident /01/
$inetsymdef ; INET symbols
exit
purge
: .ascid /ucx$device:/ ; INET device name
channel: .word 0 ; INET channel
.entry start,^m<>
.
.
.
;
; Deassign an INET device
;
$Dassgn_s chan=channel
.
.
.
.end start
#module dassgn_chanN System Service (C Programming)
/*
**++
**
** This example deassigns the specified channel
** using system service SYS$DASSNG
**
**--
*/
/*
** INCLUDE FILES
*/
dassgn_chan(chan)
short chan ; /* INET channel which is to be deassigned */
{
int status ; /* For return status */
/*
** Deassign the channel
*/
status = SYS$DASSGN(chan) ;
if ((status & 1) == 0) {
printf("Failed to deassign the channel\n") ;
return(status) ;
}
return(status) ;
}

4 $GETDVI

This service returns information about primary and secondary
device characteristics of the internet pseudodevice.
The $GETDVI service is completed asynchronously. It returns to
the caller after queuing the information request without waiting
for the requested information to be returned.
For synchronous completion, use the Get Device/Volume Information
and Wait ($GETDVIW) service. The $GETDVIW service is identical
to the $GETDVI service except that $GETDVIW returns to the caller
with the requested information.
The equivalent C Socket calls are the getpeername(),
getsockname(), and getsockopt() routines.
Format
SYS$GETDVI [efn],[chan], [devnam],itmlst,[iosb],[astadr],
[astprm],[nullarg]
Returns
OpenVMS usage:longword (unsigned)
type: write only
access: by value
mechanism: 0
Longword condition value. All system services return (by
immediate value) a condition value in R0. Condition values that
can be returned by this service are listed under Condition Values
Returned.

5 Arguments

efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $GETDVI returns the
requested information. The efn argument is a longword containing
this number.
When the request is initiated, $GETDVI clears the specified event
flag (or event flag 0 if efn was not specified). When $GETDVI
returns the requested information, it sets the specified event
flag (or event flag 0).
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the I/O channel assigned to the device about which
information is desired. The chan argument is a word containing
this number.
devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
The name of the device for which $GETDVI returns information. The
devnam argument is the address of a character string descriptor
pointing to the name string.
The device name string can be either a physical device name
or a logical name. If the first character in the string is an
underscore (_), the string is considered a physical device
name. Otherwise, the string is considered to be a logical name.
In that case, logical name translation is done until either a
physical device name is found or the system default for number of
translations has been reached.
If the device name string contains a colon, the colon and the
characters that follow it are ignored.
To identify a device to $GETDVI, specify either the chan argument
or the devnam argument, but not both. If both arguments are
specified, the chan argument is used.
If neither chan nor devnam is specified, $GETDVI uses a default
value of zero for chan.
itmlst
OpenVMS usage:item_list
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information about the device is to be
returned. The itmlst argument is the address of a list of item
descriptors, each of which describes an item of information. The
list of item descriptors is terminated by a length and item code
of zero. Single Item Descriptor depicts the format of an item
descriptor.
$GETDVI Item Descriptor Fields
buffer-length
A word containing a user-supplied integer specifying the
length (in bytes) of the buffer for which the $GETDVI returns
information. The length of the buffer needed depends on
the item code specified in the item code field of the item
descriptor. If the value of buffer-length is too small,
$GETDVI truncates the data.
item-code
A word containing a user-supplied symbolic code that
specifies the information that $GETDVI returns. These
codes are defined by the $DVIDEF macro, which is defined
in SYS$LIBRARY:STARLET.MLB for the MACRO-32 language and
SYS$LIBRARY:DVIDEF.H for the C language. Each item code is
listed in the $GETDVI Item Code Descriptions.
buffer-address
A longword containing the user-supplied address of a word in
which the length of the information (in bytes) is returned.
return-length-address
A longword containing the user-supplied address of a word in
which $GETDVI writes the length of the information it returned
(in bytes).
$GETDVI Item Codes
Table 1-1 $GETDVI Item Code Descriptions
Item Code Description
DVI$_ A 4-byte hexadecimal number. The DVI$_ACP_TCP symbol
ACPTYPE defines the ACP type code that $GETDVI can return.
This symbol is defined in the UCX$INETDEF symbol
definition file.
DVI$_ Returns device-independent characteristics as a 4-
DEVCHAR byte vector. Each characteristic is represented by
a bit. When $GETDVI sets a bit, the device has the
corresponding characteristic. Each bit in the vector
has a symbolic name. These symbolic names are defined
by the $DEVDEF macro, and are listed in Symbolic
Names for $GETDVI.
Table 1-2 Symbolic Names for $GETDVI
Symbol Device Type
DVI$_NET Network device
DVI$_AVL Available
DVI$_MNT Mounted
DVI$_IDV Input device
DVI$_ODV Output device
DVI$_STS
When DVI$_STS is specified, $GETDVI returns the device unit
status as a 4-byte vector. Each bit in the vector, when set,
corresponds to a symbolic name that is defined by the $UCBDEF
macro. These symbols are defined in Device Unit Status Symbolic
Names.
Table 1-3 Device Unit Status Symbolic Names
Symbol Device Type
UCB$M_ONLINE Online
UCB$M_TEMPLATE Template
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
The iosb argument signifies the I/O status block that receives
the final completion status code. The iosb is the address of the
quadword I/O status block.
When the iosb argument is specified, $GETDVI sets the quadword
to zero when the request is initiated. When the request is
completed, a condition value is returned to the first longword.
The second longword is reserved for DIGITAL.
Although the iosb argument is optional, DIGITAL strongly
recommends that you specify it for the following reasons:
o If you are using an event flag to signal the completion of
the service, you can test the I/O status block for a condition
value. This allows you to be sure that the event flag was not
set by an event other than service completion.
o If you are using the $SYNCH system service to synchronize the
completion of the service, you must use iosb as an argument.
The iosb argument is required for $SYNCH.
o The condition value returned in R0 and the condition value
returned in the I/O status block provide information about
different aspects of the call to the $GETDVI service. The
condition value returned in R0 gives you information about the
success or failure of the service call itself. The condition
value returned in the I/O status block gives you information
about the success or failure of the service operation.
Therefore, to accurately assess the success or failure of the
call to $GETDVI, you must check the condition values returned
in both R0 and the I/O status block.
astadr
OpenVMS usage:ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed when $GETDVI is completed. The
astadr argument is the address of the entry mask of this routine.
If astadr is specified, the AST routine executes at the same
access mode as the caller of the $GETDVI service.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST service routine specified
by the astadr argument. The astprm argument contains a longword
parameter value.
nullarg
OpenVMS usage:null_arg
type: quadword (unsigned)
access: read only
mechanism: by reference
Place-holding argument. This argument is reserved for DIGITAL.

5 Description

The chan argument can be used only if the channel has already
been assigned and the caller's access mode is equal to or more
privileged than the access mode from which the original channel
assignment was made.
The $GETDVI system service does not need to have a channel
assigned to the device about which information is desired.
The $GETDVI system service returns information about both primary
and secondary characteristics of the device. By default, $GETDVI
returns information about the primary characteristics only.
To obtain information about secondary device characteristics,
the item code specifying the information desired must be merged
(ORed) with the code DVI$M_SECONDARY.
Information about primary and secondary devices can be obtained
in a single call to $GETDVI.
In most cases, the two sets of characteristics (primary and
secondary) returned by $GETDVI are identical. However, the two
sets provide different information in the following cases:
o If the device has an associated mailbox, the primary
characteristics are those of the assigned device and the
secondary characteristics are those of the associated mailbox.
o If the device represents a logical link on the network, the
secondary characteristics contain information about the link.
Unless otherwise stated in the item code description, $GETDVI
returns information about the local node only.

5 Condition_Values_Returned

SS$_NORMAL Service successfully completed.
SS$_ACCVIO The device name string descriptor, device name
string, or itmlst argument cannot be read or
the buffer or return length longword cannot be
written by the caller.
SS$_BADPARAM The item list contains an invalid item code,
or the return length address field in an item
descriptor specifies less than 4 bytes for the
return length information.
SS$_EXASTLM The process has exceeded its AST limit quota.
SS$_IVCHAN An invalid channel number was specified (that
is, a channel number of zero or a number
greater than the number of channels).
SS$_IVDEVNAM The device name string contains invalid
characters or neither the devnam nor the chan
arguments was specified.
SS$_IVLOGNAM The device name string has either a length of
zero or more than 63 characters.
SS$_NONLOCAL This warning code indicates that the device is
on a remote system.
SS$_NOPRIV The specified channel is not assigned or was
assigned from a more privileged access mode.
SS$_NOSUCHDEV This warning code indicates that the specified
device does not exist on the host system.

4 $QIO

This service queues an I/O request to a channel associated with
an internet pseudodevice.
The $QIO service is completed asynchronously, which means it
returns to the caller immediately after queuing the I/O request,
without waiting for the I/O operation to be completed.
For synchronous completion, use the Queue I/O Request and Wait
($QIOW) service. The $QIOW service is identical to the $QIO
service, except the $QIOW returns to the caller after the I/O
operation has been completed.
The equivalent C Socket calls are the bind() and listen()
routines.
Format
SYS$QIO [efn],chan,func, [iosb],[astadr],[astprm],[p1],
[p2],[p3],[p4],[p5], [p6]
Returns
OpenVMS usage:longword (unsigned)
type: write only
access: by value
mechanism: 0
Longword condition value. All system services return (by
immediate value) a condition value in R0.

5 Arguments

efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Event flag that $QIO sets when the I/O operation is completed.
The efn argument is a longword value containing the number of the
event flag.
If efn is not specified, event flag 0 is set.
The specified event flag is set if the service terminates without
queuing an I/O request.
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
I/O channel that is assigned to the device to which the request
is directed. The chan argument is a word value containing the
number of the I/O channel.
func
OpenVMS usage:function_code
type: word (unsigned)
access: read only
mechanism: by value
Function codes and function modifiers specify the operation of
the software. The func argument is a longword value containing
the function code.
Refer to the Internet I/O Function Codes for complete information
about the function codes and function modifiers.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block to receive the final completion status of the
I/O operation. The iosb is the address of the quadword I/O status
block.
When the $QIO begins executing, the event flag clears. The $QIO
also clears the quadword I/O status block if the iosb argument is
specified.
Although the iosb argument is optional, DIGITAL strongly
recommends that you specify it for the following reasons:
- If you are using an event flag to signal the completion of
the service, you can test the I/O status block for a condition
value. This assures that the event flag was not set by an
event other than service completion.
- If you are using the OpenVMS $SYNCH service to synchronize
service completion, the I/O status block is a required
argument for $SYNCH.
- The condition values returned in the R0 and those returned
in the I/O status block provide information about different
aspects of the call to the $QIO service. The condition value
returned in R0 gives you information about the success or
failure of the service call itself. The condition values
returned in the I/O status block report the success or failure
of the service operation. Therefore, to access the success or
failure of the $QIO call, check the condition values returned
in both the R0 and the I/O status block.
astadr
OpenVMS usage:ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed when the I/O is completed.
The astadr argument is the address of the entry mask to the AST
routine.
The AST routine executes at the access mode of the caller of
$QIO.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST service routine. The astprm
argument is a longword value of the AST parameter.
p1 to p6
OpenVMS usage:varying_arg
type: longword (unsigned)
access: read only
mechanism: by reference, by value, or descriptor
Optional device- and function-specific I/O request arguments. The
parameter values contained in these arguments vary according to
the function for which they are used. See Internet I/O Function
Codes for the descriptions of internet I/O function codes.

5 Description

$QIO operates only on assigned I/O channels and only from access
modes that are equal to or more privileged than the access mode
from which the original channel assignment was made.
For TCP/IP, $QIO uses the following system resources:
o The process's AST limit (ASTLM) quota, if an AST service
routine is specified.
o System dynamic memory, which is required to queue the I/O
request. System dynamic memory requirements are protocol
specific.
o Additional memory may be required on a device-dependent basis.
For $QIO, completion can be synchronized as follows:
o By specifying the astadr argument to have an AST routine
execute when the I/O is completed.
o By calling the $SYNCH Synchronize service to await completion
of the I/O operation. (If you want your I/O operation to
complete synchronously, use the $QIOW system service instead.)

5 Condition_Values_Returned

Each function used with $QIO has its own error codes. See the
error codes listed under the individual internet I/O function
code descriptions that comprise the remainder of this chapter.

5 Internet_I/O_Function_Codes

The internet pseudodevice allows physical, logical, and virtual
block I/O functions. The physical and logical functions are used
only with the IP layer. Internet I/O Function Codes lists the
basic functions and their modifiers. The sections that follow
describe these functions in greater detail.
Table 1-4 Internet I/O Function Codes
Function Code and Function
Arguments Modifier Description
IO$_ACCESS p3,p4 IO$M_ACCEPT Open a connection.
IO$_ACPCONTROL p1 Perform an ACP (ancillary
control process) operation.
IO$_DEACCESS p4 IO$M_SHUTDOWN Abort or close a connection.
IO$_READVBLK IO$M_ Read virtual block.
p1,p2,p3,p4,p6 INTERRUPT
IO$M_PURGE Control the buffer
IO$M_LOCKBUF operations.
IO$_SENSEMODE Read the internet
[p2],p3,p4,p6 pseudodevice
characteristics.
IO$_SENSECHAR Read the internet
[p2],p3,p4,p6 pseudodevice
characteristics.
IO$_SETMODE IO$M_OUTBAND Set the internet
p1,[p2], p3,p4,p5 IO$M_READATTN pseudodevice characteristics
IO$M_WRTATTN for subsequent operations.
IO$_SETCHAR IO$M_OUTBAND Set the internet
p1,[p2],p3,p4,p5 IO$M_READATTN pseudodevice characteristics
IO$M_WRTEATTN for subsequent operations.
IO$_WRITEVBLK IO$M_ Write virtual block.
p1,p2,p3,p4,p5 INTERRUPT
The following table contains the file names of the symbol
definition files. These files specify $QIO arguments
(p1,p2,...p6) for applications written in the corresponding
programming languages. You must invoke the symbol definition
by using the appropriate include statement in your application.
Table 1-5 Internet Symbol Definition Files
File Name Language
UCX$INETDEF.H DEC C or VAX C
UCX$INETDEF.FOR VAX Fortran
UCX$INETDEF.PAS VAX PASCAL
UCX$INETDEF.MAR MACRO-32
UCX$INETDEF.PLI VAX PL/1
UCX$INETDEF.R32 BLISS-32
UCX$INETDEF.ADA VAX ADA
UCX$INETDEF.BAS VAX BASIC

6 IO$_ACCESS

When you are using a connection-oriented protocol such as TCP,
the IO$_ACCESS function initiates a connection and specifies a
remote port and address. When you use a connectionless protocol
such as UDP, the IO$_ACCESS function sets the remote port and
address.
For TCP, a connection request times out in a specified interval
(75 seconds by default). This interval can be changed by the
system manager. The program can also set a specific timeout
interval for a socket that it has created.
The equivalent C Socket function is connect() or accept().

7 Arguments

UCX usage remote socket name
type longword (unsigned)
access read only
mechanism by descriptor
For the IO$_ACCESS function, the p3 parameter is the address
of a UCX item_list_2 descriptor that points to the sockaddr_in
structure containing the remote host address and port number.
For the IO$_ACCESS function with the IO$M_ACCEPT modifier, the
p3 parameter is the address of a UCX item_list_3 descriptor that
points to a socket name and a returned longword that contains the
length.

UCX usage the device channel
type word (unsigned)
access read only
mechanism by reference
The p4 parameter specifies the address of a word value containing
the channel for the I/O operations after the connection is
established. This input parameter is specified only with the
IO$M_ACCEPT modifier (for TCP).

7 Function_Modifiers

IO$M_ACCEPT Accepts a connection request issued from
another process. The remote host address and
remote port number are output parameters.
IO$M_NOW Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the I/O
operation to block, the system completes the
I/O operation and returns the $QIO error code
SS$_SUSPENDED. The corresponding UNIX error
code is EWOULDBLOCK.

7 Condition_Values_Returned

SS$_ABORT Programming error, INET management error, or
hardware error. Aborts execution of the I/O
operation.
SS$_BADPARAM Programming error that occurred for one of the
following reasons:
1. You tried to execute a $QIO function
without specifying a device socket.
2. You tried to issue an IO$_ACCESS!IO$M_
ACCEPT function without specifying the
channel for the device socket that will
be used for the accepted connection (p4 is
null or invalid).
3. You tried to issue an IO$_ACCESS function
without specifying the address of the
remote device socket address (p3 as null).
SS$_BUGCHECK Inconsistent state. Report the problem to your
DIGITAL support representative.
SS$_CANCEL Warning code. The I/O operation was canceled
by a $CANCEL system service.
SS$_CONNECFAIL Programming error, INET management error, or
hardware error. The connection was abnormally
terminated for one of the following reasons:
1. An IO$_ACCESS!IO$M_ACCEPT failed because
the listener socket closed. The cause can
be local or remote.
2. An existing connection was aborted because
of an error detected during communication.
SS$_DEVINACT Programming or INET management error. The
driver was not started. Issue a UCX START
COMMUNICATION command before issuing any $QIO
call.
SS$_DEVNOTMOUNT Programming or INET management error.
You improperly executed the INET startup
procedure. The driver was loaded, but the
INET_ACP was not activated.
SS$_EXQUOTA Programming or system management error. Socket
quota (maximum number of sockets allowed) or
user quotas exceeded.
SS$_FILALRACC Programming error. The socket name is already
in use by one of the following:
1. On a raw socket, you specified a remote
INET socket address with an IO$_ACCESS
function, but an INET address was already
specified with a previous IO$_ACCESS.
2. On a datagram, you specified a remote INET
socket address with an IO$_ACCESS function,
but an INET address was already specified
with a previous IO$_ACCESS.
3. On a stream socket, you issued an IO$_
ACCESS function on a stream socket that was
already connected.
SS$_ILLCNTRFUNC Programming error. Illegal function.
SS$_INSFMEM INET management or programming error. Not
enough buffer space for allocation. The INET
software needs more buffer space.
SS$_IVADDR Programming error. The specified INET address
was not found or an invalid port and INET
address combination was specified with the
IO$_ACCESS function. Port zero is not allowed
with an IO$_ACCESS function.
SS$_IVBUFLEN Programming error. Socket address buffer has
an invalid size.
SS$_NOLICENSE Programming or system management error.
DIGITAL TCP/IP for OpenVMS license is not
present.
SS$_NOLINKS Programming error. An attempt was made
to disconnect a socket that has not been
connected.
SS$_LINKABORT Communication status change. The remote socket
closed a connection.
SS$_PROTOCOL Programming error. The address family of
the remote INET address specified with an
IO$_ACCESS function is not supported (UDP/IP
or TCP/IP). The address family should be
UCX$C_AF_INET.
SS$_REJECT Programming error, INET management error, or
hardware error. Connection is rejected for one
of the following reasons:
1. An attempt was made to connect to a remote
socket that is already connected.
2. An error was encountered while establishing
the connection.
3. The peer socket either refused a connection
request or wants to close the connection.
SS$_SHUT The network is being shut down.
SS$_SUSPENDED The operation is blocked. The accept
operation cannot complete because there are
no connection requests received. The socket is
marked as nonblocking.
SS$_TIMEOUT Programming error, INET management error, or
hardware error. A TCP/IP connection timed out
while in the process of being established. The
default time interval is 75 seconds.
SS$_UNREACHABLE Communication status. Remote host or network
is not reachable.

6 IO$_ACPCONTROL

The internet ACP Control I/O (IO$_ACPCONTROL) function requests
that the ACP perform operations such as providing information
from the internet host and network database files.
The equivalent C Socket functions are gethostbyname(),
gethostbyaddr(), getnetbyname(), or getnetbyaddr(). Two
programming examples for the IO$_ACPCONTROL routine follow
this command description. IO$_ACPCONTROL Function (MACRO-32
Programming) uses the MACRO-32 programming language and IO$_
ACPCONTROL Function (C Programming) uses the C programming
language.

7 Arguments

p1
UCX usage subfunction code
type longword (unsigned)
access read only
mechanism by descriptor
The p1 parameter is the address of the OpenVMS descriptor for a
4-byte block. The block consists of a subfunction type (1 byte),
a call code (1 byte), and 2 bytes reserved for DIGITAL (must be
zero).
Valid INET Subfunction Codes lists the valid INET subfunction
codes. These symbols are defined by the $INETACPFSYMDEF module in
the UCX$INETDEF symbol definition file.
Table 1-6 Valid INET Subfunction Codes
INET Subfunction Code Code Function
INETACP_FUNC$C_ Get the INET address of the specified
GETHOSTBYNAME host from the internet host database.
INETACP_FUNC$C_ Get the host name of the specified
GETHOSTBYADDR internet address from the internet
host database.
INETACP_FUNC$C_ Get the INET address of the specified
GETNETBYNAME network from the internet network
database.
INETACP_FUNC$C_ Get the network name of the specified
GETNETBYADDR internet address from the internet
network database.
When these functions are performed, IO$_ACPCONTROL searches the
local database for the host's name. If it does not find the host
name in the local host database, IO$_ACPCONTROL then searches the
BIND database if the BIND resolver is enabled.
INET Call Codes lists the valid INET call codes that IO$_
ACPCONTROL accepts.
Table 1-7 INET Call Codes
Code Description
INETACP$C_ALIASES Obtains the list of alias names associated
with the specified host or network from
the internet hosts or network database.
INETACP$C_TRANS Returns a longword value of the internet
address in dotted-decimal notation.
INETACPC$C_HOSTENT_ Returns full host information in a
OFFSET modified hostent structure. In the
modified structure, pointers are replaced
with offsets from the beginning of the
structure.
INETACP$C_NETENT_ Returns full network information in
OFFSET a modified netent structure. In the
modified structure, pointers are replaced
with offsets from the beginning of the
structure.
The INET_ACP call codes are defined by the $INETACPSYMDEF module
in the UCX$INETDEF symbol definition file.
The hostent and netent structures are defined by the $HOSTENTDEF
and $NETENTDEF modules in the UCX$INETDEF symbol definition file.
p2
UCX usage input parameter
type longword (unsigned)
access read only
mechanism by descriptor
The p2 parameter is the address of the string descriptor for
the input parameter. The input parameter contains the host name,
network name, host address, or network INET address. The INET
address is specified as a character string. The network and
host numbers are separated by periods. The address is in network
format. For example, in the address 128.20.10.5, the network is
128.20.10 and the host is 5.
p3
UCX usage length of the output string
type word
access write only
mechanism by reference
The p3 parameter is the address of the word location where the
length of the output string is returned.
p4
UCX usage output character string address
type longword or character string
access write only
mechanism by descriptor
The p4 parameter is the address of the descriptor for the output
character string that contains the host name, network name,
host address, or the network INET address. The INET address is
returned as a character string. The network and host numbers are
separated by periods. The address is in dotted decimal notation.
Alias names are separated by a null character (a 0 byte). The
length of the returned string includes all null characters that
separate aliases.

7 Condition_Values_Returned

SS$_ABORT Unknown cause of an internal error. An
unspecified error was detected while
performing an INET ACP function.
SS$_BADPARAM Programming or internal error. You specified
a bad parameter (name or address) in a
GET{HOST,NET}BY{NAME,ADDRESS} ACP call.
SS$_BUFFEROVF Programming error. There was not enough space
for returning all alias names in a
GET{HOST,NET}BY{NAME,ADDRESS} ACP call.
SS$_ENDOFFILE The information requested is not in the
database.
SS$_ILLCNTRFUNC Programming error. An invalid ACP function
code was specified in an IO$_ACPCONTROL
function.
SS$_NOPRIV INET management error. No privilege for the
execution of an INET ACP function.
SS$_RESULTOVF Programming error. The ACP overflowed the
buffer in returning a parameter.
SS$_SHUT The network is being shut down.
Example .titleOGet_host_by_namection (MACRO-32 Programming)
.ident /01/
.library /sys$share:lib.mlb/
.show meb
$inetacpfdef
dev: .ascid /ucx$device:/
chan: .long 0
iosb: .quad 0
command: .long length
.address comm
comm: .byte 1 ; get host
.byte 0
.word 0
length=.-comm
host_d: .ascid /BRIGIT/
host_nam: .ascid /
.blkl 32
title: .ascid /Host address:/
title1: .ascid /Host name:/
.entry start,^m<>
;
; assign Internet device for INIT
;
$assign_s devnam=dev, chan=chan
blbs r0,as1
brw exit
as1:
$qioW_s efn=#1,-
chan=chan, -
func=#io$_acpcontrol,-
iosb= iosb,-
p1=command,p2=#host_d,P3=#host_nam,p4=#host_nam
blbc r0,print
cmpw #ss$_normal,iosb
beqlu print
movzwl iosb,r0
print:
movl r0,r10
pushab title1
calls #1,g^lib$put_output
pushab host_d
calls #1,g^lib$put_output
pushab title
calls #1,g^lib$put_output
pushab host_nam
calls #1,g^lib$put_output
movl r10,r0
exit:
ret
.end start
#module gethost_addrCONTROL Function (C Programming)
/*
**++
**
** This example gets host address for the given host name
** using the Internet ACP Control I/O function IO$_ACPCONTROL
**
**
**--
**/
/*
** INCLUDE FILES
*/
#include <descrip.h>
#include <iodef.h>
#include <ucx$inetdef.h>
gethost_addr (addr)
int *addr;
{
/* Descriptor for Inet device name */
struct dsc$descriptor Inet_dev =
{11, DSC$K_CLASS_S, DSC$K_DTYPE_T, "UCX$DEVICE:" };
/* Descriptor for the host name for which to get the Internet address */
struct dsc$descriptor host_name =
{6, DSC$K_CLASS_S, DSC$K_DTYPE_T, "lassie" };
/* Descriptor for ACP command */
struct dsc$descriptor command =
{0, DSC$K_CLASS_S, DSC$K_DTYPE_T, 0 };
/* Descriptor for host address */
struct dsc$descriptor host_ad =
{0, DSC$K_CLASS_S, DSC$K_DTYPE_T, 0 };
int status ; /* Return status */
int iosb [2] ; /* I/O status block */
short channel ; /* INET dev channel */
short retlen ; /* Word to return address length */
/*
** ACP command: INETACP$C_TRANS - If this bit set, the Internet
** address will be returned as a long word integer value.
** INETACP_FUNC$C_GETHOSTBYNAME indicates that it is a function
** to get the host address given the host name.
*/
int comm = INETACP$C_TRANS * 256 + INETACP_FUNC$C_GETHOSTBYNAME ;
/* byte 1,2,0,0 */
int addr_buff[8]; /* buffer for ACP output */
/*
** INET ACP command
*/
command.dsc$a_pointer = &comm ;
command.dsc$w_length = sizeof(comm) ;
/*
** Descriptor for ACP output
*/
host_ad.dsc$a_pointer = &addr_buff ;
host_ad.dsc$w_length = sizeof(addr_buff) ;
/*
** Assign a channel to INET device
*/
status = SYS$ASSIGN(&Inet_dev,
&channel,
0,
0);
if ((status & 1) == 0) {
printf("Failed to assign channel to INET device \n");
return(status);
}
/*
** Get the Host address (longword)
*/
status = SYS$QIOW(1,
channel, /* Channel number */
IO$_ACPCONTROL, /* I/O function */
iosb, /* I/O status */
0,
0,
&command, /* P1 command */
&host_name, /* P2 host name */
&retlen, /* P3 adrs to ret length */
&host_ad, /* P4 adrs output */
0, 0);
if (((status & 1) && (iosb[0] & 1)) == 0) {
printf("Failed to get INET address for host %s \n",
host_name.dsc$a_pointer);
return (status) ;
}
/*
** Return the host Internet address
*/
addr = addr_buff[0];
/*
** Deassign the INET dev channel
*/
SYS$DASSGN (channel);
return (status);
}

6 IO$_DEACCESS

The IO$_DEACCESS function closes a connection. You can use a flag
to specify whether pending I/O operations will be completed or
discarded before the function is completed. After the function
completes, $QIOs to transmit data are no longer allowed. To
resume transmitting on the channel being used, you must issue
the appropriate functions to initialize a communication link. If
it is required for the protocol, you must also issue $QIOs with
IO$_SETMODE, and if it is required for the protocol, IO$_ACCESS
as well.
Issuing an IO$_DEACCESS function disconnects the link between
the two communicating agents previously established with an IO$_
ACCESS function. The connection is discontinued, but messages
queued for transmission are sent to the connection peer before
finally disconnecting the link.
An IO$_DEACCESS function prevents the user process that issued
the function from sending any more data. It also ensures
successful delivery of all data queued before the IO$_DEACCESS
function was issued, unless there is a fatal error. A fatal error
will be signaled. The user may continue to receive data until it
is signaled that the connection peer has closed the connection.
Before a receiving process with a connection-oriented protocol is
notified about a synchronous disconnection, all the data that the
peer sent is received.
You can specify a wait time or time-to-linger socket parameter
(UCX$C_LINGER option) for transmission completion before
disconnecting the connection. Use the IO$_SETMODE or IO$_SETCHAR
function to set and clear the UCX$C_LINGER option.
If you set the UCX$C_LINGER option, a $QIO call that uses the
IO$_DEACCESS function allows data queued to the socket to arrive
at the destination. The system is blocked until data arrives at
the remote socket. The socket data structure remains open for the
duration of the TCP idle time interval.
If you do not set the UCX$C_LINGER option (option is set to 0), a
$QIO call that uses the IO$_DEACCESS function discards any data
queued to the socket and deallocates the socket data structure.
NOTE
For compatibility with UNIX TCP/IP, the UCX implementation
of TCP/IP forces a time-to-linger of 2 minutes on stream
sockets.
The equivalent C Socket function is close() or shutdown().

7 Arguments

p4
UCX usage flags
type byte (unsigned)
access read only
mechanism by value
This argument is used only with the IO$M_SHUTDOWN function
modifier. The following table lists the IO$M_SHUTDOWN flags
(defined in the UCX$INETDEF symbol definition file) that you
can use to specify the disposition of pending I/O operations.
Shutdown Flag Description
UCX$C_DSC_RCV Discards messages from the receive queue and
disallows further receiving. Pending messages
in the receive queue for this connection are
discarded. The socket is put in CANTRCVMORE
state.
UCX$C_DSC_SND Discards messages from the send queue and
disallows further sending. Pending messages
in the transmit queue for this connection are
discarded. The socket is put in CANTSNDMORE
state.
UCX$C_DSC_ALL Discards all messages and disallows both sending
and receiving (socket is put in the CANTRCVMORE
and CANTSNDMORE states). All pending messages
are discarded. Specifying this flag has the same
effect as issuing a $CANCEL function followed by
an IO$_DEACCESS function without any flags.

7 Function_Modifiers

IO$M_SHUTDOWN Causes all or part of the full-duplex
connection on the device socket to be shut
down. The p4 parameter specifies shutdown
flags.
IO$M_NOW Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the
I/O operation to block, the system completes
the I/O operation and returns the error code
SS$_SUSPENDED.

7 Condition_Values_Returned

SS$_ABORT Programming error, INET management error,
or hardware error. The execution of the I/O
function aborts. A disconnect was requested on
a connection that already started a disconnect
operation.
SS$_BADPARAM Programming error. You specified a $QIO
function using an invalid parameter. You
tried to execute one of the I/O functions
without specifying a device socket. Instead,
you should first create a device socket by
issuing a $QIO with the IO$_SETMODE function
and the proper parameters.
SS$_CANCEL Warning code. The I/O operation canceled by
executing a $CANCEL system service routine.
SS$_DEVINACT INET management error. The driver was
not started. You must execute a UCX START
COMMUNICATION before issuing a $QIO operation.
SS$_DEVNOTMOUNT INET management error. You improperly executed
the INET startup procedure. The driver was
loaded, but the INET_ACP function was not
activated.
SS$_NOLINKS Programming error because of one of the
following reasons:
1. The socket was not connected (TCP/IP) or
an INET port and address were not specified
with an IO$_ACCESS (UDP/IP) or IP.
2. You tried to disconnect an unconnected
socket.
SS$_SHUT The network is being shut down.

6 IO$_READVBLK

Read functions transfer data received from an internet host and
store that data in system-dynamic space on the virtual memory
address of the user process. The TCP/IP software provides the
READ I/O function code IO$_READVBLK, which reads a virtual block
of a stream socket, datagram, or raw socket.
Received messages are stored in system-dynamic memory and copied
to user buffers when the software issues a read operation.
If you specify multiple buffers, the buffers are filled in the
order specified in the p6 list.
The TCP/IP software fills in these user buffers according to the
protocol (socket type).
For TCP/IP (stream socket), data is buffered in system space
as a stream of bytes. The user buffer specified with a $QIO is
filled in with data that is being buffered in system space. The
I/O is completed when there is no more data in the system space,
or there is no more available space in the user buffer. Data
that is buffered in the system space but did not fit in the user
buffer is available to the user in subsequent $QIOs. No data is
discarded or lost.
Datagram and raw socket data is buffered in system space as a
chain of records. The user buffer specified with a $QIO is filled
in with data that is being buffered in one record in system
space. One I/O operation reads data from one record. The I/O
completes when there is no more space in the user buffer or when
all data from the record has been transferred to the user buffer.
Data remaining in the current record in system space that did not
fit in the user buffer is discarded. A subsequent $QIO reads data
from the next record buffered in system space.
Use the UCX SHOW DEVICE_SOCKET /FULL command to display counters
related to read operations.
The equivalent C Socket function is the recv*() or read()
routine.
Three programming examples for the IO$_READVBLK routine follow
this command description. IO$_READVBLK Function (MACRO-32
Programming) uses the MACRO-32 programming language to read a
vectored buffer. IO$_READVBLK Function - Vectored Buffers (C
Programming) uses the C programming language to read a vectored
buffer. IO$_READVBLK Function - INET device (C Programming) uses
the C programming language to read from an INET driver.

7 Arguments

p1
UCX usage buffer
type longword (unsigned)
access read only
mechanism by reference
The p1 argument specifies the starting virtual address of the
buffer that is to receive the data.
p2
UCX usage buffer length
type longword (unsigned)
access read only
mechanism by value
The p2 argument specifies the size (in bytes) of the buffer that
is to receive the data.
p3
UCX usage remote socket name for the source of the message
type longword (unsigned)
access read only
mechanism by descriptor
The p3 argument specifies the address of a UCX item_list_3
descriptor with a buffer that contains the remote socket name
of the source of the message. The remote socket is composed of
the remote port and host internet address.
The parameter name for the descriptor is UCX$C_SOCK_NAME, which
is defined in the UCX$INETDEF symbol definition file.
p4
UCX usage flags
type word (unsigned)
access read only
mechanism by value
The p4 argument specifies the flags for the read operation. The
valid flags are described in Valid Flags for the p4 Argument.
Table 1-8 Valid Flags for the p4 Argument
Flag Description
UCX$C_MSG_OOB Reads an out-of-band byte.
UCX$C_MSG_PEEK Reads a message but leaves the message in the
queue. Another read operation shows the same
message.
UCX$C_MSG_NBIO Does not block the I/O operation if the
receive queue is empty. Similar to using IO$M_
NOWAIT.
UCX$C_MSG_PURGE Flushes data from the queue. Similar to using
IO$M_PURGE.
UCX$C_MSG_ Blocks the completion of the operation until
BLOCKALL the buffer is filled completely or until the
connection is closed. Similar to using IO$M_
LOCKBUF.
p6
UCX usage UCX item_list_2
type longword (unsigned)
access read only
mechanism by descriptor
The p6 argument specifies the address for the descriptor of an
output parameter list.
The maximum number of buffers you can specify with the p6
argument is 16.
If you use the p1 and p2 arguments, do not use the p6 argument;
they are mutually exclusive. You either use p1 and p2, or you use
p6 instead. The software first checks to see if the p1 argument
is used. If p1 is not used, the software checks to see if the p6
argument is being used. If neither the p1 nor the p6 arguments
are used, the software returns an error code.
The transfer-length value returned in the I/O status block is
the total number of bytes transferred to the buffer or multiple
buffers.

7 Function_Modifiers

IO$M_INTERRUPT Reads an out-of-band (OOB) message. This has
the same effect as specifying the UCX$C_MSG_
OOB flag.
On receiving a TCP/IP OOB character, TCP/IP
stores the pointer in the received stream with
the character that precedes the OOB character.
A read operation with a user-buffer size
larger than the size of the received stream
up to the OOB character completes and returns
to the user the received stream up to, but not
including, the OOB character.
To determine whether the socket must issue
more read $QIOs before getting all the
characters from the stream preceding an OOB
character, poll the socket. To do this, issue
a $QIO with the $IO_SENSEMODE function, and
the UCX$C_IOCTL subfunction that specifies the
SIOCATMARK command. The SIOCATMARK values are
as follows:
o 0 = Issue more read QIOs to read more data
before reading the OOB.
o 1 = The next read QIO will return the OOB.
Polling a socket is particularly useful
when the OOBINLINE socket option is set.
When the OOBINLINE is set, TCP/IP reads the
OOB character with the characters in the
stream (IO$_READVBLK), but not before reading
the preceding characters. Use this polling
mechanism to determine whether the first
character in the user buffer on the next read
is an OOB character.
On a socket with the OOBINLINE option set
to clear, a received OOB will always be
read by issuing a $QIO with either the
IO$_READVBLK!IO$M_INTERRUPT or IO$_READVBLK
and the UCX$C_MSG_OOB flag set. This can
occur, regardless of how many preceding
characters in the stream have been returned
to the user.
IO$M_LOCKBUF Blocks the completion of the I/O operation
until the user buffer is completely filled
or until the connection is closed. This is
particularly useful when you want to minimize
the number of $QIO commands issued to read
a data stream of a particular size. This
function code is supported only for stream
protocols.
IO$M_NOWAIT Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the
I/O operation to block, the system completes
the I/O operation and returns the error code
SS$_SUSPENDED.
IO$M_PURGE Flushes data from the device socket receive
queue (discards data). If the user buffer
is larger than the amount of data in the
queue, all data in the queue is flushed. This
function works in the same manner for both
datagram and stream sockets.

7 Condition_Values_Returned

SS$_ABORT Programming error, INET management error, or
hardware error. The execution of the I/O was
aborted.
SS$_ACCVIO Programming error. You tried to access an
invalid memory location or buffer.
SS$_BADPARAM Programming error. You used one of the
following methods to specify a $QIO function
with an invalid parameter:
1. You executed an I/O function without
specifying a device socket. You must first
issue a $QIO with the IO$_SETMODE function
and the proper parameters to create the
device socket.
2. You issued an IO$_READVBLK or IO$_WRITEVBLK
function that does not specify a correct
buffer address (p1, p5 or p6 are null).
3. You issued an IO$_READVBLK or IO$_WRITEVBLK
function that specifies an invalid vectored
buffer (p5 or p6 are invalid address
descriptors).
4. The socket has the OOBINLINE option set, or
there is no OOB character in the socket's
OOB queue because the character was either
already read or never received. This
condition happens only if you use the IO$M_
INTERRUPT modifier or set the UCX$C_MSG_OOB
flag with IO$_READVBLK.
SS$_CANCEL Warning code. The I/O operation canceled by
executing a $CANCEL system service routine.
SS$_CONNECFAIL Programming error, INET management error, or
hardware error. The connection was abnormally
terminated.
SS$_DEVINACT INET management error. The driver has not
been started. You must execute a UCX START
COMMUNICATION command before issuing a $QIO
routine.
SS$_DEVNOTMOUNT INET management error. You improperly executed
the INET startup procedure. The driver was
loaded, but the INET_ACP was not activated.
SS$_INSFMEM INET management or programming error. There
is not enough buffer space for allocation.
The INET software needs more buffer space.
You should set a higher quota for the dynamic
buffer space, or shut down and restart your
internet with a larger static buffer space.
SS$_IVBUFLEN Programming error occurred for one of the
following reasons:
1. The size of the buffer for an I/O function
is insufficient.
2. You tried to issue an IO$_READVBLK or IO$_
WRITEVBLK that specifies a correct buffer
address (p1 valid), but does not specify a
buffer length (p2 is null).
SS$_LINKDISCON A virtual circuit (TCP/IP) was closed at the
initiative of the peer.
SS$_NOLINKS Programming error. Read attempt on unconnected
TCP socket.
SS$_SHUT The network is being shut down.
SS$_SUSPENDED The operation is blocked for one of the
following reasons:
1. No messages were received so the receive
operation cannot complete. The socket is
marked as nonblocking.
2. The socket has the OOBINLINE option clear,
and the OOB character has already been
read.
SS$_TIMEOUT This applies to a socket that has KEEPALIVE
set. The connection was idle for longer
than the timeout interval (10 minutes is the
default).
SS$_UNREACHABLE Communication status. The remote host or
network is unreachable.
Example .titleORead_vVBLK Function (MACRO-32 Programming)
;+
; Read using a vectored buffer descriptor
;-
.ident /01/
$inetsymdef ; INET symbols
dev: .ascid /ucx$device:/ ; INET device name
channel: .word 0 ; INET channel
iostatus: .quad 0 ; I/O status block
Ret_adr: .blkb 16 ; Buffer for remote host IP address
Ret_len=.-Ret_adr
leng: .long 0 ; Return length of Remote IP address
loc_adr:.word INET$C_AF_INET ; INET family
.word 5001 ; Port number
; Local host IP address
.byte 128,20,20 ; Network/subnetwork number
.byte 10 ; Host number
.blkb 8
par11: .word INET$C_UDP ; UDP/IP protocol
.word INET_PROTYP$C_DGRAM ; Datagram type of socket
;
; Item_list_3 descriptor for the Remote IP address
;
par12: .long ret_len ; Length
.address ret_adr ; Buffer address
.address leng ; Returned length
;
; Item_list_2 descriptor for the Local IP address
;
par13: .long ret_len ; Length
.address loc_adr ; Address
;
; I/O Buffer
;
buffer_1:
.blkb 512
buflen=.-buffer_1
buffer_2:
.blkb 512
buffer_3:
.blkb 512
buffer_4:
.blkb 512
buf_d: .long len_d
.address buffer_d
buffer_d:
.long buflen
.address buffer_1
.long buflen
.address buffer_2
.long buflen
.address buffer_3
.long buflen
.address buffer_4
len_d=.-buffer_d
.entry start,^m<>
;
; Assign an INET device
;
$assign_s devnam=dev, chan=channel
blbs r0,read
brw exit
;
; Create and bind the device socket to the local host
;
read:
$qioW_s efn=#31,- ; Event flag
chan=channel, - ; Channel
func=#io$_setmode,- ; I/O Function
iosb= iostatus, - ; I/O status block
p1=par11,- ; Socket creation parameters
P3=#Par13 ; Socket Bind parameters
blbc r0,exit
;
; Perform a QIOW read operation
;
$qiow_s efn=#31,- ; Event flag
chan=channel, - ; Channel
func=#io$_readvblk,- ; I/O function
iosb= iostatus,- ; I/O status
p3=#par12,-; Descriptor of the remote Host IP address
P6=#buf_d ; Vectored buffer descriptor
exit:
ret ; Exit
.end start
Example 1-10 Programming) Function - Vectored Buffers (C
#module read_vecio
/*
**++
**
** This example does vectored buffers read
**
**--
*/
/*
** INCLUDE FILES
*/
#include <descrip.h>
#include <ucx$inetdef.h> /* INET symbol definitions */
#include <iodef.h>
/*
**
*/
struct bvec /* Structure definition for vec buf */
{
int length ;
char *b_adrs ;
} ;
struct sockaddr { /* Structure definition for socket adrs */
short inet_family ;
short inet_port ;
char adrs[4] ;
char blkb[8] ;
} ;
main()
{
int status ; /* For return status */
short channel ; /* INET channel */
short sck_parm[2] ; /* Socket creation parameter */
char buf_1[12],buf_2[12],buf_3[12],buf_4[12] ;
struct sockaddr remote_host ; /Socket adrs definition for rhst */
struct sockaddr local_host ; /Socket adrs definition for lhst */
struct itlst lhst_adrs ;
struct itlst rhst_adrs ;
struct bvec buf_vec[5] =
{
{12, &buf_1 },
{12, &buf_2 },
{12, &buf_3 },
{12, &buf_4 },
{0, 0 }
} ;
/* Descriptor for Inet device name */
struct dsc$descriptor dev =
{ 11, DSC$K_CLASS_S, DSC$K_DTYPE_T, "UCX$DEVICE:"} ;
/* Descriptor for vectored buffer */
struct desc$descriptor buf_d =
{ 0, DSC$K_CLASS_S, DSC$K_DTYPE_T, 0} ;
/* Initialize the parameters */
sck_parm[0] = INET$C_UDP ; /* UDP/IP protocol */
sck_parm[1] = INET_PROTYP$C_DGRAM ; /*Datagram type of socket*/
/* Itlst for local IP address */
lhst_adrs.lgth = sizeof(local_host);
lhst_adrs.hst = &local_host ;
rhst_adrs.lgth = sizeof(remote_host) ;
rhst_adrs.hst = &remote_host ;
buf_d.dsc$a_pointer = buf_vec;
buf_d.dsc$w_length = sizeof(bvec) ;
/* Initialize socket address for remote host */
remote_host.inet_family = INET$C_AF_INET ; /* INET family */
remote_host.inet_port = 5002 ; /* Port number */
remote_host.adrs[0] = 128 ; /* Network/subnetwork*/
remote_host.adrs[0] = 20 ; /* number */
remote_host.adrs[0] = 20 ;
remote_host.adrs[0] = 156 ; /* Host number */
remote_host.blkb[0] = 0 ;
remote_host.blkb[1] = 0 ;
remote_host.blkb[2] = 0 ;
remote_host.blkb[3] = 0 ;
remote_host.blkb[4] = 0 ;
remote_host.blkb[5] = 0 ;
remote_host.blkb[6] = 0 ;
remote_host.blkb[7] = 0 ;
/* Initialize socket address for local host */
local_host.inet_family = AF_INET ; /* INET family */
local_host.inet_port = 5002 ; /* Port number */
local_host.adrs[0] = 128 ; /* Network/subnetwork*/
local_host.adrs[0] = 20 ; /* number */
local_host.adrs[0] = 20 ;
local_host.adrs[0] = 156 ; /* Host number */
local_host.blkb[0] = 0 ;
local_host.blkb[1] = 0 ;
local_host.blkb[2] = 0 ;
local_host.blkb[3] = 0 ;
local_host.blkb[4] = 0 ;
local_host.blkb[5] = 0 ;
local_host.blkb[6] = 0 ;
local_host.blkb[7] = 0 ;
/*
** Assign a channel to INET device
*/
status = SYS$ASSIGN( &dev,
&channel,
0,
0) ;
if ((status & 1) == 0) {
printf("Failed to assign channel to INET device \n") ;
return(status) ;
}
/*
** Create and bind the device socket to local host
*/
status = SYS$QIOW( 31, /* Event flag */
channel, /* Channel number */
IO$_SETMODE, /* I/O function */
iosb, /* I/O status block */
0,
0,
&sck_parm, /* P1 Socket creation parameter */
0,
&lhst_adrs, /* P3 Socket bind parameter */
0,0,0) ;
if ((status & 1) == 0) {
printf("Failed to create and bind the devicesocket \n") ;
return(status) ;
/*
** Perform the QIO read operation
*/
status = SYS$QIOW( 31, /* Event flag */
channel, /* Channel number */
IO$_READVBLK,/* I/O function */
iosb, /* I/O status block */
0,
0,
0,
0,
&rhst_adrs, /* P3 Remote host adrs desc */
0,
0,
&buf_d) ; /* P6 Vectored buffer desc */
if ((status & 1) == 0) {
printf("Failed to read from device \n") ;
return(status) ;
}
/*
** Deassign the INET dev channel
*/
SYS$DASSGN (channel);
return(status) ;
}
#module read_ioO$_READVBLK Function - INET device (C Programming)
/*
**++
**
** This example does read from INET device
**
**--
*/
/*
** INCLUDE FILES
*/
#include <descrip.h>
#include <ucx$inetdef.h> /* INET symbol definitions */
#include <iodef.h>
struct sockaddr { /* Structure definition for socket adrs */
short inet_family ;
short inet_port ;
char adrs[4] ;
char blkb[8] ;
} ;
struct itlst {
int lgth ;
struct sockaddr *hst ;
} ;
main()
{
int status ; /* For return status */
short channel /* INET channel */
short sck_parm[2] ; /* Socket creation parameter */
int iosb [2] ; /* I/O status block */
struct sockaddr local_host ; /* Socket adrs definition for lhst */
struct itlst lhst_adrs ;
char buf[128] ;
int buflen = 128 ;
/* Descriptor for Inet device name */
struct dsc$descriptor dev =
{ 3, DSC$K_CLASS_S, DSC$K_DTYPE_T, "UCX$DEVICE:"} ;
/* Initialize the parameters */
sck_parm[0] = INET$C_UDP ; /* UDP/IP protocol */
sck_parm[1] = INET_PROTYP$C_DGRAM ; /* Datagram type of socket */
/* Itlst for local IP address */
lhst_adrs.lgth = sizeof(local_host);
lhst_adrs.hst = &local_host ;
/*
** Assign a channel to INET device
*/
status = SYS$ASSIGN( &dev,
&channel,
0,
0) ;
if ((status & 1) == 0) {
printf("Failed to assign channel to INET device \n") ;
return(status) ;
}
/* Initialize socket address for local host */
local_host.inet_family = INET$C_AF_INET ;/* INET family */
local_host.inet_port = 0 ; /* Port number */
local_host.adrs[0] = 128 ; /* Network/subnetwork*/
local_host.adrs[1] = 45 ; /* number */
local_host.adrs[2] = 45 ;
local_host.adrs[3] = 216 ; /* Host number */
local_host.blkb[0] = 0 ;
local_host.blkb[1] = 0 ;
local_host.blkb[2] = 0 ;
local_host.blkb[3] = 0 ;
local_host.blkb[4] = 0 ;
local_host.blkb[5] = 0 ;
local_host.blkb[6] = 0 ;
local_host.blkb[7] = 0 ;
/*
** Create and bind the device socket to local host
*/
status = SYS$QIOW( 31, /* Event flag */
channel, /* Channel number */
IO$_SETMODE, /* I/O function */
iosb, /* I/O status block */
0,
0,
&sck_parm, /* P1 Socket creation parameter */
0,
&lhst_adrs, /* P3 Socket bind parameter */
0,0,0) ;
if ((status & 1) == 0) {
printf("Failed to create and bind the device socket \n") ;
return(status) ;
}
/*
** Perform the QIO read operation
*/
status = SYS$QIOW( 0, /* Event flag */
channel, /* Channel number */
IO$_READVBLK,/* I/O function */
iosb, /* I/O status block */
0,
0,
buf, /* P1 buffer */
buflen, /* P2 buffer length */
0,0,0,0 ) ;
if ((status & 1) == 0) {
printf("Failed to read from inet device \n") ;
return(status) ;
}
/*
** Deassign the INET dev channel
*/
SYS$DASSGN (channel);
return(status) ;
}

6 IO$_SENSEMODE/IO$_SENSECHAR

The Sense Mode (IO$_SENSEMODE) and Sense Characteristics
(IO$_SENSECHAR) I/O functions return the characteristics of the
internet pseudodevice.
The C Socket equivalent is the getsockopt() function or a call to
the ioctl program.

7 Arguments

p3
UCX usage UCX item_list_3
type longword (unsigned)
access read only
mechanism by descriptor
The p3 argument contains the address of a UCX item_list_3
descriptor that specifies the buffer where the software returns
the local socket name. The buffer contains the local socket
address (family name, port number, and internet address). The
parameter name for the descriptor is UCX$_C_SOCK_NAME, which is
defined in the UCX$INET_DEF symbol definition file.
The C Socket equivalent for this function is getsockname().
p4
UCX usage UCX item_list_3
type longword (unsigned)
access read only
mechanism by descriptor
The p4 argument contains the address of a UCX item_list_3
descriptor that specifies the buffer from which to return the
remote peer socket name. The buffer contains the remote socket
address (family name, port number, and internet address).
The C Socket equivalent for this function is getpeername().
p6
UCX usage UCX item_list_2 or item_list_3
type longword (unsigned)
access read only
mechanism by descriptor
The p6 argument specifies the address of a descriptor that lists
UCX item_list_2 or item_list_3 descriptors. The following are the
parameter types for the UCX item_list to which the p6 argument
points:
o UCX$C_SOCKOPT (communication socket option parameters)
o UCX$C_TCPOPT (TCP options)
o UCX$C_IPOPT (IP options)
o UCX$C_IOCTL (I/O control parameters)
The UCX item_list descriptor points to an integer (with the
length set to the size of the integer). The integer contains
zero to clear an option and nonzero to set an option.
The UCX$C_SOCKOPT parameter specifies the communication socket
options. The descriptor that defines the list of socket options
points to a list of item_list_3 descriptors, which contains one
descriptor for each option. The p6 Socket Options describes the
options for the UCX$C_SOCKOPT parameter type.
Table 1-9 The p6 Socket Options
Socket Option Description
UCX$C_BROADCAST Permits sending broadcast messages. A
broadcast internet address is accepted
when the socket has this option set.
Supported only with datagram.
UCX$C_DONTROUTE Uses interface addresses only. Optional
only for datagram or raw IP.
UCX$C_ERROR Obtains the socket error status and clears
the error on the socket.
UCX$C_KEEPALIVE Detects broken idle connections and keeps
them alive for the specified maximum idle
time. Broken idle connections occur when
the remote end point has dropped the
connection. This is optional for stream
socket and ignored by datagram and raw IP.
UCX$C_LINGER Lingers on close operation if data is
present (that is, waits for all messages
to be sent). Optional for stream socket.
UCX$C_OOBINLINE Leaves the received OOB data in line.
UCX$C_RCVBUF Gets the socket receive quota.
UCX$C_REUSEADDR Allows reuse of the local socket address.
The local socket address is the 16-byte
structure that contains address family,
port, and host IP address.
The UCX$C_REUSEADDR option enables reuse
of the local port number portion. It
works only with connection-oriented
protocols (in particular, TCP/IP), where a
connection is characterized for its entire
life by the local address, local port,
remote host, and remote port.
The option can be used for a client that
always binds to a known or well-defined
port number. It allows several instances
of the client image running on one host
to connect to the same server on different
hosts.
UCX$C_NO_RCV_ Disables checksum calculation for received
CHECKSUM data.
UCX$C_NO_SND_ Disables checksum calculation for
CHECKSUM transmitted data.
UCX$C_NO_CHECKSUM Disables checksum calculation altogether.
UCX$C_SNDBUF Gets the socket send quota.
UCX$C_TYPE Obtains the socket type.
UCX$C_USELOOPBACK TCP/IP socket option. Shortens the data
transfer time when the transfer is local
to the host. This improves the performance
of the local TCP/IP transfer process and
results in a lower load on the CPU when
applications using local transfer are
active.
Unsupported socket options are ignored.
TCP/IP Options describes the TCP/IP options for the UCX$C_TCPOPT
parameter type.
IP Options describes the options for the UCX$C_IPOPT parameter
type.
Table 1-10 TCP/IP Options
TCP/IP Option Description
UCX$C_TCP_PROBE_ TCP/IP protocol option. Specifies the time
IDLE interval for the KEEPALIVE probe, as well as
for the connection establishing the timeout.
UCX$C_TCP_DROP_ TCP/IP protocol option. Specifies the time
IDLE interval after which the connection will be
dropped if the remote host does not respond.
Table 1-11 IP Options
IP Option Description
UCX$C_IP_TTL Time to live (TTL) for a datagram.
UCX$C_IP_TOS Type of service (1-byte value).
The UCX$C_IOCTL parameter specifies the I/O control parameters.
The parameters are specified through a UCX item_list_2 descriptor
that points to a list of longword entries. The first longword
entry contains the IOCTL command. The second longword contains
the address of a buffer structure descriptor. The IOCTL commands
are listed in IOCTL Commands.
Table 1-12 IOCTL Commands
Parameter
StructurIOCTL Command Description
Integer SIOCATMARK Determines if you are at the OOB
character mark.
Integer FIONREAD Obtains the number of bytes that are
queued in the socket receive queue.
You can use one $QIO system service call with the IO$_SENSEMODE
modifier for multiple operations. For example, a $QIO system
service could specify a list of socket options or a list of IOCTL
commands, combined with a local socket name or peer socket name.
When the software detects an error, the iosb argument contains
the error and parameter address or value that was at fault.
The UCX software sequentially processes parameters in this order:
p3, p4, p6.
You can specify multiple lists of socket options or IOCTL
commands. If you duplicate a parameter or IOCTL command in one
or more lists, the value returned is the last option or IOCTL
command read.

7 Condition_Values_Returned

SS$_ACCVIO Programming error. You attempted to access an
invalid memory location or buffer.
SS$_BADPARAM Programming error. You specified a $QIO
function with an invalid parameter that
resulted from one of the following:
1. You attempted to execute the IO$_SENSEMODE
function without specifying a device
socket. Instead, create a device socket
by issuing a $QIO with the IO$_SETMODE
function and the proper parameters.
2. You made an error while specifying a socket
option.
SS$_DEVINACT INET management error. The driver was not
started. Execute a UCX START COMMUNICATION
command before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. You improperly executed
the INET startup procedure. The driver was
loaded, but the INET_ACP was not activated.
Execute the INET startup procedure again.
SS$_ILLCNTRFUNC Programming error. The operation is
unsupported for one of the following reasons:
1. You issued an invalid IO$_SENSEMODE
function for the interface. The interface
does not have an IOCTL routine.
2. You issued a IO$_SENSEMODE function that
requires a socket, but the device did not
have one. Create a socket and then issue
the function.
3. An unsupported operation was performed on
at least one of the following protocols:
raw IP, datagram, or stream sockets.
SS$_INSFMEM INET management or programming error. Do one
of the following:
1. Set a higher quota for the dynamic buffer
space.
2. Shut down the internet and restart with
larger static buffer space.
SS$_IVBUFLEN Programming error. You set a socket option
buffer with an invalid size.
SS$_NOSUCHDEV Programming error or INET management error. An
INET address is not in the Address Resolution
Protocol (ARP) table. An attempt to show or
delete an ARP table entry failed.
SS$_NOLINKS Programming error.
1. Stream socket - You did not connect the
socket.
2. Datagram or raw IP - You did not specify
an INET port and address with an IO$_ACCESS
system service call.
3. You used the IO$_SENSEMODE system service
call to request the name of a peer socket
without first issuing calls to connect the
socket or establish the peer socket.
SS$_NOOPER Programming error. You attempted to get ARP
information without having OPER privileges.
SS$_PROTOCOL Programming error. You attempted to set socket
options on a closed socket.
SS$_SHUT The network is being shut down.
SS$_UNREACHABLE Programming error. Network is unreachable or
the network address is invalid.
1. You attempted to create a permanent ARP
table with the network part of the INET
address being zero.
2. You attempted to create a route entry with
the network part of the INET address being
zero.

6 IO$_SETMODE/IO$_SETCHAR

The Set Mode and Set Characteristics I/O functions perform mode,
operational, and program/driver interface operations with the
internet device socket. These two functions work in exactly the
same manner. They take the following form:
o IO$_SETMODE
o IO$_SETCHAR
The protocol you use determines when you can change the mode or
characteristics:
o Connectionless protocols (datagram or raw IP ) - Can be
changed any time.
o Connection-oriented protocols (TCP/IP) - Can only be changed
when the device socket is closed, such as before a connection
is established (opened) or after the connection is closed.
While a connection is open (active), only parameters that do
not affect the connection characteristics may be changed.
The routine processes parameters sequentially. If it finds an
error, the routine aborts. Any parameters correctly specified
before the routine encounters an error are properly processed
before the routine aborts.
The equivalent C Socket functions are socket(), bind(),
listen(), setsockopt() or a call to the ioctl program.

7 Arguments

p1
UCX usage socket definition (socket type, protocol, and INET
domain)
type longword (unsigned)
access read only
mechanism by reference
The p1 argument specifies the address of a buffer containing
the socket characteristics. The C Socket equivalent for this is
socket().
The socket characteristics buffer is one longword. The first two
bytes contain the protocol, the third byte contains the socket
type (protocol type), and the fourth byte contains the domain
name (the internet, by default).
Both the protocol and the socket type are contained in one
longword value.
Valid Protocols for IO$_SETMODE and IO$_SETCHAR lists the valid
protocols.
Table 1-13 Valid Protocols for IO$_SETMODE and IO$_SETCHAR
Protocol Description
UCX$C_TCP TCP/IP
UCX$C_UDP UDP/IP
UCX$C_RAW_IP IP
Valid Socket Types for IO$_SETMODE and IO$_SETCHAR lists the
valid socket types.
Table 1-14 Valid Socket Types for IO$_SETMODE and IO$_SETCHAR
Socket Type Description
UCX$C_STREAM The communications protocol is a bidirectional,
reliable, sequenced, and unduplicated data flow
without record boundaries.
UCX$C_DGRAM The communications protocol is a bidirectional
data flow with record boundaries. There are
no provisions for sequence, reliability, or
duplication of messages.
UCX$C_RAW Allows access to the lower layer (IP layer) of
the internet communication protocol. It is used
to develop new communication protocols that are
to be layered on the IP layer.
If the image that creates the socket runs in a process that has
a privileged UIC or has SYSPRV, BYPASS, or OPER privileges, the
socket is marked privileged.
NOTE
The p2 argument is not used with the IO$_SETMODE
routine. It is used when you specify either the
IO$M_OUTBAND, IO$M_READATTN, or IO$M_WRTATTN
function modifiers. See the descriptions for
IO$_SETMODE|IO$M_OUTBAND, IO$_SETMODE|IO$M_READATTN, and
IO$_SETMODE|IO$M_WRTATTN for details.
p3
UCX usage local socket name
type longword (unsigned)
access read only
mechanism by descriptor
The p3 argument specifies the address of a UCX item_list_2
descriptor of a buffer that specifies the local socket name
(port and local host internet address). The parameter name
for the descriptor is UCX$C_SOCK_NAME, which is defined in the
UCX$INETDEF symbol definition file.
The C Socket equivalent is bind().
p4
UCX usage number of connections to accept
type byte (unsigned)
access read only
mechanism by value
The p4 argument specifies the number of connections that can be
established simultaneously and held by the listener socket before
the program accepts the connections on the socket associated with
the UCX device (TCP/IP only). If more connections are received
than have been specified, the the additional connections are
rejected.
The C Socket equivalent is listen().
p5
UCX usage UCX item_list_2
type longword (unsigned)
access read only
mechanism by descriptor
The p5 argument specifies the address of a descriptor that lists
item_list_2 descriptors. The C Socket equivalent is setsockopt().
Each UCX item_list_2 descriptor describes a group of parameters
of a specific type.
The following are the parameter types for the UCX descriptor to
which the p5 points:
o UCX$C_SOCKOPT (communication socket option parameter)
o UCX$C_TCPOPT (TCP options)
o UCX$C_IPOPT (IP options)
o UCX$C_IOCTL (I/O control parameter)
You can use one $QIO system call to set up several socket options
at once. The UCX item_list_2 descriptor points to an integer
(with the length set to the size of the integer). The integer
contains zero to clear the option and nonzero to set the option.
The UCX$C_SOCKOPT parameter specifies the communication socket
options. Communications Socket Options describes the socket
options you use with the UCX$C_SOCKOPT parameter type.
Unsupported socket options are ignored.
TCP Options describes the socket options you use with the UCX$C_
TCPOPT parameter type.
IP Options describes the options you use with the UCX$C_IPOPT
parameter type.
Table 1-15 Communications Socket Options
Socket Option Description
UCX$C_KEEPALIVE Detects broken idle connections
(connections in which the remote end point
has dropped the connection) and keeps the
connection alive for the specified maximum
idle time (optional for TCP/IP).
UCX$C_DONTROUTE Uses interface addresses only.
UCX$C_BROADCAST Permits sending of broadcast messages. A
broadcast internet address is the system
number defined by using the connection
control program. This option requires
a system UIC, SYSPRV, BYPASS, or OPER
privilege in order to be set. Optional for
a connectionless datagram.
UCX$C_LINGER Lingers on Close operation if data is
present; that is, waits for all messages
to be sent (optional for TCP/IP).
UCX$C_OOBINLINE Leaves the received OOB data in line.
UCX$C_RCVBUF Sets the socket receive quota. This option
requires a system UIC, SYSPRV, BYPASS, or
OPER privilege to be set.
UCX$C_REUSEADDR Allows reuse of the local socket address.
The local socket address is the 16-byte
structure that contains the address
family, port, and host IP address.
The UCX$C_REUSEADDR option enables reuse
of the local port number portion. It
works only with connection-oriented
protocols (in particular, TCP/IP), where a
connection is characterized for its entire
life by the local address, local port,
remote host, and remote port.
The option can be used for a client that
always binds to a known or well-defined
port number. It allows several instances
of the client image running on one host
to connect to the same server on different
hosts.
UCX$C_SNDBUF Sets the socket send quota. This option
requires a system UIC, SYSPRV, BYPASS, or
OPER privilege to be set.
UCX$C_NO_RCV_CHECKSUM Disables checksum calculation for received
data.
UCX$C_NO_SND_CHECKSUM Disables checksum calculation for
transmitted data.
UCX$C_NO_CHECKSUM Disables checksum calculation altogether.
UCX$C_SHARE Allows multiple processes to share the
socket.
UCX$C_FULL_DUPLEX_ When set before a close operation,
CLOSE both receive and transmit sides of the
communications are closed.
Table 1-16 TCP Options
TCP Option Description
UCX$C_USELOOPBACK TCP/IP socket option. Shortcuts the data
transfer when the transfer is local to
the host. This improves the performance
of the local TCP/IP transfer process and
results in a lower load on the CPU when
applications using local transfer are
active.
UCX$C_TCP_NODELAY TCP/IP option. Specifies that the send
operation will not be delayed to coalesce
packets.
UCX$C_TCP_PROBE_IDLE TCP/IP option. Specifies the time interval
for the KEEPALIVE probe, as well as for
the connection establishing the timeout.
UCX$C_TCP_DROP_IDLE TCP/IP option. Specifies the time interval
after which the connection is dropped.
Table 1-17 IP Options
IP Option Description
UCX$C_IP_TTL Time to live (TTL) for a datagram.
UCX$C_IP_TOS Type of service (1-byte value)
The UCX$C_IOCTL parameter specifies the I/O control parameters.
The list of the IOCTL parameters contains two entries of
longwords: the IOCTL command (first longword) and the address
of the required buffer structure (second longword).
To set UCX$C_IOCTL, you need a system UIC, SYSPRV, BYPASS, or
OPER privileges.
You can specify multiple IO$_SETMODE parameters with one $QIO
system service call. For example, one $QIO system service
call could specify a list of socket options or a list of IOCTL
commands, combined with a local socket name.
When an error is detected, the iosb argument specifies the error
and parameter address or value that was at fault.
The UCX software processes parameter values for arguments in the
following order: p1, p3, p4, and p5.
You can specify multiple lists of socket options or IOCTL
commands. If a parameter, parameter list, or IOCTL command is
duplicated by using the same return address, then the value
returned is the last option or IOCTL command.

7 Condition_Values_Returned

SS$_ABORT Programming error, INET management error,
or hardware error. The route entry already
exists. An attempt to add a route entry
with IO$_SETMODE (IOCTL) system service call
failed.
SS$_ACCVIO Programming error. You tried to access an
invalid memory location or buffer.
SS$_BADPARAM Programming error. You specified a $QIO
function with an invalid parameter that was
a result of one of the following:
1. You tried to execute IO$_SETMODE function
(all subfunctions, except socket creation)
without specifying a device socket.
Instead, create a device socket by issuing
a $QIO with the IO$_SETMODE function and
the proper parameters.
2. You made an error specifying a socket
option.
SS$_DEVACTIVE INET management error. You attempted to change
the static INET parameters. If new parameters
are needed, shut down the internet, reset
the static parameters, and issue the START
COMMUNICATION command.
SS$_DEVINACT INET management error. The driver is not
started. Issue a UCX START COMMUNICATION
command before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. You improperly executed
the INET startup procedure. The driver was
loaded, but the INET_ACP was not activated.
Execute the INET startup procedure again.
SS$_DUPLNAM Programming error. The port being bound
is already in use. You attempted to bind
the socket to an address and port and the
operation failed.
SS$_EXQUOTA Programming or INET management error occurred
for one of the following reasons:
1. You tried to create a new socket with the
IO$_SETMODE function, but the maximum
number of sockets was exceeded. Increase
the maximum number of sockets (INET
parameter).
2. The number of sockets specified with the
IO$_SETMODE (listen) exceeds the maximum
number of sockets. Increase the maximum
number of sockets (INET parameter) or
reduce the listen parameter (the number
of sockets the listener socket can create).
SS$_FILALRACC Programming error. The INET address is already
in use. You attempted to bind the socket to an
address and port and the operation failed.
SS$_INSFMEM Programming or system management error. There
are not enough resources to allocate a new
socket.
SS$_ILLCNTRFUNC Programming error. The operation is not
supported for one of the following reasons:
1. You used an invalid IO$_SETMODE function
for the interface that does not have an
IOCTL routine.
2. You tried to perform an IO$_SETMODE
function that required a socket, but the
device did not have one. Create a socket
before issuing the function.
SS$_IVADDR Programming error. The INET address you
specified using the IO$_SETMODE function was
not placed into the system. This resulted
in an invalid port number or INET address
combination. The INET address was invalid for
one of the following reasons:
1. Port zero and INET address zero are not
allowed or port zero is not allowed when
using an IO$_ACCESS or IO$_WRITEVBLK
function.
2. You attempted to exceed the limit of
allowable permanent entries in the ARP
table.
3. You attempted to bind a raw IP socket when
there are no interfaces defined in the
system.
4. You attempted to bind a raw IP socket to a
null INET address.
SS$_IVBUFLEN Programming error. The socket option buffer
has an invalid size.
SS$_NOLICENSE Programming or system management error. A
DIGITAL TCP/IP Services for OpenVMS license is
not present.
SS$_NOOPER Programming or INET management error. You
attempted to execute an I/O function that
needs the OPER privilege.
SS$_NOPRIV Programming or INET management error. There
are not enough privileges for the attempted
operation for one of the following reasons:
1. You attempted to broadcast an IP datagram
on a process without system UIC, SYSPRV,
BYPASS, or OPER privileges.
2. You attempted to use a reserved port number
lower than 1024.
3. You attempted to access a process that
requires system UIC, SYSPRV, or BYPASS
privileges.
4. You attempted to use raw IP on a privileged
socket that requires the SYSPRV or BYPASS
privileges.
SS$_NOSUCHDEV Programming error or INET management error.
Your attempt to show or delete an ARP table
entry failed because the INET address is not
found.
SS$_NOSUCHNODE Programming error or INET management error.
Your attempt to delete a route from the
routing table failed because the entry was
not found.
SS$_PROTOCOL Programming error. You specified a protocol or
address family that caused an error for one of
the following reasons:
1. You specified an invalid protocol type at
socket creation.
2. You specified an unsupported protocol.
3. You specified a protocol type that was not
found in the internal tables.
4. The address family is unsupported for one
of the following reasons:
o You specified an unsupported address
family with the IO$_SETMODE subfunction.
Instead, specify the UCX$C_AF_INET or
UCX$C_UNSPEC address family.
o You specified an unsupported address
family for a remote INET address
with the IO$_ACCESS or IO$_WRITEVBLK
function. Instead, specify the UCX$C_AF_
INET address family.
o You specified an unsupported address
family for the local INET address with
the IO$_SETMODE function. Instead,
specify the UCX$C_AF_INET address
family.
o You specified an unsupported address
family for the INET address of the
routing module. Instead, specify the
UCX$C_AF_INET address family.
SS$_SHUT The network is being shut down.

6 IO$_SETMODE|IO$M_OUTBAND

The IO$_SETMODE|IO$M_OUTBAND function/modifier combination
requests that the asynchronous system trap (AST) for an out-
of-band (OOB) character be delivered to the requesting process.
This is to be done only when an OOB character is received on the
socket and there is no waiting read request. The socket is a TCP
/IP (stream) socket.

7 Arguments

p1
UCX usage ast_procedure
type procedure entry mask
access call without stack unwinding
mechanism by reference
To enable the AST, the p1 argument is the address of the OOB
character AST routine. To disable the AST, p1 equals 0.
p2
UCX usage user_arg
type longword (unsigned)
access read only
mechanism by value
AST parameter to be delivered to the AST routine specified by the
p1 argument.
p3
UCX usage acmode
type longword (unsigned)
access read only
mechanism by value
Access mode to deliver the AST.

7 Description

The Enable OOB character AST function allows an Attention AST
to be delivered to the requesting process only once. After the
AST occurs, the function must explicitly reenable AST delivery
before a new AST can be delivered. This function is subject to
AST quotas.

7 Condition_Values_Returned

SS$_ABORT Programming, INET management, or hardware
error. The route entry already exists. You
attempted to add a route entry with the
IO$_SETMODE function and the operation failed.
SS$_ACCVIO Programming error. You attempted to access an
invalid memory location or buffer.
SS$_BADPARAM Programming error. You specified a $QIO
function with an invalid parameter that
occurred for one of the following reasons:
1. You attempted to execute an IO$_SETMODE
function (all subfunctions, except socket
creation) without specifying a device
socket. Instead, create a device socket
by issuing a $QIO with the IO$_SETMODE
function and the proper parameters.
2. You made an error specifying a socket
option.
SS$_DEVACTIVE INET management error. You attempted to change
the static INET parameters. If new parameters
are needed, shut down the internet, reset
the static parameters, and issue the START
COMMUNICATION command.
SS$_DEVINACT INET management error. The driver was not
started. Issue a UCX START COMMUNICATION
command before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. You improperly executed
the INET startup procedure. The driver was
loaded, but the INET_ACP was not activated.
Execute the INET startup procedure again.
SS$_DUPLNAM Programming error. You are attempting to bind
a port that is already in use. An attempt to
bind the socket to an address and port failed.
SS$_EXQUOTA Programming or INET management error that
occurred because of one of the following
reasons:
1. You attempted to create a new socket with
the IO$_SETMODE function but it failed
because the maximum number of sockets was
exceeded. Increase the maximum number of
sockets (INET parameter).
2. The number of sockets specified with the
IO$_SETMODE (listen) exceeds the maximum
number of sockets. Increase the maximum
number of sockets (INET parameter) or
reduce the listen parameter (the number
of sockets that the listener socket can
create).
SS$_FILALRACC Programming error. INET address is already
in use. An attempt to bind the socket to an
address and port failed.
SS$_INSFMEM Programming or system management error: Not
enough resources to allocate new socket.
SS$_ILLCNTRFUNC Programming error. Operation is not supported
because of one of the following reasons:
1. You used an invalid IO$_SETMODE (IOCTL)
function for the interface. The interface
does not have an IOCTL routine.
2. You attempted to perform an IO$_SETMODE
(IOCTL) function that required a socket,
but the device did not have one. Create a
socket and issue the IOCTL function.
SS$_IVADDR Programming error. The specified INET address
is not in the system, and an invalid port
number or an invalid INET address combination
was specified with an IO$_SETMODE function (a
bind) for one of the following reasons:
1. An attempt to bind the address failed
because the INET address is not in the
system, port zero and INET address zero are
not allowed, or port zero is not allowed
when using an IO$_ACCESS or IO$_WRITEVBLK
function.
2. An attempt to make a permanent entry in an
ARP table that was full failed.
3. An attempt was made to bind an IP socket
(raw IP) when there are no interfaces
defined in the system.
4. An attempt was made to bind an IP socket
(raw IP) to a null INET address.
SS$_IVBUFLEN Programming error. The socket option buffer
has an invalid size.
SS$_NOLICENSE Programming or system management error. UCX
license not present.
SS$_NOOPER Programming or INET management error. An
attempt was made to execute an I/O function
that needs the OPER privilege.
SS$_NOPRIV Programming or INET management error. Not
enough privileges for the attempted operation
for one of the following reasons:
1. Broadcasting an IP datagram was denied
because the process does not have a system
UIC, SYSPRV, BYPASS, or OPER privileges.
2. An attempt was made to use a reserved port
number lower than 1024.
3. An operation accesses only processes
that have a system UIC, SYSPRV, or BYPASS
privilege.
4. Raw IP protocol can be used only on
privileged sockets. The process must have a
SYSPRV or BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error.
An INET address is not in the ARP table. An
attempt to show or delete an ARP table entry
failed.
SS$_NOSUCHNODE Programming or INET management error. An
attempt to delete a route from the routing
table failed because a route entry was not
found.
SS$_PROTOCOL Programming error due to one of the following
reasons:
1. The protocol type specified at socket
creation is not valid.
2. The protocol is not supported.
3. The protocol type specified is not found
in the internal tables and therefore is an
invalid type.
4. The address family is not supported for one
of the following reasons:
o The address family specified with an
IO$_SETMODE function (IOCTL subfunction)
is not supported. The address family
should be the UCX$C_AF_INET or UCX$C_
UNSPEC address family.
o The address family of the remote INET
address specified with an IO$_ACCESS or
IO$_WRITEVBLK function is not supported
(UDP/IP or TCP/IP). The address family
should be the UCX$C_AF_INET address
family.
o The address family of the local INET
address specified with an IO$_SETMODE
(bind) function is not supported. The
address family should be the UCX$C_AF_
INET address family.
o The address family of the INET address
specified in a request to the routing
module is not supported. The address
family should be the UCX$C_AF_INET
address family.
SS$_SHUT The network is being shut down.

6 IO$_SETMODE|IO$M_READATTN

The IO$_SETMODE|IO$M_READATTN function/modifier combination
requests that an Attention AST be delivered to the requesting
process when a data packet is received on the socket and there is
no waiting read request.

7 Arguments

p1
UCX usage procedure entry mask
type call without stack unwinding
access by reference
mechanism 0
To enable the AST, the p1 argument is the address of the Read
Attention AST routine. To disable the AST, set p1 to 0.
p2
UCX usage user_arg
type longword (unsigned)
access read only
mechanism by value
AST parameter to be delivered to the AST routine.
p3
UCX usage acmode
type longword (unsigned)
access read only
mechanism by value
Access mode to deliver the AST.

7 Description

The Enable Read Attention AST function enables an Attention AST
to be delivered to the requesting process once only. After the
AST occurs, the function must explicitly re-enable AST delivery
before the AST can occur again. The function is subject to AST
quotas.
Consider the following when using IO$M_READATTN:
o There is a one-to-one correspondence between the number of
times you enable an Attention AST and the number of times the
AST is delivered. For example, for each enabled AST, one AST
is delivered. If you enable an Attention AST several times,
several ASTs are delivered for one event when an event occurs.
o If an out-of-band (OOB) Attention AST is enabled, the OOB AST
is delivered, regardless of the following:
- A Read Attention AST enabled
- The UCX$C_OOBINLINE socket option
- A READ $QIO waiting for completion on the socket
If the UCX$C_OOBINLINE option is set, then a waiting READ $QIO is
completed and the OOB character is returned in the data stream.
o If both an OOB AST and a Read Attention AST are enabled, only
the OOB AST is delivered when an OOB character is received.
o If a Read Attention AST is enabled and the UCX$C_OOBINLINE
socket option is set, a waiting READ $QIO completes and the
OOB character is returned in the data stream.
o If a Read Attention AST is enabled and the UCX$C_OOBINLINE
socket option is not set (clear), the Read Attention AST
is delivered when an OOB character is received, regardless
of whether a READ $QIO is waiting for completion. In this
case, the OOB character is not returned in the data stream.
Therefore, if the OOB character is the only character
received, the READ $QIO does not complete.

7 Condition_Values_Returned

SS$_ABORT Programming, INET management, or hardware
error. The route entry already exists, so
your attempt to add a route entry using the
IO$_SETMODE function failed.
SS$_ACCVIO Programming error. You attempted to access an
invalid memory location or buffer.
SS$_BADPARAM Programming error. The parameter you specified
for a $QIO function was invalid for one of the
following reasons:
1. You attempted to execute the IO$_SETMODE
subfunctions without specifying a device
socket. Instead, create a device socket
by issuing a $QIO with the IO$_SETMODE
function and the proper parameters.
2. You made an error specifying a socket
option.
SS$_DEVACTIVE INET management error. You attempted to change
the static INET parameters. If you need new
parameters, shut down the internet, reset
the static parameters, and issue the START
COMMUNICATION command.
SS$_DEVINACT INET management error. The driver was not
started. Issue a UCX START COMMUNICATION
command before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. You improperly executed
the startup procedure. The driver was loaded,
but the INET_ACP was not activated. Execute
the INET startup procedure again.
SS$_DUPLNAM Programming error. You attempted to bind a
port already in use so the operation to bind
the socket to the address and port failed.
SS$_EXQUOTA Programming or INET management error. The
quota for the valid number of sockets caused
an error for one of the following reasons:
1. You attempted to exceed the maximum number
of sockets by creating new socket with
the IO$_SETMODE function. Increase the
maximum number of allowable sockets (INET
parameter) before creating more sockets.
2. You specified a number of sockets with
the IO$_SETMODE function that exceeds
the maximum number of sockets allowed.
Increase the maximum number of sockets
(INET parameter) or reduce the number of
sockets that the listener socket can create
(listen parameter).
SS$_FILALRACC Programming error. You attempted to bind the
socket to an address that is already in use
and the operation failed.
SS$_INSFMEM Programming or system management error. Your
system does not have enough resources to
allocate new socket.
SS$_ILLCNTRFUNC Programming error. Operation is not supported.
1. Invalid IO$_SETMODE (IOCTL) function was
used for the interface. The interface does
not have an IOCTL routine.
2. An attempt was made to perform an IO$_
SETMODE (IOCTL) function that required
a socket, but the device did not have
one. Create a socket and issue the IOCTL
function.
SS$_IVADDR Programming error. The specified INET address
is not in the system, and an invalid port
number or an invalid INET address combination
was specified with an IO$_SETMODE function (a
bind).
1. An attempt to bind the address failed
because the INET address is not in the
system, port zero and INET address zero are
not allowed, or port zero is not allowed
when using an IO$_ACCESS or IO$_WRITEVBLK
function.
2. An attempt to make a permanent entry in the
ARP table failed because of lack of space.
Too many permanent entries.
3. An attempt was made to bind an IP socket
(raw IP) when there are no interfaces
defined in the system.
4. An attempt was made to bind an IP socket
(raw IP) to a null INET address.
SS$_IVBUFLEN Programming error. The socket option buffer
has an invalid size.
SS$_NOLICENSE Programming or system management error. UCX
license not present.
SS$_NOOPER Programming or INET management error. An
attempt was made to execute an I/O function
that needs the OPER privilege.
SS$_NOPRIV Programming or INET management error. Not
enough privileges for the attempted operation.
1. Broadcasting an IP datagram was denied
because the process does not have a system
UIC, SYSPRV, BYPASS, or OPER privileges.
2. An attempt was made to use a reserved port
number lower than 1024.
3. An operation accesses only processes
that have a system UIC, SYSPRV, or BYPASS
privilege.
4. Raw IP protocol can be used only on
privileged sockets. The process must have a
SYSPRV or BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error.
An INET address is not in the ARP table. An
attempt to show or delete an ARP table entry
failed.
SS$_NOSUCHNODE Programming error or INET management error.
An attempt to delete a route from the routing
table failed because a route entry was not
found.
SS$_PROTOCOL Programming error.
1. The protocol type specified at socket
creation is not valid.
2. The protocol is not supported.
3. The protocol type specified is not found in
the internal tables. It is an invalid type.
4. The address family is not supported:
o The address family specified with an
IO$_SETMODE function (IOCTL subfunction)
is not supported. The address family
should be the UCX$C_AF_INET or UCX$C_
UNSPEC address family.
o The address family of the remote INET
address specified with an IO$_ACCESS or
IO$_WRITEVBLK function is not supported
(UDP/IP or TCP/IP). The address family
should be the UCX$C_AF_INET address
family.
o The address family of the local INET
address specified with an IO$_SETMODE
(bind) function is not supported. The
address family should be the UCX$C_AF_
INET address family.
o The address family of the INET address
that is specified in a request to the
routing module is not supported. The
address family should be the UCX$C_AF_
INET address family.
SS$_SHUT The network is being shut down.

6 IO$_SETMODE|IO$M_WRTATTN

The IO$_SETMODE|IO$M_WRTATTN function/modifier combination (IO$M_
WRTATTN is Enable Write Attention AST (asynchronous system trap))
requests that an Attention AST be delivered to the requesting
process when a data packet can be queued to the socket. For TCP
sockets, this occurs when the TCP transmit queue is available.

7 Arguments

p1
UCX usage procedure entry mask
type call without stack unwinding
access by reference
mechanism 0
To enable the AST, the p1 argument is the address of the Write
Attention AST routine. To disable the AST, p1 is set to 0.
p2
UCX usage user_arg
type longword (unsigned)
access read only
mechanism by value
AST parameter to be delivered to the AST routine.
p3
UCX usage acmode
type longword (unsigned)
access read only
mechanism by value
Access mode to deliver the AST.

7 Description

The Enable Write Attention AST function enables an Attention AST
to be delivered to the requesting process only once. After the
AST occurs, the function must explicitly re-enable AST delivery
before the AST can occur again. The function is subject to AST
quotas.
There is a one-to-one correspondence between the number of
times you enable an Attention AST and the number of times the
AST is delivered. For example, for each enable AST, one AST is
delivered. If you enable an Attention AST several times, several
ASTs are delivered for one event when the event occurs.
You can use the UCX command SHOW DEVICE_SOCKET to display
information on the socket's characteristics, options, and state.

7 Condition_Values_Returned

SS$_ABORT Programming error, INET management error,
or hardware error. The route you specified
with the IO$_SETMODE function already exists.
Therefore, the operation failed.
SS$_ACCVIO Programming error. You attempted to access an
invalid memory location or buffer.
SS$_BADPARAM Programming error. The parameter you specified
for the $QIO I/O function was invalid for one
of the following reasons:
1. You attempted to execute the IO$_SETMODE
functions without specifying a device
socket. Instead, create a device socket
by issuing a $QIO with the IO$_SETMODE
function and the proper parameters.
2. You made an error when specifying a socket
option.
SS$_DEVACTIVE INET management error. You attempted to change
the static INET parameters. If you need new
parameters, shut down the internet, reset
the static parameters, and issue the START
COMMUNICATION command.
SS$_DEVINACT INET management error. The driver is not
started. Issue a UCX START COMMUNICATION
command before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. The INET startup
procedure was improperly executed. The
driver was loaded, but the INET_ACP was not
activated. Execute the INET startup procedure
again.
SS$_DUPLNAM Programming error. Port that is being bound is
already in use. An attempt to bind the socket
to an address and port failed.
SS$_EXQUOTA Programming or INET management error.
1. You attempted to create a new socket with
the IO$_SETMODE function and it failed
because the maximum number of sockets was
exceeded. Increase the maximum number of
sockets (INET parameter) and then create a
new socket.
2. The number of sockets you specified with
the IO$_SETMODE function exceeds the
allowable maximum number of sockets.
Increase the maximum number of sockets
(INET parameter) or reduce the number of
sockets that the listener socket can create
(listen parameter).
SS$_FILALRACC Programming error. Because the INET address
is already in use, your attempt to bind the
socket to an address and port failed.
SS$_INSFMEM Programming or system management error. There
are not enough resources to allocate new
socket.
SS$_ILLCNTRFUNC Programming error. You specified an operation
that is unsupported for one of the following
reasons:
1. You used an invalid IO$_SETMODE function
for the interface. The interface does not
have an IOCTL routine.
2. You attempted to execute an IO$_SETMODE
function that required a socket, but the
device did not have one. Instead, create a
socket and issue the function.
SS$_IVADDR Programming error. You specified an invalid
port number and INET address combination with
the IO$_SETMODE bind function. This caused
the operation to fail for one of the following
reasons:
1. You specified an illegal combination of
port zero and INET address zero.
2. You specified port zero when using an IO$_
ACCESS or IO$_WRITEVBLK function.
3. When you attempted to make a permanent
entry in the ARP table, the operation
failed because of lack of space. There
are too many permanent entries.
4. You attempted to bind a raw IP socket when
there were no interfaces defined in the
system.
5. You attempted to bind a raw IP socket to a
null INET address.
SS$_IVBUFLEN Programming error. You specified an invalid
size for the socket option buffer.
SS$_NOLICENSE Programming or system management error. There
is no DIGITAL TCP/IP Services for OpenVMS
license present.
SS$_NOOPER Programming or INET management error. You
attempted to execute an I/O function that
needs the OPER privilege.
SS$_NOPRIV Programming or INET management error. You
attempted to execute an operation that failed
for one of the following reasons:
1. You cannot broadcast an IP datagram for
a process if you do not have system UIC,
SYSPRV, BYPASS, or OPER privileges.
2. You attempted to use a reserved port number
lower than 1024.
3. You attempted to access a process when you
do not have system UIC, SYSPRV, or BYPASS
privileges.
4. You attempted to use raw IP on a socket
that is not a privileged sockets. To do
this, the process must have SYSPRV or
BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error.
You attempted to show or delete an entry
in the ARP table. However, because the
INET address was not in the ARP table, the
operation failed.
SS$_NOSUCHNODE Programming error or INET management error.
You attempted to delete a route from the
routing information table (RIT). However,
because the route was not found in the RIT,
the operation failed.
SS$_PROTOCOL Programming error.
1. You specified an invalid protocol type when
you created the socket.
2. You specified an unsupported protocol.
3. You specified a protocol type that is
invalid because it is not found in the
internal tables.
4. You specified an address family that is
not supported for one of the following
reasons:
o You specified an address family with
an IO$_SETMODE subfunction. Instead,
specify the UCX$C_AF_INET or UCX$C_
UNSPEC address family.
o You specified an address family of the
remote INET address for a datagram or
stream socket with an IO$_ACCESS or IO$_
WRITEVBLK function. Instead, specify the
UCX$C_AF_INET address family.
o You specified an address family of the
local INET address with an IO$_SETMODE
bind function. Instead, specify the
UCX$C_AF_INET address family.
o You made a request to the routing module
by specifying the address family of
the INET address. Instead, specify the
UCX$C_AF_INET address family.
SS$_SHUT The network is being shut down.

6 IO$_WRITEVBLK

Write I/O functions provide direct transfer of data from the
virtual address space of the user's process to an internet host
or port. The DIGITAL TCP/IP Services for OpenVMS product provides
the WRITE I/O function code IO$_WRITEVBLK, which writes a user
buffer for stream sockets, datagrams, or raw IP.
If you specify multiple buffers, the system sends data from
buffers in the order specified by the p5 list. For UDP and raw
IP, the TCP/IP software sends the data in one datagram. The data
to be sent is buffered by TCP/IP before being transmitted to the
remote host.
For a TCP socket, if the socket transmit queue is full, the Write
I/O operation will be blocked until the transmit queue has enough
room for the user data.
For UDP and raw IP sockets, if the user data is greater than the
transmit (send) socket quota, an error code is returned (SS$_
TOOMUCHDATA).
The equivalent C Socket functions are recv*, send*(), sendto()
and write().
Programming examples for the IO$_WRITEVBLK routine follow
this command description. IO$_WRITEVBLK Function (MACRO-
32 Programming) uses the MACRO-32 programming language and
IO$_WRITEVBLK Function - Vectored (C Programming) uses the C
programming language to read a vectored buffer. IO$_WRITEVBLK
Function (C Programming) uses the C programming language to read
from an INET driver.

7 Arguments

p1
UCX usage buffer
type longword (unsigned)
access read only
mechanism by reference
The p1 argument specifies the starting virtual address of the
buffer containing the data to be transmitted.
p2
UCX usage buffer length
type longword (unsigned)
access read only
mechanism by value
The p2 argument specifies the size (in bytes) of the buffer
containing the data to be transmitted.
p3
UCX usage remote socket name (message source)
type longword (unsigned)
access read only
mechanism by descriptor
The p3 argument specifies the address of a UCX item_list_2
descriptor. This descriptor points to a buffer that contains
the remote port and remote host internet address (socket name) of
the message destination.
p4
UCX usage flags
type longword (unsigned)
access read only
mechanism by value
The p4 argument specifies the flags for the Write operation.
Valid Write Flags for the p4 Argument describes the valid flags
for this argument.
Table 1-18 Valid Write Flags for the p4 Argument
Flag Description
UCX$C_MSG_OOB Writes an out-of-band (OOB) byte.
UCX$C_MSG_DONTROUTE Sends the message directly without routing.
UCX$C_MSG_NBIO Completes the I/O operation and returns an
error if a condition that would cause the
I/O operation to be blocked. Similar to
using IO$M_NOWAIT.
p5
UCX usage UCX item_list_2
type longword (unsigned)
access read only
mechanism by descriptor
The p5 argument specifies the address for the descriptor of
an input parameter list. The maximum number of buffers you can
specify with the p5 argument is 16.
The p1 and p2 arguments and the p5 argument are mutually
exclusive. You either use p1 and p2 or you use p5. The software
first checks to see if the p1 argument is being used. If p1 is
not used, it checks to see if the p5 argument is being used. If
neither the p1 nor the p5 argument is being used, an error code
is produced.
The resulting transfer-length value of the I/O status block is
the sum of the bytes transferred in the multiple buffers.

7 Function_Modifiers

IO$M_INTERRUPT Sends an out-of-band byte to a target
process. At the remote process, the byte is
delivered to the user through the data receive
mechanism.
IO$M_NOWAIT Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the I/O
operation to be blocked, the system completes
the I/O operation and returns the error code
SS$_SUSPENDED.
When using this function modifier, always
check the message length in the IOSB to ensure
that all data is transferred. If only 1 byte
of data is transferred, the function returns a
success status even if data is not completely
transferred.

7 Condition_Values_Returned

SS$_ABORT Programming error, INET management error, or
hardware error. The execution of the I/O was
aborted.
SS$_ACCVIO Programming error. An attempt was made to
access an invalid memory location or buffer.
SS$_BADPARAM Programming error. A $QIO I/O function was
specified using an invalid parameter.
1. An attempt was made to execute an IO$_
WRITEVBLK function without specifying a
device socket. First create a device socket
by issuing an IO$_SETMODE function and the
proper arguments.
2. An attempt was made to issue an IO$_
READVBLK or IO$_WRITEVBLK function that
does not specify a correct buffer address
(p1, p5, or p6 is null).
3. An attempt was made to issue an IO$_
READVBLK or IO$_WRITEVBLK that specifies an
invalid vectored buffer (p5 or p6 specifies
an invalid address descriptor).
SS$_CANCEL Warning code. The I/O operation was canceled
by issuing a $CANCEL system service.
SS$_DEVINACT INET management error. The driver was not
started. A UCX START COMMUNICATION command
must be executed before issuing any $QIO
function.
SS$_DEVNOTMOUNT INET management error. The INET startup
procedure was executed improperly. The
driver was loaded, but the INET_ACP was not
activated.
SS$_EXQUOTA Returned when process resource mode wait is
disabled. There is no internet request packet
(IRP) available for completing the request.
Increase the buffered I/O quota.
SS$_FILALRACC Programming error.
1. INET address is already in use. An attempt
was made to bind the socket to an address
but the port failed.
2. IP protocol (raw socket). An attempt was
made to specify a remote INET socket
address with an IO$_WRITEVBLK function,
while an INET address was already specified
with an IO$_ACCESS function.
3. UDP/IP protocol. An attempt was made to
specify a remote INET socket address with
an IO$_WRITEVBLK function, while an INET
address was already specified with the IO$_
ACCESS function.
SS$_ILLCNTRFUNC Programming error. Unsupported operation on
the protocol (IP, UDP/IP, TCP/IP).
SS$_INSFMEM INET management or programming error returned
when process resource mode wait is disabled.
Not enough system space for buffering user
data. A higher quota for socket buffer space
needs to be set, or the internet needs more
dynamic buffer space (number of dynamic
clusters should be increased).
SS$_IVADDR Programming error. The specified INET address
is not in the system, and an invalid port
number or an INET address combination was
specified with an IO$_WRITEVBLK operation.
1. An attempt to bind the socket failed
because the INET address is not in the
system, port number zero and INET address
zero are not allowed, or port zero is not
allowed with an IO$_ACCESS or IO$_WRITEVBLK
function.
2. An attempt to get an interface INET
address, broadcast mask, or network mask
failed.
3. A send request was made on a datagram-
oriented protocol, but the destination
address is unknown or not specified.
SS$_IVBUFLEN Programming error.
1. The size of the buffer for an I/O function
is insufficient.
2. An attempt was made to issue an IO$_
WRITEVBLK function that specifies a correct
buffer address (p1 valid), but does not
specify a buffer length (p2 is null).
SS$_LINKDISCON Notification. Connection completion return
code. The virtual circuit (TCP/IP) was closed
at the initiative of the peer. The application
must stop sending data and shutdown or close
the socket.
SS$_PROTOCOL Programming error. The address family of the
remote INET address specified with an IO$_
WRITEVBLK function is not supported (UDP/IP
or TCP/IP). The address family should be the
UCX$C_AF_INET address family.
SS$_NOLINKS Programming error. The socket was not
connected (TCP/IP) or an INET port and address
were not specified with an IO$_ACCESS (UDP/IP
or IP).
1. An IO$_WRITEVBLK with no remote INET socket
address was issued on a socket that was not
the object of an IO$_ACCESS function (raw
IP).
2. An IO$_WRITEVBLK with no remote INET socket
address was issued on a socket that was not
the object of an IO$_ACCESS function (UDP
/IP).
3. An attempt was made to disconnect a socket
that is not connected, or an attempt was
made to issue an IO$_WRITEVBLK or IO$_
READVBLK function on an unconnected socket
(TCP/IP).
SS$_SHUT The network is being shut down.
SS$_SUSPENDED The operation was blocked. A send operation
requires system buffer space that is not
available. The socket is marked as performing
nonblocking operations.
SS$_TIMEOUT Programming error, INET management error, or
hardware error.
1. A TCP/IP connection timed out after several
unsuccessful retransmissions.
2. On a TCP socket where KEEPALIVE is set,
the connection was idle for longer than the
timeout interval (10 minutes by default).
SS$_TOOMUCHDATA Programming or INET management error. The
message size was too large.
1. An IP packet that is broadcast cannot be
fragmented.
2. The Not Fragment IP flag was set and the IP
datagram was too large to be sent without
being fragmented.
3. Internal error. The length of the Ethernet
datagram does not allow enough space for
the minimum IP header.
4. The message to be sent on a UDP/IP or raw
IP socket is larger than the socket buffer
high water allows.
5. An attempt was made to send or receive
more than 16 buffers specified with the p5
argument.
SS$_UNREACHABLE Programming error. Either the network address
is invalid or the network is unreachable.
Hardware error. The data link adapter detected
an error and shut itself off. The UCX software
is waiting for the adapter to come back on
line.
Example .titleIwriteITEVBLK Function (MACRO-32 Programming)
.ident /01/
;
; Write a vectored buffer
;
$inetsymdef ; INET symbols
dev: .ascid /ucx$device:/ ; INET device name
channel: .word 0 ; INET channel
iostatus: .quad 0 ; I/O status block
;
; INET Socket address definition of the remote host
;
Ret_adr:
.word INET$C_AF_INET ; INET family
.word 5002 ; Port number
; Remote host IP address
.byte 128,20,20 ; Network/subnetwork number
.byte 156 ; Remote Host number
.blkb 8
Ret_len=.-Ret_adr
leng: .long 0 ; Return length of Remote IP address
;
; INET Socket address definition of the local host
;
Local_adr:
.word INET$C_AF_INET ; INET family
.word 5001 ; Port number
; Local host IP address
.byte 128,20,20 ; Network/subnetwork number
.byte 10 ; Local Host number
.blkb 8
par11: .word INET$C_UDP ; UDP/IP protocol
.word INET_PROTYP$C_DGRAM ; Datagram type of socket
;
; Item_list_2 descriptor for the Remote IP address
;
par12: .long ret_len ; Length
.address ret_adr ; Buffer address
;
; Item_list_2 descriptor for the Local IP address
;
par13: .long ret_len ; Length
.address local_adr ; Address
;
; I/O Buffer
;
buffer:
.blkb 512
buflen=.-buffer
.entry start,^m<>
.
.
.
;
; Perform a QIOW write operation
;
write:
$qiow_s efn=#31,- ; Event flag
chan=channel, - ; Channel
func=#io$_writevblk,- ; I/O function
iosb= iostatus,- ; I/O status
p1=buffer,- ; I/O Buffer address
p2=#buflen,- ; I/O Buffer length
p3=#par12 ; Address of Descriptor
; of buffer of the remote
; Host IP address
blbc r0,exit ; Branch if error
movzwl iostatus,r0 ;
blbc r0,exit ;
$dassgn_s chan=Channel ; Deassign the socket device
exit:
ret ; Exit
.end start
#module write_vecioRITEVBLK Function - Vectored (C Programming)
/*
**++
**
** This example does vectored buffers write
**
**--
*/
/*
** INCLUDE FILES
*/
#include <descrip.h>
#include <ucx$inetdef.h> /* INET symbol definitions */
#include <iodef.h>
/*
**
*/
struct bvec /* Structure definition for vec buf */
{
int lenth ;
char *b_adrs ;
} ;
struct sockaddr { /* Structure definition for socket adrs */
short inet_family ;
short inet_port ;
char adrs[4] ;
char blkb[8] ;
} ;
struct itlst {
int lgth ;
struct sockaddr *hst ;
} ;
main()
{
int status ; /* For return status */
short channel ; /* INET channel */
short sck_parm[2] ; /* Socket creation parameter */
int iosb [2] ; /* I/O status block */
char buf_1[12],buf_2[12],buf_3[12],buf_4[12] ;
struct sockaddr remote_host ; /* Socket adrs definition for rhst */
struct sockaddr local_host ; /* Socket adrs definition for lhst */
struct itlst lhst_adrs ;
struct itlst rhst_adrs ;
struct bvec buf_vec[5] =
{
{12, &buf_1 },
{12, &buf_2 },
{12, &buf_3 },
{12, &buf_4 },
{0, 0 }
} ;
/* Descriptor for Inet device name */
struct dsc$descriptor dev =
{ 3, DSC$K_CLASS_S, DSC$K_DTYPE_T, "UCX$DEVICE:"} ;
/* Descriptor for vectored buffer */
struct dsc$descriptor buf_d =
{ 0, DSC$K_CLASS_S, DSC$K_DTYPE_T, 0} ;
/* Initialize the parameters */
sck_parm[0] = INET$C_UDP ; /* UDP/IP protocol */
sck_parm[1] = INET_PROTYP$C_DGRAM ; /* Datagram type of socket */
/* Itlst for local IP address */
lhst_adrs.lgth = sizeof(local_host);
lhst_adrs.hst = &local_host ;
rhst_adrs.lgth = sizeof(remote_host) ;
rhst_adrs.hst = &remote_host ;
buf_d.dsc$a_pointer = buf_vec;
buf_d.dsc$w_length = sizeof (bvec) ;
/* Initialize socket address for remote host */
remote_host.inet_family = INET$C_AF_INET;/* INET family */
remote_host.inet_port = 0 ; /* Port number */
remote_host.adrs[0] = 128 ; /* Network/subnetwork*/
remote_host.adrs[1] = 45 ; /* number */
remote_host.adrs[2] = 45 ;
remote_host.adrs[3] = 175 ; /* Host number */
remote_host.blkb[0] = 0 ;
remote_host.blkb[1] = 0 ;
remote_host.blkb[2] = 0 ;
remote_host.blkb[3] = 0 ;
remote_host.blkb[4] = 0 ;
remote_host.blkb[5] = 0 ;
remote_host.blkb[6] = 0 ;
remote_host.blkb[7] = 0 ;
/* Initialize socket address for local host */
local_host.inet_family = INET$C_AF_INET ;/* INET family */
local_host.inet_port = 0 ; /* Port number */
local_host.adrs[0] = 128 ; /* Network/subnetwork*/
local_host.adrs[1] = 45 ; /* number */
local_host.adrs[2] = 45 ;
local_host.adrs[3] = 186 ; /* Host number */
local_host.blkb[0] = 0 ;
local_host.blkb[1] = 0 ;
local_host.blkb[2] = 0 ;
local_host.blkb[3] = 0 ;
local_host.blkb[4] = 0 ;
local_host.blkb[5] = 0 ;
local_host.blkb[6] = 0 ;
local_host.blkb[7] = 0 ;
/*
** Assign a channel to INET device
*/
status = SYS$ASSIGN( &dev,
&channel,
0,
0) ;
if ((status & 1) == 0) {
printf("Failed to assign channel to INET device \n") ;
return(status) ;
}
/*
** Create and bind the device socket to local host
*/
status = SYS$QIOW( 31, /* Event flag */
channel, /* Channel number */
IO$_SETMODE, /* I/O function */
iosb, /* I/O status block */
0,
0,
&sck_parm, /* P1 Socket creation parameter */
0,
&lhst_adrs, /* P3 Socket bind parameter */
0,0,0) ;
if ((status & 1) == 0) {
printf("Failed to create and bind the device socket \n") ;
return(status) ;
}
/*
** Perform the QIO write operation
*/
status = SYS$QIOW( 31, /* Event flag */
channel, /* Channel number */
IO$_WRITEVBLK,/* I/O function */
iosb, /* I/O status block */
0,
0,
0,
0,
&rhst_adrs, /* P3 Remote host adrs desc */
0,
&buf_d, /* P5 Vectored buffer desc */
0) ;
if ((status & 1) == 0) {
printf("Failed to write to socket \n") ;
return(status) ;
}
/*
** Deassign the INET dev channel
*/
SYS$DASSGN (channel);
return(status) ;
}
#module write_io$_WRITEVBLK Function (C Programming)
/*
**++
**
** This example does writes to INET device
**
**--
*/
/*
** INCLUDE FILES
*/
#include <descrip.h>
#include <ucx$inetdef.h> /* INET symbol definitions */
#include <iodef.h>
struct sockaddr { /* Structure definition for socket adrs */
short inet_family ;
short inet_port ;
char adrs[4] ;
char blkb[8] ;
} ;
struct itlst {
int lgth ;
struct sockaddr *hst ;
} ;
main()
{
int status ; /* For return status */
short channel /* INET channel */
short sck_parm[2] ; /* Socket creation parameter */
int iosb [2] ; /* I/O status block */
struct sockaddr local_host ; /* Socket adrs definition for lhst */
struct itlst lhst_adrs ;
char buf[128] ;
int buflen = 128 ;
/* Descriptor for Inet device name */
struct dsc$descriptor dev =
{ 3, DSC$K_CLASS_S, DSC$K_DTYPE_T, "UCX$DEVICE:"} ;
/* Initialize the parameters */
sck_parm[0] = INET$C_UDP ; /* UDP/IP protocol */
sck_parm[1] = INET_PROTYP$C_DGRAM ; /* Datagram type of socket */
/* Itlst for local IP address */
lhst_adrs.lgth = sizeof(local_host);
lhst_adrs.hst = &local_host ;
/*
** Assign a channel to INET device
*/
status = SYS$ASSIGN( &dev,
&channel,
0,
0) ;
if ((status & 1) == 0) {
printf("Failed to assign channel to INET device \n") ;
return(status) ;
}
/* Initialize socket address for local host */
local_host.inet_family = INET$C_AF_INET ;/* INET family */
local_host.inet_port = 0 ; /* Port number */
local_host.adrs[0] = 128 ; /* Network/subnetwork*/
local_host.adrs[1] = 45 ; /* number */
local_host.adrs[2] = 45 ;
local_host.adrs[3] = 216 ; /* Host number */
local_host.blkb[0] = 0 ;
local_host.blkb[1] = 0 ;
local_host.blkb[2] = 0 ;
local_host.blkb[3] = 0 ;
local_host.blkb[4] = 0 ;
local_host.blkb[5] = 0 ;
local_host.blkb[6] = 0 ;
local_host.blkb[7] = 0 ;
/*
** Create and bind the device socket to local host
*/
status = SYS$QIOW( 31, /* Event flag */
channel, /* Channel number */
IO$_SETMODE, /* I/O function */
iosb, /* I/O status block */
0,
0,
&sck_parm, /* P1 Socket creation parameter */
0,
&lhst_adrs, /* P3 Socket bind parameter */
0,0,0) ;
if ((status & 1) == 0) {
printf("Failed to create and bind the device socket \n") ;
return(status) ;
}
/*
** Perform the QIO write operation
*/
status = SYS$QIOW( 0, /* Event flag */
channel, /* Channel number */
IO$_WRITEVBLK,/* I/O function */
iosb, /* I/O status block */
0,
0,
buf, /* P1 buffer */
buflen,0,0,0,0);/* P2 buffer length */
if ((status & 1) == 0) {
printf("Failed to write to INET device \n") ;
return(status) ;
}
/*
** Deassign the INET dev channel
*/
SYS$DASSGN (channel);
return(status) ;
}
3 Socket_Routines
Socket routines let you write internet programs. There are two
types of socket routines:
o Basic communication routines - These routines are the building
blocks of internet programs.
o Communication support routines - These routines perform
operations, such as searching databases, converting byte order
of network and host addresses, reading records, and returning
internet addresses.

4 Basic_Communication_Routines

This section describes the basic communication routines.

5 accept()

Accepts a connection on a passive socket.
The $QIO equivalent is the IO$_ACCESS function with the IO$M_
ACCEPT function modifier.
Format
#include <types.h>
#include <socket.h>
int accept (int s, struct sockaddr *addr, int *addrlen);

6 Arguments

s
A socket descriptor returned by socket(), subsequently bound to
an address with bind(), and is listening for connections after a
listen().
addr
A result parameter filled in with the address of the connecting
entity, as known to the communications layer. The exact format of
the structure to which the address parameter points is determined
by the domain in which the communication is occurring. This
version of DEC C supports only the internet domain (AF_INET).
addrlen
A value-result parameter. It should initially contain the size of
the structure pointed to by addr. On return it will contain the
actual length, in bytes, of the structure that has been filled in
by the communication layer.

6 Description

This routine completes the first connection on the queue
of pending connections, creates a new socket with the same
properties as s, and allocates and returns a new descriptor
for the socket. If no pending connections are present on the
queue and the socket is not marked as nonblocking, accept()
blocks the caller until a connection request is present. If the
socket is marked nonblocking by using a setsockopt() call and no
pending connections are present on the queue, accept() returns
an error. You cannot use the accepted socket to accept subsequent
connections. The original socket s remains open (listening) for
other connection requests. This call is used with connection-
based socket types, currently with SOCK_STREAM.
You can use the select() socket routine to do an accept() by
selecting it for read.
See also bind(), connect(), listen(), select(), and socket().

6 Return_Values

x A non-negative integer that is a descriptor
for the accepted socket.
0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a
socket.
[EOPNOTSUPP] The reference socket is not of type SOCK_
STREAM.
[EFAULT] The addr parameter is not in a writable part
of the user address space.
[EWOULDBLOCK] The socket is marked nonblocking and no
connections are present to be accepted.

5 bind()

Binds a name to a socket.
The $QIO equivalent is the IO$_SETMODE function with the p3
argument.
Format
#include <types.h>
#include <socket.h>
int bind (int s, struct sockaddr *name, int namelen);

6 Arguments

s
A socket descriptor created with socket().
name
Address of a structure used to assign a name to the socket in the
format specific to the family (AF_INET) socket address.
namelen
The size, in bytes, of the structure pointed to by name.

6 Description

This routine assigns a port number and IP address to an unnamed
socket. When a socket is created with socket() it exists in a
name space (address family) but has no name assigned. The bind()
routine requests that a name be assigned to the socket.
See also connect(), getsockname(), listen(), and socket().

6 Return_Values

0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a
socket.
[EADDRNOTAVAIL] The specified address is not available from
the local machine.
[EADDRINUSE] The specified internet address and ports are
already in use.
[EINVAL] The socket is already bound to an address.
[EACCESS] The requested address is protected, and the
current user has inadequate permission to
access it.
[EFAULT] The name parameter is not a valid part of the
user address space.

5 close()

Closes a connection and deletes a socket descriptor.
The $QIO equivalent is the $DASSGN system service.
Format
#include <unixio.h>
int close (s);

6 Argument

s
A socket descriptor.

6 Description

This routine deletes a descriptor from the per-process object
(DEC C structure) reference table. Associated TCP connections
close first.
See also accept(), socket(), and write().

6 Return_Values

0 Successful completion
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following value:
[EBADF] The socket descriptor is invalid.

5 connect()

Initiates a connection on a socket.
The $QIO equivalent is the IO$_ACCESS function.
Format
#include <types.h>
#include <socket.h>
int connect (int s, struct sockaddr *name, int namelen);

6 Arguments

s
A socket descriptor created with socket().
name
The address of a structure that specifies the name of the remote
socket in the format specific to the address family (AF_INET).
namelen
The size, in bytes, of the structure pointed to by name.

6 Description

If s is a socket descriptor of type SOCK_DGRAM, then this call
permanently specifies the peer where the data is sent. If it is
type SOCK_STREAM, then this call attempts to make a connection to
the specified socket.
Each communications space interprets the name parameter. This
argument specifies the socket that is connected to the socket
specified in s.
See also accept(), select(), socket(), getsockname(), and
shutdown().

6 Return_Values

0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a
socket.
[EADDRNOTAVAIL] The specified address is not available from
the local machine.
[EAFNOSUPPORT] Address in the specified address family cannot
be used with this socket.
[EISCONN] The socket is already connected.
[ETIMEOUT] Connection establishment timed out without
establishing a connection.
[ECONNREFUSED] The attempt to connect is rejected explicitly
when a connection request arrives with the
queue full.
[ENETUNREACH] The network is not reachable from this host.
[EADDRINUSE] The specified internet address and ports are
already in use.
[EFAULT] The name parameter is not a valid part of the
user address space.
[EWOULDBLOCK] The socket is nonblocking and the connection
cannot be completed immediately. It is
possible to select() the socket while it is
connecting by selecting it for writing.

5 listen()

Sets the maximum limit of outstanding connection requests for a
socket that is connection oriented.
The $QIO equivalent is the IO$_SETMODE or IO$_SETCHAR function.
Format
int listen (int s, int backlog);

6 Arguments

s
A socket descriptor of type SOCK_STREAM created using socket().
backlog
The maximum number of pending connections that can be queued
on the socket at any given time. The maximum is five and the
smallest useful backlog limit is one.

6 Description

This routine creates a queue for pending connection requests on
socket s with a maximum size of backlog. Connections can then be
accepted with accept().
If a connection request arrives with the queue full (more than
backlog connection requests pending), the client receives an
error with an errno indication of ECONNREFUSED.
See also accept(), connect(), and socket().

6 Return_Values

0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a
socket.
[EOPNOTSUPP] The socket is not of a type that supports the
operation listen().

5 read()

Reads bytes from a socket or file and places them in a user-
provided buffer.
The $QIO equivalent is the IO$_READVBLK function.
Format
#include <unixio.h>
int read (int d, void *buffer, int nbytes);

6 Arguments

d
A descriptor that must refer to a socket or file currently opened
for reading.
buffer
The address of a user-provided buffer in which the input data is
placed.
nbytes
The maximum number of bytes allowed in the read operation.

6 Description

If the end-of-file is not reached, the read() routine returns
nbytes. If the end-of-file occurs during the read() routine, it
returns the number of bytes read.
Upon successful completion, read() returns the number of bytes
actually read and placed in the buffer.
See also socket().

6 Return_Values

x The number of bytes read and placed in the
buffer.
0 Peer has closed the connection.
-1 Error; errno is set to indicate the error.

6 _Errors

You can set errno to the following values:
[EBADF] The descriptor is invalid.
[EFAULT] The buffer points outside the allocated
address space.
[EINVAL] The nbytes argument is negative.
[EWOULDBLOCK] The NBIO socket option (nonblocking) flag
is set for the socket or file descriptor
and the process would be delayed in the read
operation.

5 recv()

Receives bytes from a connected socket and places them into a
user-provided buffer.
The $QIO equivalent is the IO$_READVBLK function.
Format
#include <types.h>
#include <socket.h>
int recv (int s, char *buf, int len, int flags);

6 Arguments

s
A socket descriptor created as the result of a call to accept()
or connect().
buf
A pointer to a user-provided buffer into which received data will
be placed.
len
The size of the buffer pointed to by buf.
flags
A bit mask that can contain one or more MSG_OOB and MSG_PEEK
flags. It is built by ORing the appropriate values together, as
follows:
Flag Description
MSG_OOB Allows you to receive out-of-band data.
If out-of-band data is available, it is read
first. If no out-of-band data is available,
the MSG_OOB flag is ignored.
Use the send(), sendmsg(), and sendto() to
send out-of-band data.
MSG_PEEK Allows you to peek at the data next in line
to be received without actually removing it
from the system's buffers.
If you include the UCX$INETDEF definition file, use the flags
listed in the following table:
Flag Description
UCX$C_MSG_NBIO Does not block the I/O operation if the
transmit queue is full. Similar to using the
$QIO IO$M_NOWAIT function.
UCX$C_MSG_PURGE Flushes data from the queue. Similar to
using the $QIO IO$M_PURGE function.
UCX$C_MSG_BLOCKALL Blocks the completion of the operation until
the buffer is filled completely or until the
connection is closed. Similar to using the
$QIO IO$M_LOCKBUF function.

6 Description

This routine receives data from a connected socket. To receive
data on an unconnected socket, use the recvfrom() or recvmsg()
routines. The received data is placed in the buffer buf.
Data is sent by the socket's peer using the send, sendmsg(), or
sendto() routines.
Use the select() routine to determine when more data arrives.
If no data is available at the socket, the receive call waits
for data to arrive, unless the socket is nonblocking, in which
case a -1 is returned with the external variable errno set to
EWOULDBLOCK.
See also read(), send(), sendmsg(), sendto(), and socket().

6 Return_Values

x The number of bytes received and placed in
buf.
0 Peer has closed.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The descriptor references a file, not a
socket.
[EPIPE] You tried to write to a socket that is not
open for reading by any process.
[EWOULDBLOCK] The NBIO (nonblocking) flag is set for the
socket descriptor and the process is delayed
during the write operation.
[EFAULT] The data was specified to be received into a
nonexistent or protected part of the process
address space.

5 recvfrom()

Receives bytes for a socket from any source.
Format
#include <types.h>
#include <socket.h>
int recvfrom (int s, char *buf, int len, int flags, struct
sockaddr *from, int *fromlen) ;

6 Arguments

s
A socket descriptor created with socket() and bound to a name
using bind() or as a result of accept().
buf
A pointer to a buffer into which received data is placed.
len
The size of the buffer pointed to by buf.
flags
A bit mask that can contain one or more MSG_OOB and MSG_PEEK
flag. It is built by ORing the appropriate values together, as
follows:
Flag Description
MSG_OOB Allows you to receive out-of-band data. If
out-of-band data is available, it is read
first.
If no out-of-band data is available, the MSG_
OOB flag is ignored. To send out-of-band data,
use the send(), sendmsg(), and sendto().
MSG_PEEK Allows you to peek at the data that is next in
line to be received without actually removing
it from the system's buffers.
If you include the UCX$INETDEF definition file, use the flags
listed in the following table:
Flag Description
UCX$C_MSG_NBIO Does not block the I/O operation if the
transmit queue is full. Similar to using the
$QIO IO$M_NOWAIT function.
UCX$C_MSG_PURGE Flushes data from the queue. Similar to using
the $QIO IO$M_PURGE modifier.
UCX$C_MSG_ Blocks the completion of the operation until
BLOCKALL the buffer is filled completely or until the
connection is closed. Similar to using the
$QIO IO$M_LOCKBUF function.
from
A buffer that the recvfrom routine uses to place the address of
the socket from which the data is received.
If from is nonzero, the address is returned. If from is 0, the
address is not returned.
fromlen
Points to an integer containing the size of the buffer pointed to
by from. On return, the integer is modified to contain the actual
length of the socket address structure returned.

6 Description

This routine allows a named, unconnected socket to receive data.
The data is placed in the buffer pointed to by buf, and the
address of the sender of the data is placed in the buffer pointed
to by from if from is non-null. The structure that from points to
is assumed to be as large as the sockaddr structure.
To receive bytes from any source, the socket need not be
connected to another socket.
You can use the select() routine to determine if data is
available.
If no data is available at the socket, the recvfrom() call waits
for data to arrive, unless the socket is nonblocking, in which
case a -1 is returned with the external variable errno set to
EWOULDBLOCK.
See also read(), send(), sendmsg(), sendto(), and socket().

6 Return_Values

x The number of bytes of data received and
placed in buf.
0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The descriptor references a file, not a
socket.
[EPIPE] You tried to write to a socket that is not
open for reading by any process.
[EWOULDBLOCK] The NBIO (nonblocking) flag is set for the
socket descriptor and the process delayed
during the write operation.
[EFAULT] The data is specified to be received into a
non-existent or protected part of the process
address space.

5 recvmsg()

Receives bytes on a socket and places them into scattered
buffers.
Format
#include <types.h>
#include <socket.h>
int recvmsg (int s, struct msghdr msg[], int flags);

6 Arguments

s
A socket descriptor created with socket().
msg
flags
A bit mask that can contain one or more MSG_OOB and MSG_PEEK
flags. It is built by ORing the appropriate values together, as
follows:
Flag Description
MSG_OOB Allows you to receive out-of-band data.
If out-of-band data is available, it is read
first. If no out-of-band data is available,
the MSG_OOB flag is ignored. Use send(),
sendmsg(), and sendto() routines to send
out-of-band data.
MSG_PEEK Allows you to peek at the data that is next in
line to be received without actually removing
it from the system's buffers.
If you include the UCX$INETDEF definition file, you can use the
flags listed in the following table:
Flag Description
UCX$C_MSG_NBIO Does not block the I/O operation if the
transmit queue is full. Similar to using the
$QIO IO$M_NOWAIT function.
UCX$C_MSG_PURGE Flushes data from the queue. Similar to using
the $QIO IO$M_PURGE function.
UCX$C_MSG_ Blocks the completion of the operation until
BLOCKALL the buffer is filled completely or until the
connection is closed. Similar to using to the
$QIO IO$M_LOCKBUF modifier.

6 Description

You can use this routine with any socket, whether it is in a
connected state or not. It receives data sent by a call to
sendmsg(), send(), or sendto(). The message is scattered into
several user buffers if such buffers are specified.
To receive data, the socket need not be connected to another
socket.
When the iovec[iovcnt] array specifies more than one buffer, the
input data is scattered into iovcnt buffers as specified by the
members of the iovec array:
iov[0], iov[1], ..., iov[iovcnt]
When a message is received, it is split among the buffers by
filling the first buffer in the list, then the second, and so on,
until either all of the buffers are full or there is no more data
to be placed in the buffers.
You can use the select() routine to determine when more data
arrives.
See also read(), send(), and socket().

6 Return_Values

x The number of bytes returned in the msg_iov
buffers.
0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The descriptor references a file, not a
socket.
[EPIPE] You tried to read a socket that is not open
for reading by any process.
[EWOULDBLOCK] The NBIO (nonblocking) flag is set for the
socket descriptor and the process is delayed
during the read operation.
[EINTR] The receive is interrupted by delivery of a
signal before any data is available for the
receive.
[EFAULT] The data is specified to be received into a
non-existent or protected part of the process
address space.

5 select()

Allows you to poll or check a group of sockets for I/O activity.
It can indicate which sockets are ready to be read or written, or
which sockets have an exception pending.
Format
#include <time.h>
int select (int nfds, int *readfds, int *writefds, int
*execptfds, struct timeval *timeout);

6 Arguments

nfds
The highest numbered socket descriptor for which to search. In
other words, the nfds argument is the highest numbered bit plus
1 in readfds, writefds, and exceptfds that should be examined.
Descriptor s is represented by 1<< s (1 shifted to the left s
number of times).
This argument is used only to improve efficiency. If you are
unsure what the highest numbered socket descriptor is, you can
safely set nfds to 32.
The DEC C select() routine examines only the longwords referenced
by the readfds, writefds, and exceptfds arguments. Therefore, any
program that uses the DEC C select routine can never have more
than 32 files and sockets opened simultaneously.
readfds
A pointer to an array of bits, organized as integers (each
integer describing 32 descriptors) that should be examined
for read readiness. If bit n of the longword is set, socket
descriptor n is checked to see if it is ready to be read. All
bits set in the bit mask must correspond to the file descriptors
of sockets. The select() routine cannot be used on normal files.
On return, the longword to which readfds points contains a bit
mask of the sockets that are ready for reading. Only bits that
were set on entry to select() could possibly be set on exit.
writefds
A pointer to a longword bit mask of the socket descriptors that
should be examined for write readiness. If bit n of the longword
is set, socket descriptor n is checked to see if it is ready to
be written to. All bits set in the bit mask must correspond to
socket descriptors.
On return, the longword that writefds points to contains a bit
mask of the sockets that are ready for writing. Only bits that
were set on entry to select() are set on exit.
exceptfds
A pointer to a longword bit mask of the socket descriptors that
is examined for exceptions. If bit n of the longword is set,
socket descriptor n is checked to see if it has any pending
exceptions. All bits set in the bit mask must correspond to the
file descriptors of sockets.
On return, the longword exceptfds pointer contains a bit mask of
the sockets that have exceptions pending. Only bits that were set
on entry to select() could possibly be set on exit.
timeout
The length of time that select() should examine the sockets
before returning. If one of the sockets specified in the readfds,
writefds, and exceptfds bit masks is ready for I/O, select()
returns before the timeout period has expired.
The timeout structure points to a timeval structure.

6 Description

This routine determines the I/O status of the sockets specified
in the various mask arguments. It returns either when a socket is
ready to be read or written, when the timeout period expires,
or when exceptions occur. If timeout is a nonzero integer,
it specifies a maximum interval to wait for the selection to
complete.
If the timeout argument is null, the select() routine blocks
indefinitely. In order to effect a poll, timeout is non-null, and
points to a zero-valued structure.
If a process is blocked on a select() routine while waiting for
input for a socket and the sending process closes the socket,
then the select() routine notes this as an event and unblocks
the process. The descriptors are always modified on return if
select() returns because of the timeout.
NOTE
When the socket option SO_OOBINLINE is set on the device
socket, a select() on both read and exception events returns
the socket mask set on both the read and exception mask.
Otherwise, only the exception mask is set.
See also accept(), connect(), read(), recv(), recvfrom(),
recvmsg(), send(), sendmsg(), sendto(), and write().

6 Return_Values

n The number of sockets ready for I/O or pending
exceptions. This value matches the number
of returned bits that are set in all output
masks.
0 The select() routine timed out before any
socket became ready for I/O.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] One of the bit masks specified an invalid
descriptor.
[EINVAL] The specified time limit is unacceptable. One
of its components is negative or too large.

5 send()

Sends bytes through a socket to its connected peer.
The $QIO equivalent is the IO$_WRITEVBLK function.
Format
#include <types.h>
#include <socket.h>
int send (int s, char *msg, int len, int flags);

6 Arguments

s
A socket descriptor created with socket() that was connected to
another socket using accept() or connect().
msg
A pointer to a buffer containing the data to be sent.
len
The length, in bytes, of the data pointed to by msg.
flags
Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data
is sent out-of-band. This means that the data can be received
before other pending data on the receiving socket if the receiver
also specifies a MSG_OOB in the flag parameter of the call.
If you include the UCX$INETDEF definition file, you can also use:
o UCX$C_MSG_DONTROUTE - Sends the message directly without
routing.
o UCX$C_MSG_NBIO - Completes the I/O operation and returns an
error if a condition occurs that would cause the I/O operation
to be blocked. Similar to using the $QIO IO$M_NOWAIT modifier.

6 Description

You can only use this routine on connected sockets. To send
data on an unconnected socket, use the sendmsg() or sendto()
routines. The send() routine passes data along to its connected
peer, which can receive the data by using recv().
If there is no space available to buffer the data being sent
on the receiving end of the connection, send() normally blocks
until buffer space becomes available. If the socket is defined as
nonblocking, however, send() fails with an errno indication of
EWOULDBLOCK. If the message is too large to be sent in one piece
and the socket type requires that messages be sent atomically
(SOCK_DGRAM), send() fails with an errno indication of EMSGSIZE.
No indication of failure to deliver is implicit in a send(). All
errors (except EWOULDBLOCK) are detected locally. You can use the
select() routine to determine when it is possible to send more
data.
See also read(), recv(), recvmsg(), recvfrom(), getsockopt(),
and socket().

6 Return_Values

n The number of bytes sent. This value normally
equals len.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The descriptor references a file, not a
socket.
[EFAULT] An invalid user space address is specified for
a parameter.
[EMSGSIZE] The socket requires that messages be sent
atomically, and the size of the message to be
sent made this impossible.
[EWOULDBLOCK] Blocks if the system does not have enough
space for buffering the user data.

5 sendmsg()

Sends gathered bytes through a socket to any other socket.
Format
#include <types.h>
#include <socket.h>
int sendmsg (int s, struct msghdr msg[], int flags);

6 Arguments

s
A socket descriptor created with socket().
msg
A pointer to a msghdr structure containing the message to be
sent.
The msg_iov field of the msghdr structure is used as a series of
buffers from which data is read in order until msg_iovlen bytes
have been obtained.
flags
Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data
is sent out-of-band. This means that the data can be received
before other pending data on the receiving socket if the receiver
also specifies a flag of MSG_OOB.
If you include the UCX$INETDEF definition file, you can also use:
o UCX$C_MSG_DONTROUTE - Sends the message directly without
routing.
o UCX$C_MSG_NBIO - Completes the I/O operation and returns an
error if a condition occurs that would cause the I/O operation
to be blocked. Similar to using the $QIO IO$M_NOWAIT modifier.

6 Description

You can use this routine on any socket to send data to any named
socket. The data in the msg_iovec field of the msg structure is
sent to the socket whose address is specified in the msg_name
field of the structure. The receiving socket gets the data using
the read(), recv(), recvfrom(), or recvmsg() routine. When the
iovec array specifies more than one buffer, the data is gathered
from all specified buffers before being sent.
If no space is available to buffer the data on the receiving
end of the connection, the sendmsg() routine normally blocks
until buffer space becomes available. If the socket is defined
as nonblocking, the sendmsg() routine fails with an errno
indication of EWOULDBLOCK. If the message is too large to be
sent in one piece and the socket type requires that messages be
sent atomically (SOCK_DGRAM), the sendmsg() fails with an errno
indication of EMSGSIZE.
If the address specified is a INADDR_BROADCAST address, then
the SO_BROADCAST option must be set and the process must have
a system UIC, OPER, SYSPRV, or BYPASS privilege for the I/O
operation to succeed.
No indication of failure to deliver is implicit in a sendmsg()
routine. All errors (except EWOULDBLOCK) are detected locally.
You can use the select() routine to determine when it is possible
to send more data.
See also read(), recv(), recvfrom(), recvmsg(), socket(), and
getsockopt().

6 Return_Values

n The number of bytes sent.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a
socket.
[EFAULT] An invalid user space address is specified for
a parameter.
[EMSGSIZE] The socket requires that messages be sent
atomically, and the size of the message to be
sent makes this impossible.
[EWOULDBLOCK] Blocks if the system does not have enough
space for buffering the user data.

5 sendto()

Sends bytes through a socket to any other socket.
The $QIO equivalent is the IO$_WRITEVBLK function.
Format
#include <types.h>
#include <socket.h>
int sendto (int s, char *msg, int len, int flags, struct
sockaddr *to, int tolen);

6 Arguments

s
A socket descriptor created with socket().
msg
A pointer to a buffer containing the data to be sent.
len
The length of the data pointed to by msg.
flags
Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data
is sent out-of-band. This means that the data can be received
before other pending data on the receiving socket if the receiver
also specifies a MSG_OOB in its flag parameter of the call.
If you include the UCX$INETDEF definition file, you can also use:
o UCX$C_MSG_DONTROUTE - Sends the message directly without
routing.
o UCX$C_MSG_NBIO - Completes the I/O operation and returns an
error if a condition occurs that would cause the I/O operation
to be blocked. Similar to using the $QIO IO$M_NOWAIT modifier.
to
Points to the address structure of the socket to which the data
is to be sent.
tolen
The length of the address structure to points to.

6 Description

This routine can be used on sockets to send data to named
sockets. The data in the msg buffer is sent to the socket
whose address is specified in the to argument, and the
address of socket s is provided to the receiving socket. The
receiving socket gets the data using either the read(), recv(),
recvfrom(), or recvmsg() routine.
If there is no space available to buffer the data being sent
on the receiving end of the connection, the sendto() routine
blocks until buffer space becomes available. If the socket is
defined as nonblocking, the sendto() routine fails with an errno
indication of EWOULDBLOCK. If the message is too large to be sent
in one piece and the socket type requires that messages be sent
atomically (SOCK_DGRAM), the sendto() routine fails with an errno
indication of EMSGSIZE.
No indication of failure to deliver is implicit in a sendto().
All errors (except EWOULDBLOCK) are detected locally. You can use
the select() routine to determine when it is possible to send
more data.
If the address specified is a INADDR_BROADCAST address, then the
SO_BROADCAST option must be set and the process must have SYSPRV
or BYPASS privilege for the I/O operation to succeed.
See also read(), recv(), recvfrom(), recvmsg(), socket(), and
getsockopt().

6 Return_Values

n The number of bytes sent. This value normally
equals len.
-1 Error; errno is set to indicate the error.

6 Errors

5 shutdown()

Shuts down all or part of a bidirectional connection on a socket.
This routine disallows further receives, further sends, or both.
The $QIO equivalent is the IO$_DEACCESS function with the IO$M_
SHUTDOWN function modifier.
Format
#include <socket.h>
int shutdown (int s, int how);

6 Arguments

s
A socket descriptor that is in a connected state as a result of a
previous call to either connect() or accept().
how
How the socket is to be shut down. Use one of the following
values:
0 (INET$C_DSC_ Disallows further calls to recv() on the
RCV) socket.
1 (INET$C_DSC_ Disallows further calls to send() on the
SND) socket.
2 (INET$C_DSC_ Disallows further calls to both send() and
ALL) recv().

6 Description

This routine allows communications on a socket to be shut down
one piece at a time rather than all at once. Use the shutdown()
routine to create unidirectional connections rather than the
normal bidirectional (full-duplex) connections.
See also connect() and socket().

6 Return_Values

0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The descriptor references a file, not a
socket.
[ENOTCONN] The specified socket is not connected.

5 socket()

Creates an end point for communication by returning a special
kind of file descriptor called a socket descriptor, which is
associated with a UCX socket device channel.
The $QIO equivalent is the IO$_SETMODE or IO$_SETCHAR function.
Format
#include <types.h>
#include <socket.h>
int socket (int af, int type, int protocol);

6 Arguments

af
The address format to be used in later references to the socket.
Addresses specified in subsequent operations using the socket
are interpreted according to this format. Currently, only AF_INET
(internet style) addresses are supported.
type
The socket types are:
o SOCK_STREAM - Provides sequenced, reliable, two-way,
connection-based byte streams with an available out-of-band
data transmission mechanism.
o SOCK_DGRAM - Supports datagrams (connectionless, unreliable
data transmission mechanism).
o SOCK_RAW - Provides access to internal network interfaces,
and are available only to users with a system UIC or SYSPRV
privilege.
protocol
The protocol to be used with the socket. Normally only a single
protocol exists to support a particular socket type using a given
address format. However, many protocols may exist, in which case
a particular protocol must be specified with this argument. Use
the protocol number that is specific to the communication domain
in which communication takes place.

6 Description

This routine provides the primary mechanism for creating sockets.
The type and protocol of the socket affect the way the socket
behaves and how it can be used.
The operation of sockets is controlled by socket-level options,
defined in the file <socket.h>. Use the setsockopt() and
getsockopt() routines to set and get options. Options other than
SO_LINGER take an integer parameter that should be nonzero if the
option is to be enabled, or 0 if it is to be disabled. SO_LINGER
uses a linger structure parameter defined in <socket.h>.
o SO_REUSEADDR - Indicates that the rules used in validating
addresses supplied in a bind() call should allow reuse of
local addresses.
o SO_KEEPALIVE - Keeps connections alive by enabling the
periodic transmission of messages on a connected socket. If
the connected party fails to respond to these messages, the
connection is considered broken and processes using the socket
are notified through the error code SS$_LINKDISCON.
o SO_DONTROUTE - Indicates that outgoing messages should bypass
the standard routing facilities. Instead, messages are
directed to the appropriate network interface according to
the network portion of the destination address.
o SO_LINGER - Lingers on close if data is present. It controls
the actions taken when unsent messages are queued on
the socket and a close() is performed. When using the
setsockopt() to set the linger values, the option value for
the SO_LINGER command is the address of a linger structure.
If the socket promises reliable delivery of data and l_onoff
is nonzero, the system will block the process on the attempt
until it is able to transmit the data or until it decides it
is unable to deliver the information. A timeout period, called
the linger interval, is specified in l_linger. If l_onoff is
set to 0 and a close is issued, the system processes the close
in a manner that allows the process to continue as quickly as
possible.
o SO_BROADCAST - Enables or disables broadcasting on the socket.
See also accept(), bind(), connect(), listen(), read(), recv(),
recvfrom(), recvmsg(), select(), send(), sendmsg(), sendto(),
shutdown(), and write().
See also getsockname() and getsockopt().

6 Return_Values

x A file descriptor that refers to the socket
descriptor.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EAFNOSUPPORT] The specified address family is not supported
in this version of the system.
[ESOCKTNOSUPPORT] The specified socket type is not supported in
this address family.
[EPROTONOSUPPORT] The specified protocol is not supported.
[EPROTOTYPE] Request for a type of socket for which there
is no supporting protocol.
[EMFILE] The per-process descriptor table is full.
[ENOBUFS] No buffer space is available. The socket
cannot be created.

5 write()

Writes a buffer of data to a socket or file.
The $QIO equivalent is the IO$_WRITEVBLK function.
Format
#include <unixio.h>
int write (int d, void *buffer, int nbytes);

6 Arguments

d
A descriptor that must refer to a socket or file.
buffer
The address of contiguous storage from which the output data is
taken.
nbytes
The maximum number of bytes involved in the write operation.

6 Description

This routine attempts to write a buffer of data to a socket or
file.
See also socket().

6 Return_Values

x The number of bytes written to the socket or
file.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The d argument is not a valid descriptor open
for writing.
[EPIPE] An attempt was made to write to a socket that
is not open for reading by any process.
[EFAULT] Part of the array pointed to by iov or data
to be written to the file points outside the
process's allocated address space.
[EWOULDBLOCK] The NBIO (nonblocking) flag is set for the
socket descriptor and the process is delayed
during the write operation.
[EINVAL] The nbytes argument is negative.

4 Communication_Support_Routines

This section describes the communication support routines.

5 gethostbyaddr()

Searches the hosts database sequentially from the beginning of
the database for a host record with a given address.
The $QIO equivalent is the IO$_ACPCONTROL function with the
INETACP_FUNC$C_GETHOSTBYADDR subfunction code.
Format
#include <netdb.h>
struct hostent *gethostbyaddr (char *addr, int len, int type);

6 Arguments

addr
A pointer to a series of bytes in network order specifying the
address of the host sought. This argument does not point to an
ASCII string.
len
The number of bytes in the address pointed to by the addr
argument.
type
The type of address format being sought. Currently, only AF_INET
is supported.

6 Description

This routine finds the first host record in the hosts database
with the given address.
The gethostbyaddr() routine uses a common static area for its
return values. This means that subsequent calls to this routine
overwrite previously returned host entries. You must make a copy
of the host entry if you want to save it.

6 Return_Values

NULL Indicates an error.
x A pointer to an object having the hostent
structure.

5 gethostbyname()

Searches the hosts database sequentially from the beginning of
the database for a host record with a given name or alias. This
routine also invokes the BIND resolver to query the appropriate
name server if the information requested is not in the hosts
database.
The $QIO equivalent is the IO$_ACPCONTROL function with the
INETACP_FUNC$C_GETHOSTBYNAME subfunction code.
Format
#include <netdb.h>
struct hostent *gethostbyname (char *name);

6 Argument

name
A pointer to a null-terminated character string containing the
name or an alias of the host sought.

6 Description

This routine finds the first host in the hosts database with the
given name or alias.
The gethostbyname() routine uses a common static area for its
return values. This means that subsequent calls to this routine
overwrite previously returned host entries. You must make a copy
of the host entry if you want to save it.

6 Return_Values

NULL Indicates an error.
x A pointer to an object having the hostent
structure.

5 gethostname()

Returns the fully qualified name of the local host.
Format
#include <types.h>
#include <socket.h>
int gethostname (char *name, int namelen);

6 Arguments

name
The address of a buffer where the name should be returned. The
returned name is null-terminated unless sufficient space is not
provided.
namelen
The size of the buffer pointed to by name.

6 Description

This routine returns the translation of the logical names
UCX$INET_HOST and UCX$INET_DOMAIN when used with the UCX
software.

6 Return_Values

0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EFAULT] The buffer described by name and namelen is
not a valid, writable part of the user address
space.

5 getnetbyaddr()

Searches the networks database sequentially from the beginning of
the database for a network record with a given address.
The $QIO equivalent is the IO$_ACPCONTROL function with the
INETACP_FUNC$C_GETNETBYADDR subfunction code.
Format
#include <netdb.h>
struct netent *getnetbyaddr (long net, int type);

6 Arguments

net
The network number, in host byte order, of the networks database
entry required.
type
The type of network sought. Currently, only AF_INET is supported.

6 Description

This routine finds the first network record in the networks
database with the given address.
The getnetent(), getnetbyaddr(), and getnetbyname() routines
all use a common static area for their return values. This means
that subsequent calls to any of these routines will overwrite any
previously returned network entry. You must make a copy of the
network entry if you want to save it.

6 Return_Values

NULL Indicates end of file or an error.
x A pointer to an object having the netent
structure.

5 getnetbyname()

Searches the networks database sequentially from the beginning of
the database for a network record with a given name or alias.
The $QIO equivalent is the IO$_ACPCONTROL function with the
INETACP_FUNC$C_GETNETBYNAME subfunction code.
Format
#include <netdb.h>
struct netent *getnetbyname (char *name);

6 Argument

name
A pointer to a null-terminated character string of the name or an
alias of the network sought.

6 Description

This routine finds the first host in the networks database with
the given name or alias.
The getnetent(), getnetbyaddr(), and getnetbyname() routines all
use a common static area for their return values. This means that
subsequent calls to any of these routines overwrite previously
returned network entries. You must make a copy of the network
entry if you want to save it.

6 Return_Values

NULL Indicates end of file or an error.
x A pointer to an object having the netent
structure.

6 Errors

You can set errno to the following value:
[EFAULT] The buffer described by name is not a valid,
writable part of the user address space.

5 getnetent()

Reads the next record in the networks database, opening the
database if necessary.
Format
#include <netdb.h>
struct netent *getnetent();

6 Description

This routine allows the records in the networks database to
be read sequentially in the order in which they appear in the
database.
The getnetent(), getnetbyaddr(), and getnetbyname() routines all
use a common static area for their return values. This means that
subsequent calls to any of these routines overwrite previously
returned network entries. You must make a copy of the network
entry if you want to save it.

6 Return_Values

NULL Indicates end of file or an error.
x A pointer to an object having the netent
structure.

5 getpeername()

Returns the name of the connected peer.
The $QIO equivalent is the IO$_SENSEMODE or IO$_SENSECHAR
function with the p4 argument.
Format
#include <types.h>
#include <socket.h>
int getpeername (int s, struct sockaddr *name, int *namelen);

6 Arguments

s
A socket descriptor created using socket().
name
A pointer to a buffer within which the peer name is to be
returned.
namelen
An address of an integer that specifies the size of the name
buffer. On return, it will be modified to reflect the actual
length, in bytes, of the name returned.

6 Description

This routine returns the name of the peer connected to the socket
descriptor specified.
See also bind() socket() and getsockname().

6 Return_Values

0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a
socket.
[ENOTCONN] The socket is not connected.
[ENOBUFS] Resources were insufficient in the system to
perform the operation.
[EFAULT] The name parameter is not a valid part of the
user address space.

5 getprotobyname()

Searches the protocols database until a matching protocol name is
found or until end of file is encountered.
Format
#include <netdb.h>
struct protoent *getprotobyname (char *name);

6 Argument

name
A pointer to a string containing the desired protocol name.

6 Description

This routine returns a pointer to a protoent structure containing
the broken-out fields of the requested line from the protocols
database:
struct protoent {
char *p_name; /* official name of protocol */
char **p_aliases; /* alias list */
long p_proto; /* protocol number */
};
The members of this structure are:
p_name The official name of the protocol.
p_aliases A zero-terminated list of alternate names for
the protocol.
p_proto The protocol number.
All information is contained in a static area, so it must be
copied if it is to be saved.
See also getprotoent() and getprotobynumber().

6 Return_Values

NULL Indicates end of file or an error.
x A pointer to a protoent structure.

5 getprotobynumber()

Searches the protocols database until a matching protocol number
is found or until end of file is encountered.
Format
#include <netdb.h>
struct protoent *getprotobynumber (int *proto);

6 Argument

proto
A pointer to a string containing the desired protocol number.

6 Description

6 Return_Values

NULL Indicates end of file or an error.
x A pointer to a protoent structure.

5 getprotoent()

Reads the next line from the protocols database.
Format
#include <netdb.h>
struct protoent *getprotoent();

6 Description

This routine returns a pointer to a protoent structure containing
the broken-out fields of the next line in the protocols database:
struct protoent {
char *p_name; /* official name of protocol */
char **p_aliases; /* alias list */
long p_proto; /* protocol number */
};
The members of this structure are:
p_name The official name of the protocol.
p_aliases A zero-terminated list of alternate names for
the protocol.
p_proto The protocol number.
The getprotoent() routine keeps a pointer in the database,
allowing successive calls to be used to search the entire file.
All information is contained in a static area, so it must be
copied if it is to be saved.
See also getprotobyname() and getprotobynumber().

6 Return_Values

NULL Indicates an error.
x A pointer to a protoent structure.

5 getservbyname()

Gets information on the named service from the network services
database.
Format
#include <netdb.h>
struct servent *getservbyname (char *name, char *proto);

6 Arguments

name
A pointer to a string containing the name of the service about
which information is required.
proto
A pointer to a string containing the name of the protocol ("tcp"
or "udp") for which to search.

6 Description

This routine searches sequentially from the beginning of the
file until a matching service name is found, or until end of file
is encountered. If a protocol name is also supplied (non-null),
searches must also match the protocol.
This routine returns a pointer to a servent structure containing
the broken-out fields of the requested line in the network
services database:
struct servent {
char *s_name; /* official name of service */
char **s_aliases; /* alias list */
long s_port; /* port service resides at */
char *s_proto; /* protocol to use */
};
The members of this structure are:
s_name The official name of the service.
s_aliases A zero-terminated list of alternate names for
the service.
s_port The port number at which the service resides.
Port numbers are returned in network-byte
order.
s_proto The name of the protocol to use when
contacting the service.
All information is contained in a static area, so you must copy
it if you want it saved.
See also getservbyport().

6 Return_Values

NULL Indicates end of file or an error.
x A pointer to a servent structure.

5 getservbyport()

Gets information on the specified port from the network services
database.
Format
#include <netdb.h>
struct servent *getservbyport (int port, char *proto);

6 Arguments

port
The port number for which to search. This port number should be
specified in network-byte order.
proto
A pointer to a string containing the name of the protocol ("tcp"
or "udp") for which to search.

6 Description

This routine searches sequentially from the beginning of the
file until a matching port is found, or until end of file is
encountered. If a protocol name is also supplied (non-null),
searches must also match the protocol.
This routine returns a pointer to a servent structure containing
the broken-out fields of the requested line in the network
services database:
struct servent {
char *s_name; /* official name of service */
char **s_aliases; /* alias list */
long s_port; /* port service resides at */
char *s_proto; /* protocol to use */
};
The members of this structure are:
s_name The official name of the service.
s_aliases A zero-terminated list of alternate names for
the service.
s_port The port number at which the service resides.
Port numbers are returned in network-byte
order.
s_proto The name of the protocol to use when
contacting the service.
All information is contained in a static area, so you must copy
it if you it saved.
See also getservbyname().

6 Return_Values

NULL Indicates end of file or an error.
x A pointer to a servent structure.

5 getsockname()

Returns the name associated with a socket.
The $QIO equivalent is the IO$_SENSEMODE or IO$_SENSECHAR
function with the p3 argument.
Format
#include <types.h>
#include <socket.h>
int getsockname (int s, struct sockaddr *name, int *namelen);

6 Arguments

s
A socket descriptor created with socket() routine and bound to
the socket name with bind() routine.
name
A pointer to the buffer in which getsockname() should return the
socket name.
namelen
A pointer to an integer specifying the size of the buffer pointed
to by name. On return, the integer contains the actual size of
the name returned, in bytes.

6 Description

This routine returns the current name for the specified socket
descriptor. The name is a format specific to the address family
(AF_INET) assigned to the socket.
The bind() routine makes the association of the name to the
socket, not the getsockname() routine.
See also bind() and socket().

6 Return_Values

0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a
socket.
[ENOBUFS] Resources were insufficient in the system to
perform the operation.
[EFAULT] The name parameter is not a valid part of the
user address space.

5 getsockopt()

Returns the options set on a socket.
The $QIO equivalent is the IO$_SENSEMODE or IO$_SENSECHAR
function.
Format
#include <types.h>
#include <socket.h>
int getsockopt (int s, int level, int optname, char *optval,
int *optlen);

6 Arguments

s
A socket descriptor created by socket().
level
The protocol level for which the socket options are desired. It
can have one of the following values:
SOL_SOCKET Get the options at the socket level.
p Any protocol number. Get the options for
protocol level p. See the <in.h> file for
the various IPPROTO values.
optname
Interpreted by the protocol specified in the level. Options
at each protocol level are documented with the protocol. See
setsockopt() in this section for socket level options.
optval
Points to a buffer in which the value of the specified option
should be placed by getsockopt().
optlen
Points to an integer containing the size of the buffer pointed
to by optval. On return, the integer is modified to contain the
actual size of the option value returned.

6 Description

This routine gets information on socket options. See the
appropriate protocol for information on available options at
each protocol level.

6 Return_Values

0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

You can set errno to the following values:
[EBADF] The descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a
socket.
[ENOPROTOOPT] The option is unknown or the protocol is
unsupported.

5 htonl()

Converts longwords from host to network byte order.
Format
#include <in.h>
unsigned long int htonl (unsigned long int hostlong);

6 Argument

hostlong
A longword in host byte order (OpenVMS systems). All integers
on OpenVMS systems are in host byte order unless otherwise
specified.

6 Description

This routine converts 32-bit unsigned integers from host byte
order to network byte order.
The network byte order is the format in which data bytes are
expected to be transmitted through a network. All hosts on a
network should send data in network byte order. Not all hosts
have an internal data representation format that is identical
to the network byte order. The host byte order is the format in
which bytes are ordered internally on a specific host. The host
byte order on OpenVMS systems differs from the network order.
This routine is most often used with internet addresses. Network
byte order places the byte with the most significant bits at
lower addresses, whereas the OpenVMS system places the most
significant bits at the highest address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.

6 Return_Value

x A longword in network byte order.

5 htons()

Converts short integers from host to network byte order.
Format
#include <in.h>
unsigned short int htons (unsigned short int hostshort);

6 Argument

hostshort
A short integer in host byte order (OpenVMS system). All short
integers on the OpenVMS system are in host byte order unless
otherwise specified.

6 Description

This routine converts 16-bit unsigned integers from host byte
order to network byte order.
The network byte order is the format in which data bytes are
expected to be transmitted through a network. All hosts on a
network should send data in network byte order. Not all hosts
have an internal data representation format that is identical
to the network byte order. The host byte order is the format in
which bytes are ordered internally on a specific host. The host
byte order on OpenVMS systems differs from the network order.
This routine is most often used with ports as returned by
getservent(). Network byte order places the byte with the most
significant bits at lower addresses, whereas the OpenVMS system
places the most significant bits at the highest address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.

6 Return_Value

x A short integer in network byte order.
Integers in network byte order cannot be used
for arithmetic computation on the OpenVMS
system.

5 inet_addr()

Converts internet addresses in text form into numeric (binary)
internet addresses in dotted decimal format.
Format
#include <in.h>
#include <inet.h>
int inet_addr (char *cp);

6 Argument

cp
A pointer to a null-terminated character string containing an
internet address in the standard internet dotted decimal format.

6 Description

This routine returns an internet address in network byte order
when given as its argument an ASCII (null-terminated) string
representing the address in the internet standard "." notation.
Internet addresses specified with the "." notation take one of
the following forms:
a.b.c.d
a.b.c
a.b
a
When four parts are specified, each is interpreted as a byte
of data and assigned, from left to right, to the 4 bytes of an
internet address. Note that when an internet address is viewed as
a 32-bit integer quantity on the OpenVMS system, the bytes appear
in binary as "d.c.b.a". That is, OpenVMS bytes are ordered from
least significant to most significant.
When only one part is given, the value is stored directly in the
network address without any byte rearrangement.
All numbers supplied as "parts" in a "." address expression can
be decimal, octal, or hexadecimal, as specified in the C language
(that is, a leading 0x or 0X implies hexadecimal; a leading 0
implies octal; otherwise, the number is interpreted as decimal).
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.

6 Return_Values

-1 Indicates that cp does not point to a proper
internet address.
x An internet address in network byte order.

5 inet_lnaof()

Returns the local network address portion of an internet address.
Format
#include <in.h>
#include <inet.h>
int inet_lnaof (struct in_addr in);

6 Argument

in
An internet address.

6 Description

This routine returns the local network address portion of a full
internet address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.

6 Return_Value

x The local network address portion of an
internet address in host byte order.

5 inet_makeaddr()

Returns an internet address given a network address and a local
address on that network.
Format
#include <in.h>
#include <inet.h>
struct in_addr inet_makeaddr (int net, int lna);

6 Arguments

net
An internet network address in host byte order.
lna
A local network address on network net in host byte order.

6 Description

This routine combines the net and lna arguments into a single
internet address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.

6 Return_Value

x An internet address in network byte order.

5 inet_netof()

Returns the internet network address portion of an internet
address.
Format
#include <in.h>
#include <inet.h>
int inet_netof (struct in_addr in);

6 Argument

in
An internet address.

6 Description

This routine returns the internet network address (NET) portion
of a full internet address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.

6 Return_Value

x The internet network portion of an internet
address in host byte order.

5 inet_network()

Converts a null-terminated text string representing an internet
address into a network address in local host format.
Format
#include <in.h>
#include <inet.h>
int inet_network (char *cp);

6 Argument

cp
A pointer to an ASCII (null-terminated) character string
containing a network address in the standard internet "." format.

6 Description

This routine returns an internet network address as local
host integer values when given as its argument an ASCII string
representing the address in the internet standard "." notation.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.

6 Return_Values

-1 Indicates that cp does not point to a proper
internet network address.
x An internet network address as local host
integer values.

5 inet_ntoa()

Converts an internet address into a text string representing the
address in the standard internet "." notation.
Format
#include <in.h>
#include <inet.h>
char *inet_ntoa (struct in_addr in);

6 Argument

in
An internet address in network byte order.

6 Description

This routine converts an internet address into an ASCII (null-
terminated) string representing that address in the standard
internet "." notation.
WARNING
Arguments should not be passed as integers because of how
DEC C handles struct arguments.
Because the string is returned in a static buffer that is
overwritten by subsequent calls to inet_ntoa(), DIGITAL
recommends copying the string to a safe place.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.

6 Return_Value

x A pointer to a string containing the internet
address in "." notation.

5 ntohl()

Converts longwords from network byte order to host byte order.
Format
#include <in.h>
unsigned long int ntohl (unsigned long int netlong);

6 Argument

netlong
A longword in network byte order. Integers in network byte order
cannot be used for arithmetic computation on the OpenVMS system.

6 Description

This routine converts 32-bit unsigned integers from network byte
order to host byte order.
The network byte order is the format in which data bytes are
expected to be transmitted through a network. All hosts on a
network should send data in network byte order. Not all hosts
have an internal data representation format that is identical
to the network byte order. The host byte order is the format in
which bytes are ordered internally on a specific host. The host
byte order on OpenVMS systems differs from the network order.
This routine is most often used with internet addresses. Network
byte order places the byte with the most significant bits at
lower addresses, whereas the OpenVMS system places the most
significant bits at the highest address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.

6 Return_Value

x A longword in host byte order.

5 ntohs()

Converts short integers from network byte order to host byte
order.
Format
#include <in.h>
unsigned short int ntohs (unsigned short int netshort);

6 Argument

netshort
A short integer in network byte order. Integers in network byte
order cannot be used for arithmetic computation on the OpenVMS
system.

6 Description

This routine converts 16-bit unsigned integers from network byte
order to host byte order.
The network byte order is the format in which data bytes are
expected to be transmitted through a network. All hosts on a
network should send data in network byte order. Not all hosts
have an internal data representation format that is identical
to the network byte order. The host byte order is the format in
which bytes are ordered internally on a specific host.
The host byte order on OpenVMS systems differs from the network
order.
This routine is most often used with internet ports as returned
by getservent(). Network byte order places the byte with the most
significant bits at lower addresses, whereas the OpenVMS system
places the most significant bits at the highest address.

6 Return_Value

x A short integer in host byte order (OpenVMS).

5 setsockopt()

Sets options on a socket.
The $QIO equivalent is the IO$_SETMODE or IO$_SETCHAR function.
Format
#include <types.h>
#include <socket.h>
int setsockopt (int s, int level, int optname, char *optval,
int optlen);

6 Arguments

s
A socket descriptor created by socket().
level
The protocol level for which the socket options are to be
modified. It can have one of the following values:
SOL_SOCKET Set the options at the socket level.
p Any protocol number. Set the options for
protocol level p. See the <in.h> header file
for the various IPPROTO values.
optname
Interpreted by the protocol specified in level. Options at each
protocol level are documented with the protocol.
The following options are available at the socket level:
o SO_REUSEADDR indicates that the rules used in validating
addresses supplied in a bind() call should allow reuse of
local addresses.
o SO_KEEPALIVE keeps connections alive by enabling the periodic
transmission of messages on a connected socket. Should
the connected party fail to respond to these messages, the
connection is considered broken and processes using the socket
are notified through an EPIPE error.
o SO_DONTROUTE indicates that outgoing messages should bypass
the standard routing facilities. Instead, messages are
directed to the appropriate network interface according to
the network portion of the destination address.
o SO_LINGER controls the actions taken when unsent messages are
queued on the socket and a close() is performed. By default,
transmitted data is purged from the socket when the close()
is performed. SO_LINGER delays the internal socket deletion
portion of close() until either the data has been transmitted
or the device times out (in approximately 8 minutes).
o SO_BROADCAST is used to enable or disable broadcasting on
the socket. The first table that follows describes the socket
options.
If you include the UCX$INETDEF definition file, you can use the
options listed in the following three tables.
Table 1-1 Communications Socket Options
Socket Option Description
UCX$C_RCVBUF Sets the socket receive quota. This option
requires a system UIC, SYSPRV, BYPASS, or
OPER privilege to be set.
UCX$C_SNDBUF Sets the socket send quota. This option
requires a system UIC, SYSPRV, BYPASS, or
OPER privilege to be set.
UCX$C_NO_RCV_ Disables checksum calculation for received
CHECKSUM data.
UCX$C_NO_SND_ Disables checksum calculation for
CHECKSUM transmitted data.
UCX$C_NO_CHECKSUM Disables checksum calculation altogether.
Unsupported socket options are ignored. You normally set and
clear options with item_list descriptors.
Table 1-2 TCP/IP Options
TCP/IP Option Description
UCX$C_USELOOPBACK Shortcuts the data transfer when the
transfer is local to the host. This
improves the performance of the local TCP
/IP transfer process and results in a lower
load on the CPU when applications using
local transfer are active.
UCX$C_TCP_NODELAY Specifies that the send operation will not
be delayed to coalesce packets.
UCX$C_TCP_PROBE_ Specifies the time interval for the
IDLE KEEPALIVE probe, as well as for the
connection establishing the timeout.
UCX$C_TCP_DROP_IDLE Specifies the time interval after which the
connection is dropped.
UCX$C_FULL_DUPLEX_ Returns an EPIPE error (SS$_LINKDISCON)
CLOSE the first time data is sent after the peer
has closed its half of the connection.
Subsequent send operations on the half-
closed socket proceeds normally.
Table 1-3 IP Options
IP Option Description
UCX$C_IP_TTL Time to live for a datagram
UCX$C_IP_TOS Type of service (1-byte value)
optval
Points to a buffer containing the parameters of the specified
option.
All socket level options other than SO_LINGER should be nonzero
if the option is to be enabled, or zero if it is to be disabled.
SO_LINGER uses a linger structure parameter defined in the
<socket.h> file. This structure specifies the desired state of
the option and the linger interval. The option value for the SO_
LINGER command is the address of a linger structure.
If the socket promises reliable delivery of data and l_onoff is
nonzero, the system blocks the process on the close() attempt
until it is able to transmit the data or until it decides it is
unable to deliver the information. A timeout period, called the
linger interval, is specified in l_linger.
If l_onoff is set to zero and a close() is issued, the system
processes the close in a manner that allows the process to
continue as quickly as possible.
optlen
An integer containing the size of the buffer pointed to by
optval.

6 Description

This routine manipulates options associated with a socket.
Options can exist at multiple protocol levels. They are always
present at the uppermost socket level.
When manipulating socket options, specify the level at which the
option resides and the name of the option. To manipulate options
at the socket level, specify level as SOL_SOCKET. To manipulate
options at any other level, supply the protocol number of the
appropriate protocol controlling the option. For example, to
indicate that an option is to be interpreted by TCP, set the
level to the protocol number (IPPROTO_TCP) of TCP. See <in.h> for
the various IPPROTO values.

6 Return_Values

0 Successful completion.
-1 Error; errno is set to indicate the error.

6 Errors

5 vaxc$get_sdc()

Returns the socket device channel (SDC) associated with a socket
descriptor for direct use with DIGITAL TCP/IP Services for
OpenVMS software.
Format
#include <socket.h>
short int vaxc$get_sdc (int s);

6 Argument

s
A socket descriptor.

6 Description

This routine returns the SDC associated with a socket. C Socket
descriptors are normally used either as file descriptors or with
one of the routines that takes an explicit socket descriptor
as its argument. C Sockets are implemented using TCP/IP socket
device channels. This routine returns the SDC used by a given
socket descriptor so you can use the TCP/IP facilities directly
by means of various I/O system services ($QIO).
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.

6 Return_Values

0 Indicates that s is not an open socket
descriptor.
x The SDC number.

2 Displaying_User_Information
For displaying information about users on remote systems and
your local system, the DIGITAL TCP/IP Services for OpenVMS (UCX)
product includes the Finger utility. For example, you can use the
utility to determine which users are logged on to a system or to
refresh your memory about the correct login name to use before
using FTP or another service to connect to an account on a remote
host.

The Finger listing may include such information as:

o User name

o Account name

o Program the user is running

o User's home directory

o User's plans, activities, and other information

o User's project

3 Commands
Use the following rules for command syntax, quotation marks, and
wildcards when you type FINGER command lines.

4 Quotation_Marks

By default, the Finger utility translates all user and host name
specifications to lowercase. If you specify any letters that
must be uppercase, then you must enclose them in quotation marks.
In the following example, the UNIX user name includes uppercase
letters that need quotation marks around them:

FINGER "B"OB"M"ILLER@BASE1

4 Wildcards

Wildcards are not accepted for OpenVMS hosts, but may be valid
for some UNIX hosts.

4 Qualifiers

Qualifiers to the FINGER command must follow immediately
after the command, preceding the user and/or host name. If the
qualifier follows the user and/or host name, the Finger utility
interprets the qualifier as a user name. For example, in the
following command the qualifier /FULL incorrectly appears after
the user specification. As indicated by the last line in the
display, the Finger server interprets "/FULL" as a user login
name.

$ FINGER ROLLINS /FULL

Username Program Login Term/Location
ROLLINS $ Mon 15:02 64626::ROLLINS

Login name: ROLLINS In real life: Professor Rollins
Account: RES9 Directory: WORK1$:[ROLLINS]
Last login: Tue 4-MAR-1997 09:05:29
Unread mail: 25
Project: Homeopathic medicine/Silica
No Plan.
Login name: /FULL In real life: ???

The following example shows the correct position of the qualifier
(the information displayed now includes user ROLLINS' real name
and current program).

$ FINGER /FULL ROLLINS

[stlab1.bastyr.edu]
Username Real Name Program Login Term/Location
ROLLINS Ben Rollins $ Mon 15:02 64606::ROLLINS
$ Mon 09:42 64606::ROLLINS

Login name: ROLLINGS In real life: Professor Rollins
Account: RES9 Directory: WORK1$:[ROLLINS]
Last login: Tue 4-MAR-1997 09:05:29
Unread mail: 27
Project: Homeopathic medicine/Silica
No Plan.

3 User_Information
To display information about all users on a remote host, enter
the FINGER command followed by the host name (FINGER @hostname).
To display more detailed information about a particular user,
specify the user name with the host name (format FINGER
username@hostname). To display information about all users on
your local host, enter the FINGER command without specifying a
host name. To display detailed information about a specific user
on your local host, enter the FINGER command followed by the
user name. The following table summarizes the different ways to
display user information.

Table 1-1 Displaying User Information

If you need ... Use this command...

Brief information FINGER @hostname
about all users on a
remote host
Brief information FINGER
about all users on
your local host
Brief information FINGER/CLUSTER
about all users on
your cluster
Detailed information FINGER username@hostname
about a specific
user on a remote
host
Detailed information FINGER user1name@hostname
several users on a user2name@hostname
remote host
Detailed information FINGER username
about a specific
user on your local
host
Detailed information FINGER user1name user2name
about several users
on your local host
More detailed FINGER/FULL
information about
users on the local
host, including
their real name and
all logins
Detailed information FINGER/ALL username
about a specific
local user and brief
information about
all local users

4 All_Users,_Brief_Listing

To display brief information about all users on a host, use the
FINGER command with the host name only, in the format @hostname.
If you use the FINGER command alone (without specifying a host
name), you receive brief information about all users on your
local system. The following example shows how to display brief
information about all users on remote host BASTYR:

$ FINGER @SCIENCE

[science.ucd.edu]
Username Program Login Term/Location
BRADY $ Thu 07:50 dialin_706_101.ucd.lab.edu
CORRIT $ Tue 13:30 64334::CORRIT
DAVE MAIL Mon 15:02 64334::DAVE
DAWSON $ Thu 14:57
FLOYD $ Mon 17:00
KITT TPU Mon 16:57 62555::KITT
MIRTH $ Wed 16:04 UCDVAX::MIRTH
NATALIE $ Tue 09:23 64222::NATALIE
RAPSONG $ Mon 18:50 64442::RAPSONG

4 Specific_Users,_Detailed_Listing

To display details about one or more users on a remote host,
specify the user name or a list of user names, including the host
name with each user name, as shown in the examples that follow.
To display more information about users on your local host,
specify the user name(s) without a host name. The information
about each user includes the following items in addition to the
user (login) name, program, login time, and terminal/location
that is returned in the default, brief display:

o Login name

o Full name (real name)

o Working directory

o Last (previous) login

o Number of unread mail messages

o Plans and project, if the user has made the information
available

The following examples show how to display information about
specific users.

1. This example shows how to receive detailed information about
user HOWE on host BEARINGS. The second line of information
indicates user HOWE is logged on and using the Mail utility.

$ FINGER HOWE@BEARINGS

[bearings.us.beacorp.com]
Username Program Login Term/Location
HOWE MAIL Mon 15:02 84640::HOWE

Login name: HOWE In real life: Abe Howe
Account: INVENT Directory: DISK$1:[HOWE]
Last login: Tue 14-MAR-1997 10:15:39
No unread mail
Project: Inventory
No Plan.

2. To display information about several specific users on a
remote host, specify each username@hostname separated by a
space. This example shows how to display detailed information
about users HOWE and JESSE on host BEARING, and user billings
on UNIX host class. Note that user HOWE is not currently
logged on to host BEARING. JESSE is, and so FINGER includes
a line of information for JESSE including the program JESSE is
using (DCL at present) and the time of login.

$ FINGER HOWE@BEARING JESSE@BEARING BILLINGS@CLASS

[bearings.us.beacorp.com]
Login name: HOWE In real life: Abe Howe
Account: INVENT Directory: DISK$1:[HOWE]
Last login: Tue 14-MAR-1997 10:15:39
No unread mail
Project: Inventory
No Plan.
[bearings.us.beacorp.com]
Username Program Login Term/Location
JESSE $ Thu 09:24

Login name: JESSE In real life: JESSE BOYD
Account: PLAN3 Directory: DISK$1:[JESSE]
Last login: Mon 3-MAR-1997 16:48:50
Unread mail: 1
Project: Planning
Plan:
Next phase: December

Email: jesse@bearings.us.beacorp.com

Phone: 526-5444

[class.ucb.beacorp.com]
Login name: billings (messages off) In real life: M. T. Billings
Office: BLDG2-2, 236-8936 Home phone: 508-466-7873
Directory: /usr/users/billings Shell: /usr/bin/csh
On since Jan 17 14:33:06
on :0
On since Jan 17 14:33:13 15 days Idle Time
on ttyp1
On since Jan 17 14:33:13 2 days 23 hours Idle Time
on ttyp2
On since Feb 4 13:13:50 2 days 23 hours Idle Time
on ttyp5
No Plan.

3. To display detailed information about one or more specific
users and brief information about all other users logged on
a remote host, specify the user@host format for the specific
users plus @host for the brief listing of all users, as in
this example.

$ FINGER DALB@BEARING @BEARING
Username Program Login Term/Location

Login name: DALB In real life: Bob Dalb
Account: ENG_3 Directory: WORK1$:[DALB]
Last login: Thu 6-MAR-1997 16:26:06
No unread mail
Project: TCP/IP Services for OpenVMS
No Plan.

BRADY $ Thu 07:50 dialin_706_101.lkg.dec.com
BYRD $ Mon 17:00
CORTEZ $ Tue 13:30 60121::CORTEZ
DALB UCX$FINGER Thu 16:26 54242::DALB
KURT $ Mon 16:57 32556::KURT
LARSON SHWCLSTR Mon 17:01
MUELLER $ Wed 16:04 VALVE::MUELLER
NASAN $ Tue 09:23 44500::NASON
PHILLIPS $ Tue 02:42 REMHST::PHILLIPS
ROLLINS $ Mon 18:50 46142::ROLLINS
SIMMEL MAIL Thu 14:12 VALVE::SIMMEL

4. To specify detailed information about specific users and brief
information about the remaining logged-in users on a local
host, use the the /ALL qualifier as in this example, which
displays specific information about user HOWE at the local
host plus brief information about all other users logged in.
The output of this command is similar to that shown in the
preceding example.

$ FINGER/ALL HOWE

4 Cluster_Lookup

To display information about users on all nodes in your local
OpenVMS Cluster, use the /CLUSTER qualifier, as in the following
examples.

1. This example shows the default display for the FINGER/CLUSTER
command.

$ FINGER/CLUSTER

Username Node Program Login Term/Location
ANND UCDAXP $ Mon 17:00
BRADY UCDAXP $ Thu 07:50 dialin_706_101.ucd.lab.edu
CALLING UCDALP RTPAD Thu 14:50
CALLING UCDAXP $ Thu 14:57
CURREN UCDAXP $ Tue 13:30 84051::CURREN
DOBB UCDWON UCX$FINGER Mon 11:50
GILBERT UCDVAX MAIL Thu 14:34 pcgil.admin.ucd.edu
IMMIN UCDALP $ Wed 16:21 BIXBY::IMMIN
KITT UCXAXP $ Mon 16:57 62555::KITT
KITTEL UCXALP $ Thu 14:12 AGGIE::KITTEL
LEVINE UCDUNI DECW$SESSION Thu 10:50
LEVINE UCDALP UCX$UCP Thu 10:30 llevine.philos.ucd.edu
MILLLER UCDALP UCX$FINGER Thu 15:00 AGGIE::MILLER
MIRTH UCDVAX $ Tue 17:09
MIRTH UCDVAX RTPAD Mon 17:27
NATALIE UCDAXP $ Tue 09:23 64222::NATALIE
POFF UCXAXP $ Tue 02:42 AGGIE::POFF
RAPSONG UCDAXP $ Mon 18:50 64442::RAPSONG
TIBBS AGGIE $ Tue 20:43 UCXAXP::TIBBS

2. You can display each user's real name and every login to
cluster members by including the /FULL qualifier, as in this
example.

$ FINGER/CLUSTER/FULL

Username Real Name Node Program Login Term/Location
ANND Ann Darin UCDAXP $ Mon 17:00
UCDAXP $ Tue 11:51
BRADY Robert Brady UCDAXP $ Thu 07:50 dialin_706_101.ucd.edu
UCDWON $ Fri 08:31
CALLING Alvin Calling UCDALP RTPAD Thu 14:50
UCDAXP $ Thu 14:57
CURREN Steve Curren UCDAXP $ Tue 13:30 84051::CURREN
UCDVAX $ Tue 14:20
DOBB Barry Dobb UCDWON UCX$FINGER Mon 11:50
UCDAXP $ Wed 09:20
GILBERT Joanne Gilbert UCDVAX MAIL Thu 14:34 pcgil.admin.ucd.edu
IMMIN Armen Immin UCDALP $ Wed 16:21 BIXBY::IMMIN
KITT Evelyn Kitt UCXAXP $ Mon 16:57 62555::KITT
UCDALP SEARCH Mon 16:43 62555::KITT
KITTEL Herb Kittel UCXALP $ Thu 14:12 AGGIE::KITTEL
LEVINE Larry Levine UCDUNI DECW$SESSION Thu 10:50
UCDALP UCX$UCP Thu 10:30 slevine.philos.ucd.edu
MILLLER Paul Miller UCDALP UCX$FINGER Thu 15:00 AGGIE::MILLER
MIRTH Phil Anson UCDVAX $ Tue 17:09
UCDVAX RTPAD Mon 17:27
NATALIE Natalie Beardsley UCDAXP $ Tue 09:23 64222::NATALIE
POFF Pamela Offred UCXAXP $ Tue 02:42 AGGIE::POFF
RAPSONG Aaron Feller UCDAXP $ Mon 18:50 64442::RAPSONG
TIBBS Eugene Tibbs AGGIE $ Tue 20:43 UCXAXP::TIBBS

3 Host_Forwarding
If your host does not have a direct connection to a remote
host, you can use a forwarding host to get the information
about users on that remote host. Your local host must be able
to connect directly to the forwarding host, and the forwarding
host must be able to connect directly to the destination. Specify
the destination host and the forwarding host in the following
format: username@destination_host@forwarding_host. For example,
system UNION.CTSTATEU.EDU is not directly reachable, but you can
get information from it indirectly through a gateway named U-
GW.PA.ABCORP.COM. You would enter the following command to get
information about user JONES on host UNION.CTSTATEU.EDU:

$ FINGER JONES@UNION.CTSTATEU.EDU@U-GW.PA.ABCORP.COM

By default, the Finger server does not allow queries to be
forwarded from one host to another. To enable forwarding on the
Finger server, see your system manager.

3 Plan_and_Project_Information
You can use the Finger utility to display a user's project and
plans. The project (a single line of text) indicates the user's
current project, work assignment, or work group. The user's plans
can include several lines of information, such as where the user
will be throughout the week, what the user plans to accomplish
during the week, or even such information as the user's Web
site, E-mail address, and telephone number, as in the following
example:

I will be in my office Monday through Wednesday working at the S.F. lab.
On Thursday and Friday, I will be at UC Irvine for a conference.
Web site http://bio.ucd.edu/peters/r_peters.html

If you want to make such information about yourself available
to other users through the Finger utility, create the following
files in your home directory and add the appropriate information:

.PLAN A file that contains your plans, whereabouts, and
other information you wish to have displayed. The
file can contain more than one line.
.PROJECT A file that specifies your project and/or work
group. The file can contain only one line.

2 File_Transfer
The DIGITAL TCP/IP Services for OpenVMS (UCX) software includes
the File Transfer Protocol (FTP) service. FTP allows you to
connect to a remote host and:

o Transfer files between your local host and the connected
remote host

o Append local files to remote host files

o Delete and rename files on the remote host

o Create, delete, and rename directories on the remote host

o View the contents of directories and files on the remote host

o Print local files at a printer on the remote host

o Print remote files at a printer on your local host

FTP also allows you to set and display the default working
directory on the remote host as well as on your local host, and
to customize FTP command processing.

You can also use RCP to copy files. For more information on RCP,
see R_Commands.

3 Typing_Commands
Use the following rules for command syntax, quotation marks, and
wildcards when you type FTP command lines.

o Command formats

With the FTP command and most of the commands at the FTP
prompt, you can use either DCL-style or UNIX-style syntax. For
example, the DCL-style DIRECTORY and UNIX-style ls commands
produce the same results, as shown in the following example:

FTP> DIRECTORY/BRIEF *.DIR

200 PORT command successful
150 Opening data connection for DISK$2:[FLIGHT]*.DIR (11.21.308.100,2643)
com.dir;1
dis.dir;1
mail.dir;1

226 NLST Directory transfer complete.
43 bytes received in 00:00:00.09 seconds (0.42 Kbytes/s)
FTP>

FTP> ls *.dir

200 PORT command successful
150 Opening data connection for DISK$2:[FLIGHT]*.DIR (11.21.308.100,2644)
com.dir;1
dis.dir;1
mail.dir;1

226 NLST Directory transfer complete.
43 bytes received in 00:00:00.04 seconds (1.02 Kbytes/s)
FTP>

o Quotation marks

When you communicate with a non-OpenVMS host, you need to
enclose the following with quotation marks:

o UNIX path names

o UNIX file names with slashes

o Lowercase or mixed-case host names, user names, passwords,
file names, and command lines

In the following example, UNIX path names need quotation marks
around them:

FTP> PUT/FDL STAT.BCK "/USERS/SANDERS/CYGNET.BCK"

.
.
.
FTP>

o Wildcards

You can use wildcards in the following FTP commands: DELETE,
DIRECTORY, GET, and PUT.

The wildcard characters recognized by FTP are:

o The percent sign (%) to represent an individual character

o The question mark (?) to represent an individual character

o The asterisk (*) to represent multiple characters

If any of these characters are part of a file name (not
used as a wildcard), you can disable recognition of these
characters as wildcards by either enclosing the file name in
quotation marks or using the DISABLE PARSE command.

o Qualifiers

The following FTP commands require that you specify qualifiers
immediately following the command, with no space between
command and qualifier:

o CREATE

o GET

o HELP

o PUT

In the following example, the user twice attempts to enter
the GET command without the proper positioning of the /CONFIRM
qualifier.

FTP> GET TEMP. *.* /CONFIRM 1
%CLI-W-MAXPARM, too many parameters - reenter command with fewer
parameters \"/confirm"\
FTP> GET /CONFIRM TEMP. *.* 2
%CLI-W-MAXPARM, too many parameters - reenter command with fewer
parameters \"*.*"\
FTP> GET/CONFIRM TEMP. *.* 3
Get TEMP. ? [Y or N ] [Y]:Y
200 TYPE set to IMAGE.
200 PORT command successful.
150 Opening data connection for TEMP. (16.20.208.53,2634)
226 Transfer complete.
local: WORK10$:[MILGROM]TEMP.;13 remote: TEMP.
153 bytes received in 00:00:00.01 seconds (9.33 Kbytes/s)
FTP>

1 In this first attempt, the /CONFIRM qualifier is entered
following the file name parameters rather than immediately
after the GET command. An error message indicates too many
parameters have been entered.

2 The /CONFIRM qualifier follows the GET command, but with
a space between. An error message indicates too many
parameters have been entered.

3 The user enters the qualifier immediately after the
command. FTP prompts the user to confirm that file TEMP.
is to be copied and then sends a copy of the file from the
remote host.

3 Customizing_FTP
You can modify the way FTP transfers files, depending on:

o The operating system of the remote host

o The applications you use

o Whether you want wildcard name expansion

o The information you want displayed during processing

A few of the FTP commands that control FTP command processing
are:

o ENABLE/DISABLE LOG

Enables or disables the display of FTP commands sent to the
remote host.

o ENABLE/DISABLE PARSE

Enables or disables the expansion of file name specifications.

o ENABLE/DISABLE REPLY

Enables or disables the display of all responses from the
remote host.

o QUOTE

Sends FTP commands directly to the remote host without local
interpretation.

The preceding commands control the way FTP displays command
processing information and status. The SHOW STATUS command
displays the current status of the FTP client (your local host)
and, if you have a connection, the remote host.

By default, FTP returns multiple lines of error messages
(MULTILINE is enabled). The first line explains the general
problem, while subsequent lines provide details to help you
diagnose the source of the problem. These lines may include
operating system as well as FTP messages. Applications that use
FTP to transfer files under program control often do not need
the extra messages returned. To disable the MULTILINE feature,
when you supply a password to connect to a remote host, precede
the password with a hyphen "-" (-password), as in the following
example:

$ FTP /USER=SALINGER /PASSWORD=-LETMEIN HAGELS

The SHOW STATUS command displays whether the MULTILINE feature is
enabled.

You can modify the way FTP reacts to errors by using the SET
ERROR_LEVEL command. By default, the error level setting is
SUCCESS, which means that when FTP is running in batch mode, a
warning or error message will cause FTP to exit. (FTP runs in
batch mode when FTP commands are executed by a command procedure
rather than interactively.) If you do not want FTP to exit upon a
warning or error message, you can set the error level to ERROR.

For example, in the following command procedure, if the default
error level (SUCCESS) is in effect and directory [MILLER.USERS]
does not exist, the resulting error would cause FTP to exit.

$ FTP CONNECT HAGELS
CD [MILLER.USERS]
DEL *.*;*
EXIT
$

If the error level had been set to ERROR, FTP would not exit
and the DELETE command in the command procedure would delete all
files in your current working directory. Note that you can also
set the error level to WARNING, which causes FTP to tolerate
warning messages (but not error messages).

3 Starting
You can start an FTP session in any of the following ways:

o At the DCL prompt, issue the FTP command and specify a remote
host.

o At the DCL prompt, issue the FTP command with no parameters.
At the FTP prompt, issue the CONNECT or open command,
specifying a remote host.

o Invoke and use FTP from a command procedure (Command
Procedures).

You must connect to a remote host before you can enter an FTP
command that affects or displays files on the remote host. You
can invoke FTP and, without connecting to a remote host first,
enter the FTP commands that customize the FTP environment.

4 Remote_Connections

When you establish an FTP connection, the remote user name
defaults to your user name on the local system.

If you have a different user name on the remote system, do one of
the following:

o On the FTP command line, enter the /USERNAME qualifier.

o At the user name prompt, type your remote user name, for
example:

$ FTP SITE1

220 site1.midwest.billing.bench.com FTP server (Version 4.2) Ready
Connected to SITE1.midwest.billing.bench.com.
Name (SITE1:antel): crowe <return>
331 Username CROWE requires a Password
Password: not echoed<Return>
230 User logged in

If your connection is with another OpenVMS host, it executes your
LOGIN.COM procedure. You can use your LOGIN.COM command procedure
to customize the environment for your FTP sessions.

The following example connects to host XENO using the FTP
command:

$ FTP XENO /USER="bennings" /PASSWORD="keysimpl"<Return>
220 xeno FTP Server (DIGITAL UNIX Wednesday January 5, 1997) ready
Connected to XENO.site1.acctg.com.
230 User logged in
FTP>

In the following example, user DAVE invokes FTP and connects to
UNIX host sanfran using the CONNECT command:

$ FTP <Return>
FTP> CONNECT SANFRAN <Return>
220 sanfran.golden.com FTP server (DIGITAL UNIX December 18, 1996) Ready
Connected to sanfran.golden.com.
Name (sanfran:dave): <Return>
331 Password required for dave
Password: (not echoed) <Return>
230 User logged in
FTP>

4 Anonymous_FTP

Anonymous user access, also called Anonymous FTP, lets you
make an FTP connection to a remote host by specifying the name
ANONYMOUS (or another name defined by the system manager). With
Anonymous FTP, you do not need:

o A registered user account on the remote host

o To use your own user account, if you have one

o To supply a password

With Anonymous FTP, you can:

o View remote directories

- View the guest and public directories with the FTP
DIRECTORY command.

- The public directory called GUEST$PUBLIC has general
bulletin-board information. It contains files of interest
to FTP users.

o Copy files

- Issue GET and PUT commands to copy files to and from
GUEST$PUBLIC.

- The public area is read-only. You can issue the GET command
to copy files from the remote host to your local system.

Optionally, there is an ANONYMOUS$USER directory where you
can:

- Delete files

- Create directories

- Delete directories

- Rename files

- Rename directories

The system manager sets up the access restrictions for
Anonymous FTP. How the manager does this determines the
availability of features.

In the following example, UNIX user williams uses Anonymous FTP
to connect to the ANONYMOUS account on OpenVMS host TRACTPLAN.
Rather than prompting for a password, TRACTPLAN asks for the user
name.

% ftp tractplan
Connected to tractplan.green_dev.org.
220 tractplan FTP Server (Version 4.2) Ready
Name (tractplan:williams): anonymous
331 Guest login ok, send ident as password
Password: williams@tractplan.edu
230 Guest login ok, access restrictions apply

WELCOME to DIGITAL TCP/IP Services for OpenVMS
(UCX) on Internet Host TRACTPLAN
Date 04-24-97
FTP>

3 Exiting
You can end an FTP session and return to the DCL prompt with any
of the following commands: EXIT, quit, or Ctrl/Z. The following
examples close the connection with the remote host, if one is
open, and exit FTP.

FTP> EXIT
221 Goodbye.
$

FTP> QUIT
221 Goodbye.
$

If however, you want to close a connection while remaining at the
FTP prompt, use the DISCONNECT or close command.

The following examples close a connection, if one is open, and
remain at the FTP prompt for you to continue using FTP.

FTP> DISCONNECT
221 Goodbye.
FTP>

FTP> CLOSE
221 Goodbye.
FTP>

3 Command_Procedures
You can use either OpenVMS or UNIX command syntax in DCL command
procedures that use FTP. You can use command procedures to
invoke FTP tasks, connecting to a remote host and performing
assorted file operations with the remote host (see Task Command
Files), and you can use command procedures to customize the FTP
environment (see Initialization Command File).

4 Task_Command_Files

You can create DCL command procedures that include FTP
commands. In the following example, DCL command procedure
FTP_TO_SANFRAN.COM invokes FTP and copies file needs.lis from
host dave:

$! FTP_TO_SANFRAN.COM
$! This command procedure uses FTP from within
$! a DCL command file. Note that the password "letmein"
$! does not need quotation marks, but it is case sensitive.
$!
$ FTP
CONNECT sanfran
LOGIN "dave"
letmein
GET nest.lis
EXIT
$ EXIT
$

This next example, command procedure FTP_PASS_PARAMETER.COM,
accepts parameters, writes a temporary command procedure, and
executes this procedure.

$!
$! FTP_PASS_PARAMETER.COM
$! This method is useful for automated BATCH queue jobs.
$!
$ WS =="WRITE SYS$OUTPUT"
$ IF P1 .EQS "" .OR. P2 .EQS. "" .OR. P3 .EQS. "" .OR. P4 .EQS. ""
$ THEN
$ WS "@FTP_PASS_PARAMETER LOCAL-FILE SYSTEM USERNAME PASSWORD"
$ EXIT
$ ENDIF
$!
$ COM == "FTP_TEMP.COM"
$ LOG == "FTP_TEMP_COM.LOG"
$ FILE == "''P1'"
$ USER == F$EDIT("''P3'","LOWERCASE")
$ PASSW == F$EDIT("''P4'","LOWERCASE")
$!
$ ON WARNING THEN GOTO ERR
$ OPEN/WRITE OUTFILE 'COM
$ WRITE OUTFILE "$ DEFINE SYS$OUTPUT ''LOG'"
$ WRITE OUTFILE "$ FTP"
$ WRITE OUTFILE "open ''P2'"
$ WRITE OUTFILE "user ''USER'"
$ WRITE OUTFILE "''PASSW'"
$ WRITE OUTFILE "put ''FILE'"
$ WRITE OUTFILE "quit"
$ WRITE OUTFILE "$ EXIT"
$ CLOSE OUTFILE
$ @'COM
$ DELETE 'COM;*
$ PURGE 'LOG
$!
$! You can open the FTP_TEMP_COM.LOG file to check for errors,
$! for example, checking the initial return code for
$! 4xx (retry condition), or 5xx (failure condition).
$!
$ EXIT
$!
$ ERR:
$ IF F$TRNLNM("OUTFILE") .NES. "" THEN CLOSE OUTFILE
$ DELETE 'COM;*
$ EXIT
$

4 Initialization_Command_File

Initialization command files can customize your FTP sessions
with SET, ENABLE, and DISABLE commands. These command files
are optional. They eliminate the need to issue individual FTP
commands, and run automatically when you invoke FTP.

Initialization command files must:

o Be located in your login directory

o Be called FTPINIT.INI

o Contain only one command per line

The following example shows an FTP initialization command
procedure.

! This file, FTPINIT.INI, sets my FTP parameters
! the way I like them.
!
ENABLE REPLY
ENABLE TRANSFER_VERIFICATION
SET DEFAULT /LOCAL [MILLER.WORK]

When you invoke FTP, the initialization file generates output
such as the following, which displays environmental status:

$ ftp
Reply on.
Verbose mode on.
Bell off.
Hash mark printing on (1024/hash mark).
Local directory now SYS$LOGIN_DEVICE:[MILLER.WORK]

3 Default_Directory
During an FTP session, you can display or change the current
default directory either on the remote host or on your local
host.

To display the default (working) directory on the remote host,
use the SHOW DEFAULT command as in the following example:

FTP> SHOW DEFAULT
257 "/usr/users" is the current directory.

To display the working directory on the local host, use the SHOW
DEFAULT command with the /LOCAL qualifier, as in the following
example:

FTP> SHOW DEFAULT/LOCAL
Local directory is DISK$6:[MANAGER].

To change the default directory on the remote host, use the SET
DEFAULT command. The following example shows how to change the
default directory on a remote DIGITAL UNIX host to /usr/users
/robert:

FTP> SET DEFAULT "/USR/USERS/ROBERT"
250 CWD command successful.

FTP> SET DEFAULT ~ROBERT

To change back to your login default directory, specify a tilde
(~) alone, as follows:

FTP> SET DEFAULT ~
250 CWD command successful.
250 New default directory is /USR/USERS/ROBERT

This next example changes the remote working directory from /usr
/flyers/localads to /usr/flyers/localads/music:

FTP> SET DEFAULT MUSIC

To change the default directory on your local host, use the SET
DEFAULT command with the /LOCAL qualifier. The following example
sets the local default directory to USER$1:[PLANS.CHECKS]:

FTP> SET DEFAULT /LOCAL USER$1:[PLANS.CHECKS]
Local Directory now USER$1:[PLANS.CHECKS]

This next example changes the local OpenVMS default directory
down one level from [DECK] to [DECK.HEARTS]:

FTP> SET DEFAULT /LOCAL [.HEARTS]

3 Creating_and_Deleting_Directories
To create a directory on a connected remote host, use the CREATE
/DIRECTORY command. The following command example creates a
subdirectory .LOCAL_ACCTS in the current working directory on
the connected remote OpenVMS host.

FTP> CREATE/DIRECTORY [.LOCAL_ACCTS]

To delete a directory, use the DELETE/DIRECTORY command as in the
following example. The command deletes the directory created in
the preceding example.

FTP> DELETE/DIRECTORY LOCAL_ACCTS.DIR;*

3 Viewing_Remote_Directories
Use the DIRECTORY command to list the files and associated
information in remote directories. For example, the following
command lists the files in the default directory on a remote
UNIX host (assuming the user already has connected to the remote
host):

FTP> DIRECTORY
200 PORT command successful
150 Opening ASCII mode data connection for /bin/ls (16.20.208.54,1312)
total 6303
-rw-rw-r-- 1 milgrom users 1 Jan 9 1996 #UNTITLED#
-rw------- 1 milgrom users 4 Apr 11 1996 .Xauthority
-rwxr-xr-x 1 milgrom users 1499 Feb 3 1995 .cshrc
drwxr-xr-x 11 milgrom users 8192 Jan 9 1996 .dt
-rwxr-xr-x 1 milgrom users 3970 Dec 13 1995 .dtprofile

3 Renaming_and_Deleting_Files
To rename remote files, use the RENAME command. The following
command renames file YEAR.DAT to YEAR96.DAT on the connected
remote host.

FTP> RENAME YEAR.DAT YEAR96.DAT

To delete remote files, use the DELETE command. The following
command deletes all versions of file YEAR.DAT on the connected
remote host.

FTP> DELETE YEAR.DAT;*

3 Appending_Files
The FTP APPEND command allows you to append a local file to a
file on a connected remote host. The following command appends
local file JUL_DEC.DAT to file YEAR.DAT on remote host KALI. (A
connection has already been established to the remote host.)

FTP> APPEND JUL_DEC.DAT YEAR.DAT
200 PORT command successful
150 Opening data connection for year.dat. (130.180.4.8,1108)
226 Append transfer complete
local:large.txt remote:remote.dat
15596 bytes sent in 00:00:00.10 seconds (152.30 Kbytes/s)

3 Viewing_File_Contents
To display the contents of a file on a connected remote host,
use the VIEW command and specify the file name. If you are not
yet connected to a remote host, you can use the VIEW command to
display the contents of a file on your local host. In either
case, if the file is not in your current working directory,
include the directory name in the file specification.

The following example shows how to display the contents of file
ENG.DIS in your working directory on a connected host:

FTP> VIEW ENG.DIS
usrm::"khuna@jnet.com"
pobox::bearse
yield::timms
usrm::"lerry@muster.cudenver.edu"
sam
nm%us1rmc::"ldutton@TopCom.com"

3 Copying_Files
To copy files from a remote host to your local host, use the GET
command. To copy files from your local host to a remote host,
use the PUT command. To use these commands, you must have an
active FTP session with a remote host. You can enter any number
of commands during the session. Beginning with OpenVMS Version
6.2, you can also use the COPY/FTP command to copy files across
the network using TCP/IP. For more information on this command,
type HELP COPY/FTP at the DCL prompt.

Use the GET command to copy one or more files from a remote host
to your local host. For example, to copy the UNIX file acct.pay,
located in the remote working directory, to your local OpenVMS
host, use the following command:

FTP> GET ACCT.PAY

Use the PUT command to copy one or more files from your local
host to a remote host. For example, the following command copies
the local file ACCTS.LIS to a connected remote UNIX host. Use the
/FDL qualifier to prevent record attributes from being lost in
the transfer from OpenVMS to UNIX systems.

FTP> PUT ACCTS.LIS

4 How_FTP_Copies_Files_

FTP resolves the differences between UNIX file systems and
OpenVMS file systems automatically. By default, the PUT command
copies files to UNIX systems using lowercase file names without
version numbers. If you use a wildcard to copy all versions of a
file:

- The version numbers become the last element of the copied
files.

- Semicolons are converted to periods.

4 Store_Unique

The Store Unique (STOU) feature allows you to control how file
version numbers are treated when you copy (PUT) files from
local to remote hosts. After connecting to the remote host, you
toggle the Store Unique feature on and off by issuing the sunique
command at the FTP prompt, as follows:

FTP> sunique
Store unique on.
FTP> sunique
Store unique off.
FTP> sunique
Store unique on.

The Store Unique feature behaves differently when copying files
from OpenVMS to UNIX or from UNIX to OpenVMS. It also behaves
differently if you use wildcards or specify version numbers.
For example, the results vary when you copy the file text.txt as
follows:

Store Unique
FTP Command On Store Unique Off

From OpenVMS to UNIX

FTP> PUT text.txt text.txt text.txt
FTP> PUT text.txt.1 text.txt.1.1
text.txt;1
FTP> PUT text.txt.1 text.txt.1.1
text.txt;* text.txt.2 text.txt.2.1
text.txt.3 text.txt.3.1

From UNIX to OpenVMS

ftp> PUT text.txt text.txt$01 text.txt;1

4 VMS_Plus_Mode

FTP performs fast file transfers between two OpenVMS systems (VMS
Plus Mode).

When FTP identifies file transfers between two OpenVMS hosts
running DIGITAL TCP/IP Services for OpenVMS, it transfers files
in large blocks, rather than small records. VMS Plus Mode greatly
increases the transfer speed and preserves all Record Management
Services (RMS) file attributes.

FTP automatically disables VMS Plus Mode when your session is
with a UNIX host or another OpenVMS host not running DIGITAL TCP
/IP Services for OpenVMS.

4 File_Attributes

When you transfer OpenVMS files to a UNIX system and back again,
some record attributes might be lost. To preserve all RMS file
attributes, use the /FDL qualifier (File Definition Language)
with the GET and PUT commands.

You may also need to use the SET TYPE command to determine the
type of file transfer:

o Specifying SET TYPE ASCII results in a sequential file with
variable records. Select this type when transferring ASCII
text files.

o Specifying SET TYPE IMAGE results in a sequential file with
fixed records of 512 bytes. Select this type when transferring
non-ASCII files such as binary files or executable image
files.

For example, to transfer an executable image to a remote UNIX
host, follow these steps:

1. Specify the IMAGE data type:

FTP> SET TYPE IMAGE

2. Transfer the file to the remote host while at the same time
creating and transferring a secondary file with the file's
OpenVMS record attributes:

FTP> PUT/FDL file

To retrieve the file from the remote UNIX host, follow these
steps:

1. Specify the IMAGE data type:

FTP> SET TYPE IMAGE

2. Retrieve the file from the remote host after retrieving and
using the secondary file containing the file's OpenVMS record
attributes:

FTP> GET/FDL file.dat

In this next example, the PUT/FDL command does the following:

1. Creates the FDL file cygnet.bckfdl on the remote host with the
RMS attributes of file STAT.BCK .

2. Transfers the data in STAT.BCK and puts it into cygnet.bckfdl
on the remote host.

FTP> PUT/FDL STAT.BCK CYGNET.BCK
200 TYPE set to ASCII
200 PORT command successful
150 Opening data connection for cygnet.bckfdl (16.20.208.53,1028)
226 Transfer complete
local: cygnet.bckfdl remote: cygnet.bckfdl
846 bytes sent in 00:00:00.03 seconds
200 TYPE set to IMAGE
200 PORT command successful
150 Opening data connection for cygnet.bck (16.20.208.53,1029)
226 Transfer complete
local: STAT.BCK remote: cygnet.bck
8152 bytes sent in 00:00:00.12 seconds
FTP>

In this final example, the GET/FDL command does the following:

1. Transfers the FDL file cygnet.bckfdl from the remote host to
the local host.

2. Uses this file to re-create the file STAT.BCK, with all of its
original RMS attributes, on the local host.

3. Transfers the data in cygnet.bck and puts it into the new
local file STAT.BCK.

FTP> GET/FDL CYGNET.BCK STAT.BCK
200 TYPE set to ASCII
200 PORT command successful
150 Opening data connection for cygnet.bckfdl (16.20.208.53,1028)
226 Transfer complete
local: cygnet.bckfdl remote: cygnet.bckfdl
846 bytes sent in 00:00:00.03 seconds
200 TYPE set to IMAGE
200 PORT command successful
150 Opening data connection for cygnet.bck (16.20.208.53,1029)
226 Transfer complete
local: STAT.BCK remote: cygnet.bck
8152 bytes sent in 00:00:00.12 seconds
FTP>

4 Transfer_Mode

DIGITAL TCP/IP Services for OpenVMS supports only STREAM mode
for data transfer. STREAM mode transmits the data as a stream of
bytes.

4 File_Structure

DIGITAL TCP/IP Services for OpenVMS supports transfers of ASCII
(stream, records with variable length) and IMAGE (binary, records
fixed at 512 bytes) files. A file is a continuous sequence of
data bytes.

3 DECnet_Operations
To copy files from and to a DECnet node, use the standard GET and
PUT commands as described in the following paragraphs.

You can copy files to and from DECnet nodes and get remote
directory information, if your host and the DECnet node are
connected through a host running DIGITAL TCP/IP Services for
OpenVMS. Use the full file specification, including the node,
device, directory, and file name.

The following example copies local file FAX.TXT to DECnet node
CURTAIL, renaming the file to CURRENT.TXT:

FTP> PUT FAX.TXT CURTAIL::DISK$3:[GEARY.KEEPS]CURRENT.TXT

The following GET command copies remote OpenVMS file HOUSING.TXT
from DECnet node HABTAT and renames it to HOUSE.TXT:

FTP> GET HABTAT::DISK$2:[NATL.UTAH.SWEST]HOUSING.TXT HOUSE.TXT

3 Printing
Using FTP, you can:

o Print remote files on the local host using the GET command.

o Print local files on a remote host using the PUT command.

Follow these requirements:

o Specify a printer set for spooling.

o Specify the actual name of the printer, not its queue name or
logical name.

o Send individual files not batch jobs.

o When using the PUT command, specify a remote system that
supports this feature.

Note that you can also use the DCL PRINT command to print files
across the network.

4 Print_Form

FTP supports nonprint forms only. A SHOW STATUS command shows the
form type as NON_PRINT.

4 Examples

The following example sends the file MEMO.TXT from the local host
to the printer LNAX:, which is connected to the remote host:

FTP> PUT MEMO.TXT LNAX:

This next example copies remote file q4earnings and sends it to
local printer LPA0:.

FTP> GET Q4EARNINGS LPA0:

3 Suspending_FTP
While using FTP, you can use the SPAWN command to suspend
your current session and create a subprocess at the local DCL
prompt. At the DCL prompt, you can then enter any number of
DCL commands. (You can also specify a DCL command in the SPAWN
command line.) To return to your suspended FTP session (exiting
the DCL subprocess), enter the LOGOUT command. In the following
example, the user suspends the FTP session to list the files in
the working directory on the local host and delete one of the
files in that directory.

FTP> SPAWN
$ DIR
.
.
.
$ DEL TR3.TXT:*
$ LOGOUT
.
.
.
FTP>

2 Mail
For exchanging electronic mail (E-mail) with users working on
internet hosts, the DIGITAL TCP/IP Services for OpenVMS (UCX)
product includes Simple Mail Transfer Protocol (SMTP) and Post
Office Protocol (POP) software.

SMTP allows you to use the OpenVMS mail services to send and
receive messages exchanged with users on other internet hosts.
The POP software allows you to use your PC mail software to
receive and send messages. The software stores mail sent to you,
even when the PC is turned off.

3 Sending_Mail
To send E-mail to another internet host also running SMTP, simply
invoke the OpenVMS Mail utility at the DCL prompt, type SEND at
the MAIL> prompt, and enter the destination. A remote destination
consists of the user name followed by an ampersand (@) and the
host (such as user_name@host). If the user is on your local host,
omit the ampersand (@) and host name.

$ MAIL
MAIL> SEND
To: destination_user@destination_host

Specify the destination host as either a host name or an IP
address. The following example sends mail to user MALCOLM at
host PHILOS.BU.EDU:

$ MAIL
MAIL> SEND <Return>
To: malcolm@philos.bu.edu <Return>
Subj: Final Exams<Return>

The following example sends mail to user MALCOLM at the host with
IP address 16.20.40.59:

$ MAIL
MAIL> SEND <Return>
To: malcolm@16.20.40.59 <Return>
Subj: Final Exams<Return>

The OpenVMS Mail utility automatically detects destination
addresses that include fully qualified host names (where the node
component includes a period (.), such as MALCOLM@PHILOS.BU.EDU)
and sends the mail using the SMTP protocol, unless your system
has been set up to use a different Internet protocol (by defining
an alternate protocol with the MAIL$INTERNET_TRANSPORT logical
name).

However, if you use a destination address that is not fully
qualified - that is, one in which the node component does not
include a period (.) - the Mail utility by default assumes
the address is a DECnet address. For example, if you specified
MALCOLM@PHILOS as the destination address, the Mail utility
converts it to the DECnet format PHILOS::MALCOLM.

You can force the OpenVMS Mail utility to use a specific protocol
by defining the MAIL$INTERNET_MODE logical name. This is useful
in cases where a mail address, such as MALCOLM@PHILOS, can be
valid for either SMTP or DECnet.

You can assign one of the following values to the MAIL$INTERNET_
MODE logical name:

o SMTP

Mail always interprets the node component of an unqualified
address as an Internet address specification. (SMTP is the
default transport unless you define an alternate Internet
transport with the MAIL$INTERNET_TRANSPORT logical name.)

o DECNET

Mail always interprets the node component of an unqualified
address as a DECnet node specification.

o HYBRID (the default)

Mail uses an Internet protocol if the node component of the
address contains a period. If no periods are in the node
component, Mail uses the DECnet protocol.

Define the logical name in your LOGIN.COM file. For example, the
following definition causes the Mail utility to interpret any
address that does not include a period in the node component of
the specification as an Internet address:

$ DEFINE MAIL$INTERNET_MODE SMTP

Another way to force the OpenVMS Mail utility to use SMTP is to
include the SMTP% prefix. At the To: prompt, type SMTP% and, with
no space, either the destination name or IP address. Enclose the
destination in quotation marks, as in the following example:

$ MAIL
MAIL> SEND
To: SMTP%"malcolm@philos"

So, if you want to prevent the OpenVMS Mail utility from
automatically converting an unqualified Internet host name
address to a format for DECnet use, you have three choices:

o Fully qualify the host name (for example, specify
MALCOLM@PHILOS.BU.EDU instead of MALCOLM@PHILOS).

o Define the MAIL$INTERNET_MODE logical name as SMTP.

o Include the SMTP% prefix and the destination address in
quotation marks (for example, SMTP%"MALCOLM@PHILOS.BU.EDU").

For more information on the OpenVMS Mail utility and how it
interprets addresses, see the appropriate OpenVMS documentation.

4 Name_Lists

To send mail to more than one user, use the SEND command, but at
the To: prompt type one of the following:

o A list of names (Name Lists)

o The name of an existing distribution list (Distribution Lists)

When you type a list of names, use the following guidelines:

o Separate each name with a comma ( , ).

o If multiple users are on the same remote host, type the full
user_name@host combination for each user.

o If a user is on your local host, omit the ampersand (@) and
host.

Use the following syntax:

MAIL> SEND
To: user1,user2,user3@host3,user4@host4

where:

user1 is located at the local OpenVMS system.
user2 is located at the local OpenVMS system.
user3 is located at host3.
user4 is located at host4.

MAIL> SEND
To: user1@host5,user2@host5

In this example, both users are located at remote host5.

The following example sends the same mail to:

o Users NOWAK and BRENT on host CENTRAL.GREEN.ORG

o User MILLER on host BOSTON.GREEN.ORG

MAIL> SEND MEETINGS.TXT
To: NOWAK@CENTRAL.GREEN.ORG,BRENT@CENTRAL.GREEN.ORG, MILLER@BOSTON.GREEN.ORG
Subj: SCHEDULE AND AGENDAS

4 Distribution_Lists

To send mail to multiple users, at the To: prompt, you can type a
name list or use a distribution list.

To send mail to multiple users by typing the name of a
distribution list, follow these guidelines:

o The file with the distribution list can be yours or belong to
someone else.

o The file can reside locally or remotely.

o Do not include the names of other distribution lists in the
distribution list.

You can use two kinds of distribution lists:

o OpenVMS distribution list

- Create a .DIS file in your own directory or use an existing
one.

- You can include comment lines (lines preceded by an
exclamation mark (!)).

- You can include both OpenVMS addresses and SMTP addresses.
If you want the Mail utility to use SMTP for all SMTP
addresses, qualified and unqualified, either set the
MAIL$INTERNET_MODE logical name to SMTP, specify fully
qualified SMTP addresses only, or use the SMTP% prefix with
the destination enclosed in quotation marks.

- To send mail to the people on your distribution list,
issue:

MAIL> SEND
To: @list_name

o SMTP distribution list

- Create, or use an existing, .DIS file in SYS$SPECIFIC:[UCX_
SMTP] or, if defined on your system, UCX$SMTP_COMMON:.

- Give the list a unique name that is not the same as a local
user name.

- Specify comment lines with an exclamation mark (!) in the
first column.

- Include only SMTP addresses.

- Use one address per line.

- To send mail to the people on this distribution list, issue
the following command:

MAIL> SEND
To: list_name@host_where_list_resides

If the MAIL$INTERNET_MODE logical name is not set to SMTP,
specify a fully qualified host name or use the SMTP% prefix
with quotation marks enclosing the distribution list/host
specification.

The following examples show some different methods of using
distribution lists.

1. This example sends mail to users whose names are on the local
OpenVMS distribution list AGENCIES.DIS. The distribution list
file is displayed in this example. The MAIL$INTERNET_MODE
logical name is not set, so by default unqualified Internet
addresses would be sent over DECnet; therefore, the AUDUBON@NY
address is included with the SMTP% prefix and quotation marks.

$ TYPE AGENCIES.DIS

!
! This is an OpenVMS distribution file named AGENCIES.DIS.
!
SMTP%"audubon@ny"
WILLIAMS@BELTWAY.ORG
WILDLIFE@DALLAS.ORG
jmuir@19.8.7.6
SEC@GP.INTER8.ORG
BATES::SCOPE
!
$ MAIL
MAIL> SEND
To: @AGENCIES.DIS
Subj: NEWS TO WATCH FOR

2. This example sends mail to users whose names are on the
local SMTP distribution list SYS$SPECIFIC:[UCX_SMTP]NATL_
INTEREST.DIS. The distribution list file is displayed in this
example.

$ TYPE NATL_INTEREST.DIS

green@19.8.7.6
wlf@19.7.6.5
arlo@19.4.3.2
wendell@biolo.ne.edu
$ MAIL
MAIL> SEND
To: natl_interest@main_office.org
Subj: News Items

3. This example sends mail to the users on SMTP distribution list
FINANCE_CENTERS.DIS, which is maintained on remote mail server
host HOLBROOK.

$ TYPE FINANCE_CENTERS.DIS

ny_accts@23.9.7.4
sf_stocks@23.7.11.2
dallas_pfs@23.1.5.1
denver_accts@holbrook
$ MAIL
MAIL> SEND
To: finance_centers@holbrook
Subj: Portfolio Activity

3 Receiving_Mail
To read received mail, follow these steps:

1. At the DCL prompt, type MAIL.

2. At the MAIL> prompt, use the DIRECTORY command to view a list
of received messages.

3. Use the READ command or indicate the message number you wish
to view in exactly the same way as you would for OpenVMS mail.

In the following example, a user views the directory of unread
new mail and selects Message 3 to read.

$ MAIL

You have 3 new messages.

MAIL> DIRECTORY
NEWMAIL

# From Date Subject

1 GWAY::SMTP%"helenm@bhc 10-MAR-1997 Just Checking In
2 GWAY::SMTP%"mays@sfg 11-MAR-1997 Common Bases
3 CBIRD::SMTP%"seaway 12-MAR-1997 Cruises

MAIL> 3

3 Name_String
You can define a "personal name" string that is included at
the top of all the mail messages you send. To create a personal
name with SMTP mail, use the SET PERSONAL_NAME command with the
following restrictions:

o Enclose the string in quotation marks.

o Do not use additional double quotation marks within the
string.

o You may use single quotation marks ( ' ' ).

o Do not use 8-bit ASCII characters, for example, ä or ö.
The eighth bit is truncated. For example, ä becomes d and ö
becomes v.

The following example shows a user setting a personal name that
includes quotation marks:

$ MAIL
MAIL> SET PERSONAL_NAME "'Wellth' is in the mind"

3 Carbon-Copies
You can enable "carbon copying" by using the SET CC-PROMPT
command. Follow these guidelines when you specify destinations
for the CC: prompt:

o Follow the OpenVMS Mail conventions for copying mail to other
people or to yourself.

o For typing the correct address, follow the guidelines listed
in Sending Mail.

The following example sends mail to user AL and carbon copies
users ROLLINS, BOND, and RICH:

MAIL> SEND
To: al@airways
CC: rollins,bond,rich@flight_central.com
Subj: Directions for Night Flight

In the following example, OpenVMS user BRODIE sends mail to UNIX
user owens and copies soltau.

MAIL> SET CC_PROMPT
MAIL> SEND
To: owens@kezar
CC: soltau@fgtoo.bonkers.org
Subj: Goals for the Week
Enter your message below. Press CTRL/Z when complete, or CTRL/C to quit:

RC: Let's get a jump on the ball this time.
We'll meet before the conference to organize.
- J.B.<Ctrl/Z> (not echoed) <Exit>

3 Forwarding_Messages
You can forward any mail you receive to any internet host. Follow
the OpenVMS Mail conventions for forwarding mail.

If you move to another system that supports SMTP, SMTP can
forward your mail to your new location. When you set this
features, type the new address within three sets of quotation
marks.

Use the following syntax:

MAIL> SET FORWARD
_Address:SMTP%"""new_user_name@forwarding_host"""

To set the forward feature for another user, type the /USER
qualifier. Issue:

MAIL> SET FORWARD/USER=vms_node::name
_Address:SMTP%"""new_user_name@forwrding_host"""

For example, after reading a message, the FORWARD command
forwards it to user SPAN at host MILWAK.

MAIL> FORWARD
To: SMTP%"span@milwak"
CC: SELF
Subj: Who's Starting

In the following example, user CYGNET sets automatic SMTP
forwarding from host NOW to user ELLIS at host FUTURE:

MAIL> SET FORWARD /USER=now::cygnet
_Address: SMTP%"""ellis@future"""

3 PC_Mail
With SMTP and the Post Office Protocol (POP) functionality, you
can receive and send OpenVMS mail from your PC.

POP is a mail repository that accepts and stores your mail even
when the PC is turned off. At your request, the POP server reads
mail from your OpenVMS NEWMAIL folder, then moves the mail to
your MAIL folder.

To send and receive mail on your PC, make sure the system manager
has configured the POP server for use on your PC (the POP client
system).

To set up your POP client account, use one of the following
methods:

o On networks where maximum security is not required, enter your
PC mail application and configure a user name and password
into the system.

The user name and password pair becomes authorization
information for the UCX system, not your POP client
system. Your PC client sends the password to the POP server
unencrypted.

As an added security measure, POP permits only two user name
and password authorization attempts per TCP connection.

o On networks where maximum security is required, enter your
PC mail account and configure a user name and shared-secret
password into the system.

This method is called the APOP authorization method where you
store a shared-secret password in a one-line file named POP_
SECRET.DAT in your default OpenVMS mail directory.

You can use the DCL command CREATE or your text editor to
create the file and specify a password string, then set the
file protection to prevent other users from accessing it. For
example:

$ SET DEFAULT USER$DISK:[JONES.MAIL]
$ CREATE POP_SECRET.DAT
xyztancreff <Ctrl/Z>
$ SET FILE/PROT=(s,w,g,o:rwed) POP_SECRET.DAT

The shared-secret password cannot exceed 500 characters.

Each time you enter your PC mail application, the shared-
secret string is sent from the PC client to the POP server
using an encryption process.

For more information about the POP process, including information
about how POP builds SMTP-compliant mail headers, see the DIGITAL
TCP/IP Services for OpenVMS Management guide.

3 Using_UUCP
The UNIX-to-UNIX Copy Program (UUCP) lets a system copy files to
and from other systems running UUCP. UUCP is usually used to copy
files over a dialup connection (see Dialup Connections).

To route mail using UUCP, ask your system manager to define the
general gateway in the SMTP configuration.

To use SMTP to route mail to a system running UUCP, address the
mail as follows:

MAIL> SEND
To: SMTP%"user_name!uucp_host"

The following example sends mail to geoffrey at host haldir:

$ MAIL
MAIL> SEND
To: SMTP%"geoffrey!haldir.of.com"

4 Dialup_Connections

Ask your system manager if you need to specify a gateway host in
mail addresses when you work on UNIX-to-UNIX Copy Program (UUCP)
dialup lines.

The following example sends mail during a dialup connection by
specifying a gateway host:

MAIL> SEND
To: gateway_host!crandle!watts
CC: billw,jenny,ibis
Subj: Events Schedule

3 Managing_Mail
The UCX management commands that can help you work with SMTP mail
currently in a queue are listed in the following table. Type them
at the UCX> prompt.

Table 1-1 UCX Commands for Using SMTP

Command Function

SHOW MAIL Displays information about mail
REMOVE MAIL Deletes mail messages that are in holding state
in SMTP queues
SEND MAIL Releases for delivery a mail message that is in
a holding state

The following subsections describe how to use these commands. For
full command descriptions, see the DIGITAL TCP/IP Services for
OpenVMS Management Command Reference.

4 Displaying_Mail_Status

Use the UCX SHOW MAIL command to display information about SMTP
mail, such as:

o Message (entry) number of the queued mail

o User name of the sender (to display information about other
users, you need SYSPRV or BYPASS privileges)

o File name of the queued mail

o Status of a message

The following examples show how to display SMTP mail status
information.

1. The following command displays information about message
826 in an SMTP queue. By default, the command returns brief
information. Specify /FULL for more detailed information, as
in the example that follows.

$ UCX SHOW MAIL /ENTRY=826

SMTP Mail Queue Entry 826 User: MARLOW
File: _PLUTO$DKD0:[MARLOW]970207015114579_MARLOW.UCX_PLUTO;1
Status: Processing

2. The following command displays detailed information about
all your mail. The /RECIPIENT qualifier, used with the /FULL
qualifier, displays selected classes of information, depending
on the =option value you specify:

Option Description

ALL Shows failed, sent, and unsent messages
FAILED Shows messages that could not be read for a
particular recipient
SENT Shows successful deliveries to a particular
recipient
UNSENT Shows messages that, as yet, are unsent

$ UCX
UCX> SHOW MAIL /FULL /RECIPIENT=ALL

SMTP Mail Queue Entry: 826 User: MARLOW
File: _PLUTO$DKD0:[MARLOW]970207015114579_MARLOW.UCX_PLUTO;1
Status: Processing

Message Destinations:

Address: marlow@pluto

Message Headers:

Return Path: ???

SMTP Mail Queue Entry: 828 User: MARLOW
File: _PLUTO$DKD0:[MARLOW]970207015114580_MARLOW.UCX_PLUTO;1
Status: Holding

Message Destinations:

Address: marlow@pluto

Message Headers:

Return Path: ???

4 Deleting_Queued_Mail

The following examples show how to delete mail messages from SMTP
queues, using the UCX REMOVE command (similar to the DCL DELETE
/ENTRY command).

NOTE

Use this command only to release mail messages that are
being held; do not use this command to delete mail messages
in the processing state.

1. The following example deletes mail message 828, a message
that is holding (the message corresponds to your process's
user name, or you have SYSPRV or BYPASS privileges). You are
prompted to confirm that you want the message deleted.

$ UCX REMOVE MAIL /ENTRY=828
_PLUTO$DKD0:[MARLOW]970207015114580_MARLOW.UCX_PLUTO;1? y

2. This next example removes all messages for your process's
user name, or deletes everything in the SMTP queue if you
have either SYSPRV or BYPASS privileges. The /NOCONFIRM
qualifier prevents UCX from prompting you for confirmation.
Before deletion, UCX copies this queued mail to the specified
directory.

$ UCX REMOVE MAIL /NOCONFIRM /COPY=[MARLOW.OLD_MAIL]

4 Releasing_Queued_Mail

The following example shows how to requeue an SMTP mail message
that is currently holding, using the UCX SEND MAIL command
(similar to the DCL ENTRY/RELEASE command). You are prompted
to confirm you want the mail message requeued.

$ UCX SEND MAIL /ENTRY=828
_PLUTO$DKD0:[MARLOW]970207015114580_MARLOW.UCX_PLUTO;1? y

2 Network_Printing
The Line Printer/Line Printer Daemon (LPR/LPD) of the DIGITAL
TCP/IP Services for OpenVMS software supports the DCL PRINT, lpr,
LPQ, and LPRM commands for remote printing.

The LPR/LPD service allows you access to print queues on remote
hosts and allows users on remote hosts to access print queues on
your system.

You can also use FTP to print remote files on your local host and
local files on a remote host.

3 Remote_Printing
Your system manager can configure your system with LPR/LPD
network services that allow you to use the DCL PRINT command
to send print jobs to a print queue on a remote internet host.
The remote host can be a UNIX system or another OpenVMS system
running LPR/LPD.

You print a local file at a printer on a remote host by
specifying the remote queue name defined on your local host (see
your system manager for queue names). LPD copies the file to the
appropriate remote printer's spool directory. A copy of the file
to be printed remains in the spooling queue until the printer is
ready to print it.

When you issue the DCL PRINT command to send a print job to a
remote print queue, you use the /QUEUE qualifier to specify the
queue name plus any of the following qualifiers:

/AFTER /BACKUP /BEFORE /BY_OWNER
/CONFIRM /COPIES /CREATED /DELETE
/EXCLUDE /EXPIRED /FORM /HEADER
/HOLD /IDENTIFY /JOB_COUNT /MODIFIED
/NAME /NOTE /OPERATOR /PARAMETERS
/PASSALL /PRIORITY /QUEUE /SETUP
/SINCE /USER /WIDTH

Two of these qualifiers work differently with DIGITAL TCP
/IP Services for OpenVMS software than they do in a OpenVMS
environment without TCP/IP support. These two qualifiers are:

o /FORM

o /PARAMETERS

NOTE

DIGITAL TCP/IP Services for OpenVMS software does not
support layup definition files for print requests to remote
print queues. A layup definition file sets up the layup
features: borders, sheet margins, alternating margins, pages
per sheet, first page, page order, and page grid.

4 /FORM

The DCL PRINT /FORM command customizes the look of the printed
page. This qualifier associates a form other than the default
with the print job.

To see which forms are defined for your system, type:

$ SHOW QUEUE queue /FORM

To find out the currently mounted form or the default form,
issue:

$ SHOW QUEUE queue /FULL

If the FORM associated with a remote LPD queue specifies a /WIDTH
value that is not the standard 132, LPD sends a "W" card in the
job's control file with the width specified in the form.

4 /PARAMETERS

DIGITAL TCP/IP Services for OpenVMS software supports numerous
options for the DCL PRINT /PARAMETERS=(option=value) command. For
example, it supports the PAGE_SIZE option as follows:

$ PRINT/PARAMETERS=(PAGE_SIZE=size) /QUEUE=queue_name filename

When you type PRINT /PARAMETERS=(option=value), enclose the
following in quotation marks:

o Blanks

o Non-alphanumeric characters, including spaces and slashes

You can use the following /PARAMETERS options for both local
printing (standard DCL PRINT) and remote printing (DCL PRINT with
LPR/LPD network services).

DATA_TYPE NUMBER_UP PAGE_LIMIT
PAGE_ORIENTATION PAGE_SIZE SHEET_COUNT
SHEET_SIZE SIDES

For a full description of the options supported for DCL local as
well as remote printing, type the following command.

$ HELP PRINT_PARAMETER

NOTE

This help is available only if the DECprint Supervisor
(DCPS) software is installed on your system. See your system
manager for more information.

You can use the following /PARAMETERS options that are supported
only for use with remote printing.

HOST MAIL
NOFLAG PRINTERS

5 Host_and_Printers

Use the HOST and PRINTER options together to send a print job
to any specified remote host and printer that are not defined
for an LPD remote print queue on your system. Although you are
not printing to an LPD remote queue, you must specify a valid
LPD remote queue name with the /QUEUE qualifier. This activates
the remote print queue LPD service to respond to your print
request. For example, the following command specifies that the
file PINS.LIS be sent to printer CT_LN05R on remote host BALT.

$ PRINT/PARAMETERS=(HOST=BALT, PRINTER=CT_LN05R) /QUEUE=DPR_ANSI PINS.LIS

The HOST and PRINTER options allow you to use any available
network printers, without your system manager having to set up
additional LPD remote queues for each of these printers. Specify
the remote host name either by its relative name (starting name,
or label, of the absolute domain name) or by its fully qualified
name (such as PACE.STATS.RINGS_CORP.COM).

5 MAIL

The MAIL option causes the remote host to notify you through SMTP
mail when the print job completes. The following command example
specifies the MAIL option.

$ PRINT/PARAMETERS=MAIL /QUEUE=DPR_ANSI PINS.LIS

5 NOFLAG

The NOFLAG option suppresses printing of a banner (flag) page at
an LPD queue. By default, the remote printing service provider
(LPD) does not honor the /NOFLAG and /FLAG qualifiers of the DCL
PRINT command. To enable support of these qualifiers, the system
manager defines a systemwide logical name UCX$LPD_VMS_FLAGPAGES
prior to starting the remote print queues.

The following command example specifies the NOFLAG option.

$ PRINT/PARAMETERS=NOFLAG /QUEUE=DPR_ANSI PINS.LIS

4 Examples

The following examples show how to use the remote queue print
capabilities of DIGITAL TCP/IP Services for OpenVMS.

1. This example sends local file PINS.LIS to the remote print
queue defined locally as FAC3_ANSI and requests notification
through SMTP when the job completes at the remote printer.

$ PRINT /PARAMETERS=MAIL /QUEUE=FAC3_ANSI PINS.LIS

2. This example shows how to send a local file to the remote
print queue defined locally as OUR_PS for printing at a remote
printer. The command specifies that text be printed on both
sides of each sheet. The file is ROUGH.TXT.

$ PRINT /QUEUE=OUR_PS /PARAMETER=(SIDES=2) ROUGH.TXT

3. This command sends a print job to the remote queue defined
locally as YOUR_PS.

$ PRINT /QUEUE=YOUR_PS -
_$ /PARAMETERS=(DATA_TYPE=POST,PAGE_ORIENTATION=LANDSCAPE,SIDE=2) -
_$ LET.LIS

4. This example sends a print job to Internet host PACE.SATRN.COM
to print on printer K1_PRINTER. Because LPD_OUTQ is a generic
queue, OpenVMS sends the job to the first available execution
queue.

$ PRINT /QUEUE=LPD_OUTQ -
_$ /PARAMETERS=(HOST=PACE.SATRN.COM,PRINTER=K1_PRINTER) -
_$ USER$4:[GRANT.FINAN.SALES]ANNUAL.TXT

3 Remote_Queue_Status
To display the status of jobs you send to a remote printer, use
the LPQ command. The following information is displayed:

o Your name

o Current rank of job in the queue

o Names of the files in job

o Job identifier

o Total size of job in bytes

4 Examples

The following examples show how you can use the LPQ command.

1. This example displays all entries in the LPS40_QUE queue.

$ LPQ LPS40_QUE

2. This example shows information about Job 4 in the print queue
named OFFICE_QUE.

$ LPQ OFFICE_QUE /ENTRY=4

3. This example shows information about Jobs 1, 2, and 3 in print
queue PEACE_Q.

$ LPQ PEACE_Q /ENTRY=(1,2,3)

4. This example shows information about user NELSON's jobs in the
print queue FRONT_Q.

$ LPQ FRONT_Q /USER=NELSON

3 Removing_Print_Jobs
To remove your jobs from a remote print queue, use the LPRM
command. Using the LPRM command, you can remove the following:

o All of your active jobs

o All jobs, if you have the required privileges

o Selected jobs

4 Examples

The following examples show how you can use the LPRM command.

1. This example deletes one job from print queue BASE_Q.

$ LPRM BASE_Q /ENTRY=7

2. This example deletes jobs 555, 556, and 558 from queue BASE_Q.

$ LPRM BASE_Q /ENTRY=(555,556,558)

3. In this example, the system manager, who has the required
privileges, deletes all jobs from queue MAIN_QUE.

$ LPRM /ALL MAIN_QUE

3 Printing_Remote_UNIX_Files_Locally
Your system manager can set up a local print queue to handle
print jobs for files sent from a remote UNIX host. To print UNIX
files on an OpenVMS printer, the UNIX user enters an lpr command.
(See the appropriate UNIX documentation.)

Local queues set up to receive UNIX print jobs support layup
definition files. These are files supported only by DIGITAL and
used to set the following layup features: borders, sheet margins,
alternating sheet margins, pages per sheet, first page, page
order, and page grid.

4 Examples

The following example sends UNIX file /usr/stanton/recent.cnts
to OpenVMS print queue REMOTE_QUEUE4 and specifies the formatting
defined in the layup file called layup3. The REMOTE_QUEUE4 print
queue is set up as a remote queue in the printcap file by the
system manager.

% lpr -Llayup3 -Premote_queue4 /usr/stanton/recent.cnts

2 R_Commands
The Remote (R) commands provided by the DIGITAL TCP/IP Services
for OpenVMS software allow you to work in accounts on remote
internet systems also supporting the Remote (R) protocols. You
can also issue commands, shell scripts, and command procedures to
these remote host systems without logging in to the hosts. These
R commands include RCP (Remote Copy), RLOGIN (Remote Login), RSH
(Remote Shell), and REXEC (Remote Execute, invoked by RSH). You
enter these commands at your system command line prompt.

3 Accounts_and_Passwords
To use a remote command on your OpenVMS system, remote hosts need
to know the user name that you wish to use on the host. You can
provide the user name in either of two ways:

o Automatically: You do not need to take any action if your
user name is the same on the remote host as it is on the local
host. The remote commands automatically supply your local user
name as the requested user name on the remote system.

o Using the /USER_NAME qualifier: Specify the user name with the
/USER_NAME qualifier if your user name is:

- Different on the remote host

- In mixed case (only for remote hosts supporting case-
sensitive user names)

- The same on the remote host but you wish to access the
remote host using another user name

By default, the R commands send all user names in lowercase
letters. If you access a host that supports case-sensitive
user names, and the user name you specify has uppercase
letters, you may use the /NOLOWERCASE qualifier to maintain
these letters as uppercase, or you can specify the /USER_NAME
qualifier with the user name in quotes.

The remote host must also know your password or know you as a
trusted user on your local system:

o Accessing remote hosts by providing your password:

- Certain systems have case-sensitive passwords. To send your
lowercase or mixed-case password to these hosts, enclose it
in quotation marks ( " " ).

- On systems that are not case-sensitive, you do not need to
enclose your password in quotation marks ( " " ).

- You can specify the password on the command line:

$ RSH WOODS /PASSWORD="Downy" LS

Or, you can specify the password at the REXEC prompt:

$ RSH WOODS /PASSWORD LS
REXEC password: (not echoed)

o Accessing remote hosts as a trusted user:

Most systems use certain authentication files or proxy
accounts that allow trusted users on trusted hosts to access
the system by specifying only the user name they wish to
use. To access a host without specifying the corresponding
password, your originating host and user name must have an
entry in these authentication files.

The authentication file entries contain your originating user
name. The R commands convert your originating user name to
lowercase unless you use the /NOLOWERCASE qualifier. You may
have to contact the system manager from the remote system to
determine if the system is case-sensitive and, if so, what
case is used in the authentication files.

NOTES

To use the REXEC feature, you must always use the /PASSWORD
qualifier.

The RLOGIN command does not have the /PASSWORD qualifier.
If you are a trusted user, you are automatically logged in
to the remote system. If you are not a trusted user, REXEC
prompts you to enter a user name and password on the remote
system.

4 Quotation_Marks

Use quotation marks (" ") for UNIX host path names that include
slashes (/), such as user/simms/offers, and for host/file
specifications that include the username@ syntax.

If the remote host uses case-sensitive user names and passwords,
use quotation marks in the following situations:

o User names and passwords are mixed case.

o Passwords are lowercase.

o User names are uppercase, unless you use the /NOLOWERCASE
qualifier.

4 Examples

The following examples show how to provide account and password
information for the R commands.

1. OpenVMS user STALLINGS accesses the file accnts on UNIX host
ufemism as user stallings and copies the file to the current
directory on the OpenVMS system. Because /LOWERCASE is the
default, the /LOWERCASE and /USER_NAME=stallings qualifiers
are not needed. In this example, the user is a trusted user.

$ RCP UFEMISM:ACCNTS [] <Return>
$

2. From OpenVMS, STALLINGS accesses the superuser account cris
on ufemism. Because /LOWERCASE is the default, the /LOWERCASE
and /USER_NAME=stallings qualifiers are not needed. In this
example, the user is a trusted user.

$ RLOGIN /USER_NAME=CRIS UFEMISM <Return>
Welcome to UNIX system ufemism.
.
.
.
ufemism%

3. User FINCH has the same uppercase name for both an OpenVMS
account and a UNIX account. For RSH to send the uppercase
OpenVMS account name to remote host ufemism in uppercase,
FINCH uses the /NOLOWERCASE qualifier. In this example, the
user is a trusted user.

$ RSH /NOLOWERCASE UFEMISM CAT -N GRANTS

4. User BACH has the the account bach on the UNIX host classics.
To invoke the REXEC feature, BACH specifies the password on
host classics. Note that the password MagNificat is enclosed
in quotes to prevent RSH from sending it all uppercase.

$ RSH /PASSWORD="MagNificat" CLASSICS LS <Return>

3 Qualifiers
You can specify R command qualifiers in either of two ways:

o Type the qualifiers on the command line.

$ RCP /LOG TRANQUIL:VULTURES []
$ RSH /EIGHTBIT /ESCAPE_CHAR="+" /TRUNCATE HERON CAT -N STREAMS

o Add the same information to your LOGIN.COM file, for example:

$ ! To customize my R commands:
$ !
$ RCP :== RCP /LOG
$ RLOGIN :== RLOGIN /EIGHTBIT /ESCAPE_CHAR="+" /TRUNCATE_USER_NAME
$ RSH :== RSH /EIGHTBIT /ESCAPE_CHAR="+" /TRUNCATE_USER_NAME
$ !

3 RCP_(Remote_Copy)
The RCP command copies a file between your local host and a
remote internet host. You can also use RCP to copy a file between
two remote internet hosts. You specify the source and destination
file names, each in the format appropriate for the source or
destination system. For copying files from one remote host to
another:

o If you do not have proxy login accounts (or authentication
file entries) for both the source and remote hosts, you
must have the same user name and password on both source
and destination hosts. Use the /PASSWORD qualifier and,
if necessary, the /USER_NAME qualifier, to specify the
authentication information for the remote hosts.

o If you have a proxy login account (or authentication file
entry) on one of the remote hosts only, use the /PASSWORD
qualifier and, if necessary, the /USER_NAME qualifier to
specify the authentication information for the other host.

By using the /RECURSIVE qualifier with the RCP command, you can
recursively copy every file and subdirectory in a directory.

Beginning with OpenVMS Version 6.2, you can also use the COPY
/RCP command to copy files across the network using TCP/IP. For
more information on this command, type HELP COPY/RCP at the DCL
prompt.

Note that you can also use FTP to transfer files.

4 Example_RCP_Commands

The following examples show how to use RCP commands to copy files
from one host to another host.

1. User BEST has the account best on the UNIX host haven. User
BEST's password for that account is IMusici, which must be
enclosed in quotation marks because it is mixed case. The
following command copies the file /symph/nine on haven to
the local directory on the OpenVMS system (the UNIX file
specification must be enclosed in quotation marks, also):

$ RCP /PASSWORD="IMusici" "haven:/symph/nine" []<Return>

2. User BEST has a proxy account on the remote UNIX host musicx.
The following command copies the file /symph/pastoral from
host musicx to the directory [SYMPH6] on the device DKA300: on
BEST's local OpenVMS system:

$ RCP "musicx:/symph/pastoral" ":DKA300:[SYMPH6]" <Return>

3. With this command, user BEST copies each subtree rooted at
the /symph directory to the directory [SYMPHS] on the device
DKA300: on BEST's local OpenVMS system.

$ RCP/RECURSIVE "haven:/symph" ":DKA300:[SYMPHS]" <Return>

4. With the following command, user BEST copies all files
from the directory /symphonies on remote host musicx to the
directory /symph on remote host haven:

$ RCP /PASSWORD="IMusici" "musicx:/symphonies/*" "haven:/symph/*" <Return>

5. In the following example, user BEST uses the DCL COPY/RCP
command to transfer the complete subdirectory tree /symph from
remote UNIX host haven to remote OpenVMS host FRAM, which both
require specification of a password. (With the RCP command,
when transferring files between two remote hosts, you need a
proxy account or an entry in the authentication file for at
least one of the two remote hosts.) User BEST has an account
under the same name on both hosts.

$ COPY/RCP haven"BEST IMusici"::"/symph/*" <Return>
To: FRAM"VAUGHN MYLES"::[classic.compositions]*"

3 RLOGIN_(Remote_Login)
The RLOGIN command connects your terminal to the remote host you
specify and requests a login. If the remote host has an entry
in its authentication files for your host and user name, it may
bypass its login and password prompts.

Note that you can also use TELNET to log into remote internet
hosts.

4 Logging_Out

End your remote login session in either of two ways:

o Log out from the remote host.

o On a new line, enter the escape character and a period.

The default escape character is a tilde ( ~ ). To set another
escape character, use the /ESCAPE_CHARACTER qualifier on the
RLOGIN command line.

4 Example_RLOGIN_Sessions

The following examples show how to use the RLOGIN command.

1. The following command logs in to node CONDO:

$ RLOGIN CONDO <Return>

OpenVMS Version 6.1 -- Unauthorized access is prohibited.
Username: KING <Return>
Password: (not echoed) <Return>

$ RUN ...

$ ~. (not echoed)

%RSH-S-LCLCLOSED, Local connection closed
$

2. The following command logs in to host petrel and sets the
character used to close the RLOGIN session:

$ RLOGIN /ESCAPE_CHARACTER="+" PETREL <Return>

.
.
.
Last login: Mon Mar 14 18:34:27 from phoebe.edu
UNIX System petrel: Fri Mar 19 11:02:20 EST 1997
Mon Jun 28 18:44:42 EST 1997

% ls ... <Return>
% +. (not echoed)

%RSH-S-LCLCLOSED, Local connection closed
$

3 RSH_(Remote_Shell)
The RSH command connects your terminal to a remote host and
requests it to execute the command, script, or command procedure
that you specify. If the command generates output, you see it as
if it were produced locally. If you omit a remote command when
you type an RSH command line, RSH initiates an RLOGIN session.
However, if the command line includes /PASSWORD, the remote login
attempt fails. Using the /PASSWORD qualifier invokes REXEC.

Syntax rules require that you type your RSH command line so that
the remote command is the last word (or phrase).

4 Quotation_Marks

If the remote command is one or more lowercase words, you do not
need to enclose them in double quotation marks on the RSH command
line. However, double quotation marks ( " " ) are required for:

o UNIX commands that are mixed-case characters.

o UNIX commands that are uppercase characters.

In addition, RSH handles one double quotation mark ( " ) and two
consecutive double quotation marks ( "" ) as follows:

o If you input one double quotation mark in a command line, RSH
strips it.

o If you type two consecutive double quotation marks on the
command line, RSH strips the first quotation mark and leaves
the second.

o If you surround text with a set of double quotation marks on
the RSH command line, RSH disables the default conversion of
characters to lowercase, and strips the quotation marks.

4 Interrupting_Commands

To stop a remote execution, enter either Ctrl/C or Ctrl/Y.

4 Example_RSH_Commands

The following examples show how to use the RSH command.

1. In this example, the remote system manager previously created
an entry in the authentication files for remote user STAN on
host oster giving STAN permission to access user rolly.

From the local OpenVMS host, user STAN views rolly's
directory, which resides on UNIX system oster. No quotes are
required around the user name and host name because RSH by
default sends them in lowercase.

$ RSH /USER_NAME=ROLLY OSTER LS

2. On the following RSH command line, the uppercase UNIX
qualifier -R is typed within quotation marks to preserve the
uppercase R. This example assumes that the user's originating
host and user name are in the authentication files on the
remote host debts.

$ RSH DEBTS LS "-R"

3. The following commands show how RSH sends quotation marks to
a remote UNIX host and how quotation marks affect case. All
examples assume that the user's originating host and user name
are in the authentication files on the remote host.

$ RSH DEBTS ECHO TEST MESSAGE
test message

$ RSH DEBTS ECHO "\""test\"" message"
"test" message

$ RSH DEBTS ECHO TEST MESSAGE
test message

$ RSH DEBTS ECHO "TEST" MESSAGE
TEST message

$ RSH DEBTS "echo '""test"" message'"
"test" message

4. Because no remote command is specified on the RSH command
line, DIGITAL TCP/IP Services for OpenVMS executes RLOGIN.

$ RSH TANNER <Return>

Password: (not echoed)<Return>

Last login: Wed Aug 24 07:14:28 from henson.pension.daily.com
Digital UNIX Mon Aug 29 17:27:15 EDT 1997

Daily Corporation

today>

5. In this example, the OpenVMS system manager of WR2 previously
created an entry in the authentication files for remote user
SIMMS on host WR1.

From OpenVMS host WR1, user SIMMS types the DIRECTORY command
to execute at WR2.

$ RSH WR2 DIRECTORY

6. In this example, the OpenVMS system manager of WR2 previously
created an entry in the authentication files for remote user
SIMMS on host WR1 allowing SIMMS access to the user name
ROGERS.

User SIMMS issues the DIRECTORY command from WR1 to execute at
WR2 in user account ROGERS.

$ RSH WR2 /USER=ROGERS DIRECTORY

3 REXEC_Feature
Use the REXEC feature to send a command to execute on a remote
host that does not have, or might not have, the authentication
information that RSH requires. The remote system's authentication
files are not used.

Along with the remote command, REXEC sends the password you
specify on the command line to the remote host. This password
is used for security checking.

The Remote Shell program invokes REXEC. To use REXEC, issue
RSH /PASSWORD.

4 Example_REXEC_Use

The following example shows how to provide password information
for the RSH command, thereby invoking the REXEC feature on the
remote host.

From host GRANT, user STANTON types the file tops.holdings that
resides on UNIX host oster. Because STANTON is not listed in
oster's authentication files, user STANTON must use the REXEC
feature and supply the /USER_NAME and /PASSWORD qualifiers.
Quotes are required around the password because it contains
uppercase letters.

$ RSH OSTER /USER_NAME=STANTON /PASSWORD="KeepingSaneJoy" -
_$ CAT TOPS.HOLDINGS

2 Network_Terminals
With the TELNET software in DIGITAL TCP/IP Services for OpenVMS
(UCX), you can log in to a remote internet system. This is
called establishing a TELNET session. Your terminal appears to be
attached directly to the remote system. Using the TN3270 command,
you can run a TELNET session with a host that uses IBM 3270 model
terminals.

Note that you can also use RLOGIN to log into remote internet
hosts.

3 Commands
Use the following rules when you type a TELNET command line.

o Command formats

With the TELNET command and most of the commands at the TELNET
prompt, you can use either DCL-style or UNIX-style syntax. For
example, the following two commands produce the same results:

$ TELNET
TELNET> SHOW PARAMETERS

$ TELNET
TELNET> DISPLAY

o Quotation marks

No quotation marks are required for typing:

o The TELNET command line, for example:

$ TELNET CENTRAL

o The TN3270 command line, for example:

$ TN3270 CENTRAL

o Commands at the TELNET prompt, for example:

TELNET> CONNECT CENTRAL

The following example connects to UNIX host migain and
sets a terminal type with the /TERMINAL_TYPE qualifier. No
quotation marks are needed to pass a terminal type to migain
in lowercase, as demonstrated with the remote host's printenv
command.

$ TELNET MIGAIN /TERMINAL_TYPE=vt300
%TELNET-I-Trying, Trying ...11.90.208.56
%TELNET-I-SESSION, Session 01, host migain, port 23
-TELNET-I-Escape, Escape character is '^]'

Hello from UNIX host migain

TERM=vt300
HOME=/
SHELL=/bin/csh
USER=root
PATH=/bin:/usr/bin:/usr/ucb:/etc:/usr/etc:.
LOGNAME=root
PWD=/
migain#

3 Starting
You can start a TELNET or TN3270 session with a remote host (also
called establishing a connection and opening a connection) in one
of the following ways:

o At the DCL prompt, issue either the TELNET or TN3270 command
and specify a remote host.

o At the DCL prompt, issue the TELNET or TN3270 command with no
parameters. At the TELNET or TN3270 prompt that appears, issue
the CONNECT or open command, specifying a remote host.

o Invoke and use TELNET or TN3270 from a command procedure.

The following example shows three ways to establish a connection
interactively:

$ TELNET CENTRAL /TERMINAL_TYPE=IBM-3278-2

$ TELNET
TELNET> CONNECT CENTRAL 23 VT200

$ TN3270 CENTRAL /TERMINAL_TYPE=IBM-3278-3

You can invoke TELNET or TN3270 and, without connecting to a
remote host first, enter certain commands that customize the
sessions and display parameters or status.

3 Exiting
You can end a TELNET or TN3270 session (close the connection) in
one of the following ways:

o At the remote host's system prompt, log out.

o At the remote host's system prompt, return to the TELNET or
TN3270 prompt and disconnect the session, as follows:

1. At the remote host's system prompt, press the TELNET/TN3270
escape character (Ctrl/] is the default).

2. At the TELNET or TN3270 prompt, issue either DISCONNECT or
close.

The following example shows two ways to close connections:

% logout
%TELNET-S-REMCLOSED, Remote connection closed
TELNET> EXIT
$

% <Ctrl/]>
TELNET> DISCONNECT
%TELNET-S-REMCLOSED, Remote connection closed
TELNET> EXIT
$

3 Logging_Sessions
To keep a log of your TELNET session, use the /LOG_FILE
qualifier. (You cannot use this qualifier with a TN3270 session.)

The following example establishes a TELNET connection to node
central, sets the terminal type to VT200, and logs all session
output to the file CENT.LOG in your current directory.

$ TELNET/LOG_FILE=CENT.LOG/TERMINAL_TYPE=VT200 CENTRAL

3 Command_Procedures
With DCL command files, you can start TELNET and TN3270 sessions
(see Starting TELNET/TN3270) and customize the TELNET/TN3270
environment (see Initialization Command Files).

4 Starting_TELNET/TN3270

You can create a command procedure containing the DCL DEFINE and
TELNET (or TN3270) commands.

The following example shows an example of a TELNET command
procedure.

$! My TELNET startup command file, START_TELNET.COM.
$!
$! This command procedure establishes a TELNET session
$! with UNIX host central.
$!
$ DEFINE /USER_MODE SYS$INPUT TT:
$ TELNET CENTRAL

4 Initialization_Command_Files

Initialization command files can customize your TELNET/TN3270
sessions with SET, ENABLE, and DISABLE commands. These command
files:

o Are optional. They eliminate the need to issue individual
TELNET commands.

o Have the following requirements:

- Location: Your login directory

- Name: TELNETINIT.INI

- Format: one command per line

o Run automatically when you invoke TELNET or TN3270.

The following example shows a TELNET initialization command
procedure.

! This file, TELNETINIT.INI, sets my TELNET parameters
! the way I like them.
!
DISABLE AUTOFLUSH
ENABLE BINARY
ENABLE DEBUG
SET DEVICE /TERMINAL=VT300
SET ESCAPE "^p"

3 Toggling_Between_Remote_and_Local
During a session with a remote host, you can toggle back and
forth between the local TELNET or TN3270 process and the
connected host. For example, at the TELNET prompt, you might
want to display status, modify a TELNET parameter, or spawn a DCL
subprocess.

o To return to the local TELNET or TN3270 prompt (TELNET command
mode), type the TELNET escape sequence (the default is Ctrl/])
at the remote host's prompt (TELNET input mode).

o To resume your session with the remote host, type one of the
following at the TELNET (or TN3270) prompt.

TELNET> <Return>

TELNET> RESUME

TELNET> RESUME n

where n is the number of the session to which you want to
return.

o To change the default escape sequence, type the following at
the TELNET (or TN3270) prompt:

TELNET> SET ESCAPE escape_character

4 Examples

The following example toggles between remote UNIX host biway and
the local OpenVMS system.

biway> <Ctrl/]>
TELNET> SHOW STATUS

Session 1 Active Host BIWAY
Operating Mode:
Character-at-a-time
Escape character: '^]'
Options:
.
.
.
TELNET> <Return>
biway>

In the next example, user BENTLEY, working at OpenVMS node EAGLE,
uses TELNET to do the following:

1. Establish a connection to UNIX host fern.

2. Return to the local TELNET prompt.

3. Display status.

4. Establish a connection to host gannet.

5. Return to the TELNET prompt.

6. Display status.

7. Connect to sands. But, sands closes the connection because
BENTLEY mistypes the password three times.

8. Try to resume the session with gannet. However, RESUME without
specifying a session number fails:

- With multiple sessions, RESUME's default is the "active"
session, the one with the most recently opened connection.

- The most recent host to which BENTLEY connected is sands.
However, due to BENTLEY's mistyping of the password during
login, sands closed the TELNET connection. Thus, TELNET
displays "No current session."

- Because no connection is "active" (or "current"), BENTLEY
must specify a session number on the RESUME command line.

$ TELNET FERN
.
.
.
fern> <Ctrl/]>

TELNET> SHOW STATUS
Session 1 Active Host FERN
.
.
.
TELNET> CONNECT GANNET
.
.
.
gannet> <Ctrl/]>

TELNET> SHOW STATUS
Session 2 Active Host GANNET
Operating Mode: Character-at-a-time
Escape character: '^]'
.
.
.
Session 1 Waiting Host FERN

TELNET> CONNECT SANDS
%TELNET-I-Trying, Trying...11.18.222.95
%TELNET-I-SESSION, Session 03, host sands, port 23
-TELNET-I-Escape, Escape character is '^]'.
.
.
.
Sun Microsystems, Inc. UNIX System sands - Authorized Access Only

Username: BENTLEY
Password:
User authorization failure
Username: BENTLEY
Password:
User authorization failure
Username: BENTLEY
Password:
User authorization failure

Remote connection closed

TELNET> RESUME
No current session
TELNET> SHOW STATUS

Session 1 Waiting Host FERN
Session 2 Waiting Host GANNET
.
.
.
TELNET> RESUME 2

gannet> <Ctrl/]>
TELNET> SHOW STATUS
Session 2 Active Host GANNET
Operating Mode: Character-at-a-time
Escape character: '^]'
.
.
.
Session 1 Waiting Host FERN
TELNET>

3 Suspending_TELNET
While using TELNET, you can use the SPAWN command to suspend
your current session and create a subprocess at the local DCL
prompt. At the DCL prompt, you can then enter any number of DCL
commands. To return to your suspended TELNET session (exiting
the DCL subprocess), enter the LOGOUT command. In the following
example, the user suspends the TELNET session to list the files
in the working directory on the local host and deletes one of the
files in that directory.

TELNET> SPAWN
$ DIR
.
.
.
$ DEL TR3.TXT:*

3 Multiple_Sessions
TELNET supports:

o Multiple simultaneous connections

o Up to 10 simultaneous sessions

o Only one session at a time if it uses TN3270

The TELNET SHOW STATUS command helps you keep track of multiple
sessions. The SHOW STATUS display uses the terms shown in the
following table:

Term Meaning

Active host Host from which you typed the escape sequence to
return to the TELNET prompt.
Current If you log out of the active host at its system
session prompt, or issue the TELNET DISCONNECT command,
no current session exists.

To resume a connection, even if only one exists,
issue:

TELNET> RESUME n
Waiting hosts Other hosts with whom you have open sessions,
numbered in the order that you connected to them.

To resume a connection with a waiting host, even
if only one exists, issue:

TELNET> RESUME n

To open another TELNET connection:

1. At the system prompt of the remote host, press the TELNET
escape sequence (default is Ctrl/]).

2. TELNET returns to the TELNET prompt.

3. Start another session by issuing the CONNECT command.

The following example starts multiple sessions with UNIX hosts
finder and keeper.

$ TELNET FINDER /TERMINAL_TYPE=IBM-3278-2
.
.
.
finder>
.
.
.
finder> <Ctrl/]>
TELNET> CONNECT KEEPER
.
.
.
keeper>
.
.
.
keeper> <Ctrl/]>
TELNET>

4 Toggling_Sessions

To toggle from one open TELNET connection to another:

1. Type the TELNET escape sequence.

2. If necessary, issue SHOW STATUS to check the number of your
session with the other host.

3. Issue the TELNET RESUME n command, where n is the number of
the session to which you want to return.

4 Session_Information

To display a list of your active sessions, use the SHOW SESSION
command:

TELNET> SHOW SESSION <Return>
Session 01, host finder, port 23
Session 02, host keeper, port 23 (default active session)

If there are no active connections, the SHOW SESSION command
displays the following message:

%TELNET-E-NOSESSION, No active session

3 Customizing_TELNET/TN3270
To customize the TELNET/TN3270 processing environment, issue
ENABLE, DISABLE, and SET commands. You can modify how TELNET and
TN3270:

o Send and receives transmissions

o Display processing on your terminal

o Interpret certain control characters

You can redefine the following control characters, such as
when your terminal or the remote host does not recognize the
corresponding default control character.

o Echo

o Erase

o Escape

o Flush output

o Interrupt

o Kill

o Quit

Use the SET command to redefine these characters. For example,
the following command defines the interrupt character to be the
letter a or A.

TELNET> SET INTERRUPT "^a"

TN3270 allows you to redefine your keyboard. You can redefine
most IBM 3270 model functions and all emulated functions and
characters. You can create a key definition file with DEFINE/KEY
statements to redefine the keyboard. Or, you can redefine a key
interactively, using the DEF KEY function (Ctrl/K on VT100- and
VT200-series terminals).

You can determine the mode TELNET uses to transmit data. The
appropriate TELNET mode for a session depends on:

o The remote host to which you are connecting

o The applications you use

The following table shows the modes that control TELNET
communications.

Mode Function

Local Characters The local host interprets control characters,
Mode translating them into TELNET protocol sequences
(ENABLE LOCAL_CHARS). Use this mode when the
local and remote hosts implement different
control characters. By default, characters are
interpreted by the remote host (DISABLE LOCAL_
CHARS).
Binary Mode The local host sends transmissions in binary
mode (ENABLE BINARY). Use this mode when the
remote host expects each line of data to end
with a carriage return/line feed combination.
By default, the local host sends transmissions
with the end-of-line character (EOL) mapped
to the carriage return/line feed combination
(DISABLE BINARY).
Debug Mode TELNET displays data flow in both hexadecimal
and readable text (ENABLE DEBUG). By default,
TELNET displays data in readable text only
(DISABLE DEBUG).
Character TELNET transmits data one character at a time
Transmission (SET MODE CHAR) rather than line-by-line. Use
Mode this mode when you run a text editor (on the
remote host) that does character processing.
Character transmission mode is the default.
Line TELNET transmits data one line at a time (SET
Transmission MODE LINE). Most clients send a character at a
Mode time. The remote host server must support line
transmission mode.

This allows you to do signal trapping as well
as local character editing and tab expansion.

3 SEND_Commands
While in input mode (an active session with a remote host), you
can enter SEND commands that affect the remote host's processing
of commands you have entered. You use these commands when the
remote host does not recognize the default key or key sequence
used for the same operation. You can use the SEND AYT and SEND
NOP commands to determine if your session with the remote host
is still open. The following table lists the function you can
perform at the remote host with each SEND command.

Table 1-1 Sending Commands to the Remote Host

Function Command When to Use

Abort output of SEND AO You want to terminate output
the last remote but not the execution of the
command you process.
entered, without After already aborting output,
discontinuing you want to resume output. The
execution of the remote host does not recognize
process. the Ctrl/O as the flush output
character.
Determine if your SEND AYT Test the connection to the
connection with remote host application and
the remote host is verify that the remote host
still established, application is responding. You
the remote host are notified on success.
replying with
connection status
information.
Terminate execution SEND BRK The remote host does not
of the last command recognize the Ctrl/C sequence
you entered at the as an interrupt character.
remote host.
Delete the last SEND EC The remote host does not
character you typed recognize your Delete key.
at the remote host.
Delete the last SEND EL The remote host does not
line of text you recognize your Delete key or
entered at the command-line recall.
remote host.
Signal the remote SEND GA The application requires GA
host that your commands in either one or both
local system is directions.
ready.
Interrupt execution SEND IP Your terminal or the remote
of the last command host does not recognize the
you entered at the default interrupt character
remote host. (Ctrl/C).
Determine whether SEND NOP Check the communication path
your local host can to the remote host; you are
send data to the notified on error.
connected remote
host and whether
the remote host can
receive that data
Interrupt the SEND SYNCH You want to clear immediately
current process the communications path between
you are executing your system and the remote
at the remote host, host, with the remote host
and in urgent mode ignoring any incoming data not
(out-of-band), yet processed.
get a quicker
response time to
the interrupt.

3 IBM_Terminal_Emulation
You can run a TELNET session with a host that uses IBM 3270 model
terminals by using the TN3270 command. The TN3270 command:

o Provides IBM 3270 Information Display System (IDS) terminal
emulation.

o Assigns IBM 3270 functions to your DIGITAL keyboard.

o Assigns IDS functions to specific keys.

During a TN3270 session, you can:

- Redefine keys interactively (DEF KEY Function ).

- Redefine keys permanently (Key Definition File).

- Record your sessions (Recording Sessions).

- Troubleshoot problems (Problem Solving).

NOTE

When you run TN3270, you can only have one session. You
cannot have other sessions running simultaneously, as you
can when running normal TELNET sessions.

4 Supported_IBM_Terminal_Models

The following table lists the IBM 3270 model terminals that
TELNET can emulate.

Model Screen Size (Rows x Columns)

IBM 3278 Model 2 24 x 80
IBM 3278 Model 3 32 x 80
IBM 3278 Model 4 43 x 80
IBM 3278 Model 5 27 x 132

4 Setting_Up_Your_PC_or_Terminal

When you use TELNET and specify IBM 3270 model terminal emulation
(TN3270), the image displayed on your screen depends on:

o The type of DIGITAL terminal you use, or that your PC is
emulating.

o The features you set on it.

5 VT200-Series_Terminal_Setup_

Follow these steps:

1. At the Set-up Directory menu, select the keyboard type that
corresponds to the keyboard layout you are using (for example,
North American).

2. At the Display Set-up menu, select the following:

o Interpret controls

o Light text, dark screen

o Cursor (visible)

3. At the General Set-up menu, select the following:

o VT200 or VT100 mode (if VT100 mode, set VT100 ID)

o 7-bit or 8-bit controls

o Multinational/national

o Normal cursor keys

o No new line

4. At the Communications Set-up menu, select the following:

o XOFF at 64 or XOFF at 128

o 8-bit communication line

o 8-bit (any) parity

o No local echo

5. At the Keyboard Set-up menu, select warning bell ON.

At the DCL prompt, issue:

$ SET TERMINAL /INQUIRE

The software determines the terminal's characteristics and sets
the appropriate parameters.

If you select National Character mode, issue:

$ SET TERMINAL /NOEIGHTBIT

5 VT100-Series_Terminal_Setup_

Follow these steps:

1. Set your terminal to ANSI mode (see the user's guide for your
terminal).

2. Enter the following command at the DCL prompt:

$ SET TERMINAL/INQUIRE

This command causes the terminal to be questioned about its
characteristics. The appropriate parameters for the terminal
are set up according to its response.

TN3270 requires DIGITAL terminals or DECterm windows that support
at least 24 lines and 80 columns.

4 Starting_and_Exiting

Start a TN3270 session by using the TN3270 command. You can also
use the TELNET/TERMINAL_TYPE=IBM-3278-n command. The default
terminal type is IBM-3278-2. The following examples show several
ways to start a TN3270 session, using the TN3270 command and
connecting to host CENTRAL.

o Using the default terminal type:

$ TN3270 CENTRAL

o Using a terminal type other than the default:

$ TN3270/TERMINAL_TYPE=IBM-3278-4 CENTRAL

You can invoke TN3270 and, without connecting to a remote host
first, enter certain commands that customize the sessions and
display parameters or status. You can also use a command file to
invoke TN3270 and the customization.

The TN3270 command includes several qualifiers that allow you to
specify customized or special files for the following:

o Character set translation tables file (/CHARACTER_SET=file)
that translates between EBCDIC and the DIGITAL Multinational
Character Set. The default file, if set up by your system
manager, is SYS$LIBRARY:UCXTEDEF.TBL. If this file does not
exist, and you do not specify a file, TN3270 uses its own
translation table.

o Keyboard definition file (/KEY_DEFINITIONS=file) that you
create as an alternative to the default keyboard layout.

o National Replacement Character Set (NRCS) file (/NATIONAL_
CHARACTERS=n) for which your DIGITAL terminal is configured.
The default for 8-bit terminals is MULTINATIONAL. The default
for 7-bit terminals is US_ASCII.

You can end a TN3270 session (close the connection) in one of the
following ways:

o At the remote host's system prompt, log out.

o At the remote host's system prompt, return to the TN3270
prompt and disconnect the session, as follows:

1. At the remote host's system prompt, press the TN3270 escape
character (Ctrl/] is the default).

2. At the TN3270 prompt, issue either DISCONNECT or close.

4 Getting_Status

To monitor your TN3270 session, use the status line indicator
at the bottom of your screen. A reverse-video strip displays
status and information messages. To see status messages, issue
the following:

TELNET> ENABLE STATUS

4 Clearing_Error_Messages

TN3270 displays error messages in a bordered display at the
bottom of your screen. This display overwrites the status display
and remains visible until you clear it. To clear, invoke one of
the following functions:

o REFR

o HELP

o SET FIL

o DEF KEY

4 Recording_Sessions

During a TN3270 session, you can record your screen's contents.
The PRINT function directs your screen's contents to either a
file or a spooled printer.

To record your screen's contents, follow these steps:

1. Invoke the PRINT keyboard function, as explained in the topic
Keyboard_Functions.

The screen display is recorded in a file in a compressed
state. Null lines (lines with only nulls and attribute
characters) do not appear.

2. Invoke the ENTER function or any function that transmits the
screen contents to the remote host's application, as explained
in the topic Keyboard_Functions.

This creates the default output file, UCXTPRINT.LIS. TELNET does
the following:

o Each time you start a TELNET session that runs TN3270, TELNET
opens a new UCXTPRINT.LIS file.

o Each time you use PRINT during a session, TELNET appends new
output from the screen to the end of UCXTPRINT.LIS.

o Each time you use PRINT, if you direct the output to a
printer, TELNET creates a separate entry in the print queue.

o If the printer is spooled, TELNET immediately prints the
output.

You can specify a different file name. To change the name, use
one of the following two methods:

o When you start a TN3270 session, use the /PRINTER qualifier.
Issue:

$ TN3270 [ host ] /PRINTER=file

o During a TN3270 session, follow these steps:

1. Use the SET FIL keyboard function, as explained in the
topic Keyboard_Functions.

2. At the prompt for a new file name, type a name.

If you specify the same name that is already in use,
subsequent PRINT operations direct output to a new version
of the same file.

3. Use the NEW LINE keyboard function, as explained in the
topic Keyboard_Functions.

4 Online_Help

Online help during a TN3270 session displays:

o A picture of the keypad

o A list of TN3270 keyboard functions

o The key combinations that invoke the TN3270 keyboard functions

The Help screen shows the TN3270 functions as they correspond to
the keys on your physical keyboard:

o Top-row keys

o Editing keypad

o Application keypad

o Up to 32 control or extended character definitions

o All your definitions and changes, including those you make
interactively

To see the Help screen, use the HELP function which is key F15.

4 Locked_Keyboards

If your keyboard locks, the terminal bell rings, and the status
line displays:

Inhib

To unlock the keyboard, press the following key to invoke the
RESET function (KP0 refers to the 0 key in the application keypad
on the righthand side of the keyboard):

<KP0>

Do not use the following functions when the cursor is in a
protected field (a field that does not accept user input):

o DELETE

o DUP

o ER EOF

o FM

o Any graphic character

4 Keyboard_Functions

The following options describe the keyboard functions. Preceding
each function description are the key sequences for VT100 and
VT200 terminals and the function name to use in a DEFINE/KEY
command. In many of the key sequences, TN3270 allows use of the
extended function (EXT) feature. Used in conjunction with another
key, EXT allows access to an extended function for that key. The
extended function feature is described below in more detail.

5 ATTACH

VT100: EXT + E VT200: EXT + Find
DEFINE_KEY Function: ATTACH

Changes control from one subprocess to another subprocess or to
the parent process. When you invoke the ATTACH function, TN3270
uses the name of the last process to which you attached as the
default process name.

If you wish to attach to a different process, press Ctrl/U to
erase the default process name. You can then enter the process
name of your choice at the prompt. The process name can be a
quoted string. Use the quotation marks to preserve spaces, tabs,
or lowercase letters in strings.

5 ATTN

VT100: EXT + A VT200: F19
DEFINE_KEY Function: ATTENTION

Provides a way to "get the attention of" the remote application
program that you are running by sending a SIGNAL RU command
to the remote host. See the user's guide of the particular
application program to learn what response the program gives
when you use this key.

5 Back_Tab

VT100: BACKSPACE VT200: F12
DEFINE_KEY Function: BACK_TAB

Moves the cursor, depending on the type of screen. On a formatted
screen, the cursor moves one of these ways, depending on the
location when you press this key:

o If the cursor is in a field, but not at the first position of
the field, it moves to the beginning of the unprotected field
that it is in.

o If the cursor is in the first position of a field, it moves
to the beginning of the preceding unprotected field. If the
cursor is in the first position of the first unprotected
field, the cursor moves to the first position of the last
unprotected field on the screen.

On an unformatted screen, the cursor returns to the first
position on the screen.

5 Cent_Sign

VT100: EXT + C VT200: EXT + C
DEFINE_KEY Function: (None)

Enters a cent sign. If your terminal does not have this
character, your screen displays a hyphen ( - ).

5 CLEAR

VT100: EXT + Enter VT200: EXT + F20
DEFINE_KEY Function: CLEAR

Clears the screen and moves the cursor to the first position
on the screen. When you invoke the CLEAR function, the software
notifies the application program that this function has been
used.

5 DEF_KEY

VT100: Ctrl/K VT200: Ctrl/K
DEFINE_KEY Function: DEFINE_KEY

Lets you interactively define or redefine a key. You get a prompt
for the name of the key to define and for a function you wish to
assign to that key.

5 DELETE

VT100: Delete VT200: <X]
DEFINE_KEY Function: DELETE

Deletes the character at the cursor. The cursor remains where it
is, and the other characters to the right of the cursor in the
same field move one position to the left. The end of the field
fills with blanks. Note that this is not the action normally
associated with the Delete key on DIGITAL terminals.

5 DSP_ATT

VT100: Ctrl/V VT200: EXT + F17
DEFINE_KEY Function: DISPLAY_ATTRIBUTES

Enables and disables the visible attribute mode. This mode of
operation forces display of the attribute characters (that
is, the characters at the start of a field that indicate the
display and data type of that field). In IBM 3270 model terminal
emulation (TN3270), you can use the DSP ATT function to debug
application programs.

5 DUP

VT100: EXT + * VT200: EXT + F12
DEFINE_KEY Function: DUP

Lets you enter a value in the same field in several forms without
needing to repeat the entry for each form.

After entering the data in the field on the first form, use the
DUP function when at the same field on succeeding forms. The
application program makes the necessary translation, filling in
these fields with the same value. For details about the use of
this key, refer to the user's guide of the particular application
program.

Displays an asterisk (*).

5 DV_CNCL

VT100: EXT + U VT200: EXT + Remove
DEFINE_KEY Function: DVCNCL

Cancels the RECORD function. Use the DV CNCL function if you
begin using the RECORD function and then decide you want to stop.
If you want to delete a sequence that has already been recorded
on a PF key, use the RECORD function, press the PF key, and then
use the DV CNCL function.

5 ENTER

VT100: Line Feed + Enter VT200: Do + Enter
DEFINE_KEY Function: ENTER

Sends your input to the remote application program. While this
communication is active, the keyboard locks and Inhib appears
on the status line. Usually the application program releases the
keyboard when it has finished processing your input.

5 ER_EOF

VT100: EXT + KP, VT200: F18
DEFINE_KEY Function: ERASE_EOF

Erases the contents of the current field, from the location of
the cursor to the end of the field. The cursor remains in the
same location.

5 ER_INP

VT100: EXT + KP- VT200: EXT + F18
DEFINE_KEY Function: ERASE_INPUT

On a formatted screen, clears all the data in the unprotected
fields on your screen and moves the cursor to the first position
in the first unprotected field on the screen.

On an unformatted screen, clears all the data and moves the
cursor to the first position on the screen.

You can also use the ER INP function to remove all previously
recorded key sequences by using the RECORD function and then the
ER INP function.

5 EXIT

VT100: Ctrl/Z or F10 VT200: Ctrl/Z or F10
DEFINE_KEY Function: EXIT

Terminates the remote TELNET/TN3270 session. Aborts any exchange
of data in progress between the local and remote hosts. Note that
terminating a session with the IBM host in this way may result in
improper termination of the session. For the appropriate logoff
command string, see the user's guide for the IBM application with
which you are communicating.

5 EXT

VT100: KP. VT200: KP.
DEFINE_KEY Function: EXTEND

Used in conjunction with another key, allows access to an
extended function for that key. First invoke the EXT function
and then press the second key. If you invoke EXT accidentally,
invoking the RESET function cancels the EXT function.

If the status display is enabled when you invoke the EXT
function, the word Extend appears on the status line.

5 FM

VT100: EXT + ; VT200: EXT + F13
DEFINE_KEY Function: FM

Specifies the end of a field on an unformatted screen or the end
of part of an unprotected field on a formatted screen. Refer to
the user's guide of the remote application program for specific
use of this key.

Displays a semicolon ( ; ).

5 HELP

VT100: EXT + H VT200: Help
DEFINE_KEY Function: HELP

Displays online help and an illustration of the TN3270 keyboard.

5 HOME

VT100: EXT + B VT200: F13
DEFINE_KEY Function: HOME

Repositions the cursor to the first position in the first
unprotected field on the screen (that is, to the beginning of
the input area on the screen).

5 Left/Right_Arrows

VT100: Right arrow or VT200: Right arrow or Left arrow
Left arrow
DEFINE_KEY Function: RIGHT, RIGHT_NOWRAP, LEFT, or LEFT_NOWRAP

Moves the cursor horizontally across your screen without changing
data you have already entered. If the cursor is at the:

o End of a line when you use the Right arrow function, the
cursor moves to the start of the next line.

o Beginning of a line when you use the Left arrow function, the
cursor moves to the end of the previous line.

If the screen display you receive is wider than 80 columns,
you can use the Right arrow and Left arrow functions to move
through the display.

If you want the cursor to wrap to the opposite edge of the
display, use one of the following function sequences:

EXT + Right arrow

EXT + Left arrow

5 INSERT

VT100: EXT + PF4 VT200: F14
DEFINE_KEY Function: INSERT_MODE

Enables insert mode. Use insert mode to edit what you typed. If
the status display is enabled, Insert appears.

In insert mode, when you type a character into an unprotected
field, it is displayed to the left of the cursor, moving the
following one position to the right:

o The cursor

o The character at the cursor location

o All the characters to the right of the cursor in the field

You can insert characters into an:

o Unformatted screen

o Unprotected field on a formatted screen until it is full

If you attempt to insert characters after the field is full,
the keyboard locks, the terminal bell rings, and the word Inhib
appears on the status line. If the keyboard locks when you try
to insert characters into a field that looks empty, the field
might have trailing spaces. To erase these spaces, use the ER EOF
function.

To return your screen to the normal mode of entry, use one of the
following keyboard functions:

o RESET

o CLEAR

o ENTER

o Any PA key

o Any PF key

5 Logical_Not

VT100: EXT + N VT200: EXT + N
DEFINE_KEY Function: (None)

Represents the remote host's symbol for a logical NOT; displayed
as a circumflex ( ^ ) on DIGITAL terminals.

5 Logical_Or

VT100: EXT + O VT200: EXT + O
DEFINE_KEY Function: (None)

Represents the remote host's symbol for a logical OR; displayed
as a solid vertical line from the terminal's graphics set. Press
Ext + O if the vertical bar is not available on your keyboard.

5 New_Line

VT100: Return VT200: Return
DEFINE_KEY Function: NEWLINE

Moves the cursor to the first unprotected position on the next
line of your screen. If no unprotected fields are on the screen
when you invoke the new line function, the cursor moves to the
first location on the screen. If the screen has no fields, this
key has the same function as the Return key on DIGITAL terminals.

5 NUM_OVR

VT100: EXT + J VT200: Remove
DEFINE_KEY Function: NUMOVR

Lets you enter nonnumeric characters into numeric fields. Once
you enable this function, use NUM OVR again to disable it. If you
do not disable the numeric lock override, it remains enabled even
after you exit from TN3270. The letter O appears on the status
line to indicate that the numeric lock override is in effect.

5 PA_Keys

VT100: PF4 , KP- , KP, VT200: PF4 , KP- , KP,
DEFINE_KEY Function: PA1-PA3

These program access keys are defined by the program you are
using. These keys request attention from the remote application
program without sending any data. You should refer to the user's
guide of your application program to learn how the PA keys are
defined.

5 PF_Keys

VT100: see below VT200: see below
DEFINE_KEY Function: PF1-PF24

These program function keys are defined by the remote application
program you are using. They request attention from the
application program and send the data entered to the host. The
PF keys are coded by the application program to perform functions
relating to the application. A particular PF key may be coded
differently from one application to another. The user's guide of
the remote application program usually defines the specific PF
key assignments for that application program.

To
Implement
This Press This Key or
Function Key Combination

PF1 PF1
PF2 PF2
PF3 PF3
PF4 KP7
PF5 KP8
PF6 KP9
PF7 KP4
PF8 KP5
PF9 KP6
PF10 KP1
PF11 KP2
PF12 KP3
PF13 EXT + PF1
PF14 EXT + PF2
PF15 EXT + PF3
PF16 EXT + KP7
PF17 EXT + KP8
PF18 EXT + KP9
PF19 EXT + KP4
PF20 EXT + KP5
PF21 EXT + KP6
PF22 EXT + KP1
PF23 EXT + KP2
PF24 EXT + KP3

5 PLAY

VT100: EXT + M VT200: Insert Here
DEFINE_KEY Function: PLAY

Recalls keystroke sequences stored on PF keys using the RECORD
function. Invoke the PLAY function and then press the PF key
on which the desired key sequence is stored. The PLAY function
executes all commands included in the keystroke sequence.

If the HELP utility is invoked in your key sequence, the PLAY
function continues until you exit from the HELP utility. Also,
if you use functions that require you to respond to prompts (such
as ATTACH, DEF KEY, SET FIL, or SPAWN), the information you type
at the prompt is not recorded. When you recall the sequence, the
system prompts you for this information again.

P appears on the status line if the status display is enabled.

5 PRINT

VT100: EXT + P VT200: F11
DEFINE_KEY Function: PRINT

Records the contents of your screen in a file or at a printer.
(This is a local print feature.) If the status display is enabled
when you use the PRINT function, the word Print appears on the
status line. Your screen refreshes when the printing process
completes.

The first use of PRINT in a given run of TN3270 creates a new
version of the output file. Successive uses of PRINT in the same
program cause the screen contents to append to the existing file.
If the output is directed to a printer, each use of PRINT creates
a separate entry in the printer queue. If the printer is a
spooled printer, the output is released for printing immediately.

Use the command qualifier /PRINTER=file to specify where to
direct the output file. The SET FIL function allows you to
change the name of the output file each time you invoke the PRINT
function.

5 RECORD

VT100: EXT + L VT200: EXT + Insert Here
DEFINE_KEY Function: RECORD

Saves a keystroke sequence on a specific PF key. Invoke the
RECORD function with the appropriate key sequence (as described
above), press the PF key as prompted, enter the keystroke
sequence, and then invoke the RECORD function again. You can
save a maximum number of 127 keystrokes on each PF key. If the
status display is enabled when you use the RECORD function, the
letter R appears on the status line.

To recall the keystroke sequence, use the PLAY function. Use
the DV CNCL function to cancel the RECORD function. To erase all
previously recorded key sequences, use the ER INP function.

5 REFR

VT100: Ctrl/W VT200: Ctrl/W or F20
DEFINE_KEY Function: REFRESH

Removes TN3270 error messages, operating system messages, or
other messages that appear on your screen. This key function
deletes extraneous characters from your screen and redisplays the
fields and data that were on the screen before the interruption.

This function does not transmit or receive data from the remote
host. It is a local OpenVMS function.

5 RESET

VT100: KP0 VT200: KP0
DEFINE_KEY Function: RESET

Returns the keyboard to normal input mode from insert mode. Also,
the RESET function returns the keyboard to your control after
it locks when you try to enter data into a protected or a full
field, or when you try to enter the wrong type of data into a
field.

Invoking RESET turns off the Inhib indicator. The cursor remains
where it is and the screen remains unchanged.

5 SELECT

VT100: EXT + K VT200: Select
DEFINE_KEY Function: SELECT

Lets you choose items from a menu, table, or list and then notify
the program of your selection. Use the arrow keys to position
the cursor on the field designator character, then use the SELECT
function. For more information on using SELECT, refer to the
user's guide of the remote application.

5 SET_FIL

VT100: EXT + F or Ctrl/F VT200: EXT + F11
DEFINE_KEY Function: SET_PRINTFILE

Lets you change the name of the file or device that receives
output each time you invoke the PRINT function. After you invoke
SET FIL, you are prompted for the name of a new output device,
emulating the remote host's IDENT function.

Note that if you specify the same name that is already in use,
subsequent PRINT operations direct output to a new version of the
same file.

5 SHO_MSG

VT100: EXT + G VT200: EXT + F14
DEFINE_KEY Function: SHOW_MESSAGE

Displays the broadcast messages that have been posted on a
separate screen. If the status line is enabled, Msg appears on
the status line. If you do not read the messages before they fill
up the screen, the messages begin to scroll up out of view and
you will no longer be able to read them. These broadcast messages
are not saved after you read them or exit TN3270.

5 SPAWN

VT100: EXT + D VT200: Find
DEFINE_KEY Function: SPAWN

Creates a subprocess under the current process. Use the
LOGOUT command to terminate the subprocess. Because a tree of
subprocesses can be established using the SPAWN function, you
must be careful when terminating any process in the tree. When a
process is terminated, all subprocesses below that point in the
tree are terminated automatically.

When you create a subprocess, you can specify an optional
command string. The command string is executed within the created
subprocess and the subprocess terminates upon completion of the
command.

5 STATUS

VT100: EXT + S VT200: F17
DEFINE_KEY Function: STATUS

Lets you enable and disable the display of status information.

When you enable STATUS, the last line on your screen is painted
over with a reverse video strip. This line may conceal remote
host system or application information. If this occurs, Hidden
appears in the status line.

Disable the status display by using the STATUS function again.

5 SYS_REQ

VT100: EXT + R VT200: EXT + F19
DEFINE_KEY Function: SYS_REQUEST

Lets you shift between the application program (the LU-LU
session) and the control program (the SSCP-LU session). If the
status display is enabled, Appl or SSCP appears on the status
line to indicate the type of session. Appl appears when you are
in an LU-LU session and SSCP appears when you are in the SSCP-LU
session.

The screen is refreshed when you use the SYS REQ function.

5 Tab

VT100: Tab VT200: Tab
DEFINE_KEY Function: TAB

Moves the cursor to the first character location of the next
unprotected field on your screen. If the screen has no fields,
the Right arrow | function moves the cursor to the first location
on the screen.

If the cursor is within the last unprotected field on the screen,
the cursor moves to the first position of the first unprotected
field on the screen.

5 Up/Down_Arrows

VT100: Up arrow or Down VT200: Up arrow or Down arrow
arrow
DEFINE_KEY Function: UP, UP_NOWRAP, DOWN, or DOWN_NOWRAP

Moves the cursor vertically on your screen without altering the
data you have already entered.

If the cursor is at the:

o Top of the screen when you press the up arrow, the cursor
appears in the same column at the bottom of the screen

o Bottom of the screen when you press the down arrow, the cursor
appears in the same column at the top of the screen

If the screen display you receive is larger than 24 rows
deep, you can use the Up arrow and the Down arrow keys to
move through the display. These keys scroll the screen display
up or down.

If you want the cursor to wrap to the opposite edge of
the display, use the key sequence EXT + Up arrow or
EXT + Down arrow.

5 Additional_Information

For additional information about TN3270 key functions, see the
following IBM documents:

o IBM 3270 Information Display System, Order No. GA23-0060

o IBM 3270 Information Display System: Operator's Guide, Order
No. GA27-2742

o IBM 3270 Information Display System: 3278 Display Station
Operator's Guide, Order No. GA27-2890-4

4 Redefining_Your_Keyboard

You can reassign the following functions:

o All emulated functions

o Most IBM 3270 model functions

o All emulated alphanumeric and graphic characters

5 Definable_Keys

The keys you can define are:

Location Key Name

Function keys PF1-PF4
(VT100 and
VT200)

Application KP0-KP9
keypad ENTER
(VT100 and MINUS
VT200) COMMA
PERIOD

Top-row F6-F20
function keys HELP (F15)
(VT200) DO (F16)

Editing keypad FIND (E1)
(E1-E6) INSERT_HERE (E2)
(VT200) REMOVE (E3)
SELECT (E4)
PREV_SCREEN (E5)
NEXT_SCREEN (E6)

Cursor keys UP
(VT100 and DOWN
VT200) LEFT
RIGHT

Control keys Ctrl/A-Ctrl/Z, including:
(VT100 and
VT200) Ctrl/H (BS)
Ctrl/I (HT)
Ctrl/J (LF)
Ctrl/M (CR)

Excluding:

Ctrl/Y-Interrupt
Ctrl/C-Cancel/interrupt
Ctrl/O-Output off/on
Ctrl/S-Suspend output
Ctrl/Q-Resume output

5 Nondefinable_Keys

You cannot redefine the following DIGITAL-reserved keys:

o Ctrl/Y - Interrupt

o Ctrl/C - Cancel/interrupt

o Ctrl/O - Output off/on

o Ctrl/S - Suspend output

o Ctrl/Q - Resume output

o F1-F5

5 Redefining_Keys

To redefine a keyboard key, use either of the following methods:

o Create a key definition file, a text file with individual key
definitions in the form of DEFINE/KEY statements and DELETE
/KEY statements.

o Use the DEF KEY function (see DEF KEY Function ).

The following example establishes a TELNET/TN3270 connection
to host JUNCO. By default, the terminal functions as if it were
an IBM-3278-2 model terminal. It uses your customized keyboard
definition file NEW_KEYS.DAT.

$ TN3270 JUNCO /KEY_DEFINITION=NEW_KEYS.DAT

5 Key_Definition_File

Use the DEFINE/KEY and DELETE/KEY statements to create your own
key definition file as described in the following sections.

The DEFINE/KEY statement assigns a new function to a particular
key. Its format is:

DEFINE/KEY [/STATE=EXTEND] key_name function

/STATE Optional. Default: non-extend mode.
Redefines the key in extend mode.
key_name Standard key name on the DIGITAL terminal.
function TN3270 function you want mapped to this key.

You can define most of the named keys both in normal (non-extend)
mode and in extend mode.

You can define the control keys (and the synonyms for them) only
in normal mode. Do not specify the qualifier /STATE=EXTEND.

The following example assigns the EXIT function to the key
sequence EXT + Z :

DEFINE/KEY/STATE=EXTEND "Z" EXIT

The DELETE/KEY statement removes the function assigned to a
particular key. Its format is:

DELETE/KEY [/STATE=EXTEND] key_name

/STATE Optional. Default: nonextend mode. Deletes the key
in extend mode.
key_name Standard key name on the DIGITAL terminal.

Example:

The following example removes the default value of EXIT from
Ctrl/Z.

DELETE/KEY <Ctrl/Z>

5 DEF_KEY_Function_

Use the DEF KEY function to define or redefine a key
interactively. Your new definition exists until you log out from
the remote host or disconnect from it.

When you invoke the DEF KEY function, TN3270 displays a prompt in
the status line at the bottom of your screen.
Example:

The following example shows the use of DEF KEY to define a key.
You invoke the DEF KEY function by entering the Ctrl/K sequence,
after which you are prompted for the key you want to define and
the function to assign to that key.

Press the key that you wish to define:

Enter the function name or quoted character:

You can also use DEF KEY to remove an assigned function. A null
reply to the following prompt removes the definition currently in
effect for that key:

Enter the function name or quoted character:

What you type during the DEF KEY dialog is subject to translation
from the National Character Set to the DIGITAL Multinational
Character Set.

You cannot redefine a key that exists on your National Character
Set terminal if it lacks a DIGITAL Multinational Character Set
equivalent.

4 Problem_Solving

During a TELNET session in which you have invoked TN3270, you
might experience the following problems:
Problem

o The keyboard keys do not work properly.

o Messages, such as the status line messages, do not appear in
reverse video.

o You receive a message indicating that your terminal is an
unsupported model.

You cannot use TN3270 on a VT131 model terminal that is
running in block mode.

Solution for a VT100-series Terminal

Use Set-Up mode to verify that your terminal is in ANSI mode.
Issue the following command:

$ SET TERMINAL /INQUIRE
Solution for a VT200-Series Terminal or a Terminal Connected to
Either a DIGITAL Personal Computer or a Workstation

1. Use Set-Up mode to verify that your terminal is:

o In ANSI mode

o Set to VT100 or VT200 emulation mode

2. Check the Communications Menu:

The terminal communications line must be set for 8-bit
characters. To check, issue the following command:

$ SET TERMINAL /INQUIRE

Solution for a Terminal with a National Language Keyboard

Ensure that your terminal is set up to correspond to your
keyboard.

Problem
You receive a message indicating that the screen size (or the
alternate screen size) specified by the remote host is too big.
Solution

Use Set-Up mode to change to a valid screen size.

Problem
You try to use the RECORD or PLAY function, but you get an error
message indicating that you have a bad key sequence file.
Solution

The file that stores the recorded key sequence is incompatible
with the current version of the software or is corrupted.

Ask your system manager to do either of the following:

o Correct UCX$RECSEQ.DAT in your SYS$LOGIN directory.

o Delete UCX$RECSEQ.DAT.

If the system manager must delete this file, rerecord all the
key sequences you had stored on the PF keys.

4 Debugging_Application_Programs_Using_the_IBM_3270_Model_Terminal_Emulator

Visible attribute mode provides a way to debug application
programs. After you use the DSP ATT (display attributes) function
to enable visible attribute mode, all attribute characters are
visible. Attribute characters are characters that appear at the
start of a field to indicate the following information:

o How the field appears on the screen:

- At normal intensity

- At high intensity

- Invisibly

o What type of data the application expects in the field:

- Numeric

- Alphabetic

- Alphanumeric

For help on how to enter and exit visible attribute mode, see
Entering and Exiting Visible Attribute Mode . For information
on the attribute characters displayed and their meaning, Visible
Attribute Mode Displays .

5 Entering_and_Exiting_Visible_Attribute_Mode_

The displays described in this section rely on your terminal's
ability to produce reverse video and bold characters.

Invoking the DSP ATT function toggles in and out of visible
attribute mode.

o The first time you press this key combination:

- The screen refreshes.

- The attribute characters appear either in reverse video or
underlined.

o The second time you press DSP ATT:

- You turn off this mode.

- The screen refreshes and returns to normal mode.

5 Visible_Attribute_Mode_Displays_

The attribute characters are displayed in reverse video, bold
symbols. Attribute characters indicating numeric fields are
also underlined. All other characters are displayed normally.
The following table lists the attribute characters and their
meanings.

Character Meaning

n Unprotected field with normal intensity follows
N Protected field with normal intensity follows
d Following unprotected field is light-pen-detectable
D Following protected field is light-pen-detectable
h Following unprotected field has high intensity
H Following protected field has high intensity
i Unprotected nondisplay field follows
I Protected nondisplay field follows

2 NFS
For information about the Network File Service (NFS), type:

$ HELP TCP_IP_SERVICES PRODUCT_OVERVIEW NFS

For complete information about the NFS server and NFS client, see
the "DIGITAL TCP/IP Services for OpenVMS Management" manual.

2 TCPIPTRACE
Starts the UCX$TRACE utility.

Format

TCPIPTRACE host [/BUFFERS=n | /FULL | /OUTPUT |/PACKETS=n |

/PORT=option | /PROTOCOL=option]

3 Parameters

host

Required.

Remote host to which you are sending packets for tracing.

3 Qualifiers

/BUFFERS

/BUFFERS=n

Optional. Default: 100.

Number of buffers that UCX$TRACE allocates for temporary storage.
These buffers must be locked into the process working set, so
you may have to decrease the number to accomodate the working set
size or increase the number to prevent UCX$TRACE from dropping
packets.

/FULL

Optional. Default: Brief display.

Displays the packet contents.

/OUTPUT

Optional. Default: Screen display.

Redirects the trace output to a file. If you specify a file name
that already exists, UCX$TRACE appends new trace information to
the existing file.

/PACKETS

/PACKETS=n

Optional. Default: 10.

Stops the trace after UCX$TRACE displays the specified number of
packets.

/PORT

/PORT ={LOCAL | REMOTE}= n

Optional. Default: Trace all port numbers.

Specifies the local or remote port number to trace. Use in
conjunction with the /PROTOCOL qualifier to filter tracing to
an exact port and protocol.

/PROTOCOL

/PROTOCOL = {ARP | ICMP | IP | TCP | UDP}

Optional. Default: IP

Specifies the protocol to trace. Use in conjunction with the
/PORT qualifier to filter tracing to an exact port and protocol.

3 Examples

1.$ TCPIPTRACE HOST1 /FULL /PORT=REMOTE=21

Traces packets for host HOST1 and remote port number 21.
UCX$TRACE provides a full display of the packets contents.

2.$ TCPIPTRACE HOST2 /FULL /PORT=(LOCAL=23, REMOTE=1056) -

_$ /PACKETS=30 /OUTPUT=TELNET_TRACE.TXT)

Traces packets for host HOST2 with a local port of 23 and
remote port number of 1056. UCX$TRACE provides a full display
of the packets contents. UCX$TRACE continues the trace for 30
packets and writes the output to the file TELNET_TRACE.TXT in
the current directory.

2 RPCGEN
A code-generating tool for creating programming skeletons that
implement the RPC mechanism.

NOTE

RPCGEN runs the C preprocessor, CC/DECC/PREPROCESSOR, on
all input files before actually interpreted the files.
Therefore, all the preprocessor directives are legal within
an RPCGEN input file. For each type of output file, RPCGEN
defines a special preprocessor symbol for use by the RPCGEN
programmer:

RPC_HDR Defined when compiling into header files
RPC_XDR Defined when compiling into XDR routines
RPC_SVC Defined when compiling into server-side skeletons
RPC_CLNT Defined when compiling into client-side skeletons
RPC_TBL Defined when compiling into RPC dispatch table

In addition, RPCGEN does a little preprocessing of its own.
RPCGEN passes any line beginning with "%" directly into the
output file, without interpreting the line.

3 Parameters

infile

The input file to RPCGEN. The input file contains ONC RPC
programming language. This language is very similar to the C
language. By default, RPCGEN uses the name of the input file to
create the four default output files as follows:

o infile.H-the header file

o infile_CLNT.C-the client skeleton

o infile_SVC.C-the server skeleton with support for both UDP and
TCP transports

o infile_XDR.C-the XDR routines

If you specify the /DISPATCH_TABLE qualifier, RPCGEN uses the
default name infile_TBL.I for the dispatch table.

3 Qualifiers

/CLIENT_STUBS_FILE

Optional.
Digital UNIX equivalent: -l
Default: Create a client skeleton file.

Creates the client skeleton file.

Mutually exclusive with the /DISPATCH_TABLE, /HEADER_FILE,
/SERVER_STUBS_FILE, /TRANSPORT, and XDR_FILE qualifiers.

/DEFINE

/DEFINE = (name[=value][,....])

Optional.
Digital UNIX equivalent: -D
Default: No definitions.

Defines one or more symbol names. Equivalent to one or more
#define directives. Names are defined as they appear in the
argument to the qualifier. For example, /DEFINE=TEST=1 creates
the line #define TEST=1 in the output files. If you omit the
value, RPCGEN defines the name with the value 1.

/DISPATCH_TABLE

Optional.
Digital UNIX equivalent: -t
Default: No dispatch file created.

Creates the server dispatch table file. An RPCGEN dispatch table
contains:

o Pointers to the service routines corresponding to a procedure

o A pointer to the input and output arguments

o The size of these routines

A server can use the dispatch table to check authorization and
then to execute the service routine; a client may use it to deal
with the details of storage management and XDR data conversion.

Mutually exclusive with the /CLIENT_STUBS_FILE, /HEADER_FILE,
/SERVER_STUBS_FILE, /TRANSPORT, and XDR_FILE qualifiers.

/ERRLOG

Optional.
Digital UNIX equivalent: -L
Default: Logging to stderr.

Specifies that servers should log errors to the operator console
instead of using fprintf with stderr. You must install servers
with OPER privileges in order to use this feature.

/HEADER_FILE

Optional.
Digital UNIX equivalent: -h
Default: Create a header file.

Creates the C data definitions header file. Use the /TABLE
qualifier in conjunction with this qualifier to generate a header
file that supports dispatch tables.

Mutually exclusive with the /CLIENT_STUBS_FILE, /DISPATCH_TABLE,
/SERVER_STUBS_FILE, /TRANSPORT, and XDR_FILE qualifiers.

/INET_SERVICE

Optional.
Digital UNIX equivalent: -I
Default: no INETd support.

Compiles support for INETd in the server side stubs. You can
start servers yourself or you can have INETd start them. Servers
started by INETd log all error messages to the operator console.

If there are no pending client requests, the INETd servers exit
after 120 seconds (default). You can change this default with the
/TIMEOUT_SECONDS qualifier.

When RPCGEN creates servers with INETd support, it defines two
global variables: _rpcpmstart and rpcfdtype. The runtime value
of _rpcpmstart is 1 or 0 depending on whether INDEd started the
server program. The value of rpcfdtype should be SOCK_STREAM or
SOCK_DGRAM depending on the type of the connection.

/OUTPUT

/OUTPUT = file

Optional.
Digital UNIX equivalent: -o
Default: Direct output to one of the standard default files.

Use this qualifier to direct the output of the /CLIENT_STUBS_
FILE, /DISPATCH_TABLE, /HEADER_FILE, /SERVER_STUBS_FILE,
/TRANSPORT, and /XDR_FILE qualifiers.

/SERVER_STUBS_FILE

Optional.
Digital UNIX equivalent: -m
Default: Create a server skeleton file.

Creates a server skeleton file without the main routine. Use this
qualifier to generate a server skeleton when you wish to create
your own main routine. This option is useful for programs that
have callback routines and for programs that have customized
initialization requirements.

Mutually exclusive with the /CLIENT_STUBS_FILE, /DISPATCH_TABLE,
/HEADER_FILE, /TRANSPORT, and XDR_FILE qualifiers.

/TABLE

Optional.
Digital UNIX equivalent: -T
Default: No dispatch table code created.

Creates the code in the header file to support an RPCGEN dispatch
table. You can use this qualifier only when you are generating
all files (the default) or when you are using the /HEADER_FILE
qualifier to generate the header file. This /TABLE qualifier
includes a definition of the dispatch table structure in the
header file; it does not modify the server routine to use the
table.

/TRANSPORT

/TRANSPORT [= (TCP, UDP)]

Optional.
Digital UNIX equivalent: -s
Default: Create a server-side skeleton that supports both
protocols.

Creates a server-side skeleton that includes a main routine that
uses the given transport. The supported transports are UDP and
TCP. To compile a server that supports multiple transports,
specify both.

/TIMEOUT_SECONDS

/TIMEOUT_SECONDS=seconds

Optional.
Digital UNIX equivalent: -K
Default: 120 seconds.

If INETd starts the server, this option specifies the time (in
seconds) after which the server should exit if there is no
further activity. By default, if there are no pending client
requests, INETd servers exit after 120 seconds. This option is
useful for customization. If seconds is 0, the server exits after
serving a request. If seconds is -1, the server never exits after
being started by INETd.

/XDR_FILE

Optional.
Digital UNIX equivalent: -c
Default: Create an XDR file.

You can customize some of your XDR routines by leaving those data
types undefined. For every data type that is undefined, RPCGEN
assumes that there exists a routine with the name xdr_ prepended
to the name of the undefined type.

Mutually exclusive with the /CLIENT_STUBS_FILE, /DISPATCH_TABLE,
/HEADER_FILE, /TRANSPORT, and /SERVER_STUBS_FILE qualifiers.

3 Examples

1.RPCGEN /ERRLOG /TABLE PROTO.X

This example generates all of the five possible files using the
default file names: PROTO.H, PROTO_CLNT.C, PROTO_SVC.C, PROTO_
XDR.C, and PROTO_TBL.I. The PROTO_SVC.C code supports the use
of the dispatch table found in PROTO_TBL.I. The server error
messages are logged to the operator console, instead of being
sent to the standard error.

2.RPCGEN /INET_SERVICE /TIMEOUT_SECONDS=20 PROTO.X

This example generates four output files using the default file
names: PROTO.H, PROTO_CLNT.C, PROTO_SVC.C, and PROTO_XDR.C.
INETd starts the server and the server exits after 20 seconds
of inactivity.

3.RPCGEN /HEADER_FILE /TABLE PROTO.X

This example sends the header file (with support for dispatch
tables) to the default output file PROTO.H.

4.RPCGEN /TRANSPORT=TCP PROTO.X

This example sends the server skeleton file for the transport
TCP to the default output file PROTO_SVC.C.

5.RPCGEN /HEADER_FILE /TABLE /OUTPUT=PROTO_TABLE.H PROTO.X

This example sends the header file (with support for dispatch
tables) to the output file PROTO_TABLE.H.

2 FINGER_Command
Displays information about users on a host. You can display:

o Brief listings of all users on a host

o Detailed listings about specific users

o Listing of users on a cluster

Specifying the FINGER command without a user or host
specification displays information about users logged in on your
local system.

Format

FINGER [/ALL | /CLUSTER | /FULL] [username][@hostname]

3 Parameters

username

Optional. Required for detailed information about a user.

Specify the user login name. For information about a user
on your local system, do not include the @hostname. For
information about a user on a remote system, include the host
name (username@hostname).

@hostname

Optional. Required for information about users on a remote
system.

For information about a specific user on a remote host, include
the user name with the host name (username@hostname). For
information about all users on the remote host, specify the host
name only (@hostname). Omit the host name to display information
about users on your local host.

3 Qualifiers

/ALL

Optional. Use when specifying a local user name. The /ALL
qualifier must follow immediately after the FINGER command.

Displays a brief listing of all users in addition to detailed
information about any specified users. Use this qualifier
primarily for displaying information about users on the local
host. The /ALL qualifier is ignored by most remote Finger servers
when you specify a remote host name in the command line. To
display brief information about all users on a remote host in
addition to detailed information about specific users, specify
the user@hostname format for each user plus @hostname (to list
brief information about all users). Separate each user@hostname
and @hostname specification with a space.

/CLUSTER

Optional. The /CLUSTER qualifier must follow immediately after
the FINGER command. Do not specify a remote host name with this
qualifier.

Displays information about all users logged in to the local
OpenVMS Cluster system.

/FULL

Optional. The /FULL qualifier must follow immediately after the
FINGER command.

Displays more detailed information such as the user's real name
and all logins of the user (without /FULL, the display includes
the last login only). Use this qualifier primarily for displaying
information about users on the local host.

3 Examples

1.$ FINGER FRANKEL@KCRA

Username Program Login Term/Location
FRANKEL $ Mon 15:10 KCRA::FRANKEL

Login name: frankel In real Life: Sam Frankel
Account: CC_Y9M Directory: WORK1$:[FRANKEL]
Last login: Mon 29-MAR-1997 13:10:22
No unread mail
No plan

Displays detailed information about user FRANKEL at host KCRA.

2.$ FINGER @OXYGEN

[oxygen.gp.org]
Username Program Login Term/Location
BARD $ Mon 17:00
CASON LSEDIT Thu 14:57
CORR $ Tue 13:30 24151::CORR
DUDLEY $ Mon 15:02 24646::DUDLEY
GRAND $ Thu 07:50 NITROGEN::GRAND
KURT $ Mon 16:57 22556::KURT
KYLIE MAIL Thu 14:12 ELEMENT::KYLIE
MYRA $ Wed 16:04 BIGVAX::MYRA
NASON $ Tue 09:23 24200::NASON
PHILLIPS $ Tue 02:42 BIGALP::PHILLIPS
RAWLINGS $ Mon 18:50 24042::RAWLINGS

Displays brief information about users logged into host OXYGEN.

3.$ FINGER/FULL

Username Real Name Program Login Term/Location
BAIRD Randall Baird $ Mon 17:00
CARR Rich Carr LSEDIT Thu 14:57
SHWCLSTR Mon 17:01
CORTEZ Julia Cortez $ Tue 13:30 23441::CORTEZ
DANBOY Dan Keller $ Thu 16:12 ogrady.ucsb.edu
GANDHI T.J. Gandhi TPU Mon 16:57 12556::GANDHI
TPU Tue 15:27 12556::GANDHI
LIMO Michael Limorley MAIL Thu 14:12 TOPDAY::LIMO
LSEDIT Thu 19:03 TOPDAY::LIMO
MENNING Mark Menning $ Wed 16:04 TOPDAY::MENNING
$ Mon 18:58 HAPDAY::MENNING
NELSON Anne Nelson $ Tue 09:23 22200::NELSON
ROBERTS Michael Roberts $ Mon 18:50 22042::ROBERTS
$ Mon 18:34 HAPDAY::ROBERTS

Displays the real name and all logins for each user.

4.$ FINGER/CLUSTER

Username Node Program Login Term/Location
SMITH MOUNTB TPU Fri 09:47 MOUNTB::SMITH
JONES MOUNTC $ Tue 18:02
BROWN MOUNTC $ Mon 17:04
TAYLOR MOUNTB EDT Thu 15:59
CROSBY MOUNTC RTPAD Thu 14:59
CARPENTER MOUNTB $ Wed 17:23 MOUNTB::SYSTEM
BLACK MOUNTC $ Tue 10:42 MOUNTC::BLACK

Displays information about all users on all members of the
cluster.

2 FTP_Command
The DIGITAL TCP/IP Services for OpenVMS (UCX) software includes
the File Transfer Protocol (FTP) service. The FTP command starts
an FTP session and does one of the following:

o Displays the FTP prompt. You can issue FTP commands to
customize your environment and FTP command processing.

o Establishes a connection to the specified remote host.

For help with individual FTP commands, type:

$ FTP
FTP> HELP

DCL-Style Format

FTP [host [ port ] ] [/USERNAME=remote_user_name |

/PASSWORD=password | /INPUT=file]

UNIX-Style Format

ftp [ host [ port ] ] [ local_file ]

3 Parameters

host

Optional.

Remote host to which you want to connect.

port

Optional. Default: 21.

FTP port on the remote host.

3 Qualifiers

/INPUT

/INPUT=file

Optional. Default: interactive input.

Runs a DCL command file with FTP commands.

/PASSWORD

/PASSWORD=password

Optional. Default: your password on the local system.

Password for the remote user account to which you want to
connect.

/USERNAME

/USERNAME=remote_user_name

Optional. Default: your user name on the local system.

Name of the remote user account to which you want to connect.

3 Examples

1.$ FTP WKSITE <Return>
220 wksite.texts.wrights.com FTP Server (DIGITAL UNIX 13:34:28 EDT) Ready
Connected to wren.nest.willow.com.
Name (wksite:parks) <Return>
331 Username PARKS requires a password
Password: (not echoed) <Return>
230 User logged in
FTP>

User PARKS starts an FTP session and connects to UNIX host
wksite.

2.$ FTP VIRTL /USERNAME=BENSON /PASSWORD=WMSWMS

220 newy FTP Server (Version 4.2) Ready
Connected to NEWY.LINK1.MOA.COM.
230 User logged in
FTP>

Starts an FTP session and connects to remote OpenVMS host
VIRTL, in user account BENSON.

3.$ FTP
FTP>

Starts an FTP user session without establishing a connection.

2 SMTP
For information about support for Simple Network Mail Protocol
(SMTP) in the DIGITAL TCP/IP Services for OpenVMS product, type
the following:

$ HELP TCP_IP_SERVICES MAIL

2 LPQ_Command
Displays the status of your jobs in a remote print queue:

o Current rank of your job in the queue

o Names of your queued files

o Job identifier

o Size of jobs in bytes

Format

LPQ queue [/ENTRY=n | /HOST=host | /PRINTER=remote_printer |

/USER=user_name]

3 Parameters

queue

Required.

Queue for which you want status.

3 Qualifiers

/ENTRY

/ENTRY=n

Optional. Default: all jobs. You can specify a list of values.

Displays status for the specified jobs.

/HOST

/HOST=host

Optional. Default: host defined in the printcap file.

Displays status for the jobs you sent to the specified
host. This is the host you also specified in the PRINT
/PARAMETERS=(HOST=host) command.

/PRINTER

/PRINTER=remote_printer

Optional. Default: printer defined in the printcap file.

Displays status for the jobs you sent to the specified remote
printer. This is the queue you also specified in the PRINT
/PARAMETERS=(PRINTER=queue) command.

/USER

/USER=user

Optional. Default: all users.

Displays status for the jobs sent by the specified user. You can
specify a list of values.

3 Examples

1.$ LPQ LPS40_QUE

Shows all entries in the LPS40_QUE queue.

2.$ LPQ MAIN_QUE /ENTRY=4

Shows information about Job 4 in the print queue named MAIN_
QUE.

3.$ LPQ PEACE_8 /ENTRY=(1,2,3)

Shows information about Jobs 1, 2, and 3 in print queue PEACE_
8.

4.$ LPQ 3RD_FLOOR_Q /USER=MILLER

Shows information about user MILLER's jobs in the print queue
called 3RD_FLOOR_Q.

2 LPRM_Command
Removes one or more jobs from a remote print queue.

Format

LPRM queue {/ALL | /ENTRY=n | /USER=user_name} [/HOST=host |

/PRINTER=remote_printer]

3 Parameters

queue

Required.

Print queue with waiting jobs you want to delete.

3 Qualifiers

/ALL

Required, unless you specify /ENTRY or /USER.

Removes all jobs for all users from the specified queue. Requires
SYSPRV, OPER, or BYPASS privileges. Comparable to the UNIX
command lprm -Pqueue - when performed by the root user on the
UNIX system.

/ENTRY

/ENTRY=n

Required, unless you specify /ALL or /USER.

Removes the specified job. Specify only your own jobs. You can
specify a list of values.

/USER

/USER=user

Required, unless you specify /ALL or /ENTRY.

Removes jobs by user name. You can specify a list of values.

/HOST

/HOST=host

Optional. Default: host defined in the printcap file.

Removes jobs by host for the host you specified in the
PRINT /PARAMETERS=(HOST=host) command.

/PRINTER

/PRINTER=remote_printer

Optional. Default: printer defined in the printcap file.

Removes jobs from the remote printer you specified in the PRINT
/PARAMETERS=(PRINTER=queue) command.

3 Examples

1.$ LPRM BASE_Q /ENTRY=7

Deletes your Job 7 from print queue BASE_Q.

2.$ LPRM FRONT_Q /ENTRY=(555,556,558)

From queue FRONT_Q, deletes a list of entries: 555, 556, and
558.

2 PRINT_Command
See HELP TCP_IP_SERVICES NETWORK_PRINTING REMOTE_PRINTING

2 RCP_Command
Copies files between internet hosts. Issue the RCP command at the
DCL prompt. You can copy files:

o From a remote host to your host

o From your host to a remote host

o From one remote host to another remote host

You can specify qualifiers in either OpenVMS-style format or
UNIX-style format, but do not mix both types on the same command
line.

DCL-Style Format

RCP [/[NO]LOG | /PASSWORD[=password] | /[NO]PRESERVE

| /[NO]RECURSIVE | /[NO]TRUNCATE_USER_NAME[=n] |

/USER_NAME=remote_user_name] source_file destination_file

UNIX-Style Format

rcp [ -p ] [ -r ] /[source_file] /[destination_file]

This format is valid only on UNIX systems.

3 Parameters

source_file

Required.

Source host and file specification, in the format
"[username@]"host:file, where:

o username@ is the user name on a remote UNIX system, needed
only if the UNIX system has the name in its /etc/hosts.equiv
file or the UNIX user's .rhosts file. Enclose username@
portion, or the entire specification containing the username@
syntax, in quotation marks (" ").

o host is the remote host, followed by a colon (:).

o file is the name of the file to copy. A file name without
the full path specification defaults to the default (or home)
directory. RCP Command: Specifying the Source File shows the
possible correct formats.

Table 1 RCP Command: Specifying the Source File

Host Possible Formats

UNIX hosts Specify the following, enclosing UNIX path names that
include slashes (/) in quotation marks (" "):

o Absolute path name, such as /etc/user/hosts,
followed by the file name

o Path name relative to your default directory,
followed by the file name

OpenVMS Specify the following:
hosts
o Brackets ([ ]), which indicate your default
directory, followed by the file name

o Full file specification, such as
DKA0:[WILDE.BINDS.NORTHERN]CHAPTER1.TXT

To specify a device name, type a colon (:) and
then the name. Enclose the entire parameter within
quotation marks (" ").

o A logical name, such as SYS$LOGIN:ROBIN.DAT or
DIAK$9:[AMERICAN]FINDINGS.LIS

To specify a logical name, type a colon (:) and
then the name. Enclose the entire parameter within
quotation marks (" ").

destination_file

Required.

Destination host and file specification information is of the
same form as the source parameter, unless the file specification
is completely omitted or the file name portion of the file
specification is omitted. In these cases, the default file
name used is the same as specified in the source parameter, the
directory being the default/home directory of the user.

3 Qualifiers

/LOG

/LOG
/NOLOG

Optional. Default: no logging.

Logs the files copied to or from the local system.

/PASSWORD

/PASSWORD=password

Required if /USER_NAME qualifier is used.

Password on the source or destination host system (whichever
requires authentication).

/PRESERVE

/PRESERVE (OpenVMS Style)
/NOPRESERVE
-p (UNIX style, valid only on UNIX systems)

Optional.

Preserves the file protection mode and modification date during a
copy.

/RECURSIVE

/RECURSIVE (OpenVMS Style)
/NORECURSIVE
-r (UNIX style, valid only on UNIX systems)

Optional.

Recursively copies each subtree rooted at the directory you
specify in the UNIX file specification. For OpenVMS hosts,
specify [directory...] (with three trailing periods) in the file
specification instead of using this qualifier.

/TRUNCATE_USER_NAME

/TRUNCATE_USER_NAME[=n]
/NOTRUNCATE_USER_NAME

Optional. Default: no truncation.

Truncates the user name to the specified number of characters. If
you omit n, the default is eight characters.

/USER_NAME

/USER_NAME=remote_user_name

Optional. Default: current name on local host, but in lowercase.

Specify user name on the source or destination remote host.
Use only if an entry allowing access to this user has not been
added to the remote host's authentication files. You must also
specify the /PASSWORD qualifier with the /USER_NAME qualifier.
If necessary, truncate the user name to the required number of
characters using the /TRUNCATE_USER_NAME qualifier. Specifying
"username@" with the source or destination parameter is the
equivalent UNIX-style method.

3 Examples

1.$ RCP/LOG NYX:STATS.BNT []

Copies file stats.bnt from remote UNIX system nyx from under
its home directory to a local file of the same name in the
current directory. The /LOG qualifier causes information for
the copy to be displayed. This command assumes the user has an
entry in the authentication file on host nyx.

2.$ RCP HIAIR1:AIRFRS.TXT [FLTAT.STATS]FARES1.TXT

Copies file AIRFRS.TXT from remote OpenVMS system HIAIR1,
from under its home directory to a local file of a different
name (FARES1.TXT) in the specified directory. This command
assumes the user has an entry in the authentication file on
host HIAIR1.

3.$ RCP /PRESERVE HIAIR1:[FARES.SUMMER]FARES_SU.TXT ":DKA300:[]"

Copies file FARES_SU.TXT from directory [FARES.SUMMER] on
remote OpenVMS system HIAIR1 to the specified device and
directory on the local system. The new file maintains the same
name as the original. The copy preserves the source file's
protection mode and modification date.

Use quotation marks (" ") for specifying the device and
directory on the destination.

4.$ RCP /USER=MILLER /PASS="AirOut" ":SYS$LOGIN:PILOTS.LIS" FALCON:

Copies file PILOTS.LIS from the login directory of user MILLER
on the local system to the user's login directory on a remote
UNIX system. The user specifies the user name and password
for access to the UNIX system (the password is specified in
quotation marks to preserve the mixed uppercase letters).

Use quotation marks (" ") for specifying the SYS$LOGIN device
and file name on the destination.

5.$ RCP /RECURSIVE ":DKA300:[MILES...]" "nyx:/usr/tmp"

Copies all files and any subdirectories under the local
directory [MILES] to a remote UNIX host's destination
directory. All the files in the subdirectories are copied
as well, creating subdirectories on the remote host, as
appropriate. The directory hierarchy is preserved on the UNIX
host by default. This command assumes the user has an entry in
the authentication file on host nyx.

6.$ RCP /LOG /RECURSIVE [MILES...] BOSTON:[FRFL...]

Copies the complete local subdirectory tree ([MILES...] and
all subdirectories) to the destination directory on remote
OpenVMS host BOSTON, while preserving the directory hierarchy
and logging each file copy. This command assumes the user has
an entry in the authentication file on host BOSTON.

7.$ RCP /LOG /RECURSIVE [MILES...] BOSTON:[FRFL]

Same as Example 6, except that all files in the local directory
tree are copied directly to the destination directory itself.
The command does not preserve the directory hierarchy of
[MILES...] in [FRFL] on host BOSTON. In other words, the
command does not create new subdirectories in BOSTON:[FRFL];
it copies all the files in [MILES] and all its subdirectories
to directory [FRFL].

8.$ RCP /USER=VAUGHN /PASSWORD=MYLES -
_$ /TRUNCATE=4 STATS.TXT FRAM:TISTICS

Copies the local file STATS.TXT to a remote user's login
directory. Note the truncation of the remote user name. A user
name and password are necessary if no entries for the user are
present in the remote host's authentication files.

9.$ RCP BOSTON:NAMES.LIS FRAM:ROSTER.LIS

Copies file NAMES.LIS from remote host BOSTON to remote
host FRAM (naming the file ROSTER.LIS). Assumes appropriate
entries for the user have been made in each remote host's
authentication files.

10$ RCP "MILLER@BOSTON:SYS$DIR:T2" "nelson@nyx:/usr/nelson"

Copies file T2 from remote OpenVMS system BOSTON in the
directory pointed to by the logical name SYS$DIR to remote
UNIX system nyx in the specified directory. Different user
names are used on the two remote systems. Entries in the remote
host's authentication files must be set up properly because the
passwords are not being passed.

11$ RCP /USER=ROSS /PASSWORD=LC12LC BOS:CLIENT.LIS "BEX:/USR"

Copies file CLIENT.LIS from OpenVMS host BOS to UNIX host bex.
The user has a proxy account on the UNIX host. The specified
authentication information allows access to the account for
ROSS on host BOS.

2 REXEC_Command
Sends one command to a specified remote host for execution.

The difference between the REXEC facility and RSH is security
checking:

o REXEC - the remote host bases authentication on user name and
password.

o RSH - the remote host bases authentication on user name and
information in the remote system's authentication files.

To invoke the REXEC feature, type either of the following:

RSH /PASSWORD=password

RSH /PASSWORD

2 RLOGIN_Command
Initiates an interactive login session with a remote host.

DCL-Style Format

RLOGIN [/DROP_TIMEOUT=seconds | /EIGHTBIT |

/ESCAPE_CHARACTER=character | /LOG_FILE=file

| /[NO]LOWERCASE | /PROBE_TIMEOUT=seconds |

/TERMINAL_SPEED=baud | /TERMINAL_TYPE=type |

/[NO]TRUNCATE_USER_NAME | /USER_NAME=remote_user_name]

host

UNIX-Style Format

rlogin host [ -8 ] [ -ec ] [ -l remote_user_name ]

This format is valid only on UNIX systems.

3 Parameters

host

Required.

Remote host to which you want to connect.

3 Qualifiers

/DROP_TIMEOUT

/DROP_TIMEOUT=seconds

Required if you set /PROBE_TIMEOUT.

Maximum interval, in seconds, that your network link can be down
before the software closes it.

/EIGHTBIT

/EIGHTBIT
-8 (UNIX style, valid only on UNIX systems)

Optional. Default: only 7-bit data is sent.

Accepts 8-bit data from the terminal and sends it to the remote
system.

/ESCAPE_CHARACTER

/ESCAPE_CHARACTER=character
-ec (UNIX style, valid only on UNIX systems)

Optional. Default: ~ (tilde).

New escape character if you want to close your RLOGIN session
from the remote host.

To close your session from your local host, use a period ( . ) as
the escape command.

/LOG_FILE

/LOG_FILE=file

Optional. Default: no logging.

Logs a copy of the output to the specified file. Output continues
to be directed to SYS$OUTPUT while it is being recorded in the
log file.

/LOWERCASE

/LOWERCASE
/NOLOWERCASE

Optional. Default: /LOWERCASE.

Sends your local user name to the remote host in lowercase.

To send your user name in uppercase, use either of the following:

o Specify /NOLOWERCASE.

o Enclose the user name in quotation marks ( " " ). (See /USER_
NAME.)

To send your user name in mixed case, enclose it in quotation
marks ( " " ).

/PROBE_TIMEOUT

/PROBE_TIMEOUT=seconds

Required if you set /DROP_TIMEOUT.

Interval, in seconds, that DIGITAL TCP/IP Services for OpenVMS
checks to see if your network link and the remote host are both
still up.

/TERMINAL_SPEED

/TERMINAL_SPEED=baud

Optional. Default: current speed of your terminal.

Terminal speed in baud rate.

/TERMINAL_TYPE

/TERMINAL_TYPE=type

Optional. Default: type of physical terminal you are using.

Terminal type. Use this qualifier if the remote host does not
recognize your terminal.

/TRUNCATE_USER_NAME

/TRUNCATE_USER_NAME
/NOTRUNCATE_USER_NAME

Optional. Default: /NOTRUNCATE_USER_NAME.

Abbreviates the user name sent to the remote host to eight
characters (required for older UNIX hosts, which limit user names
to eight characters).

/USER_NAME

/USER_NAME=remote_user_name
-l remote_user_name (UNIX style, valid only on UNIX systems)

Optional. Default: current name on local host, but in lowercase.

Your user name on the remote host. Specify this qualifier if your
user names on the remote host and local host are different.

To send your user name in uppercase, use either of the following:

o Specify /NOLOWERCASE.

o Enclose the user name in quotation marks ( " " ).

To send your user name in mixed case, enclose it in quotation
marks ( " " ).

3 Examples

1.$ RLOGIN /USER_NAME="BlissTon" ROLLS

An OpenVMS user logs in to account BlissTon on UNIX host rolls.
The mixed-case remote user name is in quotation marks so RLOGIN
does not send it all lowercase, which is the default. This
example assumes the user has a proxy account on the remote
host.

2.$ RLOGIN /NOLOWERCASE /USER_NAME=DAVE PLETHORA

User DAVE starts an interactive login session with UNIX host
plethora. Because this user has an uppercase user name, it is
specified with the /NOLOWERCASE qualifier. This example assumes
the user has a proxy account on the remote host.

3.$ RLOGIN /ESCAPE_CHARACTER="+" PJARO <Return>
Password: (not echoed)<Return>
Last login: Wed Aug 24 16:50:40 from world.wide.webber.com
Digital UNIX System - 4: Fri Aug 26 11:02:20 EST 1996

You have mail.
Fri Aug 26 11:02:20 EST 1996

pjaro> WHO <Return>

black ttyp0 Aug 26 11:02 grades.philosophy.ucd.edu.
bristow ttyp1 Aug 12 09:00 grades.biology.ucd.edu.
cutler ttyp2 Aug 26 08:55 grades.math.ucd.edu.

pjaro> PWD <Return>

/usr/users/black
pjaro> ls <Return>

bin Sem1.paper Sem2.paper

pjaro> +. (not echoed)

%RSH-S-LCLCLOSED, Local connection closed
$

OpenVMS user BLACK, with UNIX user name black, logs in to UNIX
host pjaro and resets the escape character to a plus sign. By
default, DIGITAL TCP/IP Services for OpenVMS passes the user
name and commands to the remote host in lowercase.

4.$ RLOGIN FANTAC <Return>
OpenVMS Version 7.1 - Unauthorized access is prohibited.

Username: TDERR <Return>
Password: (not echoed) <Return>
.
.
.
$

TDERR logs in to remote OpenVMS host FANTAC.

5.$ RLOGIN QANCE /DROP_TIMEOUT=45

%RLOGIN-E-INETERROR, Internet interface error
-RLOGIN-I-INETCALL, setsockopt(TCP_DROP_IDLE)
-SYSTEM-F-BADPARAM, bad parameter value
$

The command fails because the /DROP_TIMEOUT and /PROBE_TIMEOUT
qualifiers must both be set.

2 RSH_Command
Sends a command to a remote host for execution, including a
command that invokes a remote shell script or remote command
procedure. Any command recognized by the remote host is valid.
When using the RSH command, consider the following:

o If you omit a command for remote execution, RSH initiates a
remote login session (see the RLOGIN Command command).

o If you specify the /PASSWORD qualifier, with or without a
value, RSH executes the REXEC facility.

DCL-Style Format

RSH host [/EIGHTBIT | /ESCAPE_CHARACTER=character |

/LOG_FILE=file | /[NO]LOWERCASE | /PASSWORD[=password] |

/[NO]SYSERROR | /TERMINAL_SPEED=n | /TERMINAL_TYPE=type |

/[NO]TRUNCATE_USER_NAME | /USER_NAME=remote_user_name] [

remote_command ]

UNIX-Style Format

rsh host [ -l remote_user_name ] [ remote_command ]

This format is valid only on UNIX systems.

3 Parameters

host

Required.

Remote host at which you want the command to execute.

remote_command

Optional. Default: none.

Command you are sending to the remote host for execution.

NOTE

The remote_command must be the last item on the command
line.

3 Qualifiers

/EIGHTBIT

Optional. Default: only 7-bit data is sent.

Accepts 8-bit data from the terminal and sends it to the remote
system.

/ESCAPE_CHARACTER

/ESCAPE_CHARACTER=character

Optional. Default: ~ (tilde).

New RLOGIN escape character. This character lets you exit the
RLOGIN process without typing the remote host's typical logout
sequence, for example, LOGOUT or Ctrl/D.

Typing the escape character and a period (.) breaks the
connection with the remote host, for example:

remote> ~. (not echoed)

%RSH-S-LCLCLOSED, Local connection closed
local_vms>

/LOG_FILE

/LOG_FILE=file

Optional. Default: no logging.

Logs a copy of the output to the specified file. Output continues
to be directed to SYS$OUTPUT while it is being recorded in the
log file.

Not valid with /SYSERROR.

/LOWERCASE

/LOWERCASE
/NOLOWERCASE

Optional. Default: /LOWERCASE.

Sends your local user name to the remote host in lowercase.

To send your user name in uppercase, use either of the following
ways:

o Specify /NOLOWERCASE.

o Enclose the user name in quotation marks ( " " ). (See /USER_
NAME.)

To send your user name in mixed case, enclose it in quotation
marks ( " " ).

/PASSWORD

/PASSWORD[=password]

Optional.

Your password on the remote host.

Invokes the local REXEC facility that directs your RSH command
to the REXEC server on the remote host. This server does
authentication checking using the user name and password that
you specified on the RSH command line.

o Enclose the password in quotation marks ( " " ) if it is
lowercase or mixed case.

o If you omit password, RSH prompts you for one.

o Do not use this qualifier if you want to initiate an RLOGIN
session.

/SYSERROR

/SYSERROR
/NOSYSERROR

Optional. Default: /NOSYSERROR.

Directs diagnostics to SYS$ERROR and output to SYS$OUTPUT.

When SYS$ERROR and SYS$OUTPUT both output to the same terminal,
the output might be garbled.

/NOSYSERROR directs output only to SYS$OUTPUT.

/TERMINAL_SPEED

/TERMINAL_SPEED=n

Optional. Default: your terminal's current speed.

Terminal speed passed to the remote host during an RLOGIN
session.

/TERMINAL_TYPE

/TERMINAL_TYPE=type

Optional. Default: your terminal's current type.

Terminal type passed to the remote host during an RLOGIN session.

/TRUNCATE_USER_NAME

/TRUNCATE_USER_NAME
/NOTRUNCATE_USER_NAME

Optional. Default: /NOTRUNCATE_USER_NAME.

Abbreviates the user name sent to the remote host to eight
characters (required for older UNIX hosts, which limit user names
to eight characters).

/USER_NAME

/USER_NAME=remote_user_name
-l remote_user_name (UNIX style, valid only on UNIX systems)

Optional. Default: same name on local host, but in lowercase.

Your user name on the remote host. Specify this qualifier if your
user names on the remote host and local host are different.

To send your user name in uppercase, use either of the following
ways:

o Specify /NOLOWERCASE.

o Enclose the user name in quotation marks ( " " ).

To send your user name in mixed case, enclose it in quotation
marks ( " " ).

3 Examples

1.$ RSH HENCE MAN CP

cp(1)

Name
cp - copy file data

Syntax
cp [ -f ] [ -i ] [ -p ] file1 file2
.
.
.
See Also
cat(1), pr(1), mv(1)
$

A user sends the man cp command to UNIX host hence for
execution.

2.$ RSH /USER_NAME=ROGERS DELPHI LS

OpenVMS user PHILIPS issues the ls command for execution at
remote UNIX host delphi. PHILIPS is accessing an account called
rogers.

3.$ RSH /PASSWORD=BLOOMER AVOC8N DIRECTORY

OpenVMS user PANTO sends the DIRECTORY command to remote
OpenVMS host AVOC8N. The remote directory listing is of PANTO's
home directory.

RSH /PASSWORD invokes REXEC, which authenticates PANTO's remote
password.

4.$ RSH /PASSWORD MAGIC CAT BUZZ.TXT
REXEC password: (not echoed)<Return>

A user sends the cat command to host magic. /PASSWORD invokes
REXEC, which requires a password. Because the password was
omitted from the command line, REXEC prompts the user for it.

2 TELNET_Command
Starts a TELNET session and does one of the following:

o Displays the TELNET prompt.

o Establishes a connection to a remote host.

o Establishes a connection to a remote host and runs TN3270.

For help with individual TELNET commands, type:

$ TELNET
TELNET> HELP

DCL-Style Format

TELNET [ host ] [/CREATE_SESSION | /DELETE_SESSION |

/LOG_FILE=file | /NOINTERACTIVE | /PORT=n |

/TERMINAL_TYPE=type] [ port ] [unit ]

UNIX-Style Format

telnet [ host ]

3 Parameters

host

Required with the /CREATE_SESSION qualifier; optional in all
other cases. Default: none.

Remote host to which you want to connect. Specify one of the
following:

o Host name

o IP address

port

Required with the /CREATE_SESSION qualifier; ignored in all other
cases. Default: none.

Specifies the remote port to which you want to connect the
pseudodevice.

unit

Required with the /DELETE_SESSION qualifier; optional with the
/CREATE_SESSION qualifier; ignored in all other cases. Default:
0.

With the /CREATE_SESSION qualifier, specifies the unit number
you want associated with the network terminal. The default of
0 allows the TELNET software to select the next available unit
number.

With the /DELETE_SESSION qualifier, specifies the unit number of
the network terminal you wish to delete.

3 Qualifiers

/CREATE_SESSION

Optional. Default: None

Specifies that TELNET should create a pseudodevice (network
terminal) and connect it to the specified remote port. For
additional information, see the CREATE_SESSION command.

/DELETE_SESSION

Optional. Default: None

Specifies that TELNET should delete the specified pseudodevice
(network terminal). For additional information, see the DELETE_
SESSION command.

/LOG_FILE

/LOG_FILE=file

Optional. Default: no logging.

An optional log file to contain all session output. Using this
option does not affect your terminal output. You cannot use this
option for TN3270 sessions.

/NOINTERACTIVE

Optional. Default: TELNET command mode.

Disables the capability of using the escape character to leave
a session and return to the TELNET prompt. This option is useful
when the TELNET command is referenced in a command procedure in a
captive account.

/PORT

/PORT=n

Optional. Default: 23.

Remote port to which you want your TELNET process to connect.
Specify only if you are connecting to a host that does not use
the standard TELNET port.

/TERMINAL_TYPE

/TERMINAL_TYPE=type

Optional. Default: none.

The IBM or DIGITAL terminal to emulate. Type the full
specification for one of these:

o IBM-3278-2

o IBM-3278-3

o IBM-3278-4

o IBM-3278-5

o VT100

o VT200

o VT300

o VT400

o VT500

3 Examples

1.$ TELNET
TELNET> ENABLE DEBUG
TELNET> SET TERMINAL /DEVICE=VT300
Terminal type is set to VT300
TELNET> CONNECT DEBTS

o Starts TELNET.

o Customizes the environment.

o Establishes a connection to host debts and sets up the
terminal type as VT300.

2.$ TELNET MYCOM /TERMINAL_TYPE=IBM-3278-2

Establishes a TELNET connection to remote host MYCOM and runs
TN3270.

3.$ TELNET 130.180.5.5

Establishes a TELNET connection to the host at IP address
130.180.5.5.

4.$ TELNET UCOM 31

Establishes a TELNET connection to remote host ucom at port 31.

2 TN3270_Command
Starts a TELNET session that runs TN3270 and does one of the
following:

o Displays the TELNET prompt.

o Establishes a connection to a remote host.

For help with individual TELNET commands, type:

$ TN3270
TELNET> HELP

Format

TN3270 [ host ] [/CHARACTER_SET=file | /KEY_DEFINITIONS=file

| /NATIONAL_CHARACTERS=char_set | /NOINTERACTIVE

| /PORT=n | /PRINTER=file | /STATUS=state |

/TERMINAL_TYPE=IBM-3278-n]

3 Parameters

host

Optional.

Remote host to which you want to connect. Specify one:

o Host name

o IP address

3 Qualifiers

/CHARACTER_SET

/CHARACTER_SET=file

Optional. Default: ORIGINAL.

File with the EBCDIC-to-DMCS (DIGITAL Multinational Character
Set) and the DMCS-to-EBCDIC translation tables.

If you omit this qualifier, TN3270:

o Uses the translation table named by the default file
SYS$LIBRARY:UCXTEDEF.TBL, if your system manager has created
it.

o Defaults to its own translation table, if UCXTEDEF.TBL does
not exist. The default table maps the US EBCDIC set to the
equivalent DMCS characters.

If none of these translation tables meets your needs, the
system manager can generate a new translation table. (See
the DIGITAL TCP/IP Services for OpenVMS Management manual for
information about the EBCDIC / DMCS translation tables.)

NOTE

To reset the default, do not abbreviate ORIGINAL.

/KEY_DEFINITIONS

/KEY_DEFINITIONS=file

Optional. Default: default keyboard layout.

Keyboard definition file you created to redefine how the TN3270
key functions correspond to your keyboard layout. This file holds
the definitions for alternative keyboard mapping.

/NATIONAL_CHARACTERS

/NATIONAL_CHARACTERS=character_set

Optional. Defaults: For 8-bit terminals: MULTINATIONAL
For 7-bit terminals: US_ASCII.

National Replacement Character Set (NRCS) for which your DIGITAL
terminal is configured. Specify one of the following:

Canadian MULTINATIONAL
Dutch Norwegian
Finnish Spanish
French Swedish
German Swiss
Italian UK_ASCII
Japanese US_ASCII

/NOINTERACTIVE

Optional. Default: TELNET command mode.

Disables the capability of using the escape character to leave
a session and return to the TN3270 prompt. This option is useful
when the TN3270 command is referenced in a command procedure in a
captive account.

/PORT

/PORT=n

Optional. Default: 23.

Remote port to which you want your TELNET/3TN3270 process to
connect. Specify only if you are connecting to a host that does
not use the standard TELNET port.

/PRINTER

/PRINTER=file

Optional. Default: TN3270PRINT.LIS.

File that records your screen's contents when you use the PRINT
function.

Directs printer output to either a file or a spooled printer (not
a physical printer or terminal).

/STATUS

/STATUS=state

Optional. Default: AUTOMATIC.

Determines how the status line operates during your session.
Specify one of the following:

AUTOMATIC Status line is displayed.

The status line is disabled automatically if the
remote host writes data to the area under the
status line or you type in that space.

The status line is restored automatically when
the data is erased.
ON Status line is always displayed.
OFF Status line is not displayed.

To toggle between ON and OFF, invoke the STATUS function.

/TERMINAL_TYPE

/TERMINAL_TYPE=IBM-3278-n

Optional. Default: IBM-3278-2.

IBM terminal to emulate. Type the full specification for one of
the following:

o IBM-3278-2

o IBM-3278-3

o IBM-3278-4

o IBM-3278-5

3 Examples

1.$ TN3270 MYCOM

Establishes a TELNET connection to remote host MYCOM. By
default, the physical terminal functions as an IBM-3278-2 model
terminal.

2.$ TN3270 130.180.5.5 /TERMINAL_TYPE=IBM-3278-3 -
_$ /KEY_DEFINITIONS=MY_NUMPAD.FIL

Establishes a TELNET connection to the host at IP address
130.180.5.5. The terminal functions as if it were an IBM-3278-3
model terminal, and it uses the customized keyboard definition
file MY_NUMPAD.FIL.

3.$ TN3270 UCOM 31 /TERMINAL_TYPE=IBM-3278-5 /PRINTER=LOG

Establishes a TELNET connection to remote host ucom:

o The connection is at port 31 on ucom.

o The terminal is functioning as if it were an IBM-3278-5
model terminal.

o During the session at ucom, using the PRINT function records
the screen's contents in a file named LOG.LIS.

Software development, photography, jokes, ....

Sites by me

Hosting Favorites

Blogroll

Marc's Place

1 TCP_IP_Services (1)