| Previous | Contents | Index |
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;* |
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" . . . |
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) |
While using FTP, you can:
FTP> SPAWN $ DIR Directory WORK1$:[VANA.FTP] TELNETINIT.INI;2 TELNETINIT.INI;1 Total of 2 files. $ SHOW TIME 2-OCT-1998 13:16:32 $ LOGOUT Process VANA_1 logged out at 2-OCT-1998 13:16:48.26 FTP> |
FTP> SPAWN DIR Directory WORK1$:[VANA.FTP] TELNETINIT.INI;2 TELNETINIT.INI;1 Total of 2 files. FTP> |
FTP> ! DIR Directory WORK1$:[VANA.FTP] TELNETINIT.INI;2 TELNETINIT.INI;1 Total of 2 files. FTP> |
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
$
|
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:
! 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] |
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 |
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).
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.
APPEND local_file [ remote_file ]
append local_file [ remote_file ]
No wildcards.
local_file
Required.Name of the local OpenVMS file.
remote_file
Optional.Name of the remote file, either UNIX or OpenVMS.
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.
Establishes an FTP connection to a remote host. The remote host can be any operating system that supports FTP.
CONNECT remote_host [ port ]
open remote_host [ port ]
remote_host
Required.Remote host to which you want to connect.
port
Optional. Default: 21.FTP port on the remote host.
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.
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.
CREATE/DIRECTORY remote_directory
mkdir remote/path
remote_directory
remote/path
Required.Name for the created directory.
/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.
| #1 |
|---|
FTP> CREATE/DIRECTORY TERM
257 MKD command successful.
|
In this example:
- The remote host is UNIX.
- The working directory is /usr/staff/dir.
- The command creates directory /usr/staff/dir/term.
| #2 |
|---|
FTP> CREATE/DIRECTORY [.TRANSFERS]
257 MKD command successful.
|
In this example:
- The remote host is OpenVMS.
- The working directory is DUA2:[CENTRAL].
- The command creates the OpenVMS directory DUA2:[CENTRAL.TRANSFERS].
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.
DELETE remote_files
DELETE/DIRECTORY remote_directory
delete remote_file
mdelete remote_files
rmdir remote_directory
remote_file
remote_files
remote_directory
Required.File, files, or directory to delete.
/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.
| #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.
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.
DIRECTORY [ /BRIEF | /OUT=output_file ] [ remote_directory ]
ls [ /remote/path ]
remote_directory
/remote/path
Optional. Default: default directory.Directory with the file names you want to list. Wildcards and multiple directories are valid.
/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.
| #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 |