Purpose

Use the FTP command to enter the FTP environment. When using the FTP Client API, omit the FTP keyword.

Parameters

-a

NEVER

FTP does not attempt authentication upon initial connection.

GSSAPI

FTP attempts auto-authentication upon initial connection. FTP attempts to authenticate to the FTP server by sending the AUTH command specifying GSSAPI as the authentication type. Once the authentication type is accepted, the authentication protocol proceeds by issuing ADAT commands.

TLS

FTP attempts auto-authentication upon initial connection. FTP attempts to authenticate to the FTP server by sending the AUTH command specifying TLS as the authentication type.

Note: If you specify the TLS parameter, FTP attempts to authenticate for the control connection regardless of how you have configured FTP.DATA. FTP does not protect the data connection unless you have configured FTP.DATA to protect the data connection.

-d

Starts the generation of tracing output. Equivalent to TRACE.

-e

Terminates FTP for certain FTP errors with a nonzero MVS™ return code. Equivalent to EXIT.

-f ftpdata_filename

Specifies the client file. You can specify a z/OS® UNIX file, an MVS data set, or a ddname.

Result: If you specify the -f parameter and the file or data set cannot be used, the client will exit.

Tip: The following are some examples of using the -f parameter to specify the client's FTP.DATA:

• When the FTP client is invoked from the z/OS UNIX shell:
  • To specify a z/OS UNIX file enter:

    ftp -f /etc/ftpascii myftphost

  • To specify an MVS data set enter:

    ftp -f "//'USER12.FTP.DATA'" myftphost

• When the FTP client is called from TSO:
  • To specify a z/OS UNIX file enter:

    ftp -f "/etc/ftpascii" 127.0.0.1

  • To specify an MVS data set enter:

    ftp -f "//'USER1.MYFTP.DATA'" 127.0.0.1

  • To specify an MVS PDS member enter:

    ftp -f "//'SYS1.TCPPARMS(FTPCDATA)'" 127.0.0.1

  • To specify an MVS data set by its ddname enter:

    alloc fi(myftp) da('USER1.MYFTP.DATA') SHR ftp -f "//dd:myftp" 127.0.0.1

Rule: When using the -f parameter from the TSO client, enclose the ftpdata parameter in quotes. For example:

• ftp -f "/u/user1/my.ftp.data" myHost
• ftp -f "//dd:ftpdd" myHost
• ftp -f "//'SYS1.TCPPARMS(MYFTPDAT)'"

-g

Turns off metacharacter expansion (globbing). Equivalent to the GLOB subcommand.

-i

Turns off interactive prompting for MDELETE, MGET, and MPUT subcommands. Equivalent to the PROMPT subcommand.

-n

Inhibits automatic login, preventing the FTP client from prompting the user for a user ID and password or password phrase. If you specify the -n parameter and you have defined a NETRC data set, the data set is not used to log in to this session.

-p tcpip

Indicates the name of the TCP on the local host to which the FTP client should connect. This parameter is ignored if your system is not configured for multiple instances of TCP/IP. This is equivalent to TCP tcpip.

-t data_set_name

Specifies the name of a nonstandard translation table. Equivalent to TRANSLATE data_set_name.

-r

The option -r is the same as -a except that the AUTH command must be accepted by the server. If it is not, then the client ends the session.

Result: If you specify the -r parameter, FTP attempts to authenticate for the control connection regardless of how you have configured FTP.DATA. FTP does not protect the data connection unless you have configured FTP.DATA to protect the data connection.

NEVER

FTP does not attempt to authenticate upon initial connection. This option overrides a value in the FTP.DATA file that would cause authentication.

GSSAPI

FTP attempts auto-authentication upon initial connection. FTP attempts to authenticate to the FTP server by sending the AUTH command specifying GSSAPI as the authentication type. Once the authentication type is accepted, the authentication protocol proceeds by issuing ADAT commands. If the authentication type is not accepted, the client terminates the connection.

TLS

FTP attempts auto-authentication upon initial connection. FTP attempts to authenticate to the FTP server by sending the AUTH command specifying TLS as the authentication type.

-s srcip

Indicates the source IP address that the FTP client uses for connections. You must specify this as an IP address rather than a host name. The address must be a unicast address. INADDR_ANY, the IPv6 unspecified address (in6addr_any), IPv4-mapped IPv6 addresses, and multicast addresses are not supported. If the IP address specified is not a valid home address on the TCP/IP stack, the FTP client cannot connect to the FTP server.

Restriction: Scope information cannot be specified for the source IP address.

-v

Enables verbose mode. This parameter gives you extra information (such as message IDs) when running in z/OS UNIX.

Guideline: When running the FTP client from TSO, use the TSO profile options MSGID and NOMSGID to affix or discard message IDs.

-w nn

Specifies the number of seconds to be used for the TIMEOUT parameters. Equivalent to TIMEOUT nn.

-x

