3. FTP: Transferring Files

Introduction

The File Transfer Protocol (FTP) transfers files to and from a remote host.

The FTP client utility is your interface to the FTP server. You can run the FTP client interactively or through a startup command procedure.

For TCPware’s FTP service to operate between two hosts, the remote host must provide a compliant client or server. You can run FTP directly (interactively) or indirectly from a command procedure. The FTP client supports multiline recall of up to 20 lines.

Before Using FTP

Before you can transfer files, you need:

· To make sure that the TCPware FTP software is installed, configured, and started on your system.

· The name or internet address of the remote host to which you want to connect.

· The username and password of the account on the remote host. If the remote host does not support multiuser protection features, you might not need a username and password.

· The file naming conventions on the remote host.

FTP Session

A typical FTP session consists of the following steps:

1. Open the FTP connection.

2. Determine the format of the files you want transferred.

3. Transfer files using the GET (MGET), PUT (MPUT), or COPY. The default file format is formatted ASCII.

4. Close or exit the FTP connection.

Features

TCPware’s FTP implementation includes the following features:

· Command line execution.

· Informational and error status messages.

· Support of wildcards in source file specifications.

The below table describes some of the features of the TCPware FTP client.

This feature...	Means that...
Command Line User Interface	The FTP client allows you to execute FTP commands at the FTP>. You can use either DCL-style syntax or UNIX-style syntax at the FTP> prompt. DCL syntax can include qualifiers: FTP>DIRECTORY .DIR /BRIEF You usually enter UNIX-style commands in lowercase: FTP>ls .dir
Status Messages	The FTP client issues informational and error messages. These messages are self-explanatory and conform to the standard OpenVMS message format. The numeric codes that prefix these messages conform to the RFC 959 standard for FTP.
Wildcards	The FTP client supports wildcards for the COPY, GET, PUT, DELETE, and DIRECTORY commands. The acceptable wildcard characters are: · Percent sign (%) or question mark (?) to represent individual characters. · Asterisk () to represent multiple characters. If you include the asterisk wildcard to represent multiple files to FTP, use the MGET, MPUT, or MDELETE commands, or specify the /MULTIPLE qualifier with the GET, PUT, COPY, or DELETE command. These two examples produce identical results: FTP>MGET .TXT FTP>COPY .TXT/MULTIPLE/REMOTE Note that you do not require the asterisk for the destination with MGET, but you do require it with COPY. If enclosed in a quoted string, wildcard symbols no longer act as wildcards.

Opening a Connection

Only one FTP connection can be open at a time. Once open, all file transfers and other remote operations use that connection.

You can open an FTP connection by using the command line user interface. Enter one of the following at the DCL prompt:

$ FTP
FTP>OPEN host

host is the name of the host to which you want to connect. Respond to the login prompts, if any, of the remote host. After a successful login, the FTP> prompt appears where you enter the FTP commands described in the following sections. This is the option shown in the below example.

$ FTP[/TLS] host

FTP>

$ FTP[/TLS] host username password

FTP>

Enter the host to which you want to connect, the username of the account on the remote host, and the password of the account on the remote host as part of the command. After a successful login, the FTP> prompt appears where you enter the FTP commands described in the following sections.

Closing and Exiting

An FTP connection remains open until you quit or exit FTP, close the connection, or open a new connection. To close an FTP connection, use one of the following commands:

1. Closes the current connection and continues the FTP session for the next command.

FTP>CLOSE

2. Both OPEN and CONNECT close the current connection and open another one.

FTP>OPEN host
FTP>CONNECT host

3. Exits an FTP session:

FTP>EXIT

See the CLOSE, OPEN, and EXIT commands in the Command Reference.

Examples of closing an FTP connection:

Checking Directories

After you establish an FTP connection, you can check the directories on the remote or local host to locate the file(s) you want.

To check remote directories and determine the file format type when in FTP (see the below example):

1. Open the FTP connection and enter:

FTP>DIRECTORY

Use the CD or SET DEFAULT /REMOTE command to move to other directories on the remote host.

2. Check file extensions to determine file types. You might need to enter special qualifiers when you transfer certain types of files.

See the table in the next section for a description of the file transfer formats.

3. Check the local directory when in FTP:

FTP>LDIR

4. Use the LCD or SET DEFAULT /LOCAL command to move to other directories on the local host.

See the DIRECTORY, LDIR, and SET DEFAULT commands in the Command Reference for checking directories.

Checking File Transfer Formats

You can determine what file format to use during file transfers. The FTP client lets you transfer files in formatted ASCII, formatted binary, image, block, FORTRAN carriage control, and VMS formats. On OpenVMS systems, the filename extension can indicate the file type. Formatted ASCII is the default transfer file type and is usually sufficient for most files.

FTP converts the various file formats to formatted ASCII or IMAGE. (Executable and zip/compressed files are popular files in this category.) The formats are similar to the formats that the OpenVMS EXCHANGE utility provides to transfer between OpenVMS and DOS-11 or RT-11 file systems. You either specify the file transfer format when you use the GET, PUT, or COPY command, or the FTP client determines the format from the source filename's extension.

See below for an explanation of the file transfer formats.

Check file extensions to determine file types. You might need to enter special qualifiers when you transfer certain types of files.

When you use the COPY, GET, or PUT commands to transfer files, you can use the /ASCII, /BINARY, /BLOCK, /FORTRAN, /IMAGE, or /VMS qualifiers to set the file transfer format. You can also set default file transfer formats using these qualifiers with the SET DEFAULT command, or specifying these keywords with the TYPE command. (See the SET DEFAULT and TYPE commands in the Command Reference for equivalent usage.)

This file format...	With extension...	Means...
Formatted ASCII		ASCII records terminated with a CR and LF and transferred as ASCII. Use for all except formatted binary and image files. Maximum formatted ASCII record size is 8192 bytes. In OpenVMS-to-"FTP ASCII" conversion, CR/LF pairs are added to the end of records. In "FTP ASCII"-to-OpenVMS conversion, CR/LF pairs are removed from the end of records.
Formatted Binary	.OBJ .STB .BIN .LDA	Binary records transferred as IMAGE. In OpenVMS-to-"FTP IMAGE" conversion, record header and checksum are added to all records. In "FTP IMAGE"-to-OpenVMS conversion, record header and checksum are removed from each record. Remote hosts might not be able to distinguish between formatted binary and image files because both file types are transferred using "FTP IMAGE" format. In this case, the formatted binary files are stored as image files (and if properly transferred back, are formatted binary files again). This is typically not a problem because formatted binary files are system-dependent files.
BLOCK		File blocks transferred as IMAGE. Use for STREAM, STREAM_CR, STREAM_LF, and UNDEFINED record formats. Provides the highest transfer rates since it involves minimal processing. Very similar to image mode. In OpenVMS-to-"FTP IMAGE" conversion, and OpenVMS file is read using block-I/O mode without regard to record structure. In "FTP IMAGE"-to-OpenVMS conversion, an OpenVMS file is created with the STREAM_LF record format and is written using block-I/O mode. No padding of the last block of data occurs. Block mode is particularly useful for files with a STREAM, STREAM_CR, STREAM_LF, or UNDEFINED record format.
FORTRAN		Like formatted ASCII except that first character of each line controls how to display each line. Conversions are the same as for formatted ASCII. Attributes for the output file reflect that the file has a FORTRAN carriage control format. Some hosts do not distinguish between FORTRAN carriage control and ASCII files and might not support this transfer format.
IMAGE	.EXE .TSK .OLB .MLB .SYS .SML .ULB	Fixed-length binary records transferred as IMAGE. In OpenVMS-to-"FTP IMAGE" conversion, records are read as is. In "FTP IMAGE"-to-OpenVMS conversion, records are written as fixed length. If the last record is too short (less than 512 bytes), it is padded with binary zeros.
VMS		Use for RMS file transfers between OpenVMS systems. Systems that support this structure negotiate it automatically. The VMS file structure types are richer than those of UNIX for which FTP is designed. Thus, VMS and VMS-Plus modes were added to help in transferring OpenVMS files.

Using GET, PUT, and COPY

Use the GET, PUT, or COPY commands to transfer files.

GET	"Gets" a copy of a file from the remote host and places it in the current local directory.
PUT	"Puts" a copy of a local file in the current directory on the remote host.
COPY	"Gets" or "puts" a copy of a file, depending on use of the /LOCAL or /REMOTE qualifier after the source or destination parameter. COPY requires the destination parameter.

The below example shows the format and filename syntax of the GET, PUT, and COPY commands. Follow the examples and observe the following conventions when you transfer files between remote and local hosts (the sequence is not important):

· If using GET or PUT, omit destination if you want to use the source filename (and extension if it exists), unless source is a quoted string. COPY requires the destination parameter. If using COPY, use a wildcard (asterisk) for destination when you want to use the source filename as the destination filename.

· If copying to or from a non-OpenVMS file specification, enclose it in double quotes (" ").

· Separate multiple file specifications with commas.

· If using wildcarded source file specifications (with an asterisk), use the /MULTIPLE qualifier. Alternatively, use the MGET or MPUT command to copy wildcarded source files. (Note that this requires setting the remote default directory first.)

