Start TCP/IP File Transfer (FTP)

The Start TCP/IP File Transfer Protocol (STRTCPFTP) command is used to start the File Transfer Protocol (FTP) client application that transfers files between systems using the Transmission Control Protocol/Internet Protocol (TCP/IP). FTP is an application protocol used for transferring files to and from a remote system. FTP requires a user ID, and in some cases a password, to gain access to files on a remote system.

Mapping Parameters: Mapping of data is used for all data (for example, user data and protocol data information) between the local and remote systems, except when the EBCDIC subcommand or the BINARY subcommand is in effect. In these cases, mapping of user file data is not done.

The Change FTP Attributes (CHGFTPA) command can be used to specify server mapping tables for FTP.

Parameters

Remote system (RMTSYS)

Specifies the remote system name to which or from which the files are transferred. To be successful, the remote system name must be valid, and the system must be able to communicate with the local system. The user can assign names to an internet address with the Work with TCP/IP host table entries option on the Configure TCP/IP menu (CFGTCP command). Also, a remote name server can be used to map remote system names to internet addresses. You can use the Change remote name server option on the CFGTCP menu to specify a remote name server.

*INTNETADR

The INTNETADR parameter is prompted.

character-value

Specify the remote system name to which or from which the file transfer takes place.

Internet address (INTNETADR)

Specifies the IPv4 or IPv6 internet address of the remote system to which the file transfer application is started.

An IPv4 internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255. An IPv4 Internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address.

An IPv6 internet address is specified in the form xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx, where each x is a hexadecimal digit representing 4 bits. A hexadecimal digit is a number from 0 to 9 or the letter A, B, C, D, E, or F. A "::" may be used once in the IPv6 address to indicate one or more groups of 16 bits of zeros. The "::" may be used to compress leading, imbedded, or trailing zeros in the address.

If the internet address is entered from a command line, the address must be enclosed in apostrophes.

character-value

Specify the internet address of the remote system.

Coded character set identifier (CCSID)

Specifies the ASCII coded character set identifier (CCSID) that is used for single-byte character set (SBCS) ASCII file transfers when the FTP TYPE mode is set to ASCII. ASCII file transfers are also assumed when no TYPE subcommand has been issued. The CCSID value chosen is the default used by the FTP client for ASCII-to-EBCDIC and EBCDIC-to-ASCII mapping. Mapping is determined using the specified ASCII CCSID and the EBCDIC CCSID of the job.

Outgoing and incoming mapping can be done optionally with mapping tables defined in the TBLFTPOUT and TBLFTPIN parameters. Normally the TBLFTPOUT and TBLFTPIN parameters are set to the default of *CCSID or *DFT. Both parameters indicate that the value used in the CCSID parameter is used for mapping. If a mapping table is to be used for outgoing mapping, a table object can be specified in the TBLFTPOUT parameter. The table object specified in the TBLFTPOUT parameter is used instead of the CCSID value.

Incoming mapping can be changed to use a mapping table by specifying a table object in the TBLFTPIN parameter. This mapping table overrides the specified CCSID value and is used for incoming mapping.

Double-byte character set (DBCS) CCSID values are not permitted for this parameter. DBCS values can be specified using the TYPE subcommand.

Note: IBM includes mapping support in FTP to ensure compatibility with releases prior to V3R1. Use of mapping tables for incoming TYPE A file transfers results in the loss of CCSID tagging if the target file must be created. IBM strongly recommends that you use CCSID support for normal operations.

*DFT

The CCSID value 00819 (ISO 8859-1 8-bit ASCII) is used.

1-65533

Specify the CCSID value to be used. This value is validated to ensure a valid SBCS CCSID was requested.

The TBLFTPOUT and TBLFTPIN parameters are used to specify user-defined incoming and outgoing mapping tables. The user-defined mapping tables replace the mapping done by the FTP client when the CCSID parameter is specified.

Port (PORT)

Specifies the port number to be used for connecting to the FTP server.

Normally the "well-known" port value of 21 is used to connect to the FTP server. Under some circumstances, the FTP server may be contacted at a port other than port 21. In those situations, the port parameter may be used to specify the server port to connect to.

Note: The FTP client subcommands OPEN and SECOPEN each have an optional 'port' parameter which may be used to specify a port other than port 21.

*DFT

The value 00021 is used.

*SECURE

The value 00990 is used. Port 990 is reserved for secure FTP servers which immediately use Transport Layer Security (TLS) or Secure Sockets Layer (SSL) protocols to encrypt data.

1-65535

The requested port value is used. This value is validated to ensure it is in the proper range.

Note: If 990 is specified, the FTP client will perform the same functions as if *SECURE were specified.

Secure connection (SECCNN)

Specifies the type of security mechanism to be used for protecting information transferred on the FTP control connection (which includes the password used to authenticate the session with the FTP server). Transport Layer Security (TLS) and Secure Sockets Layer (SSL) are compatible protocols which use encryption to protect data from being viewed during transmission and verify that data loss or corruption does not occur. Kerberos is also supported to do the protection.

Note: The FTP client subcommand SECOPEN can be used to open a protected FTP connection during an FTP client session.

*DFT

If the PORT parameter specifies *SECURE or 990, *IMPLICIT is used; otherwise, *NONE is used.

*IMPLICIT

