3. FTP: Transferring Files

Introduction

The File Transfer Protocol (FTP) transfers files to and from a remote host. FTP-OpenVMS controls the method by which FTP transfers the files.

The Client-FTP utility is your interface to FTP-OpenVMS. You can run Client-FTP interactively or through a startup command procedure.

For FTP-OpenVMS 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. Client-FTP supports multiline recall of up to 20 lines.

Before Using FTP

Before you can transfer files, you need:

• To make sure that the FTP-OpenVMS 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. If you are using TCPware's Token Authentication, the password is the PASSCODE generated on your SecurIDW token.

• The filenaming 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 commands or selections on the graphical user interface windows. The default file format is formatted ASCII.

4 Close or exit the FTP connection.

Features

FTP-OpenVMS includes the following features:

• Command line execution.

• Informational and error status messages.

• Support of wildcards in source filespecs.

Table 3-1 describes some of the features of Client-FTP.

Table 3-1 Client-FTP Features
This feature...	Means that...
Command Line User Interface	Client-FTP allows you to execute FTP commands at the FTP> prompt or through a DECwindows graphical user interface environment. 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*
Case Conversion	Client-FTP no longer converts the user name, password, and account to lowercase if they were not supplied on the OPEN and USER command line and thus prompted for. If you are prompted for these parameters you must enter them in the proper case, since quotes are no longer needed to maintain case.
Status Messages	Client-FTP 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	Client-FTP 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! 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 either the command line user interface, or the graphical user interface if you have a DECwindows system.

Command line method. Use this method if you want to issue commands from the DCL prompt (see Figure 3-1 Opening an FTP Connection Using the Command Line Method).

1 Enter one of the following at the DCL prompt:

$ FTP
FTP>OPEN host

in combination:

– 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 Figure 3-1.

$ FTP[/TLS] host

$ FTP[/TLS] host username password

Enter the host to which you want to connect, the username of the account on the remote host, and the password (PASSCODE if using Token Authentication) 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.

2 Closing and Exiting for the different close options.)

Figure 3-1 Opening an FTP Connection Using the Command Line Method

Closing and Exiting

An FTP connection remains open until you quit or exit FTP, close the connection, or open a new connection.

Command line method. See Figure 3-5:

1 To close an FTP connection, use one of the following commands:

FTP>CLOSE

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

FTP>OPEN host
FTP> CONNECT host

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

2 To exit an FTP session:

FTP>EXIT (or Ctrl/Z)

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

Graphical user interface method. See GET, PUT, and COPY Command Format:

1 To close an FTP connection from the TCPware FTP-OpenVMS File Transfers window, click the Connections option on the menu bar and click the Close... option. The information in the "Remote" part of the screen disappears.

To reopen a connection, click the Connection option on the menu bar and click the Open... option. (Open is initially greyed-out.)

2 To exit from FTP entirely from any of the DECwindows screens, click the File option on the menu bar and click the Exit option.

Figure 3-5 Closing from the Command Line

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 Figure 3-6):

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.

• If you use the menu-driven method, see the "Remote" part of the FTP for TCPware for OpenVMS screen (see Figure 3-3). You can double-click any of the listed directories, change the pathname in the Current Remote Directory field, or use the Go Up button in the middle of the screen.

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

See Table 3-2 in the next section for a description of the file transfer formats.

3 Check the local directory when in FTP: FTP>LDIR

If you use the menu-driven method, see the "Local" part of the FTP for TCPware for OpenVMS screen (see Figure 3-2).

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.

Figure 3-6 Checking Remote and Local Directories

Checking File Transfer Formats

You can determine what file format to use during file transfers. Client-FTP 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 Client-FTP determines the format from the source filename's extension.

See Figure 3-8 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.)

• If you use the menu-driven method, you can make the file type selections in the middle part of the TCPware FTP-OpenVMS File Transfers screen (see Figure 3-4).

Table 3-2 Client-FTP File Transfer Formats
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. Note! 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.

Command line method. Figure 3-7 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 filespec, enclose it in double quotes (" ").

• Separate multiple filespecs with commas.

