DIGITAL TCP/IP Services for OpenVMS
User's Guide

While trying to connect and log into remote UNIX host bygnet, user UserGent typed "dom" by mistake. Although host bygnet completes the connection, bygnet rejects the login request. The LOGIN command successfully completes the login to the remote host.

The PUT command does the following:

• Copies local files to a remote host.
• Copies files to a DECnet node.
• Prints one local file at a printer attached to a remote host.

File names are copied in lowercase without version numbers.

To use this command, you must have an FTP session with a remote host.

DCL-Style Format

PUT[/CONFIRM | /CONVERT | /FDL | /RAW] local_file [remote_file | printer]

UNIX-Style Formats

put local_file [remote_file]

send local_file [remote_file]

mput local_files

PARAMETERS

local_file

Required.

Name of the local file to copy.

• To specify multiple files, separate the names with commas or plus signs.
• To use wildcards, enable parsing (see ENABLE PARSE command).
  • put file_name.ext --- Copies the latest version
  • mput file_name.ext;* --- Copies all versions
• To copy a file to a remote DECnet node, use the full specification:
  node name, device, directory, file name.

remote_file

Optional. Default: same name, same case, no version number.

Name of the new file on the remote host. You cannot use wildcards.

printer

Optional.

Sends a local file to a remote printer.

Specify the actual name of the printer, not the queue name or logical name.

QUALIFIERS

/CONFIRM

Optional. Default: immediate execution. The /CONFIRM qualifier must follow immediately after the PUT command without a space.

Asks you for confirmation before executing the copy operation.

/CONVERT

Optional.

Translates the internal file-formatting characters of Variable Forms Control (VFC) files. The /CONVERT qualifier must follow immediately after the PUT command without a space.

/FDL

Optional. Default: no secondary file created. The /FDL qualifier must follow immediately after the PUT command without a space.

Creates a secondary file with the file's OpenVMS record attributes. The SET TYPE command determines the type of file:

• Specifying ASCII results in a sequential file with variable records. Select this type when transferring ASCII text files.
• Specifying IMAGE results in a sequential file with fixed records of 512 bytes. Select this type when transferring non-ASCII files such as executable image files.

/RAW

Optional.

Maintains block mode of files regardless of the UCX$FTP_RAW_BINARY logical name definition. The /RAW qualifier must follow immediately after the PUT command without a space.

Examples

FTP> PUT SALES.LIS;* 
200 PORT command successful 
150 Opening data connection for sales.lis.2 (16.20.208.53,1028) 
226 Transfer complete 
local: DISK3$:[TRANS]SALES.LIS;2  remote:  sales.lis.2 
3634 bytes sent in 00:00:00.01 seconds (394.31 Kbytes/s) 
200 PORT command successful 
150 Opening data connection for sales.lis.1 (16.20.208.53,1029) 
226 Transfer complete 
local: DISK3$:[TRANS]SALES.LIS;1  remote:  sales.lis.1 
3634 bytes sent in 00:00:00:01 seconds (394.31 Kbytes/s) 
FTP>
 

Copies all versions of the local file SALES.LIS to the remote host.

• File names are copied in lowercase.
• OpenVMS file version numbers become the last element of the copied files.
• Semicolons are converted to periods.
• If the Store Unique feature is toggled on (sunique), then when you copy a file to an OpenVMS host, the host FTP server gives the file a new, unique version number. When you specify the version number of a file to be copied (PUT) to a remote UNIX host, the file retains the version number on the remote host, with the semicolon (;) replaced by a period (.). The UNIX host adds another version number to the file name as well. For example, if you PUT file BASES.TMP;2 to a UNIX host, the file name on the UNIX host will be bases.tmp.2.1.

FTP> PUT WSTRN.TXT LPA_CENTER: 

Prints a copy of local file WSTRN.TXT at remote printer LPA_CENTER:.

FTP> PUT/FDL STAT.BCK CYGNET.BCK 
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 
21700 bytes sent in 00:00:00.03 seconds (662.23 Kbytes/s) 
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> 

Copies the local file STAT.BCK to a UNIX host, giving the copy the name cygnet.bck. Also creates a secondary file with the RMS record attributes of file STAT.BCK.

Sends your input directly to the remote host. Lets you use FTP commands that are implemented by the remote host but not known to the local host.

To use the QUOTE command, you must have an FTP session with a remote host. The QUOTE command is not valid for file transfer.

For a list of commands implemented by the remote host, issue:

FTP> HELP/REMOTE 

DCL-Style Format

QUOTE command_line

UNIX-Style Format

quote command_line

PARAMETERS

command_line

Required.

Remote command you want to execute.

Example

FTP> QUOTE CDUP 
250 CWD command successful. 
FTP>

FTP sends the cdup command to the UNIX host to change the remote directory up one level.

Renames a remote file. To use this command, you must have an FTP session with a remote host.

DCL-Style Format

RENAME old_name new_name

UNIX-Style Format

