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

- 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

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

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

      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>

# 2.13 Customizing FTP Command Processing

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

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

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

Previous | Next | Contents | Index