• If using wildcarded source filespecs (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! 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 filespec.

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

See the GET, PUT, and COPY commands in the Command Reference. The RCP command is also available at the DCL prompt for remote file copies (see Chapter 7, RCP: Copying Files, for details on its use).

Note! FTP-OpenVMS does fast transfers between two OpenVMS systems using VMS file structure or VMS Plus Mode (for HP TCP/IP Services for OpenVMS (UCX) servers). When FTP-OpenVMS 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. See Table 3-2 for the file transfer format descriptions.

Graphical user interface method. To transfer files:

From local to remote	Click one or more files on the "Local" part of the File Transfers screen (see Figure 3-3) and click Copy-->. To give the file a specific name on the remote host, enter a filename in the New Remote File/Dir Name field.
From remote to local	Click one or more files on the "Remote" part of the File Transfers screen (see Figure 3-4) and click <--Copy. To give the file a specific name on the local host, enter a filename in the New Local Name field.

See the following information on symbolically linked UNIX systems.

Figure 3-7 GET, PUT, and COPY Command Format

Symbolic links in UNIX systems. UNIX systems can have files or directories pointing to other files or directories, known as symbolic links. TCPware treats symbolic links as directories, which appear in the Remote Directories field on the menu screens. Once you click and perform an operation on a symbolic link, the directory name disappears from the Remote Directories field and the file to which it points appears in the Remote Files field. You can then treat the file like a regular UNIX file.

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 such as the U.S. Library of Congress (LOCIS.LOC.GOV) 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 Figure 3-8):

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 Alpha V6.1 and later, and all OpenVMS I64 systems, node can be a domain name or IP address.

2 Use the filespec syntax described in Figure 3-8 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

Figure 3-8 shows examples of how to allow or deny anonymous user access to remote resources.

Figure 3-8 Anonymous User Access

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 Figure 3-9 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 Client-FTP, 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, Client-FTP:

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

Figure 3-9 Setting Up a Startup Command File

Site-Specific Commands

The FTP-OpenVMS Server supports the SITE SPAWN and SITE SHOW TIME site-specific commands. The Client-FTP 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 FTP-OpenVMS site-specific commands in one of the following ways at the FTP> prompt (see Figure 3-10):

1 SITE SHOW TIME

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

2 SITE SPAWN dcl-command

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.

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! Spawning is not allowed for CAPTIVE accounts.

See the SITE and SPAWN commands in the Command Reference.

Figure 3-10 Issuing Site-Specific Commands

Sample Session

This section describes a sample FTP-OpenVMS session.

See Figure 3-11 for the corresponding numbered steps. In this example, a user on local host BETA:

1 Starts Client-FTP, opens a connection to remote host THETA, and logs in as user SMITH (the display does not echo the password at the prompt). (If you are using Token Authentication, enter your PASSCODE in place of the password here.)

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

Figure 3-11 Sample FTP-OpenVMS Session

Command Reference

The following pages describe the FTP-OpenVMS commands. Table 3-3 contains command synonyms you can use interchangeably with FTP-OpenVMS commands. Table 3-4 shows commands you can use to do various tasks. Each command includes the graphical user interface equivalent, if available.

Enter FTP commands at the FTP> prompt. Client-FTP 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

Table 3-3 FTP 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

Table 3-4 Commands to Use to Perform Various Tasks on the Local System
DEFINE/KEY	Associate an equivalence string and set of attributes with a keyboard key
HELP	Bring up the Client-FTP 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	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)

Table 3-5 Commands to Use to Perform various Tasks on the Remote System
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

Table 3-6 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

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_ADD_CC_ON_FIXED_RECORD_FILES

If this logical is defined to TRUE and a file is transferred as TYPE IMAGE with QUOTE SITE RMS BLOCK OFF in effect, the FTP server will separate the records of a fixed length record file with the linefeed character. This is useful for avoiding the explicit conversion necessary when transferring the file to a non-VMS system with an FTP client that is not able to do record mode transfers.

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.

$ DEFINE /SYSTEM /EXEC TCPWARE_FTP_DISALLOW_UNIX_STYLE FALSE

TCPWARE_FTP_EXTENSION_QUANTITY

Defines the default allocation/extension quantity for new files and appends. The ? in the logical represents where defined values go. Defined values can be either alpha or numeric.

$ DEFINE /SYSTEM /EXEC TCPWARE_FTP_EXTENSION_QUANTITY n (number of blocks)

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.

$ DEFINE /SYSTEM /EXEC TCPWARE_FTP_IGNORE_UNIX_DASH_OPTIONS FALSE

