DIGITAL TCP/IP Services for OpenVMS
User's Guide


Previous Contents Index

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

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

2.9 Renaming and Deleting Files

To change the name of a remote file, use the RENAME command. The following command renames file YEAR.DAT to YEAR96.DAT on the connected remote host:


FTP> RENAME YEAR.DAT YEAR96.DAT

To remove a remote file, use the DELETE command. The following command deletes all versions of file YEAR.DAT on the connected remote VMS host:


FTP> DELETE YEAR.DAT;*

2.10 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 the file is not in your current working directory, include the directory name in the file specification.

The following example shows how to display the contents of file ENG.DIS located in the remote working directory:


FTP> VIEW/PAGE ENG.DIS
usrm::"khuna@jnet.com" 
pobox::bearse 
yield::timms 
usrm::"lerry@muster.cudenver.edu" 
sam 
nm%us1rmc::"ldutton@TopCom.com" 
   .
   .
   .

2.11 Appending Files

The FTP APPEND command allows you to concatenate a local file to a file on a connected remote host. The following command appends local file JUL_DEC.DAT to file YEAR.DAT on remote host KALI. (A connection has already been established to the remote host.)


FTP> APPEND JUL_DEC.DAT YEAR.DAT
200 PORT command successful 
150 Opening data connection for year.dat. (130.180.4.8,1108) 
226 Append transfer complete 
local:large.txt   remote:remote.dat 
15596 bytes sent in 00:00:00.10 seconds (152.30 Kbytes/s) 

2.12 Suspending FTP to Return to the Local DCL Prompt

While using FTP, you can:

2.13 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).

2.14 Command Procedures

You can use either OpenVMS or UNIX command syntax in DCL command procedures that use FTP. You can use command procedures to invoke FTP tasks, connecting to a remote host and performing assorted file operations with the remote host (See Section 2.14.1), and you can use command procedures to customize the FTP environment (See Section 2.14.2).

2.14.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 
 
$ EXIT 
$

2.14.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 enter individual FTP commands, and run automatically when you invoke FTP.

Initialization command files:

FTP uses the following search method to locate an intialization file:

  1. FTP searches for a file specified by the logical TCPIP$FTPINIT.
  2. If not found, FTP then searches for SYS$LOGIN:TCPIP$FTPINIT.INI.
  3. If not found, FTP then searches for the file specified by the logical FTPINIT (provided for backward compatibility).
  4. If not found, FTP then searches for SYS$LOGIN:FTPINIT.INI (provided for backward compatibility).
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] 

2.14.3 Setting Error Level

When you use FTP interactively, you decide what actions to take when an error or warning is generated. In batch mode, however, any error other than SUCCESS causes the batch process to exit by default.

The command procedure in the following example calls a file that does not exist, which generates an error and causes the procedure to exit:


$ @TEST_FTP 
220 rainbw FTP Server (Version 5.60) ready. 
Connected to rainbw.tcp.klg.dec.com. 
331 Username PETERS requires a Password 
230 User logged in. 
200 TYPE set to IMAGE. 
200 PORT command successful. 
550-Failed to open WORK7$:[PETERS]TMP101.TMP; for input. 
550 file not found 
221 Goodbye. 

Internally, the 3-digit FTP Protocol reply codes listed above are converted to one of the following OpenVMS System Messages:
FTP Protocol
Reply Code
OpenVMS
System Message
Explanation
1XX %TCPIP-S-FTP_PRELIM Success
2XX %TCPIP-S-FTP_COMPLETE Success
3XX %TCPIP-S-FTP_CONTINUE Success
4XX %TCPIP-W-FTP_TRANSIENT Warning
5XX %TCPIP-E-FTP_ERROR Error

When a command is executed, the mainline checks the return status. If you are in batch mode, then the value of the error level determines whether FTP will continue with each of the above codes.

To change the error level, you enter the following command where x is SUCCESS, WARNING, or ERROR:


FTP> SET ERROR_LEVEL x 

FATAL errors will always cause FTP to exit.

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

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 

2.16 Command Descriptions

To start FTP, enter the FTP command at the DCL prompt.

To use FTP commands, type them at the FTP> prompt.

This section provides complete descriptions of each FTP command, listed alphabetically. The related ENABLE and DISABLE commands are presented together (See the description for ENABLE).


APPEND

Appends a local file to a remote file. The remote file can reside on any system that supports FTP. To use this command, you must have an FTP session with a remote host.

DCL-Style Format

APPEND local_file [ remote_file ]


UNIX Style Format

append local_file [ remote_file ]

restrictions

No wildcards.

Parameters

local_file

Required.

Name of the local OpenVMS file.

remote_file

Optional.

Name of the remote file, either UNIX or OpenVMS.


Example


FTP> APPEND LARGE.TXT CHRONOS 
200 PORT command successful. 
150 Opening ASCII mode data connection for CHRONOS. (130.180.4.8,1108) 
226 Transfer complete 
local:work1:[samson]large.txt   remote:CHRONOS 
15596 bytes sent in 00:00:00.10 seconds (152.30 Kbytes/s)  
      

Appends local file LARGE.TXT to UNIX file chronos.


CONNECT