The FTP client immediately attempts to use TLS/SSL when connecting to the specified FTP server (without sending an AUTH subcommand to the server). If the server does not support implicit TLS/SSL on the specified port, or the TLS/SSL negotiation fails for any reason, the connection is closed.

*SSL

After connecting to the specified FTP server, the FTP client sends an AUTH (authorization) subcommand requesting a TLS/SSL protected session. If the server supports TLS/SSL, a TLS/SSL negotiation performed. If the server does not support TLS/SSL or the TLS/SSL negotiation fails, the connection is closed.

*KERBEROS

After connecting to the specified FTP server, the FTP client sends an AUTH (authorization) subcommand requesting a Kerberos authentication. If the server supports Kerberos, a Kerberos authentication performed. If the server does not support Kerberos or the Kerberos authentication fails, FTP client will switch to normal logon session.

Note: The default credentials cache file for the current user is used to locate existing Kerberos ticket-granting tickets. The Add Kerberos Ticket (ADDKRBTKT) command or the Qshell kinit tool can be used to create or refresh expired tickets.

*NONE

The FTP client does not use encryption when connecting to the specified FTP server.

Data protection (DTAPROT)

Specifies the type of data protection to be used for information transferred on the FTP connection. If security mechanism TLS/SSL is enabled, *DFT *PRIVATE and *CLEAR are valid values which indicate the protection level of FTP data connection. The FTP protocol does not allow protection of the data connection if the control connection is not protected. If security mechanism Kerberos is enabled, *DFT *PRIVATE *CLEAR and *SAFE are all valid value which indicates the protection level of both FTP control connection and FTP data connection

Note: The DTAPROT parameter controls the use of the PROT (protection) FTP server subcommand. The FTP client subcommand SECDATA can be used to change protection during an FTP client session.

*DFT

If the SECCNN parameter specifies Kerberos as security mechanism, *CLEAR is used; otherwise, *PRIVATE is used.

*PRIVATE

If the SECCNN parameter specifies TLS/SSL as security mechanism, it means information sent on the FTP data connection is encrypted. If the SECCNN parameter specifies Kerberos as security mechanism, it means information sent on both the FTP control connection and FTP data connection is integrity and confidentiality protected.

Note: If the SECCNN parameter specifies security mechanism TLS/SSL and specifies that the FTP control connection is not encrypted, *PRIVATE cannot be specified.

*SAFE

Information sent on both the FTP control connection and the FTP data connection is integrity protected.

Note: *SAFE can be only specified when the SECCNN parameter specifies *KERBEROS

*CLEAR

Information sent on the FTP data connection is not protected.

Note: If the SECCNN parameter specifies Kerberos as security mechanism, *CLEAR is the default protection level.

Outgoing ASCII/EBCDIC table (TBLFTPOUT)

Specifies the table object that is to be used to map all outgoing data in the FTP client. Outgoing data is mapped from EBCDIC to ASCII.

If a table object is specified for TBLFTPOUT, the table object is used for outgoing mapping. Otherwise, the CCSID parameter is used to determine outgoing mapping.

Single values

*CCSID

The CCSID parameter is used to determine outgoing mapping.

*DFT

The CCSID parameter is used to determine outgoing mapping.

Qualifier 1: Outgoing EBCDIC/ASCII table

name

Specify the name of the table object to be used by the FTP client for mapping outgoing data.

Qualifier 2: Library

*LIBL

All libraries in the user and system portions of the job's library list are searched until the first match is found.

*CURLIB

The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

name

Specify the name of the library to be searched.

Incoming ASCII/EBCDIC table (TBLFTPIN)

Specifies the table object that is to be used to map all incoming data in the FTP client. Incoming data is mapped from ASCII to EBCDIC.

If a table object is specified for TBLFTPIN, the table object is used for incoming mapping. Otherwise, the CCSID parameter is used to determine incoming mapping

Single values

*CCSID

The CCSID parameter is used to determine incoming mapping.

*DFT

The CCSID parameter is used to determine incoming mapping.

Qualifier 1: Incoming ASCII/EBCDIC table

name

Specify the name of the table object to be used by the FTP client for mapping incoming data.

Qualifier 2: Library

*LIBL

All libraries in the user and system portions of the job's library list are searched until the first match is found.

*CURLIB

The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

name

Specify the name of the library to be searched.

Application identifier (APPID)

Specifies the name of the application identifier to use when using Secure Sockets Layer (SSL) protection. The client application identifier must be configured in the Digital Certificate Manager (DCM) application database.

*DFT

The system supplied default client application identifier QIBM_QTMF_FTP_CLIENT is used.

character-value

Specify the DCM configured client application ID. The first character of the application identifier must be an uppercase character ('A' to 'Z'); the remaining characters can be alphanumeric (uppercase 'A' to 'Z' or digits '0' to '9'). You can also use a period ('.') or underscore ('_').

Examples

Example 1: Starting FTP to an IPv4 Internet Address

STRTCPFTP   RMTSYS(*INTNETADR)  INTNETADR('1.2.3.4')

This command starts the FTP client to the system specified by IPv4 address '1.2.3.4'.

Example 2: Starting FTP to an IPv6 Internet Address

STRTCPFTP   RMTSYS(*INTNETADR)  INTNETADR('2001:D88::1')

This command starts the FTP client to the system specified by IPv6 address '2001:D88::1'.

Error messages

None