· Including an asterisk (*) after the semicolon (;) in a destination parameter preserves the file version when copying to a remote host. Note that if the file version in the source parameter already exists at the destination, that version is overwritten at the destination. Also, you do not get a warning if a higher numbered destination version already exists.

· If a DECnet file, use the full OpenVMS file specification.

· At this point, the file transfer format you determined is important.

See the GET, PUT, and COPY commands in the Command Reference.

Note: TCPware FTP does fast transfers between two OpenVMS systems using VMS file structure or VMS Plus Mode (for TCP/IP Services for OpenVMS (UCX) servers). When TCPware FTP identifies file transfers between two OpenVMS hosts running TCPware, it automatically transfers files in large blocks rather than small records. These VMS modes greatly increase the transfer speed and preserve all Record Management Services (RMS) file attributes. The VMS modes are disabled with non-OpenVMS systems.

Anonymous Users

You can access some remote resources as an ANONYMOUS user instead of with your usual username and password. This is especially useful for access to sites that allow anonymous user access to some of their files.

Anonymous access depends on your use of the /ANONYMOUS qualifier with the FTP commands that require a file or directory specification using the node name syntax.

You can access some remote resources as an ANONYMOUS user in one of the following ways (see the below example):

1. By default, use the node name file syntax (as described below) with any FTP command that requires a file or directory specification (such as COPY, DIRECTORY, RENAME, and SET DEFAULT). This file syntax sends the ANONYMOUS username and your e-mail address as a password.

Thus, the following file or directory specification: node::path

is equivalent to: node"ANONYMOUS your-email-address"::path

With OpenVMS V6.1 and later on Alpha and Itanium systems, node can be a domain name or IP address.

2. Use the file specification syntax described in the below example and (optionally) add the /ANONYMOUS qualifier or deny remote anonymous access using the /NOANONYMOUS qualifier.

Using the node name file syntax (and the /ANONYMOUS or /NOANONYMOUS qualifier) affects the following FTP commands:

COPY	CREATE/DIRECTORY	DELETE	DIRECTORY	DISPLAY
GET	LS	MDELETE	MGET	MKDIR
MPUT	PUT	RENAME	RMDIR	SET DEFAULT

Below are examples of how to allow or deny anonymous user access to remote resources.

Startup Command File

You can have a startup file execute FTP commands each time you invoke FTP. The startup file contains commands you want your system to perform at the beginning of each FTP session. Your system manager might already have defined a system-wide FTP startup file. Creating an FTP startup file is optional.

The startup command file in the below example opens a remote connection, sends the password, and initiates a SHOW STATUS command.

You can set up an FTP startup command file or override one established by the system manager at the system level using the following procedure:

1. Create an FTP_STARTUP.COM file in your directory.

2. In the file, include the FTP commands you want executed each time you start an FTP session. If you include a password, make sure to use quotation marks to preserve case.

3. Edit your LOGIN.COM file and define the FTP_STARTUP logical to point to the startup file:

$ DEFINE/PROCESS FTP_STARTUP "SYS$LOGIN:FTP_STARTUP.COM"

Using the DEFINE/PROCESS FTP_STARTUP entry in the user's LOGIN.COM file causes that file to override any FTP startup command file at the system level.

4. Run FTP.

Whenever you run the TCPware FTP client, it looks for the file to which the FTP_STARTUP logical points, and processes all the commands in that file.

If the EXIT or QUIT command appears in the startup file, the FTP client:

· Ignores all commands following the EXIT or QUIT command.

· Continues with FTP operations after the startup command file.

Note: VERBOSE mode is set ON by default so that you can read replies from the FTP server when you connect or change server directories. This means that you do not need to include the SET DEBUG /CLASS=REPLIES (or its equivalent VERBOSE) command in the startup command file. Although an existing SET DEBUG /CLASS=REPLIES command in the file does not change the mode, a VERBOSE command toggles VERBOSE mode OFF. (See the SET DEBUG /CLASS command description in the Command Reference.) If you are an ANONYMOUS user, VERBOSE mode might help in reading any informational messages the FTP server creates.

Site-Specific Commands

The TCPware FTP server supports the SITE SPAWN and SITE SHOW TIME site-specific commands. The FTP client can issue these commands at any time.

Site-specific commands can vary depending on the remote FTP server; some servers do not support any.

Issue the TCPware FTP site-specific commands in one of the following ways at the FTP> prompt (see the below example):

1. This command returns the current date and the time of day for the OpenVMS system in the reply message.

FTP> SITE SHOW TIME

2. This command allows you to execute any DCL command as a subprocess. You typically use this command to print files, submit batch jobs, execute command procedures, or issue other commands.

FTP> SITE SPAWN dcl-command

The screen does not display the output the subprocess generates. The system returns status from the subprocess as the status for the SITE SPAWN command. Note that spawning is not allowed for CAPTIVE accounts. See the SITE and SPAWN commands in the Command Reference.

Sample Session

This section describes a sample TCPware FTP session.

See the below example for the corresponding numbered steps. In this example, a user on local host BETA:

1. Starts the TCPware FTP client, opens a connection to remote host THETA, and logs in as user SMITH (the display does not echo the password at the prompt).

2. Using PUT, copies the local SYS.EXE file to THETA.

3. Using GET, copies the SYS.EXE file on THETA back to BETA.

4. Obtains a remote directory listing. There is a SYS.EXE file.

5. Deletes the SYS.EXE file.

6. Obtains another remote directory listing. SYS.EXE is now gone.

7. Obtains a local directory listing. Note that SYS.EXE;1 still exists locally.

8. Opens a connection to host ALPHA (running OpenVMS and the TCPware FTP server) and logs in as USER. This closes the connection to THETA.

9. Obtains a remote directory listing on ALPHA.

10. Using GET, copies the ASCII file SCREEN_FTP.TXT on ALPHA to BETA.

11. Changes the default for transferring files from formatted ASCII to IMAGE.

12. Using GET, copies the SEND-NORM.BIN, SEND-NORM.OBJ and SEND.OBJ files from ALPHA as image files on the local host.

13. Obtains a local directory listing. SCREEN-FTP.TXT, SEND-NORM.BIN, SEND-NORM.OBJ, and SEND.OBJ are now present.

14. Exits FTP.

Command Reference

The following pages describe the TCPware FTP commands. The immediately following table contains command synonyms you can use interchangeably with TCPware FTP commands. The second following table shows commands you can use to do various tasks.

Enter FTP commands at the FTP> prompt. The TCPware FTP client supports the following commands:

ACCOUNT	ENABLE VMS_PL	PWD	SET PASSIVE
CCC	ERROR_EXIT	QUOTE	SET VMS
CLOSE	EXIT	REMOTEHELP	SET STATUS
COPY	GET	RENAME	SITE
CREATE/DIR	HELP	SET BELL	SPAWN
DEFINE/KEY	LDIR	SET DEBUG	STRUCTURE
DELETE	OPEN	SET DEFAULT	TYPE
DIRECTORY	PROTECTION	SET HASH	USER
DISPLAY	PUT	SET LOWERCASE

FTP client command synonyms:

This command...	Is a synonym for the FTP command...
ASCII	TYPE ASCII
BELL	Toggles between SET BELL and SET NOBELL
BINARY or IMAGE	TYPE IMAGE
BYE or QUIT	EXIT
CD	SET DEFAULT /REMOTE
CONNECT	OPEN
DEBUG	Toggles SET DEBUG/CLASS=COMMANDS
DISCONNECT	CLOSE
H	HELP
HASH	Toggles between SET HASH and SETNOHASH
LCD	SET DEFAULT/LOCAL
LIST or LS	DIRECTORY/NAME_LIST
LOGIN	USER
MDELETE	DELETE/MULTIPLE
MGET	GET/MULTIPLE
MKDIR	CREATE/DIRECTCORY
MPUT	PUT/MULTIPLE
PASSIVE	Toggles between SET PASSIVE and SET NOPASSIVE
RECV	GET
RM	DELETE
RMDIR	DLETE/DIRECTORY
SEND	PUT
STATUS	HOW STATUS
VERBOSE	Toggles SET DEBUG/CLASS=REPLIES
Z	SPAWN

Commands used to perform tasks on the local system:

DEFINE/KEY	Associate an equivalence string and set of attributes with a keyboard key
HELP	Bring up the FTP client online help facility
LCD	Set your local default directory
LDIR	List files in your local directory
SET BELL	Ring terminal bell after completing a file transfer
SET DEBUG	Display of debugging information
SET DEFLATE	Sets DEFLATE mode optional parameters. The only optional parameter currently recognized is /LEVEL, which can be specified as -1 (default, balance between compression and CPU time), 0 (no compression) to 9 (maximum compression). The SET MODE DEFLATE command must be used to enter deflate (ZLIB compression) mode. DEFLATE mode is not compatible with TLS authentication, which provides its own data compression algorithms. DEFLATE mode cannot be used when TLS is being used.
SET HASH	Enable hash marks during a file transfer
SET LOWERCASE	Convert unquoted filenames to lowercase in a file transfer request
SET PASSIVE	Sets passive mode
SET VMS	The FTP client negotiates with the server for VMS file structure when opening a connection
SHOW STATUS	Show the status of the current connection and local default directory
SPAWN	Executive DCL commands without exiting FTP
STRUCTURE	Change the default file structure for a transfer (FILE, RECORD, or VMS)
TYPE	Change the default file transfer format (ASCII, BINARY, IMAGE, FORTRAN, BLOCK, VARIABLE, or DEFAULT)

