Compaq TCP/IP Services for OpenVMS
User's Guide
Previous Contents Index

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

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:

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

2.8.6 Transfer Mode

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

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

2.13 Customizing FTP Command Processing

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

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

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:

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

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

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

CONNECT

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 .

CREATE/DIRECTORY

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

#1 

FTP> CREATE/DIRECTORY TERM 
257 MKD command successful.

In this example:

#2 

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

In this example:

Previous Next Contents Index