rename old_name new_name

PARAMETERS

old_name

Required.

File name on the remote host to rename.

new_name

Required.

New name for the remote file.

Example

FTP> RENAME STUDENTS.LIS TEST.STUDENTS.LIS
350 File exists, ready for destination name
250 RNTO command successful.

FTP renames the file students.lis to test.students.lis.

Sets your default directory on either the remote host or the local host. To set the default directory on a remote host, you must have an FTP session with a remote host.

DCL-Style Format

SET DEFAULT [ /LOCAL ] directory

UNIX-Style Formats

cd directory

lcd directory

PARAMETERS

directory

Required.

Name of the directory to which to change the default.

QUALIFIERS

/LOCAL

Optional. Default: remote.

Changes the working directory on the local host.

Examples

FTP> SET DEFAULT "/USR/USERS/ROLLINGS"
250 CWD command successful.

Changes the remote working directory to /usr/users/rollings.

FTP> SET DEFAULT ~
250 CWD command successful.
250 New default directory is /USR/USERS
 

Changes the remote working directory back to the default login directory.

FTP> SET DEFAULT /LOCAL USER$1:[PRESS.CHECK] 
Local Directory now USER$1:[PRESS.CHECK]
 

Changes your local working directory to USER$1:[PRESS.CHECK].

Sets maximum tolerance level for errors:

• ERROR --- FTP tolerates errors and warnings, and will not exit when running in batch mode.
• SUCCESS --- The default; FTP does not tolerate errors and will exit when running in batch mode.
• WARNING --- FTP tolerates warnings and will not exit when running in batch mode.

Format

SET ERROR_LEVEL error_level

PARAMETERS

error_level

Required.

Severity of errors tolerated. Specify ERROR, SUCCESS, or WARNING. The default is SUCCESS.

Example

FTP> SET ERROR_LEVEL ERROR 
200 Error level set to ERROR

Sets the error level tolerance to ERROR.

Defines the data representation type:

• ASCII --- Appropriate for text files (default).
• IMAGE --- Appropriate for transferring binary files, such as executable images.

DCL-Style Format

SET TYPE type

UNIX-Style Format

type type

PARAMETERS

type

Required.

Data representation type. Specify ASCII or IMAGE. If you do not use the SET TYPE command, the default is SET TYPE ASCII.

Example

FTP> SET TYPE IMAGE 
200 Type set to I

Sets the data representation type to IMAGE for files you transfer during the current FTP session.

Displays the name of the working directory on the remote host or the local host. To use the SHOW DEFAULT command to display the working directory on the remote host, you must have an FTP session with a remote host.

DCL-Style Format

SHOW DEFAULT [/LOCAL]

UNIX-Style Format

pwd

QUALIFIERS

/LOCAL

Optional. Default: remote directory.

Displays the local working directory.

Examples

FTP> SHOW DEFAULT 
257 "/usr/staff/hurry/items" is current directory.

Displays the name of the working directory on the connected remote host.

FTP> SHOW DEFAULT /LOCAL 
Local directory is WORKS$:[CROWE].

Displays the name of the working directory on the local host.

Displays the current FTP parameter settings and, if you have an open connection, the name of the connected host and parameter settings relative to the connection.

DCL-Style Format

SHOW STATUS

UNIX-Style Format

status

Examples

FTP> SHOW STATUS 
211-FTP Server Status. 
211-SITE set to +VMS+. 
211-TYPE set to ASCII. 
211-STRU set to FILE. 
211-MODE set to STREAM. 
211 Multiline responses are enabled 
Connected to: HANKS.ABC.UCB.EDU 
VMS Plus mode enabled 
Mode = stream , Type = ascii, Form = non_print, Structure = file 
Error level is SUCCESS 
Reply display is on 
Parsing is on 
Prompting is off 
Port command is on 
Case: Filenames will be transferred in lowercase

Displays the status of the connection with remote OpenVMS host HANKS. By default, FTP sets VMS Plus Mode for rapid file transfers between the two OpenVMS systems.

FTP> SHOW STATUS 
502 STAT command not implemented. 
Connected to: EAGLE.STORE1.EQUIP_PLUS.COM 
VMS Plus mode disabled 
Mode = stream , Type = ascii, Form = non_print, Structure = file 

Displays the current FTP parameters, which control data transfers with the connected UNIX host, eagle.

Because the remote host cannot return status for the session, it displays the message "502 STAT command not implemented."

Suspends your current FTP session and runs the DCL command that you type.

DCL-Style Format

SPAWN [command]

UNIX-Style Format

! [command]

Example

FTP> SPAWN SHOW DEFAULT 
SYS$LOGIN_DEVICE:[PERCY.DISTR]
 

Interrupts your FTP process to display your default directory.

Displays the contents of a file onto your current output device.

DCL-Style Format

VIEW[/PAGE | /NOPAGE] filespec

UNIX-Style Format

view /filespec

PARAMETERS

filespec