Establishes an FTP connection to a remote host. The remote host can be any operating system that supports FTP.

DCL-Style Format

CONNECT remote_host [ port ]


UNIX Style Format

open remote_host [ port ]


Parameters

remote_host

Required.

Remote host to which you want to connect.

port

Optional. Default: 21.

FTP port on the remote host.


Example


FTP> CONNECT RETAIL [Return] 
220 retail.good_co.com FTP Server (Digital UNIX Version 5.60) ready. 
Connected to retail. 
Name (retail:dave): [Return] 
331 Password required for dave 
Password:                  (password not echoed)[Return]
230 User dave logged in. 
FTP>    
      

User dave connects to UNIX host retail.


CREATE

Creates a directory on the remote host. The remote directory can be on any operating system that supports FTP. To use this command, you must have an FTP session with a remote host.

DCL-Style Format

CREATE/DIRECTORY remote_directory


UNIX Style Format

mkdir remote/path


Parameters

remote_directory

remote/path

Required.

Name for the created directory.


Qualifiers

/DIRECTORY

The /DIRECTORY qualifier must immediately follow the DELETE command without a space.

Creates a new directory or subdirectory. Must have write access to the lowest level directory under which the new directory will be created.


Examples

#1

FTP> CREATE/DIRECTORY TERM 
257 MKD command successful. 
      

In this example:

#2

FTP> CREATE/DIRECTORY [.TRANSFERS] 
257 MKD command successful.   
      

In this example:


DELETE

Deletes either UNIX or OpenVMS remote files. To use this command, you must have an FTP session with a remote host.

Note

Use caution with the mdelete command. The FTP DIRECTORY command does not list hidden files (files that start with a period). Using the mdelete command with any wildcard deletes hidden files, which you might need.

DCL-Style Format

DELETE remote_files

DELETE/DIRECTORY remote_directory


UNIX Style Formats

delete remote_file

mdelete remote_files

rmdir remote_directory


Parameters

remote_file

remote_files

remote_directory

Required.

File, files, or directory to delete.


Qualifiers

/DIRECTORY

Optional. The /DIRECTORY qualifier must follow immediately after the DELETE command without a space.

Deletes an empty directory. To delete a directory that is not empty, you must first delete the contents of the directory.


Examples

#1

FTP> DELETE [MAIN.BRANCH]*.*;* 
250 DELE of [MAIN.BRANCH]*.*;* successful.
      

Deletes all files in the remote OpenVMS directory [MAIN.BRANCH].

#2

FTP> DELETE/DIRECTORY BRANCH.DIR;1
250 RMD command successful.
      

Deletes the directory [MAIN.BRANCH].

#3

FTP> DELETE "/USERS/VENTURE/CARTON" 
250 DELE command successful.
      

Deletes UNIX file with path name /users/venture/carton.

#4

FTP> mdelete /bids/west/january97/c* 
250 DELE command successful.
250 DELE command successful.
250 DELE command successful.
 
      

Deletes three UNIX files starting with the letter "c" from directory /bids/west/january97. Note that the messages generated depend on the server. For example, for an OpenVMS server, messages would specify the names of the files deleted.


DIRECTORY

Lists the names of remote files and other information about them. The remote files can be on any FTP server. To use this command, you must have an FTP session with a remote host.

The DCL-style DIRECTORY command supports the redirecting of output to a file.


DCL-Style Format

DIRECTORY [ /BRIEF | /OUT=output_file ] [ remote_directory ]


UNIX Style Format

ls [ /remote/path ]


Parameters

remote_directory

/remote/path

Optional. Default: default directory.

Directory with the file names you want to list. Wildcards and multiple directories are valid.


Qualifiers

/BRIEF

Optional. Default: full display.

Produces output similar to the UNIX ls command.

/OUT=output_file

Optional. If you do not specify the /OUT qualifier, FTP displays output to SYS$OUTPUT. If you do specify the /OUT qualifier, you must supply a valid output_file specification.

Name of the file to hold the output.


Examples

#1

FTP> DIRECTORY 
200 PORT command successful
150 Opening data connection for /bin/ls (130.180.9.8,1150) 
total 76
-rwxr-x--x  1  geary    users  261 Nov  6  1996 .cshrc
-rw-r--r--  1  root      users 128 May 21 11:16 .mailrc
-rwxr-x--x  1  geary    users  182 Nov  6  1996 .profile
drwxr-x--x  2  geary    users  512 Nov  6  1996 bin
   .
   .
   .
226 Transfer complete.
911 bytes received in 00:00:00.07 seconds
      

Displays a full listing of file names in the current default UNIX directory.

#2

FTP> ls disk3$:[banks.branch.bills] 
200 PORT command successful
150 Opening data connection for DISK3$:[BANKS.BRANCH.BILLS]  (11.1.2.3.4)
LOCAL_ACCTS.DIS;1
GO_FIGURE.EXE;14
COMPARE.EXE;4
SUMTOTAL.COM;1
226 NLST Directory transfer complete.
428 bytes received in 00:00:00.41 seconds (10.06 Kbyte/s) 
FTP>
      

Displays a listing of file names in the directory of the connected host, which is another OpenVMS system.


Previous Next Contents Index