HP OpenVMS systems documentation

FTP performs fast file transfers between two OpenVMS systems by using VMS Plus Mode.

When FTP identifies file transfers between two OpenVMS hosts running TCP/IP Services, it transfers files in large blocks rather than in 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 with an OpenVMS host not running TCP/IP Services.

2.8.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 might also need to use the SET TYPE command to determine the type of file transfer:

• Specifying SET TYPE ASCII results in a sequential file with variable records. Select this type when transferring ASCII text files.
• 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. At the same time, create and transfer a secondary file with the file's OpenVMS record attributes:

   FTP> PUT/FDL file

To retrieve the file from a 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 the following example, the PUT/FDL command does the following:

• Creates the FDL file cygnet.bckfdl on the remote host with the RMS attributes of file STAT.BCK.
• Transfers the data in STAT.BCK and puts it in to 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 (130.180.4.8,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 (130.180.4.8,1029) 226 Transfer complete local: STAT.BCK remote: cygnet.bck 8152 bytes sent in 00:00:00.12 seconds

In the following example, the GET/FDL command performs the following actions:

• Transfers the FDL file cygnet.bckfdl from the remote host to the local host.
• Uses this file to re-create the file STAT.BCK, with all of its original RMS attributes, on the local host.
• Transfers the data in cygnet.bck to 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 (130.180.4.8,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 (130.180.4.8,1029) 226 Transfer complete local: STAT.BCK remote: cygnet.bck 8152 bytes sent in 00:00:00.12 seconds

TCP/IP Services supports only STREAM mode for data transfer. STREAM mode transmits the data as a stream of bytes.

2.8.8 File Structure

TCP/IP Services supports transfers of ASCII (stream, records with variable length) and IMAGE (binary, records fixed at 512 bytes) files.

2.9 Renaming and Deleting Files

To change the name of a remote file, use the FTP command RENAME. 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 FTP command DELETE. 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 FTP command VIEW 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 command APPEND 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 the connected remote host KALI.

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 do the following:

• 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 FTP session (exiting the DCL subprocess), enter the LOGOUT command, as shown in the following example:

  FTP> SPAWN $ DIRECTORY Directory WORK1$:[VANA.FTP] TELNETINIT.INI;2 TELNETINIT.INI;1 Total of 2 files. $ SHOW TIME 2-OCT-2002 13:16:32 $ LOGOUT Process VANA_1 logged out at 2-OCT-2002 13:16:48.26 FTP>

• Specify a DCL command in the SPAWN command line. After the DCL command is executed, FTP prompts for further input, as shown in the following example:

  FTP> SPAWN DIR Directory WORK1$:[VANA.FTP] TELNETINIT.INI;2 TELNETINIT.INI;1 Total of 2 files. FTP>

• Use the exclamation point (!) character to spawn a new process to execute a command, as shown in the following example:

  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 the following criteria:

• The operating system of the remote host
• The applications you use
• Whether you want wildcard name expansion
• The information you want displayed during processing

The following are a few of the FTP commands that control FTP command processing:

• ENABLE/DISABLE LOG
  Enables or disables the display of FTP commands sent to the remote host.
• ENABLE/DISABLE PARSE
  Enables or disables the expansion of file name specifications.
• ENABLE/DISABLE REPLY
  Enables or disables the display of all responses from the remote host.
• 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, of 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

Use the FTP command SHOW STATUS to determine 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, 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). You can also 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 following 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 the SET, ENABLE, and DISABLE commands. These command files are optional. They eliminate the need to enter individual FTP commands, and they run automatically when you invoke FTP.

Initialization command files have the following characteristics:

• Contain only OpenVMS commands.
• Contain only one command per line.
• Are generally named SYS$LOGIN:FTPINIT.INI.

FTP uses the following search method to locate an initialization 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 environment 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 message 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 that appear in the preceding output are converted to one of the following OpenVMS system messages:

FTP Protocol Reply Code	OpenVMS System Message	Explanation
1 xx	%TCPIP-S-FTP_PRELIM	Success
2 xx	%TCPIP-S-FTP_COMPLETE	Success
3 xx	%TCPIP-S-FTP_CONTINUE	Success
4 xx	%TCPIP-W-FTP_TRANSIENT	Warning
5 xx	%TCPIP-E-FTP_ERROR	Error

When a command is executed, FTP checks the return status. In batch mode, the value of the error level determines whether FTP continues with each of the reply codes.

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

FTP> SET ERROR_LEVEL x

• If x is SUCCESS, then WARNING, ERROR, and FATAL cause FTP to exit.
• If x is WARNING, then ERROR and FATAL cause FTP to exit.
• If x is ERROR, then only FATAL causes FTP to exit.

Fatal errors always cause FTP to exit.

2.15 Using FTP with DECnet

To copy files to and from 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 TCP/IP Services for OpenVMS. Use the full file specification, including the node, device, directory, and file name.

The following PUT command copies local file FAX.TXT to DECnet node CURTAIL and renames 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 the file 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. The commands are 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.

DCL Format

APPEND local_file [ remote_file ]

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

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

DCL Format

CONNECT remote_host [ port ]

UNIX 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 (Tru64 UNIX Version 5.1) ready. 
Connected to retail. 
Name (retail:dave): [Return] 
331 Password required for dave 
Password:                  [Return]
230 User dave logged in. 
FTP>    
      

Connects user dave 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.

DCL Format

CREATE/DIRECTORY remote_directory

UNIX Format

mkdir remote/path

Parameters

remote_directory

remote/path

Required.

Name for the created directory.

Qualifiers

/DIRECTORY

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

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

Examples

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 .

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