TCPIP Services
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help TCPIP Services *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
TCP/IP is an open communications standard that enables any
connected host to communicate with any other connected host.
The Compaq TCP/IP Services for OpenVMS product is Compaq's
implementation of TCP/IP for the OpenVMS operating system.
The Compaq TCP/IP Services for OpenVMS software allows you to
communicate and share resources with remote OpenVMS systems, UNIX
systems, and other systems that support the TCP/IP protocol suite
and Sun Microsystems' Network File System (NFS).
| 1 - Product Overview |
The product consists of a number of components that implement
various TCP/IP protocols. These components provide remote
computing, file transfer, resource sharing, electronic mail,
and network services as follows:
Remote Computing
TELNET Log in to a remote host in a network using various
options to customize the session, control output
from the remote host, and negotiate compatibility
differences. To start a TELNET session, enter:
$ TELNET
RCP Copy files between the local host and a remote host or
between two remote hosts. Requests are authenticated
on the remote host or hosts using the user name
supplied by RCP.
RLOGIN Connect to a remote host, which starts an interactive
login session. Requests are authenticated on the
remote host using the user name supplied by RLOGIN.
RSH Connect to a remote host, which executes the command
you specify. Requests are authenticated on the remote
host using the user name supplied to RSH.
RSH/PASSWORUse the REXEC facility to connect to the remote host,
which executes the command you specify. Requests are
authenticated on the remote host using the user name
and password supplied by RSH.
RMT/RCD Access magnetic tape and CD drives on a remote host as
though they are available locally.
Finger Display information about users logged in to a remote
host, such as their login user names or programs they
are using.
File Transfer
FTP Create, delete, and copy files and directories between
hosts. To start an FTP session, enter:
$ FTP
TFTP Download and transfer files.
Resource Sharing
LPD/LPR Print files on remote and local hosts.
TELNETSYM Print files on remote hosts using the TELNET protocol.
NFS Authenticate requests and provide access to remote
files.
Mail
SMTP Send and receive electronic mail from remote hosts.
POP Send and receive electronic mail from your PC.
Network Services
BIND Name and address resolution service to distribute and
manage host information.
SNMP Monitor and manage network devices from across an
internetwork.
NTP Synchronize time between hosts.
BOOTP Answer bootstrap requests from remote devices.
DHCP Configure and maintain your IP address space including
the temporary assignment of IP addresses.
SLIP, Connect a node to a network over a serial connection
CSLIP using IP.
PPP Connect a node to a network using IP or other
supported network protocols.
Management Manage your TCP/IP environment. To start the
commands management control program, enter:
$ TCPIP
For online descriptions of the management commands,
enter:
$ TCPIP HELP
TCPTRACE Trace packets going in and out of the system.
NSLOOKUP Determine if your local name server is running
correctly or retrieve information from remote servers.
| 2 - BIND |
The Domain Name Service (DNS) is an Internet service that
maintains and distributes information about Internet hosts. DNS
consists of several databases that store host names and host IP
addresses. With DNS, there is no central storage of data - no one
server knows everything about all the Internet domains. In UNIX
environments, DNS is implemented by the Berkeley Internet Name
Domain (BIND) software.
Compaq TCP/IP Services for OpenVMS implements a BIND server based
on the Internet Software Consortium's (ISC) BIND 8.1.2. The BIND
8.1.2 implementation provides new configuration options and a new
format for configuring the BIND name server.
In addition to standard BIND features, the Compaq TCP/IP Services
for OpenVMS product provides cluster load balancing and round-
robin scheduling.
Configuring and managing BIND on your OpenVMS host involves the
following tasks:
o Configuring the BIND resolver and name server using
TCPIP$CONFIG
o Modifying the BIND configuration using SET CONFIGURATION
commands or by editing the BIND 8 configuration file
o Setting up name servers to be: primary (master), secondary
(slave), cache-only, and forwarder
o Populating the BIND server databases
o Displaying name server information
o Using NSLOOKUP to query a name server
| 3 - BOOTP |
The Bootstrap Protocol (BOOTP) server answers network bootstrap
requests from diskless workstations and other network devices
such as routers, terminal servers, and network switching
equipment. When it receives such a request, the BOOTP server
looks up the workstation's address in the BOOTP database file.
The Trivial File Transfer Protocol (TFTP) handles the file
transfer from a BOOTP server to a diskless client or other remote
system. The client initiates the file transfer.
Configuring and managing BOOTP on your OpenVMS host involves the
following tasks:
o Planning your BOOTP configuration
o Configuring the BOOTP and TFTP components using TCPIP$CONFIG
o Modifying the BOOTP configuration using logical names and
management commands
o Creating a BOOTP database
o Monitoring the BOOTP and TFTP processes
| 4 - DHCP |
Dynamic Host Configuration Protocol (DHCP), a superset of the
Bootstrap Protocol (BOOTP), provides a centralized approach to
the configuration and maintenance of IP address space. It allows
the system manager to configure various clients on the network
from a single location.
DHCP allocates temporary or permanent IP addresses from an
address pool to client hosts on the network. DHCP can also
configure client parameters such as default gateway parameters,
domain name server parameters, and subnet masks for each host
running a DHCP client.
Configuring and managing the DHCP server requires the following
tasks:
o Configuring the server using TCPIP$CONFIG
o Setting up the NETMASKS file
o Defining a set of IP addresses as static, dynamic, or finite
o Specifying lease time
o Configuring default gateways and DNS domain names
o Using utility commands to modify DHCP databases
| 5 - TFTP |
The Trivial File Transfer Protocol (TFTP) transfers files from
a BOOTP server to diskless clients or other remote systems. The
client initiates the file transfer.
When the client receives the configuration information in the
BOOTP response, it sends a request to the TFTP server host named
in the response. This request is necessary only if the client
must retrieve the load file.
If the client sends a read request (RRQ) to the TFTP server, the
server attempts to locate the file.
Configuring and managing TFTP on your OpenVMS host involves the
following tasks:
o Configuring the TFTP and BOOTP components using TCPIP$CONFIG
o Monitoring the TFTP and BOOTP processes
o Using management commands to enable and disable TFTP and to
configure TFTP in the service database
| 6 - NTP |
The Network Time Protocol (NTP) provides a means to synchronize
time and coordinate time distribution throughout a TCP/IP
network. NTP aims to provide accurate and dependable timekeeping
for hosts on TCP/IP networks.
NTP provides synchronization traceable to clocks of high absolute
accuracy and avoids synchronization to clocks keeping incorrect
time.
Configuring and managing NTP on your OpenVMS host involves the
following tasks:
o Determining which network hosts to use for synchronization
o Creating and populating the NTP configuration file with the
list of participating hosts
o Defining a time-zone differential (offset) logical name
o Using the NTPDATE program to set the local date and time
o Using the NTPTRACE utility to determine the source from which
an NTP server obtains its time
o Using the NTPDC query program to make runtime changes to NTP
| 7 - SNMP |
The Simple Network Management Protocol (SNMP) is network
management technology that facilitates the management of a
TCP/IP network or internet in a vendor-independent manner. SNMP
enables a network administrator to manage the various network
components using a set of well-known procedures understood by all
components, regardless of the vendor that manufactured them.
Configuring the SNMP agent on your OpenVMS system allows a remote
SNMP management client to obtain information about your host and
to set optional network parameters.
Configuring and managing SNMP on your OpenVMS host involves the
following tasks:
o Configuring the SNMP component using TCPIP$CONFIG
o Modifying the SNMP configuration using the SET CONFIGURATION
SNMP command and qualifiers
o Modifying master agent and subagent behavior by defining
logical names
o Testing the master agent and subagent behavior using the
MIB browser program, the trap sender program, and the trap
receiver program
o Writing your own subagent, as appropriate for your network
| 8 - NFS |
The Network File System (NFS) protocols enable internet clients
to access remote files that reside on NFS servers.
The Compaq TCP/IP Services implementation of the Network File
System (NFS) includes the following software:
o NFS server
o NFS client
o NFS file system
o PC-NFS print services
8.1 - Server
The NFS server software lets you set up file systems on your
local system for export to users on remote NFS client hosts.
These files and directories, even though they physically reside
on the local system, appear to the remote user to be on the
remote host.
Configuring and managing the NFS server on your OpenVMS host
involves the following tasks:
o Configuring the NFS server using TCPIP$CONFIG
o Configuring the PC-NFS daemon using TCPIP$CONFIG (if you plan
to export file systems to PC-NFS client hosts)
o Modifying NFS and PC-NFS configuration using management
commands
o Selecting a file system: OpenVMS or container (UNIX style)
o Modifying server and container file system characteristics by
defining logical names
o Registering users and hosts in the proxy database file
o Backing up the file system
o Setting up and exporting the file system
o Maintaining and examining a container file system
o Setting up NFS security features
o Improving NFS server performance
8.2 - Client
The NFS client software enables client users to access file
systems made available by an NFS server. These files and
directories physically reside on the remote (server) host but
appear to the client as if they were on the local system. For
example, any files accessed by an OpenVMS client - even a UNIX
file - appear to be OpenVMS files and have typical OpenVMS file
names.
Configuring and managing the NFS client on your OpenVMS host
involves the following tasks:
o Configuring the NFS client using TCPIP$CONFIG
o Registering users in the proxy database
o Mounting (attaching) remote files and directories exported by
the NFS server
8.3 - File System
The NFS file system on OpenVMS includes a hierarchy of devices,
directories, and files stored on a File-11 On-Disk Structure
(ODS-2) formatted disk.
You can set up and export two different kinds of file systems:
o Traditional OpenVMS file system
o UNIX style (container) file system built on top of an OpenVMS
file system.
To set up and maintain these file systems, you issue management
commands.
8.4 - PC-NFS
The TCP/IP Services implementation of PC-NFS provides the
following print services to personal computers (PCs) running
NFS Client software:
o Authentication
A PC that wants to request access to an NFS Server must first
get its user identification / group identification (UID/GID)
pair from a remote authentication server running Compaq TCP/IP
Services for OpenVMS.
o Printing
You set up the PC-NFS daemon software using TCPIP$CONFIG, and you
manage the software by issuing management commands.
| 9 - SLIP and PPP |
Compaq TCP/IP Services for OpenVMS supports serial connections
using the following protocols:
o Serial Line IP (SLIP) and Compressed SLIP (CSLIP) protocols
Sends datagrams across the serial line as a series of bytes,
using special characters to mark when a series of bytes should
be grouped together
o Point-to-Point Protocol (PPP) (Alpha only)
Uses a frame format that includes a field to identify the
protocol (for example: IP or OSI).
One of the largest applications for SLIP and PPP is dialup
access.
With PPP, you can establish a dynamic IP network connection over
a serial line without the extensive use of additional router or
server hardware. PPP ensures interoperability between systems
from a wide variety of vendors.
Because SLIP has been in use for a longer period of time,
it is available for most terminal servers and in most PC
implementations of TCP/IP. CSLIP provides header compression
to improve packet throughput, which is especially beneficial for
small packets.
For either SLIP or PPP connections, a host can function as a
dialup provider (server) to respond to incoming connection
requests. Or, a host can function as a client dialing in to a
dialup provider.
Setting up your OpenVMS host as a dialup provider or client
involves the following tasks:
o Installing the appropriate virtual terminal driver
o Configuring the interface for serial line connections
(optional for clients)
o Configuring your modem
o Setting up an asynchronous port for modem connections
o Enabling IP forwarding and dynamic routing (dialup provider
only)
o Initiating a connection (client only)
| 10 - Management Tools |
Compaq TCP/IP Services for OpenVMS includes the following network
management tools:
o A management control program with a command-line interface,
event logging, and error and information messages
o UNIX style commands
o The configuration procedure TCPIP$CONFIG
o The DHCP graphical user interface (GUI)
o The TCPTRACE utility
o Logical names
o Startup and shutdown procedures
o The NSLOOKUP utility
o SNMP and the Extensible SNMP (eSNMP)
| 11 - UNIX Commands |
UNIX management commands are available for system managers
experienced in managing a UNIX network subsystem. The following
table introduces these commands.
Command Description
ifconfig Configures or displays network interface
parameters, redefines an address for a particular
interface, or sets options such as an alias list,
broadcast address, or access filter.
netstat Displays network statistics of sockets, data link
counter` aliases, network interfaces, and a host's
routing table.
sysconfig Displays and maintains the network subsystem
attributes.
route Manually manipulates the routing table. Normally
a system routing table management daemon, such as
GATED or ROUTED, will tend to this task.
arp Controls and displays ARP tables for the specified
host.
For more information, see the help available at the TCPIP>
prompt. For example, to display ifconfig flags and parameters,
enter:
TCPIP> HELP ifconfig
| 12 - Routing |
Routing allows traffic from your local network to reach its
destination elsewhere on the internet. All hosts and gateways
on a network use routing protocols to exchange and store routing
information. Routing is simply the act of forwarding datagrams
based on information stored in a routing table.
The Compaq TCP/IP Services for OpenVMS product provides two types
of routing:
o Static
Because static routing requires manual configuration, it is
most useful when the number of gateways is limited and where
routes do not change frequently.
o Dynamic
Dynamic routing tables use information received by means of
routing protocol updates; when routes change, the routing
protocol provides information on the changes. Routing daemons
implement a routing policy, that is, the set of rules that
decide which routes go in to the routing table. A routing
daemon writes routing messages to a routing socket causing the
kernel to add a new route, delete an existing route, or modify
an existing route.
The kernel also generates routing messages that can be read by
any routing socket when events occur that may be of interest
to the process, for example, the interface has gone down or a
redirect has been received.
Compaq TCP/IP Services for OpenVMS implements two routing
daemons: the Routing Daemon (ROUTED) and the Gateway Routing
Daemon (GATED).
12.1 - ROUTED
ROUTED supports the Routing Information Protocol (RIP) Use
TCPIP$CONFIG to enable ROUTED.
12.2 - GATED
GATED supports interior and exterior gateway protocols. It
obtains information from several routing protocols and selects
the best routes based on that information.
Before enabling GATED, you must configure the GATED protocols
by editing the file TCPIP$GATED.CONF. Use TCPIP$CONFIG to enable
dynamic routing.
12. 2.1 - GATED Protocols
You can configure GATED to use one or more of the following
protocols:
Protocol RFC Description
Routing Information RFC RIP is a commonly used interior
Protocol (RIP) 1058, protocol that selects the route
Versions 1 and 2 RFC 1388 with the lowest metric (hop
count) as the best route.
Open Shortest Path RFC 1583 Another interior routing
First (OSPF) Version protocol, OSPF is a link-state
2 protocol (shortest path first)
and better suited than RIP for
use in complex networks with
many routers.
Exterior Gateway RFC 904 EGP exchanges reachability
Protocol (EGP) information between autonomous
systems. An autonomous system
is usually defined as a set
of routers under a single
administration, using an
interior gateway protocol and
common metric to route packets.
Autonomous systems use exterior
routing protocols to route
packets to other autonomous
systems.
Border Gateway RFCs Like EGP, BGP exchanges
Protocol (BGP) 1163, reachability information
1267, between autonomous systems
1654 but supports nonhierarchical
topologies. BGP uses path
attributes to provide more
information about each route.
Path attributes can include,
for example, administrative
preferences based on political,
organizational, or security
considerations.
Router Discovery RFC 1256 This protocol is used to inform
hosts of the availability of
hosts it can send packets to
and to supplement a statically
configured default router.
| 13 - Command Syntax |
Use the following rules when you type a command line:
o DCL and UNIX command formats
Most 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
o Keyword abbreviations
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
o 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.
Refer to each individual component for its specific command
syntax.
o Names and addresses
Unless otherwise stated, whenever you specify a host on a
command line, you can use its host name, a fully qualified
domain 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 enter 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:
or
$ 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:
o 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.
o Multiple values for parameters
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*.*
o Multiple values for qualifiers
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)
o Numeric values
Unless stated otherwise, all values are decimal.
o Brackets and braces Command format descriptions 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. Occasionally, you may need to specify
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.
$ 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 ]
| 14 - NSLOOKUP |
NSLOOKUP is a debugging tool provided with BIND that allows
anyone to directly query a name server and retrieve information.
Use NSLOOKUP to determine if your local name server is running
correctly or for retrieving information from remote servers.
NSLOOKUP makes direct queries to name servers around the world to
obtain DNS information, including:
o Host names and addresses on the local domain
o Host names and addresses on remote domains
o Host names that serve as mail exchangers (MX records)
o Name servers for a specific zone
14.1 - Starting and Stopping
NSLOOKUP Options shows how to start and stop NSLOOKUP.
Table 1-1 NSLOOKUP Options
Action Type This...
Run NSLOOKUP $ RUN SYS$SYSTEM:TCPIP$NSLOOKUP.EXE
Terminate > exit
NSLOOKUP
from within
interactive mode
Terminate the > Ctrl/z
current NSLOOKUP
session
Display online > HELP
help
To run NSLOOKUP as a foreign command, enter the following command
at the $ prompt or place the command in your login.com file:
$NSLOOKUP :== RUN SYS$SYSTEM:TCPIP$NSLOOKUP.EXE
You can then run an interactive NSLOOKUP session by entering:
$NSLOOKUP
>
You can put NSLOOKUP set commands in an initialization file,
SYS$LOGIN:NSLOOKUPINIT.INI. The commands are executed when you
start NSLOOKUP.
14.2 - Commands
NSLOOKUP:
o Command line must be less than 256 characters.
o Interprets unrecognized commands as host names.
o Is partly case-sensitive. It:
o Accepts lowercase
o Accepts uppercase
o Does not accept mixed case
When NSLOOKUP first starts, you see the name and address of the
default BIND server, followed by the NSLOOKUP prompt.
NSLOOKUP Commands lists the NSLOOKUP commands:
Table 1-2 NSLOOKUP Commands
Command Function
host [ server ] Looks up information using the current default
server or using the server you specify. Enter
the name of the host for which you need an IP
address.
server domain Changes the default server to the domain you
specify.
lserver domain Changes the default server.
root Changes the default server to server specified
by the root option.
ls Lists information about hosts in the domain
you specify. The default output contains host
names and their IP addresses. The options
for ls are listed in Options to the NSLOOKUP
Command.
help or ? Prints a summary of the available commands.
exit Exits NSLOOKUP.
set Selects the type of information that NSLOOKUP
displays.
14.3 - Default Options
NSLOOKUP has options which influence the type of information you
receive from a query and the way NSLOOKUP behaves. Some of the
options take a value and others are boolean options. The options
have default values and can be changed by using the set command.
You obtain a list of the options and their default values by
entering the set all command immediately after starting an
interactive NSLOOKUP session.
14.4 - Query Types
You can change the type of information output from a query: The
default query type is A.
14. 4.1 - A Type Query
This is the default NSLOOKUP querytype. It returns the name
and IP address of a host. The following NSLOOKUP session
shows a query for the host apple. The query to the server
condor.lgk.dec.com is successful and the server returns the IP
address 16.99.208.10.
$ nslookup
Default Server: condor.lgk.dec.com
Address: 16.99.208.53
> apple
Server: condor.lgk.dec.com
Address: 16.99.208.53
Name: apple.lgk.dec.com
Address: 16.99.208.10
>
If you enter a domain name without a trailing period, NSLOOKUP
appends the default domain to the name. You can change the
default domain with the set domain or set srchlist commands.
To lookup up a host not in the current domain, append a period to
the name as shown:
$NSLOOKUP apple.koz.dec.com.
14. 4.2 - PTR Type Query
To obtain the host name for an IP address, change the querytype
to PTR and enter the IP address as shown in the following
example:
> set type=ptr
> 16.99.208.189
Server: condor.lgk.dec.com
Address: 16.99.208.53
Name: dove.lgk.dec.com
Address: 16.99.208.189
You can also use the PTR querytype to obtain more information
about a domain as the following examples shows:
> lgk.dec.com
Server: condor.lgk.dec.com
Address: 16.99.208.53
lgk.dec.com
origin = condor.lgk.dec.com
mail addr = postmaster.lgk.dec.com
serial = 1998101948
refresh = 3600 (1H)
retry = 300 (5M)
expire = 604800 (1W)
minimum ttl = 43200 (12H)
>
14. 4.3 - MX Type Query
To obtain information about mail exchanger records, set the
querytype to MX and enter a domain. The output will tell you
which host(s) handles mail for the specified domain.
> set type=mx
> lgk.dec.com
Server: condor.lgk.dec.com
Address: 16.99.208.53
lgk.dec.com preference = 200, mail exchanger = crl.dec.com
lgk.dec.com preference = 50, mail exchanger = collie.lgk.dec.com
lgk.dec.com preference = 100, mail exchanger = mail13.digital.com
lgk.dec.com preference = 100, mail exchanger = mail11.digital.com
lgk.dec.com preference = 200, mail exchanger = mail2.digital.com
lgk.dec.com nameserver = collie.lgk.dec.com
lgk.dec.com nameserver = condor.lgk.dec.com
lgk.dec.com nameserver = hageln.lgk.dec.com
crl.dec.com internet address = 192.58.206.2
collie.lgk.dec.com internet address = 16.99.208.100
mail13.digital.com internet address = 192.208.46.30
mail2.digital.com internet address = 204.123.2.56
condor.lgk.dec.com internet address = 16.99.208.53
hageln.lgk.dec.com internet address = 16.99.208.10
14. 4.4 - SOA Type Query
The SOA querytype returns the domain's start-of-authority
information.
> set type=soa
> microsoft.com
Server: condor.lgk.dec.com
Address: 16.99.208.53
microsoft.com
origin = dns1.microsoft.com
mail addr = msnhst.microsoft.com
serial = 1998101204
refresh = 7200 (2H)
retry = 1800 (30M)
expire = 2592000 (4w2d)
minimum ttl = 86400 (1D)
microsoft.com nameserver = dns3.nwnet.net
microsoft.com nameserver = dns4.nwnet.net
microsoft.com nameserver = dns1.microsoft.com
microsoft.com nameserver = dns2.microsoft.com
microsoft.com nameserver = dns1.moswest.msn.net
microsoft.com nameserver = dns2.moswest.msn.net
dns3.nwnet.net internet address = 192.220.250.7
dns4.nwnet.net internet address = 192.220.251.7
dns1.microsoft.com internet address = 131.107.1.7
dns2.microsoft.com internet address = 131.107.1.240
14. 4.5 - NS Type Query
To obtain information about the name servers for a particular
zone, set the querytype to NS and then enter the desired zone.
The following example shows the nameservers for the microsoft.com
zone.
> set type=ns
> microsoft.com
Server: condor.lgk.dec.com
Address: 16.99.208.53
Non-authoritative answer:
microsoft.com nameserver = dns2.microsoft.com
microsoft.com nameserver = dns1.moswest.msn.net
microsoft.com nameserver = dns2.moswest.msn.net
microsoft.com nameserver = dns3.nwnet.net
microsoft.com nameserver = dns4.nwnet.net
microsoft.com nameserver = dns1.microsoft.com
Authoritative answers can be found from:
dns2.microsoft.com internet address = 131.107.1.240
dns3.nwnet.net internet address = 192.220.250.7
dns4.nwnet.net internet address = 192.220.251.7
dns1.microsoft.com internet address = 131.107.1.7
>
14.5 - Changing Servers
If you want to use another name server as your default server,
use the server command.
$ nslookup
Default Server: condor.klg.dec.com
Address: 16.99.208.53
> server ns01.koz.dec.com
Default Server: ns01.koz.dec.com
Address: 16.99.9.20
If for some reason the default server is not responding, you can
always use the lserver command to change the default server. The
lserver command uses the initial default name server to lookup
the IP address of the new server.
> lserver collie.klg.dec.com
Default Server: collie.klg.dec.com
Address: 16.99.208.10
Or, if you already know the IP address of the new server, you can
use the server command to reset the default server.
>server 16.99.208.10
> server 16.99.99.226
Default Server: beagel.zok.dec.com
Address: 16.99.99.226
14.6 - Listing Domain Information
The ls command lists information about a domain. This command is
useful for:
o Determining the number of hosts within a domain
o Hostnames and their IP addresses
o Troubleshooting DNS problems
Table 1-3 Options to the NSLOOKUP ls Command
Option Function
-a Lists aliases of hosts in the domain (CNAME entries)
-d Lists all the entries in the domain
-h Lists CPU and operating system information for the
domain (HINFO entries)
-m Lists mail exchangers (MX) entries in the domain
-s Lists well known services (WKS) in the domain
-t Lists a specified entry type
The following examples shows the use of the ls command to obtain
address records for all hosts within a zone.
> ls -t a lgk.dec.com
[condor.lgk.dec.com]
@ 12H IN A 16.99.208.208
dhcp-253 12H IN A 16.99.208.253
ucxv4a 12H IN A 16.99.208.129
beavis 12H IN A 16.99.208.90
boxmor 12H IN A 16.99.208.30
kempo 12H IN A 16.99.208.47
pacnet 12H IN A 16.99.208.84
kwai 12H IN A 16.99.208.63
alxica 12H IN A 16.99.9.37
ppponvms 12H IN A 16.99.208.104
a71kt 12H IN A 16.99.208.142
peteathome 12H IN A 16.99.208.101
larisa 12H IN A 16.99.208.49
pigdog 12H IN A 16.99.208.140
ntruder 12H IN A 16.99.208.110
In the following example, the ls command displays alias records
for hosts within the lgk.dec.com domain.
> ls -a lgk.dec.com
[condor.lgk.dec.com]
$ORIGIN LGK.DEC.COM.
celics 12H IN CNAME celtics
news 12H IN CNAME nntpd.KLG.DEC.COM.
tiger 12H IN CNAME ntruder
console 12H IN CNAME bblts.KLG.DEC.COM.
deebug 12H IN CNAME dot
ayla 12H IN CNAME ayla.KLG.DEC.COM.
cscibm 12H IN CNAME cscibm.KLG.DEC.COM.
>
Using the -m option obtains the MX records for hosts within the
lgk.dec.com domain which the following example shows.
> ls -m lgk.dec.com
brigit 12H IN MX 10 brigit
12H IN MX 100 mail1.digital.com.
12H IN MX 100 mail2.digital.com.
12H IN MX 200 crl.DEC.com.
piglet 12H IN MX 10 piglet
12H IN MX 100 mail1.digital.com.
12H IN MX 100 mail2.digital.com.
12H IN MX 200 crl.DEC.com.
tieta 12H IN MX 10 tieta
12H IN MX 100 mail1.digital.com.
12H IN MX 100 mail2.digital.com.
12H IN MX 200 crl.DEC.com.
sherry 12H IN MX 10 sherry
12H IN MX 100 mail1.digital.com.
12H IN MX 100 mail2.digital.com.
12H IN MX 200 crl.DEC.com.
In the following example, using the -s option displays the well
known services for a domain.
> ls -s lgk.dec.com
[condor.lgk.dec.com]
WKStesthave 12H IN WKS 16.99.208.255 21 ( )
WKStesthavenot 12H IN WKS 16.99.208.255 255 ( )
WKStestnumbers 12H IN WKS 16.99.208.255 255 ( 21 23 )
You can redirect the output from this command to a file which is
helpful when the domain consists of a large number of hosts. Once
the file is created, you can look at its contents with the DCL
TYPE command.
> ls -t a klg.dec.com > systems.txt
[condor.klg.dec.com]
#############
Received 932 answers (0 records).
$ TYPE SYSTEMS.TXT
> ls -t a klg.dec.com
[condor.klg.dec.com]
$ORIGIN KLG.DEC.COM.
@ 12H IN A 16.99.208.208
dhcp-253 12H IN A 16.99.208.253
ucxv4a 12H IN A 16.99.208.129
beavis 12H IN A 16.99.208.90
boxmor 12H IN A 16.99.208.30
kempo 12H IN A 16.99.208.47
pacnet 12H IN A 16.99.208.84
kwai 12H IN A 16.99.208.63
alxica 12H IN A 16.99.9.37
ppponvms 12H IN A 16.99.208.104
| 15 - Tracing |
The TCPTRACE utility lets you trace packet flow between the local
host and remote hosts. You can either monitor all packet flow
or use the various qualifiers to monitor only those packets of
interest.
15.1 - Starting
To start the TCPTRACE utility use the TCPTRACE command:
$ TCPTRACE HOST1 /FULL /PACKETS=30
15.2 - Stopping
To stop the TCPTRACE utility use CTRL/C.
| 16 - Programming Interfaces |
TCP/IP Services 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.
16.1 - 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.
16. 1.1 - 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)
16. 1. 1.1 - Arguments
auth_handle
An RPC authentication handle created by the authnone_create,
authunix_create, or authunix_create_default routine.
16. 1. 1.2 - 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.
16. 1. 1.3 - Return Values
None
16. 1.2 - authnone_create
Creates a authentication handle for passing null credentials and
verifiers to remote systems.
Format
#include <rpc/rpc.h>
AUTH *authnone_create ( )
16. 1. 2.1 - Arguments
None
16. 1. 2.2 - 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.
16. 1. 2.3 - Return Values
AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.
16. 1.3 - 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 );
16. 1. 3.1 - 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 parameter is ignored by the product's RPC
implementation.
aup_gids
A pointer to an array of groups to which the user belongs.
NOTE
This parameter is ignored by the product's RPC
implementation.
16. 1. 3.2 - 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.
16. 1. 3.3 - Return Values
AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.
16. 1.4 - authunix_create_default
Returns a default authentication handle.
Format
#include <rpc/rpc.h>
AUTH *authunix_create_default( )
16. 1. 4.1 - Arguments
None
16. 1. 4.2 - Description
Calls the authunix_create routine with the local host name,
effective process ID and group ID, and the process default
groups.
16. 1. 4.3 - Return Values
AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.
16. 1. 4.4 - 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.
16. 1.5 - 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);
16. 1. 5.1 - 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.
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.
16. 1. 5.2 - 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.
16. 1. 5.3 - 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.
16. 1.6 - 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);
16. 1. 6.1 - 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.
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.
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.
16. 1. 6.2 - 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.
16. 1. 6.3 - Return Values
RPC_SUCCESS Indicates success.
clnt_stat Returns the buffer of type enum clnt_stat
containing the status of the clnt_broadcast
operation.
16. 1.7 - 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);
16. 1. 7.1 - 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.
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 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.
16. 1. 7.2 - 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.
16. 1. 7.3 - Return Values
RPC_SUCCESS Indicates success.
clnt_stat Returns the buffer of type enum clnt_stat
containing the status of the clnt_call
operation.
16. 1.8 - 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);
16. 1. 8.1 - 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.
16. 1. 8.2 - 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.
16. 1. 8.3 - Return Values
TRUE Success
FALSE Failure
16. 1.9 - 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);
16. 1. 9.1 - 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.
16. 1. 9.2 - 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.
16. 1. 9.3 - 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.
16. 1.10 - 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);
16. 1. 10.1 - 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.
16. 1. 10.2 - 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.
16. 1. 10.3 - 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.
16. 1.11 - clnt_destroy
A macro that frees the memory associated with an RPC client
handle.
Format
#include <rpc/rpc.h>
void clnt_destroy(CLIENT *handle);
16. 1. 11.1 - Arguments
handle
A pointer to a client handle created by any of the client handle
creation routines.
16. 1. 11.2 - 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.
16. 1. 11.3 - Return Values
None
16. 1.12 - 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);
16. 1. 12.1 - 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.
16. 1. 12.2 - Description
The clnt_freeres routine calls the xdr_free routine to deallocate
the memory where the remote procedure's results are stored.
16. 1. 12.3 - Return Values
TRUE Success.
FALSE Error occurred while freeing the memory.
16. 1.13 - 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);
16. 1. 13.1 - 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.
16. 1. 13.2 - Description
This macro copies the error information from the client handle
to the structure referenced by errp. The macro is mainly for
diagnostic use.
16. 1. 13.3 - Return Values
None
16. 1.14 - 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);
16. 1. 14.1 - Arguments
sp
A pointer to a string to be used as the beginning of the error
message.
16. 1. 14.2 - 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.
16. 1. 14.3 - Return Values
None
16. 1.15 - 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) ;
16. 1. 15.1 - Arguments
stat
A buffer containing status information.
16. 1. 15.2 - 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.
16. 1. 15.3 - Return Values
None
16. 1.16 - clnt_perror
Prints a message explaining why an ONC RPC routine failed.
Format
#include <rpc/rpc.h>
void clnt_perror(CLIENT *handle, char *sp);
16. 1. 16.1 - 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.
16. 1. 16.2 - Description
Prints a message to standard error indicating why an ONC RPC call
failed. The message is prepended with string sp and a colon.
16. 1. 16.3 - Return Values
None
16. 1.17 - clnt_spcreateerror
Returns a message indicating why RPC could not create a client
handle.
Format
#include <rpc/rpc.h>
char *clnt_spcreateerror(char *sp);
16. 1. 17.1 - Arguments
sp
A pointer to a string to be used as the beginning of the error
message.
16. 1. 17.2 - 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.
16. 1. 17.3 - 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.
16. 1.18 - 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);
16. 1. 18.1 - Arguments
stat
A buffer containing status information.
16. 1. 18.2 - 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.
16. 1. 18.3 - Return Values
char * A pointer to the message string terminated
with a NULL character.
16. 1.19 - clnt_sperror
Returns a message indicating why an ONC RPC routine failed.
Format
#include <rpc/rpc.h>
char *clnt_sperror(CLIENT *handle, char *sp);
16. 1. 19.1 - 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.
16. 1. 19.2 - 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.
16. 1. 19.3 - 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.
16. 1.20 - 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);
16. 1. 20.1 - Arguments
prognum
The program number associated with the remote program.
versnum
The version number associated with the remote program.
16. 1. 20.2 - 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.
16. 1. 20.3 - Return Values
CLIENT * A pointer to a client handle.
NULL Indicates failure.
16. 1.21 - 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);
16. 1. 21.1 - 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.
16. 1. 21.2 - 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.
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.
16. 1. 21.3 - Return Values
CLIENT * A pointer to the client handle.
NULL Indicates failure.
16. 1.22 - 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);
16. 1. 22.1 - 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.
16. 1. 22.2 - 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.
16. 1. 22.3 - Return Values
CLIENT * A pointer to the client handle.
NULL Indicates failure.
16. 1.23 - 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);
16. 1. 23.1 - 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.
16. 1. 23.2 - 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.
16. 1. 23.3 - Return Values
CLIENT * A pointer to the client handle.
NULL Indicates failure.
16. 1.24 - get_myaddress
Returns the local host's internet address.
Format
#include <rpc/rpc.h>
void get_myaddress(struct sockaddr_in *addr);
16. 1. 24.1 - 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.
16. 1. 24.2 - Description
Puts the local host's internet address into addr without doing
any name translation. The port number is always set to htons
(PMAPPORT).
16. 1. 24.3 - Return Values
None
16. 1.25 - 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);
16. 1. 25.1 - 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.
16. 1. 25.2 - 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.
16. 1. 25.3 - Return Values
None
16.2 - 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.
16. 2.1 - 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);
16. 2. 1.1 - Arguments
addr
A pointer to a sockaddr_in structure containing the internet
address of the host whose Portmapper you wish to call.
16. 2. 1.2 - 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 SHOW PORTMAPPER management command
uses this routine.
16. 2. 1.3 - Return Values
struct pmaplist * A pointer to the returned list of server-to-
port mappings on host addr.
NULL Indicates failure.
16. 2.2 - pmap_getmaps_vms
Returns a copy of the current port mappings on a remote host
running TCP/IP Services software.
Format
#include <rpc/pmap_clnt.h>
struct pmaplist_vms *pmap_getmaps_vms(struct sockaddr_in
*addr);
16. 2. 2.1 - Arguments
addr
A pointer to a sockaddr_in structure containing the internet
address of the host whose Portmapper you wish to call.
16. 2. 2.2 - 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 TCP/IP Services hosts.
16. 2. 2.3 - Return Values
struct pmaplist * A pointer to the returned list of server-to-
port mappings on host addr.
NULL Indicates failure.
16. 2.3 - 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 );
16. 2. 3.1 - 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.
protocol
The transport protocol that the remote procedure uses. Specify
either IPPROTO_UDP or IPPROTO_TCP.
16. 2. 3.2 - 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.
16. 2. 3.3 - 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.
16. 2.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 );
16. 2. 4.1 - 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.
16. 2. 4.2 - 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.
16. 2. 4.3 - Return Values
enum clnt_stat Returns the buffer containing the status of
the operation.
16. 2.5 - 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);
16. 2. 5.1 - 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.
16. 2. 5.2 - 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.
16. 2. 5.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 2.6 - 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);
16. 2. 6.1 - Arguments
prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.
16. 2. 6.2 - Description
A server interface to the Portmapper, which destroys all mapping
between the triple [prognum, versnum, *] and ports on the local
host's Portmapper.
16. 2. 6.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16.3 - RPC Server Routines
Server routines allow C programs to receive procedure calls from
client programs over the network.
16. 3.1 - 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 );
16. 3. 1.1 - 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.
16. 3. 1.2 - 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.
16. 3. 1.3 - Return Values
0 Indicates success.
-1 Indicates failure.
16. 3.2 - 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);
16. 3. 2.1 - 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.
16. 3. 2.2 - Description
Given a reply message, seterr_reply fills in the error field.
16. 3. 2.3 - Return Values
None
16. 3.3 - svc_destroy
A macro that frees the memory associated with an RPC server
handle.
Format
#include <rpc/rpc.h>
void svc_destroy(SVCXPRT *xprt);
16. 3. 3.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
16. 3. 3.2 - 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.
16. 3. 3.3 - Return Values
None
16. 3.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);
16. 3. 4.1 - 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.
16. 3. 4.2 - 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.
16. 3. 4.3 - Return Values
TRUE Success; memory successfully deallocated.
FALSE Failure; memory not deallocated.
16. 3.5 - 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);
16. 3. 5.1 - 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.
16. 3. 5.2 - Description
This routine calls the specified XDR routine to decode the
arguments passed to the service procedure.
16. 3. 5.3 - Return Values
TRUE Successfully decoded.
FALSE Decoding unsuccessful.
16. 3.6 - 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);
16. 3. 6.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
16. 3. 6.2 - Description
This routine returns a sockaddr_in structure containing the
internet address of the RPC client routine that called the
service procedure.
16. 3. 6.3 - Return Values
struct sockaddr_ A pointer to the socket descriptor.
in
16. 3.7 - svc_getreqset
Returns data for each server connection.
Format
#include <rpc/rpc.h>
void svc_getreqset(fd_set *rdfds);
16. 3. 7.1 - Arguments
rdfds
A pointer to the read file descriptor bit mask modified by the
select routine.
16. 3. 7.2 - 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.
16. 3. 7.3 - 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);
}
16. 3. 7.4 - Return Values
None
16. 3.8 - 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);
16. 3. 8.1 - 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.
16. 3. 8.2 - 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.
16. 3. 8.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 3.9 - 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();
16. 3. 9.1 - Arguments
None
16. 3. 9.2 - 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.
16. 3. 9.3 - Return Values
Never returns
16. 3.10 - 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);
16. 3. 10.1 - 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.
16. 3. 10.2 - Description
Called by an ONC RPC service's dispatch routine to send the
results of a remote procedure call.
16. 3. 10.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 3.11 - 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);
16. 3. 11.1 - Arguments
prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.
16. 3. 11.2 - Description
Removes all mapping of the double [prognum, versnum] to dispatch
routines, and of the triple [prognum, versnum, *] to port number.
16. 3. 11.3 - Return Values
None
16. 3.12 - svcerr_auth
Sends an authentication error to the client.
Format
#include <rpc/rpc.h>
void svcerr_auth(SVCXPRT *xprt, enum auth_stat why);
16. 3. 12.1 - 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.
16. 3. 12.2 - Description
Called by a service dispatch routine that refuses to perform a
remote procedure call due to an authentication error.
16. 3. 12.3 - Return Values
None
16. 3.13 - 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);
16. 3. 13.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
16. 3. 13.2 - Description
Called by a service dispatch routine that cannot successfully
decode its parameters. See also the svc_getargs routine.
16. 3. 13.3 - Return Values
None
16. 3.14 - 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);
16. 3. 14.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
16. 3. 14.2 - Description
Called by a service dispatch routine that does not implement the
procedure number that the client requested.
16. 3. 14.3 - Return Values
None
16. 3.15 - 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);
16. 3. 15.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
16. 3. 15.2 - 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.
16. 3. 15.3 - Return Values
None
16. 3.16 - 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);
16. 3. 16.1 - 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.
16. 3. 16.2 - 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.
16. 3. 16.3 - Return Values
None
16. 3.17 - 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);
16. 3. 17.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
16. 3. 17.2 - 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.
16. 3. 17.3 - Return Values
None
16. 3.18 - 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);
16. 3. 18.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
16. 3. 18.2 - 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).
16. 3. 18.3 - Return Values
None
16. 3.19 - svcraw_create
Creates a server handle for memory-based ONC RPC for simple
testing and timing.
Format
#include <rpc/rpc.h>
SVCXPRT *svcraw_create();
16. 3. 19.1 - Arguments
None
16. 3. 19.2 - 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.
16. 3. 19.3 - Return Values
SVCXPRT * A pointer to an RPC server handle for the
in-memory transport.
NULL Indicates failure.
16. 3.20 - 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);
16. 3. 20.1 - 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.
16. 3. 20.2 - 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.
16. 3. 20.3 - Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
16. 3.21 - 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);
16. 3. 21.1 - 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.
16. 3. 21.2 - 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).
16. 3. 21.3 - Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
16. 3.22 - 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);
16. 3. 22.1 - 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.
16. 3. 22.2 - 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).
16. 3. 22.3 - Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
16. 3.23 - 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);
16. 3. 23.1 - 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.
16. 3. 23.2 - 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).
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.
16. 3. 23.3 - Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
16. 3.24 - 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);
16. 3. 24.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
16. 3. 24.2 - 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.
16. 3. 24.3 - Return Values
None
16. 3.25 - 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);
16. 3. 25.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
16. 3. 25.2 - 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.
16. 3. 25.3 - Return Values
None
16. 3.26 - _authenticate
Authenticates the request message.
Format
#include <rpc/rpc.h>
enum auth_stat _authenticate(struct svc_req *rqst, struct
rpc_msg *msg);
16. 3. 26.1 - 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.
16. 3. 26.2 - 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.
16. 3. 26.3 - 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
16.4 - 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.
16. 4.1 - xdr_accepted_reply
Serializes and deserializes a message-accepted indication in an
RPC reply message.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply
*arp);
16. 4. 1.1 - 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.
16. 4. 1.2 - 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.
16. 4. 1.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure to encode the message.
16. 4.2 - xdr_array
Serializes and deserializes the elements of a variable-length
array.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_array(XDR *xdrs, char **arrp, u_int *sizep, u_int
maxsize, u_int elsize, xdrproc_t elproc);
16. 4. 2.1 - 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.
16. 4. 2.2 - Description
A filter primitive that translates between variable-length arrays
and their corresponding external representations.
16. 4. 2.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.3 - xdr_authunix_parms
Serializes and deserializes credentials in an authentication
parameter structure.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_authunix_parms (XDR *xdrs, struct authunix_parms
*authp);
16. 4. 3.1 - 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.
16. 4. 3.2 - Description
Used for externally describing standard UNIX credentials. On a
TCP/IP Services 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.
16. 4. 3.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.4 - xdr_bool
Serializes and deserializes boolean data.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_bool (XDR *xdrs, bool_t *bp);
16. 4. 4.1 - 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.
16. 4. 4.2 - 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.
16. 4. 4.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.5 - xdr_bytes
Serializes and deserializes a counted byte array.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_bytes (XDR *xdrs, char **bpp, u_int *sizep, u_int
maxsize);
16. 4. 5.1 - 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.
16. 4. 5.2 - 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.
16. 4. 5.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.6 - xdr_callhdr
Serializes and deserializes the static part of a call message
header.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_callhdr(XDR *xdrs, struct rpc_msg *chdrp);
16. 4. 6.1 - 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.
16. 4. 6.2 - 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.
16. 4. 6.3 - Return Values
TRUE Indicate success.
FALSE Indicates failure.
16. 4.7 - xdr_callmsg
Serializes and deserializes an ONC RPC call message.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsgp);
16. 4. 7.1 - 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.
16. 4. 7.2 - 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.
16. 4. 7.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.8 - xdr_char
Serializes and deserializes character data.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_char(XDR *xdrs, char *cp);
16. 4. 8.1 - 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.
16. 4. 8.2 - Description
A filter primitive that translates between internal
representations of characters and their XDR representations.
16. 4. 8.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.9 - xdr_double
Serializes and deserializes VAX and IEEE double-precision
floating-point numbers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_double(XDR *xdrs, double *dp);
16. 4. 9.1 - 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.
16. 4. 9.2 - 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.
16. 4. 9.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.10 - xdr_enum
Serializes and deserializes enumerations.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_enum(XDR *xdrs, enum_t *ep);
16. 4. 10.1 - 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.
16. 4. 10.2 - Description
A filter primitive that translates between enumerations (actually
integers) and their external representations.
16. 4. 10.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.11 - xdr_float
Serializes and deserializes VAX and IEEE single-precision
floating-point numbers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_float(XDR *xdrs, float *fp);
16. 4. 11.1 - 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.
16. 4. 11.2 - 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.
16. 4. 11.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.12 - xdr_free
Deallocates the memory associated with the indicated data
structure.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_free(xdrproc_t proc, char *objp);
16. 4. 12.1 - Arguments
proc
The XDR routine for the data structure being freed.
objp
A pointer to the data structure to be freed.
16. 4. 12.2 - 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.
16. 4. 12.3 - Return Values
TRUE Indicate success.
FALSE Indicates failure.
16. 4.13 - xdr_hyper
Serializes and deserializes VAX quadwords (known in XDR as hyper-
integers).
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_hyper(XDR *xdrs, quad *hp);
16. 4. 13.1 - 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.
16. 4. 13.2 - Description
A filter primitive that translates between hyper-integers and
their external representations.
16. 4. 13.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.14 - xdr_int
Serializes and deserializes integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_int(XDR *xdrs, int *ip);
16. 4. 14.1 - 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.
16. 4. 14.2 - Description
A filter primitive that translates between integers and their
external representations.
16. 4. 14.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.15 - xdr_long
Serializes and deserializes long integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_long(XDR *xdrs, long *lp);
16. 4. 15.1 - 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.
16. 4. 15.2 - Description
A filter primitive that translates between long integers and
their external representations.
16. 4. 15.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.16 - xdr_opaque
Serializes and deserializes opaque structures.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_opaque(XDR *xdrs, char *op, u_int cnt);
16. 4. 16.1 - 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.
16. 4. 16.2 - 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.
16. 4. 16.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.17 - xdr_opaque_auth
Serializes and deserializes ONC RPC authentication information
message.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *authp);
16. 4. 17.1 - 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.
16. 4. 17.2 - Description
Translates ONC RPC authentication information messages. This
routine is useful for users who want to generate messages without
using the ONC RPC package.
16. 4. 17.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.18 - xdr_pmap_#
Serializes and deserializes Portmapper parameters.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_pmap(XDR *xdrs, struct pmap *regs);
16. 4. 18.1 - 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.
16. 4. 18.2 - 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.
16. 4. 18.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.19 - xdr_pmap_vms
Serializes and deserializes OpenVMS-specific Portmapper
parameters.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_pmap_vms(XDR *xdrs, struct pmap_vms *regs);
16. 4. 19.1 - 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.
16. 4. 19.2 - Description
This routine is similar to xdr_pmap(), except it also includes
the process identification in the pmap_vms structure.
16. 4. 19.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.20 - xdr_pmaplist_#
Serializes and deserializes a list of Portmapper port mappings.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rpp);
16. 4. 20.1 - 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.
16. 4. 20.2 - 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.
16. 4. 20.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.21 - xdr_pmaplist_vms
Serializes and deserializes a list of Portmapper port mappings
for OpenVMS systems.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_pmaplist_vms (XDR *xdrs, struct pmaplist_vms
**rpp);
16. 4. 21.1 - 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.
16. 4. 21.2 - Description
This routine is similar to the xdr_pmaplist routine, except it
also includes the process identification in the pmaplist_vms
structure.
16. 4. 21.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.22 - xdr_pointer
Serializes and deserializes indirect pointers and the data being
pointed to.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_pointer(XDR *xdrs, char **objpp, u_int objsize,
xdrproc_t objproc);
16. 4. 22.1 - 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.
16. 4. 22.2 - 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.
16. 4. 22.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.23 - xdr_reference
Serializes and deserializes indirect pointers and the data being
pointed to.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_reference(XDR *xdrs, char **objpp, u_int objsize,
xdrproc_t objproc);
16. 4. 23.1 - 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.
16. 4. 23.2 - Description
A primitive that provides pointer chasing within structures.
16. 4. 23.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.24 - xdr_rejected_reply
Serializes and deserializes the remainder of an RPC reply message
after the header indicates that the reply is rejected.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply
*rrp);
16. 4. 24.1 - 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.
16. 4. 24.2 - Description
Describes ONC RPC reply messages. This routine is useful for
users who want to generate messages without using the ONC RPC
package.
16. 4. 24.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.25 - xdr_replymsg
Serializes and deserializes the RPC reply header and then calls
the appropriate routine to interpret the rest of the message.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsgp);
16. 4. 25.1 - 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.
16. 4. 25.2 - 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.
16. 4. 25.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.26 - xdr_short
Serializes and deserializes short integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_short(XDR *xdrs, short *sp);
16. 4. 26.1 - 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.
16. 4. 26.2 - Description
A filter primitive that translates between short integers and
their external representations.
16. 4. 26.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.27 - xdr_string
Serializes and deserializes strings (arrays of bytes terminated
by a NULL character).
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_string(XDR *xdrs, char **spp, u_int maxsize);
16. 4. 27.1 - 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.
16. 4. 27.2 - 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.
16. 4. 27.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.28 - xdr_u_char
Serializes and deserializes unsigned characters.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_u_char(XDR *xdrs, char *ucp);
16. 4. 28.1 - 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.
16. 4. 28.2 - Description
A filter primitive that translates between internal
representation of unsigned characters and their XDR
representations.
16. 4. 28.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.29 - xdr_u_hyper
Serializes and deserializes unsigned VAX quadwords (known in XDR
as hyper-integers).
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_u_hyper(XDR *xdrs, unsigned quad *uhp);
16. 4. 29.1 - 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.
16. 4. 29.2 - Description
A filter primitive that translates between unsigned hyper-
integers and their external representations.
16. 4. 29.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.30 - xdr_u_int
Serializes and deserializes unsigned integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_u_int(XDR *xdrs, unsigned *uip);
16. 4. 30.1 - 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.
16. 4. 30.2 - Description
A filter primitive that translates between unsigned integers and
their external representations.
16. 4. 30.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.31 - xdr_u_long
Serializes and deserializes unsigned long integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp);
16. 4. 31.1 - 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.
16. 4. 31.2 - Description
A filter primitive that translates between unsigned long integers
and their external representations.
16. 4. 31.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.32 - xdr_u_short
Serializes and deserializes unsigned short integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_u_short(XDR *xdrs, unsigned short *usp);
16. 4. 32.1 - 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.
16. 4. 32.2 - Description
A filter primitive that translates between unsigned short
integers and their external representations.
16. 4. 32.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.33 - xdr_union
Serializes and deserializes discriminant unions.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_union(XDR *xdrs, enum *dscmp, char *unp, struct
xdr_discrim *choices, xdrproc_t default);
16. 4. 33.1 - 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.
16. 4. 33.2 - 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).
16. 4. 33.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.34 - xdr_vector
Serializes and deserializes the elements of a fixed-length array
(known as a vector).
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_vector(XDR *xdrs, char **vecpp, u_int elnum, u_int
elsize, xdrproc_t elproc);
16. 4. 34.1 - 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.
16. 4. 34.2 - Description
A routine that calls elproc to prepare the elements of an array
for XDR messages.
16. 4. 34.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.35 - 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 <tcpip$rpcxdr.h>
bool_t xdr_void();
16. 4. 35.1 - 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.
16. 4. 35.2 - Return Values
This routine always returns TRUE.
16. 4.36 - xdr_wrapstring
Serializes and deserializes NULL-terminated strings.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_wrapstring(XDR *xdrs, char **spp);
16. 4. 36.1 - 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.
16. 4. 36.2 - 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.
16. 4. 36.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.37 - xdrmem_create
Initializes an XDR stream descriptor for a memory buffer.
Format
#include <tcpip$rpcxdr.h>
void xdrmem_create(XDR *xdrs, char *addr, u_int size, enum
xdr_op op);
16. 4. 37.1 - 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.
16. 4. 37.2 - Description
The stream handle xdrs is initialized with the operation op, the
buffer addr and size, and the operations context for an xdrmem
stream.
16. 4. 37.3 - Return Values
None
16. 4.38 - xdrrec_create
Initializes a record-oriented XDR stream descriptor.
Format
#include <tcpip$rpcxdr.h>
void xdrrec_create(XDR *xdrs, u_int sendsize, u_int recvsize,
char *tcp_handle, int (*readit)(), int (*writeit)());
16. 4. 38.1 - 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.
16. 4. 38.2 - 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.
16. 4. 38.3 - Return Values
None
16. 4.39 - xdrrec_endofrecord
Generates an end-of-record for an XDR record.
Format
#include <tcpip$rpcxdr.h>
bool_t xdrrec_endofrecord (XDR *xdrs, bool_t sendnow);
16. 4. 39.1 - 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.
16. 4. 39.2 - Description
This routine lets an application support batch calls and
pipelined procedure calls.
16. 4. 39.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.40 - 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 <tcpip$rpcxdr.h>
bool_t xdrrec_eof (XDR *xdrs);
16. 4. 40.1 - Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
16. 4. 40.2 - Description
Returns TRUE if there is no more input in the buffer after
consuming the rest of the current record.
16. 4. 40.3 - Return Values
TRUE Indicates no more input in the buffer.
FALSE Indicates more input in the buffer.
16. 4.41 - xdrrec_skiprecord
Guarantees proper record alignment during deserialization from an
incoming stream.
Format
#include <tcpip$rpcxdr.h>
bool_t xdrrec_skiprecord (XDR *xdrs);
16. 4. 41.1 - Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream handle creation routines.
16. 4. 41.2 - 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.
16. 4. 41.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
16. 4.42 - xdrstdio_create
Initializes a stdio XDR stream.
Format
#include <tcpip$rpcxdr.h>
void xdrstdio_create (XDR *xdrs, FILE *file, enum xdr_op op);
16. 4. 42.1 - 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.
16. 4. 42.2 - Description
Initializes a stdio stream for the specified file.
16. 4. 42.3 - Return Values
None
16.5 - Sockets API
This section describes functions that comprise the Sockets API
and that are supported by TCP/IP Services.
16. 5.1 - 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 );
16. 5. 1.1 - Arguments
s
A socket descriptor returned by socket(), subsequently bound to
an address with bind(), which 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 Compaq C supports only the internet domain (AF_INET).
addrlen
A value/result argument. 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 sockaddr structure that has been
filled in by the Communications layer.
16. 5. 1.2 - Description
This function 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 (SOCK_STREAM).
Related Functions
See also bind(), connect(), listen(), select(), and socket().
16. 5. 1.3 - Return Values
x A nonnegative integer that is a descriptor for
the accepted socket.
-1 Error; errno is set to indicate the error.
16. 5. 1.4 - Errors
EBADF The socket descriptor is invalid.
ECONNABORTED A connection has been aborted.
EFAULT The addr argument is not in a writable part of
the user address space.
EINTR The accept() function was interrupted by a
signal before a valid connection arrived.
EINVAL The socket is not accepting connections.
EMFILE There are too many open file descriptors.
ENFILE The maximum number of file descriptors in the
system is already open.
ENETDOWN TCP/IP Services was not started.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system was unable to allocate kernel
memory.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The reference socket is not of type SOCK_
STREAM.
EPROTO A protocol error occurred.
EWOULDBLOCK The socket is marked nonblocking, and no
connections are present to be accepted.
16. 5.2 - 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 );
16. 5. 2.1 - Arguments
s
A socket descriptor created with the socket() function.
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.
16. 5. 2.2 - Description
This function assigns a port number and IP address to an unnamed
socket. When a socket is created with the socket() function, it
exists in a name space (address family) but has no name assigned.
The bind() function requests that a name be assigned to the
socket.
Related Functions
See also connect(), getsockname(), listen(), and socket().
16. 5. 2.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
16. 5. 2.4 - Errors
EACCESS The requested address is protected, and the
current user has inadequate permission to
access it.
EADDRINUSE The specified internet address and ports are
already in use.
EADDRNOTAVAIL The specified address is not available from
the local machine.
EAFNOSUPPORT The specified address is invalid for the
address family of the specified socket.
EBADF The socket descriptor is invalid.
EDESTADDRREQ The address argument is a null pointer.
EFAULT The name argument is not a valid part of the
user address space.
EINVAL The socket is already bound to an address and
the protocol does not support binding to a new
address, the socket has been shut down, or the
length or the namelen argument is invalid for
the address family.
EISCONN The socket is already connected.
EISDIR The address argument is a null pointer.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket type of the specified socket does
not support binding to an address.
16. 5.3 - close()
Closes a connection and deletes a socket descriptor.
The $QIO equivalent is the $DASSGN system service.
Format
#include <unixio.h>
int close ( s );
16. 5. 3.1 - Argument
s
A socket descriptor.
16. 5. 3.2 - Description
This function deletes a descriptor from the per-process object
(Compaq C structure) reference table. Associated TCP connections
close first.
If a call to the connect() function fails for a connection mode
socket, applications should use close() to deallocate the socket
and descriptor.
Related Functions
See also accept(), socket(), and write().
16. 5. 3.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
16. 5. 3.4 - Errors
EBADF The socket descriptor is invalid.
EINTR The close() function was interrupted by a
signal that was caught.
16. 5.4 - 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 );
16. 5. 4.1 - 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.
16. 5. 4.2 - Description
If s is a socket descriptor of type SOCK_DGRAM, then this call
permanently specifies the peer where the data is sent. If s is of
type SOCK_STREAM, then this call attempts to make a connection to
the specified socket.
Each communications space interprets the name argument. This
argument specifies the socket that is connected to the socket
specified in s.
If the connect() function fails for a connection-mode socket,
applications should use the close() function to deallocate
the socket and descriptor. If attempting to reinitiate the
connection, applications should create a new socket.
Related Functions
See also accept(), select(), socket(), getsockname(), and
shutdown().
16. 5. 4.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
16. 5. 4.4 - Errors
EADDRINUSE Configuration problem. There are insufficient
ports available for the attempted connection.
The ipport_userreserved variable of the inet
subsystem should be increased.
EADDRNOTAVAIL The specified address is not available from
the local machine.
EAFNOSUPPORT The addresses in the specified address family
cannot be used with this socket.
EALREADY A connection request is already in progress
for the specified socket.
EBADF The socket descriptor is invalid.
ECONNREFUSED The attempt to connect was rejected.
EFAULT The name argument is not a valid part of the
user address space.
EHOSTUNREACH The specified host is not reachable.
EINPROGRESS O_NONBLOCK is set for the file descriptor
for the socket, and the connection cannot be
immediately established; the connection will
be established asynchronously.
EINTR The connect() function was interrupted by a
signal while waiting for the connection to be
established. Once established, the connection
may continue asynchronously.
EINVAL The value of the namelen argument is invalid
for the specified address family, or the sa_
family field in the socket address structure
is invalid for the protocol.
EISCONN The socket is already connected.
ELOOP Too many symbolic links were encountered in
translating the file specification in the
address.
ENETDOWN The local network connection is not
operational.
ENETUNREACH No route to the network or host is present.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket is listening and cannot be
connected.
EPROTOTYPE The specified address has a different type
than the socket bound to the specified peer
address.
ETIMEDOUT The connection request timed out without
establishing a connection.
EWOULDBLOCK The socket is nonblocking, and the connection
cannot be completed immediately. It is
possible to use the select() function to
select the socket for writing.
16. 5.5 - decc$get_sdc()
Returns the socket device channel (SDC) associated with a socket
descriptor.
Format
#include <socket.h>
short int decc$get_sdc ( int s );
16. 5. 5.1 - Argument
s
A socket descriptor.
16. 5. 5.2 - Description
This function returns the SDC associated with a socket. Normally,
socket descriptors are used either as file descriptors or with
one of the functions that takes an explicit socket descriptor as
its argument. Sockets are implemented using TCP/IP socket device
channels. This function 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).
16. 5. 5.3 - Return Values
0 Indicates that s is not an open socket
descriptor.
x The SDC number.
16. 5.6 - gethostbyaddr()
Searches the hosts database sequentially from the beginning for a
host record with a given IPv4 address.
The $QIO equivalent is the IO$_ACPCONTROL function with the
INETACP_FUNC$C_GETHOSTBYADDR subfunction code.
Format
#include <netdb.h>
struct hostent *gethostbyaddr ( const void *addr, size_t len,
int type );
16. 5. 6.1 - Arguments
addr
A pointer to a series of bytes in network order specifying the
address of the host sought.
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.
16. 5. 6.2 - Description
This function finds the first host record in the hosts database
with the given address.
The gethostbyaddr() function uses a common static area for its
return values. This means that subsequent calls to this function
overwrite previously returned host entries. You must make a copy
of the host entry if you want to save it.
16. 5. 6.3 - Return Values
NULL Indicates an error; errno is set to one of the
following values.
x A pointer to an object having the hostent
structure.
16. 5. 6.4 - Errors
ENETDOWN TCP/IP Services was not started.
HOST_NOT_FOUND Host is unknown.
NO_DATA The server recognized the request and the
name, but no address is available for the
name. Another type of name server request may
be successful.
NO_RECOVERY An unexpected server failure occurred. This is
a nonrecoverable error.
TRY_AGAIN A transient error occurred, for example,
the server did not respond. A retry may be
successful.
16. 5.7 - gethostbyname()
Searches the hosts database sequentially from the beginning for a
host record with a given name or alias.
This function 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 );
16. 5. 7.1 - Argument
name
A pointer to a null-terminated character string containing the
name or an alias of the host being sought.
16. 5. 7.2 - Description
This function finds the first host in the hosts database with the
given name or alias.
The gethostbyname() function uses a common static area for its
return values. This means that subsequent calls to this function
overwrite previously returned host entries. You must make a copy
of the host entry if you want to save it.
16. 5. 7.3 - Return Values
NULL Indicates an error.
x A pointer to an object having the hostent
structure.
16. 5. 7.4 - Errors
ENETDOWN TCP/IP Services was not started.
HOST_NOT_FOUND Host is unknown.
NO_DATA The server recognized the request and the
name, but no address is available for the
name. Another type of name server request may
be successful.
NO_RECOVERY An unexpected server failure occurred. This is
a nonrecoverable error.
TRY_AGAIN A transient error occurred, for example,
the server did not respond. A retry may be
successful.
16. 5.8 - gethostname()
Returns the fully qualified name of the local host.
Format
#include <types.h>
#include <socket.h>
int gethostname ( char *name, int namelen) ;
16. 5. 8.1 - 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.
16. 5. 8.2 - Description
This function returns the translation of the logical names
TCPIP$INET_HOST and TCPIP$INET_DOMAIN when used with the TCP/IP
Services software.
16. 5. 8.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
16. 5. 8.4 - Errors
EFAULT The buffer described by name and namelen is
not a valid, writable part of the user address
space.
16. 5.9 - getnetbyaddr()
Searches the network database sequentially from the beginning 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) ;
16. 5. 9.1 - Arguments
net
The network number, in host byte order, of the networks database
entry required.
type
The type of network being sought (AF_INET).
16. 5. 9.2 - Description
This function finds the first network record in the networks
database with the given address.
The getnetbyaddr() and getnetbyname() functions use a common
static area for their return values. Subsequent calls to any of
these functions overwrite any previously returned network entry.
You must make a copy of the network entry if you want to save it.
16. 5. 9.3 - Return Values
NULL Indicates end of file or an error.
x A pointer to an object having the netent
structure.
16. 5. 9.4 - Errors
EINVAL The net argument is invalid.
ESRCH The search failed.
16. 5.10 - getnetbyname()
Searches the networks database sequentially from the beginning
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 );
16. 5. 10.1 - Argument
name
A pointer to a null-terminated character string containing either
the network name or an alias for the network name.
16. 5. 10.2 - Description
This function finds the first network record in the networks
database with the given name or alias.
The getnetbyaddr() and getnetbyname() functions use a common
static area for their return values. Subsequent calls to any of
these functions overwrite previously returned network entries.
You must make a copy of the network entry if you want to save it.
16. 5. 10.3 - Return Values
NULL Indicates end of file or an error.
x A pointer to an object having the netent
structure.
16. 5. 10.4 - Errors
EFAULT The buffer described by name is not a valid,
writable part of the user address space.
EINVAL The net or net_data argument is invalid.
ESRCH The search failed.
16. 5.11 - getpeername()
Returns the name of the connected peer.
The $QIO equivalent is the IO$_SENSEMODE function with the p4
argument.
Format
#include <types.h>
#include <socket.h>
int getpeername ( int s, struct sockaddr *name, int *namelen
);
16. 5. 11.1 - Arguments
s
A socket descriptor created using socket().
name
A pointer to a buffer where the peer name is to be returned.
namelen
An address of an integer that specifies the size of the name
buffer. On return, it is modified to reflect the actual length,
in bytes, of the name returned.
16. 5. 11.2 - Description
This function returns the name of the peer connected to the
specified socket descriptor.
Related Functions
See also bind(), socket(), and getsockname().
16. 5. 11.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
16. 5. 11.4 - Errors
EBADF The descriptor is invalid.
EFAULT The name argument is not a valid part of the
user address space.
EINVAL The socket has been shut down.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTCONN The socket is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The operation is not supported for the socket
protocol.
16. 5.12 - 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 );
16. 5. 12.1 - Argument
name
A pointer to a string containing the desired protocol name.
16. 5. 12.2 - Description
This function returns a pointer to a protoent structure
containing data 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 to be saved.
Related Functions
See also getprotoent() and getprotobynumber().
16. 5. 12.3 - Return Values
NULL Indicates end of file or an error; errno is
set to one of the following values.
x A pointer to a protoent structure.
16. 5.13 - 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) ;
16. 5. 13.1 - Argument
proto
A pointer to a string containing the desired protocol number.
16. 5. 13.2 - Description
This function returns a pointer to a protoent structure
containing the data 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 to be saved.
Related Functions
See also getprotoent() and getprotobyname().
16. 5. 13.3 - Return Values
NULL Indicates end of file or an error.
x A pointer to a protoent structure.
16. 5.14 - getprotoent()
Reads the next line from the protocols database.
Format
#include <netdb.h>
struct protoent *getprotoent();
16. 5. 14.1 - Description
This function returns a pointer to a protoent structure
containing the data 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.
The getprotoent() function 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 to be saved.
Related Functions
See also getprotobyname() and getprotobynumber().
16. 5. 14.2 - Return Values
NULL Indicates an end of file or an error.
x A pointer to a protoent structure.
16. 5.15 - getservbyname()
Gets information on the named service from the network services
database.
Format
#include <netdb.h>
struct servent *getservbyname ( char *name, char *proto );
16. 5. 15.1 - 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.
16. 5. 15.2 - Description
This function 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, searches
must also match the protocol.
This function returns a pointer to a servent structure containing
the data from 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 it must be
copied to be saved.
Related Functions
See also getservbyport().
16. 5. 15.3 - Return Values
NULL Indicates end of file or an error.
x A pointer to a servent structure.
16. 5.16 - getservbyport()
Gets information on the specified port from the network services
database.
Format
#include <netdb.h>
struct servent *getservbyport ( int port, char *proto );
16. 5. 16.1 - 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.
16. 5. 16.2 - Description
This function 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, searches must
also match the protocol.
This function 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 it must be
copied to be saved.
Related Functions
See also getservbyname().
16. 5. 16.3 - Return Values
NULL Indicates end of file or an error.
x A pointer to a servent structure.
16. 5.17 - getsockname()
Returns the name associated with a socket.
The $QIO equivalent is the IO$_SENSEMODE function with the p3
argument.
Format
#include <types.h>
#include <socket.h>
int getsockname ( int s, struct sockaddr *name, int *namelen
);
16. 5. 17.1 - Arguments
s
A socket descriptor created with socket() function and bound to
the socket name with the bind() function.
name
A pointer to the buffer in which getsockname() should return the
socket name.
namelen
A pointer to an integer containing the size of the buffer pointed
to by name. On return, the integer contains the actual size, in
bytes, of the name returned.
16. 5. 17.2 - Description
This function 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() function, not the getsockname() function, makes the
association of the name to the socket.
Related Functions
See also bind() and socket().
16. 5. 17.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
16. 5. 17.4 - Errors
EBADF The descriptor is invalid.
EFAULT The name argument is not a valid part of the
user address space.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The operation is not supported for this
socket's protocol.
16. 5.18 - getsockopt()
Returns the options set on a socket.
The $QIO equivalent is the IO$_SENSEMODE function.
Format
#include <types.h>
#include <socket.h>
int getsockopt ( int s, int level, int optname, char *optval,
unsigned int *optlen );
16. 5. 18.1 - Arguments
s
A socket descriptor created by the socket() function.
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 specified by p. See the IN.H
header 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.
For descriptions of the supported socket level options, see the
description of setsockopt() in this chapter.
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.
16. 5. 18.2 - Description
This function gets information on socket options. See the
appropriate protocol for information about available options
at each protocol level.
16. 5. 18.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
16. 5. 18.4 - Errors
EACCES The calling process does not have appropriate
permissions.
EBADF The socket descriptor is invalid.
EDOM The send and receive timeout values are too
large to fit in the timeout fields of the
socket structure.
EFAULT The address pointed to by the optval argument
is not in a valid (writable) part of the
process space, or the optlen argument is not
in a valid part of the process address space.
EINVAL The optval or optlen argument is invalid; or
the socket is shut down.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
ENOPROTOOPT The option is unknown or the protocol is
unsupported.
EOPNOTSUPP The operation is not supported by the socket
protocol.
ENOPROTOOPT The option is unknown.
ENOTSOCK The socket descriptor is invalid.
16. 5.19 - htonl()
Converts longwords from host byte order to network byte order.
Format
#include <in.h>
unsigned long int htonl ( unsigned long int hostlong );
16. 5. 19.1 - Argument
hostlong
A longword in host byte order (OpenVMS systems). All integers
on OpenVMS systems are in host byte order unless otherwise
specified.
16. 5. 19.2 - Description
This function converts 32-bit unsigned integers from host byte
order to network byte order.
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 byte order.
This function is most often used with internet addresses.
Network byte order places the byte with the most significant
bits at lower addresses, whereas OpenVMS systems place 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.
16. 5. 19.3 - Return Value
x A longword in network byte order.
16. 5.20 - htons()
Converts short integers from host byte order to network byte
order.
Format
#include <in.h>
unsigned short int htons ( unsigned short int hostshort );
16. 5. 20.1 - Argument
hostshort
A short integer in host byte order (OpenVMS systems). All
short integers on OpenVMS systems are in host byte order unless
otherwise specified.
16. 5. 20.2 - Description
This function converts 16-bit unsigned integers from host byte
order to network byte order.
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 byte order.
This function 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 OpenVMS systems
place 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.
16. 5. 20.3 - Return Value
x A short integer in network byte order.
Integers in network byte order cannot be used
for arithmetic computation on OpenVMS systems.
16. 5.21 - 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 );
16. 5. 21.1 - Argument
cp
A pointer to a null-terminated character string containing an
internet address in the standard internet dotted-decimal format.
16. 5. 21.2 - Description
This function returns an internet address in network byte order
when given an ASCII (null-terminated) string that represents the
address in the internet standard dotted-decimal format as its
argument.
Internet addresses specified with the dotted-decimal format 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 an 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 dotted-decimal address 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.
16. 5. 21.3 - Return Values
-1 Indicates that cp does not point to a proper
internet address.
x An internet address in network byte order.
16. 5.22 - 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 );
16. 5. 22.1 - Argument
in
An internet address.
16. 5. 22.2 - Description
This function 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.
16. 5. 22.3 - Return Value
x The local network address portion of an
internet address, in host byte order.
16. 5.23 - inet_makeaddr()
Returns an internet address based on a particular local address
and a network.
Format
#include <in.h>
#include <inet.h>
struct in_addr inet_makeaddr ( int net, int lna );
16. 5. 23.1 - Arguments
net
An internet network address in host byte order.
lna
A local network address on network net in host byte order.
16. 5. 23.2 - Description
This function 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.
16. 5. 23.3 - Return Value
x An internet address in network byte order.
16. 5.24 - 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 );
16. 5. 24.1 - Argument
in
An internet address.
16. 5. 24.2 - Description
This function 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.
16. 5. 24.3 - Return Value
x The internet network portion of an internet
address, in host byte order.
16. 5.25 - 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 );
16. 5. 25.1 - Argument
cp
A pointer to an ASCII (null-terminated) character string
containing a network address in the dotted-decimal format.
16. 5. 25.2 - Description
This function returns an internet network address as local host
integer value when an ASCII string representing the address
in the internet standard dotted-decimal format is given as its
argument.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.
16. 5. 25.3 - Return Values
-1 Indicates that cp does not point to a proper
internet network address.
x An internet network address, in local host
order.
16. 5.26 - inet_ntoa()
Converts an internet address into a text string representing the
address in the standard internet dotted-decimal format.
Format
#include <in.h>
#include <inet.h>
char *inet_ntoa ( struct in_addr in );
16. 5. 26.1 - Argument
in
An internet address in network byte order.
16. 5. 26.2 - Description
This function converts an internet address into an ASCII (null-
terminated) string that represents the address in standard
internet dotted-decimal format.
Because the string is returned in a static buffer that is
overwritten by subsequent calls to inet_ntoa(), you should copy
the string to a safe place.
16. 5. 26.3 - Return Value
x A pointer to a string containing the internet
address in dotted-decimal format.
16. 5.27 - ioctl()
Controls I/O requests to obtain network information.
Format
#include <ioctl.h>
int ioctl ( int s, int request, ... /* arg */ );
16. 5. 27.1 - Argument
s
Specifies the socket descriptor of the requested network device.
request
Specifies the type of ioctl command to be performed on the
device. The request types are grouped as follows:
o Socket operations
o File operations
o Interface operations
o ARP cache operations
o Routing table operations
Refer to <REFERENCE>(app_ioctl_commands) for a complete list of
IOCTL commands.
arg
Specifies arguments for this request. The type of arg is
dependent on the specific ioctl() request and device to which
the ioctl call is targeted.
16. 5. 27.2 - Description
The ioctl() function performs a variety of control functions
on devices. The functions performed are device-specific control
functions. The request and arg arguments are passed to the file
designated by fildes and then interpreted by the device driver.
The basic I/O functions are performed through the read() and
write() functions.
Encoded in an ioctl() request is whether the argument is an in
argument or an out argument, and the size of the arg argument
in bytes. The macros and definitions used to specify an ioctl()
request are located in the IOCTL.H header file.
16. 5. 27.3 - Return Values
-1 Error; errno is set to indicate the error.
16. 5. 27.4 - Errors
EBADF The fildes argument is not a valid open file
descriptor.
EINTR A signal was caught during the ioctl()
operation.
If an underlying device driver detects an error, errno might be
set to one of the following values:
EINVAL Either the request or the arg argument is not
valid.
ENOTTY Reserved for Compaq use. The fildes argument
is not associated with a character special
device, or the specified request does not
apply to the type of object that the fildes
argument references.
ENXIO The request and arg arguments are valid for
this device driver, but the service requested
cannot be performed on the particular
subdevice.
16. 5.28 - listen()
Converts an unconnected socket into a passive socket and
indicates that the kernel should accept incoming connection
requests directed to the socket.
Sets the maximum limit of outstanding connection requests for a
socket that is connection-oriented.
The $QIO equivalent is the IO$_SETMODE function.
Format
int listen ( int s, int backlog );
16. 5. 28.1 - Arguments
s
A socket descriptor of type SOCK_STREAM created using the
socket() function.
backlog
The maximum number of pending connections that can be queued
on the socket at any given time. The maximum number of pending
connections can be set using the sysconfig utility to set the
value of somaxconn. The default value for the maximum number of
pending connections is 1024.
16. 5. 28.2 - Description
This function creates a queue for pending connection requests
on socket s with a maximum size equal to the value of backlog.
Connections can then be accepted with the accept() function.
If a connection request arrives with the queue full (that is,
more connections pending than specified by the backlog argument),
the request is ignored so that TCP retries can succeed. If the
backlog has not cleared by the time TCP times out, the connect()
function fails with an errno indication of ETIMEDOUT.
Related Functions
See also accept(), connect(), and socket().
16. 5. 28.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
16. 5. 28.4 - Errors
EBADF The socket descriptor is invalid.
EDESTADDRREQ The socket is not bound to a local address,
and the protocol does not support listening on
an unbound socket.
EINVAL The socket is already connected, or the socket
is shut down.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The referenced socket is not of a type that
supports the operation listen().
16. 5.29 - ntohl()
Converts longwords from network byte order to host byte order.
Format
#include <in.h>
unsigned long ntohl ( unsigned long netlong );
16. 5. 29.1 - Argument
netlong
A longword in network byte order. Integers in network byte order
cannot be used for arithmetic computation on OpenVMS systems.
16. 5. 29.2 - Description
This function 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 byte
order.
This function is most often used with internet addresses.
Network byte order places the byte with the most significant
bits at lower addresses, whereas OpenVMS systems place the most
significant bits at the highest address.
16. 5. 29.3 - Return Value
x A longword in host byte order.
16. 5.30 - ntohs()
Converts short integers from network byte order to host byte
order.
Format
#include <in.h>
unsigned short ntohs ( unsigned short netshort );
16. 5. 30.1 - Argument
netshort
A short integer in network byte order. Integers in network
byte order cannot be used for arithmetic computation on OpenVMS
systems.
16. 5. 30.2 - Description
This function 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 byte
order.
This function 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 OpenVMS systems
place the most significant bits at the highest address.
16. 5. 30.3 - Return Value
x A short integer in host byte order (OpenVMS
systems).
16. 5.31 - 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 );
16. 5. 31.1 - 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.
16. 5. 31.2 - Description
If the end of file is not reached, the read() function returns
nbytes. If the end of file occurs during the read() function, it
returns the number of bytes read.
Upon successful completion, read() returns the number of bytes
actually read and placed in the buffer.
Related Functions
See also socket().
16. 5. 31.3 - 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.
16. 5. 31.4 - Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT The data was specified to be received into a
nonexistent or protected part of the process
address space.
EINTR A signal interrupted the recv() function
before any data was available.
EINVAL The MSG_OOB flag is set and no out-of-band
data is available.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN A receive is attempted on a connection-
oriented socket that is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The specified flags are not supported for this
socket type or protocol.
EWOULDBLOCK The socket is marked nonblocking, and no data
is waiting to be received.
16. 5.32 - 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 );
16. 5. 32.1 - 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 of the following
flags. The mask is built by using a logical OR operation on the
appropriate values.
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()
functions to send out-of-band data.
MSG_PEEK Allows you to examine data in the receive
buffer without removing it from the system's
buffers.
16. 5. 32.2 - Description
This function receives data from a connected socket. To receive
data on an unconnected socket, use the recvfrom() or recvmsg()
functions. The received data is placed in the buffer buf.
Data is sent by the socket's peer using the send, sendmsg(),
sendto(), or write() functions.
Use the select() function 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. If the socket
is nonblocking, a -1 is returned with the external variable errno
set to EWOULDBLOCK.
Related Functions
See also read(), send(), sendmsg(), sendto(), and socket().
16. 5. 32.3 - Return Values
x The number of bytes received and placed in
buf.
0 Peer has closed its send side of the
connection.
-1 Error; errno is set to indicate the error.
16. 5. 32.4 - Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT The data was specified to be received into a
nonexistent or protected part of the process
address space.
EINTR A signal interrupted the recv() function
before any data was available.
EINVAL The MSG_OOB flag is set and no out-of-band
data is available.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN A receive is attempted on a connection-
oriented socket that is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The specified flags are not supported for this
socket type or protocol.
EWOULDBLOCK The socket is marked nonblocking, and no data
is waiting to be received.
16. 5.33 - 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) ;
16. 5. 33.1 - Arguments
s
A socket descriptor created with the socket() function and
bound to a name using the bind() function or as a result of the
accept() function.
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 of the following
flags. The mask is built by using a logical OR operation on the
appropriate values.
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()
functions.
MSG_PEEK Allows you to examine the data that is next in
line to be received without actually removing
it from the system's buffers.
from
A buffer that the recvfrom() function uses to place the address
of the sender who sent the data.
If from is non-null, the address is returned. If from is null,
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.
16. 5. 33.2 - Description
This function 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 does not need to be
connected.
You can use the select() function 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. If
the socket is nonblocking, a -1 is returned with the external
variable errno set to EWOULDBLOCK.
Related Functions
See also read(), send(), sendmsg(), sendto(), and socket().
16. 5. 33.3 - 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.
16. 5. 33.4 - Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT A valid message buffer was not specified.
Nonexistent or protected address space is
specified for the message buffer.
EINTR A signal interrupted the recvfrom() function
before any data was available.
EINVAL The MSG_OOB flag is set, and no out-of-band
data is available.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN A receive is attempted on a connection-
oriented socket that is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The specified flags are not supported for this
socket type.
ETIMEDOUT The connection timed out when trying to
establish a connection or when a transmission
timed out on an active connection.
EWOULDBLOCK The NBIO (nonblocking) flag is set for the
socket descriptor and the process delayed
during the write operation.
16. 5.34 - 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 ); (BSD
Version 4.4)
int recvmsg ( int s, struct omsghdr msg, int flags ); (BSD
Version 4.3)
16. 5. 34.1 - Arguments
s
A socket descriptor created with the socket() function.
msg
flags
A bit mask that can contain one or more of the following
flags. The mask is built by using a logical OR operation on the
appropriate values.
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() functions 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.
16. 5. 34.2 - Description
You can use this function with any socket, whether or not it
is in a connected state. 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 does not need to be connected to
another socket.
When the ioveciovcnt array specifies more than one buffer, the
input data is scattered into iovcnt buffers as specified by the
members of the iovec array:
iov0, iov1, ..., ioviovcnt
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() function to determine when more data
arrives.
Related Functions
See also read(), send(), and socket().
16. 5. 34.3 - 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.
16. 5. 34.4 - Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT The message argument is not in a readable or
writable part of user address space.
EINTR This function was interrupted by a signal
before any data was available.
EINVAL The MSG_OOB flag is set, and no out-of-band
data is available.
The value of the msg_iovlen member of the
Lmsghdr structure is less than or equal to
zero or is greater than IOV_MAX.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN A receive is attempted on a connection-
oriented socket that is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The specified flags are not supported for this
socket type.
EWOULDBLOCK The socket is marked nonblocking, and no data
is ready to be received.
16. 5.35 - select()
Allows you to poll or check a group of sockets for I/O activity.
This function indicates 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 );
16. 5. 35.1 - Arguments
nfds
Specifies the number of open objects that may be ready for
reading or writing or that have exceptions pending. The nfds
argument is normally limited to FD_SETSIZE. Note that a single
process can have a maximum of 65535 simultaneous channels
(including sockets) on OpenVMS Alpha systems, and a maximum of
2047 on OpenVMS VAX systems.
readfds
A pointer to an array of bits, organized as integers, that should
be examined for read readiness. If bit n of the longword is set,
socket descriptor n is checked to see whether it is ready to be
read. All bits set in the bit mask must correspond to the file
descriptors of sockets. The select() function cannot be used on
normal files.
On return, the array to which readfds points contains a bit mask
of the sockets that are ready for reading. Only bits that were
set on entry to the select() function can be set on exit.
writefds
A pointer to an array of bits, organized as integers, that should
be examined for write readiness. If bit n of the longword is
set, socket descriptor n is checked to see whether it is ready
to be written to. All bits set in the bit mask must correspond to
socket descriptors.
On return, the array to which writefds points contains a bit mask
of the sockets that are ready for writing. Only bits that were
set on entry to the select() function are set on exit.
exceptfds
A pointer to an array of bits, organized as integers, that
is examined for exceptions. If bit n of the longword is set,
socket descriptor n is checked to see whether it has any pending
exceptions. All bits set in the bit mask must correspond to the
file descriptors of sockets.
On return, the array exceptfds pointer contains a bit mask of the
sockets that have exceptions pending. Only bits that were set on
entry to the select() function can be set on exit.
timeout
The length of time that the select() function 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, the
select() function returns before the timeout period expires.
The timeout argument points to a timeval structure.
16. 5. 35.2 - Description
This function determines the I/O status of the sockets specified
in the various mask arguments. It returns when a socket is ready
to be read or written, when the timeout period expires, or when
exceptions occur. If timeout is a non-null pointer, it specifies
a maximum interval to wait for the selection to complete.
If the timeout argument is null, the select() function blocks
indefinitely until a selected event occurs. To effect a poll,
the value for timeout should be non-null, and should point to a
zero-value structure.
If a process is blocked on a select() function while waiting for
input for a socket and the sending process closes the socket,
then the select() function notes this as an event and unblocks
the process. The descriptors are always modified on return if the
select() function returns because of the timeout.
NOTE
When the socket option SO_OOBINLINE is set on the device
socket, the select() function on both read and exception
events returns the socket mask that is set on both the read
and the exception mask. Otherwise, only the exception mask
is set.
Related Functions
See also accept(), connect(), read(), recv(), recvfrom(),
recvmsg(), send(), sendmsg(), sendto(), and write().
16. 5. 35.3 - 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() function timed out before any
socket became ready for I/O.
-1 Error; errno is set to indicate the error.
16. 5. 35.4 - Errors
EBADF One or more of the I/O descriptor sets
specified an invalid file descriptor.
EINTR A signal was delivered before the time limit
specified by the timeout argument expired and
before any of the selected events occurred.
EINVAL The time limit specified by the timeout
argument is invalid.
The nfds argument is less than zero, or
greater than or equal to FD_SETSIZE.
EAGAIN Allocation of internal data structures failed.
A later call to the select() function may
complete successfully.
ENETDOWN TCP/IP Services was not started.
ENOTSOCK The socket descriptor is invalid.
16. 5.36 - 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 );
16. 5. 36.1 - Arguments
s
A socket descriptor created with the socket() function that was
connected to another socket using the accept() or connect()
function.
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 MSG_OOB, the data is sent
out of band. Data can be received before other pending data on
the receiving socket if the receiver also specifies MSG_OOB in
the flag argument of its recv() or recvfrom() call.
16. 5. 36.2 - Description
You can use this function only on connected sockets. To send
data on an unconnected socket, use the sendmsg() or sendto()
function. The send() function passes data along to its connected
peer, which can receive the data by using the recv() or read()
function.
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() function to determine when it is possible to send more
data.
Related Functions
See also read(), recv(), recvmsg(), recvfrom(), getsockopt(),
and socket().
16. 5. 36.3 - Return Values
n The number of bytes sent. This value normally
equals len.
-1 Error; errno is set to indicate the error.
16. 5. 36.4 - Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EDESTADDRREQ The socket is not connection-oriented, and no
peer address is set.
EFAULT The message argument is not in a readable or
writable part of the user address space.
EINTR A signal interrupted the send() before any
data was transmitted.
EMSGSIZE The message is too large to be sent all at
once, as the socket requires.
ENETDOWN The local network connection is not
operational.
ENETUNREACH The destination network is unreachable.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTCONN The socket is not connected or has not had the
peer prespecified.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket argument is associated with a
socket that does not support one or more of
the values set in flags.
EWOULDBLOCK The socket is marked nonblocking, and no space
is available for the send() function.
16. 5.37 - 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 ); (BSD
Version 4.4)
int sendmsg ( int s, struct omsghdr *msg, int flags ); (BSD
Version 4.3)
16. 5. 37.1 - Arguments
s
A socket descriptor created with the socket() function.
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. Data can be received before other pending
data on the receiving socket if the receiver specifies a flag of
MSG_OOB.
16. 5. 37.2 - Description
You can use this function on any socket to send data to any named
socket. The data in the msg_iov field of the msghdr 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() function. 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() function blocks until buffer
space becomes available. If the socket is defined as nonblocking,
the sendmsg() function 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 an INADDR_BROADCAST address, the
SO_BROADCAST socket 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 the sendmsg()
function. All errors (except EWOULDBLOCK) are detected locally.
You can use the select() function to determine when it is
possible to send more data.
Related Functions
See also read(), recv(), recvfrom(), recvmsg(), socket(), and
getsockopt().
16. 5. 37.3 - Return Values
n The number of bytes sent.
-1 Error; errno is set to indicate the error.
16. 5. 37.4 - Errors
ENOTSOCK The socket descriptor is invalid.
EFAULT An invalid user space address is specified for
a argument.
EMSGSIZE The socket requires that messages be sent
atomically, but 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.
16. 5.38 - 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 );
16. 5. 38.1 - Arguments
s
A socket descriptor created with the socket() function.
msg
A pointer to a buffer containing the data to be sent.
len
The length of the data pointed to by the msg argument.
flags
Can be either 0 or MSG_OOB. If it is MSG_OOB, the data is sent
out of band. Data can be received before other pending data on
the receiving socket if the receiver specifies MSG_OOB in its
flag argument of its recv(), recvfrom() or recvmsg() call.
to
Points to the address structure of the socket to which the data
is to be sent.
tolen
The length of the address pointed to by the to argument.
16. 5. 38.2 - Description
This function 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 the read(), recv(), recvfrom(), or
recvmsg() function.
If there is no space available to buffer the data being sent
on the receiving end of the connection, the sendto() function
blocks until buffer space becomes available. If the socket is
defined as nonblocking, the sendto() function 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() function 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() function to determine when it is possible to send
more data.
If the address specified is a INADDR_BROADCAST address, then the
SO_BROADCAST socket option must have been set and the process
must have SYSPRV or BYPASS privilege for the I/O operation to
succeed.
Related Functions
See also read(), recv(), recvfrom(), recvmsg(), socket(), and
getsockopt().
16. 5. 38.3 - Return Values
n The number of bytes sent. This value normally
equals len.
-1 Error; errno is set to indicate the error.
16. 5. 38.4 - Errors
EAFNOSUPPORT Addresses in the specified address family
cannot be used with this socket.
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EDESTADDRREQ You did not specify a destination address for
the connectionless socket and no peer address
is set.
EFAULT An invalid user space address is specified for
a argument.
EHOSTUNREACH The destination host is unreachable.
EINTR A signal interrupted sendto() before any data
was transmitted.
EINVAL The dest_len argument is not a valid size for
the specified address family.
EISCONN The connection-oriented socket for which a
destination address was specified is already
connected.
EMSGSIZE The message is too large to be sent all at
once, as the socket requires.
ENETDOWN The local network connection is not
operational.
ENETUNREACH The destination network is unreachable.
ENOBUFS The system has insufficient to complete the
call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN The socket is connection-oriented but is not
connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket argument is associated with a
socket that does not support one or more of
the values set in flags.
EPIPE The socket is shut down for writing or is
connection oriented, and the peer is closed or
shut down for reading. In the latter case, if
the socket is of type SOCK_STREAM, the SIGPIPE
signal is generated to the calling process.
EWOULDBLOCK The socket is marked nonblocking, and no space
is available for the sendto() function.
16. 5.39 - setsockopt()
Sets options on a socket.
The $QIO equivalent is the IO$_SETMODE function.
Format
#include <types.h>
#include <socket.h>
int setsockopt ( int s, int level, int optname, char *optval,
int optlen );
16. 5. 39.1 - Arguments
s
A socket descriptor created by the socket() function.
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.
Refer to:
o <REFERENCE>(op_setsock_tab) for a list of socket options
o <REFERENCE>(tcp_set_tab_opt) for a list of TCP options
o <REFERENCE>(ip_set_tab_opt) for a list of IP options
optval
Points to a buffer containing the arguments 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 argument defined in the
SOCKET.H header 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 the 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 soon as possible.
optlen
An integer specifying the size of the buffer pointed to by
optval.
16. 5. 39.2 - Description
This function 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 the value of 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
value for level argument to the protocol number (IPPROTO_TCP) of
TCP. See the IN.H header file for the various IPPROTO values.
16. 5. 39.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
16. 5. 39.4 - Errors
EACCES The calling process does not have appropriate
permissions.
EBADF The descriptor is invalid.
EDOM The send and receive timeout values are too
large to fit in the timeout fields of the
socket structure.
EINVAL The optlen argument is invalid.
EISCONN The socket is already connected; the specified
option cannot be set when the socket is in the
connected state.
EFAULT The optval argument is not in a readable part
of the user address space.
ENOBUFS The system had insufficient resources to
complete the call.
ENOPROTOOPT The option is unknown.
ENOTSOCK The socket descriptor is invalid.
EFAULT The optname argument is invalid.
16. 5.40 - shutdown()
Shuts down all or part of a bidirectional connection on a socket.
This function does not allow further receives or 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) ;
16. 5. 40.1 - 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 Do not allow further calls to recv() on the socket.
1 Do not allow further calls to send() on the socket.
2 Do not allow further calls to both send() and recv().
16. 5. 40.2 - Description
This function allows communications on a socket to be shut down
one piece at a time rather than all at once. Use the shutdown()
function to create unidirectional connections rather than the
normal bidirectional (full-duplex) connections.
Related Functions
See also connect() and socket().
16. 5. 40.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
16. 5. 40.4 - Errors
EBADF The socket descriptor is invalid.
EINVAL The how argument is invalid.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTCONN The specified socket is not connected.
ENOTSOCK The socket descriptor is invalid.
16. 5.41 - socket()
Creates an endpoint for communication by returning a special
kind of file descriptor called a socket descriptor, which is
associated with a TCP/IP Services socket device channel.
The $QIO equivalent is the IO$_SETMODE function.
Format
#include <types.h>
#include <socket.h>
int socket ( int af, int type, int protocol );
16. 5. 41.1 - Arguments
af
The address family used in later references to the socket.
Addresses specified in subsequent operations using the socket
are interpreted according to this family. Currently, only the AF_
INET (internet) and TCPIP$C_AUXS addresses are supported.
For a network application server with the LISTEN flag enabled,
you specify the TCPIP$C_AUXS address family to obtain the
connected device socket created by the auxiliary server in
response to incoming network traffic. For an example of this
situation, refer to the example in <REFERENCE>(EX_TCP_ASRV_SOCK).
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.
Available only to users with either a system UIC or the 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, if many protocols exist, 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.
16. 5. 41.2 - Description
This function 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,
which are defined in the SOCKET.H header file and described in
the setsockopt() function section of this chapter.
Use the setsockopt() and getsockopt() functions to set and
get options. Options take an integer argument that should be
nonzero if the option is to be enabled or zero if it is to be
disabled. SO_LINGER uses a linger structure argument defined in
<socket.h>.
Related Functions
See also accept(), bind(), connect(), listen(), read(), recv(),
recvfrom(), recvmsg(), select(), send(), sendmsg(), sendto(),
shutdown(), and write().
Related Functions
See also getsockname() and getsockopt().
16. 5. 41.3 - Return Values
x A file descriptor that refers to the socket
descriptor.
-1 Error; errno is set to indicate the error.
16. 5. 41.4 - Errors
EACCES The process does not have sufficient
privileges.
EAFNOSUPPORT The specified address family is not supported
in this version of the system.
EMFILE The per-process descriptor table is full.
ENETDOWN TCP/IP Services was not started.
ENFILE No more file descriptors are available for the
system.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system was unable to allocate kernel
memory to increase the process descriptor
table.
EPERM The process is attempting to open a raw socket
and does not have SYSTEM privilege.
EPROTONOSUPPORT The socket in the specified address family is
not supported.
EPROTOTYPE The socket type is not supported by the
protocol.
ESOCKTNOSUPPORT The specified socket type is not supported in
this address family.
16. 5.42 - write()
Writes bytes from a buffer to a file or socket.
The $QIO equivalent is the IO$_WRITEVBLK function.
Format
#include <unixio.h>
int write ( int d, void *buffer, int nbytes );
16. 5. 42.1 - Arguments
d
A descriptor that refers to a socket or file.
buffer
The address of a buffer from which the output data is to be
taken.
nbytes
The maximum number of bytes involved in the write operation.
16. 5. 42.2 - Description
This function attempts to write a buffer of data to a socket or
file.
Related Functions
See also socket().
16. 5. 42.3 - Return Values
x The number of bytes written to the socket or
file.
-1 Error; errno is set to indicate the error.
16. 5. 42.4 - Errors
EPIPE The socket is shut down for writing or is
connection oriented, and the peer is closed or
shut down for reading. In the latter case, if
the socket is of type SOCK_STREAM, the SIGPIPE
signal is generated to the calling process.
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 a negative value.
EAGAIN The O_NONBLOCK flag is set on this file, and
the process is delayed in the write operation.
EBADF The d argument does not specify a valid file
descriptor that is open for writing.
EINTR A write() or pwrite() function on a pipe is
interrupted by a signal, and no bytes have
been transferred through the pipe.
EINVAL On of the following errors occurred:
o The STREAM or multiplexer referenced
by d is linked (directly or indirectly)
downstream from a multiplexer.
o The iov_count argument value was less than
or equal to zero or greater than IOV_MAX.
o The sum of the iov_len values in the iov
array overflows a ssize_t data type.
o The file position pointer associated with
the d argument was a negative value.
o One of the iov_len values in the iov array
was negative, or the sum overflowed a 32-
bit integer.
EPERM An attempt was made to write to a socket of
type SOCK_STREAM that is not connected to a
peer socket.
EPIPE An attempt was made to write to a pipe that
has only one end open.
An attempt was made to write to a pipe or FIFO
that is not opened for reading by any process.
A SIGPIPE signal is sent to the process.
ERANGE An attempt was made to write to a STREAM
socket where nbytes are outside the specified
minimum and maximum range, and the minimum
value is nonzero.
16. 5.43 - $ASSIGN
Provides a calling process with an I/O channel, thereby allowing
the calling process to perform I/O operations on the network
pseudodevice.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ASSIGN devnam, chan, [acmode], [mbxnam], [flags]
C Prototype
int sys$assign (void *devnam, unsigned short int *chan,
unsigned int acmode, void *mbxnam,...);
Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
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.
16. 5. 43.1 - Arguments
devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor (Alpha)
by 32-bit descriptor-fixed-length string descriptor
(VAX)
Name of the device to which $ASSIGN is to assign a channel. The
devnam argument is the 32- or 64-bit address (on Alpha systems)
or the 32-bit address (on VAX systems) of a character string
descriptor pointing to the network pseudodevice name string
(either TCPIP$DEVICE: or SYS$NET:).
chan
OpenVMS usage:channel
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
by 32-bit reference (VAX)
Number of the channel that is assigned. The chan argument is the
32- or 64-bit address (on Alpha systems) or the 32-bit address
(on VAX systems) 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. I/O operations on
the channel can be performed only from equal and more privileged
access modes. The $PSLDEF macro defines the following symbols for
the four access modes:
Access
Symbol Mode Numeric Value
PSL$C_KERNEL Kernel 0
PSL$C_EXEC Executive 1
PSL$C_SUPER Supervisor 2
PSL$C_USER User 3
mbxnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor (Alpha)
by 32-bit descriptor-fixed-length string descriptor
(VAX)
This argument is not used.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
An optional device-specific argument. The flags argument is a
longword bit mask. For more information about the applicability
of the flags argument for a particular device, refer to the
OpenVMS I/O User's Reference Manual.
16. 5. 43.2 - 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 the TCPIP$DEVICE: template network
device, the network software creates a new device called BGn,
where n is a unique unit number. The corresponding channel number
is used in any subsequent operation requests for that device.
When the auxiliary server creates a process for a service with
the LISTEN flag set, the server creates a device socket. In
order for your application to receive the device socket, assign
a channel to SYS$NET, which is the logical name of a network
pseudodevice, and perform an appropriate $QIO(IO$_SETMODE)
operation.
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.
16. 5. 43.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
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$_DEVLSTFULL The system maximum number of BG: device units
has been reached.
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 The specified device does not exist.
16. 5.44 - $CANCEL
Cancels all pending I/O requests on a specified channel.
Related Functions
The equivalent Sockets API function is close().
Format
SYS$CANCEL chan
C Prototype
int sys$cancel (unsigned short int chan);
Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
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.
16. 5. 44.1 - Arguments
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
I/O channel on which I/O is to be canceled. The chan argument is
a word containing the channel number.
16. 5. 44.2 - 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.
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:
o The specified event flag is set.
o The first word of the I/O status block, if specified, is set
to SS$_CANCEL if the I/O request is queued, or to SS$_ABORT if
the I/O operation is in progress.
o 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.
16. 5. 44.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ABORT A physical line went down during a network
connect operation.
SS$_CANCEL 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 to cancel
the I/O.
SS$_IVCHAN An invalid channel was specified (that is, a
channel number of 0 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.
16. 5.45 - $DASSGN
Deassigns (releases) an I/O channel previously acquired using the
Assign I/O Channel ($ASSIGN) service.
Related Functions
The equivalent Sockets API function is close().
Format
SYS$DASSGN chan
C Prototype
int sys$dassgn (unsigned short int chan);
Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
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.
16. 5. 45.1 - 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.
16. 5. 45.2 - Description
After all communication is completed, use the $DASSGN system
service to free an I/O channel. A $DASSGN operation executed
on a channel associated with a network pseudodevice does the
following:
o Ends all pending operations to send or receive data at $QIO
level ($CANCEL system service).
o Clears the port associated with the channel. When executing
the $DASSGN system service for TCP sockets, the socket remains
until the connection is closed on both the local and remote
sides.
o Ends all communications with the network pseudodevice that the
I/O channel identifies.
o Frees the channel associated with the network 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.
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 either 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 a reference to that socket after
issuing a $DASSGN.
16. 5. 45.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
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.
16. 5.46 - $QIO
Queues an I/O request to a channel associated with a network
pseudodevice.
The $QIO service is completed asynchronously; that is, 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 completed.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$QIO [efn],chan,func, [iosb],[astadr],[astprm],
[p1],[p2],[p3],[p4], [p5],[p6]
C Prototype
int sys$qio (unsigned int efn, unsigned short int chan,
unsigned int func, struct _iosb *iosb, void
(*astadr)(__unknown_params), __int64 astprm, void
*p1, __int64 p2, __int64 p3, __int64 p4, __int64
p5, __int64 p6);
Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
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.
16. 5. 46.1 - 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 completes. The
efn argument is a longword value containing the number of the
event flag, however, $QIO uses only the low-order byte.
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: longword (unsigned)
access: read only
mechanism: by value
Function codes and function modifiers specifying the operation
to be performed. The func argument is a longword containing the
function code.
For information about the network pseudodevice and TELNET device
function codes and modifiers, see Network Pseudodevice Driver
Functions and <REFERENCE>(TEL_FUNC_CODE).
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by 32-bit reference or 64-bit reference (Alpha)
by 32-bit reference (VAX)
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, it clears the event flag. The
$QIO also clears the quadword I/O status block if the iosb
argument is specified.
Although the iosb argument is optional, Compaq 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 to be sure that the event flag was not set by an event
other than service completion.
o If you are using the $SYNCH service to synchronize completion
of the service, the I/O status block is a required argument
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 $QIO service. The
condition value returned in R0 provides information about the
success or failure of the service call itself; the condition
values returned in the I/O status block give information on
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 value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference (Alpha)
by 32-bit reference (VAX)
AST service routine to be executed when the I/O completes. The
astadr argument is the address of the AST routine.
The AST routine executes at the access mode of the caller of
$QIO.
astprm
OpenVMS usage:user_arg
type: quadword unsigned (Alpha); longword unsigned (VAX)
access: read only
mechanism: by 32- or 64-bit value (Alpha)
by 32-bit value (VAX)
AST parameter to be passed to the AST service routine. On Alpha
systems, the astprm argument is a quadword value containing the
AST parameter. On VAX systems, the astprm argument is a longword
value containing the AST parameter.
p1 to p6
OpenVMS usage:varying_arg
type: quadword unsigned (Alpha); longword unsigned (VAX)
access: read only
mechanism: by 32- or 64-bit reference or by 64-bit value
depending on the I/O function (Alpha)
by 32-bit reference or by 32-bit value depending on
the I/O function (VAX)
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 Network Pseudodevice
Driver I/O Functions for descriptions of the network pseudodevice
driver I/O function codes; see List Codes for the p5 Item through
Service Type Codes for related TELNET device driver I/O function
codes.
16. 5. 46.2 - Description
The Queue I/O Request service 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 Services, $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, 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.)
16. 5. 46.3 - Condition Values Returned
Each function used with $QIO has its own error codes. See the
error codes listed under the individual descriptions of the
device driver I/O function code in the remainder of this chapter.
16. 5. 46.4 - Network Pseudodevice Driver Functions
The network pseudodevice allows physical, logical, and virtual
I/O functions. The physical and logical I/O functions are used
only with the IP layer. Network Pseudodevice Driver I/O Functions
lists the basic I/O functions and their modifiers. The sections
that follow describe in greater detail the operation of these I/O
functions.
Table 1 Network Pseudodevice Driver I/O Functions
Function Code and Function
Arguments Modifier Description
IO$_ACCESS p3,p4 IO$M_ACCEPT Opens a connection.
IO$M_EXTEND
IO$M_NOW
IO$_ACPCONTROL p1, Performs an ACP (ancillary
p2, p3, p4 control process) operation.
IO$_DEACCESS p4 IO$M_NOW Aborts or closes a
IO$M_SHUTDOWN connection.
IO$_READVBLK IO$M_EXTEND Reads a virtual block.
p1,p2,p3,p4,p6 IO$M_
INTERRUPT
IO$M_LOCKBUF Controls the buffer
IO$M_PURGE operations.
IO$_SENSEMODE Reads the network
p2,p3,p4,p6 pseudodevice
characteristics.
IO$_SENSECHAR Reads the network
p2,p3,p4,p6 pseudodevice
characteristics.
IO$_SETMODE p1,p2, IO$M_OUTBAND Sets the network
p3,p4,p5 IO$M_READATTN pseudodevice characteristics
IO$M_WRTATTN for subsequent operations.
IO$_SETCHAR p1,p2, IO$M_OUTBAND Sets the network
p3,p4,p5 IO$M_READATTN pseudodevice characteristics
IO$M_WRTEATTN for subsequent operations.
IO$_WRITEVBLK IO$M_ Writes a 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 2 Network Symbol Definition Files
File Name Language
<REFERENCE>(filpref)$INDECEC.or VAX C
<REFERENCE>(filpref)$INVAXEFortran
<REFERENCE>(filpref)$INVAXEPASCAL
<REFERENCE>(filpref)$INMACRO-32R
<REFERENCE>(filpref)$INVAXEPL/1I
<REFERENCE>(filpref)$INBLISS-322
<REFERENCE>(filpref)$INVAXEADADA
<REFERENCE>(filpref)$INVAXEBASIC
16. 5. 46. 4.1 - IO$_ACCESS
When using a connection-oriented protocol, such as TCP, the IO$_
ACCESS function initiates a connection and specifies a remote
port number and internet address. When using a connectionless
protocol, such as UDP, the IO$_ACCESS function sets the remote
port number and internet address.
For TCP, a connection request times out at a specified interval
(75 seconds is the 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.
If a connection fails, you must deallocate the socket and then
create a new socket before trying to reconnect.
Related Functions
The equivalent Sockets API function is connect().
16. 5. 46. 4. 1.1 - Arguments
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
The remote port number and internet address of the host to
connect. The p3 argument is the address of an item_list_2
descriptor that points to the socket address structure containing
the remote port number and internet address.
16. 5. 46. 4. 1.2 - Function Modifiers
IO$M_NOW Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the
operation to block, the system completes the
I/O operation and returns the SS$_SUSPENDED
status code.
16. 5. 46. 4. 1.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_BADPARAM Programming error that occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o An IO$_ACCESS function was specified
without the address of a remote socket
name (p3 was null).
SS$_BUGCHECK Inconsistent state. Report the problem to your
Compaq support representative.
SS$_CANCEL The I/O operation was canceled by a $CANCEL
system service.
SS$_CONNECFAIL The connection to a network object timed out
or failed.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_DUPLNAM A network configuration error. No ports were
available for new connections.
SS$_EXQUOTA The process has exceeded its socket quota or
some other process quota.
SS$_FILALRACC The specified socket name is already in use by
one of the following:
o On a raw socket, the remote internet
address was already specified on a previous
IO$_ACCESS call.
o On a datagram, the remote internet address
was already specified on a previous
IO$_ACCESS call.
o On a stream socket, the IO$_ACCESS function
targeted a stream socket that was already
connected.
SS$_ILLCNTRFUNC Illegal function.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVADDR The specified internet address was not found,
or an invalid port number and internet address
combination was specified with the IO$_ACCESS
function. Port 0 is not allowed with the
IO$_ACCESS function.
SS$_IVBUFLEN The size of the socket name structure
specified with the IO$_ACCESS function was
invalid.
SS$_LINKABORT The remote socket closed the connection.
SS$_NOLICENSE The Compaq TCP/IP Services for OpenVMS license
is not present.
SS$_PROTOCOL A network protocol error occurred. The
address family specified in the socket address
structure is not supported.
SS$_REJECT The network connection is rejected for one of
the following reasons:
o An attempt was made to connect to a remote
socket that is already connected.
o An error was encountered while establishing
the connection
o The peer socket refused the connection
request or is closing the connection.
SS$_SHUT The local or remote node is no longer
accepting connections.
SS$_SUSPENDED The system detected a condition that might
cause the operation to block.
SS$_TIMEOUT A TCP connection timed out before the
connection could be established.
SS$_UNREACHABLE The remote node is currently unreachable.
16. 5. 46. 4.2 - IO$_ACCESS|IO$M_ACCEPT
This function is used with a connection-based protocol, such as
TCP, to accept a new connection on a passive socket.
This function completes the first connection on the queue of
pending connections.
Related Functions
The equivalent Sockets API function is accept() .
16. 5. 46. 4. 2.1 - Arguments
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_3 descriptor
The remote port number and internet address of a new connection.
The p3 argument is the address of an item_list_3 descriptor that
points to the socket address structure into which the remote port
number and internet address of the new connection is written.
Use the IO$_ACCESS function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
p4
OpenVMS usage:channel
type: word (unsigned)
access: write only
mechanism: by reference
The I/O channel number assigned to a new connection. The p4
argument is the address of a word into which the new connection's
channel number is written.
16. 5. 46. 4. 2.2 - Function Modifiers
IO$M_EXTEND Allows the usage of BSD Version 4.4 formatted
socket address structures.
IO$M_NOW Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the
operation to block, the system completes the
I/O operation and returns the SS$_SUSPENDED
status code.
16. 5. 46. 4. 2.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_BADPARAM Programming error that occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o A IO$_ACCESS|IO$M_ACCEPT function was
specified without the address of the
channel for the new connection (p4 was
null or invalid).
SS$_BUGCHECK Inconsistent state. Report the problem to your
Compaq support representative.
SS$_CANCEL The I/O operation was canceled by a $CANCEL
system service.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_EXQUOTA The process has exceeded its socket quota or
some other process quota.
SS$_FILALRACC The specified socket name is already in use by
one of the following:
o On a raw socket, the remote internet
address was already specified on a previous
IO$_ACCESS call.
o On a datagram, the remote internet address
was already specified on a previous
IO$_ACCESS call.
o On a stream socket, the IO$_ACCESS function
targeted a stream socket that was already
connected.
SS$_ILLCNTRFUNC Illegal function.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVADDR The specified internet address was not found,
or an invalid port number and internet address
combination was specified with the IO$_ACCESS
function. Port 0 is not allowed with the
IO$_ACCESS function.
SS$_IVBUFLEN The size of the socket name structure
specified with the IO$_ACCESS function was
invalid.
SS$_LINKABORT The remote socket closed the connection.
SS$_NOLICENSE The TCP/IP Services license is not present.
SS$_PROTOCOL A network protocol error occurred. The
address family specified in the socket address
structure is not supported.
SS$_REJECT The network connection is rejected for one of
the following reasons:
o An attempt was made to connect to a remote
socket that is already connected.
o An error was encountered while establishing
the connection
o The peer socket refused the connection
request or is closing the connection.
SS$_SHUT The local or remote node is no longer
accepting connections.
SS$_SUSPENDED The system detected a condition that might
cause the operation to block.
SS$_TIMEOUT A TCP connection timed out before the
connection could be established.
SS$_UNREACHABLE The remote node is currently unreachable.
16. 5. 46. 4.3 - IO$_ACPCONTROL
The IO$_ACPCONTROL function accesses the network ACP to retrieve
information from the host and the network database files.
Related Functions
The equivalent Sockets API functions are gethostbyaddr(),
gethostbyname(), getnetbyaddr(), and getnetbyname().
16. 5. 46. 4. 3.1 - Arguments
p1
OpenVMS usage:subfunction_code
type: longword (unsigned)
access: read only
mechanism: by descriptor-fixed-length descriptor
A longword identifying the network ACP operation to perform.
The p1 argument is the address of a descriptor pointing to this
longword.
To specify the network ACP operation to perform, select a
subfunction code from Subfunction Codes and a call code from
Call Codes.
Subfunction Codes defines subfunction codes for network ACP
operations.
Table 3 Subfunction Codes
Subfunction Code Description
INETACP_FUNC$C_ Get the host name of the specified
GETHOSTBYADDR internet address from the host
database.
INETACP_FUNC$C_ Get the internet address of the
GETHOSTBYNAME specified host from the host
database.
INETACP_FUNC$C_ Get the network name of the specified
GETNETBYADDR internet address from the network
database.
INETACP_FUNC$C_ Get the internet address of the
GETNETBYNAME specified network from the network
database.
Call Codes defines call codes for network ACP operations.
Table 4 Call Codes
Call Code Description
INETACP$C_ALIASES Returns the list of alias names associated
with the specified host or network from
the internet hosts or network database.
INETACP$C_TRANS Returns the internet address associated
with the specified host or network as a
32-bit value in network byte order.
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.
IO$_ACPCONTROL searches the local host database for the host's
name. If a matching host name is not found in the local host
database, IO$_ACPCONTROL then searches the BIND database if the
BIND resolver is enabled.
p2
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Input string for the network ACP operation containing one of the
following: host internet address, host name, network internet
address, or network name. The p2 argument is the address of a
string descriptor pointing to the input string.
All internet addresses are specified in dotted-decimal notation.
p3
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length in bytes of the output buffer returned by IO$_ACPCONTROL.
The p3 argument is the address of a word in which the length of
the output buffer is written.
p4
OpenVMS usage:buffer
type: vector byte (unsigned)
access: write only
mechanism: by descriptor-fixed-length descriptor
Buffer into which IO$_ACPCONTROL writes its output data. The p4
argument is the address of a descriptor pointing to the output
buffer.
The format of the data returned in the output buffer is dictated
by the call code specified by the p1 argument.
o Strings returned by IO$_ACPCONTROL with a call code of
INETACP$C_ALIASES consist one of the following: host internet
address, host name, network internet address, or network name.
All internet addresses are formatted using dotted-decimal
notation. Alias names are separated by a null character (0).
The length of the returned string includes all null characters
that separate alias names.
o Internet addresses returned by IO$_ACPCONTROL with a call code
of INETACP$C_TRANS are 32-bit value and in network byte order.
o All hostent and netent structures returned by IO$_ACPCONTROL
with a call code of INETACP$C_HOSTENT_OFFSET or INETACP$C_
NETENT_OFFSET are modified; pointers are replaced with offsets
from the beginning of the structure.
16. 5. 46. 4. 3.2 - Condition Values Returned
SS$_NORMAL The service completed successfully
SS$_ABORT An error was detected while performing an ACP
function.
SS$_BADPARAM Programming or internal error. A bad
parameter (name or address) was specified
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 Illegal function.
SS$_NOPRIV No privilege for the execution of an ACP
function.
SS$_RESULTOVF The ACP overflowed the buffer in returning a
parameter.
SS$_SHUT The local or remote node is no longer
accepting connections.
16. 5. 46. 4.4 - IO$_DEACCESS
The IO$_DEACCESS function closes a connection and deletes a
socket. Any pending messages queued for transmission are sent
before tearing down the connection.
When used with the IO$M_SHUTDOWN function modifier, the IO$_
DEACCESS function shuts down all or part of a bidirectional
connection on a socket. Use the p4 argument to specify the
disposition of pending I/O operations on the socket.
You can specify a wait time or time-to-linger socket parameter
(TCPIP$C_LINGER option) for transmission completion before
disconnecting the connection. Use the IO$_SETMODE or IO$_SETCHAR
function to set and clear the TCPIP$C_LINGER option.
If you set the TCPIP$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 TCPIP$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 Compaq Tru64 UNIX, the TCP/IP
Services forces a time to linger of 2 minutes on TCP stream
sockets.
Related Functions
The equivalent Sockets API functions are close() and shutdown().
16. 5. 46. 4. 4.1 - Arguments
p4
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of shutdown flags to specify the disposition of pending
I/O operations on the socket. The p4 argument is used only with
the IO$M_SHUTDOWN function modifier. The following table lists
available shutdown flags.
Shutdown Flag Description
TCPIP$C_DSC_ Discards messages from the receive queue and
RCV disallows further receiving. Pending messages
in the receive queue for this connection are
discarded.
TCPIP$C_DSC_ Discards messages from the send queue and
SND disallows sending new messages. Pending messages
in the transmit queue for this connection are
discarded.
TCPIP$C_DSC_ Discards all messages and disallows both
ALL sending and receiving. All pending messages are
discarded.
Specifying this flag has the same effect as
issuing a $CANCEL QIO followed by an IO$_DEACCESS
QIO without specifying any flags.
16. 5. 46. 4. 4.2 - Function Modifiers
IO$M_SHUTDOWN Causes all or part of a full-duplex connection
on a socket to be shut down.
IO$M_NOW Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the
operation to block, the system completes the
I/O operation and returns the SS$_SUSPENDED
status code.
16. 5. 46. 4. 4.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_BADPARAM The IO$_DEACCESS operation failed to specify a
socket.
SS$_CANCEL The I/O operation was canceled by a $CANCEL
system service.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_NOLINKS The specified socket was not connected.
SS$_SHUT The local or remote node is no longer
accepting connections.
SS$_SUSPENDED The system detected a condition that might
cause the operation to block.
16. 5. 46. 4.5 - IO$_READVBLK
The IO$_READVBLK function transfers data received from an
internet host to the specified user buffers. Use both p1 and
p2 arguments to specify a single user buffer. Use the p6 argument
to specify multiple buffers.
For connection-oriented protocols, such as TCP, data is buffered
in system space as a stream of bytes. The IO$_READVBLK function
completes (1) when there is no more data buffered in system space
for this socket, or (2) when there is no more available space in
the user buffer. Data that is buffered in system space but did
not fit in the user buffer is available to the user in subsequent
$QIOs.
For connectionless protocols, datagram and raw socket data is
buffered in system space as a chain of records. The user buffer
specified with a IO$_READVBLK function is filled with data that
is buffered in one record. Each IO$_READVBLK reads data from one
record. The IO$_READVBLK function completes (1) when all data
from a record is transferred to the user buffer, or (2) when
there is no more available space in the user buffer. Any data
remaining in the current record 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 management command SHOW DEVICE_SOCKET/FULL to display
counters related to read operations.
Related Functions
The equivalent Sockets API functions are read(), recv(),
recvfrom(), and recvmsg().
16. 5. 46. 4. 5.1 - Arguments
p1
OpenVMS usage:buffer
type: vector byte (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
by 32-bit reference (VAX)
The 32- or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of the buffer to receive the incoming
data. The length of this buffer is specified by the p2 argument.
p2
OpenVMS usage:buffer_length
type: quadword unsigned (Alpha); longword unsigned (VAX)
access: read only
mechanism: by 64-bit value (Alpha)
by 32-bit value (VAX)
The length (in bytes) of the buffer available to hold the
incoming data. The address of this buffer is specified by the
p1 argument.
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_3 descriptor
The remote port number and internet address of the source of
the datagram or raw IP message (not TCP). The p3 argument is the
address of an item_list_3 descriptor that points to the socket
address structure into which the remote port number and internet
address of the message source is written.
Use the IO$_READVBLK function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
If the IO$M_EXTEND modifier is not specified, the IO$_READVBLK
function returns a BSD Version 4.3 formatted socket address
structure.
p4
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of flags to specify attributes for the read operations.
Read Flags lists the available read flags.
Table 5 Read Flags
Read Flag Description
TCPIP$C_MSG_OOB Reads an out-of-band byte.
TCPIP$C_MSG_PEEK Reads a message but leaves the message in the
queue.
TCPIP$C_MSG_NBIO Does not block the I/O operation if the
receive queue is empty (similar to using
IO$M_NOWAIT).
TCPIP$C_MSG_PURGE Flushes data from the queue (similar to using
IO$M_PURGE).
TCPIP$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
OpenVMS usage:buffer_list
type: vector byte (unsigned)
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length descriptor
(Alpha)
by 32-bit descriptor-fixed-length descriptor (VAX)
Output buffer list describing one or more buffers to hold the
incoming data. The p6 argument is the 32- or 64-bit address
(on Alpha systems) or the 32-bit address (on VAX systems) of
a descriptor that points to a output buffer list. Buffers are
filled in the order specified by the output buffer list. The
transfer-length value returned in the I/O status block is the
total number of bytes transferred to all buffers.
If you use the p1 and p2 arguments, do not use the p6 argument;
they are mutually exclusive.
16. 5. 46. 4. 5.2 - Function Modifiers
IO$M_EXTEND Specifies the format of the socket address
structure to return when used with the p3
argument.
When specified, a BSD Version 4.4 formatted
socket address structure is returned that
identifies the source of the received UDP
datagram or raw IP message.
IO$M_INTERRUPT Reads an out-of-band (OOB) message. This
has the same effect as specifying the
TCPIP$C_MSG_OOB flag in the p4 argument.
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 TCPIP$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 without the OOBINLINE option
set, a received OOB will always be
read by issuing a $QIO with either the
IO$_READVBLK|IO$M_INTERRUPT or IO$_READVBLK
and the TCPIP$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 service calls
issued to read a data stream of a set size.
This function modifier supports only stream
protocols.
IO$M_NOWAIT Regardless of a $QIO or $QIOW, if the
system detects a condition that would
cause the operation to block, the system
completes the I/O operation and returns the
SS$_SUSPENDED status code.
IO$M_PURGE Flushes data from the socket receive queue
(discards data). If the user buffer is larger
than the amount of data in the queue, all data
is flushed.
16. 5. 46. 4. 5.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ABORT Programming error, INET management error, or
hardware error. The execution of the I/O was
aborted.
SS$_ACCVIO Access to an invalid memory location or buffer
occurred.
SS$_BADPARAM One of the following methods was used to
specify a $QIO function with an invalid
parameter:
o An I/O function executed without specifying
a device socket. First issue a $QIO with
the IO$_SETMODE function and the proper
parameters to create the device socket.
o An IO$_READVBLK function that does not
specify a correct buffer address (p1 or p6
is null).
o An IO$_READVBLK function specified an
invalid vectored buffer (p6 is an invalid
descriptor).
o 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
TCPIP$C_MSG_OOB flag with IO$_READVBLK.
SS$_CANCEL The I/O operation was canceled by a $CANCEL
system service.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
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:
o The size of the buffer for an I/O function
is insufficient.
o An IO$_READVBLK specified 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:
o No messages were received, so the receive
operation cannot complete. The socket is
marked as nonblocking.
o 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.
16. 5. 46. 4.6 - IO$_SENSEMODE/IO$_SENSECHAR
The IO$_SENSEMODE and IO$_SENSECHAR functions return one or more
parameters (characteristics) pertaining to the network driver.
Socket names (local and remote peer) are returned by using IO$_
SENSEMODE's p3 and p4 arguments. Other parameters such as socket
and protocol options, are specified in an output parameter list
using the IO$_SENSEMODE p6 argument.
IO$_SENSEMODE p3 and p4 arguments can be used with the p6
argument in a single $QIO system service to return socket names
as well as socket and protocol options. IO$_SENSEMODE processes
arguments in this order: p3, p4, p6. If IO$_SENSEMODE detects an
error, the IOSB contains the error and argument address or the
value that was at fault.
Refer to individual argument descriptions for details about
specifying the type and format of output parameters.
16. 5. 46. 4. 6.1 - Arguments
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_3 descriptor
The port number and internet address of the local name associated
with the socket. The p3 argument is the address of an item_list_3
descriptor that points to the socket address structure into which
the local name is written.
Use the IO$_SENSEMODE function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
Related Functions
The Sockets API equivalent for this function is getsockname().
p4
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_3 descriptor
The port number and internet address of the remote name
associated with the socket's peer. The p3 argument is the address
of an item_list_3 descriptor that points to the socket address
structure into which the peer name is written.
Use the IO$_SENSEMODE function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
Related Functions
The equivalent Sockets API function is getpeername().
p6
OpenVMS usage:output_parameter_list
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
Output parameter list describing one or more parameters to
return. The p6 argument is the address of an item_list_2
descriptor that points to and identifies the type of output
parameter list.
The following are the types of output parameter lists:
Symbolic Name Output Parameter List Type
TCPIP$C_SOCKOPT Socket options
TCPIP$C_TCPOPT TCP protocol options
TCPIP$C_IPOPT IP protocol options
TCPIP$C_IOCTL I/O control commands
Each item_list_3 structure appearing in an output parameter
list describes an individual parameter or item to return. See
<REFERENCE>(op_setsock_tab) for details about socket option
parameters; see <REFERENCE>(tcp_set_tab_opt) for TCP protocol
option parameters; and see <REFERENCE>(ip_set_tab_opt) for
IP protocol option parameters. Unsupported socket or protocol
options are ignored.
Each ioctl_com structure that appears in an output parameter list
contains an I/O control command - the get IOCTL request code and
its associated IOCTL structure address. See <REFERENCE>(ioctl_
cmds2) for details about IOCTL command parameters.
Unsupported socket options are ignored.
The equivalent Sockets API functions are getsockopt() and
ioctl().
16. 5. 46. 4. 6.2 - Function Modifiers
IO$M_EXTEND Specifies the format of the socket address
structure to return when used with the p3 or
p4 arguments.
When specified, a BSD Version 4.4 formatted
socket address structure is returned.
16. 5. 46. 4. 6.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ACCVIO The service cannot access a buffer specified
by one or more arguments.
SS$_BADPARAM Programming error occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o Error occurred processing a socket or
protocol option.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_ILLCNTRFUNC Programming error. The operation is
unsupported for one of the following reasons:
o An invalid IO$_SENSEMODE function for the
interface was specified. The interface does
not have an IOCTL routine.
o An IO$_SENSEMODE function that requires a
socket was specified, but the device did
not have one. Create a socket and then
issue the function.
o An unsupported operation was performed on
at least one of the following protocols:
raw IP, datagram, or stream sockets.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVBUFLEN The size of a socket option buffer specified
with the IO$_SENSEMODE function was invalid.
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 The specified socket was not connected.
SS$_NOOPER Programming error. An attempt to get ARP
information occurred without OPER privilege.
SS$_PROTOCOL A network protocol error occurred. The
address family specified in the socket address
structure is not supported.
SS$_SHUT The local or remote node is no longer
accepting connections.
SS$_UNREACHABLE The remote node is currently unreachable.
16. 5. 46. 4.7 - IO$_SETMODE/IO$_SETCHAR
The IO$_SETMODE and IO$_SETCHAR functions set one or more
parameters (characteristics) pertaining to the network driver.
Sockets are created using the IO$_SETMODE p1 argument. Names are
assigned to sockets using the IO$_SETMODE p3 argument. Active
sockets are converted to passive sockets using the IO$_SETMODE p4
argument. Other parameters, such as socket and protocol options,
are specified in an input parameter list using the IO$_SETMODE p5
argument.
The IO$_SETMODE p1, p3, and p4 arguments can be used with the
p5 argument in a single $QIO system service to set socket names
as well as socket and protocol options. IO$_SETMODE processes
arguments in this order: p1, p3, p4, p5. If IO$_SETMODE detects
an error, the IOSB contains the error and argument address or the
value that was at fault.
Refer to individual argument descriptions for details about
specifying the type and format of input parameters.
16. 5. 46. 4. 7.1 - Arguments
p1
OpenVMS usage:socket_characteristics
type: longword (unsigned)
access: read only
mechanism: by reference
Longword specifying the protocol, socket type, and address
family, of a new socket. The p1 argument is the address of the
longword containing the socket characteristics.
The newly created socket is marked privileged if the image that
creates a socket runs in a process that has a privileged UIC or
has BYPASS, OPER, or SYSPRV privilege.
The following table shows protocol codes:
Protocol Description
TCPIP$C_TCP TCP/IP protocol
TCPIP$C_UDP UDP/IP protocol
TCPIP$C_RAW_ IP protocol
IP
Socket Types lists the valid socket types.
Table 6 Socket Types
Socket Type Description
TCPIP$C_STREAM Permits bidirectional, reliable, sequenced,
and unduplicated data flow without record
boundaries.
TCPIP$C_DGRAM Permits bidirectional data flow with record
boundaries. No provisions for sequencing,
reliability, or unduplicated messages.
TCPIP$C_RAW Permits access to the IP layer; used to develop
new protocols that are layered upon the IP
layer.
The following table shows address family codes:
Address
Family Description
TCPIP$C_AF_ Internet domain (default).
INET
TCPIP$C_AUXS Accept hand-off of a socket already created and
initialized by the auxiliary server.
Related Functions
The equivalent Sockets API function is socket().
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
The local name (that is, port number and internet address) to
assign to the socket. The p3 argument is the address of an item_
list_2 descriptor that points to the socket address structure
containing the local name.
Related Functions
The equivalent Sockets API function is bind() .
p4
OpenVMS usage:connection_backlog
type: byte (unsigned)
access: read only
mechanism: by value
Maximum limit of outstanding connection requests for a socket
that is connection oriented. If more connection requests are
received than are specified, the additional requests are ignored
so that TCP retries can succeed.
Related Functions
The equivalent Sockets API function is listen().
p5
OpenVMS usage:input_parameter_list
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
Input parameter list describing one or more parameters to set.
The p5 argument is the address of an item_list_2 descriptor that
points to and identifies the type of input parameter list.
The following are the types of input parameter lists:
Symbolic Name Input Parameter List Type
TCPIP$C_SOCKOPT Socket options
TCPIP$C_TCPOPT TCP protocol options
TCPIP$C_IPOPT IP protocol options
TCPIP$C_IOCTL I/O control commands
Each item_list_2 structure appearing in an input parameter
list describes an individual parameter or item to set. See
<REFERENCE>(op_setsock_tab) for details about socket option
parameters; see <REFERENCE>(tcp_set_tab_opt) for TCP protocol
option parameters; and see <REFERENCE>(ip_set_tab_opt) for
details about IP protocol option parameters. Unsupported socket
or protocol options are ignored.
Each ioctl_com structure that appears in an input parameter list
contains an I/O control command - the set IOCTL request code and
its associated IOCTL structure address. See <REFERENCE>(ioctl_
cmds2) for details about IOCTL command parameters.
You can use one $QIO system call to set up several socket options
at once.
Unsupported socket options are ignored.
To execute set IOCTL operations, you need a system UIC or SYSPRV,
BYPASS, or OPER privilege.
Related Functions
The equivalent Sockets API functions are setsockopt() and
ioctl().
16. 5. 46. 4. 7.2 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ACCVIO The service cannot access a buffer specified
by one or more arguments.
SS$_BADPARAM Programming error that occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o Error occurred processing a socket or
protocol option.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_DUPLNAM Programming error. The port 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 occurred
for one of the following reasons:
o An attempt to create a new socket with
the IO$_SETMODE function occurred, but the
maximum number of sockets was exceeded.
Increase the maximum number of sockets
(INET parameter).
o 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. An attempt to bind the socket to an
address and port failed.
SS$_ILLCNTRFUNC Programming error. The operation is not
supported for one of the following reasons:
o An invalid IO$_SETMODE function for the
interface occurred that does not have an
IOCTL routine.
o An attempt to perform an IO$_SETMODE
function 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:
o Port zero and INET address zero are not
allowed, or port zero is not allowed
when using an IO$_ACCESS or IO$_WRITEVBLK
function.
o An attempt to exceed the limit of allowable
permanent entries in the ARP table
occurred.
o An attempt to bind a raw IP socket when
there are no interfaces defined in the
system occurred.
o An attempt to bind a raw IP socket to a
null INET address occurred.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVBUFLEN The size of a socket option buffer specified
with the IO$_SETMODE function was invalid.
SS$_NOLICENSE Programming or system management error. A
TCP/IP Services license is not present.
SS$_NOOPER Programming or INET management error. An
attempt to execute an I/O function that needs
the OPER privilege occurred.
SS$_NOPRIV Programming or INET management error. There
are not enough privileges for the attempted
operation for one of the following reasons:
o An attempt to broadcast an IP datagram on
a process without a system UIC or SYSPRV,
BYPASS, or OPER privilege occurred.
o An attempt to use a reserved port number
lower than 1024 occurred.
o An attempt to access a process that
requires a system UIC or SYSPRV, or BYPASS
privilege occurred.
o An attempt to use raw IP on a privileged
socket that requires the SYSPRV or BYPASS
privilege occurred.
SS$_NOSUCHDEV Programming error or INET management error. An
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.
An attempt to delete a route from the routing
table failed because the entry was not found.
SS$_PROTOCOL Programming error. A specified protocol or
address family caused an error for one of the
following reasons:
o An invalid protocol type was specified at
socket creation.
o An unsupported protocol was specified.
o A protocol type that was not found in the
internal tables was specified.
o The address family is unsupported for one
of the following reasons:
- An unsupported address family with the
IO$_SETMODE subfunction was specified.
Instead, specify the TCPIP$C_AF_INET or
TCPIP$C_UNSPEC address family.
- An unsupported address family for a
remote INET address with the IO$_ACCESS
or IO$_WRITEVBLK function was specified.
Instead, specify the TCPIP$C_AF_INET
address family.
- An unsupported address family for the
local INET address with the IO$_SETMODE
function was specified. Instead, specify
the TCPIP$C_AF_INET address family.
- An unsupported address family for the
INET address of the routing module was
specified. Instead, specify the TCPIP$C_
AF_INET address family.
SS$_SHUT The local or remote node is no longer
accepting connections.
16. 5. 46. 4.8 - 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 must be a
TCP (stream) socket.
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.
16. 5. 46. 4. 8.1 - Arguments
p1
OpenVMS usage:ast_procedure
type: procedure value
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
OpenVMS 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
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to deliver the AST.
16. 5. 46. 4. 8.2 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ABORT Programming, INET management, or hardware
error.
SS$_ACCVIO Programming error. An attempt to access an
invalid memory location or buffer occurred.
SS$_BADPARAM Programming error. A $QIO service with an
invalid parameter occurred for one of the
following reasons:
o An attempt 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.
o A socket option was specified incorrectly.
SS$_DEVACTIVE INET management error. An attempt to change
the static INET parameters occurred. If new
parameters are needed, shut down the internet,
reset the static parameters, and issue the
START COMMUNICATION command.
SS$_DEVINTACT INET management error. The driver was not
started. Issue a START COMMUNICATION command
before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. The INET startup
procedure executed incorrectly. The driver was
loaded, but the INET_ACP was not activated.
Execute the INET startup procedure again.
SS$_DUPLNAM Programming error. An attempt to bind a port
that is already in use occurred. An attempt to
bind the socket to an address and port failed.
SS$_EXQUOTA Programming or INET management error occurred
because of one of the following reasons:
o An attempt to create a new socket with the
IO$_SETMODE function failed because the
maximum number of sockets was exceeded.
Increase the maximum number of sockets
(INET parameter).
o 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:
o Invalid IO$_SETMODE (IOCTL) function was
used for the interface. The interface does
not have an IOCTL routine.
o An attempt 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:
o An attempt to bind the address failed
because the INET address is not in the
system and port zero and INET address zero
are not allowed.
o An attempt to make a permanent entry in an
ARP table that was full failed.
o An attempt was made to bind an IP socket
(raw IP) when there are no interfaces
defined in the system.
o 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. TCP/IP
Services 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:
o Broadcasting an IP datagram was denied
because the process does not have a system
UIC or SYSPRV, BYPASS, or OPER privilege.
o An attempt was made to use a reserved port
number lower than 1024.
o An operation accesses only processes that
have a system UIC or SYSPRV or BYPASS
privilege.
o 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 because of one of the
following reasons:
o The protocol type specified at socket
creation is not valid.
o The protocol is not supported.
o The protocol type specified is not found
in the internal tables and therefore is an
invalid type.
o The address family is not supported for one
of the following reasons:
- The address family specified with an
IO$_SETMODE function (IOCTL subfunction)
is not supported. The address family
should be the TCPIP$C_AF_INET or
TCPIP$C_UNSPEC address family.
- The address family of the local INET
address specified with an IO$_SETMODE
(bind) function is not supported. The
address family should be the TCPIP$C_AF_
INET address family.
- The address family of the INET address
specified in a request to the routing
module is not supported. The address
family should be the TCPIP$C_AF_INET
address family.
SS$_SHUT The local or remote node is no longer
accepting connections.
16. 5. 46. 4.9 - 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.
The Enable Read Attention AST function enables an Attention AST
to be delivered to the requesting process only once. After the
AST occurs, the function must explicitly reenable 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:
- An enabled Read Attention AST
- The TCPIP$C_OOBINLINE socket option
- A READ $QIO waiting for completion on the socket
If the TCPIP$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 TCPIP$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 TCPIP$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.
16. 5. 46. 4. 9.1 - Arguments
p1
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
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
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be delivered to the AST routine.
p3
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to deliver the AST.
16. 5. 46. 4. 9.2 - Condition Values Returned
SS$_ABORT Programming, INET management, or hardware
error. The route entry already exists, so
the attempt to add a route entry using the
IO$_SETMODE function failed.
SS$_ACCVIO Programming error. An attempt to access an
invalid memory location or buffer occurred.
SS$_BADPARAM Programming error. The parameter specified
for a $QIO function was invalid for one of the
following reasons:
o An attempt to execute the IO$_SETMODE
subfunctions without specifying a device
socket occurred. Instead, create a device
socket by issuing a $QIO with the IO$_
SETMODE function and the proper parameters.
o A socket option was specified incorrectly.
SS$_DEVACTIVE INET management error. An attempt to change
the static INET parameter was unsuccessful.
If you need new parameters, shut down the
internet, reset the static parameters, and
issue the START COMMUNICATION command.
SS$_DEVINTACT INET management error. The driver was not
started. Issue a START COMMUNICATION command
before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. TCP/IP Services
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. An attempt to bind a port
already in use occurred 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:
o An attempt to exceed the maximum number
of sockets by creating new socket with the
IO$_SETMODE function occurred. Increase the
maximum number of allowable sockets (INET
parameter) before creating more sockets.
o The number of sockets specified with the
IO$_SETMODE function 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. An attempt to bind the
socket to an address that is already in use
occurred and the operation failed.
SS$_INSFMEM Programming or system management error. The
system does not have enough resources to
allocate new socket.
SS$_ILLCNTRFUNC Programming error. Operation is not supported.
o Invalid IO$_SETMODE (IOCTL) function was
used for the interface. The interface does
not have an IOCTL routine.
o 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).
o 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.
o An attempt to make a permanent entry in the
ARP table failed because of lack of space.
Too many permanent entries.
o An attempt was made to bind an IP socket
(raw IP) when there are no interfaces
defined in the system.
o 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. TCP/IP
Services 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.
o Broadcasting an IP datagram was denied
because the process does not have a system
UIC or SYSPRV, BYPASS, or OPER privilege.
o An attempt was made to use a reserved port
number lower than 1024.
o An operation accesses only processes that
have a system UIC or SYSPRV, or BYPASS
privilege.
o 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.
o The protocol type specified at socket
creation is not valid.
o The protocol is not supported.
o The protocol type specified is not found in
the internal tables. It is an invalid type.
o The address family is not supported:
- The address family specified with an
IO$_SETMODE function (IOCTL subfunction)
is not supported. The address family
should be the TCPIP$C_AF_INET or
TCPIP$C_UNSPEC address family.
- 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 TCPIP$C_AF_INET address
family.
- The address family of the local INET
address specified with an IO$_SETMODE
(bind) function is not supported. The
address family should be the TCPIP$C_AF_
INET address family.
- 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 TCPIP$C_AF_
INET address family.
SS$_SHUT The local or remote node is no longer
accepting connections.
16. 5. 46. 4.10 - IO$_SETMODE|IO$M_WRTATTN
The IO$_SETMODE|IO$M_WRTATTN function/modifier combination (IO$M_
WRTATTN is Enable Write Attention AST) 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 space
becomes available in the TCP transmit queue.
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 reenable 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 enabled 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 management command SHOW DEVICE_SOCKET to display
information about the socket's characteristics, options, and
state.
16. 5. 46. 4. 10.1 - Arguments
p1
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
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
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be delivered to the AST routine.
p3
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to deliver the AST.
16. 5. 46. 4. 10.2 - Condition Values Returned
SS$_ABORT Programming error, INET management error,
or hardware error. The route specified with
the IO$_SETMODE function already exists.
Therefore, the operation failed.
SS$_ACCVIO Programming error. An attempt to access an
invalid memory location or buffer occurred.
SS$_BADPARAM Programming error. The parameter specified for
the $QIO I/O function was invalid for one of
the following reasons:
o An attempt to execute the IO$_SETMODE
functions without specifying a device
socket occurred. Instead, create a device
socket by issuing a $QIO with the IO$_
SETMODE function and the proper parameters.
o A socket option was specified incorrectly.
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$_DEVINTACT INET management error. The driver is not
started. Issue a 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.
o An attempt 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.
o The number of sockets 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, an 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 a new
socket.
SS$_ILLCNTRFUNC Programming error. The operation is
unsupported for one of the following reasons:
o An invalid IO$_SETMODE function for the
interface was specified. The interface does
not have an IOCTL routine.
o An attempt 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. An invalid port number and
INET address combination was specified with
the IO$_SETMODE bind function. This caused
the operation to fail for one of the following
reasons:
o An illegal combination of port zero and
INET address zero was specified.
o An attempt to make a permanent entry in
the ARP table occurred, and the operation
failed because of lack of space. There are
too many permanent entries.
o An attempt to bind a raw IP socket occurred
when there were no interfaces defined in
the system.
o An attempt to bind a raw IP socket to a
null INET address occurred.
SS$_IVBUFLEN Programming error. An invalid size was
specified for the socket option buffer.
SS$_NOLICENSE Programming or system management error. There
is no TCP/IP Services license present.
SS$_NOOPER Programming or INET management error. An
attempt to execute an I/O function that needs
the OPER privilege occurred.
SS$_NOPRIV Programming or INET management error. The
operation failed for one of the following
reasons:
o An attempt to broadcast an IP datagram for
a process without having a system UIC or
SYSPRV, BYPASS, or OPER privilege.
o An attempt to use a reserved port number
lower than 1024 occurred.
o An attempt to access a process without
having a system UIC or SYSPRV, or BYPASS
privilege occurred.
o An attempt to use raw IP on a socket that
is not a privileged socket occurred. To
do this, the process must have SYSPRV or
BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error. An
attempt to show or delete an entry in the
ARP table occurred. However, because the
INET address was not in the ARP table, the
operation failed.
SS$_NOSUCHNODE Programming error or INET management error.
An attempt to delete a route from the routing
information table (RIT) occurred. However,
because the route was not found in the RIT,
the operation failed.
SS$_PROTOCOL Programming error.
o An invalid protocol type was specified when
creating a socket.
o An unsupported protocol was specified.
o An unsupported protocol type was specified
because it is not found in the internal
tables.
o An unsupported address family was specified
for one of the following reasons:
- An invalid address family was
specified with an IO$_SETMODE
subfunction. Instead, specify the
TCPIP$C_AF_INET or TCPIP$C_UNSPEC
address family.
- An address family of the remote INET
address for a datagram or stream
socket was specified with an IO$_
ACCESS or IO$_WRITEVBLK function.
Instead, specify the TCPIP$C_AF_INET
address family.
- An invalid address family of the
local INET address was specified
with an IO$_SETMODE bind function.
Instead, specify the TCPIP$C_AF_INET
address family.
- You made a request to the routing
module by specifying the address
family of the INET address. Instead,
specify the TCPIP$C_AF_INET address
family.
SS$_SHUT The local or remote node is no longer
accepting connections.
16. 5. 46. 4.11 - IO$_WRITEVBLK
The IO$_WRITEVBLK function transmits data from the specified
user buffers to an internet host. Use both p1 and p2 arguments
to specify a single user buffer. Use the p5 argument to specify
multiple buffers.
For connection-oriented protocols, such as TCP, if the socket
transmit buffer is full, the IO$_WRITEVBLK function is blocked
until the socket transmit buffer has room for the user data.
For connectless-oriented protocols, such as UDP and raw IP, the
user data is transmitted in one datagram. If the user data is
greater than the socket's transmit quota, the error code (SS$_
TOOMUCHDATA) is returned.
Related Functions
The equivalent Sockets API functions are send(), sendto(),
sendmsg(), and write().
16. 5. 46. 4. 11.1 - Arguments
p1
OpenVMS usage:buffer
type: vector byte (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
by 32-bit reference (VAX)
The 32- or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of the buffer containing the data to
be transmitted. The length of this buffer is specified by the p2
argument.
p2
OpenVMS usage:buffer_length
type: quadword unsigned (Alpha); longword unsigned (VAX)
access: read only
mechanism: by 64-bit value (Alpha)
by 32-bit value (VAX)
The length (in bytes) of the buffer containing data to be
transmitted. The address of this buffer is specified by the p1
argument.
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
The remote port number and internet address of the message
destination. The p3 argument is the address of an item_list_2
descriptor pointing to the socket address structure containing
the remote port number and internet address.
p4
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of flags to specify attributes for this write operation.
The following table lists the available write flags:
Write Flag Description
TCPIP$C_MSG_OOB Writes an out-of-band (OOB) byte.
TCPIP$C_MSG_ Sends message directly without routing.
DONTROUTE
TCPIP$C_MSG_NBIO Completes the I/O operation and returns
an error if a condition arises that would
cause the I/O operation to be blocked.
(Similar to using IO$M_NOWAIT.)
p5
OpenVMS usage:buffer_list
type: vector byte (unsigned)
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length descriptor
(Alpha)
by 32-bit descriptor-fixed-length descriptor (VAX)
Input buffer list describing one or more buffers containing the
data to be transmitted. The p5 argument is the 32- or 64-bit
address (on Alpha systems) or the 32-bit address (on VAX systems)
of a descriptor pointing to a input buffer list. Buffers are
transmitted in the order specified by the input buffer list. The
transfer-length value returned in the I/O status block is the
total number of bytes transferred from all buffers.
If you use the p1 and p2 arguments, do not use the p5 argument;
they are mutually exclusive.
16. 5. 46. 4. 11.2 - Function Modifiers
IO$M_EXTEND Allows the use of extended modifiers with BSD
Version 4.4. Valid only for datagram sockets
(UDP or raw IP); ignored for TCP.
IO$M_INTERRUPT Sends an OOB message.
IO$M_NOWAIT Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the
operation to block, the system completes the
I/O operation and returns the SS$_SUSPENDED
status code.
When using this function modified, always
check the message length in the IOSB to ensure
that all data is transferred. IO$_WRITEVBLK
returns a success status even if data is only
partially transferred.
16. 5. 46. 4. 11.3 - 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.
o 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.
o An attempt was made to issue an
IO$_WRITEVBLK function that did not specify
a correct buffer address (p1 or p5 is
null).
o An attempt was made to issue an IO$_
WRITEVBLK that specifies an invalid
vectored buffer (p5 specifies an invalid
address descriptor).
SS$_CANCEL The I/O operation was canceled by the $CANCEL
system service.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
in not currently available for use.
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.
o INET address is already in use. An attempt
was made to bind the socket to an address
but the port failed.
o 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.
o 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.
o 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.
o An attempt to get an interface INET
address, broadcast mask, or network mask
failed.
o A send request was made on a datagram-
oriented protocol, but the destination
address is unknown or not specified.
SS$_IVBUFLEN Programming error.
o The size of the buffer for an I/O function
is insufficient.
o 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 must either shut
down 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 TCPIP$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).
o 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).
o 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).
o An attempt was made to disconnect a socket
that is not connected, or an attempt was
made to issue an IO$_WRITEVBLK function on
an unconnected socket (TCP/IP).
SS$_SHUT The local or remote node is no longer
accepting connections.
SS$_SUSPENDED The system detected a condition that might
cause the operation to block.
SS$_TIMEOUT Programming error, INET management error, or
hardware error.
o A TCP/IP connection timed out after several
unsuccessful retransmissions.
o On a TCP socket where KEEPALIVE is set,
the connection was idle for longer than
the timeout interval (The default is 10
minutes).
SS$_TOOMUCHDATA Programming or INET management error. The
message size was too large.
o An IP packet that is broadcast cannot be
fragmented.
o The Not Fragment IP flag was set and the IP
datagram was too large to be sent without
being fragmented.
o Internal error. The length of the Ethernet
datagram does not allow enough space for
the minimum IP header.
o The message to be sent on a UDP/IP or raw
IP socket is larger than the socket buffer
high water allows.
o An attempt was made to send or receive
more than 16 buffers specified with the p5
argument.
SS$_UNREACHABLE Communication status. The remote host is
currently unreachable.
Hardware error. The data link adapter detected
an error and shut itself off. The TCP/IP
Services software is waiting for the adapter
to come back on line.
16. 5. 46.5 - TELNET Port Driver QIO Interface
The TELNET port driver (TNDRIVER) provides terminal session
support for TCP stream connections using the RAW, NVT, RLOGIN,
and TELNET protocols. Either a remote device or an application
can be present at the remote endpoint of the connection.
A user program can manage a TELNET connection with the standard
OpenVMS $QIO system service by using the IO$_TTY_PORT and IO$_
TTY_PORT_BUFIO I/O function codes. This section describes these
I/O function codes and their associated arguments.
16. 5. 46. 5.1 - Interface Definition
The following definitions are used by the interface. The symbols
are defined in SYS$LIBRARY:TNIODEF.H.
16. 5. 46. 5. 1.1 - Item List Codes
List Codes for the p5 Item describes the symbols used with the p5
parameter.
Table 7 List Codes for the p5 Item
Maximum
Item Code Size Description
TN$_ACCPORNAM 64 Access port name string. When
written, the string's length is
determined by the item_length
field. The value of item_length
should not be more than 63 bytes.
When read, the string is returned
in ASCIC format (the first byte
contains the string's length), so a
size of 64 is appropriate.
TN$_ 4 Characteristics mask. This longword
CHARACTERISTICS contains a bit mask of the device's
characteristics read or to be
written. (See Characteristic Mask
Bits.)
TN$_CONNECTION_ 4 Reconnection attempts. This item
ATTEMPTS is the number of unsuccessful
reconnection attempts which have
been made on a reconnectable
device. The value will be
reinitialized when a successful
connection is made. This item is
read only.
TN$_CONNECTION_ 4 Minimum time (in seconds) before
INTERVAL reconnection attempts.
TN$_CONNECTION_ 4 Current time (in seconds) since
TIMEOUT the last reconnection attempt. This
item is read only.
TN$_DATA_HIGH 4 Maximum amount of output data (in
bytes) buffered at the network
port. This number does not affect
the amount of data buffered within
the socket.
TN$_DEVICE_UNIT 4 Terminal device unit number. When
written, this value must be between
1 and 9999.
TN$_IDLE_INTERVAL 4 Maximum idle time (in seconds)
allowed before a connection is
to be broken. Connections are not
broken if the device is stalled.
TN$_IDLE_TIMEOUT 4 Current time (in seconds) since
last output on the terminal. This
item is read only.
TN$_LOCAL_ADDRESS 32 Local sockaddr of the active
connection. When written, the
value of item_length determines
the size of the sockaddr. Note that
the sockaddr is in BSD Version 4.4
format, which includes a sockaddr
size field. (C programs should be
compiled with the _SOCKADDR_LEN
symbol defined.) This item is read
only.
TN$_NETWORK_ 64 Name of the network pseudodevice
DEVICE_NAME currently bound to the terminal.
When read, the data is returned
in ASCIC format (the first byte
contains the string's length). This
item is read only.
TN$_PROTOCOL 4 Session protocol. (See Protocol
Type Codes.)
TN$_REMOTE_ADDRESS 32 Remote peer's sockaddr of the
active connection. Note that
the sockaddr is in BSD Version
4.4 format, which includes a
sockaddr size field. The size of
the sockaddr should be determined
from this field. This item is read
only.
TN$_SERVICE_TYPE 4 Class of terminal service. (See
Service Type Codes.)
TN$_STATUS 4 Current device and session status.
This item is read only.
16. 5. 46. 5. 1.2 - Characteristic Mask Bits
Characteristic Mask Bits describes the characteristic mask bits
used with the p5 parameter.
Table 8 Characteristic Mask Bits
Characteristic Description
TN$M_AUTOCONNECT The device supports automatic
connect/reconnect.
TN$M_LOGIN_ON_ Initiate a login when the TELNET device is
DASSGN deassigned. This characteristic requires the
BYPASS or SYSNAM privilege or executive or
kernel mode calls.
TN$M_LOGIN_TIMER Used in conjunction with TN$M_LOGIN_ON_DASSGN,
this bit indicates that the login completion
timer applies. If the TN device fails to
login within 60 seconds, the connection will
be broken and the device deallocated. This
characteristic requires the BYPASS or SYSNAM
privileges or executive or kernel mode calls.
TN$M_PERMANENT_ The TELNET device is to remain until
UCB explicitly deleted.
TN$M_RETAIN_ON_ The TELNET device is not to be deleted upon
DASSGN the deassignment of the last channel to this
device. This condition is cleared on this
last deassignment, so that a subsequent assign
and deassign will result in the device being
deleted.
TN$M_VIRTUAL_ When logging in under this device, a virtual
TERMINAL terminal is to be created by TTDRIVER.
16. 5. 46. 5. 1.3 - Protocol Types
Protocol Type Codes describes the protocol types used with the p5
parameter.
Table 9 Protocol Type Codes
Protocol Type Description
TN$K_PROTOCOL_ There is no explicit protocol for this
UNDEFINED session. Data is transmitted and received
on the socket without any interpretation.
This is a raw connection.
TN$K_PROTOCOL_NVT Network Virtual Terminal (NVT) protocol.
The protocol understands basic session
control but does not include the options
negotiation present in the TELNET
protocol.
TN$K_PROTOCOL_RLOGIN BSD Remote Login protocol. This simple
protocol provides some special control
character support but lacks the
architecture independence of the NVT and
TELNET protocols.
TN$K_PROTOCOL_TELNET TELNET protocol. Including the basic NVT
protocol, TELNET adds support for options
negotiation. This can provide an enhanced
terminal session depending upon the client
and server involved.
16. 5. 46. 5. 1.4 - Service Types
Service Type Codes describes the service type codes used with the
p5 parameter.
Table 10 Service Type Codes
Service Type Description
TN$K_SERVICE_NONE The service type is not currently known.
TN$K_SERVICE_ The service is an incoming connection.
INCOMING
TN$K_SERVICE_ The service is an outgoing connection.
OUTGOING
16. 5. 46. 5.2 - Passing Parameters to the TELNET Port Driver
The IO$_TTY_PORT function is used to pass $QIO parameters
through the terminal driver to the TELNET port driver. The actual
subfunction is encoded as an option mask and may be:
o IO$M_TN_STARTUP - Bind socket to a TELNET terminal.
o IO$M_TN_SHUTDOWN - Unbind socket from a TELNET terminal.
16. 5. 46.6 - IO$_TTY_PORT|IO$M_TN_STARTUP
Bind socket to a TELNET terminal.
This subfunction will bind a created (connected) socket to a
TELNET terminal device.
16. 5. 46. 6.1 - Arguments
p1
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
The p1 argument contains the channel number of the socket over
which the TELNET session is to be established.
p2
OpenVMS usage:protocol_number
type: longword (unsigned)
access: read only
mechanism: by value
The p2 argument contains the protocol selection.
p3
OpenVMS usage:characteristics_mask
type: longword (unsigned)
access: read only
mechanism: by value
The p3 argument specifies a mask of characteristics to apply
against the connection. See Characteristic Mask Bits for possible
values.
16. 5. 46. 6.2 - Description
The IO$M_TN_STARTUP subfunction allows the application to
communicate over a socket using the terminal driver QIO
interface. Note that incoming and outgoing data is processed
by the terminal driver, and that the terminal's characteristics
may affect the format of the data. Be aware that by default, the
terminal will echo incoming data back to the sender.
Once the subfunction completes, the application is free to
perform all terminal QIO functions on the connection. While the
socket is bound to a terminal device, it will process neither the
IO$_READxBLK nor the IO$_WRITExBLK function, and will return the
error SS$_DEVINUSE.
16. 5. 46. 6.3 - Condition Values Returned
SS$_IVCHAN Programming error. The specified channel is
not valid.
SS$_IVMODE Programming error. The access mode of the
channel is more privileged than the access
mode of the terminal's channel.
SS$_NOPRIV Programming error. The TN$M_LOGIN_ON_
DASSGN characteristic was specified in a
characteristics mask from a QIO in USER or
SUPERVISOR mode without either the BYPASS or
SYSPRV privilege.
SS$_NOTNETDEV Programming error. The specified channel is an
assignment to a non-BG device.
SS$_PROTOCOL Programming error. The specified protocol
number is not valid, or the internet network
is not available.
16. 5. 46.7 - IO$_TTY_PORT|IO$M_TN_SHUTDOWN
Unbind socket from a TELNET terminal.
This subfunction will unbind a previously bound socket-terminal
connection.
16. 5. 46. 7.1 - Arguments
p1
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
The p1 argument contains the channel number of the socket to
establish the TELNET session.
16. 5. 46. 7.2 - Description
The IO$M_TN_SHUTDOWN subfunction allows the application to break
a previously bound socket-terminal connection (created with IO$M_
TN_STARTUP). The channel must be from an assignment to the same
network pseudodevice in the socket-terminal connection.
Upon completion, the application retains the assignments to
the connection and the TELNET terminal, but they are no longer
related. Any subsequent IO$_READxBLK or IO$_WRITExBLK function on
the socket channel will no longer return the error SS$_DEVINUSE.
16. 5. 46. 7.3 - Condition Values Returned
SS$_IVCHAN Programming error. The specified channel is
not valid.
SS$_IVMODE Programming error. The access mode of the
channel is more privileged than the access
mode of the terminal's channel.
SS$_NOTNETDEV Programming error. The specified channel is an
assignment to a non-BG device.
SS$_DEVREQERR Programming error. The device on the channel
does not match the device in the socket-
terminal connection.
16. 5. 46. 7.4 - Buffered Reading and Writing of Item Lists
The IO$_TTY_PORT_BUFIO function is used to pass $QIO parameters
through the terminal driver to the TELNET port driver. IO$_TTY_
PORT_BUFIO differs from IO$_TTY_PORT in that certain subfunctions
accept buffered item lists for reading or writing parameters to
the terminal device.
o IO$M_TN_SENSEMODE - Read device parameters.
o IO$M_TN_SETMODE - Write device parameters.
The subfunctions of IO$_TTY_PORT_BUFIO accept an item list for
input or output. Subfunction Item List shows the format of this
item list.
The item list is terminated with an item_code and item_length,
both of which are zero.
The subfunctions of IO$_TTY_PORT_BUFIO can be combined into
a single QIO. For example, the IO$M_TN_SETMODE and IO$M_TN_
CONNECT can be combined to set the device's parameters and then
to attempt to make a connection.
The subfunctions are performed in the following order:
1. IO$M_TN_SETMODE
2. IO$M_TN_CONNECT
3. IO$M_TN_SENSEMODE
4. IO$M_TN_DISCON
NOTE
Certain items are read only (IO$M_TN_SENSEMODE) and cannot
be written (IO$M_TN_SETMODE). Normally, attempting to write
such items would result in the error SS$_BADATTRIB. However,
if a combination operation (IO$M_TN_SENSEMODE|IO$M_TN_
SETMODE) is being performed, these items will not result
in an error. Rather, the items will be ignored in the IO$M_
TN_SETMODE processing, and the QIO will continue with IO$M_
TN_SENSEMODE processing, returning the information that the
item specifies.
16. 5. 46. 7.5 - IO$_TTY_PORT_BUFIO|IO$M_TN_SENSEMODE
Read device parameters.
16. 5. 46. 7. 5.1 - Arguments
p5
OpenVMS usage:item_list_2
type: vector byte (unsigned)
access: read only
mechanism: by reference
The p5 argument is the address of an item list that contains a
summary of information to be read from the device.
16. 5. 46. 7. 5.2 - Description
The IO$M_TN_SENSEMODE subfunction of IO$_TTY_PORT_BUFIO is used
to read the parameters associated with a device.
16. 5. 46. 7. 5.3 - Condition Values Returned
SS$_BADATTRIB Programming error. The item code within the
list is not valid. This could be because of
its code, an attempt to write a read-only
parameter, or inappropriate size. The address
of the item's buffer is returned in the second
longword of the I/O status block.
SS$_IVBUFLEN Programming error. The length of the specified
item is not acceptable. The address of the
item's buffer is returned in the second
longword of the I/O status block.
SS$_NOPRIV Programming error. An item that requires a
privilege which the requestor does not have
is present in the item list. The address of
the item's buffer is returned in the second
longword of the I/O status block.
16. 5. 46. 7.6 - IO$_TTY_PORT_BUFIO|IO$M_TN_SETMODE
Write device parameters.
16. 5. 46. 7. 6.1 - Arguments
p5
OpenVMS usage:item_list_2
type: vector (byte unsigned)
access: read only
mechanism: by reference
The p5 argument is the address of an item list that contains a
summary of information to be written to the device.
16. 5. 46. 7. 6.2 - Description
The IO$M_TN_SETMODE subfunction of IO$_TTY_PORT_BUFIO is used to
write the parameters associated with a device.
16. 5. 46. 7. 6.3 - Condition Values Returned
SS$_BADATTRIB Programming error. The item code within the
list is not valid. This could be because of
its code, an attempt to write a read-only
parameter, or inappropriate size. The address
of the item's buffer is returned in the second
longword of the I/O status block.
SS$_DUPLNAM Programming error. An attempt to set the
device's unit number via the TN$_DEVICE_UNIT
item has failed because that specified unit
number was already present.
SS$_IVBUFLEN Programming error. The length of the specified
item is not acceptable. The address of the
item's buffer is returned in the second
longword of the I/O status block.
SS$_NOPRIV Programming error. An item that requires a
privilege which the requester does not have
is present in the item list. The address of
the item's buffer is returned in the second
longword of the I/O status block.
| 17 - Finger |
For displaying information about users on remote systems and your
local system, the DIGITAL TCP/IP Services for OpenVMS 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
The Finger software must be enabled (see your system manager).
If the Finger software is not enabled on your local OpenVMS host,
when you attempt to display information about users on that host,
an error message is returned. For example, the following error
message indicates the Finger image was not installed with the
privileges required. See your system manager.
%SYSTEM-S-NOTALLPRIV, not all requested privileges authorized
The Finger utility must be enabled on any remote host for which
you want information. If the software does not exist or is
disabled on the remote host, an error message is returned, such
as the following:
FINGER-I-CONNREF, Connection refused
17.1 - User Requirements
Use the following rules for command syntax, quotation marks, and
wildcards when you enter FINGER command lines.
o 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
o Wildcards - Wildcards are not accepted for OpenVMS hosts, but
may be valid for some UNIX hosts.
o 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 3-MAR-1998 09:05:29
Unread mail: 25
Project: Homeopathic medicine/Silica
No Plan.
Login name: /FULL In real life: ???
o 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.
17.2 - Examples
1. 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 SCIENCE:
$ 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
2. 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.
$ 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 3-MAR-1998 10:15:39
No unread mail
Project: Inventory
No Plan.
3. 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 TCPIP$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 TCPIP$UCP Thu 10:30 llevine.philos.ucd.edu
MILLLER UCDALP TCPIP$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
4. 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 TCPIP$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 TCPIP$UCP Thu 10:30 slevine.philos.ucd.edu
MILLLER Paul Miller UCDALP TCPIP$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
| 18 - FTP |
FTP - the File Transfer Protocol - 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
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 Remote_Commands.
To use FTP, you need the following:
o A user account on the OpenVMS system with access to DIGITAL
TCP/IP Services for OpenVMS
o One of the following:
- A user account on the remote FTP host
- Access to the remote host's ANONYMOUS user account
18.1 - Command Summary
To use FTP, enter the commands summarized below. For complete
descriptions (including UNIX equivalents) of each command, type
the following:
$ FTP
FTP>HELP
Command Description
Starting and Exiting (At the DCL Prompt)
FTP Invokes FTP
FTP remote_host Invokes FTP and establishes a connection to
a remote host
Starting and Exiting (At the FTP> Prompt)
CONNECT Establishes a connection to a remote host
DISCONNECT Closes the connection with the remote host
EXIT Closes the connection with the remote host
Ctrl/Z and exits FTP
Sending Commands to the Remote Host
APPEND Appends a local file to a remote file
CREATE/DIRECTORY Creates a remote directory
DELETE Deletes remote files
DIRECTORY Lists remote file names and related
information
GET Copies files from the remote host to the
local host
LOGIN Logs you in to a remote host
PUT Copies files from the local host to the
remote host
RENAME Renames remote files
SET DEFAULT Sets the remote working directory or the
local working directory
SHOW DEFAULT Displays the name of the current working
directory
VIEW Displays the contents of a file on the
current output device.
Suspending FTP to Return to DCL Prompt
SPAWN Suspends FTP to create a subprocess at the
local DCL prompt
Customizing Your Session's Environment
DISABLE LOG Disables the display of all the protocol
commands sent to the remote host
DISABLE PARSE Disables the expansion of file names
DISABLE Disables the sending of the FTP protocol
PORT_COMMAND PORT command
DISABLE REPLY Disables the display of all responses from
the remote host
DISABLE Disables the display of # for each 1K bytes
TRANSFER_VERIFICATION of data transferred
DISABLE Disables the special OpenVMS-to-OpenVMS
VMS_PLUS transfer mode
ENABLE LOG Enables the display of all protocol
commands sent to the remote host
ENABLE PARSE Enables the expansion of file names
ENABLE Enables the sending of the FTP protocol
PORT_COMMAND PORT command
ENABLE REPLY Enables the display of all responses from
the remote host
ENABLE Enables the display of # for each 1K bytes
TRANSFER_ of data transferred
VERIFICATION
ENABLE Enables the special OpenVMS-to-OpenVMS
VMS_PLUS transfer mode
HELP Invokes help
QUOTE Sends FTP commands to the remote host
without local interpretation
SET TYPE Defines the data representation for file
transfers
SHOW STATUS Displays the current FTP parameter settings
and, if you have an open connect, the name
of the connected host
SPAWN Spawns a subprocess at the DCL prompt
18.2 - FTP Conventions
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
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 MY.DOC "/usr/users/evt/my.doc"
200 PORT command successful.
150 Opening ASCII mode data connection for /usr/users/evt/mydoc (130.180.4.8,1
789).
226 Transfer complete.
local: WORK1$:[VANA]MY.DOC;2 remote: /usr/users/evt/my.doc
289 bytes sent in 00:00:00.01 seconds (20.15 Kbytes/s)
FTP>
o Wildcards
You can use wildcards in the following FTP commands: DELETE,
DIRECTORY, GET, PUT, MGET, MPUT, MDELETE, and MLS.
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
In a DCL-style command line, you can place a command qualifier
anywhere on the command line. It is a good practice to follow
the OpenVMS recommendation to place the qualifier after the
command name.
18.3 - Starting FTP
You can start an FTP session in any of the following ways:
o At the DCL prompt, enter the FTP command and specify a remote
host.
o At the DCL prompt, enter the FTP command with no parameters.
At the FTP prompt, enter the CONNECT or open command,
specifying a remote host.
o By using the /FTP qualifier on the DCL COPY and DIRECTORY
commands.
o Invoke and use FTP from a command procedure
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.
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 5.0) ready
Connected to SITE1.midwest.billing.bench.com.
Name (SITE1:antel): crowe <return>
331 Username CROWE requires a Password
Password: <Return> password not echoed
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.
18. 3.1 - Examples
The following example connects to host XENO using the FTP
command:
$ FTP XENO /USER="bennings" /PASSWORD="keysimpl"<Return>
220 xeno FTP Server (Digital UNIX Version 5.60) 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 Version 5.60) ready
Connected to sanfran.golden.com.
Name (sanfran:dave): <Return>
331 Password required for dave
Password: (password not echoed) <Return>
230 User logged in
FTP>
18.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
- Enter GET and PUT commands to copy files to and from
GUEST$PUBLIC.
- The public area is read-only. You can enter 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.
18. 4.1 - Examples
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 5.0) 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
on Internet Host TRACTPLAN
Date 04-24-97
FTP>
18.5 - Exiting FTP
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.
18. 5.1 - Examples
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>
18.6 - 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 (130.180.4.8,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
18.7 - 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.
or
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.
FTP> pwd
257 "/usr/users/robert" is current directory.
18.8 - 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;*
18.9 - 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. 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.
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 and do not specify an output file:
- The version numbers become the last element of the copied
files.
- Semicolons are converted to periods.
18. 9.1 - 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.
18. 9.2 - Preserving 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
18. 9. 2.1 - Examples
1. In this example, the PUT/FDL command does the following:
o Creates the FDL file cygnet.bckfdl on the remote host with
the RMS attributes of file STAT.BCK.
o Transfers the data in STAT.BCK and puts it in to
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 (130.180.4.8,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 (130.180.4.8,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:
o Transfers the FDL file cygnet.bckfdl from the remote host
to the local host.
o Uses this file to re-create the file STAT.BCK, with all of
its original RMS attributes, on the local host.
o Transfers the data in cygnet.bck and puts it in to 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 (130.180.4.8,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 (130.180.4.8,1029)
226 Transfer complete
local: STAT.BCK remote: cygnet.bck
8152 bytes sent in 00:00:00.12 seconds
FTP>
18. 9.3 - 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.
18. 9.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.
18.10 - Renaming and Deleting Files
To change the name of a remote file, 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 remove a remote file, use the DELETE command. The following
command deletes all versions of file YEAR.DAT on the connected
remote VMS host:
FTP> DELETE YEAR.DAT;*
18.11 - 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 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 located in the remote working directory:
FTP> VIEW/PAGE ENG.DIS
usrm::"khuna@jnet.com"
pobox::bearse
yield::timms
usrm::"lerry@muster.cudenver.edu"
sam
nm%us1rmc::"ldutton@TopCom.com"
.
.
.
18.12 - Appending Files
The FTP APPEND command allows you to concatenate 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)
18.13 - 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).
18.14 - 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 and you can use command
procedures to customize the FTP environment.
18. 14.1 - Initialization Command Files
Initialization command files can customize your FTP sessions
with SET, ENABLE, and DISABLE commands. These command files
are optional. They eliminate the need to enter individual FTP
commands, and run automatically when you invoke FTP.
Initialization command files:
o Contain only VMS commands
o Contain only one command per line
o Generally named SYS$LOGIN:FTPINIT.INI
18. 14.2 - Examples
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]
18. 14.3 - Setting Error Level
To change the error level, you enter the following command where
x is SUCCESS, WARNING, or ERROR:
FTP> SET ERROR_LEVEL x
o If ERROR LEVEL is SUCCESS, then WARNING, ERROR, and FATAL will
exit FTP.
o If ERROR LEVEL is WARNING, then ERROR and FATAL will exit FTP.
o If ERROR LEVEL is ERROR, then only FATAL will exit FTP.
FATAL errors will always cause FTP to exit.
18.15 - DECnet Operations
To copy files from and to a DECnet node, use the standard GET and
PUT commands
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.
18. 15.1 - Examples
1. 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
2. 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
| 19 - SMTP |
For exchanging electronic mail (e-mail) with users working on
internet hosts, the DIGITAL TCP/IP Services for OpenVMS 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.
To use the DIGITAL TCP/IP Services for OpenVMS mail services, you
need the following:
o Knowledge of the OpenVMS Mail utility
o User names and IP addresses of the people to whom you want to
send mail
19.1 - 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 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 mode 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.
19.2 - Multiple Recipients
To send mail to more than one user, use the SEND command, but at
the To: prompt, type a list of names or the name of an existing
distribution list.
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.
To send mail to multiple users by entering 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: OpenVMS distribution
lists and SMTP distribution lists.
19. 2.1 - OpenVMS list
Generate an OpenVMS distribution list as follows:
- 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, enter:
MAIL> SEND
To: @list_name
19. 2.2 - SMTP list
Generate an SMTP distribution list as follows:
- Create, or use an existing, .DIS file in
SYS$SPECIFIC:[TCPIP$SMTP] or, if defined on your system,
TCPIP$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, enter
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.
19. 2.3 - Examples
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:[TCPIP$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
free::monicaL
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
19.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 want
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-1998 Just Checking In
2 GWAY::SMTP%"mays@sfg 11-MAR-1998 Common Bases
3 CBIRD::SMTP%"seaway 12-MAR-1998 Cruises
MAIL> 3
19.4 - 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"
19.5 - 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 entering the correct address, follow the guidelines listed
in the Sending Mail section.
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
19.6 - 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"""
19.7 - 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.
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"
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.
19.8 - Managing Mail
The management commands that can help you work with SMTP mail
currently in a queue are listed in the following table. Type them
at the TCPIP> prompt.
Table 1 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
Displaying Mail Status
Use the 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
Deleting Queued Mail
The following examples show how to delete mail messages from
SMTP queues, using the TCPIP 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.
Releasing Queued Mail
The following example shows how to requeue an SMTP mail message
that is currently holding, using the TCPIP SEND MAIL command
(similar to the DCL ENTRY/RELEASE command). You are prompted to
confirm you want the mail message requeued.
$ TCPIP SEND MAIL /ENTRY=828
_PLUTO$DKD0:[MARLOW]970207015114580_MARLOW.TCPIP_PLUTO;1? y
| 20 - POP |
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 in
to the system.
The user name and password pair becomes authorization
information for the TCP/IP 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 in to 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.
| 21 - LPR_LPD |
The Line Printer/Line Printer Daemon (LPR/LPD) of the DIGITAL
TCP/IP Services for OpenVMS software supports the DCL PRINT, 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.
To use the DIGITAL TCP/IP Services for OpenVMS network printer
services, you need the following:
o The name of the remote print queue
o DEC Remote Print Server LPD protocol extensions software to
enter PRINT /PARAMETERS=options=value
o TCP/IP Services for OpenVMS must be installed and LPR/LPD
enabled on your OpenVMS system.
21.1 - Command Summary
To use the remote printing features, enter the commands
summarized below. For complete command descriptions, enter HELP
and the specific command at the DCL prompt.
DCL UNIX
Command Command Description
PRINT lpr Prints files
LPQ lpq Displays status of a remote print queue
LPRM lprm Removes jobs from a remote print queue
21.2 - Remote Print Queues
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 enter 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.
21. 2.1 - /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, enter:
$ SHOW QUEUE /FORM
To find out the currently mounted form or the default form,
enter:
$ 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.
21. 2.2 - /PARAMETERS
DIGITAL TCP/IP Services for OpenVMS 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 enter the PRINT /PARAMETERS=(option=value) command,
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, enter 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.
The following /PARAMETERS options are supported only for use with
remote printing.
HOST MAIL
NOFLAG PRINTER
o Use the HOST and PRINTER options together to send a print job
to any remote host and printer that does not have a specific
print queue defined on the local system.
In conjuction with the HOST and PRINTER qualifiers, you
must also specify the /QUEUE qualifier. The value of the
/QUEUE must be a local LPD print queue established for remote
printing. This may be a generic LPD queue set up to handle
all remote printing requests or a specific LPD queue for a
particular remote printer.
For example, the following command specifies that the file
PINS.LIS be sent to printer CT_LN05R on remote host BALT using
the generic remote printing queue DPR_ANSI.
$ 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 the host name or by
its fully qualified domain name (such as PACE.STATS.RINGS_
CORP.COM).
o 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
o The NOFLAG option suppresses printing of a banner (flag) page
at an LPD queue.
The following command example specifies the NOFLAG option.
$ PRINT/PARAMETERS=NOFLAG /QUEUE=DPR_ANSI PINS.LIS
21. 2.3 - 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.
$ PRINT /QUEUE=LPD_OUTQ -
_$ /PARAMETERS=(HOST=PACE.SATRN.COM,PRINTER=K1_PRINTER) -
_$ USER$4:[GRANT.FINAN.SALES]ANNUAL.TXT
21.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
21. 3.1 - 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
21.4 - 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
21. 4.1 - 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
21.5 - Remote UNIX Files
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.
21. 5.1 - 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
| 22 - Remote 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 enter commands, shell scripts, and command procedures to
these remote host systems without logging in to the hosts. These
R commands include
o RCP (Remote Copy)
o RLOGIN (Remote Login)
o RSH (Remote Shell)
o REXEC (Remote Execute, invoked by RSH).
You enter these commands at your system command line prompt.
To use the Remote (R) commands, you need access to an account on
the remote host, which is granted by either of the following:
o An entry in the remote host's authentication or proxy files
o Knowledge of a valid remote account and its password
22.1 - User Guidelines
To use a remote command on your OpenVMS system, remote hosts need
to know the user name that you want 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 want 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 within quotes.
The remote host must also know your password or know you
as a trusted user on your local system through a proxy or
authentication:
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
within quotation marks ( " " ).
- On systems that are not case sensitive, you do not need to
enclose your password within quotation marks ( " " ).
- You can specify the password on the command line:
$ RSH WOODS /PASSWORD="Downy" LS
Or, you can specify the password when the remote system
prompts:
$ RSH WOODS /PASSWORD DIR
REXEC password: (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 want 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 of the remote system to
determine if the system is case-sensitive and, if so, what
case is used in the authentication files.
NOTES
o To use the REXEC feature, you must always use the
/PASSWORD qualifier.
o The RLOGIN command does not recognize the /PASSWORD
qualifier. If you are a trusted user, you are
automatically logged in to the remote system.
o If you are not a trusted user, the remote host (REXEC)
prompts you to enter a user name and password on the
remote system.
22.2 - Command Syntax
o Quotation Marks
Use quotation marks (" ") for UNIX host path names that
include slashes (/), such as user/simms/offers, and for
user/host specifications that include the username@hostname
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.
o Qualifiers
You can specify R command qualifiers in either of two ways:
o Enter 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
$ !
22.3 - RCP
The RCP (Remote Copy) 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.
You can also use the COPY/RCP command to copy files across the
network using TCP/IP. For more information on this command, enter
HELP COPY/RCP at the DCL prompt.
Note that you can also use FTP to transfer files.
22. 3.1 - Examples
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]*"
22.4 - RLOGIN
The RLOGIN (Remote Login) 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 in to remote internet
hosts.
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.
22. 4.1 - Examples
The following examples show how to use the RLOGIN command.
1. The following command logs in to node CONDO:
$ RLOGIN CONDO <Return>
CONDO - Unauthorized access is prohibited
Username: KING <Return>
Password: (password not echoed) <Return>
Welcome to OpenVMS (TM) Alpha Operating System, Version V7.1 on node CONDO
Last interactive login on Thursday, 24-SEP-1998 15:20:29.60
Last non-interactive login on Wednesday, 23-SEP-1998 14:25:04.12
$ RUN ...
$ ~. (characters not echoed)
%RLOGIN-S-LCLCLOSED, Local connection closed
$
2. The following command logs in to host petrel and changes 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>
% +. (characters not echoed)
%RLOGIN-S-REMCLOSED, Remote connection closed
$
22.5 - RSH
The RSH (Remote Shell) 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 enter 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 enter your RSH command line so that
the remote command is the last word (or phrase).
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
removes it.
o If you enter two consecutive double quotation marks on the
command line, RSH removes 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 removes the quotation marks.
Interrupting Commands
To stop a remote execution, enter either Ctrl/C or Ctrl/Y.
22. 5.1 - Examples
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 entered 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 MOON01 <Return>
Password: (password not echoed)<Return>
Last successful login for jjones: Fri Sep 25 10:58:31 1998 from nebula
Last unsuccessful login for jjones: Fri Sep 25 11:59:43 1998 on ttyp5
Digital UNIX V5.0 (Rev. 148); Tue Apr 7 18:32:54 EST 1998
Digital Equipment Corporation
Internal Use Only
moon01>
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 enters 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 enters the DIRECTORY command from WR1 to execute at
WR2 in user account ROGERS.
$ RSH WR2 /USER=ROGERS DIRECTORY
22.6 - REXEC
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, enter
RSH /PASSWORD.
22. 6.1 - Examples
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 enters 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
| 23 - TELNET |
With the TELNET software in DIGITAL TCP/IP Services for OpenVMS,
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.
You can establish a TELNET session with a host that uses IBM 3270
model terminals (TN3270).
Note that you can also use RLOGIN to log in to remote internet
hosts. However, RLOGIN does not have the ability to manage a 3270
session.
To use the network terminal services, you need the following:
o A user account on the remote host also running TELNET.
o A user account on the OpenVMS system that runs DIGITAL TCP/IP
Services for OpenVMS.
For more information about specific TELNET commands, enter the
following
$ TELNET
TELNET> HELP
23.1 - Command Summary
To use TELNET, issue the commands summarized below. For complete
descriptions (including UNIX equivalents) of each command, enter
the following:
$ TELNET
TELNET> HELP
Command Description
Starting (at the DCL Prompt)
TELNET Invokes TELNET
TELNET remote_host Invokes TELNET and establishes a connection
to a remote host
TN3270 Invokes TELNET and TN3270
TN3270 remote_host Invokes TELNET, runs TN3270, and
establishes a connection to a remote host
Getting In and Out of Sessions
CONNECT Establishes a connection between the local
host and a remote host
CREATE_SESSION Establishes a pseudodevice and connects it
to a remote listener port
DELETE_SESSION Deletes a pseudodevice created by the
CREATE_SESSION command
DISCONNECT Terminates your current session
Ctrl/] Takes you from the remote host back to the
TELNET prompt
EXIT Closes open connections and exits from
TELNET
HELP Invokes online help
RESUME Resumes an open connection
SPAWN Suspends your TELNET session and takes you
to the DCL prompt
Customizing the TELNET Environment
DISABLE AUTOFLUSH Disables the automatic flushing of output
when interrupt characters are sent
DISABLE AUTOSYNCH Disables the automatic sending of interrupt
characters in urgent mode
DISABLE BINARY Disables transmission in binary mode
DISABLE CRLF Disables the sending of carriage returns as
Return LF
DISABLE CRMOD Disables the mapping of received carriage
returns
DISABLE DEBUG Disables the display of data flow
information in hexadecimal
DISABLE Disables the interpretation of certain
LOCAL_CHARS control characters by your local TELNET
client and passes them to the remote TELNET
server
DISABLE Disables the display of option negotiations
OPTIONS_VIEW between the client and server
ENABLE AUTOFLUSH Enables the automatic flushing of output
when interrupt characters are sent
ENABLE AUTOSYNCH Enables the automatic sending of interrupt
characters in urgent mode
ENABLE BINARY Enables transmission in binary mode
ENABLE CRLF Enables the sending of carriage returns as
Return LF
ENABLE CRMOD Enables the mapping of received carriage
returns
ENABLE DEBUG Enables the display of data flow
information in hexadecimal
ENABLE LOCAL_CHARS Enables the interpretation of certain
control characters by your local TELNET
client and prohibits them from being passed
to the remote TELNET server
ENABLE OPTIONS_VIEW Enables the display of option negotiations
between the client and server
SHOW PARAMETERS Displays the current parameter settings
SHOW SESSION Displays the current sessions
SHOW STATUS Displays the current status
SET ECHO Sets the echo character to the specified
character
SET ERASE Sets the erase character to the specified
character
SET ESCAPE Sets the escape character to the specified
character
SET FLUSHOUTPUT Sets the flush output character to the
specified character
SET INTERRUPT Sets the interrupt character to the
specified character
SET KILL Sets the kill character to the specified
character
SET MODE Sets the transmission mode to character or
line
SET QUIT Sets the quit character (an alternate
interrupt character) to the specified
character
SET TERMINAL Sets the terminal type to the specified
model
Sending Commands to the Remote Host
SEND AO Sends the Abort Output command
SEND AYT Sends the Are You There command, testing
the path to the remote application and
eliciting connection status information
from the remote host
SEND BRK Sends the Break command
SEND EC Sends the Erase Character command
SEND EL Sends the Erase Line command
SEND GA Sends the Go Ahead command
SEND IP Sends the Interrupt character
SEND NOP Sends the No Operation command to test
whether data can be sent to the remote
host, eliciting an error if the connection
is not open
SEND SYNCH Sends the Synchronize character
23.2 - Command Syntax
Use the following rules when you enter 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
23. 2.1 - Example
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
login: root
Password:...
.
.
.
migain# printenv
TERM=vt300
HOME=/
SHELL=/bin/csh
USER=root
PATH=/bin:/usr/bin:/usr/ucb:/etc:/usr/etc:.
LOGNAME=root
PWD=/
migain#
23.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.
23. 3.1 - Example
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.
$ TELNET
TELNET> SHOW STATUS
%TELNET-E-NOSESSION, No active session
Escape character: '^]'
TELNET>SET DEVICE TERMINAL=VT300
TELNET> OPEN GALAXY
%TELNET-I-TRYING, Trying ... 1.20.208.10
%TELNET-I-SESSION, Session 01, host galaxy, port 23
-TELNET-I-ESCAPE, Escape character is ^]
Digital UNIX (galaxy.udb.com) (ttyp5)
login:
23.4 - 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.
23. 4.1 - Example
The following example shows two ways to close connections:
% logout
%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host galaxy, port 23
TELNET>
TELNET> EXIT
$
% <Ctrl/]> (characters not echoed)
TELNET> DISCONNECT
galaxy.udp.com>
TELNET> DISCONNECT
%TELNET-S-LCLCLOSED, Local connection closed
-TELNET-I-SESSION, Session 01, host galaxy, port 23
TELNET>
23.5 - 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
23.6 - Command Procedures
You can create a command procedure containing the DCL DEFINE and
TELNET (or TN3270) commands.
You can create initialization command files to 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.
o You can specify the logical name, TELNETINIT, to point to an
initialization file.
23. 6.1 - Example
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"
23.7 - Toggling
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), enter 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, enter one of the
following at the TELNET (or TN3270) prompt.
TELNET> <Return>
or
TELNET> RESUME
or
TELNET> RESUME n
where n is the number of the session to which you want to
return.
o To change the default escape sequence, enter the following at
the TELNET (or TN3270) prompt:
TELNET> SET ESCAPE "^escape_character"
23. 7.1 - Examples
1. The following example toggles between remote UNIX host biway
and the local OpenVMS system.
biway> <Ctrl/]> (characters not echoed)
TELNET> SHOW STATUS
Session 1 Active Host biway Port 23
Operating Mode: Character-at-a-time
Escape character: '^]'
Options:
Echo - Remote
Terminal Type - Local
Terminal Type - VT300
Suppress Go Ahead - Local
Suppress Go Ahead - Remote
Terminal Dataoveruns: 0
Suspended Network I/Os: 0
.
.
. )
TELNET> <Return>
biway>
2. 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 incorrectly enters 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 incorrectly typing
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/]> (characters not echoed)
TELNET> SHOW STATUS
Session 1 Active Host FERN
.
.
.
TELNET> CONNECT GANNET
.
.
.
gannet> <Ctrl/]> (characters not echoed)
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/]> (characters not echoed)
TELNET> SHOW STATUS
Session 2 Active Host GANNET
Operating Mode: Character-at-a-time
Escape character: '^]'
.
.
.
Session 1 Waiting Host FERN
TELNET>
23.8 - Suspending
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.
23. 8.1 - Example
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:*
23.9 - 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.
o Toggling Sessions
To toggle from one open TELNET connection to another:
1. Enter 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.
o 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
23.10 - Customizing
To customize the TELNET/TN3270 processing environment, issue
ENABLE, DISABLE, and SET commands. You can modify how TELNET and
TN3270:
o Send and receive 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 in to 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.
23.11 - TN3270
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 (TN3270 Troubleshooting).
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.
TELNET can emulate the following IBM 3270 model terminals:
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
23. 11.1 - Terminal Setup
When you use TELNET and specify IBM 3270 model terminal emulation
(TN3270), the image displayed on your screen depends on the type
of DIGITAL terminal you use (or that your PC is emulating) and
the features you set on it.
o VT200 Series Terminals
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
o VT100 Series
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.
23. 11.2 - 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.
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:TN3270DEF.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.
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
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, TN3270PRINT.LIS. TELNET
does the following:
o Each time you start a TELNET session that runs TN3270, TELNET
opens a new TN3270PRINT.LIS file.
o Each time you use PRINT during a session, TELNET appends new
output from the screen to the end of TN3270PRINT.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, enter 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.
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 right hand 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
23.12 - TN3270 Keyboard Functions
The options listed below under "Additional Information Available"
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.
23. 12.1 - 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 want 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.
23. 12.2 - 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.
23. 12.3 - 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.
23. 12.4 - 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 ( - ).
23. 12.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.
23. 12.6 - 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 want to
assign to that key.
23. 12.7 - 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.
23. 12.8 - 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.
23. 12.9 - 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 (*).
23. 12.10 - 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.
23. 12.11 - 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.
23. 12.12 - 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.
23. 12.13 - 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.
23. 12.14 - 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.
23. 12.15 - 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.
23. 12.16 - 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 ( ; ).
23. 12.17 - HELP
VT100: EXT + H VT200: Help
DEFINE_KEY Function: HELP
Displays online help and an illustration of the TN3270 keyboard.
23. 12.18 - 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).
23. 12.19 - 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
23. 12.20 - INSERT
VT100: EXT + PF4 VT200: F14
DEFINE_KEY Function: INSERT_MODE
Enables insert mode. Use insert mode to edit what you entered. If
the status display is enabled, Insert appears.
In insert mode, when you enter a character in to 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 in to 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 in to 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
23. 12.21 - 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.
23. 12.22 - 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.
23. 12.23 - 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.
23. 12.24 - NUM_OVR
VT100: EXT + J VT200: Remove
DEFINE_KEY Function: NUMOVR
Lets you enter nonnumeric characters in to 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.
23. 12.25 - 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.
23. 12.26 - 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
23. 12.27 - 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 enter
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.
23. 12.28 - 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.
23. 12.29 - 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.
23. 12.30 - 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.
23. 12.31 - 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 in to a protected or a full
field, or when you try to enter the wrong type of data in to a
field.
Invoking RESET turns off the Inhib indicator. The cursor remains
where it is and the screen remains unchanged.
23. 12.32 - 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.
23. 12.33 - 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.
23. 12.34 - 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.
23. 12.35 - 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.
23. 12.36 - 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.
23. 12.37 - 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.
23. 12.38 - 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.
23. 12.39 - 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.
23.13 - Redefining TN3270 Keyboard
You can reassign functions and 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
You can also reassign the following functions:
o All emulated functions
o Most IBM 3270 model functions
o All emulated alphanumeric and graphic characters
23. 13.1 - Definable Keys
The keys you can define are:
Location Key Name
Function keys PF1-PF4
(VT100 and VT200)
Application keypad KP0-KP9
(VT100 and VT200) ENTER
MINUS
COMMA
PERIOD
Top-row function keys F6-F20
(VT200) HELP (F15)
DO (F16)
Editing keypad (E1-E6) FIND (E1)
(VT200) INSERT_HERE (E2)
REMOVE (E3)
SELECT (E4)
PREV_SCREEN (E5)
NEXT_SCREEN (E6)
Cursor keys UP
(VT100 and VT200) DOWN
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
23. 13.2 - 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
23. 13.3 - 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.
23. 13.4 - 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. What you enter
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.
23.14 - TN3270 Troubleshooting
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 TCPIP$RECSEQ.DAT in your SYS$LOGIN directory.
o Delete TCPIP$RECSEQ.DAT.
If the system manager must delete this file, rerecord all the
key sequences you had stored on the PF keys.
23.15 - Debugging with TN3270
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
|
|