TCPWARE_FTP_KEEP_DIR_EXT

Sometimes the FTP server strips the .DIR extension from the file name of a directory when the NLST function is requested. The FTP server now looks for the logical TCPWARE_FTPD_KEEP_DIR_EXT and, if defined, does not remove the .DIR extension. To use this feature, define the logical as:

$ DEFINE TCPWARE_FTPD_KEEP_DIR_EXT TRUE

To return to the default behavior, deassign this logical.

TCPWARE_FTP_MESSAGE_FILE

Defines the message file the FTP user sees when connecting to the server or moving between directories. The definition of this logical is commented out but defined in the FTP_CONTROL.COM file as follows:

$ DEFINE TCPWARE_FTP_MESSAGE_FILE ".MESSAGE"

TCPWARE_FTP_NOKEEPALIVES

If this logical is defined, the FTP server will not send keepalives on the control channel. The KEEPALIVE command allows the FTP client program to toggle, whether or not it desires keepalives to be sent on the control channel. The SET [NO]KEEPALIVE command allows the FTP client to explicitly set whether or not it desires keepalives on the control channel.

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. The ? in the logical represents where defined values go. Defined values can be either alpha or numeric.

$ DEFINE TCPWARE_FTP_SEMANTICS_FIXED_IGNORE_CC ?

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.

$ DEFINE TCPWARE_FTP_SEND_FEAT_ON_CONNECT 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_SERVER_LOG_LIMIT

By setting this logical in the LOGIN.COM file, you can specify that log files be retained. Set the logical name to a dash (-) to retain all log files, or specify a number in the range of 1 to 32000.

Directory size restrictions limit the number of potential files that can actually be created. If you do not specify a number or value, one log file is created or overwritten for each FTP session. Use the DCL PURGE command to delete unneeded log files. The following example specifies that 42 log files be retained:

$ DEFINE TCPWARE_FTP_SERVER_LOG_LIMIT 42

TCPWARE_FTP_STRIP_VERSION

Causes VMS mode output to have no versions. The ? in the logical represents where defined values go. Defined values can be either alpha or numeric.

$ DEFINE /NOLOG TCPWARE_FTP_STRIP_VERSION ?

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_BY_DEFAULT

If you define this logical, the FTP server starts in UNIX emulation mode.

The ? in the logical represents where defined values go. Defined values can be either alpha or numeric.

$ DEFINE /NOLOG TCPWARE_FTP_UNIX_STYLE_BY_DEFAULT ?

When sending the command from a non-OpenVMS client, a space is required between the file specification and the qualifier. For example:

$ GET filename /LOG

Previous command syntax: ftp>put xx x.x/image=2048
New command syntax: ftp>put x.x “x.x/image=2048”

You can disable this feature so that the FTP server can accept an OpenVMS transfer mode qualifier without including the space between the file specification and the qualifier. To disable this requirement, define the logical:

$ DEFINE TCPWARE_FTPD_NOUNIX_SYNTAX “TRUE”

TCPWARE_FTP_UNIX_STYLE_CASE_INSENSITIVE

Allows UNIX style filename handling to be case insensitive. The ? in the logical represents where defined values go. Defined values can be either alpha or numeric.

$ DEFINE /NOLOG TCPWARE_FTP_UNIX_STYLE_CASE_INSENSITIVE ?

TCPWARE_FTPD_NOUNIX_SYNTAX

When sending a command to a non-OpenVMS client, a space is required between the file specification and the qualifier. For example:

FTP>GET filename /LOG

$ DEFINE /SYSTEM /EXECUTIVE_MODE TCPWARE_FTPD_NOUNIX_SYNTAX “TRUE”

Troubleshooting

Access error messages help by entering HELP TCPWARE MESSAGES [identifier], or connect to web site http://www.process.com (select Customer Support followed by the Error Messages button).

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

Example

The following closes the current connection:

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

Graphical User Interface Equivalent

TCPware FTP-OpenVMS File Transfers Þ Connection Þ Close

or Open

Format

CLOSE

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 filespecs except wildcard symbols enclosed in a quoted string. Use the /MULTIPLE qualifier for a wildcard remote source filespec. /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 filespec. Use a comma between multiple filespecs. Enclose the filespec in quotes if you want to preserve case and did not use the SET NOLOWERCASE command. The format is:

node"username password"::path

