Software development, photography, jokes, ....

Sites by me

 
tas-logoTransportation Administration System
snoezelkussen-logo-kleinstSnoezelkussens voor verstandelijk gehandicapten
ikzoekeenbegeleider-logoBegeleiders voor gehandicapten
Laat uw hond het jaarlijkse vuurwerk overwinnen
logo 50x50Hey Vos! Je eigen naam@vos.net emailadres?
Kunst in huis? Nicole Karrèr maakt echt bijzonder mooie dingen
nettylogo2Kunst in huis? Netty Franssen maakt ook bijzonder mooie dingen
Salarisadministratie en belastingadvies bij De Zaak Loont
Zutphense Bomenstichting

Hosting Favorites

 
ANU Internet Services
XelMedia .internet Services
register.com

Blogroll

 
Bomenstichting
LassoSoft
MacFreak
Quality that computes
The Economy of Motion
Wheel 2.0
IntrAktv



Website Hosting bij Xel Media

Marc's Place

1 TCP_IP_Services (1)

The DIGITAL TCP/IP Services for OpenVMS product, often referred to as "UCX," provides user and network services using the TCP/IP protocol. For help on the management commands, type: $ UCX HELP 2 Product_Overview The Transmission Control Protocol/Internet Protocol (TCP/IP) suite is a set of communication protocols that work together to provide computer networking. DIGITAL TCP/IP Services for OpenVMS (UCX) is Digital's implementation of TCP/IP protocols and services for the OpenVMS operating system. DIGITAL TCP/IP Services for OpenVMS consists of the following components: Kernel (see Kernel) Network services (see Network Services) Network File System (NFS) (see NFS) End-user services (see User Services) 3 RFC_Compliance The body of information called Request For Comments (RFC) is a series of documents, begun in 1969, that describes Internet protocols and related experiments. All Internet standards are written as RFCs. RFC 1208 defines the Internet. The Internet is the public network consisting of many large networks that use the TCP/IP protocol suite. It provides universal connectivity, reaching the Defense Advanced Projects Research Agency (DARPA) Internet, MILNET, NSFnet, CREN, and many worldwide universities, government research labs, military installations, and business enterprises. In contrast, internet means any interconnected networks using the TCP/IP protocols, functioning as one, virtual network. The following RFCs are significant to the various components of DIGITAL TCP/IP Services for OpenVMS: Table 3-1 RFCs Used by UCX Protocol Number Title ARP RFC 826 Ethernet Address Resolution Protocol: Or Converting Network Protocol Addresses to 48.bit Ethernet Address for Transmission on Ethernet Hardware BOOTP RFC 951 Bootstrap Protocol RFC 1048 BOOTP Vendor Information Extensions RFC 1084 BOOTP Vendor Information Extensions CSLIP RFC 1144 Compressing TCP/IP Headers for Low-Speed Serial Links DNS, RFC 819 Domain Naming Convention for Internet User BIND Applications RFC 920 Domain Requirements RFC 974 Mail Routing and the Domain System RFC 1032 Domain Administrator's Guide RFC 1033 Domain Administrator's Operations Guide RFC 1034 Domain Names - Concepts and Facilities RFC 1035 Domain Names - Implementation and Specification RFC 1101 DNS Encoding of Network Names and Other Types RFC 1183 New DNS RR Definitions RFC 1400 Transition and Modernization of the Internet Registration Service RFC 1535 A Security Problem and Proposed Correction with Widely Deployed DNS Software RFC 1536 Common DNS Implementation Errors and Suggested Fixes RFC 1537 Common DNS Data File Configuration Errors RFC 1591 Domain Name System Structure and Delegation RFC 1597 Address Allocation for Private Internets RFC 1637 DNS NSAP Resource Records FTP RFC 959 File Transfer Protocol ICMP RFC 792 Internet Control Message Protocol IP RFC 791 Internet Protocol NTP RFC 1059 Network Time Protocol (Version 1) Specification and Implementation RFC 1119 Network Time Protocol (Version 2) Specification and Implementation RFC 1305 Network Time Protocol (Version 3) Specification and Implementation NFS RFC 1094 NFS: Network File System Protocol Specification POP RFC 822 Standard for the Format of ARPA Internet Text Messages RFC 1082 Post Office Protocol Version 3: Extended Service Offerings RFC 1321 The MD5 Message-Digest Algorithm RFC 1725 Post Office Protocol (Version 3) PPP RFC 1331 The Point-to-Point Protocol (PPP) for the Transmission of Multi-Protocol Datagrams over Point-to-Point Links RARP RFC 903 Reverse Address Resolution Protocol RIP RFC 1058 Routing Information Protocol RLP RFC 887 Resource Location Protocol Routing RFC 1112 Host Extensions for IP Multicasting RPC RFC 1057 RPC: Remote Procedure Call Protocol Specification Version 2 SLIP RFC 1055 Nonstandard for Transmission of IP Datagrams Over Serial Lines: SLIP SMTP RFC 821 Simple Mail Transfer Protocol RFC 822 Standard for the Format of ARPA Internet Text Messages SNMP RFC 1155 Structure and Identification of Management Information for TCP/IP-Based Internets RFC 1156 Management Information Base for Network Management of TCP/IP-Based Internets RFC 1157 A Simple Network Management Protocol RFC 1158 Management Information Base for Network Management of TCP/IP-based Internets: MIB-II RFC 1212 Concise MIB Definitions RFC 1213 Management Information Base for Network Management of TCP/IP-based Internets: MIB-II RFC 1214 OSI Internet Management: Management Information Base RFC 1215 Convention for Defining Traps for Use with the SNMP RFC 1442 Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2) RFC 1514 Host Resource MIB RFC 1592 Simple Network Management Protocol Distributed Protocol Interface Sun RFC 1790 An Agreement between the Internet Society and ONC Sun Microsystems, Inc. in the Matter of ONC RPC, RPC and XDR Protocols XDR TELNET RFC 854 Telnet Protocol Specification RFC 855 Telnet Option Specification RFC 856 Telnet Binary Transmission RFC 857 Telnet Echo Option RFC 858 Telnet Suppress Go Ahead Option RFC 859 Telnet Status Option RFC 860 Telnet Timing Mark Option RFC 861 Telnet Extended Options: List Option TFTP RFC 1350 The TFTP Protocol TP RFC 868 Time Protocol TCP RFC 793 Transmission Control Protocol UDP RFC 768 User Datagram Protocol XDR RFC 1014 XDR: External Data Representation Standard 3 Kernel The UCX kernel consists of the following software: Network device drivers Serial Line IP (SLIP), Compressed SLIP (CSLIP), and Point-to- Point Protocol (PPP) Address Resolution Protocol (ARP) Routing and transport Auxiliary Server (INETd) BIND Resolver (BIND Client) Application programming interfaces (APIs) Management tools Other utilities 4 Network_Device_Drivers Software drivers connect the communication hardware to the communication software. Drivers are also called device drivers, communication drivers, and network drivers. UCX includes the following network drivers: o Internet Device Driver (BG Driver) - Software interface between the OpenVMS operating system and your host's network controller device, such as an Ethernet controller or an FDDI controller o INET Driver - Network interface for customer-developed applications that use the CMU / TEK $QIO interface o DNFS Driver - Network interface for the NFS Client o PWIP Driver - Network interface for PATHWORKS[TM] and DECnet-Plus for OpenVMS o TN Driver - Network interface for the TELNET Server DIGITAL TCP/IP Services for OpenVMS bundles the PATHWORKS[TM] Internet Protocol (PWIP) Driver and the PATHWORKS network ancillary control process (ACP). This software provides TCP/IP options to PATHWORKS clients. 4 SLIP,_CSLIP,_and_PPP DIGITAL TCP/IP Services for OpenVMS implements the Serial Line IP (SLIP), Compressed SLIP (CSLIP), and Point-to-Point Protocol (PPP) protocols. SLIP and PPP are used to create point-to-point serial connections. Use SLIP to connect across a serial line, rather than an Ethernet, FDDI, or Token Ring LAN. Each end of the link requires SLIP software. You can use any standard OpenVMS terminal device as a SLIP line. Use the PPP datalink available with OpenVMS Alpha to connect point-to-point across a serial line. Making connections with PPP is similar to connecting with SLIP. With PPP, the network interface is the modem connection. You can use any standard OpenVMS terminal device as a PPP line. If the remote system is configured as a gateway to a network, you can also reach other systems on the network. CSLIP provides header compression, especially beneficial for small packets. Header compression improves packet throughput. DIGITAL TCP/IP Services for OpenVMS supports the following SLIP configurations: o Dedicated (hard-wired) o Dialups in which the DIGITAL TCP/IP Services for OpenVMS host originates the connection o Dialups in which the DIGITAL TCP/IP Services for OpenVMS host answers calls and establishes remotely initiated connections SLIP is a packet-framing protocol that defines a sequence of characters that frame IP packets on a serial line. SLIP has the following characteristics: o Provides reliable use of serial lines for connecting TCP/IP hosts and routers. o Allows mixes of hosts and routers to communicate. Host-to- host, host-to-router, and router-to-router are common SLIP network configurations. o Allows you to run only one protocol (TCP/IP) over a SLIP connection. o Provides no addressing, packet type identification, error detection, error correction, or compression mechanisms. DIGITAL TCP/IP Services for OpenVMS supports the following PPP connections: o Dedicated, low-speed connections between local hosts, such as between a laptop computer and an Alpha workstation connected by a serial line. o Dialups in which the DIGITAL TCP/IP Services for OpenVMS host originates the connection o Dialups in which a remote host to the host system 4 ARP The Address Resolution Protocol (ARP) implementation dynamically maps an IP address to the physical hardware address of a broadcast medium. The broadcast medium can be, for example, an Ethernet controller, an FDDI controller, a Token Ring controller, or a terminal server. ARP is limited to one physical network, and that network must support hardware broadcast. 4 Routing_and_Transport DIGITAL TCP/IP Services for OpenVMS implements the following routing and transport protocols: Internet Protocol (IP) Routing Information Protocol (RIP) Internet Control Message Protocol (ICMP) Transmission Control Protocol (TCP) User Datagram Protocol (UDP) 5 IP The Internet Protocol (IP) software is a connectionless packet delivery service. An IP datagram is a packet that has no delivery receipt and is connectionless in that it does not maintain state information about successive datagrams. The IP implementation sends or routes data across the network from its source to its destination by means of internetwork addressing (IP address). The IP address identifies the connection between the network controller of a node and the network cable. It receives data bits from the physical and data link layers, assembles the bits into an IP datagram, and chooses the best route to send the packet to its destination. The IP software also performs packet fragmentation and re-assembly in the routing process. 5 RIP The Routing Information Protocol (RIP) implementation enables hosts to exchange current routing information about hosts and directly connected networks. With RIP, hosts perform dynamic routing. The hosts can select to receive or both send and receive RIP messages. 5 ICMP The Internet Control Message Protocol (ICMP) implementation provides a number of diagnostic functions and handles error and control messages. ICMP reports problems with data delivery to gateways and hosts. 5 TCP The Transmission Control Protocol (TCP) implementation provides connection-oriented, reliable, sequenced data transfers between hosts. Before the sender transmits data, both participants must establish a connection. TCP guarantees that data reach its destination, retransmitting data that does not get through. 5 UDP The User Datagram Protocol (UDP) implementation provides connectionless data transfers between hosts. UDP communications are faster than TCP for applications that do not require delivery receipts. 4 Auxiliary_Server DIGITAL TCP/IP Services for OpenVMS implements INETd in the Auxiliary Server. The Auxiliary Server does the following: o Eliminates high overhead resulting from non-stop running of all the services. o Provides system security through the authentication of clients when they request service. o Supports event and error logging. 4 BIND_Resolver The Berkeley Internet Name Domain (BIND) Service provides translation of host names into IP addresses and IP addresses into host names. The BIND Resolver is the client software that requests host names, addresses, and other network information from BIND Servers. 4 APIs DIGITAL TCP/IP Services for OpenVMS includes the following application programming interfaces (APIs) for customized applications development: $QIO SRI $QIO Standard C sockets interface and C sockets library Sun Open Network Computing (ONC) RPC 5 $QIO This API extends OpenVMS System Services for socket communications. Sockets provide access to IP, TCP, and UDP. $QIO supports all programming languages. You can write programs that implement IP multicasting. 5 SRI_$QIO This API is an SRI $QIO emulator that translates older, non-UCX $QIO interfaces (first developed at Stanford Research Institute (SRI) in 1980 through 1981) into $QIO programming interfaces. You can write programs that implement IP multicasting. 5 Sockets The standard C sockets API and C sockets library provide UNIX- like access to TCP, UDP, and raw IP. The C sockets interface supports the C programming language, which aids portability of applications between OpenVMS and UNIX systems. This API is integrated with both the DEC C run-time library and VAX C run-time library. You can write programs that implement IP multicasting. 5 RPC DIGITAL TCP/IP Services for OpenVMS implements the Sun Open Network Computing (ONC) Version 4.2 Remote Procedure Calls (RPCs) Protocol. The set of ONC RPCs is a portable API and provides an efficient alternative to developing applications with sockets. You can program with this API using all data types, regardless of their byte order, floating-point presentation, string representation, or alignment. This RPC is backward-compatible with older RPC sources provided by DIGITAL TCP/IP Services for OpenVMS. DIGITAL TCP/IP Services for OpenVMS links this API with DECC$SHR (not with VAXCRTL). Note that: - OpenVMS VAX systems support both DEC C and VAX C. - OpenVMS Alpha systems support only DEC C. 4 Management_Tools DIGITAL TCP/IP Services for OpenVMS (UCX) includes the following network management tools: o Management control program with a command-line interface, event logging, and error and information messages o Configuration procedure (see the DIGITAL TCP/IP Services for OpenVMS Installation and Configuration manual) o Trace utility o Clean-up utility (see the DIGITAL TCP/IP Services for OpenVMS Installation and Configuration manual) o Logical names o Startup and shutdown procedures o NSLOOKUP utility o SNMP and the Extensible SNMP (eSNMP) o Remote Magnetic Tape (RMT) and Remote CD-ROM (RCD) services 3 Network_Services DIGITAL TCP/IP Services for OpenVMS offers the following network services: o DNS (BIND Server) software for host-name-to-address translation o Bootstrap Protocol (BOOTP) Server software for remote booting of requesting hosts o Trivial File Transport Protocol (TFTP) server software for remote booting of requesting hosts o Network Time Protocol (NTP) software for time synchronization and authentication o Portmapper for mapping requesting applications to port numbers o Simple Network Management Protocol (SNMP) Agent for remote network management o Printing services o Remote Line Printer (LPR) and Line Printer Daemon (LPD) o PC-NFS Print Server o TELNET Print Symbiont (TELNETSYM) 4 BIND_Server The Berkeley Internet Name Domain (BIND) Service (DNS) is an internet name service that does host-name-to-address lookups and reverse (address-to-host-name) lookups. The client is called the Resolver, and the server is known as a BIND Server, a name server, and DNS (Domain Name Service). Name servers maintain databases of host names, addresses, mail records, text records, and other network objects. Name servers supply this information for client systems, who query the servers with their BIND Resolver. 4 BOOTP The Bootstrap Protocol (BOOTP) software is also known as remote boot. With BOOTP, a diskless host can identify its IP address, the address of a file server on which it can store and retrieve data, and the address of the nearest IP gateway. If BOOTP cannot identify a requesting client, BOOTP ignores the request. 4 TFTP The Trivial File Transfer Protocol (TFTP) Server software is a cost-effective, unsophisticated file transfer service. It is appropriate for applications that do not need complex interactions between a client and server. TFTP is small and can be encoded into read-only memory. With TFTP, BOOTP can use the same underlying protocols that the operating system uses once it begins execution. This design allows one host to bootstrap from a server on another physical network. With BOOTP and TFTP, DIGITAL TCP/IP Services for OpenVMS can download system images and other types of information to requesting client hosts. 4 NTP The Network Time Protocol (NTP) implementation synchronizes timekeeping and provides accurate time stamps. Hosts running NTP can participate in a TCP/IP network with fully synchronized time. 4 Portmapper Each server process listens for connections on a designated port. A client requesting a particular application can ask for it by specifying the number of this designated port. You can configure the following applications to register themselves with the Portmapper Service: o Programs that use Sun RPCs o NFS and PC-NFS (Portmapper required) o MOUNT (Portmapper required) 4 Printing_Services DIGITAL TCP/IP Services for OpenVMS offers these network print services: o LPR and LPD o PC-NFS Print Server o TELNET Print Symbiont (TELNETSYM) 5 LPD_and_LPR DIGITAL TCP/IP Services for OpenVMS provides network printing with its Remote Line Printer (LPR) (outbound requests) and Line Printer Daemon (LPD) (inbound requests) implementations. This software supports: o DCL PRINT command to printers on remote hosts (outbound printing) - including utility queues that let you specify a particular remote host and printer o DCL LPQ command for the status of print jobs on remote hosts o DCL LPRM command to remove print jobs from remote queues o Retry capability for outbound jobs o UNIX lpr commands issued from a remote UNIX host to print on printers at your OpenVMS host o UNIX lpq commands issued from a remote UNIX host to display the status of the remote print queue located on your OpenVMS host o UNIX lprm commands issued from a remote UNIX host to remove jobs from a remote print queue on your OpenVMS host o Identification of PostScript[TM] files o Print setup utility UCX$LPRSETUP A print queue is either: o Local, handling inbound jobs o Remote, handling outbound jobs for remote printers 5 PC-NFS_Server The PC-NFS Print Server includes the following features: o Associating an MS-DOS printer device name with an OpenVMS print queue on the host where the PC-NFS Server is running o Printing a file to the associated queue The features of getting status and deleting job requests have the following limitations from a PC: o Users cannot list jobs queued on the PC-NFS Server. o Users cannot cancel jobs queued on the PC-NFS Server. o Users cannot get a list of available print queues from the PC-NFS Server. o Users cannot get the status of a particular print queue on the PC-NFS Server. 5 TELNET_Symbiont The TELNET Print Symbiont (TELNETSYM) provides remote printing using the TELNET Protocol. This service is achieved by attaching a printer to a terminal server. TELNETSYM is particularly useful in configurations with printers attached to terminal servers that support the TELNET Protocol. TELNETSYM does not work with terminal servers that use only the LAT Protocol. TELNETSYM is a true OpenVMS print symbiont that performs all print formatting. (This implementation differs from the LPD Protocol, where the receiver of the print job does the print formatting.) The local OpenVMS system drives the remote printer as if it were directly connected. 4 SNMP The Simple Network Management Protocol (SNMP) monitors networks and remote hosts. DIGITAL TCP/IP Services for OpenVMS implements the Agent portion of SNMP. SNMP uses the network management data standard known as the Management Information Base (MIB). The MIB specifies the data items that a gateway or network must keep and the allowed operations. For example, DIGITAL TCP/IP Services for OpenVMS specifies that SNMP can read, but not modify, the number of octets that are received. Remote system managers can only query MIB data. All SNMP operations relate to fetching and storing MIB data. 4 SNMP_Extensible_Agent_(eSNMP) DIGITAL TCP/IP Services for OpenVMS provides support for network management with the Extensible SNMP (eSNMP) software. Extensibility means that a single agent can support any number of subagents. The eSNMP software consists of an agent and subagents that run on all network elements. A management station is the entity on the TCP/IP network that runs the agent software and maintains the managed information. Network elements are entities such as hosts, routers, X terminals, and terminal servers. DIGITAL's implementation of the eSNMP software has an agent, two subagents, and an application programming interface (API) that enable developers to create subagents that manage other entities in their networks. The two provided subagents support the Internet Standard Management Information Base (MIB-II) as defined by RFC 1213 and a portion of the Host Resource MIB as defined by RFC 1514. For complete information about eSNMP functionality, see the DIGITAL TCP/IP Services for OpenVMS eSNMP Programming and Reference manual. 3 NFS The Network File System (NFS) protocols, developed by Sun Microsystems, Inc., enable internet clients to access remote files residing on NFS servers. NFS provides "transparent" user access and is an efficient alternative to moving files physically across the network. The NFS component includes the following software: o File system o NFS Server o NFS Client o PC-NFS Server 4 Server With the NFS Server running on an OpenVMS system, a remote user can access files that physically reside locally. The user can work from any host, irrespective of operating system, that runs NFS Client. OpenVMS supports index, relative, and sequential files that have various record formats. The DIGITAL TCP/IP Services for OpenVMS implementation of NFS supports the following record formats: o Fixed length o Variable length o Variable with fixed-length control (VFC) o Stream (including STREAM_LF and STREAM_CR) o Undefined 4 File_System The NFS file system is a logical file system. It is a collection of UNIX-style file systems and OpenVMS file systems that are organized as a single-level hierarchy. It has these OpenVMS file system components: o Top-level (sometimes called root) directory (Master File Directory [MFD]) o Lower-level directories o All the files in those directories o Some internal system files The container file system (CFS) run-time library is an OpenVMS run-time library that is used by both the NFS Server process and DIGITAL TCP/IP Services for OpenVMS to process files within the container file system. 4 Client The NFS Client running on OpenVMS makes file-operation requests by contacting a remote NFS Server. The server then performs the requested operation. The server host can be any operating system that runs NFS Server. The NFS Client supports STREAM_LF formatted files. 4 PC-NFS The DIGITAL TCP/IP Services for OpenVMS implementation of PC-NFS provides the following print services to personal computers (PCs) running NFS Client software. o Authentication NFS security is maintained by identifying every user with a user identification / group identification (UID/GID) pair. PCs lack this information. A PC that wants to request access to an NFS Server must first get its UID/GID from a remote Authentication Server. As an Authentication Server, DIGITAL TCP/IP Services for OpenVMS stores this information in its Proxy Database and sends it to requesting PC users. o Printing 3 User_Services DIGITAL TCP/IP Services for OpenVMS includes the following client and server end-user services: o Finger utility (FINGER command) o File Transfer Protocol (FTP) o Simple Mail Transfer Protocol (SMTP) and Post Office Protocol (POP) services o Network printing commands: DCL PRINT, LPQ, LPRM o Remote commands: RCP, RLOGIN, RSH, and REXEC o TELNET and IBM 3270 model terminal emulation (TN3270) 4 Finger The Finger utility lets users display information about users on remote or the local host. In specific, a user can use the FINGER command to: o Display brief information about all users on a host o Display detailed information about one or more specific users on a host o Display information about all users logged in to the local cluster o Make planning and project information about yourself available to other Finger users The user information displayed by the FINGER command may include the following, depending on the server: o User name o Account name o Program the user is running o User's home directory o User's plans, activities, and other information o User's project 4 FTP The File Transfer Protocol (FTP) software lets users: o Transfer remote files bidirectionally from one system to another o Set and display the default (working) directory on the local or remote host o Display the contents of files on the local or remote host o List remote directories o Delete remote files o Rename remote files o Perform file transfers using wildcard characters o Print local files at a remote printer, or remote files at a local printer FTP also provides authentication control. Clients must correctly enter a login name and password to the server before they can request file transfers. The FTP Client includes the DCL FTP command and FTP commands within the FTP utility. These FTP commands offer two command-line interfaces: UNIX style and OpenVMS style. 5 Anonymous_User_Access With FTP, users who do not have a login name or password can access designated remote files on a system using an anonymous name. Anonymous FTP can be configured as follows: o Users cannot browse through the remote file system. They have access only to the anonymous guest, or "home," directory and a public directory. The public directory can contain general bulletin information to which the user has read-only access. o Users are limited to GET (read) and PUT (copy), with additional limitations to the files that they can copy, in the guest directory. o Users can GET files only from the public directory. o Users can delete only the files in the guest directory owned by the anonymous account. 4 Remote_(R)_Commands DIGITAL TCP/IP Services for OpenVMS includes client and server implementations of these Berkeley Remote (R) commands: RCP, RLOGIN, RSH, and REXEC. These services let users gain access to remote internet hosts. 5 RCP The RCP command copies files between internet hosts. Users can copy files: o From remote hosts o To remote hosts o From one remote host to another As an RCP Server, DIGITAL TCP/IP Services for OpenVMS responds to any operating system running RCP Client. As a client, DIGITAL TCP/IP Services for OpenVMS includes the DCL RCP command, which offers the following options: o Copy and maintain the same file name. o Copy and change the file name. o Preserve the source file's protections. o Preserve the source file's modification date. o Log the FTP session. o Copy all the files under a specified directory and preserve the directory hierarchy. If subdirectories exist beneath the source directory, they are also copied into created subdirectories on the other host. Depending on how the network manager sets up security, a user can issue RCP in one of the following ways: o Without specifying a user name o Without specifying a user name or a password o Specifying both user name and password 5 RLOGIN The RLOGIN command allows server users to log in to a remote host and work as if they were directly connected. You can configure RLOGIN to pass security information to the client. This feature is called RLOGIN proxy. If you do not configure RLOGIN to pass security information to the client, the remote host prompts the user for login information. As an RLOGIN Server, DIGITAL TCP/IP Services for OpenVMS responds to any operating system running RLOGIN Client. As a client, DIGITAL TCP/IP Services for OpenVMS includes the DCL RLOGIN command. 5 RSH RSH connects a user's terminal to a remote host so that the user can send a command, shell script, or command procedure for execution at that system without logging in. Using the /PASSWORD qualifier invokes REXEC. 5 REXEC REXEC authenticates and executes the commands that users issue for execution at a remote host. The authentication is based on password information stored in the OpenVMS system's User Authorization File (UAF). The REXEC feature is useful if the remote host does not have, or might not have, the authentication information that RSH requires. Users invoke REXEC by issuing RSH /PASSWORD. 4 SMTP The Simple Mail Transfer Protocol (SMTP) server and client software transfers electronic mail messages between systems. SMTP specifies how these systems interact and the format of the mail messages they exchange. SMTP uses the OpenVMS Mail utility. To send mail with SMTP, users issue the DCL MAIL command and specify the fully qualified Internet address as the destination. By default, Internet addresses that are not fully qualified (that is, whose node component does not include a period (.), such as MALCOLM@PHILOS), are converted to a format for DECnet transport (for example, PHILOS::MALCOLM). To force messages with such addresses to be sent over SMTP, do one of the following: o Specify the fully qualified Internet address (such as MALCOLM@PHILOS.BU.EDU) o Prefix the address with SMTP% followed, without a space, by the destination address, enclosing the address in quotation marks (for example, SMTP%"MALCOLM@PHILOS") o Set the logical MAIL$INTERNET_MODE to SMTP and make sure the MAIL$INTERNET_TRANSPORT logical does not define an alternate Internet protocol) With the Post Office Protocol (POP) functionality, you can receive and send OpenVMS mail from your PC. POP is a mail repository that accepts and stores your mail even when the PC is turned off. At your request, the POP server reads mail from your OpenVMS NEWMAIL folder, then moves the mail to your MAIL folder. 4 Network_Printing The Line Printer/Line Printer Daemon (LPR/LPD) of the DIGITAL TCP/IP Services for OpenVMS software supports the DCL PRINT, lpr, LPQ, and LPRM commands for remote printing. The LPR/LPD service allows users to print to queues on remote hosts. The service also allows users on remote hosts to access queues on the local host system. 4 TELNET The TELNET Server and Client software provides remote terminal connections. With TELNET, users work in remote system accounts as if their terminals were connected directly to the remote system. The DIGITAL TCP/IP Services for OpenVMS implementation of the TELNET Client offers a user simultaneous multiple sessions and IBM 3270 model terminal emulation (TN3270). The TELNET Client includes: o DCL TELNET command o DCL TN3270 o TELNET commands within the TELNET utility These TELNET commands offer two command-line interfaces: UNIX style and OpenVMS style. 2 User_Services Some of the DIGITAL TCP/IP Services for OpenVMS facilities provide similar capabilities. The following table helps you determine the best facility to use for your specific needs and indicates where to look for information about that facility. The following table helps you determine the best facility to use for your specific needs. Table 1 Facilities to Use for Specific Needs To obtain user information, if you need to... Use... Get information about users logged in to a FINGER remote host, such as their login user names, current program being used, and last login. Get information about users logged in to your FINGER/CLUSTER OpenVMS Cluster. To copy files, if you need to... Use... Perform other operations on the files, such FTP as deleting, renaming, appending, and viewing files. Copy multiple files to or from one or more FTP unrelated directories on the remote host. Copy every file and subdirectory in a directory RCP on a host, preserving the directory hierarchy. Create or delete directories, and display the FTP contents of directories. Copy files between two remote hosts. RCP Perform fast file transfers between two OpenVMS FTP hosts. Copy files to and from a remote UNIX system, FTP preserving RMS file attributes. Copy files, preserving the protection mode and RCP modification date. Copy and work with files using DECnet file FTP specifications. To print files, if you need to... Use... Send local files to a remote host printer. FTP PUT, DCL PRINT Send remote files to your local host printer. FTP GET Send local files to a remote host printer DCL PRINT or print queue, using the OpenVMS printing options such as customizing the printed page with special print forms, specifying the number of copies to print, and so forth. Display the status of remote print queue jobs LPQ, LPRM and cancel print jobs in that queue. Send remote UNIX files to a local print queue. lpr To log in to remote accounts, if you need to... Use... Log in to a remote host that runs Remote (R) RLOGIN protocols. Log in to a remote host, using many options TELNET to customize the session, control output from the remote host, and negotiate compatibility differences. Establish multiple, simultaneous login TELNET connections with one or more hosts, and toggle between the sessions. Log in using IBM 3270 Information System (IDS) TN3270 terminal emulation with a host that uses IBM 3270 model terminals. To issue remote commands, if you need to... Use... Issue a command on a remote host, including a RSH, REXEC command that invokes a remote shell script or command procedure, with any output displayed at your terminal. Issue a command, without specifying user RSH authentication information, on a remote host that has authentication files. Issue a command and password to a host that RSH/PASSWORD does not have authentication files for you. To send and receive mail, if you need to... Use... Send mail to, and receive mail from, a remote MAIL host using SMTP. Send and receive OpenVMS mail, at your PC. MAIL, POP 3 Working_with_Files FTP allows you to establish a session with the remote host and enter an unlimited number of commands that copy, display, or manipulate files and directories. The Anonymous FTP feature allows you to connect to a remote host without specifying user authentication information. If that feature is not enabled, you must supply user authentication information for a remote host only once: when you first establish the FTP connection with the remote host. FTP allows you to determine or change the working directory on your host and on the remote host, and to perform various other operations on files and directories. In contrast, RCP is limited to copying files. To copy files, each RCP command that you enter establishes a separate link for each file transfer with the specified remote host. With each RCP command, you must specify the remote host to or from which you want to copy files. As with FTP, RCP has a feature that allows you to connect to remote hosts without specifying user authentication information. However, if that feature is not enabled, you must enter user authentication information with each RCP command, rather than just once (as with FTP) for any number of subsequent commands for a connected host. 3 Remote_Logins The RLOGIN, TELNET, and TN3270 facilities each allow you to log in to a remote host and enable your terminal to perform as if directly connected to the remote host. Use RLOGIN for simple logins in which you do not require much customization or control of the terminal-to-host interaction. Use TELNET if you want to use its extensive terminal features and controls, or you want to open several terminal sessions with one or more remote hosts. With TELNET's extensive functionality, it can support a wider variety of terminal features and behaviors between disparate, otherwise incompatible, systems. Use TN3270 to connect your terminal to a remote host that supports IBM 3270 IDS terminals. TN3270 assigns IBM 3270 functions to your DIGITAL keyboard and allows you to redefine keys. 3 Remote_Commands RSH and REXEC allow you to send any commands supported by the remote host operating system. RSH and REXEC issue one command per link. If user authentication is required, you must enter the authentication information with each command. There is no REXEC command. You invoke REXEC when you enter the RSH command with a password (RSH/PASSWORD). Note that RLOGIN, TELNET, and TN3270 allow you to log into a remote host once and then perform any number of commands supported by the remote host's operating system. TELNET and TN3270 also allow you to send certain commands to the connected remote host during a terminal session; however, these are a limited range of commands dealing with communication between hosts. They are not operating system commands. For example, you can send a command that aborts output or interrupts execution of a command you issued previously. 2 Client-Server The TCP/IP Services for OpenVMS user services include client and server software that communicates between host systems. Your local host includes client software that responds to your commands by requesting the appropriate services from the remote host you specify. If the remote host has the appropriate server software, the server on that host responds with the requested service. 2 Release_Notes The DIGITAL TCP/IP Services for OpenVMS Release Notes are in the file: SYS$HELP:UCX042.RELEASE_NOTES 2 Getting_Started The FTP, TELNET, and TN3270 utilities include a wider variety of commands than do the other user services. You can start FTP, TELNET, or TN3270 and connect to a remote host interactively in either of two ways: o Specify the utility name followed by a Return. The utility's prompt appears, and you can then enter the CONNECT command. For example, to start FTP and connect to a remote host named FATHM, type: $ FTP <RETURN> FTP> CONNECT FATHM . . . FTP> o Specify the utility name and host name in one line, as in the following example: $ FTP FATHM<RETURN> . . . FTP> In either case, you are prompted for user authentication information. (FTP includes a feature that allows you to connect to a remote host without specifying user authentication information). You can also start these utilities by using a command procedure. Start the Remote (R) and network printer services by specifying the appropriate command, host name, and parameters or qualifiers in one command line. If you specify the service command only (RCP, RSH, RLOGIN, PRINT, LPQ, or LPRM), the service will prompt you for the information required for the command. The PRINT command supports remote printing, using TCP/IP protocols and supporting the DCL PRINT qualifiers, with a few exceptions and additional features. When you enter the FINGER command without any host or user information, the service displays information about users on your local system. To display information about remote users, you need to specify the remote host name. To start MAIL and then send a message to a user on another internet host, simply start the OpenVMS Mail utility as you normally do, and use the SEND command with the Internet address of the remote host, such as in the following example. The Mail utility will use the SMTP protocol to send the mail. $ MAIL MAIL> send <Return> To: MALCOLM@PHILOS.BU.ORG <Return> Subj: FINAL EXAMS<Return> For more help on using DIGITAL TCP/IP Services for OpenVMS commands, use the DCL HELP TCP_IP_SERVICES command; for example, $ HELP TCP_IP_SERVICES TELNET The FTP, TELNET, and TN3270 utilities also provide help at the utility prompt; for example, TELNET> HELP For an introduction to the features and services provided by the DIGITAL TCP/IP Services for OpenVMS product, see the Overview topic. For tutorial information about how to use the various services, see the individual help topics for those services. 2 Command_Syntax Help available for general command syntax topics is listed below. 3 Command_Formats Most UCX command descriptions specify both a DCL-style format and a UNIX-style format. You can, therefore, type command lines in either format. For example, the following two command lines achieve the same results: TELNET> CONNECT BENTLEY TELNET> open bentley 3 Abbreviate_Keywords You can abbreviate commands and qualifiers to the fewest number of characters, usually three, that uniquely identifies the keyword. For example, the following two command lines achieve the same results: $ RL RENT /USE=BUNNINGS $ RLOGIN RENT /USER_NAME=BUNNINGS 3 Quotation_Marks Due to differences in OpenVMS and UNIX syntax, some command lines require quotation marks for selected keywords. These requirements apply to case sensitivity, slashes, and certain special characters (such as &, =, and \). UNIX is case sensitive; UNIX host names, user names, and passwords are usually lowercase. All UNIX directory names contain slashes. For the requirements for individual services, see the discussion of quotation marks under each major user service topic (Finger, FTP, R_commands, Network_Terminals, Mail, or Network_ Printing). 3 Name_or_Address Unless otherwise stated, whenever you specify a host on a command line, you can use either its relative name or its IP address. The relative name of a host is a simple name that does not include the fully qualified domain name. That is, it does not include one or more periods (.). For example, the relative host name VENDOR might have a fully qualified domain name such as VENDOR.GOODS.IGCORP.COM. The following two examples show two ways to issue the TELNET command to connect to host VENDOR at IP address 17.22.3.4. $ TELNET VENDOR Trying...17.22.3.4 Connected to VENDOR. Escape character is '^]'. UNIX V5 (vendor.goods.igcorp.com) login: 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: 3 File_and_Directory_Names When you specify OpenVMS directory names and file names, follow OpenVMS file specification rules, as explained in the OpenVMS documentation. Likewise, when you specify UNIX directory names and file names, follow UNIX file specification rules, as explained in the documentation supplied with the UNIX system. 3 Parameters:_Multiple_Values To specify multiple values for command parameters, such as host names and directories, follow these guidelines: o Separate elements with commas. o Wildcards are valid. o A space between multiple elements is optional. The following FTP GET command copies the files PROJ1.TXT and GROUP1.TXT, using a comma to separate the file names in the command line: FTP> GET PROJ1.TXT, GROUP1.TXT The following FTP GET command uses the asterisk (*) wildcard to copy all files starting with the letters "PROJ1": FTP> GET PROJ1*.* 3 Qualifiers:_Multiple_Values To specify multiple values for qualifiers, enclose them in parentheses as follows: /qualifier=(value1,value2,value3 ) For example, the following LPRM command deletes three jobs from a remote print queue: $ LPRM EST_4_1997_Q /ENTRY=(555,556,558) 3 Numeric_Values Unless stated otherwise, all values are decimal. 3 Brackets_and_Braces Command format descriptions in this help include braces and brackets. You should understand the meaning of the braces and brackets: o Braces ( { } ) - You must specify: - At least one of the enclosed values, or - All of the enclosed values (this case is always noted). Example 1: This example shows the format line for the FTP SET DEFAULT command. The choices for the directory specification parameter are enclosed in braces, which means that you must specify one of these values (either an OpenVMS directory name or a UNIX path name). FTP> SET DEFAULT /LOCAL {vms_directory_name | unix/path/name} Example 2: In this TELNET example, you must specify either CHAR or LINE. TELNET> SET MODE {CHAR | LINE} o Brackets ( [ ] ) - The enclosed values are optional. Example 1: The last two parameters for the TELNET CONNECT command are enclosed in brackets, which means they are optional. In this example, the port can be specified without a terminal type, and the host without a port. TELNET> CONNECT host [ port [terminal_type ] ] Example 2: The format of the RSH command shows that all the qualifiers and the remote_command parameter are optional. $ 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 ] 2 NSLOOKUP The NSLOOKUP Facility lets you interactively query domain name servers (BIND servers). This tool helps you set up and manage the BIND server software. You can get the following information: Host names and addresses on the local domain Host names and addresses on remote domains Host names that have mail exchanger (MX records) Name servers for a specific zone For information about individual NSLOOKUP commands, type: $ $ RUN SYS$SYSTEM:UCX$NSLOOKUP > HELP 3 Starting Use the following command to start NSLOOKUP: $ RUN SYS$COMMON:[SYSEXE]UCX$NSLOOKUP.EXE 3 Exiting To exit from within interactive mode, type: > <Ctrl/d> 3 Terminating_Lookups To terminate the current lookup activity, type: > <Ctrl/c> 3 Command_Guidelines The command line length must be less than 256 characters. Unrecognized commands are interpreted as a host name. 3 Modes_of_Operation NSLOOKUP has two modes: o Interactive mode + Queries name servers for information about hosts and domains. + Asks for a printout of a list of hosts in a domain. + Use this mode if you have no arguments to provide. nslookup queries the default BIND server. + To request a query to a specific BIND server, use a hyphen (-) as the first argumentand the host name or IP address of the name server as the second argument. o Non-interactive mode + Queries for the name and IP address of a host or domain. + Use this mode when the name or IP address of the host that you are looking up is the first argument. + The optional second argument specifies a name server. 2 Tracing The UCX$TRACE utility lets you trace packet flow between the local UCX host and remote hosts. You can either monitor all packet flow or use the various qualifiers to monitor only those packets of interest. 3 Starting To start the UCX$TRACE utility use the TCPIPTRACE command: $ TCPIPTRACE HOST1 /FULL /PACKETS=30 3 Stopping To stop the UCX$TRACE utility use CTRL/C. 2 Programming_Interfaces UCX includes a standard C sockets API and a standard Open Network Computing Remote Procedure Call (ONC RPC) API. The standard C socket API provides UNIX-style access to the TCP and UDP transports and to the IP network layer. The ONC RPC library provides a method of creating communicating programs without the need to program the details of the transport protocol being used. The ONC RPC library is divided into calls frequently used by client programs, calls used to access the Portmapper utility, and calls frequently used by server programs. The ONC RPC library also includes XDR routines which provide the ability to transport data over the network in a standard fashion. 3 RPC_Client_Routines Client routines allow C programs to make procedure calls to server programs across the network. Important: In order to maintain uniqueness for the OpenVMS HELP utility, some client routines have a "_#" appended at the end. Do not use the "_#" when coding the routine in a program. 4 auth_destroy A macro that frees the memory associated with the authentication handle created by the authnone_create and authunix_create routines. Format #include <rpc/rpc.h> void auth_destroy(AUTH *auth_handle) 5 Arguments auth_handle An RPC authentication handle created by the authnone_create, authunix_create, or authunix_create_default routine. 5 Description Frees the memory associated with the AUTH data structure created by the authnone_create, authunix_create, or authunix_create_ default routine. Be careful not to reference the data structure after calling this routine. 5 Return_Values None 4 authnone_create Creates a authentication handle for passing null credentials and verifiers to remote systems. Format #include <rpc/rpc.h> AUTH *authnone_create ( ) 5 Arguments None 5 Description Creates and returns an authentication handle that passes null authentication information with each remote procedure call. Use this routine if the server process does not require authentication information. RPC uses this routine as the default authentication routine unless you create another authentication handle using either the authunix_create or authunix_create_ default routine. 5 Return_Values AUTH * Authentication handle containing the pertinent information. NULL Indicates allocation of AUTH handle failed. 4 authunix_create Creates and returns an RPC authentication handle that contains UNIX-style authentication information. Format #include <rpc/rpc.h> AUTH *authunix_create(char *host, int uid, int gid, int len, int *aup_gids ); 5 Arguments host Pointer to the name of the host on which the information was created. This is usually the name of the system running the client process. uid The user's user identification. gid The user's current group. len The number of elements in aup_gids array. NOTE This parameters is ignored by UCX's RPC implementation. aup_gids A pointer to an array of groups to which the user belongs. NOTE This parameters is ignored by UCX's RPC implementation. 5 Description Implements UNIX-style authentication parameters. The client uses no encryption for its credentials and only sends null verifiers. The server sends back null verifiers or optionally a verifier that suggests a new shorthand for the credentials. 5 Return_Values AUTH * Authentication handle containing the pertinent information. NULL Indicates allocation of AUTH handle failed. 4 authunix_create_default Returns a default authentication handle. Format #include <rpc/rpc.h> AUTH *authunix_create_default( ) 5 Arguments None 5 Description Calls the authunix_create routine with the local host name, effective process ID and group ID, and the process default groups. 5 Return_Values AUTH * Authentication handle containing the pertinent information. NULL Indicates allocation of AUTH handle failed. 5 Examples 1.auth_destroy(client->cl_auth) client->cl_auth = authunix_create_default(); This example overrides the default authnone_create action. The client handle, client, is returned by the clnt_create, clnt_ create_vers, clnttcp_create, or clntudp_create routine. 4 callrpc Executes a remote procedure call. Format #include <rpc/rpc.h> int callrpc(char *host, u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, char *in, xdrproc_t outproc, char *out); 5 Arguments host A pointer to the name of the host on which the remote procedure resides. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. procnum The procedure number associated with the remote procedure. inproc The XDR routine used to encode the remote procedure's arguments. 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. 5 Description Calls the remote procedure associated with prognum, versnum, and procnum on the host host. This routine performs the same functions as a set of calls to the clnt_create, clnt_call, and clnt_destroy routines. This routine returns RPC_SUCCESS if it succeeds, or the value of enum clnt_stat cast to an integer if it fails. The routine clnt_perrno is handy for translating a failure status into a message. NOTE Calling remote procedures with this routine uses UDP/IP as a transport; see clntudp_create for restrictions. You do not have control of timeouts or authentication using this routine. If you want to use the TCP transport, use the clnt_ create or clnttcp_create routine. 5 Return_Values RPC_SUCCESS Indicates success. clnt_stat Returns a value of type enum clnt_stat cast to type int containing the status of the callrpc operation. 4 clnt_broadcast Executes a remote procedure call that is sent to all locally connected networks using the broadcast address. Format #include <rpc/rpc.h> enum clnt_stat clnt_broadcast(u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, char * in, xdrproc_t outproc, char * out, resultproc_t eachresult); 5 Arguments prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. procnum The procedure number associated with the remote procedure. inproc The XDR routine used to encode the remote procedure's arguments. 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. 5 Description Performs the same function as the callrpc routine, except that the call message is sent to all locally connected networks using the broadcast address. Each time it receives a response, this routine calls the eachresult routine. If eachresult returns zero, clnt_broadcast waits for more replies; otherwise it assumes success and returns RPC_SUCCESS. NOTE This routine uses the UDP protocol. Broadcast sockets are limited in size to the maximum transfer unit of the data link. For Ethernet, this value is 1400 bytes. For FDDI, this value is 4500 bytes. 5 Return_Values RPC_SUCCESS Indicates success. clnt_stat Returns the buffer of type enum clnt_stat containing the status of the clnt_broadcast operation. 4 clnt_call A macro that calls a remote procedure. Format #include <rpc/rpc.h> enum clnt_stat clnt_call(CLIENT *handle, u_long procnum, xdrproc_t inproc, char *in, xdrproc_t outproc, char *out, struct timeval timeout); 5 Arguments handle A pointer to a client handle created by any of the client handle creation routines. procnum The procedure number associated with the remote procedure. inproc The XDR routine used to encode the remote procedure's arguments. 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. 5 Description Use the clnt_call macro after using one of the client handle creation routines. After you are finished with the handle, return it using the clnt_destroy macro. Use the clnt_perror to print any errors that occurred. 5 Return_Values RPC_SUCCESS Indicates success. clnt_stat Returns the buffer of type enum clnt_stat containing the status of the clnt_call operation. 4 clnt_control A macro that changes or retrieves information about an RPC client process. Format #include <rpc/rpc.h> bool_t clnt_control(CLIENT *handle, u_int code, char *info); 5 Arguments handle A pointer to a client handle created by any of the client handle creation routines. code A code designating the type of information to be set or retrieved. info A pointer to a buffer containing the information for a SET operation or the results of a GET operation. 5 Description For UDP and TCP transports specify any of the following for code: CLSET_TIMEOUT struct Set total timeout timeval CLGET_TIMEOUT struct Get total timeout timeval CLGET_SERVER_ADDR struct Get server address sockaddr_ in CLGET_FD int Get associated socket CL_FD_CLOSE void Close socket on clnt_destroy CL_FD_NCLOSE void Leave socket open on clnt_ destroy If you set the timeout using clnt_control, ONC RPC ignores the timeout parameter in all future clnt_call calls. The default total timeout is 25 seconds. For the UDP transport two additional options are available: CLSET_RETRY_ struct Set retry timeout TIMEOUT timeval CLGET_RETRY_ struct Get retry timeout TIMEOUT timeval The timeout value in these two calls is the time that UDP waits for a response before retransmitting the message to the server. The default time is 5 seconds. The retry timeout controls when UDP retransmits the request, the total timeout controls the total time that the client should wait for a response. For example, with the default settings, UDP will retry the transmission four times at 5-second intervals. 5 Return_Values TRUE Success FALSE Failure 4 clnt_create_# Creates a client handle and returns its address. Format #include <rpc/rpc.h> CLIENT *clnt_create(char *host, u_long prognum, u_long versnum, char *protocol); 5 Arguments host A pointer to the name of the remote host. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. protocol A pointer to a string containing the name of the protocol for transmitting and receiving RPC messages. Specify either tcp or udp. 5 Description The clnt_create routine creates an RPC client handle for prognum. An RPC client handle is a structure containing information about the RPC client. The client can use the UDP or TCP transport protocol. This routine uses the Portmapper. You cannot control the local port. The default sizes of the send and receive buffers are 8800 bytes for the UDP transport, and 4000 bytes for the TCP transport. The retry time for the UDP transport is five seconds. Use the clnt_create routine instead of the callrpc or clnt_ broadcast routines if you want to use one of the following: o The TCP transport o A non-null authentication o More than one active client at the same time You can also use the clnttcp_create routine to use the TCP protocol, or the clntudp_create routine to use the UDP protocol. The clnt_create routine uses the global variable rpc_createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerrif you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. NOTE If the requested program is available on the host but the program does not support the requested version number, this routine still succeeds. A subsequent call to the clnt_call routine will discover the version mismatch. Use the clnt_ create_vers routine if you want to avoid this condition. 5 Return_Values CLIENT * Client handle containing the server information. NULL Error occurred while creating the client handle. Use the clnt_pcreateerror or clnt_ spcreateerror routine to obtain diagnostic information. 4 clnt_create_vers Creates a client handle and returns its address. Seeks to use a server supporting the highest version number within a specified range. Format #include <rpc/rpc.h> CLIENT *clnt_create_vers(char *host, u_long prognum, u_long *versnum, u_long min_vers, u_long max_vers, char *protocol); 5 Arguments host A pointer to the name of the remote host. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. This value is returned by the routine. The value is the highest version number supported by the remote server that is in the range of version numbers specified by min_vers and max_vers. The argument may remain undefined; see additional information in the Description section. min_vers The minimum acceptable version number for the remote procedure. max_vers The maximum acceptable version number for the remote procedure. protocol A pointer to a string containing the name of the protocol for transmitting and receiving RPC messages. Specify either tcp or udp. 5 Description The clnt_create_vers routine creates an RPC client handle for prognum. An RPC client handle is a structure containing information about the RPC client. The client can use the UDP or TCP transport protocol. This routine uses the Portmapper. You cannot control the local port. The default sizes of the send and receive buffers are 8800 bytes for the UDP transport, and 4000 bytes for the TCP transport. The retry time for the UDP transport is 5 seconds. The clnt_create_vers routine differs from the standard clnt_ create routine in that it seeks out the highest version number supported by the server. If the server does not support any version numbers within the requested range, the routine returns NULL and the versnum variable is undefined. The clnt_create_vers routine uses the global variable rpc_ createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. 5 Return_Values CLIENT * Client handle containing the server information. NULL Error occurred while creating the client handle. Usually the error indicates that the server does not support any version numbers within the requested range. Use the clnt_ pcreateerror or clnt_spcreateerror routine to obtain diagnostic information. 4 clnt_destroy A macro that frees the memory associated with an RPC client handle. Format #include <rpc/rpc.h> void clnt_destroy(CLIENT *handle); 5 Arguments handle A pointer to a client handle created by any of the client handle creation routines. 5 Description The clnt_destroy routine destroys the client's RPC handle by deallocating all memory related to the handle. The client is undefined after the clnt_destroy call. If the clnt_create routine had previously opened the socket associated with the client handle or the program had used the clnt_control routine to set CL_FD_CLOSE, this routine closes the socket. If the clnt_create routine had not previously opened the socket associated with the client handle or the program had used the clnt_control routine to set CL_FD_NCLOSE, this routine leaves the socket open. 5 Return_Values None 4 clnt_freeres A macro that frees the memory that was allocated when the remote procedure's results were decoded. Format #include <rpc/rpc.h> bool_t clnt_freeres(CLIENT *handle, xdrproc_t outproc, char *out); 5 Arguments handle A pointer to a client handle created by any of the client handle creation routines. outproc The XDR routine used to decode the remote procedure's results. out A pointer to the remote procedure's results. 5 Description The clnt_freeres routine calls the xdr_free routine to deallocate the memory where the remote procedure's results are stored. 5 Return_Values TRUE Success. FALSE Error occurred while freeing the memory. 4 clnt_geterr A macro that returns error information indicating why an RPC call failed. Format #include <rpc/rpc.h> void clnt_geterr(CLIENT *handle, struct rpc_err *errp); 5 Arguments handle A pointer to a client handle created by any of the client handle creation routines. errp A pointer to an rpc_err structure containing information that indicates why an RPC call failed. This information is the same information as clnt_stat contains, plus one of the following: the C error number, the range of server versions supported, or authentication errors. 5 Description This macro copies the error information from the client handle to the structure referenced by errp. The macro is mainly for diagnostic use. 5 Return_Values None 4 clnt_pcreateerror Prints a message explaining why ONC RPC could not create a client handle. Format #include <rpc/rpc.h> void clnt_pcreateerror(char *sp); 5 Arguments sp A pointer to a string to be used as the beginning of the error message. 5 Description The clnt_pcreateerror routine prints a message to SYS$OUTPUT. The message consists of the sp parameter followed by an RPC-generated error message. Use this routine when the clnt_create, clnttcp_ create, or clntudp_create routine fails. 5 Return_Values None 4 clnt_perrno Prints a message indicating why the callrpc or clnt_broadcast routine failed. Format #include <rpc/rpc.h> void clnt_perrno(enum clnt_stat stat) ; 5 Arguments stat A buffer containing status information. 5 Description Prints a message to standard error corresponding to the condition indicated by the stat argument. The data type declaration for clnt_stat in rpc/rpc.h lists the standard errors. 5 Return_Values None 4 clnt_perror Prints a message explaining why an ONC RPC routine failed. Format #include <rpc/rpc.h> void clnt_perror(CLIENT *handle, char *sp); 5 Arguments handle A pointer to the client handle used in the call that failed. sp A pointer to a string to be used as the beginning of the error message. 5 Description Prints a message to standard error indicating why an ONC RPC call failed. The message is prepended with string sp and a colon. 5 Return_Values None 4 clnt_spcreateerror Returns a message indicating why RPC could not create a client handle. Format #include <rpc/rpc.h> char *clnt_spcreateerror(char *sp); 5 Arguments sp A pointer to a string to be used as the beginning of the error message. 5 Description The clnt_spcreateerror routine returns the address of a message string. The message consists of the sp parameter followed by an error message generated by calling the clnt_sperrno routine. Use the clnt_spcreateerror routine when the clnt_create, clnttcp_ create, or clntudp_create routine fails. Use this routine if: o You want to save the string. o You do not want to use fprintf to print the message. o The message format is different from the one that clnt_perrno supports. The address that clnt_spcreateerror returns is the address of its own internal string buffer. The clnt_spcreateerror routine overwrites this buffer with each call. Therefore, you must copy the string to your own buffer if you wish to save the string. 5 Return_Values char * A pointer to the message string terminated with a NULL character. NULL The routine was not able to allocate its internal buffer. 4 clnt_sperrno Returns a message indicating why the callrpc or clnt_broadcast routine failed to create a client handle. Format #include <rpc/rpc.h> char *clnt_sperrno(enum clnt_stat stat); 5 Arguments stat A buffer containing status information. 5 Description The clnt_sperrno routine returns a pointer to a string. Use this routine instead if: o The server does not have a stderr file; many servers do not. o You want to save the string. o You do not want to use fprintf to print the message. o The message format is different from the one that clnt_perrno supports. The address that clnt_sperrno returns is a pointer to the error message string for the error. Therefore, you do not have to copy the string to your own buffer in order to save the string. 5 Return_Values char * A pointer to the message string terminated with a NULL character. 4 clnt_sperror Returns a message indicating why an ONC RPC routine failed. Format #include <rpc/rpc.h> char *clnt_sperror(CLIENT *handle, char *sp); 5 Arguments handle A pointer to the client handle used in the call that failed. sp A pointer to a string to be used as the beginning of the error message. 5 Description The clnt_sperror routine returns a pointer to a message string. The message consists of the sp parameter followed by an error message generated by calling the clnt_sperrno routine. Use this routine when the clnt_call routine fails. Use this routine if: o You want to save the string. o You do not want to use fprintf to print the message. o The message format is different from the one that clnt_perrno supports. The address that clnt_sperror returns is a pointer to its own internal string buffer. The clnt_sperror routine overwrites this buffer with each call. Therefore, you must copy the string to your own buffer if you wish to save the string. 5 Return_Values char * A pointer to the message string terminated with a NULL character. NULL The routine was not able to allocate its internal buffer. 4 clntraw_create Creates a client handle for memory-based ONC RPC for simple testing and timing. Format #include <rpc/rpc.h> CLIENT *clntraw_create(u_long prognum, u_long versnum); 5 Arguments prognum The program number associated with the remote program. versnum The version number associated with the remote program. 5 Description Creates an in-program ONC RPC client for the remote program prognum, version versnum. The transport used to pass messages to the service is actually a buffer within the process's address space, so the corresponding server should live in the same address space; see svcraw_create. This allows simulation of and acquisition of ONC RPC overheads, such as round-trip times, without any kernel interference. 5 Return_Values CLIENT * A pointer to a client handle. NULL Indicates failure. 4 clnttcp_create Creates an ONC RPC client handle for a TCP/IP connection. Format #include <rpc/rpc.h> CLIENT *clnttcp_create(struct sockaddr_in *addr, u_long prognum, u_long versnum, int *sockp, u_int sendsize, u_int recvsize); 5 Arguments addr A pointer to a buffer containing the internet address where the remote program is located. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. sockp A pointer to the socket number to be used for the remote procedure call. If sockp is RPC_ANYSOCK, then this routine opens a new socket and sets sockp. sendsize The size of the send buffer. If you specify 0 the routine chooses a suitable default. recvsize The size of the receive buffer. If you specify 0 the routine chooses a suitable default. 5 Description Creates an ONC RPC client handle for the remote program prognum, version versnum at address addr. The client uses TCP/IP as a transport. The routine is similar to the clnt_create routine, except clnttcp_create allows you to specify a socket and the send and receive buffer sizes. If you specify the port number as zero by using addr->sin_port, the Portmapper provides the number of the port on which the remote program is listening. The clnttcp_create routine uses the global variable rpc_ createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. The rpc_createerr variable is defined in the CLNT.H file. The socket referenced by sockp is copied into a private area for RPC to use. It is the client's responsibility to close the socket referenced by sockp. The authentication scheme for the client, client->cl_auth, gets set to null authentication. The calling program can set this to something different if necessary. NOTE If the requested program is available on the host but the program does not support the requested version number, this routine still succeeds. A subsequent call to the clnt_call routine will discover the version mismatch. Use the clnt_ create_vers routine if you want to avoid this condition. 5 Return_Values CLIENT * A pointer to the client handle. NULL Indicates failure. 4 clntudp_bufcreate Creates an ONC RPC client handle for a buffered I/O UDP connection. Format #include <rpc/rpc.h> CLIENT *clntudp_bufcreate(struct sockaddr_in *addr, u_long prognum, u_long versnum, struct timeval wait, register int *sockp, u_int sendsize, u_int recvsize); 5 Arguments addr A pointer to a buffer containing the internet address where the remote program is located. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. wait The amount of time used between call retransmission if no response is received. Retransmission occurs until the ONC RPC calls time out. sockp A pointer to the socket number to be used for the remote procedure call. If sockp is RPC_ANYSOCK, then this routine opens a new socket and sets sockp. sendsize The size of the send buffer. If you specify 0, the routine chooses a suitable default. recvsize The size of the receive buffer. If you specify 0, the routine chooses a suitable default. 5 Description Creates an ONC RPC client handle for the remote program prognum, version versnum at address addr. The client uses UDP as the transport. The routine is similar to the clnt_create routine, except clntudp_bufcreate allows you to specify a socket, the UDP retransmission time, and the send and receive buffer sizes. If you specify the port number as zero by using addr->sin_port, the Portmapper provides the number of the port on which the remote program is listening. The clntudp_bufcreate routine uses the global variable rpc_ createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. The rpc_createerr variable is defined in the CLNT.H file. The socket referenced by sockp is copied into a private area for RPC to use. It is the client's responsibility to close the socket referenced by sockp. The authentication scheme for the client, client->cl_auth, gets set to null authentication. The calling program can set this to something different if necessary. NOTE If addr->sin_port is 0 and the requested program is available on the host but the program does not support the requested version number, this routine still succeeds. A subsequent call to the clnt_call routine will discover the version mismatch. Use the clnt_create_vers routine if you want to avoid this condition. 5 Return_Values CLIENT * A pointer to the client handle. NULL Indicates failure. 4 clntudp_create Creates an ONC RPC client handle for a non-buffered I/O UDP connection. Format #include <rpc/rpc.h> CLIENT *clntudp_create(struct sockaddr_in *addr, u_long prognum, u_long versnum, struct timeval wait, register int *sockp); 5 Arguments addr A pointer to a buffer containing the internet address where the remote program is located. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. wait The amount of time used between call retransmission if no response is received. Retransmission occurs until the ONC RPC calls time out. sockp A pointer to the socket number to be used for the remote procedure call. If sockp is RPC_ANYSOCK, then this routine opens a new socket and sets sockp. 5 Description Creates an ONC RPC client handle for the remote program prognum, version versnum at address addr. The client uses UDP as the transport. The routine is similar to the clnt_create routine, except clntudp_create allows you to specify a socket and the UDP retransmission time. If you specify the port number as zero by using addr->sin_port, the Portmapper provides the number of the port on which the remote program is listening. The clntudp_create routine uses the global variable rpc_ createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. The rpc_createerr variable is defined in the CLNT.H file. The socket referenced by sockp is copied into a private area for RPC to use. It is the client's responsibility to close the socket referenced by sockp. The authentication scheme for the client, client->cl_auth, gets set to null authentication. The calling program can set this to something different if necessary. NOTES Since UDP/IP messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for procedures that take large arguments or return huge results. If addr->sin_port is 0 and the requested program is available on the host but the program does not support the requested version number, this routine still succeeds. A subsequent call to the clnt_call routine will discover the version mismatch. Use the clnt_create_vers routine if you want to avoid this condition. 5 Return_Values CLIENT * A pointer to the client handle. NULL Indicates failure. 4 get_myaddress Returns the local host's internet address. Format #include <rpc/rpc.h> void get_myaddress(struct sockaddr_in *addr); 5 Arguments addr A pointer to a sockaddr_in structure that the routine will load with the internet address of the host where the local procedure resides. 5 Description Puts the local host's internet address into addr without doing any name translation. The port number is always set to htons (PMAPPORT). 5 Return_Values None 4 get_myaddr_dest Returns the local host's internet address according to a destination address. Format #include <rpc/rpc.h> void get_myaddr_dest(struct sockaddr_in *addr, struct sockaddr_in *dest); 5 Arguments addr A pointer to a sockaddr_in structure that the routine will load with the local internet address which would provide a connection to the remote address specified in dest. dest A pointer to a sockaddr_in structure containing an internet address of a remote host. 5 Description Since the local host may have multiple network addresses (each on its own interface), this routine is used to select the local address which would provide a connection to the remote address specified in dest. This is an alternative to gethostbyname, which invokes yellow pages. It takes a destination (where we are trying to get to) and finds an exact network match to go to. 5 Return_Values None 3 RPC_Portmapper_Routines Portmapper routines allow C programs to access the Portmapper network service. Important: In order to maintain uniqueness for the OpenVMS HELP utility, some XDR routines have a "_#" appended at the end. Do not use the "_#" when coding the routine in a program. 4 pmap_getmaps_# Returns a copy of the current port mappings on a remote host. Format #include <rpc/pmap_clnt.h> struct pmaplist *pmap_getmaps(struct sockaddr_in *addr); 5 Arguments addr A pointer to a sockaddr_in structure containing the internet address of the host whose Portmapper you wish to call. 5 Description A client interface to the Portmapper, which returns a list of the current ONC RPC program-to-port mappings on the host located at the internet address addr. The UCX SHOW PORTMAPPER command uses this routine. 5 Return_Values struct pmaplist * A pointer to the returned list of server-to- port mappings on host addr. NULL Indicates failure. 4 pmap_getmaps_vms Returns a copy of the current port mappings on a remote UCX host. Format #include <rpc/pmap_clnt.h> struct pmaplist_vms *pmap_getmaps_vms(struct sockaddr_in *addr); 5 Arguments addr A pointer to a sockaddr_in structure containing the internet address of the UCX host whose Portmapper you wish to call. 5 Description This routine is similar to the pmap_getmaps routine. However, pmap_getmaps_vms also returns the process identifiers (PIDs) that are required for mapping requests to UCX hosts. 5 Return_Values struct pmaplist * A pointer to the returned list of server-to- port mappings on host addr. NULL Indicates failure. 4 pmap_getport Returns the port number on which the specified service is waiting. Format #include <rpc/pmap_clnt.h> u_short pmap_getport(struct sockaddr_in *addr, u_long prognum, u_long versnum, u_long protocol ); 5 Arguments 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. 5 Description A client interface to the Portmapper. This routine returns the port number on which waits a server that supports program number prognum, version versnum, and speaks the transport protocol associated with protocol (IPPROTO_UDP or IPPROTO_TCP). NOTES If the requested version is not available, but at least the requested program is registered, the routine returns a port number. The pmap_getport routine returns the port number in host byte order not network byte order. For certain routines you may need to convert this value to network byte order using the htons routine. For example, the sockaddr_in structure requires that the port number be in network byte order. 5 Return_Values x The port number of the service on the remote system. 0 No mapping exists or RPC could not contact the remote Portmapper service. In the latter case, the global variable rpc_createerr.cf_error contains the ONC RPC status. 4 pmap_rmtcall The client interface to the Portmapper service for a remote call and broadcast service. This routine allows a program to do a lookup and call in one step. Format #include <rpc/pmap_clnt.h> enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr, u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, char * in xdrproc_t outproc, char * out, struct timeval timeout, u_long *port ); 5 Arguments addr A pointer to a sockaddr_in structure containing the internet address of the host where the remote Portmapper resides. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. procnum The procedure number associated with the remote procedure. inproc The XDR routine used to encode the remote procedure's arguments. in A pointer to the remote procedure's arguments. outproc The XDR routine used to decode the remote procedure's results. out A pointer to the remote procedure's results. timeout A timeval structure describing the time allowed for the results to return to the client. port A pointer to a location for the returned port number. Modified to the remote program's port number if the pmap_rmtcall routine succeeds. 5 Description A client interface to the Portmapper, which instructs the Portmapper on the host at the internet address *addr to make a call on your behalf to a procedure on that host. Use this procedure for a ping operation and nothing else. You can use the clnt_perrno routine to print any error message. NOTE If the requested procedure is not registered with the remote Portmapper, the remote Portmapper does not reply to the request. The call to pmap_rmtcall will eventually time out. The pmap_rmtcall does not perform authentication. 5 Return_Values enum clnt_stat Returns the buffer containing the status of the operation. 4 pmap_set Called by the server procedure to have the Portmapper create a mapping of the procedure's program and version number. Format #include <rpc/pmap_clnt.h> bool_t pmap_set(u_long prognum, u_long versnum, u_long protocol, u_short port); 5 Arguments prognum The program number associated with the server procedure. versnum The version number associated with the server procedure. protocol The transport protocol that the server procedure uses. Specify either IPPROTO_UDP or IPPROTO_TCP. port The port number associated with the server program. 5 Description A server interface to the Portmapper, which establishes a mapping between the triple [prognum,versnum,protocol] and port on the server's Portmapper service. The svc_register routine calls this routine to register the server with the local Portmapper. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 pmap_unset Called by the server procedure to have the Portmapper delete a mapping of the procedure's program and version number. Format #include <rpc/pmap_clnt.h> bool_t pmap_unset(u_long prognum, u_long versnum); 5 Arguments prognum The program number associated with the server procedure. versnum The version number associated with the server procedure. 5 Description A server interface to the Portmapper, which destroys all mapping between the triple [prognum, versnum, *] and ports on the local host's Portmapper. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 3 RPC_Server_Routines Server routines allow C programs to receive procedure calls from client programs over the network. 4 registerrpc Obtains a unique systemwide procedure identification number. Format #include <rpc/rpc.h> int registerrpc(u_long prognum, u_long versnum, u_long procnum, char *(*progname)(), xdrproc_t inproc, xdrproc_t outproc ); 5 Arguments prognum The program number associated with the service procedure. versnum The version number associated with the service procedure. procnum The procedure number associated with the service procedure. progname The address of the service procedure being registered with the ONC RPC service package. inproc The XDR routine used to decode the service procedure's arguments. outproc The XDR routine used to encode the service procedure's results. 5 Description The registerrpc routine performs the following tasks for a server: o Creates a UDP server handle. See the svcudp_create routine for restrictions. o Calls the svc_register routine to register the program with the Portmapper. o Adds prognum, versnum, and procnum to an internal list of registered procedures. When the server receives a request, it uses this list to determine which routine to call. A server should call registerrpc for every procedure it implements, except for the NULL procedure. If a request arrives for program prognum, version versnum, and procedure procnum, progname is called with a pointer to its parameters. 5 Return_Values 0 Indicates success. -1 Indicates failure. 4 seterr_reply Fills in the error text in a reply message. Format #include <rpc/rpc.h> void seterr_reply(struct rpc_msg *msg, struct rpc_err *error); 5 Arguments msg A pointer to a reply message buffer. error A pointer to an rpc_err structure containing the error associated with the reply message. 5 Description Given a reply message, seterr_reply fills in the error field. 5 Return_Values None 4 svc_destroy A macro that frees the memory associated with an RPC server handle. Format #include <rpc/rpc.h> void svc_destroy(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. 5 Description The svc_destroy routine returns all the private data structures associated with a server handle. If the server handle creation routine received the value RPC_ANYSOCK as the socket, svc_destroy closes the socket. Otherwise, your program must close the socket. 5 Return_Values None 4 svc_freeargs A macro that frees the memory allocated when the procedure's arguments were decoded. Format #include <rpc/rpc.h> bool_t svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char *in); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. inproc The XDR routine used to decode the service procedure's arguments. in A pointer to the service procedure's decoded arguments. 5 Description The svc_destroy routine returns the memory that the svc_getargs routine allocated to hold the service procedure's decoded arguments. This routine calls the xdr_free routine. 5 Return_Values TRUE Success; memory successfully deallocated. FALSE Failure; memory not deallocated. 4 svc_getargs A macro that decodes the service procedure's arguments. Format #include <rpc/rpc.h> bool_t svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. inproc The XDR routine used to decode the service procedure's arguments. in A pointer to the service procedure's decoded arguments. 5 Description This routine calls the specified XDR routine to decode the arguments passed to the service procedure. 5 Return_Values TRUE Successfully decoded. FALSE Decoding unsuccessful. 4 svc_getcaller A macro that returns the address of the client that called the service procedure. Format #include <rpc/rpc.h> struct sockaddr_in *svc_getcaller(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. 5 Description This routine returns a sockaddr_in structure containing the internet address of the RPC client routine that called the service procedure. 5 Return_Values struct sockaddr_ A pointer to the socket descriptor. in 4 svc_getreqset Returns data for each server connection. Format #include <rpc/rpc.h> void svc_getreqset(fd_set *rdfds); 5 Arguments rdfds A pointer to the read file descriptor bit mask modified by the select routine. 5 Description The svc_getreqset routine is for servers that implement custom asynchronous event processing or that do not use the svc_run routine. You may only use svc_fdset when the server does not use svc_run. You are unlikely to call this routine directly, because the svc_run routine calls it. However, there are times when you cannot call svc_run. For example, suppose a program services RPC requests and reads or writes to another socket at the same time. The program cannot call svc_run. It must call select and svc_getreqset. The server calls svc_getreqset when a call to the select system call determines the server has received one or more RPC requests. The svc_getreqset routine reads in data for each server connection, then calls the server program to handle the data. The svc_getreqset routine does not return a value. It finishes executing after all sockets associated with the variable rdfds have been serviced. You may use the global variable svc_fdset with svc_getreqset. The svc_fdset variable is the RPC server's read file descriptor bit mask. To use svc_fdset: 1. Copy the global variable svc_fdset into a temporary variable. 2. Pass the temporary variable to the select routine. The select routine overwrites the variable and returns it. 3. Pass the temporary variable to the svc_getreqset routine. 5 Example #define MAXSOCK 10 int readfds[ MAXSOCK+1], /* sockets to select from*/ i, j; for(i = 0, j = 0; i << MAXSOCK; i++) if((svc_fdset[i].sockname != 0) && (svc_ fdset[i].sockname != -1)) readfds[j++] = svc_fdset[i].sockname; readfds[j] = 0; /* list of sockets ends with a zero */ switch(select(0, readfds, 0, 0, 0)) { case -1: /* an error happened */ case 0: /* time out */ break; default: /* 1 or more sockets ready for reading */ errno = 0; svc_getreqset(readfds); if( errno == ENETDOWN || errno == ENOTCONN) sys$exit( SS$_THIRDPARTY); } 5 Return_Values None 4 svc_register Registers the server program with the Portmapper service. Format #include <rpc/rpc.h> bool_t svc_register(SVCXPRT *xprt, u_long prognum, u_long versnum, void (*dispatch)(), u_long protocol); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. prognum The program number associated with the server procedure. versnum The version number associated with the server procedure. dispatch The address of the service dispatch procedure that the server procedure calls. The procedure dispatch has the following form: void dispatch(request, xprt) struct svc_req *request; SVCXPRT *xprt; The svc_run and svc_getreqset call the dispatch routine. protocol The protocol that the server procedure uses. Values for this parameter are zero, IPPROTO_UDP, or IPPROTO_TCP. If protocol is zero, the service is not registered with the Portmapper service. 5 Description Associates prognum and versnum with the service dispatch procedure dispatch. If protocol is non-zero, then a mapping of the triple [prognum, versnum, protocol] to xprt->xp_port is also established with the local Portmapper service. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 svc_run Waits for incoming RPC requests and calls the svc_getreqset routine to dispatch to the appropriate RPC server program. Format #include <rpc/rpc.h> void svc_run(); 5 Arguments None 5 Description The svc_run routine calls the select routine to wait for RPC requests. When a request arrives, svc_run calls the svc_getreqset routine. Then svc_run calls the select routine again. The svc_run routine never returns. You may use the global variable svc_fdset with the svc_run routine. See the svc_getreqset routine for more information on svc_fdset. 5 Return_Values Never returns 4 svc_sendreply Sends the results of a remote procedure call to an RPC client. Format #include <rpc/rpc.h> bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char *out); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. outproc The XDR routine used to encode the server procedure's results. out A pointer to the server procedure's results. 5 Description Called by an ONC RPC service's dispatch routine to send the results of a remote procedure call. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 svc_unregister Calls the Portmapper to unregister the specified program and version for all protocols. The program and version are removed from the list of active servers. Format #include <rpc/rpc.h> void svc_unregister(u_long prognum, u_long versnum); 5 Arguments prognum The program number associated with the server procedure. versnum The version number associated with the server procedure. 5 Description Removes all mapping of the double [prognum, versnum] to dispatch routines, and of the triple [prognum, versnum, *] to port number. 5 Return_Values None 4 svcerr_auth Sends an authentication error to the client. Format #include <rpc/rpc.h> void svcerr_auth(SVCXPRT *xprt, enum auth_stat why); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. why The reason for the authentication error. 5 Description Called by a service dispatch routine that refuses to perform a remote procedure call due to an authentication error. 5 Return_Values None 4 svcerr_decode Sends an error code to the client indicating that the server procedure cannot decode the client's arguments. Format #include <rpc/rpc.h> void svcerr_decode(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. 5 Description Called by a service dispatch routine that cannot successfully decode its parameters. See also the svc_getargs routine. 5 Return_Values None 4 svcerr_noproc Sends an error code to the client indicating that the server program does not implement the requested procedure. Format #include <rpc/rpc.h> void svcerr_noproc(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. 5 Description Called by a service dispatch routine that does not implement the procedure number that the client requested. 5 Return_Values None 4 svcerr_noprog Sends an error code to the client indicating that the server program is not registered with the Portmapper. Format #include <rpc/rpc.h> void svcerr_noprog(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. 5 Description Called when the desired program is not registered with the ONC RPC package. Generally, the Portmapper informs the client when a server is not registered. Therefore, service implementors usually do not use this routine. 5 Return_Values None 4 svcerr_progvers Sends an error code to the client indicating that the requested program is registered with the Portmapper but the requested version of the program is not registered. Format #include <rpc/rpc.h> void svcerr_progvers(SVCXPRT *xprt, u_long low_vers, u_long high_vers); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. low_vers The lowest version of the requested program that the server supports. high_vers The highest version of the requested program that the server supports. 5 Description Called when the desired version of a program is not registered with the ONC RPC package. Generally, the Portmapper informs the client when a requested program version is not registered. Therefore, service implementors usually do not use this routine. 5 Return_Values None 4 svcerr_systemerr Sends an error code to the client indicating that the an error occurred that is not handled by the protocol being used. Format #include <rpc/rpc.h> void svcerr_systemerr(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. 5 Description Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. 5 Return_Values None 4 svcerr_weakauth Sends an error code to the client indicating that an authentication error occurred. The authentication information was correct but was insufficient. Format #include <rpc/rpc.h> void svcerr_weakauth(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. 5 Description Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient (but correct) authentication parameters. The routine calls svcerr_auth (xprt, AUTH_TOOWEAK). 5 Return_Values None 4 svcraw_create Creates a server handle for memory-based ONC RPC for simple testing and timing. Format #include <rpc/rpc.h> SVCXPRT *svcraw_create(); 5 Arguments None 5 Description Creates a in-program ONC RPC service transport, to which it returns a pointer. The transport is really a buffer within the process's address space, so the corresponding client should live in the same address space; see the clntraw_create routine. The svcraw_create and clntraw_create routines allow simulation and acquisition of ONC RPC overheads (such as round-trip times), without any kernel interference. 5 Return_Values SVCXPRT * A pointer to an RPC server handle for the in-memory transport. NULL Indicates failure. 4 svcfd_create Creates an RPC server handle using the specified open file descriptor. Format #include <rpc/rpc.h> SVCXPRT *svcfd_create(int fd, u_int sendsize, u_int recvsize); 5 Arguments fd The number of an open file descriptor. sendsize The size of the send buffer. If you specify 0, the routine chooses a suitable default. recvsize The size of the receive buffer. If you specify 0, the routine chooses a suitable default. 5 Description Creates an RPC server handle using the specified TCP socket, to which it returns a pointer. The server should call the svcfd_ create routine after it accepts an incoming TCP connection. 5 Return_Values SVCXPRT * A pointer to the server handle. NULL Indicates failure. 4 svctcp_create Creates an ONC RPC server handle for a TCP/IP connection. Format #include <rpc/rpc.h> SVCXPRT *svctcp_create(int sock, u_int sendsize, u_int recvsize); 5 Arguments sock The socket with which the connection is associated. If sock is RPC_ANYSOCK, then this routine opens a new socket and sets sock. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port. sendsize The size of the send buffer. If you specify 0, the routine chooses a suitable default. recvsize The size of the receive buffer. If you specify 0, the routine chooses a suitable default. 5 Description Creates an RPC server handle using the TCP/IP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls). 5 Return_Values SVCXPRT * A pointer to the server handle. NULL Indicates failure. 4 svcudp_bufcreate Creates an ONC RPC server handle for a buffered I/O UDP connection. Format #include <rpc/rpc.h> SVCXPRT *svcudp_bufcreate(int sock, u_int sendsize, u_int recvsize); 5 Arguments sock The socket with which the connection is associated. If sock is RPC_ANYSOCK, then this routine opens a new socket and sets sock. sendsize The size of the send buffer. If you specify 0, the routine chooses a suitable default. recvsize The size of the receive buffer. If you specify 0, the routine chooses a suitable default. 5 Description Creates an RPC server handle using the UDP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls). 5 Return_Values SVCXPRT * A pointer to the server handle. NULL Indicates failure. 4 svcudp_create Creates an ONC RPC server handle for a non-buffered I/O UDP connection. Format #include <rpc/rpc.h> SVCXPRT *svcudp_create(int sock); 5 Arguments sock The socket with which the connection is associated. If sock is RPC_ANYSOCK, then this routine opens a new socket and sets sock. 5 Description 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. 5 Return_Values SVCXPRT * A pointer to the server handle. NULL Indicates failure. 4 xprt_register Adds a socket associated with an RPC server handle to the list of registered sockets. Format #include <rpc/rpc.h> void xprt_register(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. 5 Description Activation of a transport handle involves setting the most appropriate bit for the socket associated with xprt in the svc_ fds mask. When svc_run() is invoked, activity on the transport handle is eligible to be processed by the server. The svc_register routine calls this routine; therefore, you are unlikely to use this routine directly. 5 Return_Values None 4 xprt_unregister Removes a socket associated with an RPC server handle from the list of registered sockets. Format #include <rpc/rpc.h> void xprt_unregister(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server handle creation routines. 5 Description Removes the socket associated with the indicated handle from the list of registered sockets maintained in the svc_fdset variable. Activity on the socket associated with xprt will no longer be checked by the svc_run routine. The svc_unregister routine calls this routine; therefore, you are unlikely to use this routine directly. 5 Return_Values None 4 _authenticate Authenticates the request message. Format #include <rpc/rpc.h> enum auth_stat _authenticate(struct svc_req *rqst, struct rpc_msg *msg); 5 Arguments rqst A pointer to an svc_req structure with the requested program number, procedure number, version number, and credentials passed by the client. msg A pointer to an rpc_msg structure with members that make up the RPC message. 5 Description Returns AUTH_OK if the message is authenticated successfully. If it returns AUTH_OK, the routine also does the following: o Sets rqst->rq_xprt->verf to the appropriate response verifier. o Sets rqst->rq_client_cred to the "cooked" form of the credentials. The expression rqst->rq_xprt->verf must be preallocated, and its length set appropriately. The program still owns and is responsible for msg->u.cmb.cred and msg->u.cmb.verf. The authentication system retains ownership of rqst->rq_client_cred, the "cooked" credentials. 5 Return_Values enum auth_stat The return status code for the authentication checks: AUTH_OK=0-Authentication checks successful. AUTH_BADCRED=1-Invalid credentials (seal broken) AUTH_REJECTEDCRED=2-Client should begin new session AUTH_BADVERF=3-Invalid verifier (seal broken) AUTH_REJECTEDVERF=4-Verifier expired or was replayed AUTH_TOOWEAK=5-Rejected due to security reasons AUTH_INVALIDRESP=6-Invalid response verifier AUTH_FAILED=7-some unknown reason 3 RPC_XDR_Routines XDR routines specify external data representation. They allow C programmers to describe arbitrary data structures in a system- independent fashion. Important: In order to maintain uniqueness for the OpenVMS HELP utility, some XDR routines have a "_#" appended at the end. Do not use the "_#" when coding the routine in a program. 4 xdr_accepted_reply Serializes and deserializes a message-accepted indication in an RPC reply message. Format #include <ucx$rpcxdr.h> bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply *arp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. arp A pointer to a buffer to which the message-accepted indication is written. 5 Description Used for encoding reply messages. This routine encodes the status of the RPC call and, in the case of success, the call results as well. This routine is useful for users who wish to generate messages without using the ONC RPC package. It returns the message-accepted variant of a reply message union in the arp argument. The xdr_replymsg routine calls this routine. 5 Return_Values TRUE Indicates success. FALSE Indicates failure to encode the message. 4 xdr_array Serializes and deserializes the elements of a variable-length array. Format #include <ucx$rpcxdr.h> bool_t xdr_array(XDR *xdrs, char **arrp, u_int *sizep, u_int maxsize, u_int elsize, xdrproc_t elproc); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. arrp A pointer to the pointer to the array. sizep A pointer to the number of elements in the array. This element count cannot exceed the maxsize parameter. maxsize The maximum size of the sizep parameter. This value is the maximum number of elements that the array can hold. elsize The size, in bytes, of each of the array's elements. elproc The XDR routine to call that handles each element of the array. 5 Description A filter primitive that translates between variable-length arrays and their corresponding external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_authunix_parms Serializes and deserializes credentials in an authentication parameter structure. Format #include <ucx$rpcxdr.h> bool_t xdr_authunix_parms (XDR *xdrs, struct authunix_parms *authp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. authp A pointer to an authunix_parms structure. 5 Description Used for externally describing standard UNIX credentials. On a UCX host this routine encodes the host name, the user ID, and the group ID. It sets the group ID list to NULL. This routine is useful for users who want to generate these credentials without using the ONC RPC authentication package. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_bool Serializes and deserializes boolean data. Format #include <ucx$rpcxdr.h> bool_t xdr_bool (XDR *xdrs, bool_t *bp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. bp A pointer to the boolean data. 5 Description A filter primitive that translates between booleans (integers) and their external representations. When encoding data, this filter produces values of either one or zero. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_bytes Serializes and deserializes a counted byte array. Format #include <ucx$rpcxdr.h> bool_t xdr_bytes (XDR *xdrs, char **bpp, u_int *sizep, u_int maxsize); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. bpp A pointer to a pointer to the byte array. sizep A pointer to the length of the byte array. maxsize The maximum size of the length of the byte array. 5 Description A filter primitive that translates between a variable-length byte array and its external representation. The length of the array is located at sizep; the array cannot be longer than maxsize. If *bpp is NULL, xdr_bytes allocates maxsize bytes. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_callhdr Serializes and deserializes the static part of a call message header. Format #include <ucx$rpcxdr.h> bool_t xdr_callhdr(XDR *xdrs, struct rpc_msg *chdrp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. chdrp A pointer to the call header data. 5 Description Describes call header messages. This routine is useful for users who want to generate messages without using the ONC RPC package. The xdr_callhdr routine encodes the following fields: transaction ID, direction, RPC version, server program number, and server version. 5 Return_Values TRUE Indicate success. FALSE Indicates failure. 4 xdr_callmsg Serializes and deserializes an ONC RPC call message. Format #include <ucx$rpcxdr.h> bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsgp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. cmsgp A pointer to an rpc_msg structure that describes the RPC call message. 5 Description This routine is useful for users who want to generate messages without using the ONC RPC package. The xdr_callmsg routine encodes the following fields: transaction ID, direction, RPC version, server program number, server version number, server procedure number, and client authentication. The pmap_rmtcall and svc_sendreply routines call xdr_callmsg. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_char Serializes and deserializes character data. Format #include <ucx$rpcxdr.h> bool_t xdr_char(XDR *xdrs, char *cp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. cp A pointer to a character. 5 Description A filter primitive that translates between internal representations of characters and their XDR representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_double Serializes and deserializes VAX and IEEE double-precision floating-point numbers. Format #include <ucx$rpcxdr.h> bool_t xdr_double(XDR *xdrs, double *dp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. dp A pointer to the double-precision floating-point number. 5 Description A filter primitive that translates between double-precision numbers and their external representations. This routine is actually implemented by four XDR routines: xdr_ converts VAX D-format floating-point numbers double_D xdr_ converts VAX G-format floating-point numbers double_G xdr_ converts IEEE T-format floating-point numbers double_T xdr_ converts IEEE X-format floating-point numbers double_X You can reference these routines explicitly or you can use compiler settings to control which routine is used when you reference the xdr_double routine. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_enum Serializes and deserializes enumerations. Format #include <ucx$rpcxdr.h> bool_t xdr_enum(XDR *xdrs, enum_t *ep); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. ep A pointer to the enumeration data. 5 Description A filter primitive that translates between enumerations (actually integers) and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_float Serializes and deserializes VAX and IEEE single-precision floating-point numbers. Format #include <ucx$rpcxdr.h> bool_t xdr_float(XDR *xdrs, float *fp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. fp A pointer to a single-precision floating-point number. 5 Description A filter primitive that translates between single-precision floating-point numbers and their external representations. This routine is actually implemented by two XDR routines: xdr_ converts VAX F-format floating-point numbers float_F xdr_ converts IEEE T-format floating-point numbers float_S You can reference these routines explicitly or you can use compiler settings to control which routine is used when you reference the xdr_float routine. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_free Deallocates the memory associated with the indicated data structure. Format #include <ucx$rpcxdr.h> bool_t xdr_free(xdrproc_t proc, char *objp); 5 Arguments proc The XDR routine for the data structure being freed. objp A pointer to the data structure to be freed. 5 Description Releases memory allocated for the data structure to which objp points. The pointer passed to this routine is not freed, but what it points to is freed (recursively). Use this routine to free decoded data that is no longer needed. Never use this routine for encoded data. 5 Return_Values TRUE Indicate success. FALSE Indicates failure. 4 xdr_hyper Serializes and deserializes VAX quadwords (known in XDR as hyper- integers). Format #include <ucx$rpcxdr.h> bool_t xdr_hyper(XDR *xdrs, quad *hp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. hp A pointer to the hyper-integer data. 5 Description A filter primitive that translates between hyper-integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_int Serializes and deserializes integers. Format #include <ucx$rpcxdr.h> bool_t xdr_int(XDR *xdrs, int *ip); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. ip A pointer to the integer data. 5 Description A filter primitive that translates between integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_long Serializes and deserializes long integers. Format #include <ucx$rpcxdr.h> bool_t xdr_long(XDR *xdrs, long *lp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. lp A pointer to a long integer. 5 Description A filter primitive that translates between long integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_opaque Serializes and deserializes opaque structures. Format #include <ucx$rpcxdr.h> bool_t xdr_opaque(XDR *xdrs, char *op, u_int cnt); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. op A pointer to the opaque data. cnt The size of op in bytes. 5 Description A filter primitive that translates between fixed-size opaque data and its external representation. This routine treats the data as a fixed length of bytes and does not attempt to convert the bytes. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_opaque_auth Serializes and deserializes ONC RPC authentication information message. Format #include <ucx$rpcxdr.h> bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *authp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. authp A pointer to an opaque_auth structure describing authentication information. The pointer should reference data created by the authnone_create, authunix_create, or authunix_create_default routine. 5 Description Translates ONC RPC authentication information messages. This routine is useful for users who want to generate messages without using the ONC RPC package. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_pmap_# Serializes and deserializes Portmapper parameters. Format #include <ucx$rpcxdr.h> bool_t xdr_pmap(XDR *xdrs, struct pmap *regs); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. regs A pointer to the pmap structure. This structure contains the program number, version number, protocol number, and port number. 5 Description Describes parameters to various Portmapper procedures, externally. This routine is useful for users who want to generate these parameters without using the Portmapper interface. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_pmap_vms Serializes and deserializes OpenVMS-specific Portmapper parameters. Format #include <ucx$rpcxdr.h> bool_t xdr_pmap_vms(XDR *xdrs, struct pmap_vms *regs); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. regs A pointer to the pmap_vms structure. This structure contains the program number, version number, protocol number, port number and the OpenVMS-specific process identification. 5 Description This routine is similar to xdr_pmap(), except it also includes the process identification in the pmap_vms structure. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_pmaplist_# Serializes and deserializes a list of Portmapper port mappings. Format #include <ucx$rpcxdr.h> bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rpp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. rpp A pointer to a pointer to a pmaplist structure containing a list of Portmapper programs and their respective information. If the routine is used to decode a Portmapper listing, it sets rpp to the address of a newly-allocated linked list of pmaplist structures. 5 Description Describes a list of port mappings, externally. This routine is useful for users who want to generate these parameters without using the Portmapper interface. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_pmaplist_vms Serializes and deserializes a list of Portmapper port mappings for OpenVMS systems. Format #include <ucx$rpcxdr.h> bool_t xdr_pmaplist_vms (XDR *xdrs, struct pmaplist_vms **rpp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. rpp A pointer to a pointer to a pmaplist_vms structure containing a list of Portmapper programs and their respective information, including OpenVMS-specific information. 5 Description This routine is similar to the xdr_pmaplist routine, except it also includes the process identification in the pmaplist_vms structure. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_pointer Serializes and deserializes indirect pointers and the data being pointed to. Format #include <ucx$rpcxdr.h> bool_t xdr_pointer(XDR *xdrs, char **objpp, u_int objsize, xdrproc_t objproc); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. objpp A pointer to a pointer to the data being converted. objsize The size of the data structure in bytes. objproc The XDR procedure that filters the structure between its local form and its external representation. 5 Description An XDR routine for translating data structures that contain pointers to other structures, such as a linked list. The xdr_ pointer routine is similar to the xdr_reference routine. The differences are that the xdr_pointer routine handles pointers with the value NULL and that it translates the pointer values to a boolean. If the boolean is TRUE, the data follows the boolean. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_reference Serializes and deserializes indirect pointers and the data being pointed to. Format #include <ucx$rpcxdr.h> bool_t xdr_reference(XDR *xdrs, char **objpp, u_int objsize, xdrproc_t objproc); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. objpp A pointer to a pointer to the structure containing the data being converted. If objpp is zero, the xdr_reference routine allocates the necessary storage when decoding. This argument must be non- zero during encoding. objsize The size of the structure in bytes. objproc The XDR procedure that filters the structure between its local form and its external representation. 5 Description A primitive that provides pointer chasing within structures. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_rejected_reply Serializes and deserializes the remainder of an RPC reply message after the header indicates that the reply is rejected. Format #include <ucx$rpcxdr.h> bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply *rrp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. rrp A pointer to the rejected_reply structure describing the rejected-reply message. 5 Description Describes ONC RPC reply messages. This routine is useful for users who want to generate messages without using the ONC RPC package. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_replymsg Serializes and deserializes the RPC reply header and then calls the appropriate routine to interpret the rest of the message. Format #include <ucx$rpcxdr.h> bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsgp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. rmsgp A pointer to the rpc_msg structure describing the reply message. 5 Description Describes ONC RPC reply messages. This routine is useful for users who want to generate messages without using the ONC RPC package. This routine interprets the message header and then calls either the xdr_accepted_reply or the xdr_rejected_reply routine to interpret the body of the RPC message. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_short Serializes and deserializes short integers. Format #include <ucx$rpcxdr.h> bool_t xdr_short(XDR *xdrs, short *sp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. sp A pointer to a short integer. 5 Description A filter primitive that translates between short integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_string Serializes and deserializes strings (arrays of bytes terminated by a NULL character). Format #include <ucx$rpcxdr.h> bool_t xdr_string(XDR *xdrs, char **spp, u_int maxsize); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. spp A pointer to a pointer to a character string. maxsize The maximum size of the string. 5 Description A filter primitive that translates between strings and their corresponding external representations. Strings cannot be longer than the value specified with the maxsize parameter. While decoding, if *spp is NULL, this routine allocates the necessary storage to hold the NULL-terminated string and sets *spp to point to the allocated storage. This routine is the same as the xdr_wrapstring routine, except that this routine allows you to specify maxsize. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_u_char Serializes and deserializes unsigned characters. Format #include <ucx$rpcxdr.h> bool_t xdr_u_char(XDR *xdrs, char *ucp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. ucp A pointer to a character. 5 Description A filter primitive that translates between internal representation of unsigned characters and their XDR representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_u_hyper Serializes and deserializes unsigned VAX quadwords (known in XDR as hyper-integers). Format #include <ucx$rpcxdr.h> bool_t xdr_u_hyper(XDR *xdrs, unsigned quad *uhp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. uhp A pointer to the unsigned hyper-integer. 5 Description A filter primitive that translates between unsigned hyper- integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_u_int Serializes and deserializes unsigned integers. Format #include <ucx$rpcxdr.h> bool_t xdr_u_int(XDR *xdrs, unsigned *uip); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. uip A pointer to the unsigned integer. 5 Description A filter primitive that translates between unsigned integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_u_long Serializes and deserializes unsigned long integers. Format #include <ucx$rpcxdr.h> bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. ulp A pointer to the unsigned long integer. 5 Description A filter primitive that translates between unsigned long integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_u_short Serializes and deserializes unsigned short integers. Format #include <ucx$rpcxdr.h> bool_t xdr_u_short(XDR *xdrs, unsigned short *usp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. usp A pointer to the unsigned short integer. 5 Description A filter primitive that translates between unsigned short integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_union Serializes and deserializes discriminant unions. Format #include <ucx$rpcxdr.h> bool_t xdr_union(XDR *xdrs, enum *dscmp, char *unp, struct xdr_discrim *choices, xdrproc_t default); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. dscmp A pointer to the union's discriminant. unp A pointer to the union's data. choices A pointer to an array of xdr_discrim structures. Each structure contains an ordered pair of [value,proc]. The final structure in the array is denoted by a pointer with the value NULL. default The address of the default XDR routine to call if the dscmp argument is not found in the choices array. 5 Description A filter primitive that translates between a discriminated union and its corresponding external representation. The xdr_union routine first translates the discriminant of the union located at dscmp. This discriminant is always of type enum_t. Next, the routine translates the union data located at unp. To translate the union data the xdr_union routine first searches the structure pointed to by the choices argument for the union discriminant passed in the dscmp argument. If a match is found, the xdr_union routine calls proc to translate the union data. The end of the xdr_discrim structure array must contain an entry with the value NULL for proc. If the xdr_union routine reaches this entry before finding a match, the routine calls the default procedure (if it is not NULL). 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_vector Serializes and deserializes the elements of a fixed-length array (known as a vector). Format #include <ucx$rpcxdr.h> bool_t xdr_vector(XDR *xdrs, char **vecpp, u_int elnum, u_int elsize, xdrproc_t elproc); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. vecpp A pointer to a pointer to the array. elnum The number of elements in the array. elsize The size, in bytes, of each element. elproc The XDR routine to handle each element. 5 Description A routine that calls elproc to prepare the elements of an array for XDR messages. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_void When there is no data to convert, this routine is passed to ONC RPC routines that require an XDR procedure parameter. Format #include <ucx$rpcxdr.h> bool_t xdr_void(); 5 Description This routine is used as a placeholder for a program that passes no data in a remote procedure call. Most client and server routines expect an XDR routine to be called, even when there is no data to pass. 5 Return_Values This routine always returns TRUE. 4 xdr_wrapstring Serializes and deserializes NULL-terminated strings. Format #include <ucx$rpcxdr.h> bool_t xdr_wrapstring(XDR *xdrs, char **spp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. spp A pointer to a pointer to a string. 5 Description A primitive that calls xdr_string(xdrs, sp, MAXUNSIGNED); where MAXUNSIGNED is the maximum value of an unsigned integer. This routine is useful because the ONC RPC client and server routines pass the XDR stream handle and a single pointer as parameters to any referenced XDR routines. The xdr_string routine, one of the most frequently used ONC RPC primitives, requires three parameters. While decoding, if *sp is NULL, the necessary storage is allocated to hold the null-terminated string and *sp is set to point to it. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdrmem_create Initializes an XDR stream descriptor for a memory buffer. Format #include <ucx$rpcxdr.h> void xdrmem_create(XDR *xdrs, char *addr, u_int size, enum xdr_op op); 5 Arguments xdrs A pointer to the XDR stream handle being created. The routine xdrmem_create fills in xdrs with encoding and decoding information. addr A pointer to the memory buffer. size The length of the memory buffer. op An XDR operation, one of: XDR_ENCODE, XDR_DECODE, and XDR_FREE. 5 Description The stream handle xdrs is initialized with the operation op, the buffer addr and size, and the operations context for an xdrmem stream. 5 Return_Values None 4 xdrrec_create Initializes a record-oriented XDR stream descriptor. Format #include <ucx$rpcxdr.h> void xdrrec_create(XDR *xdrs, u_int sendsize, u_int recvsize, char *tcp_handle, int (*readit)(), int (*writeit)()); 5 Arguments xdrs A pointer to the XDR stream handle being created. The routine xdrrec_create fills in xdrs with encoding and decoding information. sendsize The send buffer size. recvsize The receive buffer size. tcp_handle A pointer to an opaque handle that is passed as the first parameter to the procedures (*readit)() and (*writeit)(). (*readit)() Read procedure that takes the opaque handle tcp_handle. The routine must use the following format: int readit(char *tcp_handle, char *buffer, u_long len) where tcp_handle is the client or server handle, buffer is the buffer to fill, and len is the number of bytes to read. The readit routine should return either the number of bytes read or the value -1 if an error occurs. (*writeit)() Write procedure that takes the opaque handle tcp_handle. The routine must use the following format: int writeit(char *tcp_handle, char *buffer, u_long len) where tcp_handle is the client or server handle, buffer is the buffer to write, and len is the number of bytes to write. The readit routine should return either the number of bytes written or the value -1 if an error occurs. 5 Description The stream descriptor for xdrs initializes the maximum allowable size for a request recvsize and reply sendsize, the addresses of the routine to perform the read (readit) and write (writeit), and the TCP handle used for network I/O. 5 Return_Values None 4 xdrrec_endofrecord Generates an end-of-record for an XDR record. Format #include <ucx$rpcxdr.h> bool_t xdrrec_endofrecord (XDR *xdrs, bool_t sendnow); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. sendnow Indicates whether the record should be sent. If sendnow is TRUE, xdrrec_endofrecord sends the record by calling the writeit routine specified in the call to xdrrec_create. If sendnow is FALSE, xdrrec_endofrecord marks the end of the record and calls writeit when the buffer is full. 5 Description This routine lets an application support batch calls and pipelined procedure calls. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdrrec_eof Moves the buffer pointer to the end of the current record and returns an indication if any more data exists in the buffer. Format #include <ucx$rpcxdr.h> bool_t xdrrec_eof (XDR *xdrs); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. 5 Description Returns TRUE if there is no more input in the buffer after consuming the rest of the current record. 5 Return_Values TRUE Indicates no more input in the buffer. FALSE Indicates more input in the buffer. 4 xdrrec_skiprecord Guarantees proper record alignment during deserialization from an incoming stream. Format #include <ucx$rpcxdr.h> bool_t xdrrec_skiprecord (XDR *xdrs); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream handle creation routines. 5 Description This routine ensures that the stream is properly aligned in preparation for a subsequent read. It is recommended that when a record stream is being used, this routine is called prior to any operations that would read from the stream. This routine is similar to the xdrrec_eof routine, except that this routine does not verify if there is more data in the buffer. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdrstdio_create Initializes a stdio XDR stream. Format #include <ucx$rpcxdr.h> void xdrstdio_create (XDR *xdrs, FILE *file, enum xdr_op op); 5 Arguments xdrs A pointer to the XDR stream handle being created. The routine xdrstdio_create fills in xdrs with encoding and decoding information.. file A pointer to the FILE structure that is to be associated with the stream. op An XDR operation, one of: XDR_ENCODE, XDR_DECODE, and XDR_FREE. 5 Description Initializes a stdio stream for the specified file. 5 Return_Values None 3 System_Services_Routines System Services routines let you write internet programs. The $QIO service routine uses internet I/O function codes. 4 $ASSIGN The Assign I/O Channel service provides a calling process with an I/O channel. This makes it possible for the calling process to do I/O operations on the internet pseudodevice. Format SYS$ASSIGN devnam, chan, [acmode], [mbxnam] Returns OpenVMS usage:longword (unsigned) type: write only access: by value mechanism: 0 Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned. 5 Arguments devnam OpenVMS usage:device_name type: character-coded text string access: read only mechanism: by fixed-length string descriptor Name of the device to which $ASSIGN is to assign a channel. The devnam argument specifies the address of a character string descriptor pointing to the pseudodevice name string. The character string contains UCX$DEVICE:. chan OpenVMS usage:channel type: word (unsigned) access: write only mechanism: by reference Number of the channel that is assigned. The chan argument is the address of a word into which $ASSIGN writes the channel number. acmode OpenVMS usage:access_mode type: longword (unsigned) access: read only mechanism: by value Access mode to be associated with the channel. The acmode argument specifies the access mode. I/O operations on the channel can be performed only from equal and more privileged access modes. mbxnam OpenVMS usage:device_name type: character-coded text string access: read only mechanism: by descriptor-fixed length string descriptor This argument is not used. 5 Description The $ASSIGN system service establishes a path to a device but does not check whether the calling process has the capability to do I/O operations to the device. The device drivers may apply privilege and protection restrictions. The calling process must have NETMBX privilege to assign a channel. System dynamic memory is required for the target device and the I/O byte-limit quota from the process buffer is used. When a channel is assigned to UCX$DEVICE:, the internet software creates a new pseudodevice called BGn, where n is a unique unit number. The corresponding channel number is used in any subsequent operation requests for that device. Channels remain assigned either until they are explicitly deassigned with the Deassign I/O Channel ($DASSGN) service, or, if they are user-mode channels, until the image that assigned the channel exits. Two programming examples for the $ASSIGN routine follow this command description. $ASSIGN System Service (MACRO-32) uses the MACRO-32 programming language and $ASSIGN System Service (C Programming) uses the C programming language. 5 Condition_Values_Returned SS$_NORMAL Service successfully completed. SS$_ACCVIO The caller cannot read the device string or string descriptor, or the caller cannot write the channel number. SS$_DEVALLOC The device is allocated to another process. SS$_EXQUOTA The process has exceeded its buffered I/O byte limit (BIOLM) quota. SS$_IVDEVNAM No device name was specified, the logical name translation failed, or the device name string contains invalid characters. SS$_IVLOGNAM The device name string has a length of zero or has more than 63 characters. SS$_NOIOCHAN No I/O channel is available for assignment. SS$_NOSUCHDEV This warning code indicates that the specified device does not exist. Example .titleASAssignystem Service (MACRO-32) .ident /01/ $inetsymdef ; INET symbols dev: .ascid /ucx$device:/ ; INET device name channel: .word 0 ; INET channel .entry start,^m<> ; ; Assign an INET device ; $assign_s devnam=dev, chan=channel . . . .end start #module assgn_chanGN System Service (C Programming) /* **++ ** ** This example assigns a channel to INET device ** using system service SYS$ASSIGN ** **-- */ /* ** INCLUDE FILES */ #include <descrip.h> assgn_chan(channel) unsigned short ; /* INET channel */ { int status ; /* For return status */ /* Descriptor for Inet device name */ $DESCRIPTOR (dev, "UCX$DEVICE:"); /* ** Assign a channel to INET device */ status = SYS$ASSIGN( &dev, &channel, 0, 0) ; if ((status & 1) == 0) { printf("Failed to assign channel to INET device \n") ; return(status) ; } return(status) ; /* ** channel will have the assigned ** channel number */ } 4 $CANCEL This routine cancels all pending I/O requests on a specified channel. The equivalent C Socket call is the close() routine. Format SYS$CANCEL chan Returns OpenVMS usage:longword (unsigned) type: write only access: by value mechanism: 0 Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned. 5 Arguments chan OpenVMS usage:channel type: word (unsigned) access: read only mechanism: by value The channel on which the routine cancels the I/O. The chan argument is a word containing the channel number. 5 Description To cancel I/O on a channel, the access mode of the calling process must be equal to or more privileged than the access mode of the process that made the original channel assignment. The $CANCEL service requires system dynamic memory and uses the process's buffered I/O limit (BIOLM) quota. Two programming examples for the $CANCEL routine follow this command description. $CANCEL System Service (MACRO-32) uses the MACRO-32 programming language and $CANCEL System Service (C Programming) uses the C programming language. When a request currently in progress is canceled, the driver is notified immediately. Actual cancellation may or may not occur immediately, depending on the logical state of the driver. When cancellation does occur, the action taken for I/O in progress is similar to that taken for queued requests. For example: 1. The specified event flag is set. 2. The first word of the IOSB of the I/O request you are canceling is set to SS$_CANCEL if the I/O request is queued or to SS$_ABORT if the I/O operation is in progress. 3. If the asynchronous system trap (AST) is specified, it is queued. For proper synchronization between this service and the actual canceling of I/O requests to take place, the issuing process must wait for the I/O process to complete normally. Note that the I/O has been canceled. Outstanding I/O requests are canceled automatically at image exit. 5 Condition_Values_Returned SS$_NORMAL Service successfully completed. SS$_ABORT A physical line went down during a network connect operation. SS$_CANCEL Warning code. The I/O operation was canceled by executing a $CANCEL system service. SS$_EXQUOTA The process has exceeded its buffered I/O limit (BIOLM) quota. SS$_INSFMEM Insufficient system dynamic memory is available to cancel the I/O. SS$_IVCHAN An invalid channel was specified (that is, a channel number of zero or a number larger than the number of channels available). SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode. Example 1-3 $CANCEL System Service (MACRO-32) .title Cancel .ident /01/ $inetsymdef ; INET symbols dev: .ascid /ucx$device:/ ; INET device name channel: .word 0 ; INET channel .entry start,^m<> ; ; Assign an INET device ; . . . ; ; Cancel I/O on INET device ; $cancel_s chan=channel . . . .end start #module cancel_ioCEL System Service (C Programming) /* **++ ** ** This example cancels all pending I/O requests on the ** specified channel using system service SYS$CANCEL ** **-- */ /* ** INCLUDE FILES */ cancel_io(chan) short chan ; /* INET channel on which I/O is to be canceled */ { int status ; /* For return status */ /* ** Cancel the pending I/Os */ (status = SYS$CANCEL(chan)) ; if ((status & 1) == 0) { printf("Failed to cancel pending I/Os \n") ; return(status) ; } return(status) ; } 4 $DASSGN This service deassigns (releases) an I/O channel that was acquired using the Assign I/O Channel ($ASSIGN) service. The equivalent C Socket call is the close() routine. Format SYS$DASSGN chan Returns OpenVMS usage:longword (unsigned) type: read/write access: by value mechanism: 0 Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned. 5 Arguments chan OpenVMS usage:channel type: word (unsigned) access: read only mechanism: by value Number of the I/O channel to be deassigned. The chan argument is a word containing this number. 5 Description After all communication is completed, use the $DASSGN system service to free an I/O channel. A $DASSGN operation issued on a channel associated with an internet pseudodevice does the following: 1. Ends all pending operations to send or receive data at $QIO level ($CANCEL system service). 2. Clears the port associated with the channel. When issuing the $DASSGN system service for TCP/IP sockets, the socket remains until the connection is closed on both sides, local and remote. 3. Ends all communications with the internet pseudodevice that the I/O channel identifies. 4. Frees the channel associated with the internet pseudodevice. An I/O channel can be deassigned only from an access mode equal to or more privileged than the access mode from which the original channel assignment was made. I/O channels assigned from user mode are automatically deassigned at image exit. Two programming examples for the $DASSGN routine follow this command description. $DASSGN System Service (MACRO-32) uses the MACRO-32 programming language and $DASSGN System Service (C Programming) uses the C programming language. NOTE Even after a $DASSGN has been issued, a TCP socket may remain until the TCP close timeout interval expires. The default and maximum timeout interval is 10 minutes if the peer host is not responding or 30 seconds after acknowledging the socket close. Although, the TCP socket is open, you cannot make reference to that socket after issuing a $DASSGN. 5 Condition_Values_Returned SS$_NORMAL Service successfully completed. SS$_IVCHAN An invalid channel number was specified (that is, a channel number of zero or a number larger than the number of channels available). SS$_NOPRIV The specified channel is not assigned, or is assigned from a more privileged access mode. Example 1-5 $DASSGN System Service (MACRO-32) .title Dassign .ident /01/ $inetsymdef ; INET symbols exit purge : .ascid /ucx$device:/ ; INET device name channel: .word 0 ; INET channel .entry start,^m<> . . . ; ; Deassign an INET device ; $Dassgn_s chan=channel . . . .end start #module dassgn_chanN System Service (C Programming) /* **++ ** ** This example deassigns the specified channel ** using system service SYS$DASSNG ** **-- */ /* ** INCLUDE FILES */ dassgn_chan(chan) short chan ; /* INET channel which is to be deassigned */ { int status ; /* For return status */ /* ** Deassign the channel */ status = SYS$DASSGN(chan) ; if ((status & 1) == 0) { printf("Failed to deassign the channel\n") ; return(status) ; } return(status) ; } 4 $GETDVI This service returns information about primary and secondary device characteristics of the internet pseudodevice. The $GETDVI service is completed asynchronously. It returns to the caller after queuing the information request without waiting for the requested information to be returned. For synchronous completion, use the Get Device/Volume Information and Wait ($GETDVIW) service. The $GETDVIW service is identical to the $GETDVI service except that $GETDVIW returns to the caller with the requested information. The equivalent C Socket calls are the getpeername(), getsockname(), and getsockopt() routines. Format SYS$GETDVI [efn],[chan], [devnam],itmlst,[iosb],[astadr], [astprm],[nullarg] Returns OpenVMS usage:longword (unsigned) type: write only access: by value mechanism: 0 Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned. 5 Arguments efn OpenVMS usage:ef_number type: longword (unsigned) access: read only mechanism: by value Number of the event flag to be set when $GETDVI returns the requested information. The efn argument is a longword containing this number. When the request is initiated, $GETDVI clears the specified event flag (or event flag 0 if efn was not specified). When $GETDVI returns the requested information, it sets the specified event flag (or event flag 0). chan OpenVMS usage:channel type: word (unsigned) access: read only mechanism: by value Number of the I/O channel assigned to the device about which information is desired. The chan argument is a word containing this number. devnam OpenVMS usage:device_name type: character-coded text string access: read only mechanism: by descriptor-fixed-length string descriptor The name of the device for which $GETDVI returns information. The devnam argument is the address of a character string descriptor pointing to the name string. The device name string can be either a physical device name or a logical name. If the first character in the string is an underscore (_), the string is considered a physical device name. Otherwise, the string is considered to be a logical name. In that case, logical name translation is done until either a physical device name is found or the system default for number of translations has been reached. If the device name string contains a colon, the colon and the characters that follow it are ignored. To identify a device to $GETDVI, specify either the chan argument or the devnam argument, but not both. If both arguments are specified, the chan argument is used. If neither chan nor devnam is specified, $GETDVI uses a default value of zero for chan. itmlst OpenVMS usage:item_list type: longword (unsigned) access: read only mechanism: by reference Item list specifying which information about the device is to be returned. The itmlst argument is the address of a list of item descriptors, each of which describes an item of information. The list of item descriptors is terminated by a length and item code of zero. Single Item Descriptor depicts the format of an item descriptor. $GETDVI Item Descriptor Fields buffer-length A word containing a user-supplied integer specifying the length (in bytes) of the buffer for which the $GETDVI returns information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer-length is too small, $GETDVI truncates the data. item-code A word containing a user-supplied symbolic code that specifies the information that $GETDVI returns. These codes are defined by the $DVIDEF macro, which is defined in SYS$LIBRARY:STARLET.MLB for the MACRO-32 language and SYS$LIBRARY:DVIDEF.H for the C language. Each item code is listed in the $GETDVI Item Code Descriptions. buffer-address A longword containing the user-supplied address of a word in which the length of the information (in bytes) is returned. return-length-address A longword containing the user-supplied address of a word in which $GETDVI writes the length of the information it returned (in bytes). $GETDVI Item Codes Table 1-1 $GETDVI Item Code Descriptions Item Code Description DVI$_ A 4-byte hexadecimal number. The DVI$_ACP_TCP symbol ACPTYPE defines the ACP type code that $GETDVI can return. This symbol is defined in the UCX$INETDEF symbol definition file. DVI$_ Returns device-independent characteristics as a 4- DEVCHAR byte vector. Each characteristic is represented by a bit. When $GETDVI sets a bit, the device has the corresponding characteristic. Each bit in the vector has a symbolic name. These symbolic names are defined by the $DEVDEF macro, and are listed in Symbolic Names for $GETDVI. Table 1-2 Symbolic Names for $GETDVI Symbol Device Type DVI$_NET Network device DVI$_AVL Available DVI$_MNT Mounted DVI$_IDV Input device DVI$_ODV Output device DVI$_STS When DVI$_STS is specified, $GETDVI returns the device unit status as a 4-byte vector. Each bit in the vector, when set, corresponds to a symbolic name that is defined by the $UCBDEF macro. These symbols are defined in Device Unit Status Symbolic Names. Table 1-3 Device Unit Status Symbolic Names Symbol Device Type UCB$M_ONLINE Online UCB$M_TEMPLATE Template iosb OpenVMS usage:io_status_block type: quadword (unsigned) access: write only mechanism: by reference The iosb argument signifies the I/O status block that receives the final completion status code. The iosb is the address of the quadword I/O status block. When the iosb argument is specified, $GETDVI sets the quadword to zero when the request is initiated. When the request is completed, a condition value is returned to the first longword. The second longword is reserved for DIGITAL. Although the iosb argument is optional, DIGITAL strongly recommends that you specify it for the following reasons: o If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value. This allows you to be sure that the event flag was not set by an event other than service completion. o If you are using the $SYNCH system service to synchronize the completion of the service, you must use iosb as an argument. The iosb argument is required for $SYNCH. o The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $GETDVI service. The condition value returned in R0 gives you information about the success or failure of the service call itself. The condition value returned in the I/O status block gives you information about the success or failure of the service operation. Therefore, to accurately assess the success or failure of the call to $GETDVI, you must check the condition values returned in both R0 and the I/O status block. astadr OpenVMS usage:ast_procedure type: procedure entry mask access: call without stack unwinding mechanism: by reference AST service routine to be executed when $GETDVI is completed. The astadr argument is the address of the entry mask of this routine. If astadr is specified, the AST routine executes at the same access mode as the caller of the $GETDVI service. astprm OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value AST parameter to be passed to the AST service routine specified by the astadr argument. The astprm argument contains a longword parameter value. nullarg OpenVMS usage:null_arg type: quadword (unsigned) access: read only mechanism: by reference Place-holding argument. This argument is reserved for DIGITAL. 5 Description The chan argument can be used only if the channel has already been assigned and the caller's access mode is equal to or more privileged than the access mode from which the original channel assignment was made. The $GETDVI system service does not need to have a channel assigned to the device about which information is desired. The $GETDVI system service returns information about both primary and secondary characteristics of the device. By default, $GETDVI returns information about the primary characteristics only. To obtain information about secondary device characteristics, the item code specifying the information desired must be merged (ORed) with the code DVI$M_SECONDARY. Information about primary and secondary devices can be obtained in a single call to $GETDVI. In most cases, the two sets of characteristics (primary and secondary) returned by $GETDVI are identical. However, the two sets provide different information in the following cases: o If the device has an associated mailbox, the primary characteristics are those of the assigned device and the secondary characteristics are those of the associated mailbox. o If the device represents a logical link on the network, the secondary characteristics contain information about the link. Unless otherwise stated in the item code description, $GETDVI returns information about the local node only. 5 Condition_Values_Returned SS$_NORMAL Service successfully completed. SS$_ACCVIO The device name string descriptor, device name string, or itmlst argument cannot be read or the buffer or return length longword cannot be written by the caller. SS$_BADPARAM The item list contains an invalid item code, or the return length address field in an item descriptor specifies less than 4 bytes for the return length information. SS$_EXASTLM The process has exceeded its AST limit quota. SS$_IVCHAN An invalid channel number was specified (that is, a channel number of zero or a number greater than the number of channels). SS$_IVDEVNAM The device name string contains invalid characters or neither the devnam nor the chan arguments was specified. SS$_IVLOGNAM The device name string has either a length of zero or more than 63 characters. SS$_NONLOCAL This warning code indicates that the device is on a remote system. SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode. SS$_NOSUCHDEV This warning code indicates that the specified device does not exist on the host system. 4 $QIO This service queues an I/O request to a channel associated with an internet pseudodevice. The $QIO service is completed asynchronously, which means it returns to the caller immediately after queuing the I/O request, without waiting for the I/O operation to be completed. For synchronous completion, use the Queue I/O Request and Wait ($QIOW) service. The $QIOW service is identical to the $QIO service, except the $QIOW returns to the caller after the I/O operation has been completed. The equivalent C Socket calls are the bind() and listen() routines. Format SYS$QIO [efn],chan,func, [iosb],[astadr],[astprm],[p1], [p2],[p3],[p4],[p5], [p6] Returns OpenVMS usage:longword (unsigned) type: write only access: by value mechanism: 0 Longword condition value. All system services return (by immediate value) a condition value in R0. 5 Arguments efn OpenVMS usage:ef_number type: longword (unsigned) access: read only mechanism: by value Event flag that $QIO sets when the I/O operation is completed. The efn argument is a longword value containing the number of the event flag. If efn is not specified, event flag 0 is set. The specified event flag is set if the service terminates without queuing an I/O request. chan OpenVMS usage:channel type: word (unsigned) access: read only mechanism: by value I/O channel that is assigned to the device to which the request is directed. The chan argument is a word value containing the number of the I/O channel. func OpenVMS usage:function_code type: word (unsigned) access: read only mechanism: by value Function codes and function modifiers specify the operation of the software. The func argument is a longword value containing the function code. Refer to the Internet I/O Function Codes for complete information about the function codes and function modifiers. iosb OpenVMS usage:io_status_block type: quadword (unsigned) access: write only mechanism: by reference I/O status block to receive the final completion status of the I/O operation. The iosb is the address of the quadword I/O status block. When the $QIO begins executing, the event flag clears. The $QIO also clears the quadword I/O status block if the iosb argument is specified. Although the iosb argument is optional, DIGITAL strongly recommends that you specify it for the following reasons: - If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value. This assures that the event flag was not set by an event other than service completion. - If you are using the OpenVMS $SYNCH service to synchronize service completion, the I/O status block is a required argument for $SYNCH. - The condition values returned in the R0 and those returned in the I/O status block provide information about different aspects of the call to the $QIO service. The condition value returned in R0 gives you information about the success or failure of the service call itself. The condition values returned in the I/O status block report the success or failure of the service operation. Therefore, to access the success or failure of the $QIO call, check the condition values returned in both the R0 and the I/O status block. astadr OpenVMS usage:ast_procedure type: procedure entry mask access: call without stack unwinding mechanism: by reference AST service routine to be executed when the I/O is completed. The astadr argument is the address of the entry mask to the AST routine. The AST routine executes at the access mode of the caller of $QIO. astprm OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value AST parameter to be passed to the AST service routine. The astprm argument is a longword value of the AST parameter. p1 to p6 OpenVMS usage:varying_arg type: longword (unsigned) access: read only mechanism: by reference, by value, or descriptor Optional device- and function-specific I/O request arguments. The parameter values contained in these arguments vary according to the function for which they are used. See Internet I/O Function Codes for the descriptions of internet I/O function codes. 5 Description $QIO operates only on assigned I/O channels and only from access modes that are equal to or more privileged than the access mode from which the original channel assignment was made. For TCP/IP, $QIO uses the following system resources: o The process's AST limit (ASTLM) quota, if an AST service routine is specified. o System dynamic memory, which is required to queue the I/O request. System dynamic memory requirements are protocol specific. o Additional memory may be required on a device-dependent basis. For $QIO, completion can be synchronized as follows: o By specifying the astadr argument to have an AST routine execute when the I/O is completed. o By calling the $SYNCH Synchronize service to await completion of the I/O operation. (If you want your I/O operation to complete synchronously, use the $QIOW system service instead.) 5 Condition_Values_Returned Each function used with $QIO has its own error codes. See the error codes listed under the individual internet I/O function code descriptions that comprise the remainder of this chapter. 5 Internet_I/O_Function_Codes The internet pseudodevice allows physical, logical, and virtual block I/O functions. The physical and logical functions are used only with the IP layer. Internet I/O Function Codes lists the basic functions and their modifiers. The sections that follow describe these functions in greater detail. Table 1-4 Internet I/O Function Codes Function Code and Function Arguments Modifier Description IO$_ACCESS p3,p4 IO$M_ACCEPT Open a connection. IO$_ACPCONTROL p1 Perform an ACP (ancillary control process) operation. IO$_DEACCESS p4 IO$M_SHUTDOWN Abort or close a connection. IO$_READVBLK IO$M_ Read virtual block. p1,p2,p3,p4,p6 INTERRUPT IO$M_PURGE Control the buffer IO$M_LOCKBUF operations. IO$_SENSEMODE Read the internet [p2],p3,p4,p6 pseudodevice characteristics. IO$_SENSECHAR Read the internet [p2],p3,p4,p6 pseudodevice characteristics. IO$_SETMODE IO$M_OUTBAND Set the internet p1,[p2], p3,p4,p5 IO$M_READATTN pseudodevice characteristics IO$M_WRTATTN for subsequent operations. IO$_SETCHAR IO$M_OUTBAND Set the internet p1,[p2],p3,p4,p5 IO$M_READATTN pseudodevice characteristics IO$M_WRTEATTN for subsequent operations. IO$_WRITEVBLK IO$M_ Write virtual block. p1,p2,p3,p4,p5 INTERRUPT The following table contains the file names of the symbol definition files. These files specify $QIO arguments (p1,p2,...p6) for applications written in the corresponding programming languages. You must invoke the symbol definition by using the appropriate include statement in your application. Table 1-5 Internet Symbol Definition Files File Name Language UCX$INETDEF.H DEC C or VAX C UCX$INETDEF.FOR VAX Fortran UCX$INETDEF.PAS VAX PASCAL UCX$INETDEF.MAR MACRO-32 UCX$INETDEF.PLI VAX PL/1 UCX$INETDEF.R32 BLISS-32 UCX$INETDEF.ADA VAX ADA UCX$INETDEF.BAS VAX BASIC 6 IO$_ACCESS When you are using a connection-oriented protocol such as TCP, the IO$_ACCESS function initiates a connection and specifies a remote port and address. When you use a connectionless protocol such as UDP, the IO$_ACCESS function sets the remote port and address. For TCP, a connection request times out in a specified interval (75 seconds by default). This interval can be changed by the system manager. The program can also set a specific timeout interval for a socket that it has created. The equivalent C Socket function is connect() or accept(). 7 Arguments p3 UCX usage remote socket name type longword (unsigned) access read only mechanism by descriptor For the IO$_ACCESS function, the p3 parameter is the address of a UCX item_list_2 descriptor that points to the sockaddr_in structure containing the remote host address and port number. For the IO$_ACCESS function with the IO$M_ACCEPT modifier, the p3 parameter is the address of a UCX item_list_3 descriptor that points to a socket name and a returned longword that contains the length. p4 UCX usage the device channel type word (unsigned) access read only mechanism by reference The p4 parameter specifies the address of a word value containing the channel for the I/O operations after the connection is established. This input parameter is specified only with the IO$M_ACCEPT modifier (for TCP). 7 Function_Modifiers IO$M_ACCEPT Accepts a connection request issued from another process. The remote host address and remote port number are output parameters. IO$M_NOW Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the I/O operation to block, the system completes the I/O operation and returns the $QIO error code SS$_SUSPENDED. The corresponding UNIX error code is EWOULDBLOCK. 7 Condition_Values_Returned SS$_ABORT Programming error, INET management error, or hardware error. Aborts execution of the I/O operation. SS$_BADPARAM Programming error that occurred for one of the following reasons: 1. You tried to execute a $QIO function without specifying a device socket. 2. You tried to issue an IO$_ACCESS!IO$M_ ACCEPT function without specifying the channel for the device socket that will be used for the accepted connection (p4 is null or invalid). 3. You tried to issue an IO$_ACCESS function without specifying the address of the remote device socket address (p3 as null). SS$_BUGCHECK Inconsistent state. Report the problem to your DIGITAL support representative. SS$_CANCEL Warning code. The I/O operation was canceled by a $CANCEL system service. SS$_CONNECFAIL Programming error, INET management error, or hardware error. The connection was abnormally terminated for one of the following reasons: 1. An IO$_ACCESS!IO$M_ACCEPT failed because the listener socket closed. The cause can be local or remote. 2. An existing connection was aborted because of an error detected during communication. SS$_DEVINACT Programming or INET management error. The driver was not started. Issue a UCX START COMMUNICATION command before issuing any $QIO call. SS$_DEVNOTMOUNT Programming or INET management error. You improperly executed the INET startup procedure. The driver was loaded, but the INET_ACP was not activated. SS$_EXQUOTA Programming or system management error. Socket quota (maximum number of sockets allowed) or user quotas exceeded. SS$_FILALRACC Programming error. The socket name is already in use by one of the following: 1. On a raw socket, you specified a remote INET socket address with an IO$_ACCESS function, but an INET address was already specified with a previous IO$_ACCESS. 2. On a datagram, you specified a remote INET socket address with an IO$_ACCESS function, but an INET address was already specified with a previous IO$_ACCESS. 3. On a stream socket, you issued an IO$_ ACCESS function on a stream socket that was already connected. SS$_ILLCNTRFUNC Programming error. Illegal function. SS$_INSFMEM INET management or programming error. Not enough buffer space for allocation. The INET software needs more buffer space. SS$_IVADDR Programming error. The specified INET address was not found or an invalid port and INET address combination was specified with the IO$_ACCESS function. Port zero is not allowed with an IO$_ACCESS function. SS$_IVBUFLEN Programming error. Socket address buffer has an invalid size. SS$_NOLICENSE Programming or system management error. DIGITAL TCP/IP for OpenVMS license is not present. SS$_NOLINKS Programming error. An attempt was made to disconnect a socket that has not been connected. SS$_LINKABORT Communication status change. The remote socket closed a connection. SS$_PROTOCOL Programming error. The address family of the remote INET address specified with an IO$_ACCESS function is not supported (UDP/IP or TCP/IP). The address family should be UCX$C_AF_INET. SS$_REJECT Programming error, INET management error, or hardware error. Connection is rejected for one of the following reasons: 1. An attempt was made to connect to a remote socket that is already connected. 2. An error was encountered while establishing the connection. 3. The peer socket either refused a connection request or wants to close the connection. SS$_SHUT The network is being shut down. SS$_SUSPENDED The operation is blocked. The accept operation cannot complete because there are no connection requests received. The socket is marked as nonblocking. SS$_TIMEOUT Programming error, INET management error, or hardware error. A TCP/IP connection timed out while in the process of being established. The default time interval is 75 seconds. SS$_UNREACHABLE Communication status. Remote host or network is not reachable. 6 IO$_ACPCONTROL The internet ACP Control I/O (IO$_ACPCONTROL) function requests that the ACP perform operations such as providing information from the internet host and network database files. The equivalent C Socket functions are gethostbyname(), gethostbyaddr(), getnetbyname(), or getnetbyaddr(). Two programming examples for the IO$_ACPCONTROL routine follow this command description. IO$_ACPCONTROL Function (MACRO-32 Programming) uses the MACRO-32 programming language and IO$_ ACPCONTROL Function (C Programming) uses the C programming language. 7 Arguments p1 UCX usage subfunction code type longword (unsigned) access read only mechanism by descriptor The p1 parameter is the address of the OpenVMS descriptor for a 4-byte block. The block consists of a subfunction type (1 byte), a call code (1 byte), and 2 bytes reserved for DIGITAL (must be zero). Valid INET Subfunction Codes lists the valid INET subfunction codes. These symbols are defined by the $INETACPFSYMDEF module in the UCX$INETDEF symbol definition file. Table 1-6 Valid INET Subfunction Codes INET Subfunction Code Code Function INETACP_FUNC$C_ Get the INET address of the specified GETHOSTBYNAME host from the internet host database. INETACP_FUNC$C_ Get the host name of the specified GETHOSTBYADDR internet address from the internet host database. INETACP_FUNC$C_ Get the INET address of the specified GETNETBYNAME network from the internet network database. INETACP_FUNC$C_ Get the network name of the specified GETNETBYADDR internet address from the internet network database. When these functions are performed, IO$_ACPCONTROL searches the local database for the host's name. If it does not find the host name in the local host database, IO$_ACPCONTROL then searches the BIND database if the BIND resolver is enabled. INET Call Codes lists the valid INET call codes that IO$_ ACPCONTROL accepts. Table 1-7 INET Call Codes Code Description INETACP$C_ALIASES Obtains the list of alias names associated with the specified host or network from the internet hosts or network database. INETACP$C_TRANS Returns a longword value of the internet address in dotted-decimal notation. INETACPC$C_HOSTENT_ Returns full host information in a OFFSET modified hostent structure. In the modified structure, pointers are replaced with offsets from the beginning of the structure. INETACP$C_NETENT_ Returns full network information in OFFSET a modified netent structure. In the modified structure, pointers are replaced with offsets from the beginning of the structure. The INET_ACP call codes are defined by the $INETACPSYMDEF module in the UCX$INETDEF symbol definition file. The hostent and netent structures are defined by the $HOSTENTDEF and $NETENTDEF modules in the UCX$INETDEF symbol definition file. p2 UCX usage input parameter type longword (unsigned) access read only mechanism by descriptor The p2 parameter is the address of the string descriptor for the input parameter. The input parameter contains the host name, network name, host address, or network INET address. The INET address is specified as a character string. The network and host numbers are separated by periods. The address is in network format. For example, in the address 128.20.10.5, the network is 128.20.10 and the host is 5. p3 UCX usage length of the output string type word access write only mechanism by reference The p3 parameter is the address of the word location where the length of the output string is returned. p4 UCX usage output character string address type longword or character string access write only mechanism by descriptor The p4 parameter is the address of the descriptor for the output character string that contains the host name, network name, host address, or the network INET address. The INET address is returned as a character string. The network and host numbers are separated by periods. The address is in dotted decimal notation. Alias names are separated by a null character (a 0 byte). The length of the returned string includes all null characters that separate aliases. 7 Condition_Values_Returned SS$_ABORT Unknown cause of an internal error. An unspecified error was detected while performing an INET ACP function. SS$_BADPARAM Programming or internal error. You specified a bad parameter (name or address) in a GET{HOST,NET}BY{NAME,ADDRESS} ACP call. SS$_BUFFEROVF Programming error. There was not enough space for returning all alias names in a GET{HOST,NET}BY{NAME,ADDRESS} ACP call. SS$_ENDOFFILE The information requested is not in the database. SS$_ILLCNTRFUNC Programming error. An invalid ACP function code was specified in an IO$_ACPCONTROL function. SS$_NOPRIV INET management error. No privilege for the execution of an INET ACP function. SS$_RESULTOVF Programming error. The ACP overflowed the buffer in returning a parameter. SS$_SHUT The network is being shut down. Example .titleOGet_host_by_namection (MACRO-32 Programming) .ident /01/ .library /sys$share:lib.mlb/ .show meb $inetacpfdef dev: .ascid /ucx$device:/ chan: .long 0 iosb: .quad 0 command: .long length .address comm comm: .byte 1 ; get host .byte 0 .word 0 length=.-comm host_d: .ascid /BRIGIT/ host_nam: .ascid / .blkl 32 title: .ascid /Host address:/ title1: .ascid /Host name:/ .entry start,^m<> ; ; assign Internet device for INIT ; $assign_s devnam=dev, chan=chan blbs r0,as1 brw exit as1: $qioW_s efn=#1,- chan=chan, - func=#io$_acpcontrol,- iosb= iosb,- p1=command,p2=#host_d,P3=#host_nam,p4=#host_nam blbc r0,print cmpw #ss$_normal,iosb beqlu print movzwl iosb,r0 print: movl r0,r10 pushab title1 calls #1,g^lib$put_output pushab host_d calls #1,g^lib$put_output pushab title calls #1,g^lib$put_output pushab host_nam calls #1,g^lib$put_output movl r10,r0 exit: ret .end start #module gethost_addrCONTROL Function (C Programming) /* **++ ** ** This example gets host address for the given host name ** using the Internet ACP Control I/O function IO$_ACPCONTROL ** ** **-- **/ /* ** INCLUDE FILES */ #include <descrip.h> #include <iodef.h> #include <ucx$inetdef.h> gethost_addr (addr) int *addr; { /* Descriptor for Inet device name */ struct dsc$descriptor Inet_dev = {11, DSC$K_CLASS_S, DSC$K_DTYPE_T, "UCX$DEVICE:" }; /* Descriptor for the host name for which to get the Internet address */ struct dsc$descriptor host_name = {6, DSC$K_CLASS_S, DSC$K_DTYPE_T, "lassie" }; /* Descriptor for ACP command */ struct dsc$descriptor command = {0, DSC$K_CLASS_S, DSC$K_DTYPE_T, 0 }; /* Descriptor for host address */ struct dsc$descriptor host_ad = {0, DSC$K_CLASS_S, DSC$K_DTYPE_T, 0 }; int status ; /* Return status */ int iosb [2] ; /* I/O status block */ short channel ; /* INET dev channel */ short retlen ; /* Word to return address length */ /* ** ACP command: INETACP$C_TRANS - If this bit set, the Internet ** address will be returned as a long word integer value. ** INETACP_FUNC$C_GETHOSTBYNAME indicates that it is a function ** to get the host address given the host name. */ int comm = INETACP$C_TRANS * 256 + INETACP_FUNC$C_GETHOSTBYNAME ; /* byte 1,2,0,0 */ int addr_buff[8]; /* buffer for ACP output */ /* ** INET ACP command */ command.dsc$a_pointer = &comm ; command.dsc$w_length = sizeof(comm) ; /* ** Descriptor for ACP output */ host_ad.dsc$a_pointer = &addr_buff ; host_ad.dsc$w_length = sizeof(addr_buff) ; /* ** Assign a channel to INET device */ status = SYS$ASSIGN(&Inet_dev, &channel, 0, 0); if ((status & 1) == 0) { printf("Failed to assign channel to INET device \n"); return(status); } /* ** Get the Host address (longword) */ status = SYS$QIOW(1, channel, /* Channel number */ IO$_ACPCONTROL, /* I/O function */ iosb, /* I/O status */ 0, 0, &command, /* P1 command */ &host_name, /* P2 host name */ &retlen, /* P3 adrs to ret length */ &host_ad, /* P4 adrs output */ 0, 0); if (((status & 1) && (iosb[0] & 1)) == 0) { printf("Failed to get INET address for host %s \n", host_name.dsc$a_pointer); return (status) ; } /* ** Return the host Internet address */ addr = addr_buff[0]; /* ** Deassign the INET dev channel */ SYS$DASSGN (channel); return (status); } 6 IO$_DEACCESS The IO$_DEACCESS function closes a connection. You can use a flag to specify whether pending I/O operations will be completed or discarded before the function is completed. After the function completes, $QIOs to transmit data are no longer allowed. To resume transmitting on the channel being used, you must issue the appropriate functions to initialize a communication link. If it is required for the protocol, you must also issue $QIOs with IO$_SETMODE, and if it is required for the protocol, IO$_ACCESS as well. Issuing an IO$_DEACCESS function disconnects the link between the two communicating agents previously established with an IO$_ ACCESS function. The connection is discontinued, but messages queued for transmission are sent to the connection peer before finally disconnecting the link. An IO$_DEACCESS function prevents the user process that issued the function from sending any more data. It also ensures successful delivery of all data queued before the IO$_DEACCESS function was issued, unless there is a fatal error. A fatal error will be signaled. The user may continue to receive data until it is signaled that the connection peer has closed the connection. Before a receiving process with a connection-oriented protocol is notified about a synchronous disconnection, all the data that the peer sent is received. You can specify a wait time or time-to-linger socket parameter (UCX$C_LINGER option) for transmission completion before disconnecting the connection. Use the IO$_SETMODE or IO$_SETCHAR function to set and clear the UCX$C_LINGER option. If you set the UCX$C_LINGER option, a $QIO call that uses the IO$_DEACCESS function allows data queued to the socket to arrive at the destination. The system is blocked until data arrives at the remote socket. The socket data structure remains open for the duration of the TCP idle time interval. If you do not set the UCX$C_LINGER option (option is set to 0), a $QIO call that uses the IO$_DEACCESS function discards any data queued to the socket and deallocates the socket data structure. NOTE For compatibility with UNIX TCP/IP, the UCX implementation of TCP/IP forces a time-to-linger of 2 minutes on stream sockets. The equivalent C Socket function is close() or shutdown(). 7 Arguments p4 UCX usage flags type byte (unsigned) access read only mechanism by value This argument is used only with the IO$M_SHUTDOWN function modifier. The following table lists the IO$M_SHUTDOWN flags (defined in the UCX$INETDEF symbol definition file) that you can use to specify the disposition of pending I/O operations. Shutdown Flag Description UCX$C_DSC_RCV Discards messages from the receive queue and disallows further receiving. Pending messages in the receive queue for this connection are discarded. The socket is put in CANTRCVMORE state. UCX$C_DSC_SND Discards messages from the send queue and disallows further sending. Pending messages in the transmit queue for this connection are discarded. The socket is put in CANTSNDMORE state. UCX$C_DSC_ALL Discards all messages and disallows both sending and receiving (socket is put in the CANTRCVMORE and CANTSNDMORE states). All pending messages are discarded. Specifying this flag has the same effect as issuing a $CANCEL function followed by an IO$_DEACCESS function without any flags. 7 Function_Modifiers IO$M_SHUTDOWN Causes all or part of the full-duplex connection on the device socket to be shut down. The p4 parameter specifies shutdown flags. IO$M_NOW Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the I/O operation to block, the system completes the I/O operation and returns the error code SS$_SUSPENDED. 7 Condition_Values_Returned SS$_ABORT Programming error, INET management error, or hardware error. The execution of the I/O function aborts. A disconnect was requested on a connection that already started a disconnect operation. SS$_BADPARAM Programming error. You specified a $QIO function using an invalid parameter. You tried to execute one of the I/O functions without specifying a device socket. Instead, you should first create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. SS$_CANCEL Warning code. The I/O operation canceled by executing a $CANCEL system service routine. SS$_DEVINACT INET management error. The driver was not started. You must execute a UCX START COMMUNICATION before issuing a $QIO operation. SS$_DEVNOTMOUNT INET management error. You improperly executed the INET startup procedure. The driver was loaded, but the INET_ACP function was not activated. SS$_NOLINKS Programming error because of one of the following reasons: 1. The socket was not connected (TCP/IP) or an INET port and address were not specified with an IO$_ACCESS (UDP/IP) or IP. 2. You tried to disconnect an unconnected socket. SS$_SHUT The network is being shut down. 6 IO$_READVBLK Read functions transfer data received from an internet host and store that data in system-dynamic space on the virtual memory address of the user process. The TCP/IP software provides the READ I/O function code IO$_READVBLK, which reads a virtual block of a stream socket, datagram, or raw socket. Received messages are stored in system-dynamic memory and copied to user buffers when the software issues a read operation. If you specify multiple buffers, the buffers are filled in the order specified in the p6 list. The TCP/IP software fills in these user buffers according to the protocol (socket type). For TCP/IP (stream socket), data is buffered in system space as a stream of bytes. The user buffer specified with a $QIO is filled in with data that is being buffered in system space. The I/O is completed when there is no more data in the system space, or there is no more available space in the user buffer. Data that is buffered in the system space but did not fit in the user buffer is available to the user in subsequent $QIOs. No data is discarded or lost. Datagram and raw socket data is buffered in system space as a chain of records. The user buffer specified with a $QIO is filled in with data that is being buffered in one record in system space. One I/O operation reads data from one record. The I/O completes when there is no more space in the user buffer or when all data from the record has been transferred to the user buffer. Data remaining in the current record in system space that did not fit in the user buffer is discarded. A subsequent $QIO reads data from the next record buffered in system space. Use the UCX SHOW DEVICE_SOCKET /FULL command to display counters related to read operations. The equivalent C Socket function is the recv*() or read() routine. Three programming examples for the IO$_READVBLK routine follow this command description. IO$_READVBLK Function (MACRO-32 Programming) uses the MACRO-32 programming language to read a vectored buffer. IO$_READVBLK Function - Vectored Buffers (C Programming) uses the C programming language to read a vectored buffer. IO$_READVBLK Function - INET device (C Programming) uses the C programming language to read from an INET driver. 7 Arguments p1 UCX usage buffer type longword (unsigned) access read only mechanism by reference The p1 argument specifies the starting virtual address of the buffer that is to receive the data. p2 UCX usage buffer length type longword (unsigned) access read only mechanism by value The p2 argument specifies the size (in bytes) of the buffer that is to receive the data. p3 UCX usage remote socket name for the source of the message type longword (unsigned) access read only mechanism by descriptor The p3 argument specifies the address of a UCX item_list_3 descriptor with a buffer that contains the remote socket name of the source of the message. The remote socket is composed of the remote port and host internet address. The parameter name for the descriptor is UCX$C_SOCK_NAME, which is defined in the UCX$INETDEF symbol definition file. p4 UCX usage flags type word (unsigned) access read only mechanism by value The p4 argument specifies the flags for the read operation. The valid flags are described in Valid Flags for the p4 Argument. Table 1-8 Valid Flags for the p4 Argument Flag Description UCX$C_MSG_OOB Reads an out-of-band byte. UCX$C_MSG_PEEK Reads a message but leaves the message in the queue. Another read operation shows the same message. UCX$C_MSG_NBIO Does not block the I/O operation if the receive queue is empty. Similar to using IO$M_ NOWAIT. UCX$C_MSG_PURGE Flushes data from the queue. Similar to using IO$M_PURGE. UCX$C_MSG_ Blocks the completion of the operation until BLOCKALL the buffer is filled completely or until the connection is closed. Similar to using IO$M_ LOCKBUF. p6 UCX usage UCX item_list_2 type longword (unsigned) access read only mechanism by descriptor The p6 argument specifies the address for the descriptor of an output parameter list. The maximum number of buffers you can specify with the p6 argument is 16. If you use the p1 and p2 arguments, do not use the p6 argument; they are mutually exclusive. You either use p1 and p2, or you use p6 instead. The software first checks to see if the p1 argument is used. If p1 is not used, the software checks to see if the p6 argument is being used. If neither the p1 nor the p6 arguments are used, the software returns an error code. The transfer-length value returned in the I/O status block is the total number of bytes transferred to the buffer or multiple buffers. 7 Function_Modifiers IO$M_INTERRUPT Reads an out-of-band (OOB) message. This has the same effect as specifying the UCX$C_MSG_ OOB flag. On receiving a TCP/IP OOB character, TCP/IP stores the pointer in the received stream with the character that precedes the OOB character. A read operation with a user-buffer size larger than the size of the received stream up to the OOB character completes and returns to the user the received stream up to, but not including, the OOB character. To determine whether the socket must issue more read $QIOs before getting all the characters from the stream preceding an OOB character, poll the socket. To do this, issue a $QIO with the $IO_SENSEMODE function, and the UCX$C_IOCTL subfunction that specifies the SIOCATMARK command. The SIOCATMARK values are as follows: o 0 = Issue more read QIOs to read more data before reading the OOB. o 1 = The next read QIO will return the OOB. Polling a socket is particularly useful when the OOBINLINE socket option is set. When the OOBINLINE is set, TCP/IP reads the OOB character with the characters in the stream (IO$_READVBLK), but not before reading the preceding characters. Use this polling mechanism to determine whether the first character in the user buffer on the next read is an OOB character. On a socket with the OOBINLINE option set to clear, a received OOB will always be read by issuing a $QIO with either the IO$_READVBLK!IO$M_INTERRUPT or IO$_READVBLK and the UCX$C_MSG_OOB flag set. This can occur, regardless of how many preceding characters in the stream have been returned to the user. IO$M_LOCKBUF Blocks the completion of the I/O operation until the user buffer is completely filled or until the connection is closed. This is particularly useful when you want to minimize the number of $QIO commands issued to read a data stream of a particular size. This function code is supported only for stream protocols. IO$M_NOWAIT Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the I/O operation to block, the system completes the I/O operation and returns the error code SS$_SUSPENDED. IO$M_PURGE Flushes data from the device socket receive queue (discards data). If the user buffer is larger than the amount of data in the queue, all data in the queue is flushed. This function works in the same manner for both datagram and stream sockets. 7 Condition_Values_Returned SS$_ABORT Programming error, INET management error, or hardware error. The execution of the I/O was aborted. SS$_ACCVIO Programming error. You tried to access an invalid memory location or buffer. SS$_BADPARAM Programming error. You used one of the following methods to specify a $QIO function with an invalid parameter: 1. You executed an I/O function without specifying a device socket. You must first issue a $QIO with the IO$_SETMODE function and the proper parameters to create the device socket. 2. You issued an IO$_READVBLK or IO$_WRITEVBLK function that does not specify a correct buffer address (p1, p5 or p6 are null). 3. You issued an IO$_READVBLK or IO$_WRITEVBLK function that specifies an invalid vectored buffer (p5 or p6 are invalid address descriptors). 4. The socket has the OOBINLINE option set, or there is no OOB character in the socket's OOB queue because the character was either already read or never received. This condition happens only if you use the IO$M_ INTERRUPT modifier or set the UCX$C_MSG_OOB flag with IO$_READVBLK. SS$_CANCEL Warning code. The I/O operation canceled by executing a $CANCEL system service routine. SS$_CONNECFAIL Programming error, INET management error, or hardware error. The connection was abnormally terminated. SS$_DEVINACT INET management error. The driver has not been started. You must execute a UCX START COMMUNICATION command before issuing a $QIO routine. SS$_DEVNOTMOUNT INET management error. You improperly executed the INET startup procedure. The driver was loaded, but the INET_ACP was not activated. SS$_INSFMEM INET management or programming error. There is not enough buffer space for allocation. The INET software needs more buffer space. You should set a higher quota for the dynamic buffer space, or shut down and restart your internet with a larger static buffer space. SS$_IVBUFLEN Programming error occurred for one of the following reasons: 1. The size of the buffer for an I/O function is insufficient. 2. You tried to issue an IO$_READVBLK or IO$_ WRITEVBLK that specifies a correct buffer address (p1 valid), but does not specify a buffer length (p2 is null). SS$_LINKDISCON A virtual circuit (TCP/IP) was closed at the initiative of the peer. SS$_NOLINKS Programming error. Read attempt on unconnected TCP socket. SS$_SHUT The network is being shut down. SS$_SUSPENDED The operation is blocked for one of the following reasons: 1. No messages were received so the receive operation cannot complete. The socket is marked as nonblocking. 2. The socket has the OOBINLINE option clear, and the OOB character has already been read. SS$_TIMEOUT This applies to a socket that has KEEPALIVE set. The connection was idle for longer than the timeout interval (10 minutes is the default). SS$_UNREACHABLE Communication status. The remote host or network is unreachable. Example .titleORead_vVBLK Function (MACRO-32 Programming) ;+ ; Read using a vectored buffer descriptor ;- .ident /01/ $inetsymdef ; INET symbols dev: .ascid /ucx$device:/ ; INET device name channel: .word 0 ; INET channel iostatus: .quad 0 ; I/O status block Ret_adr: .blkb 16 ; Buffer for remote host IP address Ret_len=.-Ret_adr leng: .long 0 ; Return length of Remote IP address loc_adr:.word INET$C_AF_INET ; INET family .word 5001 ; Port number ; Local host IP address .byte 128,20,20 ; Network/subnetwork number .byte 10 ; Host number .blkb 8 par11: .word INET$C_UDP ; UDP/IP protocol .word INET_PROTYP$C_DGRAM ; Datagram type of socket ; ; Item_list_3 descriptor for the Remote IP address ; par12: .long ret_len ; Length .address ret_adr ; Buffer address .address leng ; Returned length ; ; Item_list_2 descriptor for the Local IP address ; par13: .long ret_len ; Length .address loc_adr ; Address ; ; I/O Buffer ; buffer_1: .blkb 512 buflen=.-buffer_1 buffer_2: .blkb 512 buffer_3: .blkb 512 buffer_4: .blkb 512 buf_d: .long len_d .address buffer_d buffer_d: .long buflen .address buffer_1 .long buflen .address buffer_2 .long buflen .address buffer_3 .long buflen .address buffer_4 len_d=.-buffer_d .entry start,^m<> ; ; Assign an INET device ; $assign_s devnam=dev, chan=channel blbs r0,read brw exit ; ; Create and bind the device socket to the local host ; read: $qioW_s efn=#31,- ; Event flag chan=channel, - ; Channel func=#io$_setmode,- ; I/O Function iosb= iostatus, - ; I/O status block p1=par11,- ; Socket creation parameters P3=#Par13 ; Socket Bind parameters blbc r0,exit ; ; Perform a QIOW read operation ; $qiow_s efn=#31,- ; Event flag chan=channel, - ; Channel func=#io$_readvblk,- ; I/O function iosb= iostatus,- ; I/O status p3=#par12,-; Descriptor of the remote Host IP address P6=#buf_d ; Vectored buffer descriptor exit: ret ; Exit .end start Example 1-10 Programming) Function - Vectored Buffers (C #module read_vecio /* **++ ** ** This example does vectored buffers read ** **-- */ /* ** INCLUDE FILES */ #include <descrip.h> #include <ucx$inetdef.h> /* INET symbol definitions */ #include <iodef.h> /* ** */ struct bvec /* Structure definition for vec buf */ { int length ; char *b_adrs ; } ; struct sockaddr { /* Structure definition for socket adrs */ short inet_family ; short inet_port ; char adrs[4] ; char blkb[8] ; } ; main() { int status ; /* For return status */ short channel ; /* INET channel */ short sck_parm[2] ; /* Socket creation parameter */ char buf_1[12],buf_2[12],buf_3[12],buf_4[12] ; struct sockaddr remote_host ; /Socket adrs definition for rhst */ struct sockaddr local_host ; /Socket adrs definition for lhst */ struct itlst lhst_adrs ; struct itlst rhst_adrs ; struct bvec buf_vec[5] = { {12, &buf_1 }, {12, &buf_2 }, {12, &buf_3 }, {12, &buf_4 }, {0, 0 } } ; /* Descriptor for Inet device name */ struct dsc$descriptor dev = { 11, DSC$K_CLASS_S, DSC$K_DTYPE_T, "UCX$DEVICE:"} ; /* Descriptor for vectored buffer */ struct desc$descriptor buf_d = { 0, DSC$K_CLASS_S, DSC$K_DTYPE_T, 0} ; /* Initialize the parameters */ sck_parm[0] = INET$C_UDP ; /* UDP/IP protocol */ sck_parm[1] = INET_PROTYP$C_DGRAM ; /*Datagram type of socket*/ /* Itlst for local IP address */ lhst_adrs.lgth = sizeof(local_host); lhst_adrs.hst = &local_host ; rhst_adrs.lgth = sizeof(remote_host) ; rhst_adrs.hst = &remote_host ; buf_d.dsc$a_pointer = buf_vec; buf_d.dsc$w_length = sizeof(bvec) ; /* Initialize socket address for remote host */ remote_host.inet_family = INET$C_AF_INET ; /* INET family */ remote_host.inet_port = 5002 ; /* Port number */ remote_host.adrs[0] = 128 ; /* Network/subnetwork*/ remote_host.adrs[0] = 20 ; /* number */ remote_host.adrs[0] = 20 ; remote_host.adrs[0] = 156 ; /* Host number */ remote_host.blkb[0] = 0 ; remote_host.blkb[1] = 0 ; remote_host.blkb[2] = 0 ; remote_host.blkb[3] = 0 ; remote_host.blkb[4] = 0 ; remote_host.blkb[5] = 0 ; remote_host.blkb[6] = 0 ; remote_host.blkb[7] = 0 ; /* Initialize socket address for local host */ local_host.inet_family = AF_INET ; /* INET family */ local_host.inet_port = 5002 ; /* Port number */ local_host.adrs[0] = 128 ; /* Network/subnetwork*/ local_host.adrs[0] = 20 ; /* number */ local_host.adrs[0] = 20 ; local_host.adrs[0] = 156 ; /* Host number */ local_host.blkb[0] = 0 ; local_host.blkb[1] = 0 ; local_host.blkb[2] = 0 ; local_host.blkb[3] = 0 ; local_host.blkb[4] = 0 ; local_host.blkb[5] = 0 ; local_host.blkb[6] = 0 ; local_host.blkb[7] = 0 ; /* ** Assign a channel to INET device */ status = SYS$ASSIGN( &dev, &channel, 0, 0) ; if ((status & 1) == 0) { printf("Failed to assign channel to INET device \n") ; return(status) ; } /* ** Create and bind the device socket to local host */ status = SYS$QIOW( 31, /* Event flag */ channel, /* Channel number */ IO$_SETMODE, /* I/O function */ iosb, /* I/O status block */ 0, 0, &sck_parm, /* P1 Socket creation parameter */ 0, &lhst_adrs, /* P3 Socket bind parameter */ 0,0,0) ; if ((status & 1) == 0) { printf("Failed to create and bind the devicesocket \n") ; return(status) ; /* ** Perform the QIO read operation */ status = SYS$QIOW( 31, /* Event flag */ channel, /* Channel number */ IO$_READVBLK,/* I/O function */ iosb, /* I/O status block */ 0, 0, 0, 0, &rhst_adrs, /* P3 Remote host adrs desc */ 0, 0, &buf_d) ; /* P6 Vectored buffer desc */ if ((status & 1) == 0) { printf("Failed to read from device \n") ; return(status) ; } /* ** Deassign the INET dev channel */ SYS$DASSGN (channel); return(status) ; } #module read_ioO$_READVBLK Function - INET device (C Programming) /* **++ ** ** This example does read from INET device ** **-- */ /* ** INCLUDE FILES */ #include <descrip.h> #include <ucx$inetdef.h> /* INET symbol definitions */ #include <iodef.h> struct sockaddr { /* Structure definition for socket adrs */ short inet_family ; short inet_port ; char adrs[4] ; char blkb[8] ; } ; struct itlst { int lgth ; struct sockaddr *hst ; } ; main() { int status ; /* For return status */ short channel /* INET channel */ short sck_parm[2] ; /* Socket creation parameter */ int iosb [2] ; /* I/O status block */ struct sockaddr local_host ; /* Socket adrs definition for lhst */ struct itlst lhst_adrs ; char buf[128] ; int buflen = 128 ; /* Descriptor for Inet device name */ struct dsc$descriptor dev = { 3, DSC$K_CLASS_S, DSC$K_DTYPE_T, "UCX$DEVICE:"} ; /* Initialize the parameters */ sck_parm[0] = INET$C_UDP ; /* UDP/IP protocol */ sck_parm[1] = INET_PROTYP$C_DGRAM ; /* Datagram type of socket */ /* Itlst for local IP address */ lhst_adrs.lgth = sizeof(local_host); lhst_adrs.hst = &local_host ; /* ** Assign a channel to INET device */ status = SYS$ASSIGN( &dev, &channel, 0, 0) ; if ((status & 1) == 0) { printf("Failed to assign channel to INET device \n") ; return(status) ; } /* Initialize socket address for local host */ local_host.inet_family = INET$C_AF_INET ;/* INET family */ local_host.inet_port = 0 ; /* Port number */ local_host.adrs[0] = 128 ; /* Network/subnetwork*/ local_host.adrs[1] = 45 ; /* number */ local_host.adrs[2] = 45 ; local_host.adrs[3] = 216 ; /* Host number */ local_host.blkb[0] = 0 ; local_host.blkb[1] = 0 ; local_host.blkb[2] = 0 ; local_host.blkb[3] = 0 ; local_host.blkb[4] = 0 ; local_host.blkb[5] = 0 ; local_host.blkb[6] = 0 ; local_host.blkb[7] = 0 ; /* ** Create and bind the device socket to local host */ status = SYS$QIOW( 31, /* Event flag */ channel, /* Channel number */ IO$_SETMODE, /* I/O function */ iosb, /* I/O status block */ 0, 0, &sck_parm, /* P1 Socket creation parameter */ 0, &lhst_adrs, /* P3 Socket bind parameter */ 0,0,0) ; if ((status & 1) == 0) { printf("Failed to create and bind the device socket \n") ; return(status) ; } /* ** Perform the QIO read operation */ status = SYS$QIOW( 0, /* Event flag */ channel, /* Channel number */ IO$_READVBLK,/* I/O function */ iosb, /* I/O status block */ 0, 0, buf, /* P1 buffer */ buflen, /* P2 buffer length */ 0,0,0,0 ) ; if ((status & 1) == 0) { printf("Failed to read from inet device \n") ; return(status) ; } /* ** Deassign the INET dev channel */ SYS$DASSGN (channel); return(status) ; } 6 IO$_SENSEMODE/IO$_SENSECHAR The Sense Mode (IO$_SENSEMODE) and Sense Characteristics (IO$_SENSECHAR) I/O functions return the characteristics of the internet pseudodevice. The C Socket equivalent is the getsockopt() function or a call to the ioctl program. 7 Arguments p3 UCX usage UCX item_list_3 type longword (unsigned) access read only mechanism by descriptor The p3 argument contains the address of a UCX item_list_3 descriptor that specifies the buffer where the software returns the local socket name. The buffer contains the local socket address (family name, port number, and internet address). The parameter name for the descriptor is UCX$_C_SOCK_NAME, which is defined in the UCX$INET_DEF symbol definition file. The C Socket equivalent for this function is getsockname(). p4 UCX usage UCX item_list_3 type longword (unsigned) access read only mechanism by descriptor The p4 argument contains the address of a UCX item_list_3 descriptor that specifies the buffer from which to return the remote peer socket name. The buffer contains the remote socket address (family name, port number, and internet address). The C Socket equivalent for this function is getpeername(). p6 UCX usage UCX item_list_2 or item_list_3 type longword (unsigned) access read only mechanism by descriptor The p6 argument specifies the address of a descriptor that lists UCX item_list_2 or item_list_3 descriptors. The following are the parameter types for the UCX item_list to which the p6 argument points: o UCX$C_SOCKOPT (communication socket option parameters) o UCX$C_TCPOPT (TCP options) o UCX$C_IPOPT (IP options) o UCX$C_IOCTL (I/O control parameters) The UCX item_list descriptor points to an integer (with the length set to the size of the integer). The integer contains zero to clear an option and nonzero to set an option. The UCX$C_SOCKOPT parameter specifies the communication socket options. The descriptor that defines the list of socket options points to a list of item_list_3 descriptors, which contains one descriptor for each option. The p6 Socket Options describes the options for the UCX$C_SOCKOPT parameter type. Table 1-9 The p6 Socket Options Socket Option Description UCX$C_BROADCAST Permits sending broadcast messages. A broadcast internet address is accepted when the socket has this option set. Supported only with datagram. UCX$C_DONTROUTE Uses interface addresses only. Optional only for datagram or raw IP. UCX$C_ERROR Obtains the socket error status and clears the error on the socket. UCX$C_KEEPALIVE Detects broken idle connections and keeps them alive for the specified maximum idle time. Broken idle connections occur when the remote end point has dropped the connection. This is optional for stream socket and ignored by datagram and raw IP. UCX$C_LINGER Lingers on close operation if data is present (that is, waits for all messages to be sent). Optional for stream socket. UCX$C_OOBINLINE Leaves the received OOB data in line. UCX$C_RCVBUF Gets the socket receive quota. UCX$C_REUSEADDR Allows reuse of the local socket address. The local socket address is the 16-byte structure that contains address family, port, and host IP address. The UCX$C_REUSEADDR option enables reuse of the local port number portion. It works only with connection-oriented protocols (in particular, TCP/IP), where a connection is characterized for its entire life by the local address, local port, remote host, and remote port. The option can be used for a client that always binds to a known or well-defined port number. It allows several instances of the client image running on one host to connect to the same server on different hosts. UCX$C_NO_RCV_ Disables checksum calculation for received CHECKSUM data. UCX$C_NO_SND_ Disables checksum calculation for CHECKSUM transmitted data. UCX$C_NO_CHECKSUM Disables checksum calculation altogether. UCX$C_SNDBUF Gets the socket send quota. UCX$C_TYPE Obtains the socket type. UCX$C_USELOOPBACK TCP/IP socket option. Shortens the data transfer time when the transfer is local to the host. This improves the performance of the local TCP/IP transfer process and results in a lower load on the CPU when applications using local transfer are active. Unsupported socket options are ignored. TCP/IP Options describes the TCP/IP options for the UCX$C_TCPOPT parameter type. IP Options describes the options for the UCX$C_IPOPT parameter type. Table 1-10 TCP/IP Options TCP/IP Option Description UCX$C_TCP_PROBE_ TCP/IP protocol option. Specifies the time IDLE interval for the KEEPALIVE probe, as well as for the connection establishing the timeout. UCX$C_TCP_DROP_ TCP/IP protocol option. Specifies the time IDLE interval after which the connection will be dropped if the remote host does not respond. Table 1-11 IP Options IP Option Description UCX$C_IP_TTL Time to live (TTL) for a datagram. UCX$C_IP_TOS Type of service (1-byte value). The UCX$C_IOCTL parameter specifies the I/O control parameters. The parameters are specified through a UCX item_list_2 descriptor that points to a list of longword entries. The first longword entry contains the IOCTL command. The second longword contains the address of a buffer structure descriptor. The IOCTL commands are listed in IOCTL Commands. Table 1-12 IOCTL Commands Parameter StructurIOCTL Command Description Integer SIOCATMARK Determines if you are at the OOB character mark. Integer FIONREAD Obtains the number of bytes that are queued in the socket receive queue. You can use one $QIO system service call with the IO$_SENSEMODE modifier for multiple operations. For example, a $QIO system service could specify a list of socket options or a list of IOCTL commands, combined with a local socket name or peer socket name. When the software detects an error, the iosb argument contains the error and parameter address or value that was at fault. The UCX software sequentially processes parameters in this order: p3, p4, p6. You can specify multiple lists of socket options or IOCTL commands. If you duplicate a parameter or IOCTL command in one or more lists, the value returned is the last option or IOCTL command read. 7 Condition_Values_Returned SS$_ACCVIO Programming error. You attempted to access an invalid memory location or buffer. SS$_BADPARAM Programming error. You specified a $QIO function with an invalid parameter that resulted from one of the following: 1. You attempted to execute the IO$_SENSEMODE function without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. 2. You made an error while specifying a socket option. SS$_DEVINACT INET management error. The driver was not started. Execute a UCX START COMMUNICATION command before issuing $QIO functions. SS$_DEVNOTMOUNT INET management error. You improperly executed the INET startup procedure. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again. SS$_ILLCNTRFUNC Programming error. The operation is unsupported for one of the following reasons: 1. You issued an invalid IO$_SENSEMODE function for the interface. The interface does not have an IOCTL routine. 2. You issued a IO$_SENSEMODE function that requires a socket, but the device did not have one. Create a socket and then issue the function. 3. An unsupported operation was performed on at least one of the following protocols: raw IP, datagram, or stream sockets. SS$_INSFMEM INET management or programming error. Do one of the following: 1. Set a higher quota for the dynamic buffer space. 2. Shut down the internet and restart with larger static buffer space. SS$_IVBUFLEN Programming error. You set a socket option buffer with an invalid size. SS$_NOSUCHDEV Programming error or INET management error. An INET address is not in the Address Resolution Protocol (ARP) table. An attempt to show or delete an ARP table entry failed. SS$_NOLINKS Programming error. 1. Stream socket - You did not connect the socket. 2. Datagram or raw IP - You did not specify an INET port and address with an IO$_ACCESS system service call. 3. You used the IO$_SENSEMODE system service call to request the name of a peer socket without first issuing calls to connect the socket or establish the peer socket. SS$_NOOPER Programming error. You attempted to get ARP information without having OPER privileges. SS$_PROTOCOL Programming error. You attempted to set socket options on a closed socket. SS$_SHUT The network is being shut down. SS$_UNREACHABLE Programming error. Network is unreachable or the network address is invalid. 1. You attempted to create a permanent ARP table with the network part of the INET address being zero. 2. You attempted to create a route entry with the network part of the INET address being zero. 6 IO$_SETMODE/IO$_SETCHAR The Set Mode and Set Characteristics I/O functions perform mode, operational, and program/driver interface operations with the internet device socket. These two functions work in exactly the same manner. They take the following form: o IO$_SETMODE o IO$_SETCHAR The protocol you use determines when you can change the mode or characteristics: o Connectionless protocols (datagram or raw IP ) - Can be changed any time. o Connection-oriented protocols (TCP/IP) - Can only be changed when the device socket is closed, such as before a connection is established (opened) or after the connection is closed. While a connection is open (active), only parameters that do not affect the connection characteristics may be changed. The routine processes parameters sequentially. If it finds an error, the routine aborts. Any parameters correctly specified before the routine encounters an error are properly processed before the routine aborts. The equivalent C Socket functions are socket(), bind(), listen(), setsockopt() or a call to the ioctl program. 7 Arguments p1 UCX usage socket definition (socket type, protocol, and INET domain) type longword (unsigned) access read only mechanism by reference The p1 argument specifies the address of a buffer containing the socket characteristics. The C Socket equivalent for this is socket(). The socket characteristics buffer is one longword. The first two bytes contain the protocol, the third byte contains the socket type (protocol type), and the fourth byte contains the domain name (the internet, by default). Both the protocol and the socket type are contained in one longword value. Valid Protocols for IO$_SETMODE and IO$_SETCHAR lists the valid protocols. Table 1-13 Valid Protocols for IO$_SETMODE and IO$_SETCHAR Protocol Description UCX$C_TCP TCP/IP UCX$C_UDP UDP/IP UCX$C_RAW_IP IP Valid Socket Types for IO$_SETMODE and IO$_SETCHAR lists the valid socket types. Table 1-14 Valid Socket Types for IO$_SETMODE and IO$_SETCHAR Socket Type Description UCX$C_STREAM The communications protocol is a bidirectional, reliable, sequenced, and unduplicated data flow without record boundaries. UCX$C_DGRAM The communications protocol is a bidirectional data flow with record boundaries. There are no provisions for sequence, reliability, or duplication of messages. UCX$C_RAW Allows access to the lower layer (IP layer) of the internet communication protocol. It is used to develop new communication protocols that are to be layered on the IP layer. If the image that creates the socket runs in a process that has a privileged UIC or has SYSPRV, BYPASS, or OPER privileges, the socket is marked privileged. NOTE The p2 argument is not used with the IO$_SETMODE routine. It is used when you specify either the IO$M_OUTBAND, IO$M_READATTN, or IO$M_WRTATTN function modifiers. See the descriptions for IO$_SETMODE|IO$M_OUTBAND, IO$_SETMODE|IO$M_READATTN, and IO$_SETMODE|IO$M_WRTATTN for details. p3 UCX usage local socket name type longword (unsigned) access read only mechanism by descriptor The p3 argument specifies the address of a UCX item_list_2 descriptor of a buffer that specifies the local socket name (port and local host internet address). The parameter name for the descriptor is UCX$C_SOCK_NAME, which is defined in the UCX$INETDEF symbol definition file. The C Socket equivalent is bind(). p4 UCX usage number of connections to accept type byte (unsigned) access read only mechanism by value The p4 argument specifies the number of connections that can be established simultaneously and held by the listener socket before the program accepts the connections on the socket associated with the UCX device (TCP/IP only). If more connections are received than have been specified, the the additional connections are rejected. The C Socket equivalent is listen(). p5 UCX usage UCX item_list_2 type longword (unsigned) access read only mechanism by descriptor The p5 argument specifies the address of a descriptor that lists item_list_2 descriptors. The C Socket equivalent is setsockopt(). Each UCX item_list_2 descriptor describes a group of parameters of a specific type. The following are the parameter types for the UCX descriptor to which the p5 points: o UCX$C_SOCKOPT (communication socket option parameter) o UCX$C_TCPOPT (TCP options) o UCX$C_IPOPT (IP options) o UCX$C_IOCTL (I/O control parameter) You can use one $QIO system call to set up several socket options at once. The UCX item_list_2 descriptor points to an integer (with the length set to the size of the integer). The integer contains zero to clear the option and nonzero to set the option. The UCX$C_SOCKOPT parameter specifies the communication socket options. Communications Socket Options describes the socket options you use with the UCX$C_SOCKOPT parameter type. Unsupported socket options are ignored. TCP Options describes the socket options you use with the UCX$C_ TCPOPT parameter type. IP Options describes the options you use with the UCX$C_IPOPT parameter type. Table 1-15 Communications Socket Options Socket Option Description UCX$C_KEEPALIVE Detects broken idle connections (connections in which the remote end point has dropped the connection) and keeps the connection alive for the specified maximum idle time (optional for TCP/IP). UCX$C_DONTROUTE Uses interface addresses only. UCX$C_BROADCAST Permits sending of broadcast messages. A broadcast internet address is the system number defined by using the connection control program. This option requires a system UIC, SYSPRV, BYPASS, or OPER privilege in order to be set. Optional for a connectionless datagram. UCX$C_LINGER Lingers on Close operation if data is present; that is, waits for all messages to be sent (optional for TCP/IP). UCX$C_OOBINLINE Leaves the received OOB data in line. UCX$C_RCVBUF Sets the socket receive quota. This option requires a system UIC, SYSPRV, BYPASS, or OPER privilege to be set. UCX$C_REUSEADDR Allows reuse of the local socket address. The local socket address is the 16-byte structure that contains the address family, port, and host IP address. The UCX$C_REUSEADDR option enables reuse of the local port number portion. It works only with connection-oriented protocols (in particular, TCP/IP), where a connection is characterized for its entire life by the local address, local port, remote host, and remote port. The option can be used for a client that always binds to a known or well-defined port number. It allows several instances of the client image running on one host to connect to the same server on different hosts. UCX$C_SNDBUF Sets the socket send quota. This option requires a system UIC, SYSPRV, BYPASS, or OPER privilege to be set. UCX$C_NO_RCV_CHECKSUM Disables checksum calculation for received data. UCX$C_NO_SND_CHECKSUM Disables checksum calculation for transmitted data. UCX$C_NO_CHECKSUM Disables checksum calculation altogether. UCX$C_SHARE Allows multiple processes to share the socket. UCX$C_FULL_DUPLEX_ When set before a close operation, CLOSE both receive and transmit sides of the communications are closed. Table 1-16 TCP Options TCP Option Description UCX$C_USELOOPBACK TCP/IP socket option. Shortcuts the data transfer when the transfer is local to the host. This improves the performance of the local TCP/IP transfer process and results in a lower load on the CPU when applications using local transfer are active. UCX$C_TCP_NODELAY TCP/IP option. Specifies that the send operation will not be delayed to coalesce packets. UCX$C_TCP_PROBE_IDLE TCP/IP option. Specifies the time interval for the KEEPALIVE probe, as well as for the connection establishing the timeout. UCX$C_TCP_DROP_IDLE TCP/IP option. Specifies the time interval after which the connection is dropped. Table 1-17 IP Options IP Option Description UCX$C_IP_TTL Time to live (TTL) for a datagram. UCX$C_IP_TOS Type of service (1-byte value) The UCX$C_IOCTL parameter specifies the I/O control parameters. The list of the IOCTL parameters contains two entries of longwords: the IOCTL command (first longword) and the address of the required buffer structure (second longword). To set UCX$C_IOCTL, you need a system UIC, SYSPRV, BYPASS, or OPER privileges. You can specify multiple IO$_SETMODE parameters with one $QIO system service call. For example, one $QIO system service call could specify a list of socket options or a list of IOCTL commands, combined with a local socket name. When an error is detected, the iosb argument specifies the error and parameter address or value that was at fault. The UCX software processes parameter values for arguments in the following order: p1, p3, p4, and p5. You can specify multiple lists of socket options or IOCTL commands. If a parameter, parameter list, or IOCTL command is duplicated by using the same return address, then the value returned is the last option or IOCTL command. 7 Condition_Values_Returned SS$_ABORT Programming error, INET management error, or hardware error. The route entry already exists. An attempt to add a route entry with IO$_SETMODE (IOCTL) system service call failed. SS$_ACCVIO Programming error. You tried to access an invalid memory location or buffer. SS$_BADPARAM Programming error. You specified a $QIO function with an invalid parameter that was a result of one of the following: 1. You tried to execute IO$_SETMODE function (all subfunctions, except socket creation) without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. 2. You made an error specifying a socket option. SS$_DEVACTIVE INET management error. You attempted to change the static INET parameters. If new parameters are needed, shut down the internet, reset the static parameters, and issue the START COMMUNICATION command. SS$_DEVINACT INET management error. The driver is not started. Issue a UCX START COMMUNICATION command before issuing $QIO functions. SS$_DEVNOTMOUNT INET management error. You improperly executed the INET startup procedure. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again. SS$_DUPLNAM Programming error. The port being bound is already in use. You attempted to bind the socket to an address and port and the operation failed. SS$_EXQUOTA Programming or INET management error occurred for one of the following reasons: 1. You tried to create a new socket with the IO$_SETMODE function, but the maximum number of sockets was exceeded. Increase the maximum number of sockets (INET parameter). 2. The number of sockets specified with the IO$_SETMODE (listen) exceeds the maximum number of sockets. Increase the maximum number of sockets (INET parameter) or reduce the listen parameter (the number of sockets the listener socket can create). SS$_FILALRACC Programming error. The INET address is already in use. You attempted to bind the socket to an address and port and the operation failed. SS$_INSFMEM Programming or system management error. There are not enough resources to allocate a new socket. SS$_ILLCNTRFUNC Programming error. The operation is not supported for one of the following reasons: 1. You used an invalid IO$_SETMODE function for the interface that does not have an IOCTL routine. 2. You tried to perform an IO$_SETMODE function that required a socket, but the device did not have one. Create a socket before issuing the function. SS$_IVADDR Programming error. The INET address you specified using the IO$_SETMODE function was not placed into the system. This resulted in an invalid port number or INET address combination. The INET address was invalid for one of the following reasons: 1. Port zero and INET address zero are not allowed or port zero is not allowed when using an IO$_ACCESS or IO$_WRITEVBLK function. 2. You attempted to exceed the limit of allowable permanent entries in the ARP table. 3. You attempted to bind a raw IP socket when there are no interfaces defined in the system. 4. You attempted to bind a raw IP socket to a null INET address. SS$_IVBUFLEN Programming error. The socket option buffer has an invalid size. SS$_NOLICENSE Programming or system management error. A DIGITAL TCP/IP Services for OpenVMS license is not present. SS$_NOOPER Programming or INET management error. You attempted to execute an I/O function that needs the OPER privilege. SS$_NOPRIV Programming or INET management error. There are not enough privileges for the attempted operation for one of the following reasons: 1. You attempted to broadcast an IP datagram on a process without system UIC, SYSPRV, BYPASS, or OPER privileges. 2. You attempted to use a reserved port number lower than 1024. 3. You attempted to access a process that requires system UIC, SYSPRV, or BYPASS privileges. 4. You attempted to use raw IP on a privileged socket that requires the SYSPRV or BYPASS privileges. SS$_NOSUCHDEV Programming error or INET management error. Your attempt to show or delete an ARP table entry failed because the INET address is not found. SS$_NOSUCHNODE Programming error or INET management error. Your attempt to delete a route from the routing table failed because the entry was not found. SS$_PROTOCOL Programming error. You specified a protocol or address family that caused an error for one of the following reasons: 1. You specified an invalid protocol type at socket creation. 2. You specified an unsupported protocol. 3. You specified a protocol type that was not found in the internal tables. 4. The address family is unsupported for one of the following reasons: o You specified an unsupported address family with the IO$_SETMODE subfunction. Instead, specify the UCX$C_AF_INET or UCX$C_UNSPEC address family. o You specified an unsupported address family for a remote INET address with the IO$_ACCESS or IO$_WRITEVBLK function. Instead, specify the UCX$C_AF_ INET address family. o You specified an unsupported address family for the local INET address with the IO$_SETMODE function. Instead, specify the UCX$C_AF_INET address family. o You specified an unsupported address family for the INET address of the routing module. Instead, specify the UCX$C_AF_INET address family. SS$_SHUT The network is being shut down. 6 IO$_SETMODE|IO$M_OUTBAND The IO$_SETMODE|IO$M_OUTBAND function/modifier combination requests that the asynchronous system trap (AST) for an out- of-band (OOB) character be delivered to the requesting process. This is to be done only when an OOB character is received on the socket and there is no waiting read request. The socket is a TCP /IP (stream) socket. 7 Arguments p1 UCX usage ast_procedure type procedure entry mask access call without stack unwinding mechanism by reference To enable the AST, the p1 argument is the address of the OOB character AST routine. To disable the AST, p1 equals 0. p2 UCX usage user_arg type longword (unsigned) access read only mechanism by value AST parameter to be delivered to the AST routine specified by the p1 argument. p3 UCX usage acmode type longword (unsigned) access read only mechanism by value Access mode to deliver the AST. 7 Description The Enable OOB character AST function allows an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly reenable AST delivery before a new AST can be delivered. This function is subject to AST quotas. 7 Condition_Values_Returned SS$_ABORT Programming, INET management, or hardware error. The route entry already exists. You attempted to add a route entry with the IO$_SETMODE function and the operation failed. SS$_ACCVIO Programming error. You attempted to access an invalid memory location or buffer. SS$_BADPARAM Programming error. You specified a $QIO function with an invalid parameter that occurred for one of the following reasons: 1. You attempted to execute an IO$_SETMODE function (all subfunctions, except socket creation) without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. 2. You made an error specifying a socket option. SS$_DEVACTIVE INET management error. You attempted to change the static INET parameters. If new parameters are needed, shut down the internet, reset the static parameters, and issue the START COMMUNICATION command. SS$_DEVINACT INET management error. The driver was not started. Issue a UCX START COMMUNICATION command before issuing $QIO functions. SS$_DEVNOTMOUNT INET management error. You improperly executed the INET startup procedure. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again. SS$_DUPLNAM Programming error. You are attempting to bind a port that is already in use. An attempt to bind the socket to an address and port failed. SS$_EXQUOTA Programming or INET management error that occurred because of one of the following reasons: 1. You attempted to create a new socket with the IO$_SETMODE function but it failed because the maximum number of sockets was exceeded. Increase the maximum number of sockets (INET parameter). 2. The number of sockets specified with the IO$_SETMODE (listen) exceeds the maximum number of sockets. Increase the maximum number of sockets (INET parameter) or reduce the listen parameter (the number of sockets that the listener socket can create). SS$_FILALRACC Programming error. INET address is already in use. An attempt to bind the socket to an address and port failed. SS$_INSFMEM Programming or system management error: Not enough resources to allocate new socket. SS$_ILLCNTRFUNC Programming error. Operation is not supported because of one of the following reasons: 1. You used an invalid IO$_SETMODE (IOCTL) function for the interface. The interface does not have an IOCTL routine. 2. You attempted to perform an IO$_SETMODE (IOCTL) function that required a socket, but the device did not have one. Create a socket and issue the IOCTL function. SS$_IVADDR Programming error. The specified INET address is not in the system, and an invalid port number or an invalid INET address combination was specified with an IO$_SETMODE function (a bind) for one of the following reasons: 1. An attempt to bind the address failed because the INET address is not in the system, port zero and INET address zero are not allowed, or port zero is not allowed when using an IO$_ACCESS or IO$_WRITEVBLK function. 2. An attempt to make a permanent entry in an ARP table that was full failed. 3. An attempt was made to bind an IP socket (raw IP) when there are no interfaces defined in the system. 4. An attempt was made to bind an IP socket (raw IP) to a null INET address. SS$_IVBUFLEN Programming error. The socket option buffer has an invalid size. SS$_NOLICENSE Programming or system management error. UCX license not present. SS$_NOOPER Programming or INET management error. An attempt was made to execute an I/O function that needs the OPER privilege. SS$_NOPRIV Programming or INET management error. Not enough privileges for the attempted operation for one of the following reasons: 1. Broadcasting an IP datagram was denied because the process does not have a system UIC, SYSPRV, BYPASS, or OPER privileges. 2. An attempt was made to use a reserved port number lower than 1024. 3. An operation accesses only processes that have a system UIC, SYSPRV, or BYPASS privilege. 4. Raw IP protocol can be used only on privileged sockets. The process must have a SYSPRV or BYPASS privilege. SS$_NOSUCHDEV Programming error or INET management error. An INET address is not in the ARP table. An attempt to show or delete an ARP table entry failed. SS$_NOSUCHNODE Programming or INET management error. An attempt to delete a route from the routing table failed because a route entry was not found. SS$_PROTOCOL Programming error due to one of the following reasons: 1. The protocol type specified at socket creation is not valid. 2. The protocol is not supported. 3. The protocol type specified is not found in the internal tables and therefore is an invalid type. 4. The address family is not supported for one of the following reasons: o The address family specified with an IO$_SETMODE function (IOCTL subfunction) is not supported. The address family should be the UCX$C_AF_INET or UCX$C_ UNSPEC address family. o The address family of the remote INET address specified with an IO$_ACCESS or IO$_WRITEVBLK function is not supported (UDP/IP or TCP/IP). The address family should be the UCX$C_AF_INET address family. o The address family of the local INET address specified with an IO$_SETMODE (bind) function is not supported. The address family should be the UCX$C_AF_ INET address family. o The address family of the INET address specified in a request to the routing module is not supported. The address family should be the UCX$C_AF_INET address family. SS$_SHUT The network is being shut down. 6 IO$_SETMODE|IO$M_READATTN The IO$_SETMODE|IO$M_READATTN function/modifier combination requests that an Attention AST be delivered to the requesting process when a data packet is received on the socket and there is no waiting read request. 7 Arguments p1 UCX usage procedure entry mask type call without stack unwinding access by reference mechanism 0 To enable the AST, the p1 argument is the address of the Read Attention AST routine. To disable the AST, set p1 to 0. p2 UCX usage user_arg type longword (unsigned) access read only mechanism by value AST parameter to be delivered to the AST routine. p3 UCX usage acmode type longword (unsigned) access read only mechanism by value Access mode to deliver the AST. 7 Description The Enable Read Attention AST function enables an Attention AST to be delivered to the requesting process once only. After the AST occurs, the function must explicitly re-enable AST delivery before the AST can occur again. The function is subject to AST quotas. Consider the following when using IO$M_READATTN: o There is a one-to-one correspondence between the number of times you enable an Attention AST and the number of times the AST is delivered. For example, for each enabled AST, one AST is delivered. If you enable an Attention AST several times, several ASTs are delivered for one event when an event occurs. o If an out-of-band (OOB) Attention AST is enabled, the OOB AST is delivered, regardless of the following: - A Read Attention AST enabled - The UCX$C_OOBINLINE socket option - A READ $QIO waiting for completion on the socket If the UCX$C_OOBINLINE option is set, then a waiting READ $QIO is completed and the OOB character is returned in the data stream. o If both an OOB AST and a Read Attention AST are enabled, only the OOB AST is delivered when an OOB character is received. o If a Read Attention AST is enabled and the UCX$C_OOBINLINE socket option is set, a waiting READ $QIO completes and the OOB character is returned in the data stream. o If a Read Attention AST is enabled and the UCX$C_OOBINLINE socket option is not set (clear), the Read Attention AST is delivered when an OOB character is received, regardless of whether a READ $QIO is waiting for completion. In this case, the OOB character is not returned in the data stream. Therefore, if the OOB character is the only character received, the READ $QIO does not complete. 7 Condition_Values_Returned SS$_ABORT Programming, INET management, or hardware error. The route entry already exists, so your attempt to add a route entry using the IO$_SETMODE function failed. SS$_ACCVIO Programming error. You attempted to access an invalid memory location or buffer. SS$_BADPARAM Programming error. The parameter you specified for a $QIO function was invalid for one of the following reasons: 1. You attempted to execute the IO$_SETMODE subfunctions without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. 2. You made an error specifying a socket option. SS$_DEVACTIVE INET management error. You attempted to change the static INET parameters. If you need new parameters, shut down the internet, reset the static parameters, and issue the START COMMUNICATION command. SS$_DEVINACT INET management error. The driver was not started. Issue a UCX START COMMUNICATION command before issuing $QIO functions. SS$_DEVNOTMOUNT INET management error. You improperly executed the startup procedure. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again. SS$_DUPLNAM Programming error. You attempted to bind a port already in use so the operation to bind the socket to the address and port failed. SS$_EXQUOTA Programming or INET management error. The quota for the valid number of sockets caused an error for one of the following reasons: 1. You attempted to exceed the maximum number of sockets by creating new socket with the IO$_SETMODE function. Increase the maximum number of allowable sockets (INET parameter) before creating more sockets. 2. You specified a number of sockets with the IO$_SETMODE function that exceeds the maximum number of sockets allowed. Increase the maximum number of sockets (INET parameter) or reduce the number of sockets that the listener socket can create (listen parameter). SS$_FILALRACC Programming error. You attempted to bind the socket to an address that is already in use and the operation failed. SS$_INSFMEM Programming or system management error. Your system does not have enough resources to allocate new socket. SS$_ILLCNTRFUNC Programming error. Operation is not supported. 1. Invalid IO$_SETMODE (IOCTL) function was used for the interface. The interface does not have an IOCTL routine. 2. An attempt was made to perform an IO$_ SETMODE (IOCTL) function that required a socket, but the device did not have one. Create a socket and issue the IOCTL function. SS$_IVADDR Programming error. The specified INET address is not in the system, and an invalid port number or an invalid INET address combination was specified with an IO$_SETMODE function (a bind). 1. An attempt to bind the address failed because the INET address is not in the system, port zero and INET address zero are not allowed, or port zero is not allowed when using an IO$_ACCESS or IO$_WRITEVBLK function. 2. An attempt to make a permanent entry in the ARP table failed because of lack of space. Too many permanent entries. 3. An attempt was made to bind an IP socket (raw IP) when there are no interfaces defined in the system. 4. An attempt was made to bind an IP socket (raw IP) to a null INET address. SS$_IVBUFLEN Programming error. The socket option buffer has an invalid size. SS$_NOLICENSE Programming or system management error. UCX license not present. SS$_NOOPER Programming or INET management error. An attempt was made to execute an I/O function that needs the OPER privilege. SS$_NOPRIV Programming or INET management error. Not enough privileges for the attempted operation. 1. Broadcasting an IP datagram was denied because the process does not have a system UIC, SYSPRV, BYPASS, or OPER privileges. 2. An attempt was made to use a reserved port number lower than 1024. 3. An operation accesses only processes that have a system UIC, SYSPRV, or BYPASS privilege. 4. Raw IP protocol can be used only on privileged sockets. The process must have a SYSPRV or BYPASS privilege. SS$_NOSUCHDEV Programming error or INET management error. An INET address is not in the ARP table. An attempt to show or delete an ARP table entry failed. SS$_NOSUCHNODE Programming error or INET management error. An attempt to delete a route from the routing table failed because a route entry was not found. SS$_PROTOCOL Programming error. 1. The protocol type specified at socket creation is not valid. 2. The protocol is not supported. 3. The protocol type specified is not found in the internal tables. It is an invalid type. 4. The address family is not supported: o The address family specified with an IO$_SETMODE function (IOCTL subfunction) is not supported. The address family should be the UCX$C_AF_INET or UCX$C_ UNSPEC address family. o The address family of the remote INET address specified with an IO$_ACCESS or IO$_WRITEVBLK function is not supported (UDP/IP or TCP/IP). The address family should be the UCX$C_AF_INET address family. o The address family of the local INET address specified with an IO$_SETMODE (bind) function is not supported. The address family should be the UCX$C_AF_ INET address family. o The address family of the INET address that is specified in a request to the routing module is not supported. The address family should be the UCX$C_AF_ INET address family. SS$_SHUT The network is being shut down. 6 IO$_SETMODE|IO$M_WRTATTN The IO$_SETMODE|IO$M_WRTATTN function/modifier combination (IO$M_ WRTATTN is Enable Write Attention AST (asynchronous system trap)) requests that an Attention AST be delivered to the requesting process when a data packet can be queued to the socket. For TCP sockets, this occurs when the TCP transmit queue is available. 7 Arguments p1 UCX usage procedure entry mask type call without stack unwinding access by reference mechanism 0 To enable the AST, the p1 argument is the address of the Write Attention AST routine. To disable the AST, p1 is set to 0. p2 UCX usage user_arg type longword (unsigned) access read only mechanism by value AST parameter to be delivered to the AST routine. p3 UCX usage acmode type longword (unsigned) access read only mechanism by value Access mode to deliver the AST. 7 Description The Enable Write Attention AST function enables an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly re-enable AST delivery before the AST can occur again. The function is subject to AST quotas. There is a one-to-one correspondence between the number of times you enable an Attention AST and the number of times the AST is delivered. For example, for each enable AST, one AST is delivered. If you enable an Attention AST several times, several ASTs are delivered for one event when the event occurs. You can use the UCX command SHOW DEVICE_SOCKET to display information on the socket's characteristics, options, and state. 7 Condition_Values_Returned SS$_ABORT Programming error, INET management error, or hardware error. The route you specified with the IO$_SETMODE function already exists. Therefore, the operation failed. SS$_ACCVIO Programming error. You attempted to access an invalid memory location or buffer. SS$_BADPARAM Programming error. The parameter you specified for the $QIO I/O function was invalid for one of the following reasons: 1. You attempted to execute the IO$_SETMODE functions without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. 2. You made an error when specifying a socket option. SS$_DEVACTIVE INET management error. You attempted to change the static INET parameters. If you need new parameters, shut down the internet, reset the static parameters, and issue the START COMMUNICATION command. SS$_DEVINACT INET management error. The driver is not started. Issue a UCX START COMMUNICATION command before issuing $QIO functions. SS$_DEVNOTMOUNT INET management error. The INET startup procedure was improperly executed. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again. SS$_DUPLNAM Programming error. Port that is being bound is already in use. An attempt to bind the socket to an address and port failed. SS$_EXQUOTA Programming or INET management error. 1. You attempted to create a new socket with the IO$_SETMODE function and it failed because the maximum number of sockets was exceeded. Increase the maximum number of sockets (INET parameter) and then create a new socket. 2. The number of sockets you specified with the IO$_SETMODE function exceeds the allowable maximum number of sockets. Increase the maximum number of sockets (INET parameter) or reduce the number of sockets that the listener socket can create (listen parameter). SS$_FILALRACC Programming error. Because the INET address is already in use, your attempt to bind the socket to an address and port failed. SS$_INSFMEM Programming or system management error. There are not enough resources to allocate new socket. SS$_ILLCNTRFUNC Programming error. You specified an operation that is unsupported for one of the following reasons: 1. You used an invalid IO$_SETMODE function for the interface. The interface does not have an IOCTL routine. 2. You attempted to execute an IO$_SETMODE function that required a socket, but the device did not have one. Instead, create a socket and issue the function. SS$_IVADDR Programming error. You specified an invalid port number and INET address combination with the IO$_SETMODE bind function. This caused the operation to fail for one of the following reasons: 1. You specified an illegal combination of port zero and INET address zero. 2. You specified port zero when using an IO$_ ACCESS or IO$_WRITEVBLK function. 3. When you attempted to make a permanent entry in the ARP table, the operation failed because of lack of space. There are too many permanent entries. 4. You attempted to bind a raw IP socket when there were no interfaces defined in the system. 5. You attempted to bind a raw IP socket to a null INET address. SS$_IVBUFLEN Programming error. You specified an invalid size for the socket option buffer. SS$_NOLICENSE Programming or system management error. There is no DIGITAL TCP/IP Services for OpenVMS license present. SS$_NOOPER Programming or INET management error. You attempted to execute an I/O function that needs the OPER privilege. SS$_NOPRIV Programming or INET management error. You attempted to execute an operation that failed for one of the following reasons: 1. You cannot broadcast an IP datagram for a process if you do not have system UIC, SYSPRV, BYPASS, or OPER privileges. 2. You attempted to use a reserved port number lower than 1024. 3. You attempted to access a process when you do not have system UIC, SYSPRV, or BYPASS privileges. 4. You attempted to use raw IP on a socket that is not a privileged sockets. To do this, the process must have SYSPRV or BYPASS privilege. SS$_NOSUCHDEV Programming error or INET management error. You attempted to show or delete an entry in the ARP table. However, because the INET address was not in the ARP table, the operation failed. SS$_NOSUCHNODE Programming error or INET management error. You attempted to delete a route from the routing information table (RIT). However, because the route was not found in the RIT, the operation failed. SS$_PROTOCOL Programming error. 1. You specified an invalid protocol type when you created the socket. 2. You specified an unsupported protocol. 3. You specified a protocol type that is invalid because it is not found in the internal tables. 4. You specified an address family that is not supported for one of the following reasons: o You specified an address family with an IO$_SETMODE subfunction. Instead, specify the UCX$C_AF_INET or UCX$C_ UNSPEC address family. o You specified an address family of the remote INET address for a datagram or stream socket with an IO$_ACCESS or IO$_ WRITEVBLK function. Instead, specify the UCX$C_AF_INET address family. o You specified an address family of the local INET address with an IO$_SETMODE bind function. Instead, specify the UCX$C_AF_INET address family. o You made a request to the routing module by specifying the address family of the INET address. Instead, specify the UCX$C_AF_INET address family. SS$_SHUT The network is being shut down. 6 IO$_WRITEVBLK Write I/O functions provide direct transfer of data from the virtual address space of the user's process to an internet host or port. The DIGITAL TCP/IP Services for OpenVMS product provides the WRITE I/O function code IO$_WRITEVBLK, which writes a user buffer for stream sockets, datagrams, or raw IP. If you specify multiple buffers, the system sends data from buffers in the order specified by the p5 list. For UDP and raw IP, the TCP/IP software sends the data in one datagram. The data to be sent is buffered by TCP/IP before being transmitted to the remote host. For a TCP socket, if the socket transmit queue is full, the Write I/O operation will be blocked until the transmit queue has enough room for the user data. For UDP and raw IP sockets, if the user data is greater than the transmit (send) socket quota, an error code is returned (SS$_ TOOMUCHDATA). The equivalent C Socket functions are recv*, send*(), sendto() and write(). Programming examples for the IO$_WRITEVBLK routine follow this command description. IO$_WRITEVBLK Function (MACRO- 32 Programming) uses the MACRO-32 programming language and IO$_WRITEVBLK Function - Vectored (C Programming) uses the C programming language to read a vectored buffer. IO$_WRITEVBLK Function (C Programming) uses the C programming language to read from an INET driver. 7 Arguments p1 UCX usage buffer type longword (unsigned) access read only mechanism by reference The p1 argument specifies the starting virtual address of the buffer containing the data to be transmitted. p2 UCX usage buffer length type longword (unsigned) access read only mechanism by value The p2 argument specifies the size (in bytes) of the buffer containing the data to be transmitted. p3 UCX usage remote socket name (message source) type longword (unsigned) access read only mechanism by descriptor The p3 argument specifies the address of a UCX item_list_2 descriptor. This descriptor points to a buffer that contains the remote port and remote host internet address (socket name) of the message destination. p4 UCX usage flags type longword (unsigned) access read only mechanism by value The p4 argument specifies the flags for the Write operation. Valid Write Flags for the p4 Argument describes the valid flags for this argument. Table 1-18 Valid Write Flags for the p4 Argument Flag Description UCX$C_MSG_OOB Writes an out-of-band (OOB) byte. UCX$C_MSG_DONTROUTE Sends the message directly without routing. UCX$C_MSG_NBIO Completes the I/O operation and returns an error if a condition that would cause the I/O operation to be blocked. Similar to using IO$M_NOWAIT. p5 UCX usage UCX item_list_2 type longword (unsigned) access read only mechanism by descriptor The p5 argument specifies the address for the descriptor of an input parameter list. The maximum number of buffers you can specify with the p5 argument is 16. The p1 and p2 arguments and the p5 argument are mutually exclusive. You either use p1 and p2 or you use p5. The software first checks to see if the p1 argument is being used. If p1 is not used, it checks to see if the p5 argument is being used. If neither the p1 nor the p5 argument is being used, an error code is produced. The resulting transfer-length value of the I/O status block is the sum of the bytes transferred in the multiple buffers. 7 Function_Modifiers IO$M_INTERRUPT Sends an out-of-band byte to a target process. At the remote process, the byte is delivered to the user through the data receive mechanism. IO$M_NOWAIT Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the I/O operation to be blocked, the system completes the I/O operation and returns the error code SS$_SUSPENDED. When using this function modifier, always check the message length in the IOSB to ensure that all data is transferred. If only 1 byte of data is transferred, the function returns a success status even if data is not completely transferred. 7 Condition_Values_Returned SS$_ABORT Programming error, INET management error, or hardware error. The execution of the I/O was aborted. SS$_ACCVIO Programming error. An attempt was made to access an invalid memory location or buffer. SS$_BADPARAM Programming error. A $QIO I/O function was specified using an invalid parameter. 1. An attempt was made to execute an IO$_ WRITEVBLK function without specifying a device socket. First create a device socket by issuing an IO$_SETMODE function and the proper arguments. 2. An attempt was made to issue an IO$_ READVBLK or IO$_WRITEVBLK function that does not specify a correct buffer address (p1, p5, or p6 is null). 3. An attempt was made to issue an IO$_ READVBLK or IO$_WRITEVBLK that specifies an invalid vectored buffer (p5 or p6 specifies an invalid address descriptor). SS$_CANCEL Warning code. The I/O operation was canceled by issuing a $CANCEL system service. SS$_DEVINACT INET management error. The driver was not started. A UCX START COMMUNICATION command must be executed before issuing any $QIO function. SS$_DEVNOTMOUNT INET management error. The INET startup procedure was executed improperly. The driver was loaded, but the INET_ACP was not activated. SS$_EXQUOTA Returned when process resource mode wait is disabled. There is no internet request packet (IRP) available for completing the request. Increase the buffered I/O quota. SS$_FILALRACC Programming error. 1. INET address is already in use. An attempt was made to bind the socket to an address but the port failed. 2. IP protocol (raw socket). An attempt was made to specify a remote INET socket address with an IO$_WRITEVBLK function, while an INET address was already specified with an IO$_ACCESS function. 3. UDP/IP protocol. An attempt was made to specify a remote INET socket address with an IO$_WRITEVBLK function, while an INET address was already specified with the IO$_ ACCESS function. SS$_ILLCNTRFUNC Programming error. Unsupported operation on the protocol (IP, UDP/IP, TCP/IP). SS$_INSFMEM INET management or programming error returned when process resource mode wait is disabled. Not enough system space for buffering user data. A higher quota for socket buffer space needs to be set, or the internet needs more dynamic buffer space (number of dynamic clusters should be increased). SS$_IVADDR Programming error. The specified INET address is not in the system, and an invalid port number or an INET address combination was specified with an IO$_WRITEVBLK operation. 1. An attempt to bind the socket failed because the INET address is not in the system, port number zero and INET address zero are not allowed, or port zero is not allowed with an IO$_ACCESS or IO$_WRITEVBLK function. 2. An attempt to get an interface INET address, broadcast mask, or network mask failed. 3. A send request was made on a datagram- oriented protocol, but the destination address is unknown or not specified. SS$_IVBUFLEN Programming error. 1. The size of the buffer for an I/O function is insufficient. 2. An attempt was made to issue an IO$_ WRITEVBLK function that specifies a correct buffer address (p1 valid), but does not specify a buffer length (p2 is null). SS$_LINKDISCON Notification. Connection completion return code. The virtual circuit (TCP/IP) was closed at the initiative of the peer. The application must stop sending data and shutdown or close the socket. SS$_PROTOCOL Programming error. The address family of the remote INET address specified with an IO$_ WRITEVBLK function is not supported (UDP/IP or TCP/IP). The address family should be the UCX$C_AF_INET address family. SS$_NOLINKS Programming error. The socket was not connected (TCP/IP) or an INET port and address were not specified with an IO$_ACCESS (UDP/IP or IP). 1. An IO$_WRITEVBLK with no remote INET socket address was issued on a socket that was not the object of an IO$_ACCESS function (raw IP). 2. An IO$_WRITEVBLK with no remote INET socket address was issued on a socket that was not the object of an IO$_ACCESS function (UDP /IP). 3. An attempt was made to disconnect a socket that is not connected, or an attempt was made to issue an IO$_WRITEVBLK or IO$_ READVBLK function on an unconnected socket (TCP/IP). SS$_SHUT The network is being shut down. SS$_SUSPENDED The operation was blocked. A send operation requires system buffer space that is not available. The socket is marked as performing nonblocking operations. SS$_TIMEOUT Programming error, INET management error, or hardware error. 1. A TCP/IP connection timed out after several unsuccessful retransmissions. 2. On a TCP socket where KEEPALIVE is set, the connection was idle for longer than the timeout interval (10 minutes by default). SS$_TOOMUCHDATA Programming or INET management error. The message size was too large. 1. An IP packet that is broadcast cannot be fragmented. 2. The Not Fragment IP flag was set and the IP datagram was too large to be sent without being fragmented. 3. Internal error. The length of the Ethernet datagram does not allow enough space for the minimum IP header. 4. The message to be sent on a UDP/IP or raw IP socket is larger than the socket buffer high water allows. 5. An attempt was made to send or receive more than 16 buffers specified with the p5 argument. SS$_UNREACHABLE Programming error. Either the network address is invalid or the network is unreachable. Hardware error. The data link adapter detected an error and shut itself off. The UCX software is waiting for the adapter to come back on line. Example .titleIwriteITEVBLK Function (MACRO-32 Programming) .ident /01/ ; ; Write a vectored buffer ; $inetsymdef ; INET symbols dev: .ascid /ucx$device:/ ; INET device name channel: .word 0 ; INET channel iostatus: .quad 0 ; I/O status block ; ; INET Socket address definition of the remote host ; Ret_adr: .word INET$C_AF_INET ; INET family .word 5002 ; Port number ; Remote host IP address .byte 128,20,20 ; Network/subnetwork number .byte 156 ; Remote Host number .blkb 8 Ret_len=.-Ret_adr leng: .long 0 ; Return length of Remote IP address ; ; INET Socket address definition of the local host ; Local_adr: .word INET$C_AF_INET ; INET family .word 5001 ; Port number ; Local host IP address .byte 128,20,20 ; Network/subnetwork number .byte 10 ; Local Host number .blkb 8 par11: .word INET$C_UDP ; UDP/IP protocol .word INET_PROTYP$C_DGRAM ; Datagram type of socket ; ; Item_list_2 descriptor for the Remote IP address ; par12: .long ret_len ; Length .address ret_adr ; Buffer address ; ; Item_list_2 descriptor for the Local IP address ; par13: .long ret_len ; Length .address local_adr ; Address ; ; I/O Buffer ; buffer: .blkb 512 buflen=.-buffer .entry start,^m<> . . . ; ; Perform a QIOW write operation ; write: $qiow_s efn=#31,- ; Event flag chan=channel, - ; Channel func=#io$_writevblk,- ; I/O function iosb= iostatus,- ; I/O status p1=buffer,- ; I/O Buffer address p2=#buflen,- ; I/O Buffer length p3=#par12 ; Address of Descriptor ; of buffer of the remote ; Host IP address blbc r0,exit ; Branch if error movzwl iostatus,r0 ; blbc r0,exit ; $dassgn_s chan=Channel ; Deassign the socket device exit: ret ; Exit .end start #module write_vecioRITEVBLK Function - Vectored (C Programming) /* **++ ** ** This example does vectored buffers write ** **-- */ /* ** INCLUDE FILES */ #include <descrip.h> #include <ucx$inetdef.h> /* INET symbol definitions */ #include <iodef.h> /* ** */ struct bvec /* Structure definition for vec buf */ { int lenth ; char *b_adrs ; } ; struct sockaddr { /* Structure definition for socket adrs */ short inet_family ; short inet_port ; char adrs[4] ; char blkb[8] ; } ; struct itlst { int lgth ; struct sockaddr *hst ; } ; main() { int status ; /* For return status */ short channel ; /* INET channel */ short sck_parm[2] ; /* Socket creation parameter */ int iosb [2] ; /* I/O status block */ char buf_1[12],buf_2[12],buf_3[12],buf_4[12] ; struct sockaddr remote_host ; /* Socket adrs definition for rhst */ struct sockaddr local_host ; /* Socket adrs definition for lhst */ struct itlst lhst_adrs ; struct itlst rhst_adrs ; struct bvec buf_vec[5] = { {12, &buf_1 }, {12, &buf_2 }, {12, &buf_3 }, {12, &buf_4 }, {0, 0 } } ; /* Descriptor for Inet device name */ struct dsc$descriptor dev = { 3, DSC$K_CLASS_S, DSC$K_DTYPE_T, "UCX$DEVICE:"} ; /* Descriptor for vectored buffer */ struct dsc$descriptor buf_d = { 0, DSC$K_CLASS_S, DSC$K_DTYPE_T, 0} ; /* Initialize the parameters */ sck_parm[0] = INET$C_UDP ; /* UDP/IP protocol */ sck_parm[1] = INET_PROTYP$C_DGRAM ; /* Datagram type of socket */ /* Itlst for local IP address */ lhst_adrs.lgth = sizeof(local_host); lhst_adrs.hst = &local_host ; rhst_adrs.lgth = sizeof(remote_host) ; rhst_adrs.hst = &remote_host ; buf_d.dsc$a_pointer = buf_vec; buf_d.dsc$w_length = sizeof (bvec) ; /* Initialize socket address for remote host */ remote_host.inet_family = INET$C_AF_INET;/* INET family */ remote_host.inet_port = 0 ; /* Port number */ remote_host.adrs[0] = 128 ; /* Network/subnetwork*/ remote_host.adrs[1] = 45 ; /* number */ remote_host.adrs[2] = 45 ; remote_host.adrs[3] = 175 ; /* Host number */ remote_host.blkb[0] = 0 ; remote_host.blkb[1] = 0 ; remote_host.blkb[2] = 0 ; remote_host.blkb[3] = 0 ; remote_host.blkb[4] = 0 ; remote_host.blkb[5] = 0 ; remote_host.blkb[6] = 0 ; remote_host.blkb[7] = 0 ; /* Initialize socket address for local host */ local_host.inet_family = INET$C_AF_INET ;/* INET family */ local_host.inet_port = 0 ; /* Port number */ local_host.adrs[0] = 128 ; /* Network/subnetwork*/ local_host.adrs[1] = 45 ; /* number */ local_host.adrs[2] = 45 ; local_host.adrs[3] = 186 ; /* Host number */ local_host.blkb[0] = 0 ; local_host.blkb[1] = 0 ; local_host.blkb[2] = 0 ; local_host.blkb[3] = 0 ; local_host.blkb[4] = 0 ; local_host.blkb[5] = 0 ; local_host.blkb[6] = 0 ; local_host.blkb[7] = 0 ; /* ** Assign a channel to INET device */ status = SYS$ASSIGN( &dev, &channel, 0, 0) ; if ((status & 1) == 0) { printf("Failed to assign channel to INET device \n") ; return(status) ; } /* ** Create and bind the device socket to local host */ status = SYS$QIOW( 31, /* Event flag */ channel, /* Channel number */ IO$_SETMODE, /* I/O function */ iosb, /* I/O status block */ 0, 0, &sck_parm, /* P1 Socket creation parameter */ 0, &lhst_adrs, /* P3 Socket bind parameter */ 0,0,0) ; if ((status & 1) == 0) { printf("Failed to create and bind the device socket \n") ; return(status) ; } /* ** Perform the QIO write operation */ status = SYS$QIOW( 31, /* Event flag */ channel, /* Channel number */ IO$_WRITEVBLK,/* I/O function */ iosb, /* I/O status block */ 0, 0, 0, 0, &rhst_adrs, /* P3 Remote host adrs desc */ 0, &buf_d, /* P5 Vectored buffer desc */ 0) ; if ((status & 1) == 0) { printf("Failed to write to socket \n") ; return(status) ; } /* ** Deassign the INET dev channel */ SYS$DASSGN (channel); return(status) ; } #module write_io$_WRITEVBLK Function (C Programming) /* **++ ** ** This example does writes to INET device ** **-- */ /* ** INCLUDE FILES */ #include <descrip.h> #include <ucx$inetdef.h> /* INET symbol definitions */ #include <iodef.h> struct sockaddr { /* Structure definition for socket adrs */ short inet_family ; short inet_port ; char adrs[4] ; char blkb[8] ; } ; struct itlst { int lgth ; struct sockaddr *hst ; } ; main() { int status ; /* For return status */ short channel /* INET channel */ short sck_parm[2] ; /* Socket creation parameter */ int iosb [2] ; /* I/O status block */ struct sockaddr local_host ; /* Socket adrs definition for lhst */ struct itlst lhst_adrs ; char buf[128] ; int buflen = 128 ; /* Descriptor for Inet device name */ struct dsc$descriptor dev = { 3, DSC$K_CLASS_S, DSC$K_DTYPE_T, "UCX$DEVICE:"} ; /* Initialize the parameters */ sck_parm[0] = INET$C_UDP ; /* UDP/IP protocol */ sck_parm[1] = INET_PROTYP$C_DGRAM ; /* Datagram type of socket */ /* Itlst for local IP address */ lhst_adrs.lgth = sizeof(local_host); lhst_adrs.hst = &local_host ; /* ** Assign a channel to INET device */ status = SYS$ASSIGN( &dev, &channel, 0, 0) ; if ((status & 1) == 0) { printf("Failed to assign channel to INET device \n") ; return(status) ; } /* Initialize socket address for local host */ local_host.inet_family = INET$C_AF_INET ;/* INET family */ local_host.inet_port = 0 ; /* Port number */ local_host.adrs[0] = 128 ; /* Network/subnetwork*/ local_host.adrs[1] = 45 ; /* number */ local_host.adrs[2] = 45 ; local_host.adrs[3] = 216 ; /* Host number */ local_host.blkb[0] = 0 ; local_host.blkb[1] = 0 ; local_host.blkb[2] = 0 ; local_host.blkb[3] = 0 ; local_host.blkb[4] = 0 ; local_host.blkb[5] = 0 ; local_host.blkb[6] = 0 ; local_host.blkb[7] = 0 ; /* ** Create and bind the device socket to local host */ status = SYS$QIOW( 31, /* Event flag */ channel, /* Channel number */ IO$_SETMODE, /* I/O function */ iosb, /* I/O status block */ 0, 0, &sck_parm, /* P1 Socket creation parameter */ 0, &lhst_adrs, /* P3 Socket bind parameter */ 0,0,0) ; if ((status & 1) == 0) { printf("Failed to create and bind the device socket \n") ; return(status) ; } /* ** Perform the QIO write operation */ status = SYS$QIOW( 0, /* Event flag */ channel, /* Channel number */ IO$_WRITEVBLK,/* I/O function */ iosb, /* I/O status block */ 0, 0, buf, /* P1 buffer */ buflen,0,0,0,0);/* P2 buffer length */ if ((status & 1) == 0) { printf("Failed to write to INET device \n") ; return(status) ; } /* ** Deassign the INET dev channel */ SYS$DASSGN (channel); return(status) ; } 3 Socket_Routines Socket routines let you write internet programs. There are two types of socket routines: o Basic communication routines - These routines are the building blocks of internet programs. o Communication support routines - These routines perform operations, such as searching databases, converting byte order of network and host addresses, reading records, and returning internet addresses. 4 Basic_Communication_Routines This section describes the basic communication routines. 5 accept() Accepts a connection on a passive socket. The $QIO equivalent is the IO$_ACCESS function with the IO$M_ ACCEPT function modifier. Format #include <types.h> #include <socket.h> int accept (int s, struct sockaddr *addr, int *addrlen); 6 Arguments s A socket descriptor returned by socket(), subsequently bound to an address with bind(), and is listening for connections after a listen(). addr A result parameter filled in with the address of the connecting entity, as known to the communications layer. The exact format of the structure to which the address parameter points is determined by the domain in which the communication is occurring. This version of DEC C supports only the internet domain (AF_INET). addrlen A value-result parameter. It should initially contain the size of the structure pointed to by addr. On return it will contain the actual length, in bytes, of the structure that has been filled in by the communication layer. 6 Description This routine completes the first connection on the queue of pending connections, creates a new socket with the same properties as s, and allocates and returns a new descriptor for the socket. If no pending connections are present on the queue and the socket is not marked as nonblocking, accept() blocks the caller until a connection request is present. If the socket is marked nonblocking by using a setsockopt() call and no pending connections are present on the queue, accept() returns an error. You cannot use the accepted socket to accept subsequent connections. The original socket s remains open (listening) for other connection requests. This call is used with connection- based socket types, currently with SOCK_STREAM. You can use the select() socket routine to do an accept() by selecting it for read. See also bind(), connect(), listen(), select(), and socket(). 6 Return_Values x A non-negative integer that is a descriptor for the accepted socket. 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The socket descriptor is invalid. [ENOTSOCK] The socket descriptor references a file, not a socket. [EOPNOTSUPP] The reference socket is not of type SOCK_ STREAM. [EFAULT] The addr parameter is not in a writable part of the user address space. [EWOULDBLOCK] The socket is marked nonblocking and no connections are present to be accepted. 5 bind() Binds a name to a socket. The $QIO equivalent is the IO$_SETMODE function with the p3 argument. Format #include <types.h> #include <socket.h> int bind (int s, struct sockaddr *name, int namelen); 6 Arguments s A socket descriptor created with socket(). name Address of a structure used to assign a name to the socket in the format specific to the family (AF_INET) socket address. namelen The size, in bytes, of the structure pointed to by name. 6 Description This routine assigns a port number and IP address to an unnamed socket. When a socket is created with socket() it exists in a name space (address family) but has no name assigned. The bind() routine requests that a name be assigned to the socket. See also connect(), getsockname(), listen(), and socket(). 6 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The descriptor is invalid. [ENOTSOCK] The socket descriptor references a file, not a socket. [EADDRNOTAVAIL] The specified address is not available from the local machine. [EADDRINUSE] The specified internet address and ports are already in use. [EINVAL] The socket is already bound to an address. [EACCESS] The requested address is protected, and the current user has inadequate permission to access it. [EFAULT] The name parameter is not a valid part of the user address space. 5 close() Closes a connection and deletes a socket descriptor. The $QIO equivalent is the $DASSGN system service. Format #include <unixio.h> int close (s); 6 Argument s A socket descriptor. 6 Description This routine deletes a descriptor from the per-process object (DEC C structure) reference table. Associated TCP connections close first. See also accept(), socket(), and write(). 6 Return_Values 0 Successful completion -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following value: [EBADF] The socket descriptor is invalid. 5 connect() Initiates a connection on a socket. The $QIO equivalent is the IO$_ACCESS function. Format #include <types.h> #include <socket.h> int connect (int s, struct sockaddr *name, int namelen); 6 Arguments s A socket descriptor created with socket(). name The address of a structure that specifies the name of the remote socket in the format specific to the address family (AF_INET). namelen The size, in bytes, of the structure pointed to by name. 6 Description If s is a socket descriptor of type SOCK_DGRAM, then this call permanently specifies the peer where the data is sent. If it is type SOCK_STREAM, then this call attempts to make a connection to the specified socket. Each communications space interprets the name parameter. This argument specifies the socket that is connected to the socket specified in s. See also accept(), select(), socket(), getsockname(), and shutdown(). 6 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The descriptor is invalid. [ENOTSOCK] The socket descriptor references a file, not a socket. [EADDRNOTAVAIL] The specified address is not available from the local machine. [EAFNOSUPPORT] Address in the specified address family cannot be used with this socket. [EISCONN] The socket is already connected. [ETIMEOUT] Connection establishment timed out without establishing a connection. [ECONNREFUSED] The attempt to connect is rejected explicitly when a connection request arrives with the queue full. [ENETUNREACH] The network is not reachable from this host. [EADDRINUSE] The specified internet address and ports are already in use. [EFAULT] The name parameter is not a valid part of the user address space. [EWOULDBLOCK] The socket is nonblocking and the connection cannot be completed immediately. It is possible to select() the socket while it is connecting by selecting it for writing. 5 listen() Sets the maximum limit of outstanding connection requests for a socket that is connection oriented. The $QIO equivalent is the IO$_SETMODE or IO$_SETCHAR function. Format int listen (int s, int backlog); 6 Arguments s A socket descriptor of type SOCK_STREAM created using socket(). backlog The maximum number of pending connections that can be queued on the socket at any given time. The maximum is five and the smallest useful backlog limit is one. 6 Description This routine creates a queue for pending connection requests on socket s with a maximum size of backlog. Connections can then be accepted with accept(). If a connection request arrives with the queue full (more than backlog connection requests pending), the client receives an error with an errno indication of ECONNREFUSED. See also accept(), connect(), and socket(). 6 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The socket descriptor is invalid. [ENOTSOCK] The socket descriptor references a file, not a socket. [EOPNOTSUPP] The socket is not of a type that supports the operation listen(). 5 read() Reads bytes from a socket or file and places them in a user- provided buffer. The $QIO equivalent is the IO$_READVBLK function. Format #include <unixio.h> int read (int d, void *buffer, int nbytes); 6 Arguments d A descriptor that must refer to a socket or file currently opened for reading. buffer The address of a user-provided buffer in which the input data is placed. nbytes The maximum number of bytes allowed in the read operation. 6 Description If the end-of-file is not reached, the read() routine returns nbytes. If the end-of-file occurs during the read() routine, it returns the number of bytes read. Upon successful completion, read() returns the number of bytes actually read and placed in the buffer. See also socket(). 6 Return_Values x The number of bytes read and placed in the buffer. 0 Peer has closed the connection. -1 Error; errno is set to indicate the error. 6 _Errors You can set errno to the following values: [EBADF] The descriptor is invalid. [EFAULT] The buffer points outside the allocated address space. [EINVAL] The nbytes argument is negative. [EWOULDBLOCK] The NBIO socket option (nonblocking) flag is set for the socket or file descriptor and the process would be delayed in the read operation. 5 recv() Receives bytes from a connected socket and places them into a user-provided buffer. The $QIO equivalent is the IO$_READVBLK function. Format #include <types.h> #include <socket.h> int recv (int s, char *buf, int len, int flags); 6 Arguments s A socket descriptor created as the result of a call to accept() or connect(). buf A pointer to a user-provided buffer into which received data will be placed. len The size of the buffer pointed to by buf. flags A bit mask that can contain one or more MSG_OOB and MSG_PEEK flags. It is built by ORing the appropriate values together, as follows: Flag Description MSG_OOB Allows you to receive out-of-band data. If out-of-band data is available, it is read first. If no out-of-band data is available, the MSG_OOB flag is ignored. Use the send(), sendmsg(), and sendto() to send out-of-band data. MSG_PEEK Allows you to peek at the data next in line to be received without actually removing it from the system's buffers. If you include the UCX$INETDEF definition file, use the flags listed in the following table: Flag Description UCX$C_MSG_NBIO Does not block the I/O operation if the transmit queue is full. Similar to using the $QIO IO$M_NOWAIT function. UCX$C_MSG_PURGE Flushes data from the queue. Similar to using the $QIO IO$M_PURGE function. UCX$C_MSG_BLOCKALL Blocks the completion of the operation until the buffer is filled completely or until the connection is closed. Similar to using the $QIO IO$M_LOCKBUF function. 6 Description This routine receives data from a connected socket. To receive data on an unconnected socket, use the recvfrom() or recvmsg() routines. The received data is placed in the buffer buf. Data is sent by the socket's peer using the send, sendmsg(), or sendto() routines. Use the select() routine to determine when more data arrives. If no data is available at the socket, the receive call waits for data to arrive, unless the socket is nonblocking, in which case a -1 is returned with the external variable errno set to EWOULDBLOCK. See also read(), send(), sendmsg(), sendto(), and socket(). 6 Return_Values x The number of bytes received and placed in buf. 0 Peer has closed. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The socket descriptor is invalid. [ENOTSOCK] The descriptor references a file, not a socket. [EPIPE] You tried to write to a socket that is not open for reading by any process. [EWOULDBLOCK] The NBIO (nonblocking) flag is set for the socket descriptor and the process is delayed during the write operation. [EFAULT] The data was specified to be received into a nonexistent or protected part of the process address space. 5 recvfrom() Receives bytes for a socket from any source. Format #include <types.h> #include <socket.h> int recvfrom (int s, char *buf, int len, int flags, struct sockaddr *from, int *fromlen) ; 6 Arguments s A socket descriptor created with socket() and bound to a name using bind() or as a result of accept(). buf A pointer to a buffer into which received data is placed. len The size of the buffer pointed to by buf. flags A bit mask that can contain one or more MSG_OOB and MSG_PEEK flag. It is built by ORing the appropriate values together, as follows: Flag Description MSG_OOB Allows you to receive out-of-band data. If out-of-band data is available, it is read first. If no out-of-band data is available, the MSG_ OOB flag is ignored. To send out-of-band data, use the send(), sendmsg(), and sendto(). MSG_PEEK Allows you to peek at the data that is next in line to be received without actually removing it from the system's buffers. If you include the UCX$INETDEF definition file, use the flags listed in the following table: Flag Description UCX$C_MSG_NBIO Does not block the I/O operation if the transmit queue is full. Similar to using the $QIO IO$M_NOWAIT function. UCX$C_MSG_PURGE Flushes data from the queue. Similar to using the $QIO IO$M_PURGE modifier. UCX$C_MSG_ Blocks the completion of the operation until BLOCKALL the buffer is filled completely or until the connection is closed. Similar to using the $QIO IO$M_LOCKBUF function. from A buffer that the recvfrom routine uses to place the address of the socket from which the data is received. If from is nonzero, the address is returned. If from is 0, the address is not returned. fromlen Points to an integer containing the size of the buffer pointed to by from. On return, the integer is modified to contain the actual length of the socket address structure returned. 6 Description This routine allows a named, unconnected socket to receive data. The data is placed in the buffer pointed to by buf, and the address of the sender of the data is placed in the buffer pointed to by from if from is non-null. The structure that from points to is assumed to be as large as the sockaddr structure. To receive bytes from any source, the socket need not be connected to another socket. You can use the select() routine to determine if data is available. If no data is available at the socket, the recvfrom() call waits for data to arrive, unless the socket is nonblocking, in which case a -1 is returned with the external variable errno set to EWOULDBLOCK. See also read(), send(), sendmsg(), sendto(), and socket(). 6 Return_Values x The number of bytes of data received and placed in buf. 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The socket descriptor is invalid. [ENOTSOCK] The descriptor references a file, not a socket. [EPIPE] You tried to write to a socket that is not open for reading by any process. [EWOULDBLOCK] The NBIO (nonblocking) flag is set for the socket descriptor and the process delayed during the write operation. [EFAULT] The data is specified to be received into a non-existent or protected part of the process address space. 5 recvmsg() Receives bytes on a socket and places them into scattered buffers. Format #include <types.h> #include <socket.h> int recvmsg (int s, struct msghdr msg[], int flags); 6 Arguments s A socket descriptor created with socket(). msg flags A bit mask that can contain one or more MSG_OOB and MSG_PEEK flags. It is built by ORing the appropriate values together, as follows: Flag Description MSG_OOB Allows you to receive out-of-band data. If out-of-band data is available, it is read first. If no out-of-band data is available, the MSG_OOB flag is ignored. Use send(), sendmsg(), and sendto() routines to send out-of-band data. MSG_PEEK Allows you to peek at the data that is next in line to be received without actually removing it from the system's buffers. If you include the UCX$INETDEF definition file, you can use the flags listed in the following table: Flag Description UCX$C_MSG_NBIO Does not block the I/O operation if the transmit queue is full. Similar to using the $QIO IO$M_NOWAIT function. UCX$C_MSG_PURGE Flushes data from the queue. Similar to using the $QIO IO$M_PURGE function. UCX$C_MSG_ Blocks the completion of the operation until BLOCKALL the buffer is filled completely or until the connection is closed. Similar to using to the $QIO IO$M_LOCKBUF modifier. 6 Description You can use this routine with any socket, whether it is in a connected state or not. It receives data sent by a call to sendmsg(), send(), or sendto(). The message is scattered into several user buffers if such buffers are specified. To receive data, the socket need not be connected to another socket. When the iovec[iovcnt] array specifies more than one buffer, the input data is scattered into iovcnt buffers as specified by the members of the iovec array: iov[0], iov[1], ..., iov[iovcnt] When a message is received, it is split among the buffers by filling the first buffer in the list, then the second, and so on, until either all of the buffers are full or there is no more data to be placed in the buffers. You can use the select() routine to determine when more data arrives. See also read(), send(), and socket(). 6 Return_Values x The number of bytes returned in the msg_iov buffers. 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The socket descriptor is invalid. [ENOTSOCK] The descriptor references a file, not a socket. [EPIPE] You tried to read a socket that is not open for reading by any process. [EWOULDBLOCK] The NBIO (nonblocking) flag is set for the socket descriptor and the process is delayed during the read operation. [EINTR] The receive is interrupted by delivery of a signal before any data is available for the receive. [EFAULT] The data is specified to be received into a non-existent or protected part of the process address space. 5 select() Allows you to poll or check a group of sockets for I/O activity. It can indicate which sockets are ready to be read or written, or which sockets have an exception pending. Format #include <time.h> int select (int nfds, int *readfds, int *writefds, int *execptfds, struct timeval *timeout); 6 Arguments nfds The highest numbered socket descriptor for which to search. In other words, the nfds argument is the highest numbered bit plus 1 in readfds, writefds, and exceptfds that should be examined. Descriptor s is represented by 1<< s (1 shifted to the left s number of times). This argument is used only to improve efficiency. If you are unsure what the highest numbered socket descriptor is, you can safely set nfds to 32. The DEC C select() routine examines only the longwords referenced by the readfds, writefds, and exceptfds arguments. Therefore, any program that uses the DEC C select routine can never have more than 32 files and sockets opened simultaneously. readfds A pointer to an array of bits, organized as integers (each integer describing 32 descriptors) that should be examined for read readiness. If bit n of the longword is set, socket descriptor n is checked to see if it is ready to be read. All bits set in the bit mask must correspond to the file descriptors of sockets. The select() routine cannot be used on normal files. On return, the longword to which readfds points contains a bit mask of the sockets that are ready for reading. Only bits that were set on entry to select() could possibly be set on exit. writefds A pointer to a longword bit mask of the socket descriptors that should be examined for write readiness. If bit n of the longword is set, socket descriptor n is checked to see if it is ready to be written to. All bits set in the bit mask must correspond to socket descriptors. On return, the longword that writefds points to contains a bit mask of the sockets that are ready for writing. Only bits that were set on entry to select() are set on exit. exceptfds A pointer to a longword bit mask of the socket descriptors that is examined for exceptions. If bit n of the longword is set, socket descriptor n is checked to see if it has any pending exceptions. All bits set in the bit mask must correspond to the file descriptors of sockets. On return, the longword exceptfds pointer contains a bit mask of the sockets that have exceptions pending. Only bits that were set on entry to select() could possibly be set on exit. timeout The length of time that select() should examine the sockets before returning. If one of the sockets specified in the readfds, writefds, and exceptfds bit masks is ready for I/O, select() returns before the timeout period has expired. The timeout structure points to a timeval structure. 6 Description This routine determines the I/O status of the sockets specified in the various mask arguments. It returns either when a socket is ready to be read or written, when the timeout period expires, or when exceptions occur. If timeout is a nonzero integer, it specifies a maximum interval to wait for the selection to complete. If the timeout argument is null, the select() routine blocks indefinitely. In order to effect a poll, timeout is non-null, and points to a zero-valued structure. If a process is blocked on a select() routine while waiting for input for a socket and the sending process closes the socket, then the select() routine notes this as an event and unblocks the process. The descriptors are always modified on return if select() returns because of the timeout. NOTE When the socket option SO_OOBINLINE is set on the device socket, a select() on both read and exception events returns the socket mask set on both the read and exception mask. Otherwise, only the exception mask is set. See also accept(), connect(), read(), recv(), recvfrom(), recvmsg(), send(), sendmsg(), sendto(), and write(). 6 Return_Values n The number of sockets ready for I/O or pending exceptions. This value matches the number of returned bits that are set in all output masks. 0 The select() routine timed out before any socket became ready for I/O. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] One of the bit masks specified an invalid descriptor. [EINVAL] The specified time limit is unacceptable. One of its components is negative or too large. 5 send() Sends bytes through a socket to its connected peer. The $QIO equivalent is the IO$_WRITEVBLK function. Format #include <types.h> #include <socket.h> int send (int s, char *msg, int len, int flags); 6 Arguments s A socket descriptor created with socket() that was connected to another socket using accept() or connect(). msg A pointer to a buffer containing the data to be sent. len The length, in bytes, of the data pointed to by msg. flags Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data is sent out-of-band. This means that the data can be received before other pending data on the receiving socket if the receiver also specifies a MSG_OOB in the flag parameter of the call. If you include the UCX$INETDEF definition file, you can also use: o UCX$C_MSG_DONTROUTE - Sends the message directly without routing. o UCX$C_MSG_NBIO - Completes the I/O operation and returns an error if a condition occurs that would cause the I/O operation to be blocked. Similar to using the $QIO IO$M_NOWAIT modifier. 6 Description You can only use this routine on connected sockets. To send data on an unconnected socket, use the sendmsg() or sendto() routines. The send() routine passes data along to its connected peer, which can receive the data by using recv(). If there is no space available to buffer the data being sent on the receiving end of the connection, send() normally blocks until buffer space becomes available. If the socket is defined as nonblocking, however, send() fails with an errno indication of EWOULDBLOCK. If the message is too large to be sent in one piece and the socket type requires that messages be sent atomically (SOCK_DGRAM), send() fails with an errno indication of EMSGSIZE. No indication of failure to deliver is implicit in a send(). All errors (except EWOULDBLOCK) are detected locally. You can use the select() routine to determine when it is possible to send more data. See also read(), recv(), recvmsg(), recvfrom(), getsockopt(), and socket(). 6 Return_Values n The number of bytes sent. This value normally equals len. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The socket descriptor is invalid. [ENOTSOCK] The descriptor references a file, not a socket. [EFAULT] An invalid user space address is specified for a parameter. [EMSGSIZE] The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible. [EWOULDBLOCK] Blocks if the system does not have enough space for buffering the user data. 5 sendmsg() Sends gathered bytes through a socket to any other socket. Format #include <types.h> #include <socket.h> int sendmsg (int s, struct msghdr msg[], int flags); 6 Arguments s A socket descriptor created with socket(). msg A pointer to a msghdr structure containing the message to be sent. The msg_iov field of the msghdr structure is used as a series of buffers from which data is read in order until msg_iovlen bytes have been obtained. flags Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data is sent out-of-band. This means that the data can be received before other pending data on the receiving socket if the receiver also specifies a flag of MSG_OOB. If you include the UCX$INETDEF definition file, you can also use: o UCX$C_MSG_DONTROUTE - Sends the message directly without routing. o UCX$C_MSG_NBIO - Completes the I/O operation and returns an error if a condition occurs that would cause the I/O operation to be blocked. Similar to using the $QIO IO$M_NOWAIT modifier. 6 Description You can use this routine on any socket to send data to any named socket. The data in the msg_iovec field of the msg structure is sent to the socket whose address is specified in the msg_name field of the structure. The receiving socket gets the data using the read(), recv(), recvfrom(), or recvmsg() routine. When the iovec array specifies more than one buffer, the data is gathered from all specified buffers before being sent. If no space is available to buffer the data on the receiving end of the connection, the sendmsg() routine normally blocks until buffer space becomes available. If the socket is defined as nonblocking, the sendmsg() routine fails with an errno indication of EWOULDBLOCK. If the message is too large to be sent in one piece and the socket type requires that messages be sent atomically (SOCK_DGRAM), the sendmsg() fails with an errno indication of EMSGSIZE. If the address specified is a INADDR_BROADCAST address, then the SO_BROADCAST option must be set and the process must have a system UIC, OPER, SYSPRV, or BYPASS privilege for the I/O operation to succeed. No indication of failure to deliver is implicit in a sendmsg() routine. All errors (except EWOULDBLOCK) are detected locally. You can use the select() routine to determine when it is possible to send more data. See also read(), recv(), recvfrom(), recvmsg(), socket(), and getsockopt(). 6 Return_Values n The number of bytes sent. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The descriptor is invalid. [ENOTSOCK] The socket descriptor references a file, not a socket. [EFAULT] An invalid user space address is specified for a parameter. [EMSGSIZE] The socket requires that messages be sent atomically, and the size of the message to be sent makes this impossible. [EWOULDBLOCK] Blocks if the system does not have enough space for buffering the user data. 5 sendto() Sends bytes through a socket to any other socket. The $QIO equivalent is the IO$_WRITEVBLK function. Format #include <types.h> #include <socket.h> int sendto (int s, char *msg, int len, int flags, struct sockaddr *to, int tolen); 6 Arguments s A socket descriptor created with socket(). msg A pointer to a buffer containing the data to be sent. len The length of the data pointed to by msg. flags Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data is sent out-of-band. This means that the data can be received before other pending data on the receiving socket if the receiver also specifies a MSG_OOB in its flag parameter of the call. If you include the UCX$INETDEF definition file, you can also use: o UCX$C_MSG_DONTROUTE - Sends the message directly without routing. o UCX$C_MSG_NBIO - Completes the I/O operation and returns an error if a condition occurs that would cause the I/O operation to be blocked. Similar to using the $QIO IO$M_NOWAIT modifier. to Points to the address structure of the socket to which the data is to be sent. tolen The length of the address structure to points to. 6 Description This routine can be used on sockets to send data to named sockets. The data in the msg buffer is sent to the socket whose address is specified in the to argument, and the address of socket s is provided to the receiving socket. The receiving socket gets the data using either the read(), recv(), recvfrom(), or recvmsg() routine. If there is no space available to buffer the data being sent on the receiving end of the connection, the sendto() routine blocks until buffer space becomes available. If the socket is defined as nonblocking, the sendto() routine fails with an errno indication of EWOULDBLOCK. If the message is too large to be sent in one piece and the socket type requires that messages be sent atomically (SOCK_DGRAM), the sendto() routine fails with an errno indication of EMSGSIZE. No indication of failure to deliver is implicit in a sendto(). All errors (except EWOULDBLOCK) are detected locally. You can use the select() routine to determine when it is possible to send more data. If the address specified is a INADDR_BROADCAST address, then the SO_BROADCAST option must be set and the process must have SYSPRV or BYPASS privilege for the I/O operation to succeed. See also read(), recv(), recvfrom(), recvmsg(), socket(), and getsockopt(). 6 Return_Values n The number of bytes sent. This value normally equals len. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The descriptor is invalid. [ENOTSOCK] The socket descriptor references a file, not a socket. [EFAULT] An invalid user space address is specified for a parameter. [EMSGSIZE] The socket requires that messages be sent atomically, and the size of the message to be sent makes this impossible. [EWOULDBLOCK] Blocks if the system does not have enough space for buffering the user data. 5 shutdown() Shuts down all or part of a bidirectional connection on a socket. This routine disallows further receives, further sends, or both. The $QIO equivalent is the IO$_DEACCESS function with the IO$M_ SHUTDOWN function modifier. Format #include <socket.h> int shutdown (int s, int how); 6 Arguments s A socket descriptor that is in a connected state as a result of a previous call to either connect() or accept(). how How the socket is to be shut down. Use one of the following values: 0 (INET$C_DSC_ Disallows further calls to recv() on the RCV) socket. 1 (INET$C_DSC_ Disallows further calls to send() on the SND) socket. 2 (INET$C_DSC_ Disallows further calls to both send() and ALL) recv(). 6 Description This routine allows communications on a socket to be shut down one piece at a time rather than all at once. Use the shutdown() routine to create unidirectional connections rather than the normal bidirectional (full-duplex) connections. See also connect() and socket(). 6 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The socket descriptor is invalid. [ENOTSOCK] The descriptor references a file, not a socket. [ENOTCONN] The specified socket is not connected. 5 socket() Creates an end point for communication by returning a special kind of file descriptor called a socket descriptor, which is associated with a UCX socket device channel. The $QIO equivalent is the IO$_SETMODE or IO$_SETCHAR function. Format #include <types.h> #include <socket.h> int socket (int af, int type, int protocol); 6 Arguments af The address format to be used in later references to the socket. Addresses specified in subsequent operations using the socket are interpreted according to this format. Currently, only AF_INET (internet style) addresses are supported. type The socket types are: o SOCK_STREAM - Provides sequenced, reliable, two-way, connection-based byte streams with an available out-of-band data transmission mechanism. o SOCK_DGRAM - Supports datagrams (connectionless, unreliable data transmission mechanism). o SOCK_RAW - Provides access to internal network interfaces, and are available only to users with a system UIC or SYSPRV privilege. protocol The protocol to be used with the socket. Normally only a single protocol exists to support a particular socket type using a given address format. However, many protocols may exist, in which case a particular protocol must be specified with this argument. Use the protocol number that is specific to the communication domain in which communication takes place. 6 Description This routine provides the primary mechanism for creating sockets. The type and protocol of the socket affect the way the socket behaves and how it can be used. The operation of sockets is controlled by socket-level options, defined in the file <socket.h>. Use the setsockopt() and getsockopt() routines to set and get options. Options other than SO_LINGER take an integer parameter that should be nonzero if the option is to be enabled, or 0 if it is to be disabled. SO_LINGER uses a linger structure parameter defined in <socket.h>. o SO_REUSEADDR - Indicates that the rules used in validating addresses supplied in a bind() call should allow reuse of local addresses. o SO_KEEPALIVE - Keeps connections alive by enabling the periodic transmission of messages on a connected socket. If the connected party fails to respond to these messages, the connection is considered broken and processes using the socket are notified through the error code SS$_LINKDISCON. o SO_DONTROUTE - Indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. o SO_LINGER - Lingers on close if data is present. It controls the actions taken when unsent messages are queued on the socket and a close() is performed. When using the setsockopt() to set the linger values, the option value for the SO_LINGER command is the address of a linger structure. If the socket promises reliable delivery of data and l_onoff is nonzero, the system will block the process on the attempt until it is able to transmit the data or until it decides it is unable to deliver the information. A timeout period, called the linger interval, is specified in l_linger. If l_onoff is set to 0 and a close is issued, the system processes the close in a manner that allows the process to continue as quickly as possible. o SO_BROADCAST - Enables or disables broadcasting on the socket. See also accept(), bind(), connect(), listen(), read(), recv(), recvfrom(), recvmsg(), select(), send(), sendmsg(), sendto(), shutdown(), and write(). See also getsockname() and getsockopt(). 6 Return_Values x A file descriptor that refers to the socket descriptor. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EAFNOSUPPORT] The specified address family is not supported in this version of the system. [ESOCKTNOSUPPORT] The specified socket type is not supported in this address family. [EPROTONOSUPPORT] The specified protocol is not supported. [EPROTOTYPE] Request for a type of socket for which there is no supporting protocol. [EMFILE] The per-process descriptor table is full. [ENOBUFS] No buffer space is available. The socket cannot be created. 5 write() Writes a buffer of data to a socket or file. The $QIO equivalent is the IO$_WRITEVBLK function. Format #include <unixio.h> int write (int d, void *buffer, int nbytes); 6 Arguments d A descriptor that must refer to a socket or file. buffer The address of contiguous storage from which the output data is taken. nbytes The maximum number of bytes involved in the write operation. 6 Description This routine attempts to write a buffer of data to a socket or file. See also socket(). 6 Return_Values x The number of bytes written to the socket or file. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The d argument is not a valid descriptor open for writing. [EPIPE] An attempt was made to write to a socket that is not open for reading by any process. [EFAULT] Part of the array pointed to by iov or data to be written to the file points outside the process's allocated address space. [EWOULDBLOCK] The NBIO (nonblocking) flag is set for the socket descriptor and the process is delayed during the write operation. [EINVAL] The nbytes argument is negative. 4 Communication_Support_Routines This section describes the communication support routines. 5 gethostbyaddr() Searches the hosts database sequentially from the beginning of the database for a host record with a given address. The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETHOSTBYADDR subfunction code. Format #include <netdb.h> struct hostent *gethostbyaddr (char *addr, int len, int type); 6 Arguments addr A pointer to a series of bytes in network order specifying the address of the host sought. This argument does not point to an ASCII string. len The number of bytes in the address pointed to by the addr argument. type The type of address format being sought. Currently, only AF_INET is supported. 6 Description This routine finds the first host record in the hosts database with the given address. The gethostbyaddr() routine uses a common static area for its return values. This means that subsequent calls to this routine overwrite previously returned host entries. You must make a copy of the host entry if you want to save it. 6 Return_Values NULL Indicates an error. x A pointer to an object having the hostent structure. 5 gethostbyname() Searches the hosts database sequentially from the beginning of the database for a host record with a given name or alias. This routine also invokes the BIND resolver to query the appropriate name server if the information requested is not in the hosts database. The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETHOSTBYNAME subfunction code. Format #include <netdb.h> struct hostent *gethostbyname (char *name); 6 Argument name A pointer to a null-terminated character string containing the name or an alias of the host sought. 6 Description This routine finds the first host in the hosts database with the given name or alias. The gethostbyname() routine uses a common static area for its return values. This means that subsequent calls to this routine overwrite previously returned host entries. You must make a copy of the host entry if you want to save it. 6 Return_Values NULL Indicates an error. x A pointer to an object having the hostent structure. 5 gethostname() Returns the fully qualified name of the local host. Format #include <types.h> #include <socket.h> int gethostname (char *name, int namelen); 6 Arguments name The address of a buffer where the name should be returned. The returned name is null-terminated unless sufficient space is not provided. namelen The size of the buffer pointed to by name. 6 Description This routine returns the translation of the logical names UCX$INET_HOST and UCX$INET_DOMAIN when used with the UCX software. 6 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EFAULT] The buffer described by name and namelen is not a valid, writable part of the user address space. 5 getnetbyaddr() Searches the networks database sequentially from the beginning of the database for a network record with a given address. The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETNETBYADDR subfunction code. Format #include <netdb.h> struct netent *getnetbyaddr (long net, int type); 6 Arguments net The network number, in host byte order, of the networks database entry required. type The type of network sought. Currently, only AF_INET is supported. 6 Description This routine finds the first network record in the networks database with the given address. The getnetent(), getnetbyaddr(), and getnetbyname() routines all use a common static area for their return values. This means that subsequent calls to any of these routines will overwrite any previously returned network entry. You must make a copy of the network entry if you want to save it. 6 Return_Values NULL Indicates end of file or an error. x A pointer to an object having the netent structure. 5 getnetbyname() Searches the networks database sequentially from the beginning of the database for a network record with a given name or alias. The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETNETBYNAME subfunction code. Format #include <netdb.h> struct netent *getnetbyname (char *name); 6 Argument name A pointer to a null-terminated character string of the name or an alias of the network sought. 6 Description This routine finds the first host in the networks database with the given name or alias. The getnetent(), getnetbyaddr(), and getnetbyname() routines all use a common static area for their return values. This means that subsequent calls to any of these routines overwrite previously returned network entries. You must make a copy of the network entry if you want to save it. 6 Return_Values NULL Indicates end of file or an error. x A pointer to an object having the netent structure. 6 Errors You can set errno to the following value: [EFAULT] The buffer described by name is not a valid, writable part of the user address space. 5 getnetent() Reads the next record in the networks database, opening the database if necessary. Format #include <netdb.h> struct netent *getnetent(); 6 Description This routine allows the records in the networks database to be read sequentially in the order in which they appear in the database. The getnetent(), getnetbyaddr(), and getnetbyname() routines all use a common static area for their return values. This means that subsequent calls to any of these routines overwrite previously returned network entries. You must make a copy of the network entry if you want to save it. 6 Return_Values NULL Indicates end of file or an error. x A pointer to an object having the netent structure. 5 getpeername() Returns the name of the connected peer. The $QIO equivalent is the IO$_SENSEMODE or IO$_SENSECHAR function with the p4 argument. Format #include <types.h> #include <socket.h> int getpeername (int s, struct sockaddr *name, int *namelen); 6 Arguments s A socket descriptor created using socket(). name A pointer to a buffer within which the peer name is to be returned. namelen An address of an integer that specifies the size of the name buffer. On return, it will be modified to reflect the actual length, in bytes, of the name returned. 6 Description This routine returns the name of the peer connected to the socket descriptor specified. See also bind() socket() and getsockname(). 6 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The descriptor is invalid. [ENOTSOCK] The socket descriptor references a file, not a socket. [ENOTCONN] The socket is not connected. [ENOBUFS] Resources were insufficient in the system to perform the operation. [EFAULT] The name parameter is not a valid part of the user address space. 5 getprotobyname() Searches the protocols database until a matching protocol name is found or until end of file is encountered. Format #include <netdb.h> struct protoent *getprotobyname (char *name); 6 Argument name A pointer to a string containing the desired protocol name. 6 Description This routine returns a pointer to a protoent structure containing the broken-out fields of the requested line from the protocols database: struct protoent { char *p_name; /* official name of protocol */ char **p_aliases; /* alias list */ long p_proto; /* protocol number */ }; The members of this structure are: p_name The official name of the protocol. p_aliases A zero-terminated list of alternate names for the protocol. p_proto The protocol number. All information is contained in a static area, so it must be copied if it is to be saved. See also getprotoent() and getprotobynumber(). 6 Return_Values NULL Indicates end of file or an error. x A pointer to a protoent structure. 5 getprotobynumber() Searches the protocols database until a matching protocol number is found or until end of file is encountered. Format #include <netdb.h> struct protoent *getprotobynumber (int *proto); 6 Argument proto A pointer to a string containing the desired protocol number. 6 Description This routine returns a pointer to a protoent structure containing the broken-out fields of the requested line from the protocols database: struct protoent { char *p_name; /* official name of protocol */ char **p_aliases; /* alias list */ long p_proto; /* protocol number */ }; The members of this structure are: p_name The official name of the protocol. p_aliases A zero-terminated list of alternate names for the protocol. p_proto The protocol number. All information is contained in a static area, so it must be copied if it is to be saved. See also getprotoent() and getprotobyname(). 6 Return_Values NULL Indicates end of file or an error. x A pointer to a protoent structure. 5 getprotoent() Reads the next line from the protocols database. Format #include <netdb.h> struct protoent *getprotoent(); 6 Description This routine returns a pointer to a protoent structure containing the broken-out fields of the next line in the protocols database: struct protoent { char *p_name; /* official name of protocol */ char **p_aliases; /* alias list */ long p_proto; /* protocol number */ }; The members of this structure are: p_name The official name of the protocol. p_aliases A zero-terminated list of alternate names for the protocol. p_proto The protocol number. The getprotoent() routine keeps a pointer in the database, allowing successive calls to be used to search the entire file. All information is contained in a static area, so it must be copied if it is to be saved. See also getprotobyname() and getprotobynumber(). 6 Return_Values NULL Indicates an error. x A pointer to a protoent structure. 5 getservbyname() Gets information on the named service from the network services database. Format #include <netdb.h> struct servent *getservbyname (char *name, char *proto); 6 Arguments name A pointer to a string containing the name of the service about which information is required. proto A pointer to a string containing the name of the protocol ("tcp" or "udp") for which to search. 6 Description This routine searches sequentially from the beginning of the file until a matching service name is found, or until end of file is encountered. If a protocol name is also supplied (non-null), searches must also match the protocol. This routine returns a pointer to a servent structure containing the broken-out fields of the requested line in the network services database: struct servent { char *s_name; /* official name of service */ char **s_aliases; /* alias list */ long s_port; /* port service resides at */ char *s_proto; /* protocol to use */ }; The members of this structure are: s_name The official name of the service. s_aliases A zero-terminated list of alternate names for the service. s_port The port number at which the service resides. Port numbers are returned in network-byte order. s_proto The name of the protocol to use when contacting the service. All information is contained in a static area, so you must copy it if you want it saved. See also getservbyport(). 6 Return_Values NULL Indicates end of file or an error. x A pointer to a servent structure. 5 getservbyport() Gets information on the specified port from the network services database. Format #include <netdb.h> struct servent *getservbyport (int port, char *proto); 6 Arguments port The port number for which to search. This port number should be specified in network-byte order. proto A pointer to a string containing the name of the protocol ("tcp" or "udp") for which to search. 6 Description This routine searches sequentially from the beginning of the file until a matching port is found, or until end of file is encountered. If a protocol name is also supplied (non-null), searches must also match the protocol. This routine returns a pointer to a servent structure containing the broken-out fields of the requested line in the network services database: struct servent { char *s_name; /* official name of service */ char **s_aliases; /* alias list */ long s_port; /* port service resides at */ char *s_proto; /* protocol to use */ }; The members of this structure are: s_name The official name of the service. s_aliases A zero-terminated list of alternate names for the service. s_port The port number at which the service resides. Port numbers are returned in network-byte order. s_proto The name of the protocol to use when contacting the service. All information is contained in a static area, so you must copy it if you it saved. See also getservbyname(). 6 Return_Values NULL Indicates end of file or an error. x A pointer to a servent structure. 5 getsockname() Returns the name associated with a socket. The $QIO equivalent is the IO$_SENSEMODE or IO$_SENSECHAR function with the p3 argument. Format #include <types.h> #include <socket.h> int getsockname (int s, struct sockaddr *name, int *namelen); 6 Arguments s A socket descriptor created with socket() routine and bound to the socket name with bind() routine. name A pointer to the buffer in which getsockname() should return the socket name. namelen A pointer to an integer specifying the size of the buffer pointed to by name. On return, the integer contains the actual size of the name returned, in bytes. 6 Description This routine returns the current name for the specified socket descriptor. The name is a format specific to the address family (AF_INET) assigned to the socket. The bind() routine makes the association of the name to the socket, not the getsockname() routine. See also bind() and socket(). 6 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The descriptor is invalid. [ENOTSOCK] The socket descriptor references a file, not a socket. [ENOBUFS] Resources were insufficient in the system to perform the operation. [EFAULT] The name parameter is not a valid part of the user address space. 5 getsockopt() Returns the options set on a socket. The $QIO equivalent is the IO$_SENSEMODE or IO$_SENSECHAR function. Format #include <types.h> #include <socket.h> int getsockopt (int s, int level, int optname, char *optval, int *optlen); 6 Arguments s A socket descriptor created by socket(). level The protocol level for which the socket options are desired. It can have one of the following values: SOL_SOCKET Get the options at the socket level. p Any protocol number. Get the options for protocol level p. See the <in.h> file for the various IPPROTO values. optname Interpreted by the protocol specified in the level. Options at each protocol level are documented with the protocol. See setsockopt() in this section for socket level options. optval Points to a buffer in which the value of the specified option should be placed by getsockopt(). optlen Points to an integer containing the size of the buffer pointed to by optval. On return, the integer is modified to contain the actual size of the option value returned. 6 Description This routine gets information on socket options. See the appropriate protocol for information on available options at each protocol level. 6 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The descriptor is invalid. [ENOTSOCK] The socket descriptor references a file, not a socket. [ENOPROTOOPT] The option is unknown or the protocol is unsupported. 5 htonl() Converts longwords from host to network byte order. Format #include <in.h> unsigned long int htonl (unsigned long int hostlong); 6 Argument hostlong A longword in host byte order (OpenVMS systems). All integers on OpenVMS systems are in host byte order unless otherwise specified. 6 Description This routine converts 32-bit unsigned integers from host byte order to network byte order. The network byte order is the format in which data bytes are expected to be transmitted through a network. All hosts on a network should send data in network byte order. Not all hosts have an internal data representation format that is identical to the network byte order. The host byte order is the format in which bytes are ordered internally on a specific host. The host byte order on OpenVMS systems differs from the network order. This routine is most often used with internet addresses. Network byte order places the byte with the most significant bits at lower addresses, whereas the OpenVMS system places the most significant bits at the highest address. NOTE The 64-bit return from OpenVMS Alpha systems has zero- extended bits in the high 32 bits of R0. 6 Return_Value x A longword in network byte order. 5 htons() Converts short integers from host to network byte order. Format #include <in.h> unsigned short int htons (unsigned short int hostshort); 6 Argument hostshort A short integer in host byte order (OpenVMS system). All short integers on the OpenVMS system are in host byte order unless otherwise specified. 6 Description This routine converts 16-bit unsigned integers from host byte order to network byte order. The network byte order is the format in which data bytes are expected to be transmitted through a network. All hosts on a network should send data in network byte order. Not all hosts have an internal data representation format that is identical to the network byte order. The host byte order is the format in which bytes are ordered internally on a specific host. The host byte order on OpenVMS systems differs from the network order. This routine is most often used with ports as returned by getservent(). Network byte order places the byte with the most significant bits at lower addresses, whereas the OpenVMS system places the most significant bits at the highest address. NOTE The 64-bit return from OpenVMS Alpha systems has zero- extended bits in the high 32 bits of R0. 6 Return_Value x A short integer in network byte order. Integers in network byte order cannot be used for arithmetic computation on the OpenVMS system. 5 inet_addr() Converts internet addresses in text form into numeric (binary) internet addresses in dotted decimal format. Format #include <in.h> #include <inet.h> int inet_addr (char *cp); 6 Argument cp A pointer to a null-terminated character string containing an internet address in the standard internet dotted decimal format. 6 Description This routine returns an internet address in network byte order when given as its argument an ASCII (null-terminated) string representing the address in the internet standard "." notation. Internet addresses specified with the "." notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the 4 bytes of an internet address. Note that when an internet address is viewed as a 32-bit integer quantity on the OpenVMS system, the bytes appear in binary as "d.c.b.a". That is, OpenVMS bytes are ordered from least significant to most significant. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as "parts" in a "." address expression can be decimal, octal, or hexadecimal, as specified in the C language (that is, a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). NOTE The 64-bit return from OpenVMS Alpha systems has zero- extended bits in the high 32 bits of R0. 6 Return_Values -1 Indicates that cp does not point to a proper internet address. x An internet address in network byte order. 5 inet_lnaof() Returns the local network address portion of an internet address. Format #include <in.h> #include <inet.h> int inet_lnaof (struct in_addr in); 6 Argument in An internet address. 6 Description This routine returns the local network address portion of a full internet address. NOTE The 64-bit return from OpenVMS Alpha systems has zero- extended bits in the high 32 bits of R0. 6 Return_Value x The local network address portion of an internet address in host byte order. 5 inet_makeaddr() Returns an internet address given a network address and a local address on that network. Format #include <in.h> #include <inet.h> struct in_addr inet_makeaddr (int net, int lna); 6 Arguments net An internet network address in host byte order. lna A local network address on network net in host byte order. 6 Description This routine combines the net and lna arguments into a single internet address. NOTE The 64-bit return from OpenVMS Alpha systems has zero- extended bits in the high 32 bits of R0. 6 Return_Value x An internet address in network byte order. 5 inet_netof() Returns the internet network address portion of an internet address. Format #include <in.h> #include <inet.h> int inet_netof (struct in_addr in); 6 Argument in An internet address. 6 Description This routine returns the internet network address (NET) portion of a full internet address. NOTE The 64-bit return from OpenVMS Alpha systems has zero- extended bits in the high 32 bits of R0. 6 Return_Value x The internet network portion of an internet address in host byte order. 5 inet_network() Converts a null-terminated text string representing an internet address into a network address in local host format. Format #include <in.h> #include <inet.h> int inet_network (char *cp); 6 Argument cp A pointer to an ASCII (null-terminated) character string containing a network address in the standard internet "." format. 6 Description This routine returns an internet network address as local host integer values when given as its argument an ASCII string representing the address in the internet standard "." notation. NOTE The 64-bit return from OpenVMS Alpha systems has zero- extended bits in the high 32 bits of R0. 6 Return_Values -1 Indicates that cp does not point to a proper internet network address. x An internet network address as local host integer values. 5 inet_ntoa() Converts an internet address into a text string representing the address in the standard internet "." notation. Format #include <in.h> #include <inet.h> char *inet_ntoa (struct in_addr in); 6 Argument in An internet address in network byte order. 6 Description This routine converts an internet address into an ASCII (null- terminated) string representing that address in the standard internet "." notation. WARNING Arguments should not be passed as integers because of how DEC C handles struct arguments. Because the string is returned in a static buffer that is overwritten by subsequent calls to inet_ntoa(), DIGITAL recommends copying the string to a safe place. NOTE The 64-bit return from OpenVMS Alpha systems has zero- extended bits in the high 32 bits of R0. 6 Return_Value x A pointer to a string containing the internet address in "." notation. 5 ntohl() Converts longwords from network byte order to host byte order. Format #include <in.h> unsigned long int ntohl (unsigned long int netlong); 6 Argument netlong A longword in network byte order. Integers in network byte order cannot be used for arithmetic computation on the OpenVMS system. 6 Description This routine converts 32-bit unsigned integers from network byte order to host byte order. The network byte order is the format in which data bytes are expected to be transmitted through a network. All hosts on a network should send data in network byte order. Not all hosts have an internal data representation format that is identical to the network byte order. The host byte order is the format in which bytes are ordered internally on a specific host. The host byte order on OpenVMS systems differs from the network order. This routine is most often used with internet addresses. Network byte order places the byte with the most significant bits at lower addresses, whereas the OpenVMS system places the most significant bits at the highest address. NOTE The 64-bit return from OpenVMS Alpha systems has zero- extended bits in the high 32 bits of R0. 6 Return_Value x A longword in host byte order. 5 ntohs() Converts short integers from network byte order to host byte order. Format #include <in.h> unsigned short int ntohs (unsigned short int netshort); 6 Argument netshort A short integer in network byte order. Integers in network byte order cannot be used for arithmetic computation on the OpenVMS system. 6 Description This routine converts 16-bit unsigned integers from network byte order to host byte order. The network byte order is the format in which data bytes are expected to be transmitted through a network. All hosts on a network should send data in network byte order. Not all hosts have an internal data representation format that is identical to the network byte order. The host byte order is the format in which bytes are ordered internally on a specific host. The host byte order on OpenVMS systems differs from the network order. This routine is most often used with internet ports as returned by getservent(). Network byte order places the byte with the most significant bits at lower addresses, whereas the OpenVMS system places the most significant bits at the highest address. 6 Return_Value x A short integer in host byte order (OpenVMS). 5 setsockopt() Sets options on a socket. The $QIO equivalent is the IO$_SETMODE or IO$_SETCHAR function. Format #include <types.h> #include <socket.h> int setsockopt (int s, int level, int optname, char *optval, int optlen); 6 Arguments s A socket descriptor created by socket(). level The protocol level for which the socket options are to be modified. It can have one of the following values: SOL_SOCKET Set the options at the socket level. p Any protocol number. Set the options for protocol level p. See the <in.h> header file for the various IPPROTO values. optname Interpreted by the protocol specified in level. Options at each protocol level are documented with the protocol. The following options are available at the socket level: o SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind() call should allow reuse of local addresses. o SO_KEEPALIVE keeps connections alive by enabling the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified through an EPIPE error. o SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. o SO_LINGER controls the actions taken when unsent messages are queued on the socket and a close() is performed. By default, transmitted data is purged from the socket when the close() is performed. SO_LINGER delays the internal socket deletion portion of close() until either the data has been transmitted or the device times out (in approximately 8 minutes). o SO_BROADCAST is used to enable or disable broadcasting on the socket. The first table that follows describes the socket options. If you include the UCX$INETDEF definition file, you can use the options listed in the following three tables. Table 1-1 Communications Socket Options Socket Option Description UCX$C_RCVBUF Sets the socket receive quota. This option requires a system UIC, SYSPRV, BYPASS, or OPER privilege to be set. UCX$C_SNDBUF Sets the socket send quota. This option requires a system UIC, SYSPRV, BYPASS, or OPER privilege to be set. UCX$C_NO_RCV_ Disables checksum calculation for received CHECKSUM data. UCX$C_NO_SND_ Disables checksum calculation for CHECKSUM transmitted data. UCX$C_NO_CHECKSUM Disables checksum calculation altogether. Unsupported socket options are ignored. You normally set and clear options with item_list descriptors. Table 1-2 TCP/IP Options TCP/IP Option Description UCX$C_USELOOPBACK Shortcuts the data transfer when the transfer is local to the host. This improves the performance of the local TCP /IP transfer process and results in a lower load on the CPU when applications using local transfer are active. UCX$C_TCP_NODELAY Specifies that the send operation will not be delayed to coalesce packets. UCX$C_TCP_PROBE_ Specifies the time interval for the IDLE KEEPALIVE probe, as well as for the connection establishing the timeout. UCX$C_TCP_DROP_IDLE Specifies the time interval after which the connection is dropped. UCX$C_FULL_DUPLEX_ Returns an EPIPE error (SS$_LINKDISCON) CLOSE the first time data is sent after the peer has closed its half of the connection. Subsequent send operations on the half- closed socket proceeds normally. Table 1-3 IP Options IP Option Description UCX$C_IP_TTL Time to live for a datagram UCX$C_IP_TOS Type of service (1-byte value) optval Points to a buffer containing the parameters of the specified option. All socket level options other than SO_LINGER should be nonzero if the option is to be enabled, or zero if it is to be disabled. SO_LINGER uses a linger structure parameter defined in the <socket.h> file. This structure specifies the desired state of the option and the linger interval. The option value for the SO_ LINGER command is the address of a linger structure. If the socket promises reliable delivery of data and l_onoff is nonzero, the system blocks the process on the close() attempt until it is able to transmit the data or until it decides it is unable to deliver the information. A timeout period, called the linger interval, is specified in l_linger. If l_onoff is set to zero and a close() is issued, the system processes the close in a manner that allows the process to continue as quickly as possible. optlen An integer containing the size of the buffer pointed to by optval. 6 Description This routine manipulates options associated with a socket. Options can exist at multiple protocol levels. They are always present at the uppermost socket level. When manipulating socket options, specify the level at which the option resides and the name of the option. To manipulate options at the socket level, specify level as SOL_SOCKET. To manipulate options at any other level, supply the protocol number of the appropriate protocol controlling the option. For example, to indicate that an option is to be interpreted by TCP, set the level to the protocol number (IPPROTO_TCP) of TCP. See <in.h> for the various IPPROTO values. 6 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 6 Errors You can set errno to the following values: [EBADF] The descriptor is invalid. [ENOTSOCK] The socket descriptor references a file, not a socket. [ENOPROTOOPT] The option is unknown. [EFAULT] The optname parameter is not a valid part of the user address space. 5 vaxc$get_sdc() Returns the socket device channel (SDC) associated with a socket descriptor for direct use with DIGITAL TCP/IP Services for OpenVMS software. Format #include <socket.h> short int vaxc$get_sdc (int s); 6 Argument s A socket descriptor. 6 Description This routine returns the SDC associated with a socket. C Socket descriptors are normally used either as file descriptors or with one of the routines that takes an explicit socket descriptor as its argument. C Sockets are implemented using TCP/IP socket device channels. This routine returns the SDC used by a given socket descriptor so you can use the TCP/IP facilities directly by means of various I/O system services ($QIO). NOTE The 64-bit return from OpenVMS Alpha systems has zero- extended bits in the high 32 bits of R0. 6 Return_Values 0 Indicates that s is not an open socket descriptor. x The SDC number. 2 Displaying_User_Information For displaying information about users on remote systems and your local system, the DIGITAL TCP/IP Services for OpenVMS (UCX) product includes the Finger utility. For example, you can use the utility to determine which users are logged on to a system or to refresh your memory about the correct login name to use before using FTP or another service to connect to an account on a remote host. The Finger listing may include such information as: o User name o Account name o Program the user is running o User's home directory o User's plans, activities, and other information o User's project 3 Commands Use the following rules for command syntax, quotation marks, and wildcards when you type FINGER command lines. 4 Quotation_Marks By default, the Finger utility translates all user and host name specifications to lowercase. If you specify any letters that must be uppercase, then you must enclose them in quotation marks. In the following example, the UNIX user name includes uppercase letters that need quotation marks around them: FINGER "B"OB"M"ILLER@BASE1 4 Wildcards Wildcards are not accepted for OpenVMS hosts, but may be valid for some UNIX hosts. 4 Qualifiers Qualifiers to the FINGER command must follow immediately after the command, preceding the user and/or host name. If the qualifier follows the user and/or host name, the Finger utility interprets the qualifier as a user name. For example, in the following command the qualifier /FULL incorrectly appears after the user specification. As indicated by the last line in the display, the Finger server interprets "/FULL" as a user login name. $ FINGER ROLLINS /FULL Username Program Login Term/Location ROLLINS $ Mon 15:02 64626::ROLLINS Login name: ROLLINS In real life: Professor Rollins Account: RES9 Directory: WORK1$:[ROLLINS] Last login: Tue 4-MAR-1997 09:05:29 Unread mail: 25 Project: Homeopathic medicine/Silica No Plan. Login name: /FULL In real life: ??? The following example shows the correct position of the qualifier (the information displayed now includes user ROLLINS' real name and current program). $ FINGER /FULL ROLLINS [stlab1.bastyr.edu] Username Real Name Program Login Term/Location ROLLINS Ben Rollins $ Mon 15:02 64606::ROLLINS $ Mon 09:42 64606::ROLLINS Login name: ROLLINGS In real life: Professor Rollins Account: RES9 Directory: WORK1$:[ROLLINS] Last login: Tue 4-MAR-1997 09:05:29 Unread mail: 27 Project: Homeopathic medicine/Silica No Plan. 3 User_Information To display information about all users on a remote host, enter the FINGER command followed by the host name (FINGER @hostname). To display more detailed information about a particular user, specify the user name with the host name (format FINGER username@hostname). To display information about all users on your local host, enter the FINGER command without specifying a host name. To display detailed information about a specific user on your local host, enter the FINGER command followed by the user name. The following table summarizes the different ways to display user information. Table 1-1 Displaying User Information If you need ... Use this command... Brief information FINGER @hostname about all users on a remote host Brief information FINGER about all users on your local host Brief information FINGER/CLUSTER about all users on your cluster Detailed information FINGER username@hostname about a specific user on a remote host Detailed information FINGER user1name@hostname several users on a user2name@hostname remote host Detailed information FINGER username about a specific user on your local host Detailed information FINGER user1name user2name about several users on your local host More detailed FINGER/FULL information about users on the local host, including their real name and all logins Detailed information FINGER/ALL username about a specific local user and brief information about all local users 4 All_Users,_Brief_Listing To display brief information about all users on a host, use the FINGER command with the host name only, in the format @hostname. If you use the FINGER command alone (without specifying a host name), you receive brief information about all users on your local system. The following example shows how to display brief information about all users on remote host BASTYR: $ FINGER @SCIENCE [science.ucd.edu] Username Program Login Term/Location BRADY $ Thu 07:50 dialin_706_101.ucd.lab.edu CORRIT $ Tue 13:30 64334::CORRIT DAVE MAIL Mon 15:02 64334::DAVE DAWSON $ Thu 14:57 FLOYD $ Mon 17:00 KITT TPU Mon 16:57 62555::KITT MIRTH $ Wed 16:04 UCDVAX::MIRTH NATALIE $ Tue 09:23 64222::NATALIE RAPSONG $ Mon 18:50 64442::RAPSONG 4 Specific_Users,_Detailed_Listing To display details about one or more users on a remote host, specify the user name or a list of user names, including the host name with each user name, as shown in the examples that follow. To display more information about users on your local host, specify the user name(s) without a host name. The information about each user includes the following items in addition to the user (login) name, program, login time, and terminal/location that is returned in the default, brief display: o Login name o Full name (real name) o Working directory o Last (previous) login o Number of unread mail messages o Plans and project, if the user has made the information available The following examples show how to display information about specific users. 1. This example shows how to receive detailed information about user HOWE on host BEARINGS. The second line of information indicates user HOWE is logged on and using the Mail utility. $ FINGER HOWE@BEARINGS [bearings.us.beacorp.com] Username Program Login Term/Location HOWE MAIL Mon 15:02 84640::HOWE Login name: HOWE In real life: Abe Howe Account: INVENT Directory: DISK$1:[HOWE] Last login: Tue 14-MAR-1997 10:15:39 No unread mail Project: Inventory No Plan. 2. To display information about several specific users on a remote host, specify each username@hostname separated by a space. This example shows how to display detailed information about users HOWE and JESSE on host BEARING, and user billings on UNIX host class. Note that user HOWE is not currently logged on to host BEARING. JESSE is, and so FINGER includes a line of information for JESSE including the program JESSE is using (DCL at present) and the time of login. $ FINGER HOWE@BEARING JESSE@BEARING BILLINGS@CLASS [bearings.us.beacorp.com] Login name: HOWE In real life: Abe Howe Account: INVENT Directory: DISK$1:[HOWE] Last login: Tue 14-MAR-1997 10:15:39 No unread mail Project: Inventory No Plan. [bearings.us.beacorp.com] Username Program Login Term/Location JESSE $ Thu 09:24 Login name: JESSE In real life: JESSE BOYD Account: PLAN3 Directory: DISK$1:[JESSE] Last login: Mon 3-MAR-1997 16:48:50 Unread mail: 1 Project: Planning Plan: Next phase: December Email: jesse@bearings.us.beacorp.com Phone: 526-5444 [class.ucb.beacorp.com] Login name: billings (messages off) In real life: M. T. Billings Office: BLDG2-2, 236-8936 Home phone: 508-466-7873 Directory: /usr/users/billings Shell: /usr/bin/csh On since Jan 17 14:33:06 on :0 On since Jan 17 14:33:13 15 days Idle Time on ttyp1 On since Jan 17 14:33:13 2 days 23 hours Idle Time on ttyp2 On since Feb 4 13:13:50 2 days 23 hours Idle Time on ttyp5 No Plan. 3. To display detailed information about one or more specific users and brief information about all other users logged on a remote host, specify the user@host format for the specific users plus @host for the brief listing of all users, as in this example. $ FINGER DALB@BEARING @BEARING Username Program Login Term/Location Login name: DALB In real life: Bob Dalb Account: ENG_3 Directory: WORK1$:[DALB] Last login: Thu 6-MAR-1997 16:26:06 No unread mail Project: TCP/IP Services for OpenVMS No Plan. BRADY $ Thu 07:50 dialin_706_101.lkg.dec.com BYRD $ Mon 17:00 CORTEZ $ Tue 13:30 60121::CORTEZ DALB UCX$FINGER Thu 16:26 54242::DALB KURT $ Mon 16:57 32556::KURT LARSON SHWCLSTR Mon 17:01 MUELLER $ Wed 16:04 VALVE::MUELLER NASAN $ Tue 09:23 44500::NASON PHILLIPS $ Tue 02:42 REMHST::PHILLIPS ROLLINS $ Mon 18:50 46142::ROLLINS SIMMEL MAIL Thu 14:12 VALVE::SIMMEL 4. To specify detailed information about specific users and brief information about the remaining logged-in users on a local host, use the the /ALL qualifier as in this example, which displays specific information about user HOWE at the local host plus brief information about all other users logged in. The output of this command is similar to that shown in the preceding example. $ FINGER/ALL HOWE 4 Cluster_Lookup To display information about users on all nodes in your local OpenVMS Cluster, use the /CLUSTER qualifier, as in the following examples. 1. This example shows the default display for the FINGER/CLUSTER command. $ FINGER/CLUSTER Username Node Program Login Term/Location ANND UCDAXP $ Mon 17:00 BRADY UCDAXP $ Thu 07:50 dialin_706_101.ucd.lab.edu CALLING UCDALP RTPAD Thu 14:50 CALLING UCDAXP $ Thu 14:57 CURREN UCDAXP $ Tue 13:30 84051::CURREN DOBB UCDWON UCX$FINGER Mon 11:50 GILBERT UCDVAX MAIL Thu 14:34 pcgil.admin.ucd.edu IMMIN UCDALP $ Wed 16:21 BIXBY::IMMIN KITT UCXAXP $ Mon 16:57 62555::KITT KITTEL UCXALP $ Thu 14:12 AGGIE::KITTEL LEVINE UCDUNI DECW$SESSION Thu 10:50 LEVINE UCDALP UCX$UCP Thu 10:30 llevine.philos.ucd.edu MILLLER UCDALP UCX$FINGER Thu 15:00 AGGIE::MILLER MIRTH UCDVAX $ Tue 17:09 MIRTH UCDVAX RTPAD Mon 17:27 NATALIE UCDAXP $ Tue 09:23 64222::NATALIE POFF UCXAXP $ Tue 02:42 AGGIE::POFF RAPSONG UCDAXP $ Mon 18:50 64442::RAPSONG TIBBS AGGIE $ Tue 20:43 UCXAXP::TIBBS 2. You can display each user's real name and every login to cluster members by including the /FULL qualifier, as in this example. $ FINGER/CLUSTER/FULL Username Real Name Node Program Login Term/Location ANND Ann Darin UCDAXP $ Mon 17:00 UCDAXP $ Tue 11:51 BRADY Robert Brady UCDAXP $ Thu 07:50 dialin_706_101.ucd.edu UCDWON $ Fri 08:31 CALLING Alvin Calling UCDALP RTPAD Thu 14:50 UCDAXP $ Thu 14:57 CURREN Steve Curren UCDAXP $ Tue 13:30 84051::CURREN UCDVAX $ Tue 14:20 DOBB Barry Dobb UCDWON UCX$FINGER Mon 11:50 UCDAXP $ Wed 09:20 GILBERT Joanne Gilbert UCDVAX MAIL Thu 14:34 pcgil.admin.ucd.edu IMMIN Armen Immin UCDALP $ Wed 16:21 BIXBY::IMMIN KITT Evelyn Kitt UCXAXP $ Mon 16:57 62555::KITT UCDALP SEARCH Mon 16:43 62555::KITT KITTEL Herb Kittel UCXALP $ Thu 14:12 AGGIE::KITTEL LEVINE Larry Levine UCDUNI DECW$SESSION Thu 10:50 UCDALP UCX$UCP Thu 10:30 slevine.philos.ucd.edu MILLLER Paul Miller UCDALP UCX$FINGER Thu 15:00 AGGIE::MILLER MIRTH Phil Anson UCDVAX $ Tue 17:09 UCDVAX RTPAD Mon 17:27 NATALIE Natalie Beardsley UCDAXP $ Tue 09:23 64222::NATALIE POFF Pamela Offred UCXAXP $ Tue 02:42 AGGIE::POFF RAPSONG Aaron Feller UCDAXP $ Mon 18:50 64442::RAPSONG TIBBS Eugene Tibbs AGGIE $ Tue 20:43 UCXAXP::TIBBS 3 Host_Forwarding If your host does not have a direct connection to a remote host, you can use a forwarding host to get the information about users on that remote host. Your local host must be able to connect directly to the forwarding host, and the forwarding host must be able to connect directly to the destination. Specify the destination host and the forwarding host in the following format: username@destination_host@forwarding_host. For example, system UNION.CTSTATEU.EDU is not directly reachable, but you can get information from it indirectly through a gateway named U- GW.PA.ABCORP.COM. You would enter the following command to get information about user JONES on host UNION.CTSTATEU.EDU: $ FINGER JONES@UNION.CTSTATEU.EDU@U-GW.PA.ABCORP.COM By default, the Finger server does not allow queries to be forwarded from one host to another. To enable forwarding on the Finger server, see your system manager. 3 Plan_and_Project_Information You can use the Finger utility to display a user's project and plans. The project (a single line of text) indicates the user's current project, work assignment, or work group. The user's plans can include several lines of information, such as where the user will be throughout the week, what the user plans to accomplish during the week, or even such information as the user's Web site, E-mail address, and telephone number, as in the following example: I will be in my office Monday through Wednesday working at the S.F. lab. On Thursday and Friday, I will be at UC Irvine for a conference. Web site http://bio.ucd.edu/peters/r_peters.html If you want to make such information about yourself available to other users through the Finger utility, create the following files in your home directory and add the appropriate information: .PLAN A file that contains your plans, whereabouts, and other information you wish to have displayed. The file can contain more than one line. .PROJECT A file that specifies your project and/or work group. The file can contain only one line. 2 File_Transfer The DIGITAL TCP/IP Services for OpenVMS (UCX) software includes the File Transfer Protocol (FTP) service. FTP allows you to connect to a remote host and: o Transfer files between your local host and the connected remote host o Append local files to remote host files o Delete and rename files on the remote host o Create, delete, and rename directories on the remote host o View the contents of directories and files on the remote host o Print local files at a printer on the remote host o Print remote files at a printer on your local host FTP also allows you to set and display the default working directory on the remote host as well as on your local host, and to customize FTP command processing. You can also use RCP to copy files. For more information on RCP, see R_Commands. 3 Typing_Commands Use the following rules for command syntax, quotation marks, and wildcards when you type FTP command lines. o Command formats With the FTP command and most of the commands at the FTP prompt, you can use either DCL-style or UNIX-style syntax. For example, the DCL-style DIRECTORY and UNIX-style ls commands produce the same results, as shown in the following example: FTP> DIRECTORY/BRIEF *.DIR 200 PORT command successful 150 Opening data connection for DISK$2:[FLIGHT]*.DIR (11.21.308.100,2643) com.dir;1 dis.dir;1 mail.dir;1 226 NLST Directory transfer complete. 43 bytes received in 00:00:00.09 seconds (0.42 Kbytes/s) FTP> FTP> ls *.dir 200 PORT command successful 150 Opening data connection for DISK$2:[FLIGHT]*.DIR (11.21.308.100,2644) com.dir;1 dis.dir;1 mail.dir;1 226 NLST Directory transfer complete. 43 bytes received in 00:00:00.04 seconds (1.02 Kbytes/s) FTP> o Quotation marks When you communicate with a non-OpenVMS host, you need to enclose the following with quotation marks: o UNIX path names o UNIX file names with slashes o Lowercase or mixed-case host names, user names, passwords, file names, and command lines In the following example, UNIX path names need quotation marks around them: FTP> PUT/FDL STAT.BCK "/USERS/SANDERS/CYGNET.BCK" . . . FTP> o Wildcards You can use wildcards in the following FTP commands: DELETE, DIRECTORY, GET, and PUT. The wildcard characters recognized by FTP are: o The percent sign (%) to represent an individual character o The question mark (?) to represent an individual character o The asterisk (*) to represent multiple characters If any of these characters are part of a file name (not used as a wildcard), you can disable recognition of these characters as wildcards by either enclosing the file name in quotation marks or using the DISABLE PARSE command. o Qualifiers The following FTP commands require that you specify qualifiers immediately following the command, with no space between command and qualifier: o CREATE o GET o HELP o PUT In the following example, the user twice attempts to enter the GET command without the proper positioning of the /CONFIRM qualifier. FTP> GET TEMP. *.* /CONFIRM 1 %CLI-W-MAXPARM, too many parameters - reenter command with fewer parameters \"/confirm"\ FTP> GET /CONFIRM TEMP. *.* 2 %CLI-W-MAXPARM, too many parameters - reenter command with fewer parameters \"*.*"\ FTP> GET/CONFIRM TEMP. *.* 3 Get TEMP. ? [Y or N ] [Y]:Y 200 TYPE set to IMAGE. 200 PORT command successful. 150 Opening data connection for TEMP. (16.20.208.53,2634) 226 Transfer complete. local: WORK10$:[MILGROM]TEMP.;13 remote: TEMP. 153 bytes received in 00:00:00.01 seconds (9.33 Kbytes/s) FTP> 1 In this first attempt, the /CONFIRM qualifier is entered following the file name parameters rather than immediately after the GET command. An error message indicates too many parameters have been entered. 2 The /CONFIRM qualifier follows the GET command, but with a space between. An error message indicates too many parameters have been entered. 3 The user enters the qualifier immediately after the command. FTP prompts the user to confirm that file TEMP. is to be copied and then sends a copy of the file from the remote host. 3 Customizing_FTP You can modify the way FTP transfers files, depending on: o The operating system of the remote host o The applications you use o Whether you want wildcard name expansion o The information you want displayed during processing A few of the FTP commands that control FTP command processing are: o ENABLE/DISABLE LOG Enables or disables the display of FTP commands sent to the remote host. o ENABLE/DISABLE PARSE Enables or disables the expansion of file name specifications. o ENABLE/DISABLE REPLY Enables or disables the display of all responses from the remote host. o QUOTE Sends FTP commands directly to the remote host without local interpretation. The preceding commands control the way FTP displays command processing information and status. The SHOW STATUS command displays the current status of the FTP client (your local host) and, if you have a connection, the remote host. By default, FTP returns multiple lines of error messages (MULTILINE is enabled). The first line explains the general problem, while subsequent lines provide details to help you diagnose the source of the problem. These lines may include operating system as well as FTP messages. Applications that use FTP to transfer files under program control often do not need the extra messages returned. To disable the MULTILINE feature, when you supply a password to connect to a remote host, precede the password with a hyphen "-" (-password), as in the following example: $ FTP /USER=SALINGER /PASSWORD=-LETMEIN HAGELS The SHOW STATUS command displays whether the MULTILINE feature is enabled. You can modify the way FTP reacts to errors by using the SET ERROR_LEVEL command. By default, the error level setting is SUCCESS, which means that when FTP is running in batch mode, a warning or error message will cause FTP to exit. (FTP runs in batch mode when FTP commands are executed by a command procedure rather than interactively.) If you do not want FTP to exit upon a warning or error message, you can set the error level to ERROR. For example, in the following command procedure, if the default error level (SUCCESS) is in effect and directory [MILLER.USERS] does not exist, the resulting error would cause FTP to exit. $ FTP CONNECT HAGELS CD [MILLER.USERS] DEL *.*;* EXIT $ If the error level had been set to ERROR, FTP would not exit and the DELETE command in the command procedure would delete all files in your current working directory. Note that you can also set the error level to WARNING, which causes FTP to tolerate warning messages (but not error messages). 3 Starting You can start an FTP session in any of the following ways: o At the DCL prompt, issue the FTP command and specify a remote host. o At the DCL prompt, issue the FTP command with no parameters. At the FTP prompt, issue the CONNECT or open command, specifying a remote host. o Invoke and use FTP from a command procedure (Command Procedures). You must connect to a remote host before you can enter an FTP command that affects or displays files on the remote host. You can invoke FTP and, without connecting to a remote host first, enter the FTP commands that customize the FTP environment. 4 Remote_Connections When you establish an FTP connection, the remote user name defaults to your user name on the local system. If you have a different user name on the remote system, do one of the following: o On the FTP command line, enter the /USERNAME qualifier. o At the user name prompt, type your remote user name, for example: $ FTP SITE1 220 site1.midwest.billing.bench.com FTP server (Version 4.2) Ready Connected to SITE1.midwest.billing.bench.com. Name (SITE1:antel): crowe <return> 331 Username CROWE requires a Password Password: not echoed<Return> 230 User logged in If your connection is with another OpenVMS host, it executes your LOGIN.COM procedure. You can use your LOGIN.COM command procedure to customize the environment for your FTP sessions. The following example connects to host XENO using the FTP command: $ FTP XENO /USER="bennings" /PASSWORD="keysimpl"<Return> 220 xeno FTP Server (DIGITAL UNIX Wednesday January 5, 1997) ready Connected to XENO.site1.acctg.com. 230 User logged in FTP> In the following example, user DAVE invokes FTP and connects to UNIX host sanfran using the CONNECT command: $ FTP <Return> FTP> CONNECT SANFRAN <Return> 220 sanfran.golden.com FTP server (DIGITAL UNIX December 18, 1996) Ready Connected to sanfran.golden.com. Name (sanfran:dave): <Return> 331 Password required for dave Password: (not echoed) <Return> 230 User logged in FTP> 4 Anonymous_FTP Anonymous user access, also called Anonymous FTP, lets you make an FTP connection to a remote host by specifying the name ANONYMOUS (or another name defined by the system manager). With Anonymous FTP, you do not need: o A registered user account on the remote host o To use your own user account, if you have one o To supply a password With Anonymous FTP, you can: o View remote directories - View the guest and public directories with the FTP DIRECTORY command. - The public directory called GUEST$PUBLIC has general bulletin-board information. It contains files of interest to FTP users. o Copy files - Issue GET and PUT commands to copy files to and from GUEST$PUBLIC. - The public area is read-only. You can issue the GET command to copy files from the remote host to your local system. Optionally, there is an ANONYMOUS$USER directory where you can: - Delete files - Create directories - Delete directories - Rename files - Rename directories The system manager sets up the access restrictions for Anonymous FTP. How the manager does this determines the availability of features. In the following example, UNIX user williams uses Anonymous FTP to connect to the ANONYMOUS account on OpenVMS host TRACTPLAN. Rather than prompting for a password, TRACTPLAN asks for the user name. % ftp tractplan Connected to tractplan.green_dev.org. 220 tractplan FTP Server (Version 4.2) Ready Name (tractplan:williams): anonymous 331 Guest login ok, send ident as password Password: williams@tractplan.edu 230 Guest login ok, access restrictions apply WELCOME to DIGITAL TCP/IP Services for OpenVMS (UCX) on Internet Host TRACTPLAN Date 04-24-97 FTP> 3 Exiting You can end an FTP session and return to the DCL prompt with any of the following commands: EXIT, quit, or Ctrl/Z. The following examples close the connection with the remote host, if one is open, and exit FTP. FTP> EXIT 221 Goodbye. $ FTP> QUIT 221 Goodbye. $ If however, you want to close a connection while remaining at the FTP prompt, use the DISCONNECT or close command. The following examples close a connection, if one is open, and remain at the FTP prompt for you to continue using FTP. FTP> DISCONNECT 221 Goodbye. FTP> FTP> CLOSE 221 Goodbye. FTP> 3 Command_Procedures You can use either OpenVMS or UNIX command syntax in DCL command procedures that use FTP. You can use command procedures to invoke FTP tasks, connecting to a remote host and performing assorted file operations with the remote host (see Task Command Files), and you can use command procedures to customize the FTP environment (see Initialization Command File). 4 Task_Command_Files You can create DCL command procedures that include FTP commands. In the following example, DCL command procedure FTP_TO_SANFRAN.COM invokes FTP and copies file needs.lis from host dave: $! FTP_TO_SANFRAN.COM $! This command procedure uses FTP from within $! a DCL command file. Note that the password "letmein" $! does not need quotation marks, but it is case sensitive. $! $ FTP CONNECT sanfran LOGIN "dave" letmein GET nest.lis EXIT $ EXIT $ This next example, command procedure FTP_PASS_PARAMETER.COM, accepts parameters, writes a temporary command procedure, and executes this procedure. $! $! FTP_PASS_PARAMETER.COM $! This method is useful for automated BATCH queue jobs. $! $ WS =="WRITE SYS$OUTPUT" $ IF P1 .EQS "" .OR. P2 .EQS. "" .OR. P3 .EQS. "" .OR. P4 .EQS. "" $ THEN $ WS "@FTP_PASS_PARAMETER LOCAL-FILE SYSTEM USERNAME PASSWORD" $ EXIT $ ENDIF $! $ COM == "FTP_TEMP.COM" $ LOG == "FTP_TEMP_COM.LOG" $ FILE == "''P1'" $ USER == F$EDIT("''P3'","LOWERCASE") $ PASSW == F$EDIT("''P4'","LOWERCASE") $! $ ON WARNING THEN GOTO ERR $ OPEN/WRITE OUTFILE 'COM $ WRITE OUTFILE "$ DEFINE SYS$OUTPUT ''LOG'" $ WRITE OUTFILE "$ FTP" $ WRITE OUTFILE "open ''P2'" $ WRITE OUTFILE "user ''USER'" $ WRITE OUTFILE "''PASSW'" $ WRITE OUTFILE "put ''FILE'" $ WRITE OUTFILE "quit" $ WRITE OUTFILE "$ EXIT" $ CLOSE OUTFILE $ @'COM $ DELETE 'COM;* $ PURGE 'LOG $! $! You can open the FTP_TEMP_COM.LOG file to check for errors, $! for example, checking the initial return code for $! 4xx (retry condition), or 5xx (failure condition). $! $ EXIT $! $ ERR: $ IF F$TRNLNM("OUTFILE") .NES. "" THEN CLOSE OUTFILE $ DELETE 'COM;* $ EXIT $ 4 Initialization_Command_File Initialization command files can customize your FTP sessions with SET, ENABLE, and DISABLE commands. These command files are optional. They eliminate the need to issue individual FTP commands, and run automatically when you invoke FTP. Initialization command files must: o Be located in your login directory o Be called FTPINIT.INI o Contain only one command per line The following example shows an FTP initialization command procedure. ! This file, FTPINIT.INI, sets my FTP parameters ! the way I like them. ! ENABLE REPLY ENABLE TRANSFER_VERIFICATION SET DEFAULT /LOCAL [MILLER.WORK] When you invoke FTP, the initialization file generates output such as the following, which displays environmental status: $ ftp Reply on. Verbose mode on. Bell off. Hash mark printing on (1024/hash mark). Local directory now SYS$LOGIN_DEVICE:[MILLER.WORK] 3 Default_Directory During an FTP session, you can display or change the current default directory either on the remote host or on your local host. To display the default (working) directory on the remote host, use the SHOW DEFAULT command as in the following example: FTP> SHOW DEFAULT 257 "/usr/users" is the current directory. To display the working directory on the local host, use the SHOW DEFAULT command with the /LOCAL qualifier, as in the following example: FTP> SHOW DEFAULT/LOCAL Local directory is DISK$6:[MANAGER]. To change the default directory on the remote host, use the SET DEFAULT command. The following example shows how to change the default directory on a remote DIGITAL UNIX host to /usr/users /robert: FTP> SET DEFAULT "/USR/USERS/ROBERT" 250 CWD command successful. 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. 250 New default directory is /USR/USERS/ROBERT This next example changes the remote working directory from /usr /flyers/localads to /usr/flyers/localads/music: FTP> SET DEFAULT MUSIC To change the default directory on your local host, use the SET DEFAULT command with the /LOCAL qualifier. The following example sets the local default directory to USER$1:[PLANS.CHECKS]: FTP> SET DEFAULT /LOCAL USER$1:[PLANS.CHECKS] Local Directory now USER$1:[PLANS.CHECKS] This next example changes the local OpenVMS default directory down one level from [DECK] to [DECK.HEARTS]: FTP> SET DEFAULT /LOCAL [.HEARTS] 3 Creating_and_Deleting_Directories To create a directory on a connected remote host, use the CREATE /DIRECTORY command. The following command example creates a subdirectory .LOCAL_ACCTS in the current working directory on the connected remote OpenVMS host. FTP> CREATE/DIRECTORY [.LOCAL_ACCTS] To delete a directory, use the DELETE/DIRECTORY command as in the following example. The command deletes the directory created in the preceding example. FTP> DELETE/DIRECTORY LOCAL_ACCTS.DIR;* 3 Viewing_Remote_Directories Use the DIRECTORY command to list the files and associated information in remote directories. For example, the following command lists the files in the default directory on a remote UNIX host (assuming the user already has connected to the remote host): FTP> DIRECTORY 200 PORT command successful 150 Opening ASCII mode data connection for /bin/ls (16.20.208.54,1312) total 6303 -rw-rw-r-- 1 milgrom users 1 Jan 9 1996 #UNTITLED# -rw------- 1 milgrom users 4 Apr 11 1996 .Xauthority -rwxr-xr-x 1 milgrom users 1499 Feb 3 1995 .cshrc drwxr-xr-x 11 milgrom users 8192 Jan 9 1996 .dt -rwxr-xr-x 1 milgrom users 3970 Dec 13 1995 .dtprofile 3 Renaming_and_Deleting_Files To rename remote files, use the RENAME command. The following command renames file YEAR.DAT to YEAR96.DAT on the connected remote host. FTP> RENAME YEAR.DAT YEAR96.DAT To delete remote files, use the DELETE command. The following command deletes all versions of file YEAR.DAT on the connected remote host. FTP> DELETE YEAR.DAT;* 3 Appending_Files The FTP APPEND command allows you to append a local file to a file on a connected remote host. The following command appends local file JUL_DEC.DAT to file YEAR.DAT on remote host KALI. (A connection has already been established to the remote host.) FTP> APPEND JUL_DEC.DAT YEAR.DAT 200 PORT command successful 150 Opening data connection for year.dat. (130.180.4.8,1108) 226 Append transfer complete local:large.txt remote:remote.dat 15596 bytes sent in 00:00:00.10 seconds (152.30 Kbytes/s) 3 Viewing_File_Contents To display the contents of a file on a connected remote host, use the VIEW command and specify the file name. If you are not yet connected to a remote host, you can use the VIEW command to display the contents of a file on your local host. In either case, if the file is not in your current working directory, include the directory name in the file specification. The following example shows how to display the contents of file ENG.DIS in your working directory on a connected host: FTP> VIEW ENG.DIS usrm::"khuna@jnet.com" pobox::bearse yield::timms usrm::"lerry@muster.cudenver.edu" sam nm%us1rmc::"ldutton@TopCom.com" 3 Copying_Files To copy files from a remote host to your local host, use the GET command. To copy files from your local host to a remote host, use the PUT command. To use these commands, you must have an active FTP session with a remote host. You can enter any number of commands during the session. Beginning with OpenVMS Version 6.2, you can also use the COPY/FTP command to copy files across the network using TCP/IP. For more information on this command, type HELP COPY/FTP at the DCL prompt. Use the GET command to copy one or more files from a remote host to your local host. For example, to copy the UNIX file acct.pay, located in the remote working directory, to your local OpenVMS host, use the following command: FTP> GET ACCT.PAY Use the PUT command to copy one or more files from your local host to a remote host. For example, the following command copies the local file ACCTS.LIS to a connected remote UNIX host. Use the /FDL qualifier to prevent record attributes from being lost in the transfer from OpenVMS to UNIX systems. FTP> PUT ACCTS.LIS 4 How_FTP_Copies_Files_ FTP resolves the differences between UNIX file systems and OpenVMS file systems automatically. By default, the PUT command copies files to UNIX systems using lowercase file names without version numbers. If you use a wildcard to copy all versions of a file: - The version numbers become the last element of the copied files. - Semicolons are converted to periods. 4 Store_Unique The Store Unique (STOU) feature allows you to control how file version numbers are treated when you copy (PUT) files from local to remote hosts. After connecting to the remote host, you toggle the Store Unique feature on and off by issuing the sunique command at the FTP prompt, as follows: FTP> sunique Store unique on. FTP> sunique Store unique off. FTP> sunique Store unique on. The Store Unique feature behaves differently when copying files from OpenVMS to UNIX or from UNIX to OpenVMS. It also behaves differently if you use wildcards or specify version numbers. For example, the results vary when you copy the file text.txt as follows: Store Unique FTP Command On Store Unique Off From OpenVMS to UNIX FTP> PUT text.txt text.txt text.txt FTP> PUT text.txt.1 text.txt.1.1 text.txt;1 FTP> PUT text.txt.1 text.txt.1.1 text.txt;* text.txt.2 text.txt.2.1 text.txt.3 text.txt.3.1 From UNIX to OpenVMS ftp> PUT text.txt text.txt$01 text.txt;1 4 VMS_Plus_Mode FTP performs fast file transfers between two OpenVMS systems (VMS Plus Mode). When FTP identifies file transfers between two OpenVMS hosts running DIGITAL TCP/IP Services for OpenVMS, it transfers files in large blocks, rather than small records. VMS Plus Mode greatly increases the transfer speed and preserves all Record Management Services (RMS) file attributes. FTP automatically disables VMS Plus Mode when your session is with a UNIX host or another OpenVMS host not running DIGITAL TCP /IP Services for OpenVMS. 4 File_Attributes When you transfer OpenVMS files to a UNIX system and back again, some record attributes might be lost. To preserve all RMS file attributes, use the /FDL qualifier (File Definition Language) with the GET and PUT commands. You may also need to use the SET TYPE command to determine the type of file transfer: o Specifying SET TYPE ASCII results in a sequential file with variable records. Select this type when transferring ASCII text files. o Specifying SET TYPE IMAGE results in a sequential file with fixed records of 512 bytes. Select this type when transferring non-ASCII files such as binary files or executable image files. For example, to transfer an executable image to a remote UNIX host, follow these steps: 1. Specify the IMAGE data type: FTP> SET TYPE IMAGE 2. Transfer the file to the remote host while at the same time creating and transferring a secondary file with the file's OpenVMS record attributes: FTP> PUT/FDL file To retrieve the file from the remote UNIX host, follow these steps: 1. Specify the IMAGE data type: FTP> SET TYPE IMAGE 2. Retrieve the file from the remote host after retrieving and using the secondary file containing the file's OpenVMS record attributes: FTP> GET/FDL file.dat In this next example, the PUT/FDL command does the following: 1. Creates the FDL file cygnet.bckfdl on the remote host with the RMS attributes of file STAT.BCK . 2. Transfers the data in STAT.BCK and puts it into cygnet.bckfdl on the remote host. FTP> PUT/FDL STAT.BCK CYGNET.BCK 200 TYPE set to ASCII 200 PORT command successful 150 Opening data connection for cygnet.bckfdl (16.20.208.53,1028) 226 Transfer complete local: cygnet.bckfdl remote: cygnet.bckfdl 846 bytes sent in 00:00:00.03 seconds 200 TYPE set to IMAGE 200 PORT command successful 150 Opening data connection for cygnet.bck (16.20.208.53,1029) 226 Transfer complete local: STAT.BCK remote: cygnet.bck 8152 bytes sent in 00:00:00.12 seconds FTP> In this final example, the GET/FDL command does the following: 1. Transfers the FDL file cygnet.bckfdl from the remote host to the local host. 2. Uses this file to re-create the file STAT.BCK, with all of its original RMS attributes, on the local host. 3. Transfers the data in cygnet.bck and puts it into the new local file STAT.BCK. FTP> GET/FDL CYGNET.BCK STAT.BCK 200 TYPE set to ASCII 200 PORT command successful 150 Opening data connection for cygnet.bckfdl (16.20.208.53,1028) 226 Transfer complete local: cygnet.bckfdl remote: cygnet.bckfdl 846 bytes sent in 00:00:00.03 seconds 200 TYPE set to IMAGE 200 PORT command successful 150 Opening data connection for cygnet.bck (16.20.208.53,1029) 226 Transfer complete local: STAT.BCK remote: cygnet.bck 8152 bytes sent in 00:00:00.12 seconds FTP> 4 Transfer_Mode DIGITAL TCP/IP Services for OpenVMS supports only STREAM mode for data transfer. STREAM mode transmits the data as a stream of bytes. 4 File_Structure DIGITAL TCP/IP Services for OpenVMS supports transfers of ASCII (stream, records with variable length) and IMAGE (binary, records fixed at 512 bytes) files. A file is a continuous sequence of data bytes. 3 DECnet_Operations To copy files from and to a DECnet node, use the standard GET and PUT commands as described in the following paragraphs. You can copy files to and from DECnet nodes and get remote directory information, if your host and the DECnet node are connected through a host running DIGITAL TCP/IP Services for OpenVMS. Use the full file specification, including the node, device, directory, and file name. The following example copies local file FAX.TXT to DECnet node CURTAIL, renaming the file to CURRENT.TXT: FTP> PUT FAX.TXT CURTAIL::DISK$3:[GEARY.KEEPS]CURRENT.TXT The following GET command copies remote OpenVMS file HOUSING.TXT from DECnet node HABTAT and renames it to HOUSE.TXT: FTP> GET HABTAT::DISK$2:[NATL.UTAH.SWEST]HOUSING.TXT HOUSE.TXT 3 Printing Using FTP, you can: o Print remote files on the local host using the GET command. o Print local files on a remote host using the PUT command. Follow these requirements: o Specify a printer set for spooling. o Specify the actual name of the printer, not its queue name or logical name. o Send individual files not batch jobs. o When using the PUT command, specify a remote system that supports this feature. Note that you can also use the DCL PRINT command to print files across the network. 4 Print_Form FTP supports nonprint forms only. A SHOW STATUS command shows the form type as NON_PRINT. 4 Examples The following example sends the file MEMO.TXT from the local host to the printer LNAX:, which is connected to the remote host: FTP> PUT MEMO.TXT LNAX: This next example copies remote file q4earnings and sends it to local printer LPA0:. FTP> GET Q4EARNINGS LPA0: 3 Suspending_FTP While using FTP, you can use the SPAWN command to suspend your current session and create a subprocess at the local DCL prompt. At the DCL prompt, you can then enter any number of DCL commands. (You can also specify a DCL command in the SPAWN command line.) To return to your suspended FTP session (exiting the DCL subprocess), enter the LOGOUT command. In the following example, the user suspends the FTP session to list the files in the working directory on the local host and delete one of the files in that directory. FTP> SPAWN $ DIR . . . $ DEL TR3.TXT:* $ LOGOUT . . . FTP> 2 Mail For exchanging electronic mail (E-mail) with users working on internet hosts, the DIGITAL TCP/IP Services for OpenVMS (UCX) product includes Simple Mail Transfer Protocol (SMTP) and Post Office Protocol (POP) software. SMTP allows you to use the OpenVMS mail services to send and receive messages exchanged with users on other internet hosts. The POP software allows you to use your PC mail software to receive and send messages. The software stores mail sent to you, even when the PC is turned off. 3 Sending_Mail To send E-mail to another internet host also running SMTP, simply invoke the OpenVMS Mail utility at the DCL prompt, type SEND at the MAIL> prompt, and enter the destination. A remote destination consists of the user name followed by an ampersand (@) and the host (such as user_name@host). If the user is on your local host, omit the ampersand (@) and host name. $ MAIL MAIL> SEND To: destination_user@destination_host Specify the destination host as either a host name or an IP address. The following example sends mail to user MALCOLM at host PHILOS.BU.EDU: $ MAIL MAIL> SEND <Return> To: malcolm@philos.bu.edu <Return> Subj: Final Exams<Return> The following example sends mail to user MALCOLM at the host with IP address 16.20.40.59: $ MAIL MAIL> SEND <Return> To: malcolm@16.20.40.59 <Return> Subj: Final Exams<Return> The OpenVMS Mail utility automatically detects destination addresses that include fully qualified host names (where the node component includes a period (.), such as MALCOLM@PHILOS.BU.EDU) and sends the mail using the SMTP protocol, unless your system has been set up to use a different Internet protocol (by defining an alternate protocol with the MAIL$INTERNET_TRANSPORT logical name). However, if you use a destination address that is not fully qualified - that is, one in which the node component does not include a period (.) - the Mail utility by default assumes the address is a DECnet address. For example, if you specified MALCOLM@PHILOS as the destination address, the Mail utility converts it to the DECnet format PHILOS::MALCOLM. You can force the OpenVMS Mail utility to use a specific protocol by defining the MAIL$INTERNET_MODE logical name. This is useful in cases where a mail address, such as MALCOLM@PHILOS, can be valid for either SMTP or DECnet. You can assign one of the following values to the MAIL$INTERNET_ MODE logical name: o SMTP Mail always interprets the node component of an unqualified address as an Internet address specification. (SMTP is the default transport unless you define an alternate Internet transport with the MAIL$INTERNET_TRANSPORT logical name.) o DECNET Mail always interprets the node component of an unqualified address as a DECnet node specification. o HYBRID (the default) Mail uses an Internet protocol if the node component of the address contains a period. If no periods are in the node component, Mail uses the DECnet protocol. Define the logical name in your LOGIN.COM file. For example, the following definition causes the Mail utility to interpret any address that does not include a period in the node component of the specification as an Internet address: $ DEFINE MAIL$INTERNET_MODE SMTP Another way to force the OpenVMS Mail utility to use SMTP is to include the SMTP% prefix. At the To: prompt, type SMTP% and, with no space, either the destination name or IP address. Enclose the destination in quotation marks, as in the following example: $ MAIL MAIL> SEND To: SMTP%"malcolm@philos" So, if you want to prevent the OpenVMS Mail utility from automatically converting an unqualified Internet host name address to a format for DECnet use, you have three choices: o Fully qualify the host name (for example, specify MALCOLM@PHILOS.BU.EDU instead of MALCOLM@PHILOS). o Define the MAIL$INTERNET_MODE logical name as SMTP. o Include the SMTP% prefix and the destination address in quotation marks (for example, SMTP%"MALCOLM@PHILOS.BU.EDU"). For more information on the OpenVMS Mail utility and how it interprets addresses, see the appropriate OpenVMS documentation. 4 Name_Lists To send mail to more than one user, use the SEND command, but at the To: prompt type one of the following: o A list of names (Name Lists) o The name of an existing distribution list (Distribution Lists) When you type a list of names, use the following guidelines: o Separate each name with a comma ( , ). o If multiple users are on the same remote host, type the full user_name@host combination for each user. o If a user is on your local host, omit the ampersand (@) and host. Use the following syntax: MAIL> SEND To: user1,user2,user3@host3,user4@host4 where: user1 is located at the local OpenVMS system. user2 is located at the local OpenVMS system. user3 is located at host3. user4 is located at host4. MAIL> SEND To: user1@host5,user2@host5 In this example, both users are located at remote host5. The following example sends the same mail to: o Users NOWAK and BRENT on host CENTRAL.GREEN.ORG o User MILLER on host BOSTON.GREEN.ORG MAIL> SEND MEETINGS.TXT To: NOWAK@CENTRAL.GREEN.ORG,BRENT@CENTRAL.GREEN.ORG, MILLER@BOSTON.GREEN.ORG Subj: SCHEDULE AND AGENDAS 4 Distribution_Lists To send mail to multiple users, at the To: prompt, you can type a name list or use a distribution list. To send mail to multiple users by typing the name of a distribution list, follow these guidelines: o The file with the distribution list can be yours or belong to someone else. o The file can reside locally or remotely. o Do not include the names of other distribution lists in the distribution list. You can use two kinds of distribution lists: o OpenVMS distribution list - Create a .DIS file in your own directory or use an existing one. - You can include comment lines (lines preceded by an exclamation mark (!)). - You can include both OpenVMS addresses and SMTP addresses. If you want the Mail utility to use SMTP for all SMTP addresses, qualified and unqualified, either set the MAIL$INTERNET_MODE logical name to SMTP, specify fully qualified SMTP addresses only, or use the SMTP% prefix with the destination enclosed in quotation marks. - To send mail to the people on your distribution list, issue: MAIL> SEND To: @list_name o SMTP distribution list - Create, or use an existing, .DIS file in SYS$SPECIFIC:[UCX_ SMTP] or, if defined on your system, UCX$SMTP_COMMON:. - Give the list a unique name that is not the same as a local user name. - Specify comment lines with an exclamation mark (!) in the first column. - Include only SMTP addresses. - Use one address per line. - To send mail to the people on this distribution list, issue the following command: MAIL> SEND To: list_name@host_where_list_resides If the MAIL$INTERNET_MODE logical name is not set to SMTP, specify a fully qualified host name or use the SMTP% prefix with quotation marks enclosing the distribution list/host specification. The following examples show some different methods of using distribution lists. 1. This example sends mail to users whose names are on the local OpenVMS distribution list AGENCIES.DIS. The distribution list file is displayed in this example. The MAIL$INTERNET_MODE logical name is not set, so by default unqualified Internet addresses would be sent over DECnet; therefore, the AUDUBON@NY address is included with the SMTP% prefix and quotation marks. $ TYPE AGENCIES.DIS ! ! This is an OpenVMS distribution file named AGENCIES.DIS. ! SMTP%"audubon@ny" WILLIAMS@BELTWAY.ORG WILDLIFE@DALLAS.ORG jmuir@19.8.7.6 SEC@GP.INTER8.ORG BATES::SCOPE ! $ MAIL MAIL> SEND To: @AGENCIES.DIS Subj: NEWS TO WATCH FOR 2. This example sends mail to users whose names are on the local SMTP distribution list SYS$SPECIFIC:[UCX_SMTP]NATL_ INTEREST.DIS. The distribution list file is displayed in this example. $ TYPE NATL_INTEREST.DIS green@19.8.7.6 wlf@19.7.6.5 arlo@19.4.3.2 wendell@biolo.ne.edu $ MAIL MAIL> SEND To: natl_interest@main_office.org Subj: News Items 3. This example sends mail to the users on SMTP distribution list FINANCE_CENTERS.DIS, which is maintained on remote mail server host HOLBROOK. $ TYPE FINANCE_CENTERS.DIS ny_accts@23.9.7.4 sf_stocks@23.7.11.2 dallas_pfs@23.1.5.1 denver_accts@holbrook $ MAIL MAIL> SEND To: finance_centers@holbrook Subj: Portfolio Activity 3 Receiving_Mail To read received mail, follow these steps: 1. At the DCL prompt, type MAIL. 2. At the MAIL> prompt, use the DIRECTORY command to view a list of received messages. 3. Use the READ command or indicate the message number you wish to view in exactly the same way as you would for OpenVMS mail. In the following example, a user views the directory of unread new mail and selects Message 3 to read. $ MAIL You have 3 new messages. MAIL> DIRECTORY NEWMAIL # From Date Subject 1 GWAY::SMTP%"helenm@bhc 10-MAR-1997 Just Checking In 2 GWAY::SMTP%"mays@sfg 11-MAR-1997 Common Bases 3 CBIRD::SMTP%"seaway 12-MAR-1997 Cruises MAIL> 3 3 Name_String You can define a "personal name" string that is included at the top of all the mail messages you send. To create a personal name with SMTP mail, use the SET PERSONAL_NAME command with the following restrictions: o Enclose the string in quotation marks. o Do not use additional double quotation marks within the string. o You may use single quotation marks ( ' ' ). o Do not use 8-bit ASCII characters, for example, ä or ö. The eighth bit is truncated. For example, ä becomes d and ö becomes v. The following example shows a user setting a personal name that includes quotation marks: $ MAIL MAIL> SET PERSONAL_NAME "'Wellth' is in the mind" 3 Carbon-Copies You can enable "carbon copying" by using the SET CC-PROMPT command. Follow these guidelines when you specify destinations for the CC: prompt: o Follow the OpenVMS Mail conventions for copying mail to other people or to yourself. o For typing the correct address, follow the guidelines listed in Sending Mail. The following example sends mail to user AL and carbon copies users ROLLINS, BOND, and RICH: MAIL> SEND To: al@airways CC: rollins,bond,rich@flight_central.com Subj: Directions for Night Flight In the following example, OpenVMS user BRODIE sends mail to UNIX user owens and copies soltau. MAIL> SET CC_PROMPT MAIL> SEND To: owens@kezar CC: soltau@fgtoo.bonkers.org Subj: Goals for the Week Enter your message below. Press CTRL/Z when complete, or CTRL/C to quit: RC: Let's get a jump on the ball this time. We'll meet before the conference to organize. - J.B.<Ctrl/Z> (not echoed) <Exit> 3 Forwarding_Messages You can forward any mail you receive to any internet host. Follow the OpenVMS Mail conventions for forwarding mail. If you move to another system that supports SMTP, SMTP can forward your mail to your new location. When you set this features, type the new address within three sets of quotation marks. Use the following syntax: MAIL> SET FORWARD _Address:SMTP%"""new_user_name@forwarding_host""" To set the forward feature for another user, type the /USER qualifier. Issue: MAIL> SET FORWARD/USER=vms_node::name _Address:SMTP%"""new_user_name@forwrding_host""" For example, after reading a message, the FORWARD command forwards it to user SPAN at host MILWAK. MAIL> FORWARD To: SMTP%"span@milwak" CC: SELF Subj: Who's Starting In the following example, user CYGNET sets automatic SMTP forwarding from host NOW to user ELLIS at host FUTURE: MAIL> SET FORWARD /USER=now::cygnet _Address: SMTP%"""ellis@future""" 3 PC_Mail With SMTP and the Post Office Protocol (POP) functionality, you can receive and send OpenVMS mail from your PC. POP is a mail repository that accepts and stores your mail even when the PC is turned off. At your request, the POP server reads mail from your OpenVMS NEWMAIL folder, then moves the mail to your MAIL folder. To send and receive mail on your PC, make sure the system manager has configured the POP server for use on your PC (the POP client system). To set up your POP client account, use one of the following methods: o On networks where maximum security is not required, enter your PC mail application and configure a user name and password into the system. The user name and password pair becomes authorization information for the UCX system, not your POP client system. Your PC client sends the password to the POP server unencrypted. As an added security measure, POP permits only two user name and password authorization attempts per TCP connection. o On networks where maximum security is required, enter your PC mail account and configure a user name and shared-secret password into the system. This method is called the APOP authorization method where you store a shared-secret password in a one-line file named POP_ SECRET.DAT in your default OpenVMS mail directory. You can use the DCL command CREATE or your text editor to create the file and specify a password string, then set the file protection to prevent other users from accessing it. For example: $ SET DEFAULT USER$DISK:[JONES.MAIL] $ CREATE POP_SECRET.DAT xyztancreff <Ctrl/Z> $ SET FILE/PROT=(s,w,g,o:rwed) POP_SECRET.DAT The shared-secret password cannot exceed 500 characters. Each time you enter your PC mail application, the shared- secret string is sent from the PC client to the POP server using an encryption process. For more information about the POP process, including information about how POP builds SMTP-compliant mail headers, see the DIGITAL TCP/IP Services for OpenVMS Management guide. 3 Using_UUCP The UNIX-to-UNIX Copy Program (UUCP) lets a system copy files to and from other systems running UUCP. UUCP is usually used to copy files over a dialup connection (see Dialup Connections). To route mail using UUCP, ask your system manager to define the general gateway in the SMTP configuration. To use SMTP to route mail to a system running UUCP, address the mail as follows: MAIL> SEND To: SMTP%"user_name!uucp_host" The following example sends mail to geoffrey at host haldir: $ MAIL MAIL> SEND To: SMTP%"geoffrey!haldir.of.com" 4 Dialup_Connections Ask your system manager if you need to specify a gateway host in mail addresses when you work on UNIX-to-UNIX Copy Program (UUCP) dialup lines. The following example sends mail during a dialup connection by specifying a gateway host: MAIL> SEND To: gateway_host!crandle!watts CC: billw,jenny,ibis Subj: Events Schedule 3 Managing_Mail The UCX management commands that can help you work with SMTP mail currently in a queue are listed in the following table. Type them at the UCX> prompt. Table 1-1 UCX Commands for Using SMTP Command Function SHOW MAIL Displays information about mail REMOVE MAIL Deletes mail messages that are in holding state in SMTP queues SEND MAIL Releases for delivery a mail message that is in a holding state The following subsections describe how to use these commands. For full command descriptions, see the DIGITAL TCP/IP Services for OpenVMS Management Command Reference. 4 Displaying_Mail_Status Use the UCX SHOW MAIL command to display information about SMTP mail, such as: o Message (entry) number of the queued mail o User name of the sender (to display information about other users, you need SYSPRV or BYPASS privileges) o File name of the queued mail o Status of a message The following examples show how to display SMTP mail status information. 1. The following command displays information about message 826 in an SMTP queue. By default, the command returns brief information. Specify /FULL for more detailed information, as in the example that follows. $ UCX SHOW MAIL /ENTRY=826 SMTP Mail Queue Entry 826 User: MARLOW File: _PLUTO$DKD0:[MARLOW]970207015114579_MARLOW.UCX_PLUTO;1 Status: Processing 2. The following command displays detailed information about all your mail. The /RECIPIENT qualifier, used with the /FULL qualifier, displays selected classes of information, depending on the =option value you specify: Option Description ALL Shows failed, sent, and unsent messages FAILED Shows messages that could not be read for a particular recipient SENT Shows successful deliveries to a particular recipient UNSENT Shows messages that, as yet, are unsent $ UCX UCX> SHOW MAIL /FULL /RECIPIENT=ALL SMTP Mail Queue Entry: 826 User: MARLOW File: _PLUTO$DKD0:[MARLOW]970207015114579_MARLOW.UCX_PLUTO;1 Status: Processing Message Destinations: Address: marlow@pluto Message Headers: Return Path: ??? SMTP Mail Queue Entry: 828 User: MARLOW File: _PLUTO$DKD0:[MARLOW]970207015114580_MARLOW.UCX_PLUTO;1 Status: Holding Message Destinations: Address: marlow@pluto Message Headers: Return Path: ??? 4 Deleting_Queued_Mail The following examples show how to delete mail messages from SMTP queues, using the UCX REMOVE command (similar to the DCL DELETE /ENTRY command). NOTE Use this command only to release mail messages that are being held; do not use this command to delete mail messages in the processing state. 1. The following example deletes mail message 828, a message that is holding (the message corresponds to your process's user name, or you have SYSPRV or BYPASS privileges). You are prompted to confirm that you want the message deleted. $ UCX REMOVE MAIL /ENTRY=828 _PLUTO$DKD0:[MARLOW]970207015114580_MARLOW.UCX_PLUTO;1? y 2. This next example removes all messages for your process's user name, or deletes everything in the SMTP queue if you have either SYSPRV or BYPASS privileges. The /NOCONFIRM qualifier prevents UCX from prompting you for confirmation. Before deletion, UCX copies this queued mail to the specified directory. $ UCX REMOVE MAIL /NOCONFIRM /COPY=[MARLOW.OLD_MAIL] 4 Releasing_Queued_Mail The following example shows how to requeue an SMTP mail message that is currently holding, using the UCX SEND MAIL command (similar to the DCL ENTRY/RELEASE command). You are prompted to confirm you want the mail message requeued. $ UCX SEND MAIL /ENTRY=828 _PLUTO$DKD0:[MARLOW]970207015114580_MARLOW.UCX_PLUTO;1? y 2 Network_Printing The Line Printer/Line Printer Daemon (LPR/LPD) of the DIGITAL TCP/IP Services for OpenVMS software supports the DCL PRINT, lpr, LPQ, and LPRM commands for remote printing. The LPR/LPD service allows you access to print queues on remote hosts and allows users on remote hosts to access print queues on your system. You can also use FTP to print remote files on your local host and local files on a remote host. 3 Remote_Printing Your system manager can configure your system with LPR/LPD network services that allow you to use the DCL PRINT command to send print jobs to a print queue on a remote internet host. The remote host can be a UNIX system or another OpenVMS system running LPR/LPD. You print a local file at a printer on a remote host by specifying the remote queue name defined on your local host (see your system manager for queue names). LPD copies the file to the appropriate remote printer's spool directory. A copy of the file to be printed remains in the spooling queue until the printer is ready to print it. When you issue the DCL PRINT command to send a print job to a remote print queue, you use the /QUEUE qualifier to specify the queue name plus any of the following qualifiers: /AFTER /BACKUP /BEFORE /BY_OWNER /CONFIRM /COPIES /CREATED /DELETE /EXCLUDE /EXPIRED /FORM /HEADER /HOLD /IDENTIFY /JOB_COUNT /MODIFIED /NAME /NOTE /OPERATOR /PARAMETERS /PASSALL /PRIORITY /QUEUE /SETUP /SINCE /USER /WIDTH Two of these qualifiers work differently with DIGITAL TCP /IP Services for OpenVMS software than they do in a OpenVMS environment without TCP/IP support. These two qualifiers are: o /FORM o /PARAMETERS NOTE DIGITAL TCP/IP Services for OpenVMS software does not support layup definition files for print requests to remote print queues. A layup definition file sets up the layup features: borders, sheet margins, alternating margins, pages per sheet, first page, page order, and page grid. 4 /FORM The DCL PRINT /FORM command customizes the look of the printed page. This qualifier associates a form other than the default with the print job. To see which forms are defined for your system, type: $ SHOW QUEUE queue /FORM To find out the currently mounted form or the default form, issue: $ SHOW QUEUE queue /FULL If the FORM associated with a remote LPD queue specifies a /WIDTH value that is not the standard 132, LPD sends a "W" card in the job's control file with the width specified in the form. 4 /PARAMETERS DIGITAL TCP/IP Services for OpenVMS software supports numerous options for the DCL PRINT /PARAMETERS=(option=value) command. For example, it supports the PAGE_SIZE option as follows: $ PRINT/PARAMETERS=(PAGE_SIZE=size) /QUEUE=queue_name filename When you type PRINT /PARAMETERS=(option=value), enclose the following in quotation marks: o Blanks o Non-alphanumeric characters, including spaces and slashes You can use the following /PARAMETERS options for both local printing (standard DCL PRINT) and remote printing (DCL PRINT with LPR/LPD network services). DATA_TYPE NUMBER_UP PAGE_LIMIT PAGE_ORIENTATION PAGE_SIZE SHEET_COUNT SHEET_SIZE SIDES For a full description of the options supported for DCL local as well as remote printing, type the following command. $ HELP PRINT_PARAMETER NOTE This help is available only if the DECprint Supervisor (DCPS) software is installed on your system. See your system manager for more information. You can use the following /PARAMETERS options that are supported only for use with remote printing. HOST MAIL NOFLAG PRINTERS 5 Host_and_Printers Use the HOST and PRINTER options together to send a print job to any specified remote host and printer that are not defined for an LPD remote print queue on your system. Although you are not printing to an LPD remote queue, you must specify a valid LPD remote queue name with the /QUEUE qualifier. This activates the remote print queue LPD service to respond to your print request. For example, the following command specifies that the file PINS.LIS be sent to printer CT_LN05R on remote host BALT. $ PRINT/PARAMETERS=(HOST=BALT, PRINTER=CT_LN05R) /QUEUE=DPR_ANSI PINS.LIS The HOST and PRINTER options allow you to use any available network printers, without your system manager having to set up additional LPD remote queues for each of these printers. Specify the remote host name either by its relative name (starting name, or label, of the absolute domain name) or by its fully qualified name (such as PACE.STATS.RINGS_CORP.COM). 5 MAIL The MAIL option causes the remote host to notify you through SMTP mail when the print job completes. The following command example specifies the MAIL option. $ PRINT/PARAMETERS=MAIL /QUEUE=DPR_ANSI PINS.LIS 5 NOFLAG The NOFLAG option suppresses printing of a banner (flag) page at an LPD queue. By default, the remote printing service provider (LPD) does not honor the /NOFLAG and /FLAG qualifiers of the DCL PRINT command. To enable support of these qualifiers, the system manager defines a systemwide logical name UCX$LPD_VMS_FLAGPAGES prior to starting the remote print queues. The following command example specifies the NOFLAG option. $ PRINT/PARAMETERS=NOFLAG /QUEUE=DPR_ANSI PINS.LIS 4 Examples The following examples show how to use the remote queue print capabilities of DIGITAL TCP/IP Services for OpenVMS. 1. This example sends local file PINS.LIS to the remote print queue defined locally as FAC3_ANSI and requests notification through SMTP when the job completes at the remote printer. $ PRINT /PARAMETERS=MAIL /QUEUE=FAC3_ANSI PINS.LIS 2. This example shows how to send a local file to the remote print queue defined locally as OUR_PS for printing at a remote printer. The command specifies that text be printed on both sides of each sheet. The file is ROUGH.TXT. $ PRINT /QUEUE=OUR_PS /PARAMETER=(SIDES=2) ROUGH.TXT 3. This command sends a print job to the remote queue defined locally as YOUR_PS. $ PRINT /QUEUE=YOUR_PS - _$ /PARAMETERS=(DATA_TYPE=POST,PAGE_ORIENTATION=LANDSCAPE,SIDE=2) - _$ LET.LIS 4. This example sends a print job to Internet host PACE.SATRN.COM to print on printer K1_PRINTER. Because LPD_OUTQ is a generic queue, OpenVMS sends the job to the first available execution queue. $ PRINT /QUEUE=LPD_OUTQ - _$ /PARAMETERS=(HOST=PACE.SATRN.COM,PRINTER=K1_PRINTER) - _$ USER$4:[GRANT.FINAN.SALES]ANNUAL.TXT 3 Remote_Queue_Status To display the status of jobs you send to a remote printer, use the LPQ command. The following information is displayed: o Your name o Current rank of job in the queue o Names of the files in job o Job identifier o Total size of job in bytes 4 Examples The following examples show how you can use the LPQ command. 1. This example displays all entries in the LPS40_QUE queue. $ LPQ LPS40_QUE 2. This example shows information about Job 4 in the print queue named OFFICE_QUE. $ LPQ OFFICE_QUE /ENTRY=4 3. This example shows information about Jobs 1, 2, and 3 in print queue PEACE_Q. $ LPQ PEACE_Q /ENTRY=(1,2,3) 4. This example shows information about user NELSON's jobs in the print queue FRONT_Q. $ LPQ FRONT_Q /USER=NELSON 3 Removing_Print_Jobs To remove your jobs from a remote print queue, use the LPRM command. Using the LPRM command, you can remove the following: o All of your active jobs o All jobs, if you have the required privileges o Selected jobs 4 Examples The following examples show how you can use the LPRM command. 1. This example deletes one job from print queue BASE_Q. $ LPRM BASE_Q /ENTRY=7 2. This example deletes jobs 555, 556, and 558 from queue BASE_Q. $ LPRM BASE_Q /ENTRY=(555,556,558) 3. In this example, the system manager, who has the required privileges, deletes all jobs from queue MAIN_QUE. $ LPRM /ALL MAIN_QUE 3 Printing_Remote_UNIX_Files_Locally Your system manager can set up a local print queue to handle print jobs for files sent from a remote UNIX host. To print UNIX files on an OpenVMS printer, the UNIX user enters an lpr command. (See the appropriate UNIX documentation.) Local queues set up to receive UNIX print jobs support layup definition files. These are files supported only by DIGITAL and used to set the following layup features: borders, sheet margins, alternating sheet margins, pages per sheet, first page, page order, and page grid. 4 Examples The following example sends UNIX file /usr/stanton/recent.cnts to OpenVMS print queue REMOTE_QUEUE4 and specifies the formatting defined in the layup file called layup3. The REMOTE_QUEUE4 print queue is set up as a remote queue in the printcap file by the system manager. % lpr -Llayup3 -Premote_queue4 /usr/stanton/recent.cnts 2 R_Commands The Remote (R) commands provided by the DIGITAL TCP/IP Services for OpenVMS software allow you to work in accounts on remote internet systems also supporting the Remote (R) protocols. You can also issue commands, shell scripts, and command procedures to these remote host systems without logging in to the hosts. These R commands include RCP (Remote Copy), RLOGIN (Remote Login), RSH (Remote Shell), and REXEC (Remote Execute, invoked by RSH). You enter these commands at your system command line prompt. 3 Accounts_and_Passwords To use a remote command on your OpenVMS system, remote hosts need to know the user name that you wish to use on the host. You can provide the user name in either of two ways: o Automatically: You do not need to take any action if your user name is the same on the remote host as it is on the local host. The remote commands automatically supply your local user name as the requested user name on the remote system. o Using the /USER_NAME qualifier: Specify the user name with the /USER_NAME qualifier if your user name is: - Different on the remote host - In mixed case (only for remote hosts supporting case- sensitive user names) - The same on the remote host but you wish to access the remote host using another user name By default, the R commands send all user names in lowercase letters. If you access a host that supports case-sensitive user names, and the user name you specify has uppercase letters, you may use the /NOLOWERCASE qualifier to maintain these letters as uppercase, or you can specify the /USER_NAME qualifier with the user name in quotes. The remote host must also know your password or know you as a trusted user on your local system: o Accessing remote hosts by providing your password: - Certain systems have case-sensitive passwords. To send your lowercase or mixed-case password to these hosts, enclose it in quotation marks ( " " ). - On systems that are not case-sensitive, you do not need to enclose your password in quotation marks ( " " ). - You can specify the password on the command line: $ RSH WOODS /PASSWORD="Downy" LS Or, you can specify the password at the REXEC prompt: $ RSH WOODS /PASSWORD LS REXEC password: (not echoed) o Accessing remote hosts as a trusted user: Most systems use certain authentication files or proxy accounts that allow trusted users on trusted hosts to access the system by specifying only the user name they wish to use. To access a host without specifying the corresponding password, your originating host and user name must have an entry in these authentication files. The authentication file entries contain your originating user name. The R commands convert your originating user name to lowercase unless you use the /NOLOWERCASE qualifier. You may have to contact the system manager from the remote system to determine if the system is case-sensitive and, if so, what case is used in the authentication files. NOTES To use the REXEC feature, you must always use the /PASSWORD qualifier. The RLOGIN command does not have the /PASSWORD qualifier. If you are a trusted user, you are automatically logged in to the remote system. If you are not a trusted user, REXEC prompts you to enter a user name and password on the remote system. 4 Quotation_Marks Use quotation marks (" ") for UNIX host path names that include slashes (/), such as user/simms/offers, and for host/file specifications that include the username@ syntax. If the remote host uses case-sensitive user names and passwords, use quotation marks in the following situations: o User names and passwords are mixed case. o Passwords are lowercase. o User names are uppercase, unless you use the /NOLOWERCASE qualifier. 4 Examples The following examples show how to provide account and password information for the R commands. 1. OpenVMS user STALLINGS accesses the file accnts on UNIX host ufemism as user stallings and copies the file to the current directory on the OpenVMS system. Because /LOWERCASE is the default, the /LOWERCASE and /USER_NAME=stallings qualifiers are not needed. In this example, the user is a trusted user. $ RCP UFEMISM:ACCNTS [] <Return> $ 2. From OpenVMS, STALLINGS accesses the superuser account cris on ufemism. Because /LOWERCASE is the default, the /LOWERCASE and /USER_NAME=stallings qualifiers are not needed. In this example, the user is a trusted user. $ RLOGIN /USER_NAME=CRIS UFEMISM <Return> Welcome to UNIX system ufemism. . . . ufemism% 3. User FINCH has the same uppercase name for both an OpenVMS account and a UNIX account. For RSH to send the uppercase OpenVMS account name to remote host ufemism in uppercase, FINCH uses the /NOLOWERCASE qualifier. In this example, the user is a trusted user. $ RSH /NOLOWERCASE UFEMISM CAT -N GRANTS 4. User BACH has the the account bach on the UNIX host classics. To invoke the REXEC feature, BACH specifies the password on host classics. Note that the password MagNificat is enclosed in quotes to prevent RSH from sending it all uppercase. $ RSH /PASSWORD="MagNificat" CLASSICS LS <Return> 3 Qualifiers You can specify R command qualifiers in either of two ways: o Type the qualifiers on the command line. $ RCP /LOG TRANQUIL:VULTURES [] $ RSH /EIGHTBIT /ESCAPE_CHAR="+" /TRUNCATE HERON CAT -N STREAMS o Add the same information to your LOGIN.COM file, for example: $ ! To customize my R commands: $ ! $ RCP :== RCP /LOG $ RLOGIN :== RLOGIN /EIGHTBIT /ESCAPE_CHAR="+" /TRUNCATE_USER_NAME $ RSH :== RSH /EIGHTBIT /ESCAPE_CHAR="+" /TRUNCATE_USER_NAME $ ! 3 RCP_(Remote_Copy) The RCP command copies a file between your local host and a remote internet host. You can also use RCP to copy a file between two remote internet hosts. You specify the source and destination file names, each in the format appropriate for the source or destination system. For copying files from one remote host to another: o If you do not have proxy login accounts (or authentication file entries) for both the source and remote hosts, you must have the same user name and password on both source and destination hosts. Use the /PASSWORD qualifier and, if necessary, the /USER_NAME qualifier, to specify the authentication information for the remote hosts. o If you have a proxy login account (or authentication file entry) on one of the remote hosts only, use the /PASSWORD qualifier and, if necessary, the /USER_NAME qualifier to specify the authentication information for the other host. By using the /RECURSIVE qualifier with the RCP command, you can recursively copy every file and subdirectory in a directory. Beginning with OpenVMS Version 6.2, you can also use the COPY /RCP command to copy files across the network using TCP/IP. For more information on this command, type HELP COPY/RCP at the DCL prompt. Note that you can also use FTP to transfer files. 4 Example_RCP_Commands The following examples show how to use RCP commands to copy files from one host to another host. 1. User BEST has the account best on the UNIX host haven. User BEST's password for that account is IMusici, which must be enclosed in quotation marks because it is mixed case. The following command copies the file /symph/nine on haven to the local directory on the OpenVMS system (the UNIX file specification must be enclosed in quotation marks, also): $ RCP /PASSWORD="IMusici" "haven:/symph/nine" []<Return> 2. User BEST has a proxy account on the remote UNIX host musicx. The following command copies the file /symph/pastoral from host musicx to the directory [SYMPH6] on the device DKA300: on BEST's local OpenVMS system: $ RCP "musicx:/symph/pastoral" ":DKA300:[SYMPH6]" <Return> 3. With this command, user BEST copies each subtree rooted at the /symph directory to the directory [SYMPHS] on the device DKA300: on BEST's local OpenVMS system. $ RCP/RECURSIVE "haven:/symph" ":DKA300:[SYMPHS]" <Return> 4. With the following command, user BEST copies all files from the directory /symphonies on remote host musicx to the directory /symph on remote host haven: $ RCP /PASSWORD="IMusici" "musicx:/symphonies/*" "haven:/symph/*" <Return> 5. In the following example, user BEST uses the DCL COPY/RCP command to transfer the complete subdirectory tree /symph from remote UNIX host haven to remote OpenVMS host FRAM, which both require specification of a password. (With the RCP command, when transferring files between two remote hosts, you need a proxy account or an entry in the authentication file for at least one of the two remote hosts.) User BEST has an account under the same name on both hosts. $ COPY/RCP haven"BEST IMusici"::"/symph/*" <Return> To: FRAM"VAUGHN MYLES"::[classic.compositions]*" 3 RLOGIN_(Remote_Login) The RLOGIN command connects your terminal to the remote host you specify and requests a login. If the remote host has an entry in its authentication files for your host and user name, it may bypass its login and password prompts. Note that you can also use TELNET to log into remote internet hosts. 4 Logging_Out End your remote login session in either of two ways: o Log out from the remote host. o On a new line, enter the escape character and a period. The default escape character is a tilde ( ~ ). To set another escape character, use the /ESCAPE_CHARACTER qualifier on the RLOGIN command line. 4 Example_RLOGIN_Sessions The following examples show how to use the RLOGIN command. 1. The following command logs in to node CONDO: $ RLOGIN CONDO <Return> OpenVMS Version 6.1 -- Unauthorized access is prohibited. Username: KING <Return> Password: (not echoed) <Return> $ RUN ... $ ~. (not echoed) %RSH-S-LCLCLOSED, Local connection closed $ 2. The following command logs in to host petrel and sets the character used to close the RLOGIN session: $ RLOGIN /ESCAPE_CHARACTER="+" PETREL <Return> . . . Last login: Mon Mar 14 18:34:27 from phoebe.edu UNIX System petrel: Fri Mar 19 11:02:20 EST 1997 Mon Jun 28 18:44:42 EST 1997 % ls ... <Return> % +. (not echoed) %RSH-S-LCLCLOSED, Local connection closed $ 3 RSH_(Remote_Shell) The RSH command connects your terminal to a remote host and requests it to execute the command, script, or command procedure that you specify. If the command generates output, you see it as if it were produced locally. If you omit a remote command when you type an RSH command line, RSH initiates an RLOGIN session. However, if the command line includes /PASSWORD, the remote login attempt fails. Using the /PASSWORD qualifier invokes REXEC. Syntax rules require that you type your RSH command line so that the remote command is the last word (or phrase). 4 Quotation_Marks If the remote command is one or more lowercase words, you do not need to enclose them in double quotation marks on the RSH command line. However, double quotation marks ( " " ) are required for: o UNIX commands that are mixed-case characters. o UNIX commands that are uppercase characters. In addition, RSH handles one double quotation mark ( " ) and two consecutive double quotation marks ( "" ) as follows: o If you input one double quotation mark in a command line, RSH strips it. o If you type two consecutive double quotation marks on the command line, RSH strips the first quotation mark and leaves the second. o If you surround text with a set of double quotation marks on the RSH command line, RSH disables the default conversion of characters to lowercase, and strips the quotation marks. 4 Interrupting_Commands To stop a remote execution, enter either Ctrl/C or Ctrl/Y. 4 Example_RSH_Commands The following examples show how to use the RSH command. 1. In this example, the remote system manager previously created an entry in the authentication files for remote user STAN on host oster giving STAN permission to access user rolly. From the local OpenVMS host, user STAN views rolly's directory, which resides on UNIX system oster. No quotes are required around the user name and host name because RSH by default sends them in lowercase. $ RSH /USER_NAME=ROLLY OSTER LS 2. On the following RSH command line, the uppercase UNIX qualifier -R is typed within quotation marks to preserve the uppercase R. This example assumes that the user's originating host and user name are in the authentication files on the remote host debts. $ RSH DEBTS LS "-R" 3. The following commands show how RSH sends quotation marks to a remote UNIX host and how quotation marks affect case. All examples assume that the user's originating host and user name are in the authentication files on the remote host. $ RSH DEBTS ECHO TEST MESSAGE test message $ RSH DEBTS ECHO "\""test\"" message" "test" message $ RSH DEBTS ECHO TEST MESSAGE test message $ RSH DEBTS ECHO "TEST" MESSAGE TEST message $ RSH DEBTS "echo '""test"" message'" "test" message 4. Because no remote command is specified on the RSH command line, DIGITAL TCP/IP Services for OpenVMS executes RLOGIN. $ RSH TANNER <Return> Password: (not echoed)<Return> Last login: Wed Aug 24 07:14:28 from henson.pension.daily.com Digital UNIX Mon Aug 29 17:27:15 EDT 1997 Daily Corporation today> 5. In this example, the OpenVMS system manager of WR2 previously created an entry in the authentication files for remote user SIMMS on host WR1. From OpenVMS host WR1, user SIMMS types the DIRECTORY command to execute at WR2. $ RSH WR2 DIRECTORY 6. In this example, the OpenVMS system manager of WR2 previously created an entry in the authentication files for remote user SIMMS on host WR1 allowing SIMMS access to the user name ROGERS. User SIMMS issues the DIRECTORY command from WR1 to execute at WR2 in user account ROGERS. $ RSH WR2 /USER=ROGERS DIRECTORY 3 REXEC_Feature Use the REXEC feature to send a command to execute on a remote host that does not have, or might not have, the authentication information that RSH requires. The remote system's authentication files are not used. Along with the remote command, REXEC sends the password you specify on the command line to the remote host. This password is used for security checking. The Remote Shell program invokes REXEC. To use REXEC, issue RSH /PASSWORD. 4 Example_REXEC_Use The following example shows how to provide password information for the RSH command, thereby invoking the REXEC feature on the remote host. From host GRANT, user STANTON types the file tops.holdings that resides on UNIX host oster. Because STANTON is not listed in oster's authentication files, user STANTON must use the REXEC feature and supply the /USER_NAME and /PASSWORD qualifiers. Quotes are required around the password because it contains uppercase letters. $ RSH OSTER /USER_NAME=STANTON /PASSWORD="KeepingSaneJoy" - _$ CAT TOPS.HOLDINGS 2 Network_Terminals With the TELNET software in DIGITAL TCP/IP Services for OpenVMS (UCX), you can log in to a remote internet system. This is called establishing a TELNET session. Your terminal appears to be attached directly to the remote system. Using the TN3270 command, you can run a TELNET session with a host that uses IBM 3270 model terminals. Note that you can also use RLOGIN to log into remote internet hosts. 3 Commands Use the following rules when you type a TELNET command line. o Command formats With the TELNET command and most of the commands at the TELNET prompt, you can use either DCL-style or UNIX-style syntax. For example, the following two commands produce the same results: $ TELNET TELNET> SHOW PARAMETERS $ TELNET TELNET> DISPLAY o Quotation marks No quotation marks are required for typing: o The TELNET command line, for example: $ TELNET CENTRAL o The TN3270 command line, for example: $ TN3270 CENTRAL o Commands at the TELNET prompt, for example: TELNET> CONNECT CENTRAL The following example connects to UNIX host migain and sets a terminal type with the /TERMINAL_TYPE qualifier. No quotation marks are needed to pass a terminal type to migain in lowercase, as demonstrated with the remote host's printenv command. $ TELNET MIGAIN /TERMINAL_TYPE=vt300 %TELNET-I-Trying, Trying ...11.90.208.56 %TELNET-I-SESSION, Session 01, host migain, port 23 -TELNET-I-Escape, Escape character is '^]' Hello from UNIX host migain 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# 3 Starting You can start a TELNET or TN3270 session with a remote host (also called establishing a connection and opening a connection) in one of the following ways: o At the DCL prompt, issue either the TELNET or TN3270 command and specify a remote host. o At the DCL prompt, issue the TELNET or TN3270 command with no parameters. At the TELNET or TN3270 prompt that appears, issue the CONNECT or open command, specifying a remote host. o Invoke and use TELNET or TN3270 from a command procedure. The following example shows three ways to establish a connection interactively: $ TELNET CENTRAL /TERMINAL_TYPE=IBM-3278-2 $ TELNET TELNET> CONNECT CENTRAL 23 VT200 $ TN3270 CENTRAL /TERMINAL_TYPE=IBM-3278-3 You can invoke TELNET or TN3270 and, without connecting to a remote host first, enter certain commands that customize the sessions and display parameters or status. 3 Exiting You can end a TELNET or TN3270 session (close the connection) in one of the following ways: o At the remote host's system prompt, log out. o At the remote host's system prompt, return to the TELNET or TN3270 prompt and disconnect the session, as follows: 1. At the remote host's system prompt, press the TELNET/TN3270 escape character (Ctrl/] is the default). 2. At the TELNET or TN3270 prompt, issue either DISCONNECT or close. The following example shows two ways to close connections: % logout %TELNET-S-REMCLOSED, Remote connection closed TELNET> EXIT $ % <Ctrl/]> TELNET> DISCONNECT %TELNET-S-REMCLOSED, Remote connection closed TELNET> EXIT $ 3 Logging_Sessions To keep a log of your TELNET session, use the /LOG_FILE qualifier. (You cannot use this qualifier with a TN3270 session.) The following example establishes a TELNET connection to node central, sets the terminal type to VT200, and logs all session output to the file CENT.LOG in your current directory. $ TELNET/LOG_FILE=CENT.LOG/TERMINAL_TYPE=VT200 CENTRAL 3 Command_Procedures With DCL command files, you can start TELNET and TN3270 sessions (see Starting TELNET/TN3270) and customize the TELNET/TN3270 environment (see Initialization Command Files). 4 Starting_TELNET/TN3270 You can create a command procedure containing the DCL DEFINE and TELNET (or TN3270) commands. The following example shows an example of a TELNET command procedure. $! My TELNET startup command file, START_TELNET.COM. $! $! This command procedure establishes a TELNET session $! with UNIX host central. $! $ DEFINE /USER_MODE SYS$INPUT TT: $ TELNET CENTRAL 4 Initialization_Command_Files Initialization command files can customize your TELNET/TN3270 sessions with SET, ENABLE, and DISABLE commands. These command files: o Are optional. They eliminate the need to issue individual TELNET commands. o Have the following requirements: - Location: Your login directory - Name: TELNETINIT.INI - Format: one command per line o Run automatically when you invoke TELNET or TN3270. The following example shows a TELNET initialization command procedure. ! This file, TELNETINIT.INI, sets my TELNET parameters ! the way I like them. ! DISABLE AUTOFLUSH ENABLE BINARY ENABLE DEBUG SET DEVICE /TERMINAL=VT300 SET ESCAPE "^p" 3 Toggling_Between_Remote_and_Local During a session with a remote host, you can toggle back and forth between the local TELNET or TN3270 process and the connected host. For example, at the TELNET prompt, you might want to display status, modify a TELNET parameter, or spawn a DCL subprocess. o To return to the local TELNET or TN3270 prompt (TELNET command mode), type the TELNET escape sequence (the default is Ctrl/]) at the remote host's prompt (TELNET input mode). o To resume your session with the remote host, type one of the following at the TELNET (or TN3270) prompt. TELNET> <Return> 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, type the following at the TELNET (or TN3270) prompt: TELNET> SET ESCAPE escape_character 4 Examples The following example toggles between remote UNIX host biway and the local OpenVMS system. biway> <Ctrl/]> TELNET> SHOW STATUS Session 1 Active Host BIWAY Operating Mode: Character-at-a-time Escape character: '^]' Options: . . . TELNET> <Return> biway> In the next example, user BENTLEY, working at OpenVMS node EAGLE, uses TELNET to do the following: 1. Establish a connection to UNIX host fern. 2. Return to the local TELNET prompt. 3. Display status. 4. Establish a connection to host gannet. 5. Return to the TELNET prompt. 6. Display status. 7. Connect to sands. But, sands closes the connection because BENTLEY mistypes the password three times. 8. Try to resume the session with gannet. However, RESUME without specifying a session number fails: - With multiple sessions, RESUME's default is the "active" session, the one with the most recently opened connection. - The most recent host to which BENTLEY connected is sands. However, due to BENTLEY's mistyping of the password during login, sands closed the TELNET connection. Thus, TELNET displays "No current session." - Because no connection is "active" (or "current"), BENTLEY must specify a session number on the RESUME command line. $ TELNET FERN . . . fern> <Ctrl/]> TELNET> SHOW STATUS Session 1 Active Host FERN . . . TELNET> CONNECT GANNET . . . gannet> <Ctrl/]> TELNET> SHOW STATUS Session 2 Active Host GANNET Operating Mode: Character-at-a-time Escape character: '^]' . . . Session 1 Waiting Host FERN TELNET> CONNECT SANDS %TELNET-I-Trying, Trying...11.18.222.95 %TELNET-I-SESSION, Session 03, host sands, port 23 -TELNET-I-Escape, Escape character is '^]'. . . . Sun Microsystems, Inc. UNIX System sands - Authorized Access Only Username: BENTLEY Password: User authorization failure Username: BENTLEY Password: User authorization failure Username: BENTLEY Password: User authorization failure Remote connection closed TELNET> RESUME No current session TELNET> SHOW STATUS Session 1 Waiting Host FERN Session 2 Waiting Host GANNET . . . TELNET> RESUME 2 gannet> <Ctrl/]> TELNET> SHOW STATUS Session 2 Active Host GANNET Operating Mode: Character-at-a-time Escape character: '^]' . . . Session 1 Waiting Host FERN TELNET> 3 Suspending_TELNET While using TELNET, you can use the SPAWN command to suspend your current session and create a subprocess at the local DCL prompt. At the DCL prompt, you can then enter any number of DCL commands. To return to your suspended TELNET session (exiting the DCL subprocess), enter the LOGOUT command. In the following example, the user suspends the TELNET session to list the files in the working directory on the local host and deletes one of the files in that directory. TELNET> SPAWN $ DIR . . . $ DEL TR3.TXT:* 3 Multiple_Sessions TELNET supports: o Multiple simultaneous connections o Up to 10 simultaneous sessions o Only one session at a time if it uses TN3270 The TELNET SHOW STATUS command helps you keep track of multiple sessions. The SHOW STATUS display uses the terms shown in the following table: Term Meaning Active host Host from which you typed the escape sequence to return to the TELNET prompt. Current If you log out of the active host at its system session prompt, or issue the TELNET DISCONNECT command, no current session exists. To resume a connection, even if only one exists, issue: TELNET> RESUME n Waiting hosts Other hosts with whom you have open sessions, numbered in the order that you connected to them. To resume a connection with a waiting host, even if only one exists, issue: TELNET> RESUME n To open another TELNET connection: 1. At the system prompt of the remote host, press the TELNET escape sequence (default is Ctrl/]). 2. TELNET returns to the TELNET prompt. 3. Start another session by issuing the CONNECT command. The following example starts multiple sessions with UNIX hosts finder and keeper. $ TELNET FINDER /TERMINAL_TYPE=IBM-3278-2 . . . finder> . . . finder> <Ctrl/]> TELNET> CONNECT KEEPER . . . keeper> . . . keeper> <Ctrl/]> TELNET> 4 Toggling_Sessions To toggle from one open TELNET connection to another: 1. Type the TELNET escape sequence. 2. If necessary, issue SHOW STATUS to check the number of your session with the other host. 3. Issue the TELNET RESUME n command, where n is the number of the session to which you want to return. 4 Session_Information To display a list of your active sessions, use the SHOW SESSION command: TELNET> SHOW SESSION <Return> Session 01, host finder, port 23 Session 02, host keeper, port 23 (default active session) If there are no active connections, the SHOW SESSION command displays the following message: %TELNET-E-NOSESSION, No active session 3 Customizing_TELNET/TN3270 To customize the TELNET/TN3270 processing environment, issue ENABLE, DISABLE, and SET commands. You can modify how TELNET and TN3270: o Send and receives transmissions o Display processing on your terminal o Interpret certain control characters You can redefine the following control characters, such as when your terminal or the remote host does not recognize the corresponding default control character. o Echo o Erase o Escape o Flush output o Interrupt o Kill o Quit Use the SET command to redefine these characters. For example, the following command defines the interrupt character to be the letter a or A. TELNET> SET INTERRUPT "^a" TN3270 allows you to redefine your keyboard. You can redefine most IBM 3270 model functions and all emulated functions and characters. You can create a key definition file with DEFINE/KEY statements to redefine the keyboard. Or, you can redefine a key interactively, using the DEF KEY function (Ctrl/K on VT100- and VT200-series terminals). You can determine the mode TELNET uses to transmit data. The appropriate TELNET mode for a session depends on: o The remote host to which you are connecting o The applications you use The following table shows the modes that control TELNET communications. Mode Function Local Characters The local host interprets control characters, Mode translating them into TELNET protocol sequences (ENABLE LOCAL_CHARS). Use this mode when the local and remote hosts implement different control characters. By default, characters are interpreted by the remote host (DISABLE LOCAL_ CHARS). Binary Mode The local host sends transmissions in binary mode (ENABLE BINARY). Use this mode when the remote host expects each line of data to end with a carriage return/line feed combination. By default, the local host sends transmissions with the end-of-line character (EOL) mapped to the carriage return/line feed combination (DISABLE BINARY). Debug Mode TELNET displays data flow in both hexadecimal and readable text (ENABLE DEBUG). By default, TELNET displays data in readable text only (DISABLE DEBUG). Character TELNET transmits data one character at a time Transmission (SET MODE CHAR) rather than line-by-line. Use Mode this mode when you run a text editor (on the remote host) that does character processing. Character transmission mode is the default. Line TELNET transmits data one line at a time (SET Transmission MODE LINE). Most clients send a character at a Mode time. The remote host server must support line transmission mode. This allows you to do signal trapping as well as local character editing and tab expansion. 3 SEND_Commands While in input mode (an active session with a remote host), you can enter SEND commands that affect the remote host's processing of commands you have entered. You use these commands when the remote host does not recognize the default key or key sequence used for the same operation. You can use the SEND AYT and SEND NOP commands to determine if your session with the remote host is still open. The following table lists the function you can perform at the remote host with each SEND command. Table 1-1 Sending Commands to the Remote Host Function Command When to Use Abort output of SEND AO You want to terminate output the last remote but not the execution of the command you process. entered, without After already aborting output, discontinuing you want to resume output. The execution of the remote host does not recognize process. the Ctrl/O as the flush output character. Determine if your SEND AYT Test the connection to the connection with remote host application and the remote host is verify that the remote host still established, application is responding. You the remote host are notified on success. replying with connection status information. Terminate execution SEND BRK The remote host does not of the last command recognize the Ctrl/C sequence you entered at the as an interrupt character. remote host. Delete the last SEND EC The remote host does not character you typed recognize your Delete key. at the remote host. Delete the last SEND EL The remote host does not line of text you recognize your Delete key or entered at the command-line recall. remote host. Signal the remote SEND GA The application requires GA host that your commands in either one or both local system is directions. ready. Interrupt execution SEND IP Your terminal or the remote of the last command host does not recognize the you entered at the default interrupt character remote host. (Ctrl/C). Determine whether SEND NOP Check the communication path your local host can to the remote host; you are send data to the notified on error. connected remote host and whether the remote host can receive that data Interrupt the SEND SYNCH You want to clear immediately current process the communications path between you are executing your system and the remote at the remote host, host, with the remote host and in urgent mode ignoring any incoming data not (out-of-band), yet processed. get a quicker response time to the interrupt. 3 IBM_Terminal_Emulation You can run a TELNET session with a host that uses IBM 3270 model terminals by using the TN3270 command. The TN3270 command: o Provides IBM 3270 Information Display System (IDS) terminal emulation. o Assigns IBM 3270 functions to your DIGITAL keyboard. o Assigns IDS functions to specific keys. During a TN3270 session, you can: - Redefine keys interactively (DEF KEY Function ). - Redefine keys permanently (Key Definition File). - Record your sessions (Recording Sessions). - Troubleshoot problems (Problem Solving). NOTE When you run TN3270, you can only have one session. You cannot have other sessions running simultaneously, as you can when running normal TELNET sessions. 4 Supported_IBM_Terminal_Models The following table lists the IBM 3270 model terminals that TELNET can emulate. Model Screen Size (Rows x Columns) IBM 3278 Model 2 24 x 80 IBM 3278 Model 3 32 x 80 IBM 3278 Model 4 43 x 80 IBM 3278 Model 5 27 x 132 4 Setting_Up_Your_PC_or_Terminal When you use TELNET and specify IBM 3270 model terminal emulation (TN3270), the image displayed on your screen depends on: o The type of DIGITAL terminal you use, or that your PC is emulating. o The features you set on it. 5 VT200-Series_Terminal_Setup_ Follow these steps: 1. At the Set-up Directory menu, select the keyboard type that corresponds to the keyboard layout you are using (for example, North American). 2. At the Display Set-up menu, select the following: o Interpret controls o Light text, dark screen o Cursor (visible) 3. At the General Set-up menu, select the following: o VT200 or VT100 mode (if VT100 mode, set VT100 ID) o 7-bit or 8-bit controls o Multinational/national o Normal cursor keys o No new line 4. At the Communications Set-up menu, select the following: o XOFF at 64 or XOFF at 128 o 8-bit communication line o 8-bit (any) parity o No local echo 5. At the Keyboard Set-up menu, select warning bell ON. At the DCL prompt, issue: $ SET TERMINAL /INQUIRE The software determines the terminal's characteristics and sets the appropriate parameters. If you select National Character mode, issue: $ SET TERMINAL /NOEIGHTBIT 5 VT100-Series_Terminal_Setup_ Follow these steps: 1. Set your terminal to ANSI mode (see the user's guide for your terminal). 2. Enter the following command at the DCL prompt: $ SET TERMINAL/INQUIRE This command causes the terminal to be questioned about its characteristics. The appropriate parameters for the terminal are set up according to its response. TN3270 requires DIGITAL terminals or DECterm windows that support at least 24 lines and 80 columns. 4 Starting_and_Exiting Start a TN3270 session by using the TN3270 command. You can also use the TELNET/TERMINAL_TYPE=IBM-3278-n command. The default terminal type is IBM-3278-2. The following examples show several ways to start a TN3270 session, using the TN3270 command and connecting to host CENTRAL. o Using the default terminal type: $ TN3270 CENTRAL o Using a terminal type other than the default: $ TN3270/TERMINAL_TYPE=IBM-3278-4 CENTRAL You can invoke TN3270 and, without connecting to a remote host first, enter certain commands that customize the sessions and display parameters or status. You can also use a command file to invoke TN3270 and the customization. The TN3270 command includes several qualifiers that allow you to specify customized or special files for the following: o Character set translation tables file (/CHARACTER_SET=file) that translates between EBCDIC and the DIGITAL Multinational Character Set. The default file, if set up by your system manager, is SYS$LIBRARY:UCXTEDEF.TBL. If this file does not exist, and you do not specify a file, TN3270 uses its own translation table. o Keyboard definition file (/KEY_DEFINITIONS=file) that you create as an alternative to the default keyboard layout. o National Replacement Character Set (NRCS) file (/NATIONAL_ CHARACTERS=n) for which your DIGITAL terminal is configured. The default for 8-bit terminals is MULTINATIONAL. The default for 7-bit terminals is US_ASCII. You can end a TN3270 session (close the connection) in one of the following ways: o At the remote host's system prompt, log out. o At the remote host's system prompt, return to the TN3270 prompt and disconnect the session, as follows: 1. At the remote host's system prompt, press the TN3270 escape character (Ctrl/] is the default). 2. At the TN3270 prompt, issue either DISCONNECT or close. 4 Getting_Status To monitor your TN3270 session, use the status line indicator at the bottom of your screen. A reverse-video strip displays status and information messages. To see status messages, issue the following: TELNET> ENABLE STATUS 4 Clearing_Error_Messages TN3270 displays error messages in a bordered display at the bottom of your screen. This display overwrites the status display and remains visible until you clear it. To clear, invoke one of the following functions: o REFR o HELP o SET FIL o DEF KEY 4 Recording_Sessions During a TN3270 session, you can record your screen's contents. The PRINT function directs your screen's contents to either a file or a spooled printer. To record your screen's contents, follow these steps: 1. Invoke the PRINT keyboard function, as explained in the topic Keyboard_Functions. The screen display is recorded in a file in a compressed state. Null lines (lines with only nulls and attribute characters) do not appear. 2. Invoke the ENTER function or any function that transmits the screen contents to the remote host's application, as explained in the topic Keyboard_Functions. This creates the default output file, UCXTPRINT.LIS. TELNET does the following: o Each time you start a TELNET session that runs TN3270, TELNET opens a new UCXTPRINT.LIS file. o Each time you use PRINT during a session, TELNET appends new output from the screen to the end of UCXTPRINT.LIS. o Each time you use PRINT, if you direct the output to a printer, TELNET creates a separate entry in the print queue. o If the printer is spooled, TELNET immediately prints the output. You can specify a different file name. To change the name, use one of the following two methods: o When you start a TN3270 session, use the /PRINTER qualifier. Issue: $ TN3270 [ host ] /PRINTER=file o During a TN3270 session, follow these steps: 1. Use the SET FIL keyboard function, as explained in the topic Keyboard_Functions. 2. At the prompt for a new file name, type a name. If you specify the same name that is already in use, subsequent PRINT operations direct output to a new version of the same file. 3. Use the NEW LINE keyboard function, as explained in the topic Keyboard_Functions. 4 Online_Help Online help during a TN3270 session displays: o A picture of the keypad o A list of TN3270 keyboard functions o The key combinations that invoke the TN3270 keyboard functions The Help screen shows the TN3270 functions as they correspond to the keys on your physical keyboard: o Top-row keys o Editing keypad o Application keypad o Up to 32 control or extended character definitions o All your definitions and changes, including those you make interactively To see the Help screen, use the HELP function which is key F15. 4 Locked_Keyboards If your keyboard locks, the terminal bell rings, and the status line displays: Inhib To unlock the keyboard, press the following key to invoke the RESET function (KP0 refers to the 0 key in the application keypad on the righthand side of the keyboard): <KP0> Do not use the following functions when the cursor is in a protected field (a field that does not accept user input): o DELETE o DUP o ER EOF o FM o Any graphic character 4 Keyboard_Functions The following options describe the keyboard functions. Preceding each function description are the key sequences for VT100 and VT200 terminals and the function name to use in a DEFINE/KEY command. In many of the key sequences, TN3270 allows use of the extended function (EXT) feature. Used in conjunction with another key, EXT allows access to an extended function for that key. The extended function feature is described below in more detail. 5 ATTACH VT100: EXT + E VT200: EXT + Find DEFINE_KEY Function: ATTACH Changes control from one subprocess to another subprocess or to the parent process. When you invoke the ATTACH function, TN3270 uses the name of the last process to which you attached as the default process name. If you wish to attach to a different process, press Ctrl/U to erase the default process name. You can then enter the process name of your choice at the prompt. The process name can be a quoted string. Use the quotation marks to preserve spaces, tabs, or lowercase letters in strings. 5 ATTN VT100: EXT + A VT200: F19 DEFINE_KEY Function: ATTENTION Provides a way to "get the attention of" the remote application program that you are running by sending a SIGNAL RU command to the remote host. See the user's guide of the particular application program to learn what response the program gives when you use this key. 5 Back_Tab VT100: BACKSPACE VT200: F12 DEFINE_KEY Function: BACK_TAB Moves the cursor, depending on the type of screen. On a formatted screen, the cursor moves one of these ways, depending on the location when you press this key: o If the cursor is in a field, but not at the first position of the field, it moves to the beginning of the unprotected field that it is in. o If the cursor is in the first position of a field, it moves to the beginning of the preceding unprotected field. If the cursor is in the first position of the first unprotected field, the cursor moves to the first position of the last unprotected field on the screen. On an unformatted screen, the cursor returns to the first position on the screen. 5 Cent_Sign VT100: EXT + C VT200: EXT + C DEFINE_KEY Function: (None) Enters a cent sign. If your terminal does not have this character, your screen displays a hyphen ( - ). 5 CLEAR VT100: EXT + Enter VT200: EXT + F20 DEFINE_KEY Function: CLEAR Clears the screen and moves the cursor to the first position on the screen. When you invoke the CLEAR function, the software notifies the application program that this function has been used. 5 DEF_KEY VT100: Ctrl/K VT200: Ctrl/K DEFINE_KEY Function: DEFINE_KEY Lets you interactively define or redefine a key. You get a prompt for the name of the key to define and for a function you wish to assign to that key. 5 DELETE VT100: Delete VT200: <X] DEFINE_KEY Function: DELETE Deletes the character at the cursor. The cursor remains where it is, and the other characters to the right of the cursor in the same field move one position to the left. The end of the field fills with blanks. Note that this is not the action normally associated with the Delete key on DIGITAL terminals. 5 DSP_ATT VT100: Ctrl/V VT200: EXT + F17 DEFINE_KEY Function: DISPLAY_ATTRIBUTES Enables and disables the visible attribute mode. This mode of operation forces display of the attribute characters (that is, the characters at the start of a field that indicate the display and data type of that field). In IBM 3270 model terminal emulation (TN3270), you can use the DSP ATT function to debug application programs. 5 DUP VT100: EXT + * VT200: EXT + F12 DEFINE_KEY Function: DUP Lets you enter a value in the same field in several forms without needing to repeat the entry for each form. After entering the data in the field on the first form, use the DUP function when at the same field on succeeding forms. The application program makes the necessary translation, filling in these fields with the same value. For details about the use of this key, refer to the user's guide of the particular application program. Displays an asterisk (*). 5 DV_CNCL VT100: EXT + U VT200: EXT + Remove DEFINE_KEY Function: DVCNCL Cancels the RECORD function. Use the DV CNCL function if you begin using the RECORD function and then decide you want to stop. If you want to delete a sequence that has already been recorded on a PF key, use the RECORD function, press the PF key, and then use the DV CNCL function. 5 ENTER VT100: Line Feed + Enter VT200: Do + Enter DEFINE_KEY Function: ENTER Sends your input to the remote application program. While this communication is active, the keyboard locks and Inhib appears on the status line. Usually the application program releases the keyboard when it has finished processing your input. 5 ER_EOF VT100: EXT + KP, VT200: F18 DEFINE_KEY Function: ERASE_EOF Erases the contents of the current field, from the location of the cursor to the end of the field. The cursor remains in the same location. 5 ER_INP VT100: EXT + KP- VT200: EXT + F18 DEFINE_KEY Function: ERASE_INPUT On a formatted screen, clears all the data in the unprotected fields on your screen and moves the cursor to the first position in the first unprotected field on the screen. On an unformatted screen, clears all the data and moves the cursor to the first position on the screen. You can also use the ER INP function to remove all previously recorded key sequences by using the RECORD function and then the ER INP function. 5 EXIT VT100: Ctrl/Z or F10 VT200: Ctrl/Z or F10 DEFINE_KEY Function: EXIT Terminates the remote TELNET/TN3270 session. Aborts any exchange of data in progress between the local and remote hosts. Note that terminating a session with the IBM host in this way may result in improper termination of the session. For the appropriate logoff command string, see the user's guide for the IBM application with which you are communicating. 5 EXT VT100: KP. VT200: KP. DEFINE_KEY Function: EXTEND Used in conjunction with another key, allows access to an extended function for that key. First invoke the EXT function and then press the second key. If you invoke EXT accidentally, invoking the RESET function cancels the EXT function. If the status display is enabled when you invoke the EXT function, the word Extend appears on the status line. 5 FM VT100: EXT + ; VT200: EXT + F13 DEFINE_KEY Function: FM Specifies the end of a field on an unformatted screen or the end of part of an unprotected field on a formatted screen. Refer to the user's guide of the remote application program for specific use of this key. Displays a semicolon ( ; ). 5 HELP VT100: EXT + H VT200: Help DEFINE_KEY Function: HELP Displays online help and an illustration of the TN3270 keyboard. 5 HOME VT100: EXT + B VT200: F13 DEFINE_KEY Function: HOME Repositions the cursor to the first position in the first unprotected field on the screen (that is, to the beginning of the input area on the screen). 5 Left/Right_Arrows VT100: Right arrow or VT200: Right arrow or Left arrow Left arrow DEFINE_KEY Function: RIGHT, RIGHT_NOWRAP, LEFT, or LEFT_NOWRAP Moves the cursor horizontally across your screen without changing data you have already entered. If the cursor is at the: o End of a line when you use the Right arrow function, the cursor moves to the start of the next line. o Beginning of a line when you use the Left arrow function, the cursor moves to the end of the previous line. If the screen display you receive is wider than 80 columns, you can use the Right arrow and Left arrow functions to move through the display. If you want the cursor to wrap to the opposite edge of the display, use one of the following function sequences: EXT + Right arrow EXT + Left arrow 5 INSERT VT100: EXT + PF4 VT200: F14 DEFINE_KEY Function: INSERT_MODE Enables insert mode. Use insert mode to edit what you typed. If the status display is enabled, Insert appears. In insert mode, when you type a character into an unprotected field, it is displayed to the left of the cursor, moving the following one position to the right: o The cursor o The character at the cursor location o All the characters to the right of the cursor in the field You can insert characters into an: o Unformatted screen o Unprotected field on a formatted screen until it is full If you attempt to insert characters after the field is full, the keyboard locks, the terminal bell rings, and the word Inhib appears on the status line. If the keyboard locks when you try to insert characters into a field that looks empty, the field might have trailing spaces. To erase these spaces, use the ER EOF function. To return your screen to the normal mode of entry, use one of the following keyboard functions: o RESET o CLEAR o ENTER o Any PA key o Any PF key 5 Logical_Not VT100: EXT + N VT200: EXT + N DEFINE_KEY Function: (None) Represents the remote host's symbol for a logical NOT; displayed as a circumflex ( ^ ) on DIGITAL terminals. 5 Logical_Or VT100: EXT + O VT200: EXT + O DEFINE_KEY Function: (None) Represents the remote host's symbol for a logical OR; displayed as a solid vertical line from the terminal's graphics set. Press Ext + O if the vertical bar is not available on your keyboard. 5 New_Line VT100: Return VT200: Return DEFINE_KEY Function: NEWLINE Moves the cursor to the first unprotected position on the next line of your screen. If no unprotected fields are on the screen when you invoke the new line function, the cursor moves to the first location on the screen. If the screen has no fields, this key has the same function as the Return key on DIGITAL terminals. 5 NUM_OVR VT100: EXT + J VT200: Remove DEFINE_KEY Function: NUMOVR Lets you enter nonnumeric characters into numeric fields. Once you enable this function, use NUM OVR again to disable it. If you do not disable the numeric lock override, it remains enabled even after you exit from TN3270. The letter O appears on the status line to indicate that the numeric lock override is in effect. 5 PA_Keys VT100: PF4 , KP- , KP, VT200: PF4 , KP- , KP, DEFINE_KEY Function: PA1-PA3 These program access keys are defined by the program you are using. These keys request attention from the remote application program without sending any data. You should refer to the user's guide of your application program to learn how the PA keys are defined. 5 PF_Keys VT100: see below VT200: see below DEFINE_KEY Function: PF1-PF24 These program function keys are defined by the remote application program you are using. They request attention from the application program and send the data entered to the host. The PF keys are coded by the application program to perform functions relating to the application. A particular PF key may be coded differently from one application to another. The user's guide of the remote application program usually defines the specific PF key assignments for that application program. To Implement This Press This Key or Function Key Combination PF1 PF1 PF2 PF2 PF3 PF3 PF4 KP7 PF5 KP8 PF6 KP9 PF7 KP4 PF8 KP5 PF9 KP6 PF10 KP1 PF11 KP2 PF12 KP3 PF13 EXT + PF1 PF14 EXT + PF2 PF15 EXT + PF3 PF16 EXT + KP7 PF17 EXT + KP8 PF18 EXT + KP9 PF19 EXT + KP4 PF20 EXT + KP5 PF21 EXT + KP6 PF22 EXT + KP1 PF23 EXT + KP2 PF24 EXT + KP3 5 PLAY VT100: EXT + M VT200: Insert Here DEFINE_KEY Function: PLAY Recalls keystroke sequences stored on PF keys using the RECORD function. Invoke the PLAY function and then press the PF key on which the desired key sequence is stored. The PLAY function executes all commands included in the keystroke sequence. If the HELP utility is invoked in your key sequence, the PLAY function continues until you exit from the HELP utility. Also, if you use functions that require you to respond to prompts (such as ATTACH, DEF KEY, SET FIL, or SPAWN), the information you type at the prompt is not recorded. When you recall the sequence, the system prompts you for this information again. P appears on the status line if the status display is enabled. 5 PRINT VT100: EXT + P VT200: F11 DEFINE_KEY Function: PRINT Records the contents of your screen in a file or at a printer. (This is a local print feature.) If the status display is enabled when you use the PRINT function, the word Print appears on the status line. Your screen refreshes when the printing process completes. The first use of PRINT in a given run of TN3270 creates a new version of the output file. Successive uses of PRINT in the same program cause the screen contents to append to the existing file. If the output is directed to a printer, each use of PRINT creates a separate entry in the printer queue. If the printer is a spooled printer, the output is released for printing immediately. Use the command qualifier /PRINTER=file to specify where to direct the output file. The SET FIL function allows you to change the name of the output file each time you invoke the PRINT function. 5 RECORD VT100: EXT + L VT200: EXT + Insert Here DEFINE_KEY Function: RECORD Saves a keystroke sequence on a specific PF key. Invoke the RECORD function with the appropriate key sequence (as described above), press the PF key as prompted, enter the keystroke sequence, and then invoke the RECORD function again. You can save a maximum number of 127 keystrokes on each PF key. If the status display is enabled when you use the RECORD function, the letter R appears on the status line. To recall the keystroke sequence, use the PLAY function. Use the DV CNCL function to cancel the RECORD function. To erase all previously recorded key sequences, use the ER INP function. 5 REFR VT100: Ctrl/W VT200: Ctrl/W or F20 DEFINE_KEY Function: REFRESH Removes TN3270 error messages, operating system messages, or other messages that appear on your screen. This key function deletes extraneous characters from your screen and redisplays the fields and data that were on the screen before the interruption. This function does not transmit or receive data from the remote host. It is a local OpenVMS function. 5 RESET VT100: KP0 VT200: KP0 DEFINE_KEY Function: RESET Returns the keyboard to normal input mode from insert mode. Also, the RESET function returns the keyboard to your control after it locks when you try to enter data into a protected or a full field, or when you try to enter the wrong type of data into a field. Invoking RESET turns off the Inhib indicator. The cursor remains where it is and the screen remains unchanged. 5 SELECT VT100: EXT + K VT200: Select DEFINE_KEY Function: SELECT Lets you choose items from a menu, table, or list and then notify the program of your selection. Use the arrow keys to position the cursor on the field designator character, then use the SELECT function. For more information on using SELECT, refer to the user's guide of the remote application. 5 SET_FIL VT100: EXT + F or Ctrl/F VT200: EXT + F11 DEFINE_KEY Function: SET_PRINTFILE Lets you change the name of the file or device that receives output each time you invoke the PRINT function. After you invoke SET FIL, you are prompted for the name of a new output device, emulating the remote host's IDENT function. Note that if you specify the same name that is already in use, subsequent PRINT operations direct output to a new version of the same file. 5 SHO_MSG VT100: EXT + G VT200: EXT + F14 DEFINE_KEY Function: SHOW_MESSAGE Displays the broadcast messages that have been posted on a separate screen. If the status line is enabled, Msg appears on the status line. If you do not read the messages before they fill up the screen, the messages begin to scroll up out of view and you will no longer be able to read them. These broadcast messages are not saved after you read them or exit TN3270. 5 SPAWN VT100: EXT + D VT200: Find DEFINE_KEY Function: SPAWN Creates a subprocess under the current process. Use the LOGOUT command to terminate the subprocess. Because a tree of subprocesses can be established using the SPAWN function, you must be careful when terminating any process in the tree. When a process is terminated, all subprocesses below that point in the tree are terminated automatically. When you create a subprocess, you can specify an optional command string. The command string is executed within the created subprocess and the subprocess terminates upon completion of the command. 5 STATUS VT100: EXT + S VT200: F17 DEFINE_KEY Function: STATUS Lets you enable and disable the display of status information. When you enable STATUS, the last line on your screen is painted over with a reverse video strip. This line may conceal remote host system or application information. If this occurs, Hidden appears in the status line. Disable the status display by using the STATUS function again. 5 SYS_REQ VT100: EXT + R VT200: EXT + F19 DEFINE_KEY Function: SYS_REQUEST Lets you shift between the application program (the LU-LU session) and the control program (the SSCP-LU session). If the status display is enabled, Appl or SSCP appears on the status line to indicate the type of session. Appl appears when you are in an LU-LU session and SSCP appears when you are in the SSCP-LU session. The screen is refreshed when you use the SYS REQ function. 5 Tab VT100: Tab VT200: Tab DEFINE_KEY Function: TAB Moves the cursor to the first character location of the next unprotected field on your screen. If the screen has no fields, the Right arrow | function moves the cursor to the first location on the screen. If the cursor is within the last unprotected field on the screen, the cursor moves to the first position of the first unprotected field on the screen. 5 Up/Down_Arrows VT100: Up arrow or Down VT200: Up arrow or Down arrow arrow DEFINE_KEY Function: UP, UP_NOWRAP, DOWN, or DOWN_NOWRAP Moves the cursor vertically on your screen without altering the data you have already entered. If the cursor is at the: o Top of the screen when you press the up arrow, the cursor appears in the same column at the bottom of the screen o Bottom of the screen when you press the down arrow, the cursor appears in the same column at the top of the screen If the screen display you receive is larger than 24 rows deep, you can use the Up arrow and the Down arrow keys to move through the display. These keys scroll the screen display up or down. If you want the cursor to wrap to the opposite edge of the display, use the key sequence EXT + Up arrow or EXT + Down arrow. 5 Additional_Information For additional information about TN3270 key functions, see the following IBM documents: o IBM 3270 Information Display System, Order No. GA23-0060 o IBM 3270 Information Display System: Operator's Guide, Order No. GA27-2742 o IBM 3270 Information Display System: 3278 Display Station Operator's Guide, Order No. GA27-2890-4 4 Redefining_Your_Keyboard You can reassign the following functions: o All emulated functions o Most IBM 3270 model functions o All emulated alphanumeric and graphic characters 5 Definable_Keys The keys you can define are: Location Key Name Function keys PF1-PF4 (VT100 and VT200) Application KP0-KP9 keypad ENTER (VT100 and MINUS VT200) COMMA PERIOD Top-row F6-F20 function keys HELP (F15) (VT200) DO (F16) Editing keypad FIND (E1) (E1-E6) INSERT_HERE (E2) (VT200) REMOVE (E3) SELECT (E4) PREV_SCREEN (E5) NEXT_SCREEN (E6) Cursor keys UP (VT100 and DOWN VT200) LEFT RIGHT Control keys Ctrl/A-Ctrl/Z, including: (VT100 and VT200) Ctrl/H (BS) Ctrl/I (HT) Ctrl/J (LF) Ctrl/M (CR) Excluding: Ctrl/Y-Interrupt Ctrl/C-Cancel/interrupt Ctrl/O-Output off/on Ctrl/S-Suspend output Ctrl/Q-Resume output 5 Nondefinable_Keys You cannot redefine the following DIGITAL-reserved keys: o Ctrl/Y - Interrupt o Ctrl/C - Cancel/interrupt o Ctrl/O - Output off/on o Ctrl/S - Suspend output o Ctrl/Q - Resume output o F1-F5 5 Redefining_Keys To redefine a keyboard key, use either of the following methods: o Create a key definition file, a text file with individual key definitions in the form of DEFINE/KEY statements and DELETE /KEY statements. o Use the DEF KEY function (see DEF KEY Function ). The following example establishes a TELNET/TN3270 connection to host JUNCO. By default, the terminal functions as if it were an IBM-3278-2 model terminal. It uses your customized keyboard definition file NEW_KEYS.DAT. $ TN3270 JUNCO /KEY_DEFINITION=NEW_KEYS.DAT 5 Key_Definition_File Use the DEFINE/KEY and DELETE/KEY statements to create your own key definition file as described in the following sections. The DEFINE/KEY statement assigns a new function to a particular key. Its format is: DEFINE/KEY [/STATE=EXTEND] key_name function /STATE Optional. Default: non-extend mode. Redefines the key in extend mode. key_name Standard key name on the DIGITAL terminal. function TN3270 function you want mapped to this key. You can define most of the named keys both in normal (non-extend) mode and in extend mode. You can define the control keys (and the synonyms for them) only in normal mode. Do not specify the qualifier /STATE=EXTEND. The following example assigns the EXIT function to the key sequence EXT + Z : DEFINE/KEY/STATE=EXTEND "Z" EXIT The DELETE/KEY statement removes the function assigned to a particular key. Its format is: DELETE/KEY [/STATE=EXTEND] key_name /STATE Optional. Default: nonextend mode. Deletes the key in extend mode. key_name Standard key name on the DIGITAL terminal. Example: The following example removes the default value of EXIT from Ctrl/Z. DELETE/KEY <Ctrl/Z> 5 DEF_KEY_Function_ Use the DEF KEY function to define or redefine a key interactively. Your new definition exists until you log out from the remote host or disconnect from it. When you invoke the DEF KEY function, TN3270 displays a prompt in the status line at the bottom of your screen. Example: The following example shows the use of DEF KEY to define a key. You invoke the DEF KEY function by entering the Ctrl/K sequence, after which you are prompted for the key you want to define and the function to assign to that key. <Ctrl/K> Press the key that you wish to define: Enter the function name or quoted character: You can also use DEF KEY to remove an assigned function. A null reply to the following prompt removes the definition currently in effect for that key: Enter the function name or quoted character: What you type during the DEF KEY dialog is subject to translation from the National Character Set to the DIGITAL Multinational Character Set. You cannot redefine a key that exists on your National Character Set terminal if it lacks a DIGITAL Multinational Character Set equivalent. 4 Problem_Solving During a TELNET session in which you have invoked TN3270, you might experience the following problems: Problem o The keyboard keys do not work properly. o Messages, such as the status line messages, do not appear in reverse video. o You receive a message indicating that your terminal is an unsupported model. You cannot use TN3270 on a VT131 model terminal that is running in block mode. Solution for a VT100-series Terminal Use Set-Up mode to verify that your terminal is in ANSI mode. Issue the following command: $ SET TERMINAL /INQUIRE Solution for a VT200-Series Terminal or a Terminal Connected to Either a DIGITAL Personal Computer or a Workstation 1. Use Set-Up mode to verify that your terminal is: o In ANSI mode o Set to VT100 or VT200 emulation mode 2. Check the Communications Menu: The terminal communications line must be set for 8-bit characters. To check, issue the following command: $ SET TERMINAL /INQUIRE Solution for a Terminal with a National Language Keyboard Ensure that your terminal is set up to correspond to your keyboard. Problem You receive a message indicating that the screen size (or the alternate screen size) specified by the remote host is too big. Solution Use Set-Up mode to change to a valid screen size. Problem You try to use the RECORD or PLAY function, but you get an error message indicating that you have a bad key sequence file. Solution The file that stores the recorded key sequence is incompatible with the current version of the software or is corrupted. Ask your system manager to do either of the following: o Correct UCX$RECSEQ.DAT in your SYS$LOGIN directory. o Delete UCX$RECSEQ.DAT. If the system manager must delete this file, rerecord all the key sequences you had stored on the PF keys. 4 Debugging_Application_Programs_Using_the_IBM_3270_Model_Terminal_Emulator Visible attribute mode provides a way to debug application programs. After you use the DSP ATT (display attributes) function to enable visible attribute mode, all attribute characters are visible. Attribute characters are characters that appear at the start of a field to indicate the following information: o How the field appears on the screen: - At normal intensity - At high intensity - Invisibly o What type of data the application expects in the field: - Numeric - Alphabetic - Alphanumeric For help on how to enter and exit visible attribute mode, see Entering and Exiting Visible Attribute Mode . For information on the attribute characters displayed and their meaning, Visible Attribute Mode Displays . 5 Entering_and_Exiting_Visible_Attribute_Mode_ The displays described in this section rely on your terminal's ability to produce reverse video and bold characters. Invoking the DSP ATT function toggles in and out of visible attribute mode. o The first time you press this key combination: - The screen refreshes. - The attribute characters appear either in reverse video or underlined. o The second time you press DSP ATT: - You turn off this mode. - The screen refreshes and returns to normal mode. 5 Visible_Attribute_Mode_Displays_ The attribute characters are displayed in reverse video, bold symbols. Attribute characters indicating numeric fields are also underlined. All other characters are displayed normally. The following table lists the attribute characters and their meanings. Character Meaning n Unprotected field with normal intensity follows N Protected field with normal intensity follows d Following unprotected field is light-pen-detectable D Following protected field is light-pen-detectable h Following unprotected field has high intensity H Following protected field has high intensity i Unprotected nondisplay field follows I Protected nondisplay field follows 2 NFS For information about the Network File Service (NFS), type: $ HELP TCP_IP_SERVICES PRODUCT_OVERVIEW NFS For complete information about the NFS server and NFS client, see the "DIGITAL TCP/IP Services for OpenVMS Management" manual. 2 TCPIPTRACE Starts the UCX$TRACE utility. Format TCPIPTRACE host [/BUFFERS=n | /FULL | /OUTPUT |/PACKETS=n | /PORT=option | /PROTOCOL=option] 3 Parameters host Required. Remote host to which you are sending packets for tracing. 3 Qualifiers /BUFFERS /BUFFERS=n Optional. Default: 100. Number of buffers that UCX$TRACE allocates for temporary storage. These buffers must be locked into the process working set, so you may have to decrease the number to accomodate the working set size or increase the number to prevent UCX$TRACE from dropping packets. /FULL Optional. Default: Brief display. Displays the packet contents. /OUTPUT Optional. Default: Screen display. Redirects the trace output to a file. If you specify a file name that already exists, UCX$TRACE appends new trace information to the existing file. /PACKETS /PACKETS=n Optional. Default: 10. Stops the trace after UCX$TRACE displays the specified number of packets. /PORT /PORT ={LOCAL | REMOTE}= n Optional. Default: Trace all port numbers. Specifies the local or remote port number to trace. Use in conjunction with the /PROTOCOL qualifier to filter tracing to an exact port and protocol. /PROTOCOL /PROTOCOL = {ARP | ICMP | IP | TCP | UDP} Optional. Default: IP Specifies the protocol to trace. Use in conjunction with the /PORT qualifier to filter tracing to an exact port and protocol. 3 Examples 1.$ TCPIPTRACE HOST1 /FULL /PORT=REMOTE=21 Traces packets for host HOST1 and remote port number 21. UCX$TRACE provides a full display of the packets contents. 2.$ TCPIPTRACE HOST2 /FULL /PORT=(LOCAL=23, REMOTE=1056) - _$ /PACKETS=30 /OUTPUT=TELNET_TRACE.TXT) Traces packets for host HOST2 with a local port of 23 and remote port number of 1056. UCX$TRACE provides a full display of the packets contents. UCX$TRACE continues the trace for 30 packets and writes the output to the file TELNET_TRACE.TXT in the current directory. 2 RPCGEN A code-generating tool for creating programming skeletons that implement the RPC mechanism. NOTE RPCGEN runs the C preprocessor, CC/DECC/PREPROCESSOR, on all input files before actually interpreted the files. Therefore, all the preprocessor directives are legal within an RPCGEN input file. For each type of output file, RPCGEN defines a special preprocessor symbol for use by the RPCGEN programmer: RPC_HDR Defined when compiling into header files RPC_XDR Defined when compiling into XDR routines RPC_SVC Defined when compiling into server-side skeletons RPC_CLNT Defined when compiling into client-side skeletons RPC_TBL Defined when compiling into RPC dispatch table In addition, RPCGEN does a little preprocessing of its own. RPCGEN passes any line beginning with "%" directly into the output file, without interpreting the line. 3 Parameters infile The input file to RPCGEN. The input file contains ONC RPC programming language. This language is very similar to the C language. By default, RPCGEN uses the name of the input file to create the four default output files as follows: o infile.H-the header file o infile_CLNT.C-the client skeleton o infile_SVC.C-the server skeleton with support for both UDP and TCP transports o infile_XDR.C-the XDR routines If you specify the /DISPATCH_TABLE qualifier, RPCGEN uses the default name infile_TBL.I for the dispatch table. 3 Qualifiers /CLIENT_STUBS_FILE Optional. Digital UNIX equivalent: -l Default: Create a client skeleton file. Creates the client skeleton file. Mutually exclusive with the /DISPATCH_TABLE, /HEADER_FILE, /SERVER_STUBS_FILE, /TRANSPORT, and XDR_FILE qualifiers. /DEFINE /DEFINE = (name[=value][,....]) Optional. Digital UNIX equivalent: -D Default: No definitions. Defines one or more symbol names. Equivalent to one or more #define directives. Names are defined as they appear in the argument to the qualifier. For example, /DEFINE=TEST=1 creates the line #define TEST=1 in the output files. If you omit the value, RPCGEN defines the name with the value 1. /DISPATCH_TABLE Optional. Digital UNIX equivalent: -t Default: No dispatch file created. Creates the server dispatch table file. An RPCGEN dispatch table contains: o Pointers to the service routines corresponding to a procedure o A pointer to the input and output arguments o The size of these routines A server can use the dispatch table to check authorization and then to execute the service routine; a client may use it to deal with the details of storage management and XDR data conversion. Mutually exclusive with the /CLIENT_STUBS_FILE, /HEADER_FILE, /SERVER_STUBS_FILE, /TRANSPORT, and XDR_FILE qualifiers. /ERRLOG Optional. Digital UNIX equivalent: -L Default: Logging to stderr. Specifies that servers should log errors to the operator console instead of using fprintf with stderr. You must install servers with OPER privileges in order to use this feature. /HEADER_FILE Optional. Digital UNIX equivalent: -h Default: Create a header file. Creates the C data definitions header file. Use the /TABLE qualifier in conjunction with this qualifier to generate a header file that supports dispatch tables. Mutually exclusive with the /CLIENT_STUBS_FILE, /DISPATCH_TABLE, /SERVER_STUBS_FILE, /TRANSPORT, and XDR_FILE qualifiers. /INET_SERVICE Optional. Digital UNIX equivalent: -I Default: no INETd support. Compiles support for INETd in the server side stubs. You can start servers yourself or you can have INETd start them. Servers started by INETd log all error messages to the operator console. If there are no pending client requests, the INETd servers exit after 120 seconds (default). You can change this default with the /TIMEOUT_SECONDS qualifier. When RPCGEN creates servers with INETd support, it defines two global variables: _rpcpmstart and rpcfdtype. The runtime value of _rpcpmstart is 1 or 0 depending on whether INDEd started the server program. The value of rpcfdtype should be SOCK_STREAM or SOCK_DGRAM depending on the type of the connection. /OUTPUT /OUTPUT = file Optional. Digital UNIX equivalent: -o Default: Direct output to one of the standard default files. Use this qualifier to direct the output of the /CLIENT_STUBS_ FILE, /DISPATCH_TABLE, /HEADER_FILE, /SERVER_STUBS_FILE, /TRANSPORT, and /XDR_FILE qualifiers. /SERVER_STUBS_FILE Optional. Digital UNIX equivalent: -m Default: Create a server skeleton file. Creates a server skeleton file without the main routine. Use this qualifier to generate a server skeleton when you wish to create your own main routine. This option is useful for programs that have callback routines and for programs that have customized initialization requirements. Mutually exclusive with the /CLIENT_STUBS_FILE, /DISPATCH_TABLE, /HEADER_FILE, /TRANSPORT, and XDR_FILE qualifiers. /TABLE Optional. Digital UNIX equivalent: -T Default: No dispatch table code created. Creates the code in the header file to support an RPCGEN dispatch table. You can use this qualifier only when you are generating all files (the default) or when you are using the /HEADER_FILE qualifier to generate the header file. This /TABLE qualifier includes a definition of the dispatch table structure in the header file; it does not modify the server routine to use the table. /TRANSPORT /TRANSPORT [= (TCP, UDP)] Optional. Digital UNIX equivalent: -s Default: Create a server-side skeleton that supports both protocols. Creates a server-side skeleton that includes a main routine that uses the given transport. The supported transports are UDP and TCP. To compile a server that supports multiple transports, specify both. /TIMEOUT_SECONDS /TIMEOUT_SECONDS=seconds Optional. Digital UNIX equivalent: -K Default: 120 seconds. If INETd starts the server, this option specifies the time (in seconds) after which the server should exit if there is no further activity. By default, if there are no pending client requests, INETd servers exit after 120 seconds. This option is useful for customization. If seconds is 0, the server exits after serving a request. If seconds is -1, the server never exits after being started by INETd. /XDR_FILE Optional. Digital UNIX equivalent: -c Default: Create an XDR file. You can customize some of your XDR routines by leaving those data types undefined. For every data type that is undefined, RPCGEN assumes that there exists a routine with the name xdr_ prepended to the name of the undefined type. Mutually exclusive with the /CLIENT_STUBS_FILE, /DISPATCH_TABLE, /HEADER_FILE, /TRANSPORT, and /SERVER_STUBS_FILE qualifiers. 3 Examples 1.RPCGEN /ERRLOG /TABLE PROTO.X This example generates all of the five possible files using the default file names: PROTO.H, PROTO_CLNT.C, PROTO_SVC.C, PROTO_ XDR.C, and PROTO_TBL.I. The PROTO_SVC.C code supports the use of the dispatch table found in PROTO_TBL.I. The server error messages are logged to the operator console, instead of being sent to the standard error. 2.RPCGEN /INET_SERVICE /TIMEOUT_SECONDS=20 PROTO.X This example generates four output files using the default file names: PROTO.H, PROTO_CLNT.C, PROTO_SVC.C, and PROTO_XDR.C. INETd starts the server and the server exits after 20 seconds of inactivity. 3.RPCGEN /HEADER_FILE /TABLE PROTO.X This example sends the header file (with support for dispatch tables) to the default output file PROTO.H. 4.RPCGEN /TRANSPORT=TCP PROTO.X This example sends the server skeleton file for the transport TCP to the default output file PROTO_SVC.C. 5.RPCGEN /HEADER_FILE /TABLE /OUTPUT=PROTO_TABLE.H PROTO.X This example sends the header file (with support for dispatch tables) to the output file PROTO_TABLE.H. 2 FINGER_Command Displays information about users on a host. You can display: o Brief listings of all users on a host o Detailed listings about specific users o Listing of users on a cluster Specifying the FINGER command without a user or host specification displays information about users logged in on your local system. Format FINGER [/ALL | /CLUSTER | /FULL] [username][@hostname] 3 Parameters username Optional. Required for detailed information about a user. Specify the user login name. For information about a user on your local system, do not include the @hostname. For information about a user on a remote system, include the host name (username@hostname). @hostname Optional. Required for information about users on a remote system. For information about a specific user on a remote host, include the user name with the host name (username@hostname). For information about all users on the remote host, specify the host name only (@hostname). Omit the host name to display information about users on your local host. 3 Qualifiers /ALL Optional. Use when specifying a local user name. The /ALL qualifier must follow immediately after the FINGER command. Displays a brief listing of all users in addition to detailed information about any specified users. Use this qualifier primarily for displaying information about users on the local host. The /ALL qualifier is ignored by most remote Finger servers when you specify a remote host name in the command line. To display brief information about all users on a remote host in addition to detailed information about specific users, specify the user@hostname format for each user plus @hostname (to list brief information about all users). Separate each user@hostname and @hostname specification with a space. /CLUSTER Optional. The /CLUSTER qualifier must follow immediately after the FINGER command. Do not specify a remote host name with this qualifier. Displays information about all users logged in to the local OpenVMS Cluster system. /FULL Optional. The /FULL qualifier must follow immediately after the FINGER command. Displays more detailed information such as the user's real name and all logins of the user (without /FULL, the display includes the last login only). Use this qualifier primarily for displaying information about users on the local host. 3 Examples 1.$ FINGER FRANKEL@KCRA Username Program Login Term/Location FRANKEL $ Mon 15:10 KCRA::FRANKEL Login name: frankel In real Life: Sam Frankel Account: CC_Y9M Directory: WORK1$:[FRANKEL] Last login: Mon 29-MAR-1997 13:10:22 No unread mail No plan Displays detailed information about user FRANKEL at host KCRA. 2.$ FINGER @OXYGEN [oxygen.gp.org] Username Program Login Term/Location BARD $ Mon 17:00 CASON LSEDIT Thu 14:57 CORR $ Tue 13:30 24151::CORR DUDLEY $ Mon 15:02 24646::DUDLEY GRAND $ Thu 07:50 NITROGEN::GRAND KURT $ Mon 16:57 22556::KURT KYLIE MAIL Thu 14:12 ELEMENT::KYLIE MYRA $ Wed 16:04 BIGVAX::MYRA NASON $ Tue 09:23 24200::NASON PHILLIPS $ Tue 02:42 BIGALP::PHILLIPS RAWLINGS $ Mon 18:50 24042::RAWLINGS Displays brief information about users logged into host OXYGEN. 3.$ FINGER/FULL Username Real Name Program Login Term/Location BAIRD Randall Baird $ Mon 17:00 CARR Rich Carr LSEDIT Thu 14:57 SHWCLSTR Mon 17:01 CORTEZ Julia Cortez $ Tue 13:30 23441::CORTEZ DANBOY Dan Keller $ Thu 16:12 ogrady.ucsb.edu GANDHI T.J. Gandhi TPU Mon 16:57 12556::GANDHI TPU Tue 15:27 12556::GANDHI LIMO Michael Limorley MAIL Thu 14:12 TOPDAY::LIMO LSEDIT Thu 19:03 TOPDAY::LIMO MENNING Mark Menning $ Wed 16:04 TOPDAY::MENNING $ Mon 18:58 HAPDAY::MENNING NELSON Anne Nelson $ Tue 09:23 22200::NELSON ROBERTS Michael Roberts $ Mon 18:50 22042::ROBERTS $ Mon 18:34 HAPDAY::ROBERTS Displays the real name and all logins for each user. 4.$ FINGER/CLUSTER Username Node Program Login Term/Location SMITH MOUNTB TPU Fri 09:47 MOUNTB::SMITH JONES MOUNTC $ Tue 18:02 BROWN MOUNTC $ Mon 17:04 TAYLOR MOUNTB EDT Thu 15:59 CROSBY MOUNTC RTPAD Thu 14:59 CARPENTER MOUNTB $ Wed 17:23 MOUNTB::SYSTEM BLACK MOUNTC $ Tue 10:42 MOUNTC::BLACK Displays information about all users on all members of the cluster. 2 FTP_Command The DIGITAL TCP/IP Services for OpenVMS (UCX) software includes the File Transfer Protocol (FTP) service. The FTP command starts an FTP session and does one of the following: o Displays the FTP prompt. You can issue FTP commands to customize your environment and FTP command processing. o Establishes a connection to the specified remote host. For help with individual FTP commands, type: $ FTP FTP> HELP DCL-Style Format FTP [host [ port ] ] [/USERNAME=remote_user_name | /PASSWORD=password | /INPUT=file] UNIX-Style Format ftp [ host [ port ] ] [ local_file ] 3 Parameters host Optional. Remote host to which you want to connect. port Optional. Default: 21. FTP port on the remote host. 3 Qualifiers /INPUT /INPUT=file Optional. Default: interactive input. Runs a DCL command file with FTP commands. /PASSWORD /PASSWORD=password Optional. Default: your password on the local system. Password for the remote user account to which you want to connect. /USERNAME /USERNAME=remote_user_name Optional. Default: your user name on the local system. Name of the remote user account to which you want to connect. 3 Examples 1.$ FTP WKSITE <Return> 220 wksite.texts.wrights.com FTP Server (DIGITAL UNIX 13:34:28 EDT) Ready Connected to wren.nest.willow.com. Name (wksite:parks) <Return> 331 Username PARKS requires a password Password: (not echoed) <Return> 230 User logged in FTP> User PARKS starts an FTP session and connects to UNIX host wksite. 2.$ FTP VIRTL /USERNAME=BENSON /PASSWORD=WMSWMS 220 newy FTP Server (Version 4.2) Ready Connected to NEWY.LINK1.MOA.COM. 230 User logged in FTP> Starts an FTP session and connects to remote OpenVMS host VIRTL, in user account BENSON. 3.$ FTP FTP> Starts an FTP user session without establishing a connection. 2 SMTP For information about support for Simple Network Mail Protocol (SMTP) in the DIGITAL TCP/IP Services for OpenVMS product, type the following: $ HELP TCP_IP_SERVICES MAIL 2 LPQ_Command Displays the status of your jobs in a remote print queue: o Current rank of your job in the queue o Names of your queued files o Job identifier o Size of jobs in bytes Format LPQ queue [/ENTRY=n | /HOST=host | /PRINTER=remote_printer | /USER=user_name] 3 Parameters queue Required. Queue for which you want status. 3 Qualifiers /ENTRY /ENTRY=n Optional. Default: all jobs. You can specify a list of values. Displays status for the specified jobs. /HOST /HOST=host Optional. Default: host defined in the printcap file. Displays status for the jobs you sent to the specified host. This is the host you also specified in the PRINT /PARAMETERS=(HOST=host) command. /PRINTER /PRINTER=remote_printer Optional. Default: printer defined in the printcap file. Displays status for the jobs you sent to the specified remote printer. This is the queue you also specified in the PRINT /PARAMETERS=(PRINTER=queue) command. /USER /USER=user Optional. Default: all users. Displays status for the jobs sent by the specified user. You can specify a list of values. 3 Examples 1.$ LPQ LPS40_QUE Shows all entries in the LPS40_QUE queue. 2.$ LPQ MAIN_QUE /ENTRY=4 Shows information about Job 4 in the print queue named MAIN_ QUE. 3.$ LPQ PEACE_8 /ENTRY=(1,2,3) Shows information about Jobs 1, 2, and 3 in print queue PEACE_ 8. 4.$ LPQ 3RD_FLOOR_Q /USER=MILLER Shows information about user MILLER's jobs in the print queue called 3RD_FLOOR_Q. 2 LPRM_Command Removes one or more jobs from a remote print queue. Format LPRM queue {/ALL | /ENTRY=n | /USER=user_name} [/HOST=host | /PRINTER=remote_printer] 3 Parameters queue Required. Print queue with waiting jobs you want to delete. 3 Qualifiers /ALL Required, unless you specify /ENTRY or /USER. Removes all jobs for all users from the specified queue. Requires SYSPRV, OPER, or BYPASS privileges. Comparable to the UNIX command lprm -Pqueue - when performed by the root user on the UNIX system. /ENTRY /ENTRY=n Required, unless you specify /ALL or /USER. Removes the specified job. Specify only your own jobs. You can specify a list of values. /USER /USER=user Required, unless you specify /ALL or /ENTRY. Removes jobs by user name. You can specify a list of values. /HOST /HOST=host Optional. Default: host defined in the printcap file. Removes jobs by host for the host you specified in the PRINT /PARAMETERS=(HOST=host) command. /PRINTER /PRINTER=remote_printer Optional. Default: printer defined in the printcap file. Removes jobs from the remote printer you specified in the PRINT /PARAMETERS=(PRINTER=queue) command. 3 Examples 1.$ LPRM BASE_Q /ENTRY=7 Deletes your Job 7 from print queue BASE_Q. 2.$ LPRM FRONT_Q /ENTRY=(555,556,558) From queue FRONT_Q, deletes a list of entries: 555, 556, and 558. 2 PRINT_Command See HELP TCP_IP_SERVICES NETWORK_PRINTING REMOTE_PRINTING 2 RCP_Command Copies files between internet hosts. Issue the RCP command at the DCL prompt. You can copy files: o From a remote host to your host o From your host to a remote host o From one remote host to another remote host You can specify qualifiers in either OpenVMS-style format or UNIX-style format, but do not mix both types on the same command line. DCL-Style Format RCP [/[NO]LOG | /PASSWORD[=password] | /[NO]PRESERVE | /[NO]RECURSIVE | /[NO]TRUNCATE_USER_NAME[=n] | /USER_NAME=remote_user_name] source_file destination_file UNIX-Style Format rcp [ -p ] [ -r ] /[source_file] /[destination_file] This format is valid only on UNIX systems. 3 Parameters source_file Required. Source host and file specification, in the format "[username@]"host:file, where: o username@ is the user name on a remote UNIX system, needed only if the UNIX system has the name in its /etc/hosts.equiv file or the UNIX user's .rhosts file. Enclose username@ portion, or the entire specification containing the username@ syntax, in quotation marks (" "). o host is the remote host, followed by a colon (:). o file is the name of the file to copy. A file name without the full path specification defaults to the default (or home) directory. RCP Command: Specifying the Source File shows the possible correct formats. Table 1 RCP Command: Specifying the Source File Host Possible Formats UNIX hosts Specify the following, enclosing UNIX path names that include slashes (/) in quotation marks (" "): o Absolute path name, such as /etc/user/hosts, followed by the file name o Path name relative to your default directory, followed by the file name OpenVMS Specify the following: hosts o Brackets ([ ]), which indicate your default directory, followed by the file name o Full file specification, such as DKA0:[WILDE.BINDS.NORTHERN]CHAPTER1.TXT To specify a device name, type a colon (:) and then the name. Enclose the entire parameter within quotation marks (" "). o A logical name, such as SYS$LOGIN:ROBIN.DAT or DIAK$9:[AMERICAN]FINDINGS.LIS To specify a logical name, type a colon (:) and then the name. Enclose the entire parameter within quotation marks (" "). destination_file Required. Destination host and file specification information is of the same form as the source parameter, unless the file specification is completely omitted or the file name portion of the file specification is omitted. In these cases, the default file name used is the same as specified in the source parameter, the directory being the default/home directory of the user. 3 Qualifiers /LOG /LOG /NOLOG Optional. Default: no logging. Logs the files copied to or from the local system. /PASSWORD /PASSWORD=password Required if /USER_NAME qualifier is used. Password on the source or destination host system (whichever requires authentication). /PRESERVE /PRESERVE (OpenVMS Style) /NOPRESERVE -p (UNIX style, valid only on UNIX systems) Optional. Preserves the file protection mode and modification date during a copy. /RECURSIVE /RECURSIVE (OpenVMS Style) /NORECURSIVE -r (UNIX style, valid only on UNIX systems) Optional. Recursively copies each subtree rooted at the directory you specify in the UNIX file specification. For OpenVMS hosts, specify [directory...] (with three trailing periods) in the file specification instead of using this qualifier. /TRUNCATE_USER_NAME /TRUNCATE_USER_NAME[=n] /NOTRUNCATE_USER_NAME Optional. Default: no truncation. Truncates the user name to the specified number of characters. If you omit n, the default is eight characters. /USER_NAME /USER_NAME=remote_user_name Optional. Default: current name on local host, but in lowercase. Specify user name on the source or destination remote host. Use only if an entry allowing access to this user has not been added to the remote host's authentication files. You must also specify the /PASSWORD qualifier with the /USER_NAME qualifier. If necessary, truncate the user name to the required number of characters using the /TRUNCATE_USER_NAME qualifier. Specifying "username@" with the source or destination parameter is the equivalent UNIX-style method. 3 Examples 1.$ RCP/LOG NYX:STATS.BNT [] Copies file stats.bnt from remote UNIX system nyx from under its home directory to a local file of the same name in the current directory. The /LOG qualifier causes information for the copy to be displayed. This command assumes the user has an entry in the authentication file on host nyx. 2.$ RCP HIAIR1:AIRFRS.TXT [FLTAT.STATS]FARES1.TXT Copies file AIRFRS.TXT from remote OpenVMS system HIAIR1, from under its home directory to a local file of a different name (FARES1.TXT) in the specified directory. This command assumes the user has an entry in the authentication file on host HIAIR1. 3.$ RCP /PRESERVE HIAIR1:[FARES.SUMMER]FARES_SU.TXT ":DKA300:[]" Copies file FARES_SU.TXT from directory [FARES.SUMMER] on remote OpenVMS system HIAIR1 to the specified device and directory on the local system. The new file maintains the same name as the original. The copy preserves the source file's protection mode and modification date. Use quotation marks (" ") for specifying the device and directory on the destination. 4.$ RCP /USER=MILLER /PASS="AirOut" ":SYS$LOGIN:PILOTS.LIS" FALCON: Copies file PILOTS.LIS from the login directory of user MILLER on the local system to the user's login directory on a remote UNIX system. The user specifies the user name and password for access to the UNIX system (the password is specified in quotation marks to preserve the mixed uppercase letters). Use quotation marks (" ") for specifying the SYS$LOGIN device and file name on the destination. 5.$ RCP /RECURSIVE ":DKA300:[MILES...]" "nyx:/usr/tmp" Copies all files and any subdirectories under the local directory [MILES] to a remote UNIX host's destination directory. All the files in the subdirectories are copied as well, creating subdirectories on the remote host, as appropriate. The directory hierarchy is preserved on the UNIX host by default. This command assumes the user has an entry in the authentication file on host nyx. 6.$ RCP /LOG /RECURSIVE [MILES...] BOSTON:[FRFL...] Copies the complete local subdirectory tree ([MILES...] and all subdirectories) to the destination directory on remote OpenVMS host BOSTON, while preserving the directory hierarchy and logging each file copy. This command assumes the user has an entry in the authentication file on host BOSTON. 7.$ RCP /LOG /RECURSIVE [MILES...] BOSTON:[FRFL] Same as Example 6, except that all files in the local directory tree are copied directly to the destination directory itself. The command does not preserve the directory hierarchy of [MILES...] in [FRFL] on host BOSTON. In other words, the command does not create new subdirectories in BOSTON:[FRFL]; it copies all the files in [MILES] and all its subdirectories to directory [FRFL]. 8.$ RCP /USER=VAUGHN /PASSWORD=MYLES - _$ /TRUNCATE=4 STATS.TXT FRAM:TISTICS Copies the local file STATS.TXT to a remote user's login directory. Note the truncation of the remote user name. A user name and password are necessary if no entries for the user are present in the remote host's authentication files. 9.$ RCP BOSTON:NAMES.LIS FRAM:ROSTER.LIS Copies file NAMES.LIS from remote host BOSTON to remote host FRAM (naming the file ROSTER.LIS). Assumes appropriate entries for the user have been made in each remote host's authentication files. 10$ RCP "MILLER@BOSTON:SYS$DIR:T2" "nelson@nyx:/usr/nelson" Copies file T2 from remote OpenVMS system BOSTON in the directory pointed to by the logical name SYS$DIR to remote UNIX system nyx in the specified directory. Different user names are used on the two remote systems. Entries in the remote host's authentication files must be set up properly because the passwords are not being passed. 11$ RCP /USER=ROSS /PASSWORD=LC12LC BOS:CLIENT.LIS "BEX:/USR" Copies file CLIENT.LIS from OpenVMS host BOS to UNIX host bex. The user has a proxy account on the UNIX host. The specified authentication information allows access to the account for ROSS on host BOS. 2 REXEC_Command Sends one command to a specified remote host for execution. The difference between the REXEC facility and RSH is security checking: o REXEC - the remote host bases authentication on user name and password. o RSH - the remote host bases authentication on user name and information in the remote system's authentication files. To invoke the REXEC feature, type either of the following: RSH /PASSWORD=password or RSH /PASSWORD 2 RLOGIN_Command Initiates an interactive login session with a remote host. DCL-Style Format RLOGIN [/DROP_TIMEOUT=seconds | /EIGHTBIT | /ESCAPE_CHARACTER=character | /LOG_FILE=file | /[NO]LOWERCASE | /PROBE_TIMEOUT=seconds | /TERMINAL_SPEED=baud | /TERMINAL_TYPE=type | /[NO]TRUNCATE_USER_NAME | /USER_NAME=remote_user_name] host UNIX-Style Format rlogin host [ -8 ] [ -ec ] [ -l remote_user_name ] This format is valid only on UNIX systems. 3 Parameters host Required. Remote host to which you want to connect. 3 Qualifiers /DROP_TIMEOUT /DROP_TIMEOUT=seconds Required if you set /PROBE_TIMEOUT. Maximum interval, in seconds, that your network link can be down before the software closes it. /EIGHTBIT /EIGHTBIT -8 (UNIX style, valid only on UNIX systems) Optional. Default: only 7-bit data is sent. Accepts 8-bit data from the terminal and sends it to the remote system. /ESCAPE_CHARACTER /ESCAPE_CHARACTER=character -ec (UNIX style, valid only on UNIX systems) Optional. Default: ~ (tilde). New escape character if you want to close your RLOGIN session from the remote host. To close your session from your local host, use a period ( . ) as the escape command. /LOG_FILE /LOG_FILE=file Optional. Default: no logging. Logs a copy of the output to the specified file. Output continues to be directed to SYS$OUTPUT while it is being recorded in the log file. /LOWERCASE /LOWERCASE /NOLOWERCASE Optional. Default: /LOWERCASE. Sends your local user name to the remote host in lowercase. To send your user name in uppercase, use either of the following: o Specify /NOLOWERCASE. o Enclose the user name in quotation marks ( " " ). (See /USER_ NAME.) To send your user name in mixed case, enclose it in quotation marks ( " " ). /PROBE_TIMEOUT /PROBE_TIMEOUT=seconds Required if you set /DROP_TIMEOUT. Interval, in seconds, that DIGITAL TCP/IP Services for OpenVMS checks to see if your network link and the remote host are both still up. /TERMINAL_SPEED /TERMINAL_SPEED=baud Optional. Default: current speed of your terminal. Terminal speed in baud rate. /TERMINAL_TYPE /TERMINAL_TYPE=type Optional. Default: type of physical terminal you are using. Terminal type. Use this qualifier if the remote host does not recognize your terminal. /TRUNCATE_USER_NAME /TRUNCATE_USER_NAME /NOTRUNCATE_USER_NAME Optional. Default: /NOTRUNCATE_USER_NAME. Abbreviates the user name sent to the remote host to eight characters (required for older UNIX hosts, which limit user names to eight characters). /USER_NAME /USER_NAME=remote_user_name -l remote_user_name (UNIX style, valid only on UNIX systems) Optional. Default: current name on local host, but in lowercase. Your user name on the remote host. Specify this qualifier if your user names on the remote host and local host are different. To send your user name in uppercase, use either of the following: o Specify /NOLOWERCASE. o Enclose the user name in quotation marks ( " " ). To send your user name in mixed case, enclose it in quotation marks ( " " ). 3 Examples 1.$ RLOGIN /USER_NAME="BlissTon" ROLLS An OpenVMS user logs in to account BlissTon on UNIX host rolls. The mixed-case remote user name is in quotation marks so RLOGIN does not send it all lowercase, which is the default. This example assumes the user has a proxy account on the remote host. 2.$ RLOGIN /NOLOWERCASE /USER_NAME=DAVE PLETHORA User DAVE starts an interactive login session with UNIX host plethora. Because this user has an uppercase user name, it is specified with the /NOLOWERCASE qualifier. This example assumes the user has a proxy account on the remote host. 3.$ RLOGIN /ESCAPE_CHARACTER="+" PJARO <Return> Password: (not echoed)<Return> Last login: Wed Aug 24 16:50:40 from world.wide.webber.com Digital UNIX System - 4: Fri Aug 26 11:02:20 EST 1996 You have mail. Fri Aug 26 11:02:20 EST 1996 pjaro> WHO <Return> black ttyp0 Aug 26 11:02 grades.philosophy.ucd.edu. bristow ttyp1 Aug 12 09:00 grades.biology.ucd.edu. cutler ttyp2 Aug 26 08:55 grades.math.ucd.edu. pjaro> PWD <Return> /usr/users/black pjaro> ls <Return> bin Sem1.paper Sem2.paper pjaro> +. (not echoed) %RSH-S-LCLCLOSED, Local connection closed $ OpenVMS user BLACK, with UNIX user name black, logs in to UNIX host pjaro and resets the escape character to a plus sign. By default, DIGITAL TCP/IP Services for OpenVMS passes the user name and commands to the remote host in lowercase. 4.$ RLOGIN FANTAC <Return> OpenVMS Version 7.1 - Unauthorized access is prohibited. Username: TDERR <Return> Password: (not echoed) <Return> . . . $ TDERR logs in to remote OpenVMS host FANTAC. 5.$ RLOGIN QANCE /DROP_TIMEOUT=45 %RLOGIN-E-INETERROR, Internet interface error -RLOGIN-I-INETCALL, setsockopt(TCP_DROP_IDLE) -SYSTEM-F-BADPARAM, bad parameter value $ The command fails because the /DROP_TIMEOUT and /PROBE_TIMEOUT qualifiers must both be set. 2 RSH_Command Sends a command to a remote host for execution, including a command that invokes a remote shell script or remote command procedure. Any command recognized by the remote host is valid. When using the RSH command, consider the following: o If you omit a command for remote execution, RSH initiates a remote login session (see the RLOGIN Command command). o If you specify the /PASSWORD qualifier, with or without a value, RSH executes the REXEC facility. DCL-Style Format RSH host [/EIGHTBIT | /ESCAPE_CHARACTER=character | /LOG_FILE=file | /[NO]LOWERCASE | /PASSWORD[=password] | /[NO]SYSERROR | /TERMINAL_SPEED=n | /TERMINAL_TYPE=type | /[NO]TRUNCATE_USER_NAME | /USER_NAME=remote_user_name] [ remote_command ] UNIX-Style Format rsh host [ -l remote_user_name ] [ remote_command ] This format is valid only on UNIX systems. 3 Parameters host Required. Remote host at which you want the command to execute. remote_command Optional. Default: none. Command you are sending to the remote host for execution. NOTE The remote_command must be the last item on the command line. 3 Qualifiers /EIGHTBIT Optional. Default: only 7-bit data is sent. Accepts 8-bit data from the terminal and sends it to the remote system. /ESCAPE_CHARACTER /ESCAPE_CHARACTER=character Optional. Default: ~ (tilde). New RLOGIN escape character. This character lets you exit the RLOGIN process without typing the remote host's typical logout sequence, for example, LOGOUT or Ctrl/D. Typing the escape character and a period (.) breaks the connection with the remote host, for example: remote> ~. (not echoed) %RSH-S-LCLCLOSED, Local connection closed local_vms> /LOG_FILE /LOG_FILE=file Optional. Default: no logging. Logs a copy of the output to the specified file. Output continues to be directed to SYS$OUTPUT while it is being recorded in the log file. Not valid with /SYSERROR. /LOWERCASE /LOWERCASE /NOLOWERCASE Optional. Default: /LOWERCASE. Sends your local user name to the remote host in lowercase. To send your user name in uppercase, use either of the following ways: o Specify /NOLOWERCASE. o Enclose the user name in quotation marks ( " " ). (See /USER_ NAME.) To send your user name in mixed case, enclose it in quotation marks ( " " ). /PASSWORD /PASSWORD[=password] Optional. Your password on the remote host. Invokes the local REXEC facility that directs your RSH command to the REXEC server on the remote host. This server does authentication checking using the user name and password that you specified on the RSH command line. o Enclose the password in quotation marks ( " " ) if it is lowercase or mixed case. o If you omit password, RSH prompts you for one. o Do not use this qualifier if you want to initiate an RLOGIN session. /SYSERROR /SYSERROR /NOSYSERROR Optional. Default: /NOSYSERROR. Directs diagnostics to SYS$ERROR and output to SYS$OUTPUT. When SYS$ERROR and SYS$OUTPUT both output to the same terminal, the output might be garbled. /NOSYSERROR directs output only to SYS$OUTPUT. /TERMINAL_SPEED /TERMINAL_SPEED=n Optional. Default: your terminal's current speed. Terminal speed passed to the remote host during an RLOGIN session. /TERMINAL_TYPE /TERMINAL_TYPE=type Optional. Default: your terminal's current type. Terminal type passed to the remote host during an RLOGIN session. /TRUNCATE_USER_NAME /TRUNCATE_USER_NAME /NOTRUNCATE_USER_NAME Optional. Default: /NOTRUNCATE_USER_NAME. Abbreviates the user name sent to the remote host to eight characters (required for older UNIX hosts, which limit user names to eight characters). /USER_NAME /USER_NAME=remote_user_name -l remote_user_name (UNIX style, valid only on UNIX systems) Optional. Default: same name on local host, but in lowercase. Your user name on the remote host. Specify this qualifier if your user names on the remote host and local host are different. To send your user name in uppercase, use either of the following ways: o Specify /NOLOWERCASE. o Enclose the user name in quotation marks ( " " ). To send your user name in mixed case, enclose it in quotation marks ( " " ). 3 Examples 1.$ RSH HENCE MAN CP cp(1) Name cp - copy file data Syntax cp [ -f ] [ -i ] [ -p ] file1 file2 . . . See Also cat(1), pr(1), mv(1) $ A user sends the man cp command to UNIX host hence for execution. 2.$ RSH /USER_NAME=ROGERS DELPHI LS OpenVMS user PHILIPS issues the ls command for execution at remote UNIX host delphi. PHILIPS is accessing an account called rogers. 3.$ RSH /PASSWORD=BLOOMER AVOC8N DIRECTORY OpenVMS user PANTO sends the DIRECTORY command to remote OpenVMS host AVOC8N. The remote directory listing is of PANTO's home directory. RSH /PASSWORD invokes REXEC, which authenticates PANTO's remote password. 4.$ RSH /PASSWORD MAGIC CAT BUZZ.TXT REXEC password: (not echoed)<Return> A user sends the cat command to host magic. /PASSWORD invokes REXEC, which requires a password. Because the password was omitted from the command line, REXEC prompts the user for it. 2 TELNET_Command Starts a TELNET session and does one of the following: o Displays the TELNET prompt. o Establishes a connection to a remote host. o Establishes a connection to a remote host and runs TN3270. For help with individual TELNET commands, type: $ TELNET TELNET> HELP DCL-Style Format TELNET [ host ] [/CREATE_SESSION | /DELETE_SESSION | /LOG_FILE=file | /NOINTERACTIVE | /PORT=n | /TERMINAL_TYPE=type] [ port ] [unit ] UNIX-Style Format telnet [ host ] 3 Parameters host Required with the /CREATE_SESSION qualifier; optional in all other cases. Default: none. Remote host to which you want to connect. Specify one of the following: o Host name o IP address port Required with the /CREATE_SESSION qualifier; ignored in all other cases. Default: none. Specifies the remote port to which you want to connect the pseudodevice. unit Required with the /DELETE_SESSION qualifier; optional with the /CREATE_SESSION qualifier; ignored in all other cases. Default: 0. With the /CREATE_SESSION qualifier, specifies the unit number you want associated with the network terminal. The default of 0 allows the TELNET software to select the next available unit number. With the /DELETE_SESSION qualifier, specifies the unit number of the network terminal you wish to delete. 3 Qualifiers /CREATE_SESSION Optional. Default: None Specifies that TELNET should create a pseudodevice (network terminal) and connect it to the specified remote port. For additional information, see the CREATE_SESSION command. /DELETE_SESSION Optional. Default: None Specifies that TELNET should delete the specified pseudodevice (network terminal). For additional information, see the DELETE_ SESSION command. /LOG_FILE /LOG_FILE=file Optional. Default: no logging. An optional log file to contain all session output. Using this option does not affect your terminal output. You cannot use this option for TN3270 sessions. /NOINTERACTIVE Optional. Default: TELNET command mode. Disables the capability of using the escape character to leave a session and return to the TELNET prompt. This option is useful when the TELNET command is referenced in a command procedure in a captive account. /PORT /PORT=n Optional. Default: 23. Remote port to which you want your TELNET process to connect. Specify only if you are connecting to a host that does not use the standard TELNET port. /TERMINAL_TYPE /TERMINAL_TYPE=type Optional. Default: none. The IBM or DIGITAL terminal to emulate. Type the full specification for one of these: o IBM-3278-2 o IBM-3278-3 o IBM-3278-4 o IBM-3278-5 o VT100 o VT200 o VT300 o VT400 o VT500 3 Examples 1.$ TELNET TELNET> ENABLE DEBUG TELNET> SET TERMINAL /DEVICE=VT300 Terminal type is set to VT300 TELNET> CONNECT DEBTS o Starts TELNET. o Customizes the environment. o Establishes a connection to host debts and sets up the terminal type as VT300. 2.$ TELNET MYCOM /TERMINAL_TYPE=IBM-3278-2 Establishes a TELNET connection to remote host MYCOM and runs TN3270. 3.$ TELNET 130.180.5.5 Establishes a TELNET connection to the host at IP address 130.180.5.5. 4.$ TELNET UCOM 31 Establishes a TELNET connection to remote host ucom at port 31. 2 TN3270_Command Starts a TELNET session that runs TN3270 and does one of the following: o Displays the TELNET prompt. o Establishes a connection to a remote host. For help with individual TELNET commands, type: $ TN3270 TELNET> HELP Format TN3270 [ host ] [/CHARACTER_SET=file | /KEY_DEFINITIONS=file | /NATIONAL_CHARACTERS=char_set | /NOINTERACTIVE | /PORT=n | /PRINTER=file | /STATUS=state | /TERMINAL_TYPE=IBM-3278-n] 3 Parameters host Optional. Remote host to which you want to connect. Specify one: o Host name o IP address 3 Qualifiers /CHARACTER_SET /CHARACTER_SET=file Optional. Default: ORIGINAL. File with the EBCDIC-to-DMCS (DIGITAL Multinational Character Set) and the DMCS-to-EBCDIC translation tables. If you omit this qualifier, TN3270: o Uses the translation table named by the default file SYS$LIBRARY:UCXTEDEF.TBL, if your system manager has created it. o Defaults to its own translation table, if UCXTEDEF.TBL does not exist. The default table maps the US EBCDIC set to the equivalent DMCS characters. If none of these translation tables meets your needs, the system manager can generate a new translation table. (See the DIGITAL TCP/IP Services for OpenVMS Management manual for information about the EBCDIC / DMCS translation tables.) NOTE To reset the default, do not abbreviate ORIGINAL. /KEY_DEFINITIONS /KEY_DEFINITIONS=file Optional. Default: default keyboard layout. Keyboard definition file you created to redefine how the TN3270 key functions correspond to your keyboard layout. This file holds the definitions for alternative keyboard mapping. /NATIONAL_CHARACTERS /NATIONAL_CHARACTERS=character_set Optional. Defaults: For 8-bit terminals: MULTINATIONAL For 7-bit terminals: US_ASCII. National Replacement Character Set (NRCS) for which your DIGITAL terminal is configured. Specify one of the following: Canadian MULTINATIONAL Dutch Norwegian Finnish Spanish French Swedish German Swiss Italian UK_ASCII Japanese US_ASCII /NOINTERACTIVE Optional. Default: TELNET command mode. Disables the capability of using the escape character to leave a session and return to the TN3270 prompt. This option is useful when the TN3270 command is referenced in a command procedure in a captive account. /PORT /PORT=n Optional. Default: 23. Remote port to which you want your TELNET/3TN3270 process to connect. Specify only if you are connecting to a host that does not use the standard TELNET port. /PRINTER /PRINTER=file Optional. Default: TN3270PRINT.LIS. File that records your screen's contents when you use the PRINT function. Directs printer output to either a file or a spooled printer (not a physical printer or terminal). /STATUS /STATUS=state Optional. Default: AUTOMATIC. Determines how the status line operates during your session. Specify one of the following: AUTOMATIC Status line is displayed. The status line is disabled automatically if the remote host writes data to the area under the status line or you type in that space. The status line is restored automatically when the data is erased. ON Status line is always displayed. OFF Status line is not displayed. To toggle between ON and OFF, invoke the STATUS function. /TERMINAL_TYPE /TERMINAL_TYPE=IBM-3278-n Optional. Default: IBM-3278-2. IBM terminal to emulate. Type the full specification for one of the following: o IBM-3278-2 o IBM-3278-3 o IBM-3278-4 o IBM-3278-5 3 Examples 1.$ TN3270 MYCOM Establishes a TELNET connection to remote host MYCOM. By default, the physical terminal functions as an IBM-3278-2 model terminal. 2.$ TN3270 130.180.5.5 /TERMINAL_TYPE=IBM-3278-3 - _$ /KEY_DEFINITIONS=MY_NUMPAD.FIL Establishes a TELNET connection to the host at IP address 130.180.5.5. The terminal functions as if it were an IBM-3278-3 model terminal, and it uses the customized keyboard definition file MY_NUMPAD.FIL. 3.$ TN3270 UCOM 31 /TERMINAL_TYPE=IBM-3278-5 /PRINTER=LOG Establishes a TELNET connection to remote host ucom: o The connection is at port 31 on ucom. o The terminal is functioning as if it were an IBM-3278-5 model terminal. o During the session at ucom, using the PRINT function records the screen's contents in a file named LOG.LIS.

© 1997- Marc Vos (and others) Contact Me