Commands used to perform tasks on remote systems:

CD	Change the remote default directory
DELETE	Delete a file or directory on the remote host
DIR, LIST, or ls	List files on the remote host
MKDIR	Create a directory on the remote host
PWD	Display the name of the current working directory on the remote host
QUOTE	Send an FTP command to the remote server
REMOTEHELP	Bring up the remote FTP server’s online help facility
RENAME	Rename a file on the remote host
SITE	Issue a site-specific command to the remote server
USER	Set the username at the remote host

TCPware FTP logicals for users:

FTP_STARTUP

Define the FTP_STARTUP logical to point to the FTP_STARTUP.COM file. For example:

$ DEFINE /SYSTEM/EXECUTIVE FTP_STARTUP SYS$MANAGER:FTP_STARTUP.COM

Client users can override this startup file by creating their own. Including the command
DEFINE/PROCESS FTP_STARTUP in a user's LOGIN.COM file overrides any system wide setting.

TCPWARE_FTP_MAX_PRE_ALLOCATION

The logical TCPWARE_FTP_MAX_PRE_ALLOCATION may be defined to limit the size that a file will be pre-allocated to when file size information is available at transfer time. This can be important when transferring very large files, as it can take a long time to pre-allocate the file at the start of the transfer and timeout routines in FTP and/or firewalls may cause connections to be dropped. This logical does not have any effect for STRU OVMS transfers of Indexed, Contiguous, or Contiguous, Best Try files; these files need to have accurate allocation size information at the start of the transfer.

TCPWARE_FTP_ALL_VERSIONS

Requests the NLST and LIST commands to display all versions of the specified files. If TCPWARE_FTP_ALL_VERSIONS is defined, the logical TCPWARE_FTP_STRIP_VERSION has no effect.

TCPWARE_FTP_ALL_VERSIONS is ignored if the FTP server is in UNIX emulation mode.

TCPWARE_FTP_DISALLOW_UNIX_STYLE

Controls whether UNIX style filename parsing is done. If not defined and a / is found in the filename, it is assumed to be a UNIX style filename.

TCPWARE_FTP_EXTENSION_QUANTITY

Defines the default allocation/extension quantity for new files and appends.

TCPWARE_FTP_IGNORE_UNIX_DASH_OPTIONS

By default, the FTP server ignores Unix-style dash options on LIST and NLST when in Unix mode (for example, the “-l” in “ls -l”). Define this to be FALSE to tell the FTP server to pay attention to Unix-style dash options.

TCPWARE_FTP_ONLY_BREAK_ON_CRLF

If this logical is set and an ASCII file is transferred, a new line is created in the file upon receipt of a carriage return/line feed sequence.

If this logical is not set and an ASCII file is transferred, a new line is created upon receipt of either a carriage return/line feed sequence or a line feed.

TCPWARE_FTP_SEMANTICS_FIXED_IGNORE_CC

If this logical is defined to TRUE, then GET operations of fixed lengths record files will not have a <CR>(carriage return)<LF>(line feed) added to the end of each record.

TCPWARE_FTP_SEND_FEAT_ON_CONNECT

By default, the FTP client sends the FEAT command upon connecting to a server. This can be disabled by defining this logical as FALSE.

When this is disabled the FTP client will not be able to detect the support of optional features such as TLS, REST STREAM, and others and these features may not work correctly if there is an attempt to use them.

TCPWARE_FTP_STRIP_VERSION

Causes VMS mode output to have no versions.

TCPWARE_FTP_USE_SRI_ENCODING_ON_ODS5

The logical TCPWARE_FTP_USE_SRI_ENCODING_ON_ODS5 can be defined to 1, TRUE or YES to cause the file name encoding used for UNIX-style file names on ODS-2 disks to be used on ODS-5 disks. This also sets the default case of letters in filenames to lowercase and ignores the stored case.

TCPWARE_FTP_UNIX_STYLE_CASE_INSENSITIVE

Allows UNIX style filename handling to be case insensitive.

Troubleshooting

Access error messages help by entering HELP TCPWARE MESSAGES [identifier], or visit the Process Software web site at www.process.com.

ACCOUNT

Specifies the user's account if the remote server requires it.

Format

ACCOUNT account

Parameter

account

User's account. Enclose in quotes if it contains special characters or embedded spaces, or contains mixed-case characters.

Example

The following specifies account Smith on the remote system. Use quotes around the mixed-case account name.

FTP>ACCOUNT "Smith"

CCC

Change the control port to clear text after performing RFC 4217 encrypted authentication. Clear text may be desired for the control port when NAT or firewalls are being used that expect to examine and/or alter commands and responses dealing with the data port (PORT, PASV, EPRT, EPSV and the respective replies). The PROTECTION command should be used before the CCC command as it is not allowed after the command channel has returned to clear text mode.

Format

CCC

CLOSE

Closes the connection to the remote FTP server if one is open and keeps you in FTP.

OPEN and CONNECT also close an existing connection before opening another one.

Format

Synonym

DISCONNECT

Example

The following closes the current connection:

FTP>CLOSE

COPY

Copies files to or from a remote host. You specify whether the source or destination file is local or remote using the /LOCAL or /REMOTE qualifier. COPY supports full wildcard file specifications except wildcard symbols enclosed in a quoted string. Use the /MULTIPLE qualifier for a wildcard remote source file specification. /REMOTE also supports use of asterisk (*) wildcards after a semicolon (;) in remote file specifications. This creates the same version in the destination file as in the source file (instead of creating a new version). If the server is not OpenVMS, the version number is part of the filename. TCPware does not issue a warning if the server host already has a higher numbered version.

Format

COPY source [,source,...] destination

Equivalents

GET = COPY source /REMOTE destination

RECV = COPY source /REMOTE destination

MGET = COPY source /REMOTE /MULTIPLE destination

PUT = COPY source /LOCAL destination

SEND = COPY source /LOCAL destination

MPUT = COPY source /LOCAL /MULTIPLE destination

Parameters

source

Input file specification. Use a comma between multiple file specifications. Enclose the file specifications in quotes if you want to preserve case and did not use the SET NOLOWERCASE command.

destination

Output file specification. Enclose the file specification in quotes if you want to preserve case and did not use the SET NOLOWERCASE command. If wildcarded (*), the FTP client uses the source filename or extension, unless the file specification is a quoted string. See the source parameter for the destination file specification format.

To obtain the same version number in the destination file as in the source file (instead of creating a newer one), wildcard the destination file version using ;*. Note that if the server is not an OpenVMS host, the version number is included in the filename. You do not get a warning if the server host already has a higher numbered version. Also, if the server host already has the version specified, the old file with that version is overwritten.

Transfer Qualifiers (Positional)

/LOCAL

The preceding file is on the local host. If /LOCAL follows source, /REMOTE is implicit for destination. If /LOCAL is omitted, the FTP client searches for a node; if found, the FTP client assumes the file is remote. Do not use for both source and destination.

/REMOTE

The preceding file is on the remote host. If /REMOTE follows source, /LOCAL is implicit for destination. If /REMOTE is omitted, the FTP client searches for a node; if found, the FTP client assumes the file is remote. Do not use for both source and destination. (See the destination parameter on how to preserve version numbers on a remote copy.)

/MULTIPLE

Transfers multiple files. Use after source only. Include wildcards in source only because some remote hosts do not recognize the OpenVMS asterisk and percent characters as wildcards. The remote host's server must support the FTP NLST command. Not all servers support VMS files. If the server does and you do not specify another mode (using a qualifier or the STRUCTURE or SET DEFAULT commands), /VMS is the default.

File Type Qualifiers (Positional)

If you omit one of the file type qualifiers, the FTP client transfers the file based on either:

· The current default setting; for example, ASCII or IMAGE.

· The extension (type) of the file you want to copy (see File Transfer Formats).

Setting a file type qualifier overrides the default transfer format for this transaction only. (See also the SET DEFAULT command.)

/ASCII

Transfers the preceding file in formatted ASCII format.

/BINARY

Transfers the preceding .BIN, .LDA, .OBJ, or .STB file in formatted binary format.

/BLOCK

Transfers the preceding STREAM, STREAM_CR, STREAM_LF, or UNDEFINED file in block mode.

/FORTRAN

Transfers the preceding file in FORTRAN mode. The first character of each record is a FORTRAN carriage control character. Some hosts do not recognize this transfer format.

/IMAGE[=size]

Transfers the preceding file in image mode. Optional size sets the record size of the local output file. Does not apply to remote output files. The maximum size for this qualifier is 32768.

/RECORD

Transfers the preceding file using STRU R so as to communicate the record structure during the copy. Not all servers support record structure mode. If you specify both /RECORD and /VMS, the FTP client uses /VMS.