node	hostname or DECnet node name (with OpenVMS Alpha V6.1 and later, and all OpenVMS I64 systems, the hostname can be a domain name or IP address)
username	valid account on the host
password	password (PASSCODE if using Token Authentication) for the account
path	location and name of the file

You can omit the node"username password":: part of the specification unless it is for a DECnet file. If omitted, Client-FTP uses the current default directory. You can use the node::path syntax (omitting the username and password) if you want access to anonymous FTP resources. In this case, FTP-OpenVMS implicitly adds the /ANONYMOUS qualifier.

Use the /LOCAL or /REMOTE qualifier after the parameter, depending on the context. The local filespec must conform to OpenVMS filenaming rules. The remote filespec must conform to the filenaming conventions of the remote host.

Enclose the pathname in quotes if it contains delimiters or symbols the FTP server could possibly misinterpret. For example, the following remote filespec is enclosed in quotes because it includes slashes (/) that OpenVMS normally interprets as qualifier delimiters:

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

destination

Output filespec. Enclose the filespec in quotes if you want to preserve case and did not use the SET NOLOWERCASE command. If wildcarded (*), Client-FTP uses the source filename or extension, unless the filespec is a quoted string. See the source parameter for the destination filespec 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, Client-FTP searches for a node; if found, Client-FTP 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, Client-FTP searches for a node; if found, Client-FTP 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, Client-FTP 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 Client-FTP File Transfer Formats ).

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

/ASCII

Transfers the preceding file in formatted ASCII format (see Client-FTP File Transfer Formats ).

/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 (see Client-FTP File Transfer Formats ).

/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 (see Client-FTP File Transfer Formats ). 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, Client-FTP 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 (see Client-FTP File Transfer Formats ). Allows you to transfer any type of RMS file between OpenVMS systems. If you use /VMS, Client-FTP ignores /APPEND, /ASCII, /BINARY, /BLOCK, /FORTRAN, /IMAGE, and /VARIABLE. If you specify both /RECORD and /VMS, Client-FTP 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, Client-FTP 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 (default)

/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, Client-FTP 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 (default)

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

/LOG
/NOLOG (default)

/LOG displays file specifications for each file transferred. /NOLOG 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 facts currently supported are:

• 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 filespec, 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.

Graphical User Interface Equivalent

TCPware FTP-OpenVMS File Transfers Þ Enter new directory name in
New Remote File/Dir Name Þ Make Dir>

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, Client-FTP 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. Table 3-7 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 Client-FTP. 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.

Table 3-7 Key Designations for Three Terminal Types
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 (default)

/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 (default)

/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 Client-FTP uses the current state.

Establish states using /SET_STATE.

/LOCK_STATE
/NOLOCK_STATE (default)

/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 (default)

/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 (default)

/TERMINATE specifies that Client-FTP terminates (effectively executes) the current equivalence string when someone presses the defined key. /NOTERMINATE 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.

Some remote hosts might not support file or directory deletion operations.

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. If used with the /DIRECTORY qualifier, you can indicate the remote directory 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, Client-FTP 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 for access to an anonymous user directory. The /ANONYMOUS qualifier is implicit.

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

Note! SET DEFAULT can change the defaults indicated for the following qualifiers.

/CONFIRM
/NOCONFIRM (default)

/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 particular filename to relate to that file only.

/DIRECTORY

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

/IGNORE
/NOIGNORE (default)

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

/LOG
/NOLOG (default)

/LOG displays file specifications for each file deleted.

/MULTIPLE

Deletes multiple files (equivalent to MDELETE). You must include wildcards in the filespec. /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 filespec on the remote host. Enclose in quotes if you want to preserve case and did not use the SET NOLOWERCASE command, or the filespec contains delimiters or symbols the FTP server can interpret in special ways. Use a comma between multiple filespecs. The remote filespec must conform to the filenaming 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

ENABLE VMS_PLUS

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 FTP-OpenVMS 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, Client-FTP uses the status value of the last error.

Note! Client-FTP 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, Client-FTP closes it before exiting.

Format

EXIT

Synonyms

QUIT

BYE

GET

Copies files from a remote host.

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

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 filespec must conform to the filenaming 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 filespec 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 filespecs are *.txt , W????.*, and *.*;*.

local-filename

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

node"username password"::path

