DIGITAL TCP/IP Services for OpenVMS
User's Guide


Previous | Contents

In the following example, UNIX path names need quotation marks around them:

FTP> PUT/FDL STAT.BCK "/USERS/SANDERS/CYGNET.BCK" 
. 
. 
. 
FTP> 

3.1.3 Wildcards

You can use wildcards in the following FTP commands: DELETE, DIRECTORY, GET, and PUT.

The wildcard characters recognized by FTP are:

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.

3.1.4 Qualifiers

The following FTP commands require that you specify qualifiers immediately following the command, with no space between command and qualifier:

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. (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. (2) The /CONFIRM qualifier follows the GET command, but with a space between. An error message indicates too many parameters have been entered.
  3. (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.2 Obtaining Online Help

You can obtain online help for the FTP utility and FTP commands by typing either of the following commands:

$ HELP TCP_IP_SERVICES FILE_TRANSFER
$ HELP TCP_IP_SERVICES FTP_COMMAND

You can also enter the HELP command at the FTP prompt:

FTP> HELP

To obtain information about a specific command, specify the command as in the following example:

FTP> HELP command

3.3 Customizing FTP Command Processing

You can modify the way FTP transfers files, depending on:

A few of the FTP commands that control FTP command processing are:

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.4 Starting FTP Sessions

You can start an FTP session in any of the following ways:

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.

3.4.1 Making a Remote Connection

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:

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>

3.4.2 Anonymous User Access (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:

With Anonymous FTP, you can:

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.5 Exiting FTP

You can end an FTP session and return to the DCL prompt with any of the following commands: EXIT, quit, or Ctrl/Z. The following examples close the connection with the remote host, if one is open, and exit FTP.

FTP> EXIT
221 Goodbye. 
$
FTP> QUIT
221 Goodbye. 
$

If however, you want to close a connection while remaining at the FTP prompt, use the DISCONNECT or close command.

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.6 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 Section 3.6.1), and you can use command procedures to customize the FTP environment (see Section 3.6.2).

3.6.1 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 
$ 

In the next example, command procedure FTP_PASS_PARAMETER.COM accepts parameters and writes and executes a temporary command 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 
$

3.6.2 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:

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.7 Displaying and Changing the 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.8 Creating and Deleting Directories

To create a directory on a connected remote host, use the CREATE/DIRECTORY command. The following command example creates a subdirectory .LOCAL_ACCTS in the current working directory on the connected remote OpenVMS host.

FTP> CREATE/DIRECTORY [.LOCAL_ACCTS]

To delete a directory, use the DELETE/DIRECTORY command as in the following example. The command deletes the directory created in the preceding example.

FTP> DELETE/DIRECTORY LOCAL_ACCTS.DIR;*

3.9 Viewing Directories on the Remote Host

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.10 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.11 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.12 Viewing the Contents of a File

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.13 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. For information on using these commands to copy files to and from a remote DECnet host, see Section 3.14. 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.

3.13.1 Using the GET Command to Copy Remote Files to the Local Host

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

Figure 3-1 The GET Command



As shown in Figure 3-1:

  1. The user at the local host named Host A, and connected through FTP to the remote UNIX host named hostx, issues a GET command.
  2. The FTP client software on Host A sends a request to the remote FTP server on hostx to send the requested file.
  3. The FTP PORT command successful message and the following line indicate the remote server is opening a data connection to send the requested file.
  4. The remote FTP server sends the requested file, acct.pay, to Host A.
  5. (5) A message indicates the file transfer was complete and provides additional information about the transfer.

For more information on the GET command, see Section 3.17.

3.13.2 Using the PUT Command to Copy Local Files to the Remote Host

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. For more information on the /FDL qualifier, see Section 3.13.6.

FTP> PUT ACCTS.LIS

Figure 3-2 The PUT Command



As shown in Figure 3-2,

  1. The user at local host Host A, and connected through FTP to the remote UNIX host hostx, issues a PUT command.
  2. The FTP client software on Host A requests the FTP server on hostx to receive the specified file (accts.lis).
  3. The remote FTP server establishes a data connection with the local host.
  4. The PORT command successful message and the following line indicate the remote server will receive the file.
  5. The client sends the requested file, accts.lis, to hostx.
  6. A message indicates the file transfer is complete and provides additional information about the transfer.

For more information on the PUT command, see Section 3.17.

3.13.3 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:

3.13.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:
FTP Command Store Unique On Store Unique Off
From OpenVMS to UNIX
FTP> PUT text.txt text.txt text.txt
FTP> PUT text.txt;1 text.txt.1 text.txt.1.1
FTP> PUT text.txt;* text.txt.1
text.txt.2
text.txt.3
text.txt.1.1
text.txt.2.1
text.txt.3.1
From UNIX to OpenVMS
ftp> PUT text.txt text.txt$01 text.txt;1

3.13.5 Transfers Between OpenVMS Hosts: 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.

3.13.6 Preserving OpenVMS 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:

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>
    

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

3.13.8 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.14 Using FTP with DECnet

To copy files from and to a DECnet node, use the standard GET and PUT commands as described in the following paragraphs.


Previous | Next | Contents