Client attempts to negotiate encryption (data and command protection level of private) immediately after a successful authentication negotiation.

foreign_host

Specifies the name of the host to which you are connecting. Specify the host by its host name or its IP address. The host can be a remote host or your local host. When you use IPv6 link-local addresses, you can provide scope information along with the host name or IP address, as described in support for scope information in the z/OS Communications Server: IPv6 Network and Application Design Guide.

You are prompted for a host name if you do not specify a foreign_host value with the FTP command. If you specify a foreign_host value incorrectly or if the host is not accessible, you enter the FTP environment without connecting to a host. You should then use either the OPEN subcommand to attempt another connection with a host or the QUIT subcommand (or Ctrl-C, in z/OS UNIX) to exit the FTP environment.

port_number

Specifies the port number of the FTP server on the remote host. The default is well-known port 21. The maximum port number that can be specified is 65 534. This parameter should not be used unless you are sure there is a server listening on a port other than the well-known port 21 at the destination.

Exit

Terminates FTP, for certain FTP errors, with a nonzero MVS return code. See FTP return codes for a description of the return code options available for the client.

Exit=nn

Terminates FTP with a nonzero return code of your choice when an FTP error occurs. Valid values are in the range 0 - 4095.

TRACe

Starts the generation of tracing output. TRACe is used in debugging.

TImeout nn

Specifies the number of seconds (nn) to be used for the following TImeout parameters:

• MYOPENTIME
• DCONNTIME
• CCONNTIME
• INACTTIME
• DATACTTIME

The name of each timer corresponds to an FTP.DATA statement available to set that timer. See the FTP.DATA data set statements information in the z/OS Communications Server: IP Configuration Reference for a description of each of these timers and its default value.

Results:

• If the value is not in the range 15 - 85600 or 0, FTP uses the default values for the TImeout parameters.
• If the value is not a number, all TImeout parameter values are set to 0.

TCP tcpip

Indicates the name of the TCP on the local host to which the FTP client should connect. This parameter is ignored if your system is not configured for multiple instances of TCP/IP.

Note: You must specify this value as a parameter, not as a value in the FTP.DATA data set. You can choose to specify this value with the TCPIPJOBNAME statement in the resolver configuration file.

TRANslate data_set_name

Specifies the data set name of a nonstandard translation table. If you specify this parameter, FTP uses the translation table in the user_id.data_set_name.TCPXLBIN data set, rather than the standard translation table provided with TCP/IP (hlq.STANDARD.TCPXLBIN). The hlq.STANDARD.TCPXLBIN data set is never used if you specify the TRANSLATE parameter.

If user_id.data_set_name.TCPXLBIN does not exist, FTP uses hlq.data_set_name.TCPXLBIN. If neither data set exists, or if they were incorrectly created, FTP ends with an error message.

Since the TRANslate parameter also dictates the search order for DBCS translation tables, you might want to use a customized DBCS translation table but not require a modified SBCS translation table. If this is the case, copy hlq.STANDARD.TCPXLBIN into the nonstandard TCPXLBIN translation table data set to ensure that FTP will start.

Notes:

1. Use the CTRLConn and SBDataconn statements in your local FTP.DATA data set to specify different SBCS tables for the control and data connections, or use the LOCSITE SBDataconn subcommand to change the SBCS translation for the data connection. For information on specifying these statements, see Support for SBCS languages.
2. If you require the use of a customized DBCS translation table, but cannot or do not want to use the TRANSlate parameter, you can name the data set such that it is found in the client search order (for example, userid.FTP.TCPdbBIN). See z/OS Communications Server: IP Configuration Reference for information about the DBCS translation table search order. FTP does not terminate because it fails to find a nonstandard DBCS translation table data set.

Usage

• When starting FTP in a TSO environment that includes support for the REXX programming language, you receive the following message:

  CSV003I Requested module IRXSTK not found

  This is a normal informational message when starting FTP in a TSO environment.
• If you enter the FTP flags (-a, -d, -e, -f, -g, -i, -n, -p, -r, -s -t, -v, -w, and -x) from z/OS UNIX the flags must be entered in lowercase. These options can be entered in lowercase or uppercase from TSO.
• GSSAPI authentication is supported only for IPv4 connections. The client fails the negotiation when the connection is IPv6.
• NOOPTMSS is no longer supported and is ignored.
• When FTP is started from the FTP Client API, some of the start parameters are ignored. See the FTP client behavior when started by the FTP Client API information in the z/OS Communications Server: IP Programmer's Guide and Reference for details.

Context

• See Open subcommand—Connect to the FTP server and QUIt subcommand—Leave the FTP environment for more information about the OPEN and QUIT subcommands.
• See FTP return codes for a description of return code handling in the FTP client.
• See Changing local site defaults using FTP.DATA for information about the FTP.DATA data set.
• See z/OS Communications Server: IP Configuration Reference for information about the TCPIP.DATA data set or loading and customizing DBCS translation tables.