/VARIABLE

Transfers an image file (see /IMAGE) in variable length record mode. At the destination site, all /IMAGE records have a fixed length. Applies to local output image files only. This qualifier has meaning only if the /IMAGE qualifier is present.

/VMS

Transfers the preceding file in VMS file mode. Allows you to transfer any type of RMS file between OpenVMS systems. If you use /VMS, the FTP client ignores /APPEND, /ASCII, /BINARY, /BLOCK, /FORTRAN, /IMAGE, and /VARIABLE. If you specify both /RECORD and /VMS, the FTP client uses /VMS.

Other Qualifiers (Non-positional)

/ANONYMOUS
/NOANONYMOUS

Enables (/ANONYMOUS) or denies (/NOANONYMOUS) anonymous user access to remote resources. You can omit /ANONYMOUS if you use the node file syntax (node::pathname). (See Anonymous Users.)

/APPEND

Appends the source file to the destination file. If the destination file does not exist, the FTP client creates it. Only valid if appending to a file with the same file transfer type. Some remote hosts might not support this operation.

/CONFIRM
/NOCONFIRM

/CONFIRM issues a confirmation prompt before copying a file. Useful when source contains wildcards so that you can confirm each file copy. Respond with Y or N. /NOCONFIRM is the default.

If confirming multiple file copying, use with COPY/MULTIPLE with a wildcard value. Position the qualifier immediately after the COPY verb to relate to all files, or after the particular filename to relate to that file only.

/CONTIGUOUS=blocks

Local output file should have an initial contiguous allocation of the specified number of blocks. If the output file is smaller than the specified blocks, the FTP client truncates the allocation. If the output file is larger, the additional allocations are non-contiguous. Does not apply to remote output files.

/FDL

Uses and then deletes a separate FDL file describing the specified file's OpenVMS RMS record attributes. This qualifier is useful after a PUT /FDL operation from a VMS node transfers a file to a non-VMS node: the GET /FDL operation can then return the file with the proper record attributes back from the non-VMS node. The default is not to create an accompanying FDL file. The TYPE command determines the type of file. A transfer of:

· ASCII data results in a sequential file with variable length records (the default).

· IMAGE data results in a sequential file with fixed length records of 512 bytes.

/IGNORE
/NOIGNORE

/IGNORE ignores errors so that copying can continue with the next file. /NOIGNORE, the default, terminates copying if an error occurs.

/LOG
/NOLOG

/LOG displays file specifications for each file transferred. /NOLOG, the default, does not display the transferred file's specifications.

/RESTART

For STREAM mode transfers restart the transfer where it was interrupted. The client verifies that the server supports the RFC 3659 SIZE and REST commands, and ignores the qualifier if it does not.

This does NOT work for VMS mode transfers (STRU VMS), and if the remote system is a VMS system it is recommended that a STRU FILE be done before the transfer command and to include /NOVMS on the command line.

/SET_FACTS

Set selected file facts on the destination file to match the source file after transfer. The currently supported fact is MODIFICATION__TIME.

Examples