node	hostname or DECnet node name (with OpenVMS Alpha V6.1 and later, and all OpenVMS I64 systems, the host name can be a domain name or IP address)
username	valid account on the host
password	password (PASSCODE if using Token Authentication) for the account
path	location and name of the file

You can omit the node"username password":: part of the specification unless it is for a DECnet file. If omitted, Client-FTP uses the current default directory.

You can use the node::path syntax (omitting the username and password) if you want access to anonymous FTP resources, in which case the /ANONYMOUS qualifier is implied.

Qualifiers

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

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

• The extension (type) of the file you want copied (see Client-FTP File Transfer Formats ).

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). (See Anonymous Users.)

/APPEND

Appends the remote-file file to the local-filename. If the local-filename does not exist, Client-FTP 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 (see Client-FTP File Transfer Formats ).

/BINARY

Transfers .BIN, .LDA, .OBJ, and .STB, files in formatted binary format (see Client-FTP File Transfer Formats ).

/BLOCK

Transfers STREAM, STREAM_CR, STREAM_LF, and UNDEFINED files in block mode (see Client-FTP File Transfer Formats ).

/CONFIRM
/NOCONFIRM (default)

/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, Client-FTP 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 (see Client-FTP File Transfer Formats ). The first character of each record is a FORTRAN carriage control character. Some hosts do not recognize this transfer format.

/IGNORE
/NOIGNORE (default)

/IGNORE ignores errors so that copying can continue with the next file. /NOIGNORE 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 (see Client-FTP File Transfer Formats ). Does not apply to remote output files.

/LOG
/NOLOG (default)

/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, Client-FTP 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 facts currently supported are:

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 (see Client-FTP File Transfer Formats ). Allows you to transfer any type of RMS file between OpenVMS systems. A positional qualifier. If you use /VMS, Client-FTP ignores /APPEND, /ASCII, /BINARY, /BLOCK, /FORTRAN, /IMAGE, and /VARIABLE. If you specify both /RECORD and /VMS, Client-FTP 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 Client-FTP online help.

Client-FTP 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-FTP 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 on-line 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]

Equivalent

SPAWN DIRECTORY [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.

If you are designated by the system administrator as having password authentication using Token Authentication, you need to enter the PASSCODE in place of the password. Depending on which type of SecurID card you were assigned:

• Enter a combination of your personal identification number (PIN) and the tokencode that appears on the card (with no separating space) as the password, or

• Enter your PIN on the PINPAD] card and the resulting tokencode that appears on the card as the password.

See Chapter 15, Token Authentication: Protecting Logins, for details on obtaining PASSCODEs. account

Account on the remote host. Enclose the account in quotes if the case is important or it contains special characters.

Qualifiers

/PORT=port

Port number for the remote FTP server. If omitted, Client-FTP 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! Data transfers will not be encrypted until a PROTECTION PRIVATE command has been issued.

/VMS (default)
/NOVMS

/VMS negotiates for VMS file structure. /NOVMS does not. If omitted, SET VMS or SET NOVMS determines the outcome (see the SET VMS command for details).

Note! 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 have to 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"

3 The following DCL level command opens a connection to SYS1, but uses a Token Authentication PASSCODE derived from the SecurID card, instead of the password:

$ FTP OPEN SYS1 "smith" "1234987654"

PROTECTION

Set the protection for the data port after doing TLS authentication. RFC 2228 defines CLEAR, PRIVATE, SAFE and CONFIDENTIAL, but RFC 4217 specifies that only CLEAR and PRIVATE can be used with TLS. 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 filespecs except wildcards enclosed in a quoted string. Use the
/MULTIPLE qualifier for a wildcarded local-file filespec. 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 filespec on the local host. Must conform to OpenVMS filenaming rules. Use a comma between multiple filespecs.

The filespec format is:

node"username password"::path

node	hostname or DECnet node name (with OpenVMS Alpha V6.1 and later, and all OpenVMS I64 systems, the host name can be a domain name or IP address)
username	valid account on the host
password	password (PASSCODE if using Token Authentication) for the account
path	location and name of the file

You can omit the node"username password":: part of the specification unless it is for a DECnet file. If omitted, Client-FTP uses the current default directory.

You can use the node::path syntax (omitting the username and password) if you want access to anonymous FTP resources, in which case the /ANONYMOUS qualifier is implied.

wildcarded-local-files