Required.

Specifies the file to be displayed. Wildcard characters (*, %) are not allowed in place of the directory name, file name, file type, or file version number field.

QUALIFIERS

/NOPAGE

Optional.

Displays the entire file by scrolling through its contents. This is the default. The /NOPAGE qualifier must follow immediately after the VIEW command without a space.

/PAGE

Optional.

Displays one screen at a time until the end of file (EOF) is reached. You can terminate the display at any time by pressing Ctrl/Z. The /PAGE qualifier must follow immediately after the VIEW command without a space.

Examples

FTP> VIEW FUNDING.TXT 

Scrolls through the contents of the FUNDING.TXT file, in the current working directory, and displays the contents on the current output device.

FTP> VIEW/PAGE FUNDING.TXT

Displays the contents of the FUNDING.TXT file, one screen at a time, on the current output device.

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 into 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.

What You Can Do

The following table lists the Remote (R) commands and services, the functions you can perform, and the sections that explain how to use them.

Capability	Section
Remote copy (RCP command): Copy a file between the local host and a remote internet host Copy a file between two remote internet hosts	4.4
Remote login (RLOGIN): Log into an account on a remote host	4.5
Remote command or shell execution (RSH): Send a command, shell script, or command procedure to a remote host for execution	4.6
Remote command or shell execution with authentication (REXEC facility (using RSH/PASSWORD)): Using your user name and password for authentication, execute a command, shell script, or command procedure at a remote host	4.7

What You Need

To use the Remote (R) commands, you need access to an account on the remote host, which is granted by either of the following:

• An entry in the remote host's authentication files
• Knowledge of the password for the remote account

Command Summary

Table 4-1 summarizes the Remote (R) commands (for complete command descriptions, see Section 4.8).

Table 4-1 Remote (R) Commands: Summary

Function/Command	Description
RCP	Copies files between the local host and a remote host or between two remote hosts. Authentication is performed on the remote host or hosts using the user name supplied by RCP.
RLOGIN	Connects to the remote host, which starts an interactive login session. Authentication is performed on the remote host using the user name supplied by RLOGIN.
RSH	Connects to the remote host, which executes the command you specified. Authentication is performed on the remote host using the user name supplied to RSH.
RSH/PASSWORD	Uses the REXEC facility to connect to the remote host, which executes the command you specified. Authentication is performed on the remote host using the user name and password supplied by RSH.

4.1 Providing Account and Password Information

To use a remote command on your OpenVMS system, remote hosts need to know the user name that you want to use on the host. You can provide the user name in either of two ways:

• 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.
• Using the /USER_NAME qualifier: Specify the user name with the /USER_NAME qualifier if your user name is:
  • Different on the remote host
  • In mixed case (only for remote hosts supporting case-sensitive user names)
  • The same on the remote host but you want to access the remote host using another user name
  
  By default, the R commands send all user names in lowercase letters. If you access a host that supports case-sensitive user names, and the user name you specify has uppercase letters, you may use the /NOLOWERCASE qualifier to maintain these letters as uppercase, or you can specify the /USER_NAME qualifier with the user name in quotes.

The remote host must also know your password or know you as a trusted user on your local system:

• 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)
    

• Accessing remote hosts as a trusted user:
  Most systems use certain authentication files or proxy accounts that allow trusted users on trusted hosts to access the system by specifying only the user name they want to use. To access a host without specifying the corresponding password, your originating host and user name must have an entry in these authentication files.
  The authentication file entries contain your originating user name. The R commands convert your originating user name to lowercase unless you use the /NOLOWERCASE qualifier. You may have to contact the system manager 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 recognize the /PASSWORD qualifier. If you are a trusted user, you are automatically logged into the remote system. If you are not a trusted user, REXEC prompts you to enter a user name and password on the remote system.

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:

• User names and passwords are mixed case.
• Passwords are lowercase.
• User names are uppercase, unless you use the /NOLOWERCASE qualifier.

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 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] 
   

You can specify R command qualifiers in either of two ways:

• Type the qualifiers on the command line.

  $ RCP /LOG TRANQUIL:VULTURES [] 
  $ RSH /EIGHTBIT /ESCAPE_CHAR="+" /TRUNCATE HERON CAT -N STREAMS 
  

• 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 
  $ ! 
  

You can obtain online help for the R commands by typing the following command:

$ HELP TCP_IP_SERVICES R_COMMANDS

You can also obtain information for a specific R command by typing one of the following commands:

$ HELP TCP_IP_SERVICES RCP_COMMAND
$ HELP TCP_IP_SERVICES RLOGIN_COMMAND
$ HELP TCP_IP_SERVICES RSH_COMMAND
$ HELP TCP_IP_SERVICES REXEC_COMMAND

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:

• 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.
• 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. To determine the best file transfer service to use for your needs, see Section 1.1.1. For more information about FTP, see Chapter 3.

4.4.1 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]*" 
   

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. (See Section 4.1.)