1. Each of these commands copies the STUFF.TXT file from the local host to remote host SYS1 (the receiving system stores the file under the same filename in user SMITH's directory):

FTP>COPY STUFF.TXT SYS1"SMITH SECRET"::
FTP>PUT STUFF.TXT SYS1"SMITH SECRET"::

2. Each of these commands copies the DATA1.TXT and DATA2.TXT files from the remote host to the local host, assuming that a connection to the remote host is currently open:

FTP>COPY DATA1.TXT,DATA2.TXT /REMOTE *
FTP>GET DATA1.TXT,DATA2.TXT

3. Each of the following commands copies all .BAS files from a remote OpenVMS host to the local host. The /MULTIPLE qualifier and the asterisk wildcard are used in the COPY command, and they are omitted in the equivalent MGET command.

FTP>COPY *.BAS/REMOTE/MULTIPLE *
FTP>MGET *.BAS

4. The issuer of the following command wants to copy all local .SQL type files into multiple files in the remote UNIX system's directory.

FTP>COPY *.SQL/LOCAL/MULTIPLE "/usr/users/sql/*"

To accomplish this, the issuer uses an asterisk wildcard in the output file specification, as in Example 3. However, the result is not as intended. Because the asterisk is part of a quoted string, the command actually copies the files into a single file literally named * on the remote host.

To avoid this, set the remote default directory to the full pathname. You do not have to specify the quoted pathname in the COPY command:

FTP>SET DEFAULT/REMOTE "/usr/users/sql"
FTP>COPY *.SQL/LOCAL/MULTIPLE *

The asterisk now acts as a true wildcard, with the intended result.

CREATE/DIRECTORY

Creates a directory on the remote host. The /DIRECTORY qualifier is required as part of the command. Some remote hosts might not support directory creation operations.

Format

CREATE/DIRECTORY remote-directory

Synonym

MKDIR

Parameter

remote-directory

Directory to create on the remote host, in the format:

[node"username password"::]directory

To open a connection first, use the node"username password":: part of the format. This syntax is optional. If you omit the parameter and a connection is already open, the FTP client uses the current default directory. The directory part of the format is any valid remote directory specification. Enclose the specification in quotes if it contains special characters or embedded spaces or is case-sensitive.

Use the node::directory syntax to create an anonymous user directory. The /ANONYMOUS qualifier is implicit.

Qualifier

/ANONYMOUS
/NOANONYMOUS

Enables (/ANONYMOUS) or denies (/NOANONYMOUS) creation of anonymous user directories. You can omit /ANONYMOUS if using the node file syntax (node::pathname). (See Anonymous Users.)

Examples

1. These commands are equivalent and create a directory USERS on the remote OpenVMS host SYS1, with the username and password specified explicitly:

FTP>CREATE/DIRECTORY SYS1"SMITH SECRET"::[USERS]
FTP>mkdir sys1"smith secret"::[users]

2. All three of the following commands create a directory USERS in the anonymous directory on the remote OpenVMS host SYS2.

FTP>CREATE/DIRECTORY SYS2::[USERS]
FTP>mkdir sys2::[users]
FTP>mkdir sys2::[users] /anonymous

The commands are equivalent to:

FTP>CREATE/DIRECTORY SYS2"ANONYMOUS user-email-address"::[USERS]

DEFINE/KEY

Associates an equivalence string and a set of attributes with a key on the terminal keyboard.

Format

DEFINE/KEY key-name ["]equivalence-string["]

Parameters

key-name

Name of the key to define. The below table lists key designations for three terminal types:

· On LK201 terminals, you can define three types of keys: numeric keypad, editing keypad (except the up and down arrow keys), and function key row (except F1 through F5).

· On VT100-type terminals, you can also define the left arrow and right arrow keys. On VT200 terminals, the left arrow and right arrow keys, and the F6 through F14 keys, are for command line editing. Issue the DCL command SET TERMINAL/ NOLINE_EDITING to define these keys before you run the FTP client. You can also press Ctrl+V to enable keys F7 through F14 (but not F6).

· On VT52 terminals, the only definable keys are on the numeric keypad.

Key Name	LK201	VT100-type	VT52
PF1	PF1	PF1	[blue]
PF2	PF2	PF2	[red]
PF3	PF3	PF3	[gray]
PF4	PF4	PF4
KP0,...,KP9	0,...,9	0,...9	0,...9
PERIOD	.	.	.
COMMA	,	,	,
MINUS	-	-	-
ENTER	ENTER	ENTER	ENTER
LEFT	ß	ß	ß
RIGHT	à	à	à
Find (E1)	Find
Insert Here (E2)	Insert_Here
Remove (E3)	Remove
Select (E4)	Select
Prev Screen (E5)	Prev_Screen
Next Screen (E6)	Next_Screen
HELP	Help
DO	Do
F6,...,F20	F6,...,F20

equivalence-string

String to substitute when you press the key. If the string contains spaces, enclose it in quotes.

Qualifiers

/ECHO
/NOECHO

/ECHO displays the equivalence string on your screen after you press the key. /NOECHO is the default. Do not use /NOECHO with /NOTERMINATE.

/IF_STATE=(state-name,...)
/NOIF_STATE

/IF_STATE specifies a list of one or more state-names (an alphanumeric string) for the key definition to be in effect. If you specify only one state-name, you can omit the parentheses. By including several state-names, you can define a key to have the same function in all the specified states. /NOIF_STATE is the default, where the FTP client uses the current state.

Establish states using /SET_STATE.

/LOCK_STATE
/NOLOCK_STATE

/LOCK_STATE specifies that the state set by /SET_STATE remains in effect until explicitly changed. /NOLOCK_STATE is the default, meaning the state which has been set in effect by /SET_STATE is in effect only for the next definable key you press or the next read-terminating character you type.

You can specify /LOCK_STATE only on the same command line as /SET_STATE.

/SET_STATE=state-name
/NOSET_STATE

/SET_STATE specifies the state-name (an alphanumeric string) you want set for the key. The default is /NOSET_STATE, where the current state locked by /LOCK_STATE is in effect.

/TERMINATE
/NOTERMINATE

/TERMINATE specifies that the FTP client terminates (effectively executes) the current equivalence string when someone presses the defined key. /NOTERMINATE, the default, allows you to create key definitions that insert text into command lines, after prompts, or into other typed text.

Example

The following sets the F1 key on the keyboard to the ""SMITH SECRET"::[USERS]" string, sets the state to 1, and locks the state for that definition:

FTP>DEFINE/KEY F1 """SMITH SECRET""::[USERS]" /SET=1 /LOCK

DELETE

Deletes files or directories on the remote host.

Format

DELETE file[,file,...]

Synonyms

RMDIR dir[,dir,...] = DELETE /DIRECTORY

MDELETE file[,file,...] = DELETE /MULTIPLE

CAUTION! The DIRECTORY command does not list hidden files (files that start with a period). Using any wildcards with the MDELETE command deletes hidden files, which you might need.

Parameters

file

dir

Remote files or directories to delete. When deleting files, file can contain wildcards. See the /MULTIPLE qualifier.

Qualifiers

/ANONYMOUS
/NOANONYMOUS

Enables (/ANONYMOUS) or denies (/NOANONYMOUS) deletion of anonymous files or directories. You can omit /ANONYMOUS if using the node file syntax (node::path). (See Anonymous Users.)

/CONFIRM
/NOCONFIRM

/CONFIRM issues a confirmation prompt before deleting a file. Useful when source contains wildcards so that you can confirm each file copy. Respond with Y or N. /NOCONFIRM is the default.

If confirming multiple file deletions, use with MDELETE or DELETE/MULTIPLE with a wildcard value. Position the qualifier immediately after the DELETE verb to relate to all files, or after the filename to relate to that file only.

/DIRECTORY

Deletes a directory (equivalent to RMDIR). If omitted, the FTP client deletes a file. Do not use with /MULTIPLE.

/IGNORE
/NOIGNORE

/IGNORE ignores errors so that deletion can continue with the next file when using /MULTIPLE. /NOIGNORE, the default, terminates the deletion operation if an error occurs.

/LOG
/LOG displays file specifications for each file deleted.

/MULTIPLE

Deletes multiple files (equivalent to MDELETE). You must include wildcards in the file specification. /MULTIPLE is necessary because other systems do not universally recognize the OpenVMS asterisk and percent characters as wildcards. (You do not need this qualifier with multiple deletes between OpenVMS systems.) The remote host's FTP server must support the FTP NLST command for remote wildcard operations to work. Do not use with /DIRECTORY.

Examples

1. The following deletes the proj1 file from the UNIX /usr/src/directory:

FTP>DELETE "/usr/src/proj1"

2. The following deletes all files with the .TMP extension in the remote default directory. You do not need /MULTIPLE when doing this delete operation between OpenVMS systems. If several versions of any *.TMP file exist, it deletes only the latest version.

FTP>DELETE *.TMP/MULTIPLE

3. The following deletes all files with the FOO filename in the remote default directory. You do not need /MULTIPLE when doing this delete operation between OpenVMS systems. If several versions of any FOO.* file exist, it deletes only the latest version.

FTP>DELETE FOO.*/MULTIPLE

4. The following deletes all files and file versions with the FOO filename in the remote default directory. For example, this command deletes FOO.EXE;1, FOO.EXE;2, FOO.C;1, FOO.C;2, and FOO.TXT;1. You do not need /MULTIPLE when doing this delete operation between OpenVMS systems.

FTP>DELETE FOO.*;*/MULTIPLE

DISPLAY

Displays a remote file on the screen.

Equivalent to the GET (or COPY /REMOTE) command with SYS$OUTPUT as the local file specification.

If a VMS Plus mode transfer is requested, DISPLAY temporarily cancels VMS Plus mode, transfers the file(s), and resets VMS Plus mode again.

Note that displaying a non-ASCII file might produce unrecognizable output, as would be the case with the DCL TYPE command.

Format

DISPLAY remote-file[,remote-file,...]

Equivalents

COPY remote-file[,remote-file,…] /REMOTE [/MULTIPLE] SYS$OUTPUT

[M]GET remote-file[,remote-file,…] SYS$OUTPUT

Parameters

remote-file

Input file specification on the remote host. Enclose in quotes if you want to preserve case and did not use the SET NOLOWERCASE command, or the file specification contains delimiters or symbols the FTP server can interpret in special ways. Use a comma between multiple file specifications. The remote file specification must conform to the file naming conventions of the remote host.

Examples

The following shows formats of acceptable equivalent commands that implement the DISPLAY function:

FTP>DISPLAY TEXT.TXT
FTP>GET TEXT.TXT SYS$OUTPUT
FTP>MGET TEXT.TXT, TEXT2.TXT SYS$OUTPUT
FTP>COPY TEXT.TXT /REMOTE SYS$OUTPUT
FTP>COPY TEXT.* /REMOTE /MULTIPLE SYS$OUTPUT
FTP>COPY NODE"USER PASSWORD"::TEXT.TXT SYS$OUTPUT

ENABLE [DISABLE] VMS_PLUS

Turns VMS Plus Mode on or off. This lets you specify a transfer mode based on file type, for example, ASCII or image.

In VMS Plus mode, file transfers use File Descriptor Language (FDL) information to create output files.

Format

FTP> ENABLE VMS_PLUS

FTP> DISABLE VMS_PLUS

ERROR_EXIT

Exits FTP with a specified status if an error occurs in the previous FTP command. This feature is useful when running FTP from a command procedure.

Note that you exit the FTP client if you try to use this command interactively.

Format

ERROR_EXIT [status]

Parameter

status

Optional status value the DCL $STATUS symbol returns if FTP exits. Specifies which command (or sequence of commands) failed. If omitted, the FTP client uses the status value of the last error.

Note: The FTP client reports the $STATUS as the status value ORd with %X10000000.

Example

The following example is part of a DCL command procedure:

.
$ SET NOON
$ FTP
OPEN LILAC SMITH PASSWORD
ERROR_EXIT %X10000010
PUT DATA_FILE1.TXT
ERROR_EXIT %X10000020
PUT DATA_FILE1.IMG
ERROR_EXIT %X10000030
PUT DATA_FILE1.DES
ERROR_EXIT %X10000040
EXIT
$ FTP_EXIT_STATUS = $STATUS
$ SET ON
$ IF (FTP_EXIT_STATUS .EQ. %X10000010) THEN GOTO LOGIN_FAILED
$ IF (FTP_EXIT_STATUS .EQ. %X10000020) THEN GOTO TRANSFER_1_FAILED
.
.

This command procedure transfers several files and uses ERROR_EXIT to detect if any of the transfers fail. FTP_EXIT_STATUS returns the following values:

· %X10000010 if the connection or login to LILAC fails

· %X10000020 if FTP cannot transfer DATA_FILE1.TXT

· and so on

· 1 if the connection is successful

EXIT

Exits FTP and returns to the DCL prompt. If a connection is open, the FTP client closes it before exiting.

Format

EXIT

Synonyms

QUIT

BYE

GET

Copies files from a remote host.

GET supports full wildcard file specifications except wildcards enclosed in a quoted string. Use the /MULTIPLE qualifier for a wildcarded remote file specification.

Format

GET remote-file[,remote-file,...] [local-filename]

Equivalents

COPY remote-file /REMOTE local-filename

MGET wildcarded-remote-files = GET remote-file /MULTIPLE

RECV remote-file[,remote-file,...] [local-filename]

Parameters

remote-file

The remote file specification must conform to the file naming conventions of the remote host. In OpenVMS-to-OpenVMS file transfers, the remote-file and local-filename formats are the same. (See the local-filename parameter).

wildcarded-remote-files

Input file specification on the remote host in wildcarded format. Wildcards include the % or ? symbol to indicate individual characters, and the * symbol to indicate multiple characters. Examples of wildcarded file specifications are *.txt , W????.*, and *.*;*.

local-filename

Output file specification on the local host. If omitted, the FTP client uses the remote-file filename (and extension if it exists), unless remote-file is a quoted string. If used, must conform to the OpenVMS file name format.

Qualifiers

If you omit one of the file type qualifiers (/ASCII, /BINARY, /FORTRAN, /IMAGE, /VMS), the FTP client transfers the file based on either:

· The current default setting; for example, ASCII or IMAGE.

· The extension (type) of the file you want copied.

Setting a file type qualifier overrides the default transfer format for this transaction only. See also the SET DEFAULT command.

/ANONYMOUS
/NOANONYMOUS

Enables (/ANONYMOUS) or denies (/NOANONYMOUS) anonymous user access to remote resources. You can omit /ANONYMOUS if using the node file syntax (node::path).

/APPEND

Appends the remote-file file to the local-filename. If the local-filename does not exist, the FTP client creates it. Some remote hosts do not support this operation. NOTE: If the operation fails, try appending in binary mode by using the /BINARY qualifier.

/ASCII

Transfers the file in formatted ASCII format.

/BINARY

Transfers .BIN, .LDA, .OBJ, and .STB files in formatted binary.

/BLOCK

Transfers STREAM, STREAM_CR, STREAM_LF, and UNDEFINED files in block.

/CONFIRM
/NOCONFIRM

/CONFIRM issues a confirmation prompt before getting a file. Useful when source contains wildcards so that you can confirm each file copy. Respond with Y or N. /NOCONFIRM is the default.

If confirming multiple file gets, use with MGET or GET/MULTIPLE with a wildcard value. Position the qualifier immediately after the GET verb to relate to all files, or after the particular filename to relate to that file only.

/CONTIGUOUS=blocks

Local output file should have an initial contiguous allocation of the specified number of blocks. If the output file is smaller than the specified blocks, the FTP client truncates the number of blocks allocated. If the output file is larger, the additional allocations are non-contiguous. Does not apply to remote output files.

/FDL

· ASCII data results in a sequential file with variable length records (the default).

· IMAGE data results in a sequential file with fixed length records of 512 bytes.

/FORTRAN

Transfers the file in FORTRAN mode. The first character of each record is a FORTRAN carriage control character. Some hosts do not recognize this transfer format.

/IGNORE
/NOIGNORE

/IGNORE ignores errors so that copying can continue with the next file. /NOIGNORE, the default, terminates copying if an error occurs.

/IMAGE[=size]

Transfers the file in image mode. Optional size sets the record size of the local output file. Does not apply to remote output files.

/LOG
/LOG displays file specifications for each file transferred.

/MULTIPLE

Transfers multiple files (equivalent to MGET). Use after remote-file only and include wildcards in remote-file. Necessary because some remote hosts do not recognize the OpenVMS asterisk, percent, or question mark characters as wildcards. /MULTIPLE ensures that the remote host understands more than one file is to be transferred. The remote host's server must support the FTP NLST command for remote wildcard operations to work.

/RECORD

Transfers the preceding file using STRU R so as to communicate the record structure during the copy. A positional qualifier. Not all servers support record structure mode. If you specify both /RECORD and /VMS, the FTP client uses /VMS.

/RESTART

For STREAM mode transfers restart the transfer where it was interrupted. The client verifies that the server supports the RFC 3659 SIZE and REST commands, and ignores the qualifier if it does not.

/SET_FACTS

Set selected file facts on the destination file to match the source file after transfer. The only fact currently supported is MODIFICATION__TIME.

/VARIABLE

Transfers an image file (see /IMAGE) in variable length record mode. All /IMAGE records are fixed length when stored at the destination. Applies to local output image files only.

/VMS

Transfers the file in VMS file mode. Allows you to transfer any type of RMS file between OpenVMS systems. A positional qualifier. If you use /VMS, the FTP client ignores /APPEND, /ASCII, /BINARY, /BLOCK, /FORTRAN, /IMAGE, and /VARIABLE. If you specify both /RECORD and /VMS, the FTP client uses /VMS.

Not all servers support VMS files. If the server does and you do not specify another mode (using a qualifier or the STRUCTURE or SET DEFAULT commands), /VMS is the default.

Examples

1. The following copies the DATA1.TXT and DATA2.TXT files from the remote host to the local system, assuming that a connection to the remote host is currently open:

FTP>GET DATA1.TXT,DATA2.TXT

2. The following copies all remote files with extension .BAS from a remote OpenVMS host to the local host:

FTP>MGET *.BAS

3. The following copies the STUFF.TXT file from DELTA's anonymous directory. It is equivalent to having used /ANONYMOUS. Sends the "ANONYMOUS user-email-address" username and password with the command.

FTP>RECV DELTA::STUFF.TXT

HELP

Accesses the the FTP client online help.

The FTP client help uses the OpenVMS interactive help facility.

To exit the help facility, press Return until you return to the FTP> prompt.

See the REMOTEHELP command, or the /REMOTE qualifier, for access to the remote server's online help.

Format

HELP [/REMOTE] [topic]

Synonyms and Equivalents

REMOTEHELP [topic] = HELP /REMOTE [topic]

HELP /REMOTE SITE = REMOTEHELP SITE = SITE HELP = QUOTE HELP SITE

Parameter

topic

Optional; allows you to specify the topic, if known, for which you want help. Otherwise HELP offers you a list of topics from which to choose.

Qualifier

/REMOTE

Equivalent to the REMOTEHELP command: it accesses the remote FTP server's online help instead of the local client’s online help.

Position the qualifier directly after the HELP command. If positioned after the topic, you could get incorrect help or an error. For example, if you specify HELP LDIR /REMOTE, you get online help for "LDIR /REMOTE," which does not exist.

LDIR

Lists files in your local directory along with their creation date and size.

See DIRECTORY to list files on the remote host.

See SET DEFAULT /LOCAL to set the default local directory.

Format

LDIR [directory]

Parameter

directory

Directory to list on your local host. The asterisk (*) wildcard is acceptable.

OPEN

Opens a connection to a remote host.

The connection remains open until you exit FTP, close the connection with the CLOSE command, or open a new connection using the OPEN command or any other command that accepts a node specification.

Format

OPEN [host [username [password [account]]]]

If you:

· Supply the host, username, password, and account (if required) with the command, you are not prompted for them separately.

· Omit the parameters from the command line, you are prompted for them.

· Use the OPEN command non-interactively (for example, a batch job), and do not want to be prompted for a username, password, and account, then include the parameters on subsequent lines, after the OPEN command, in the command file.

· Want to be prompted for a password, do not submit the command file with a batch job.

The display does not echo the password or account information. After a connection is open, you do not have to specify the parameters for remote files.

Synonym

CONNECT

Parameters

host

Name or internet address of the remote host to which you want to connect. OPEN supports any valid hostname syntax, including an internet address.

username

Username on the remote host. Enclose the username in quotes if the case is important or it contains special characters. For a null username, use a pair of quotation marks (" ").

password

Password on the remote host. Enclose the password in quotes if the case is important or it contains special characters. For a null password, use a pair of quotation marks (" ").

If you use OPEN at the DCL level (see the second example), include the password on the same command line.

Qualifiers

/PORT=port

Port number for the remote FTP server. If omitted, the FTP client uses port number 21.

/TIMEOUT=time

Timeout time, in seconds, to establish the FTP control connection. If omitted, the timeout time is 120 seconds (2 minutes). Minimum value is 20 seconds.

/TLS

Negotiate with the server to perform TLS authentication as per RFC 4217. The certificate delivered by the server is checked and self-signed certificates may be rejected if desired. After performing the negotiation user authentication takes place over an encrypted connection. Note that data transfers will not be encrypted until a PROTECTION PRIVATE command has been issued.

/VMS
/NOVMS

/VMS negotiates for VMS file structure. /NOVMS, the default, does not. If omitted, SET VMS or SET NOVMS determines the outcome (see the SET VMS command for details). Note that the OPEN /VMS and OPEN /NOVMS settings override SET VMS and SET NOVMS.

Examples

1. The following opens a connection to SYS1. If successful, you must enter a username and password.

FTP>OPEN SYS1

2. The following DCL level command opens a connection to SYS1. The line includes the username and password so that you can use the command procedure interactively or in batch processing.

$ FTP OPEN SYS1 "smith" "opensesame"

PROTECTION

Set the protection for the data port after doing TLS authentication. The PROTECTION command does an FTP PBSZ (protection buffer size) command followed by an FTP PROT command. The PROTECTION should be specified before returning the command channel to clear text mode as the RFCs specify.

Format

PROTECTION level

Parameters

CLEAR

Data transfers take place in the clear, as they would with a traditional FTP session. This is the default if no protection has been specified.

PRIVATE

Data transfers are encrypted such that they cannot be read by an intermediate system and are integrity protected.

Example

FTP>PROTECTION CLEAR

FTP>PROTECTION PRIVATE

PUT

Copies files to a remote host.

PUT supports full wildcard file specifications except wildcards enclosed in a quoted string. Use the
/MULTIPLE qualifier for a wildcarded local-file file specification. PUT also supports use of asterisk (*) wildcards after a semicolon (;) in remote file specifications. This creates the same version in the destination file as in the source file (instead of creating a new version). If the server is not OpenVMS, the version number is part of the filename. TCPware does not issue a warning if the server host already has a higher numbered version.

Format

PUT local-file[,local-file,...] [remote-filename]

Synonyms and Equivalents

COPY local-file /LOCAL remote-filename
MPUT wildcarded-local-files [remote-filename] = PUT local-file/MULTIPLE
SEND local-file[,local-file,...] [remote-filename]

Parameters

local-file

Input file specification on the local host. Must conform to OpenVMS file naming rules. Use a comma between multiple file specifications.

wildcarded-local-files

Input file specification on the local host in wildcard format. Wildcards include the percent symbol (%) or the question mark symbol (?) to indicate individual characters, and the asterisk symbol (*) to indicate multiple characters. Examples of wildcarded file specifications are *.TXT, W????.*, and *.*;*.

remote-filename

Output file specification on the remote host. Enclose the file specification in quotes if you want to preserve case and did not use the SET NOLOWERCASE command. If the remote-filename is omitted, the FTP client uses the local-file filename and extension, unless they are part of a quoted string. Also, enclose the file specification in quotes if it contains delimiters or symbols the FTP server can interpret in special ways.

For example, the following remote file specification is enclosed in quotes because it includes slashes (/) OpenVMS normally interprets as qualifier delimiters:

ALPHA"smithabcd"::"/usr/bin/proj1.txt"

The remote file specification must conform to the filenaming conventions of the remote host. In OpenVMS-to-OpenVMS file transfers, the local-file and remote-filename specification formats are the same. (See the local-file parameter).

Qualifiers

If you omit one of the file type qualifiers (/ASCII, /BINARY, /FORTRAN, /IMAGE, or /VMS), the FTP client transfers the file based on either:

· The current default setting; for example, ASCII or IMAGE.

· The extension (type) of the file you want copied.

Setting a file type qualifier with the PUT command overrides the default transfer format for this PUT only.

Examples

1. The following copies the STUFF.TXT file from your local host to the remote host (the receiving system stores the file under the same filename in the default directory):

FTP>PUT STUFF.TXT

2. The following copies the local STUFF.TXT file to DELTA's anonymous directory. It is equivalent to having used /ANONYMOUS:, sending the "ANONYMOUS user-email-address" username and password with the command.

FTP>SEND DELTA::STUFF.TXT

PWD

Prints the name of the current working directory on the remote host.

Useful for determining the default directory when not specifying a full pathname.

Format

PWD

Equivalent

SHOW DEFAULT

QUOTE

Sends an FTP command to the remote server.

Note: Do not use QUOTE to initiate a file transfer operation.

Format

QUOTE command

Equivalents

QUOTE HELP SITE = SITE HELP = HELP /REMOTE SITE = REMOTEHELP SITE

Parameter

command

FTP command string sent to the remote FTP server. FTP commands are not the same as the FTP client commands. Enclose the command in quotes if it contains special characters, or embedded spaces, or is case-sensitive.

Example

The following sends the SYST command to the remote FTP server. If implemented by the remote server, it returns the type of operating system running on the remote server.

FTP>QUOTE "SYST"

REMOTEHELP

Accesses the remote FTP server's on-line help.

See HELP to bring up the FTP client's on-line help.

Format

REMOTEHELP [topic]

Equivalents

HELP /REMOTE [topic]

HELP /REMOTE SITE = REMOTEHELP SITE = SITE HELP = QUOTE HELP SITE

Parameter

topic

Optional topic for which you want help from the remote server. If you do not specify a topic, HELP provides you with a list of topics and prompts you to choose one.

RENAME

Renames a file on the remote host.

Format

RENAME old-name new-name

Parameters

old-name

File on the remote host to rename. The remote file specification must conform to the file naming conventions of the remote host. Enclose the file specification in quotes if it contains delimiters or symbols the FTP server can interpret in special ways.

new-name

Valid file specification to substitute for old-name. Enclose in quotes if it contains special characters, imbedded spaces, or is case sensitive.

Qualifier

/ANONYMOUS
/NOANONYMOUS

Enables (/ANONYMOUS) or denies (/NOANONYMOUS) renaming files in anonymous user directories. You can omit /ANONYMOUS if using the node file syntax (node::path).

Examples

1. The following renames the testb file to test2/test:

FTP>RENAME testb "test2/test"

2. The following renames the OLD.TXT file on DELTA to NEW.TXT. It is equivalent to using the /ANONYMOUS qualifier: sends the "ANONYMOUS user-email-address" username and password with the command.

FTP>RENAME DELTA::OLD.TXT NEW.TXT

SET [NO]BELL

Enables the terminal bell after completing a file transfer.

SET NOBELL is the default.

Format

SET BELL

SET NOBELL

Synonym

BELL - toggles between SET BELL and SET NOBELL

SET DEBUG /CLASS

Enables or disables displaying debugging information depending on the class keyword(s) used. The /CLASS qualifier is required.

Format

SET DEBUG /CLASS=(keyword,...)

Synonyms

DEBUG - toggles SET DEBUG /CLASS=COMMANDS

VERBOSE - toggles SET DEBUG /CLASS=REPLIES (default is ON)

Qualifier

/CLASS=(keyword,...)

Classes of debugging information to enable or disable. Use one or more of the keywords listed in the below table. The initial default is PERFORMANCE and REPLIES. Use NONE as the first entry to clear the classes before resetting them (see Example 1).

Keyword	Purpose
COMMANDS	Enables displaying FTP commands sent to the server.
PERFORMANCE	Enables displaying performance information (when using COPY/LOG, GET/LOG, or PUT/LOG).
REPLIES	Enables displaying FTP replies received from the server; equivalent to toggling the VERBOSE command ON (the default).
ALL	Enables displaying all classes.
NONE	Disables displaying all classes.

Examples

1. The following resets the debugging classes. It first disables all classes (NONE), and then enables the COMMANDS and REPLIES (VERBOSE) classes.

FTP>SET DEBUG/CLASS=(NONE,COMMANDS,REPLIES)

2. The following toggles the REPLIES (VERBOSE) class. If on, it shows informational messages (if enabled on the server) when logging in or moving around directories on the server. The ON or OFF setting is immediately displayed after the command.

FTP>VERBOSE

SET DEFAULT

Changes the default local or remote directory.

Sets the default qualifiers used with the COPY, GET, PUT, and DELETE commands.

Note: Specify the parameter or the qualifiers separately. Do not specify them together.

Format

SET DEFAULT [directory]

Synonyms and Equivalents

CD [directory]= SET DEFAULT /REMOTE (CD allows you to use UNIX-style directory names)

LCD [directory]= SET DEFAULT /LOCAL

IMAGE = SET DEFAULT /IMAGE

TYPE BINARY = SET DEFAULT /BINARY

Parameter

directory

Default directory to set on the local or remote host, depending on whether the /LOCAL or /REMOTE qualifier follows, or the remote directory specification if no qualifier follows. The directory format is:

[node"username password"::]directory

To open a connection first, use the node"username password":: part of the format. This syntax is optional. The directory part of the format is any valid directory specification. Enclose it in quotes if it contains special characters or embedded spaces, or is case-sensitive. (You can also use the [directory] format, as in [-], if the remote host is an OpenVMS system.) If directory is omitted:

• With SET DEFAULT or SET DEFAULT /REMOTE, the FTP client sets the default directory to the parent of the current directory on the remote host.

• With SET DEFAULT /LOCAL, the FTP client sets the local default directory to your login directory defined by the SYS$LOGIN logical.

Use the node::directory syntax to access an anonymous FTP user directory, in which case you can omit the /ANONYMOUS qualifier.

Qualifiers

/LOCAL

Changes the local default directory to directory. LCD is the same as SET DEFAULT /LOCAL.

/REMOTE

Changes the remote default directory to directory. CD is the same as SET DEFAULT /REMOTE.

/ANONYMOUS
/NOANONYMOUS

Enables (/ANONYMOUS) or denies (/NOANONYMOUS) the setting of defaults for anonymous user directories. You can omit /ANONYMOUS if you use the syntax node::directory.

/[NO]APPEND
/[NO]CONFIRM
/[NO]IGNORE
/[NO]LOG
/[NO]RECORD
/[NO]VARIABLE
/[NO]VMS

These qualifiers set various transfer defaults. Do not use with /LOCAL or /REMOTE. See the COPY, GET, PUT, or DELETE command for qualifier descriptions.

/ASCII
/BINARY
/BLOCK
/FORTRAN
/IMAGE[=n]

These qualifiers set transfer mode defaults. Use only one. Do not use with /LOCAL or /REMOTE. See the COPY, GET, or PUT command for qualifier descriptions.

/DEFAULT

Determines the default transfer mode from the local file's file extension. Do not use with /LOCAL or /REMOTE.

Examples

1. The following equivalent commands set the local default directory to [SMITH.DOC]. The default device does not change.

FTP>SET DEFAULT /LOCAL [SMITH.DOC]
FTP>LCD [SMITH.DOC]

2. The following equivalent commands sets the remote default directory to /usr/src/:

FTP>SET DEFAULT /REMOTE "/usr/src/"
FTP>CD "/usr/src/"

3. The following sets the default transfer mode to /IMAGE for subsequent copy commands, and sets the default to /LOG and /NOCONFIRM:

FTP>SET DEFAULT /IMAGE /LOG /NOCONFIRM

4. The following sets the remote directory to the anonymous directory on DELTA.

FTP>SET DEFAULT DELTA::[]

It is equivalent to:

FTP>SET DEFAULT DELTA"ANONYMOUS user-email-address"::[]

5. The following sets the remote directory to SYS$SYSDEVICE:[USER.SMITH]:

FTP>CD "/sys$sysdevice/user/smith"

SET DEFLATE

Changes the options for MODE DEFLATE transfers. The only deflate engine present is ZLIB.

DEFLATE transfers can be enabled with the SET MODE DEFLATE command. DEFLATE transfers cannot be used when TLS is being used.

Format

SET DEFLATE

Qualifiers

/LEVEL={-1-9}

Changes the level of data compression that the engine uses when a file is transferred. The default level is -1 - a compromise between speed and compression, 0 is no compression, 1 is best speed and 9 is best compression.

SET [NO]ALLOWSELFSIGNED

Allows or disallows self-signed certificates for RFC 4217 TLS negotiation.

The default is to allow self-signed certificates.

Format

SET ALLOWSELFSIGNED

SET NOALLOWSELFSIGNED

SET [NO]HASH

Enables hash marks.

With SET HASH, the FTP client displays a hash mark (#) every 1024 bytes sent or received during a file transfer. SET NOHASH is the default.

Hash marks appear in files only. No hash marks appear if the file transfer is output to the terminal screen.

Note: With SET HASH, FTP reads only 1024 bytes at a time from the network layer. While this means that FTP gives more accurate reports on the progress of a transfer, it increases overhead. Use hash marks primarily with transfers over slower-speed links (such as SLIP lines).

Format

SET HASH
SET NOHASH

Synonym

HASH - toggles between SET HASH and SET NOHASH

SET [NO]LOWERCASE

Enables the conversion of unquoted filenames to lowercase before the FTP client sends the files to the remote host. SET LOWERCASE is the default.

With SET NOLOWERCASE, the FTP client does not convert unquoted filenames to lowercase.

The FTP client always preserves the case of filenames that appear within quotation marks.

Format

SET LOWERCASE
SET NOLOWERCASE

SET MODE

Set the transfer mode to STREAM (default), BLOCK, COMPRESSED or DEFLATE.

Format

SET MODE {STREAM | BLOCK | COMPRESSED | DEFLATE}

Parameters

STREAM

The data are transmitted as a stream of bytes. This is the default.

BLOCK

The file is transmitted as a series of data blocks preceded by one or more header bytes.

COMPRESSED

Data that contains repeated sequences may be compressed to obtain better bandwidth.

DEFLATE

The data is compressed with the ZLIB compression engine. DEFLATE cannot be used with sessions that use TLS authentication. The TLS code provides data compression when the data stream is protected.

Example

FTP>SET MODE STREAM

FTP>SET MODE DEFLATE

SET [NO]PASSIVE

Sets passive mode. Passive mode performs an active open on the data connection, which can avoid problems with firewall systems.

SET NOPASSIVE (the default) disables passive mode.

You can also define the TCPware FTP_PASV logical as follows:

$ DEFINE/PROCESS TCPWARE_FTP_PASV "TRUE"

Your system manager can also define the logical system-wide as follows:

$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_PASV "TRUE"

Format

SET PASSIVE
SET NOPASSIVE

Synonym

PASSIVE - toggles between SET PASSIVE and SET NOPASSIVE

SET [NO]VMS

Controls whether the the FTP client negotiates for VMS file structure with the FTP server when opening a connection. The default is SET VMS, where the client negotiates with the server to use File Descriptor Language (FDL) information.

The FTP client first queries if the server supports VMS file transfer mode. If not, it queries for VMS Plus file transfer mode, such as with the TCP/IP Services for OpenVMS (UCX) server.

In connecting to a TCPware or other OpenVMS server, the VMS file structure transfer mode is used.

Note that OPEN /VMS or OPEN /NOVMS overrides SET VMS and SET NOVMS.

Format

SET VMS
SET NOVMS

SHOW STATUS

Displays the following information about your present FTP session:

• Remote hostname and internet address if you are connected to a remote host

• Username on the remote host if you are connected and logged in

• Local default directory

• Remote default directory if you are logged in to a remote host and that host supports the FTP PWD command

• Record size to be used with the /IMAGE qualifier

• Defaults that are defined by the SET DEFAULT command for the COPY, GET, PUT, and DELETE commands

Format

SHOW STATUS

Synonym

STATUS

Example

The following shows the status for the current connection:

FTP>SHOW STATUS

Connected to ALPHA (192.168.1.1)
Logged in as user "SMITH"

The local default is SYS$COMMON:[SYS$LDR]
The remote working directory is /usr/users

Default qualifiers are /VMS

SITE

Issues a site-specific command to the remote server.

Format

SITE command

Equivalents

SITE HELP = HELP /REMOTE SITE = REMOTEHELP SITE = QUOTE HELP SITE

Parameter

command

Site-specific command string to send to the remote host. Enclose the command in quotes if it contains special characters or embedded spaces, or is case sensitive. Site-specific commands can vary depending on the remote FTP server; some servers do not support any.

This command is often useful in obtaining information about the site-specific commands, if any, the remote FTP server supports.

Example

The following sends a site-specific command (SITE SPAWN PRINT MYFILE.TXT) to the remote server. With the TCPware FTP server, requests printing of the MYFILE.TXT file.

FTP>SITE "SPAWN PRINT MYFILE.TXT"

SPAWN

Executes DCL commands without exiting FTP. Note that spawning is not allowed for CAPTIVE accounts.

Format

SPAWN [command-line]

Parameter

command-line

DCL command line you want executed. If omitted, spawns an interactive subprocess. To return from an interactive subprocess, enter LOGOUT.

Synonym

Z [command-line]

Examples

1. The following displays the time on your local host without leaving the FTP client:

FTP>SPAWN SHOW TIME

3-NOV-2021 14:02:48

2. The following initiates DCL command mode, displays the local time, logs out, and returns to the FTP client:

FTP>SPAWN

$ SHOW TIME

3-NOV-2021 14:02:51

$ LOGOUT

Process SMITH_1 logged out at 3-NOV-2021 14:02:54.34

FTP>

STRUCTURE

Changes the default file structure.

The FTP client uses FILE structured files as the default. Use the /[NO]RECORD qualifier for the COPY, GET, or PUT commands to override this default for individual transactions.

Format

STRUCTURE keyword

Parameter

keyword

The below table lists valid values for keyword.

Value	Purpose
FILE	Sets FILE as the default file structure. FILE structured files consist of sequential bytes. Equivalent to SET DEFAULT/NORECORD. This is the default.
RECORD	Sets RECORD as the default file structure. RECORD structured files consists of a collection of records. Equivalent to SET DEFAULT/RECORD.
VMS	Sets VMS as the default file structure. VMS file structure allows you to transfer all types of RMS files between OpenVMS systems using File Descriptor Language (FDL) information. May OpenVMS systems that implement FTP support this structure. Equivalent to SET DEFAULT/VMS.

Note: Some FTP servers do not support the RECORD or VMS structures.

Example

The following changes the default file structure to FILE:

FTP>STRUCTURE FILE

TYPE

Changes the default file transfer format for all future file operations in this session.

The following rules apply to the TYPE command:

· The default file transfer format remains set until you redefine it. It does not change when opening or closing a connection.

· The default format changes only if the remote host accepts the type change.

· If there is no default file format defined, the FTP client tries to determine the file format based on the local file's file extension.

Use the COPY, GET, or PUT command qualifiers to override this default for individual transactions.

Format

TYPE keyword

Equivalents

SET DEFAULT TYPE keyword

TYPE ASCII

TYPE IMAGE

Parameter

keyword

The below table lists valid values for keyword.

Keyword	Purpose
ASCII	Sets formatted ASCII format. Equivalents: · SET DEFAULT/ASCII · ASCII
BINARY	Sets formatted binary format. SET DEFAULT/BINARY is equivalent.
IMAGE	Sets image format. Equivalents: · SET DEFAULT/IMAGE · BINARY · IMAGE
FORTRAN	Sets ASCII format and specifies that the first character of each record is a FORTRAN carriage control character. SET DEFAULT/FORTRAN is equivalent.
BLOCK	Sets block format. SET DEFAULT/BLOCK is equivalent.
VARIABLE	Specifies that FTP writes an image format file as a variable-length record format file. Although FTP writes the records as variable-length, all records are the same length. SET DEFAULT/IMAGE/VARIABLE is equivalent.
DEFAULT	Removes the previous default file format. SET DEFAULT/DEFAULT is equivalent. This is the default setting for an undefined format.

Examples

1. The following changes the default file format to formatted ASCII:

FTP> TYPE ASCII

2. The following removes the previous default file format. For future transactions, the FTP client tries to determine the file format based on the local file's extension.

FTP>TYPE DEFAULT

USER

Sets the username at the remote host. USER requires an open connection.

Format

USER [username [password [account]]]

If you:

· Supply the username, password, and account (if required) with the command, you are not prompted for them separately.

· Omit the parameters from the command line, you are prompted for them.

· Use USER in an interactive command file and do not want to be prompted for a username, enter the username in the file on the line after the USER command. (You cannot include password or account information in the interactive command file.)

· Use the command non-interactively (for example, a batch job), and do not want to be prompted for a username, password, or account, then include the parameters on subsequent lines, after the USER command, in the command file.

· Want to be prompted for a password, do not use the command file with a batch job nor specify the password in a command file.

The display does not echo the password or account information.

Synonym

Parameters

username

Username on the remote host. Enclose the username in quotes if case is important or if it contains special characters. Prompted if omitted.

password

Password on the remote host. Enclose the password in quotes if case is important or if it contains special characters. Prompted if omitted and required. Not echoed.

account

Account on the remote host. Enclose the account in quotes if case is important or if it contains special characters. Prompted if omitted and required. Not echoed.

Example

The following sets the username on the remote host to SMITH, and specifies a password and an account:

FTP>USER "SMITH" "PASSWORD" "SMITH"