Input filespec 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 filespecs are *.TXT , W????.*, and *.*;*.

remote-filename

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

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

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

The remote filespec 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), Client-FTP transfers the file based on either:

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

• The extension (type) of the file you want copied (see Table 3-2).

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 Client-FTP 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 Client-FTP'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 filespec must conform to the filenaming conventions of the remote host. Enclose the filespec in quotes if it contains delimiters or symbols the FTP server can interpret in special ways. If a remote OpenVMS file, the specification is:

node"username password"::path

node	hostname or DECnet node name (with OpenVMS Alpha V6.1 and later, and all OpenVMS I64 systems, the host name can be a domain name or IP address)
username	valid account on the host
password	password (PASSCODE if using Token Authentication) for the account
path	location and name of the file

You can omit the node"username password":: part of the specification unless it is for a DECnet file. If omitted, Client-FTP uses the current default directory. You can use the node::pathsyntax (omitting the username and password) if you want to rename anonymous FTP resources, in which case the /ANONYMOUS qualifier is implied.

new-name

Valid filespec 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). (See Anonymous Users.)

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.

Note! SET DEBUG /CLASS=REPLIES (or VERBOSE toggled to ON) is the default. In this way, you can see informational messages when logging in to the server or changing remote directories (if informational messaging is enabled on the server).

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 Table 3-8. The initial default is PERFORMANCE and REPLIES. Use NONE as the first entry to clear the classes before resetting them (see Example 1).

Table 3-8 Class Keywords
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, Client-FTP sets the default directory to the parent of the current directory on the remote host.

• With SET DEFAULT /LOCAL, Client-FTP 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 (default)

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. (See Anonymous Users.)

/[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 (see Client-FTP File Transfer Formats ). 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, Client-FTP 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 Client-FTP sends the files to the remote host. SET LOWERCASE is the default.

With SET NOLOWERCASE, Client-FTP does not convert unquoted filenames to lowercase.

Note! Client-FTP 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.

Note! 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 Client-FTP 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.

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

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

See Client-FTP File Transfer Formats for more information.

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

Format

SET VMS (default)
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 FTP-OpenVMS server, requests printing of the MYFILE.TXT file.

FTP>SITE "SPAWN PRINT MYFILE.TXT"

SPAWN

Executes DCL commands without exiting FTP.

Note! 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 Client-FT:

FTP>SPAWN SHOW TIME

3-NOV-2014 14:02:48

2 The following initiates DCL command mode, displays the local time, logs out, and returns to Client-FT:

FTP>SPAWN

$ SHOW TIME

3-NOV-2014 14:02:51

$ LOGOUT

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

FTP>

STRUCTURE

Changes the default file structure.

Client-FTP 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

Table 3-9 lists valid values for keyword.

Table 3-9 STRUCTURE Command Keyword Values
Value	Purpose
FILE	Sets FILE as the default file structure. FILE structured files consists 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, Client-FTP 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 qualifier

ASCII= TYPE ASCII

BINARY= TYPE IMAGE

IMAGE= TYPE IMAGE

Parameter

keyword

Table 3-10 lists valid values for keyword. See Client-FTP File Transfer Formats for a full description of the file transfer types.

Table 3-10 TYPE Command Keyword Values
Keyword	Purpose
ASCII	Sets formatted ASCII format (see Client-FTP File Transfer Formats ). Equivalents: • SET DEFAULT/ASCII • ASCII
BINARY	Sets formatted binary format (see Client-FTP File Transfer Formats ). SET DEFAULT/BINARY is equivalent.
IMAGE	Sets image format (see Client-FTP File Transfer Formats ). 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 (see Client-FTP File Transfer Formats ). SET DEFAULT/FORTRAN is equivalent.
BLOCK	Sets block format (see Client-FTP File Transfer Formats ). 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, Client-FTP 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 user name, 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

LOGIN

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.

If you are designated by the system administrator as having password authentication through Token Authentication, you need to enter the PASSCODE in place of the password. Depending on which type of SecurID card you were assigned:

• Enter a combination of your memorized personal identification number (PIN) and the tokencode that appears on the card (with no separating space) as the password, or

• Enter your memorized PIN on the PINPAD] card and the resulting tokencode that appears on the card as the password.

See the Chapter 15, Token Authentication: Protecting Logins, for details on obtaining PASSCODEs.

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"