Adapter Properties and Commands

FTP adapter commands

The following table lists valid commands for the FTP adapter, the command syntax, and whether the command is supported (✓) for data sources, targets, or both.

Account

Specifies the account required to connect to an FTP server. If the account is required to log on, account_id must be specified. The corresponding adapter command is -AC or (-ACCT account_id).

account_id: Specifies the account for connecting to an FTP server.

Audit

Generates a log file in the map directory where the adapter is installed with the default name m4ftp.log. The log file records audit information with details such as files sent or received from each host, elapsed time, file size, and retry count for each file.

The corresponding adapter command is: -AUDIT or -A

-AUDIT[+][S] [full_path]

For example:

+-> Appends audit information to the existing log file. If no log file exists, a new one will be created.

S-> Summary mode, recording only minimal information in the log file.

full_path-> Creates an audit file with the specified name in the specified directory. By default, the directory is where the map is located, and the file name is m4ftp.log.

Client Certificate

Specifies the label of the client certificate in the key store. This command is applicable only when the SSL_CLIENT secure_mode setting in the config.yaml file is set, and SSL/TLS encryption is in effect.

The corresponding adapter command is -CERT {label}.

label: The name of the entry in the certificate store, which is specified by the key_store field in the config.yaml file.

Code Page Local

Specifies the code page of the data on the local system. The local system is the system on which the IBM Sterling Transformation Extender is running.

Use this command with the TYPE=ASCII feature of the -URL command. This command must be used if the Code Page Remote adapter command (-CPR) is specified.

This command is only valid on z/OS systems. The default value is the default EBCDIC code page for your system.

The corresponding adapter command is -CPL code_page_name.

code_page_name: Specifies the code page name of the data on the local system.

For more information, see the description of the atoe_l function in the IBM z/OS C/C++ Run-Time Library Reference.

Code Page Remote

Specifies the code page of the data on the remote system, from which or to which the data is being transferred. This command is only valid on z/OS systems; the default value is ISO 8859-1.

Use this command with the TYPE=ASCII feature of the -URL command. This command must be used if the Code Page Local adapter command (-CPL) is specified.

The corresponding adapter command is -CPR code_page_name.

code_page_name: Specifies the code page name of the data on the local system.

Fail

Specifies the error codes that cause the adapter to fail and disconnect from the FTP server. This is an optional command.

The default behavior of the FTP adapter is to pass 100 and 200-level error codes and to fail only on 300, 400, and 500-level error codes as defined in RFC 959. Any other error codes returned are ignored. Using the Fail adapter command, you can specify the error codes, such as from third-party data, for which the adapter fails.

The Fail adapter command requires a numerical integer for the error code. If necessary, you can specify multiple error codes.

The corresponding adapter command is -FAIL.

-FAIL error_code[:error_code…]

error_code: Any numerical integer return code except 100, 200, 300, 400, and 500 level FTP error codes as defined in RFC 959 that you want the adapter to fail on.

Use a colon (:) to separate multiple error codes. For example, the following command indicates that the adapter will fail on return codes 13 and 24:

-FAIL 13:24

Firewall Connection Method

The corresponding adapter command is -FW or (-FIREWALL).

Generally, the command format is written as:

-FIREWALL FTP://[fw_user[:fw_pass]@][fw_host[:fw_port]]/method

fw_user: Specifies the username required for connecting to the proxy server. Unless you specify a password, this parameter must be followed by @ if you specify fw_host.

:fw_pass: Specifies the password required to authenticate the username. This parameter must be followed by @ if you are also specifying fw_host.

fw_host: Specifies the name (or address) of the proxy server to which to connect.

:fw_port: Specifies the name (or number) of the port to use for connection.

TRANSPARENT is the only method directly connecting to the FTP server; all other methods connect to the firewall. For more information on the FTP variables shown in the Connect Information column, see the section for the FTP URL (-URL) adapter command.

Adapter behavior when the -FIREWALL command Is present

A firewall isolates and restricts some computers from reaching other computers.

Only a small part of the FTP adapter knows its presence if a firewall is mentioned.

Without a firewall, the start of a file transfer begins with:

• Establish a Socket connection to the remote host.
• Issue the USER command over the connection.
• Issue the PASS command over the connection.

When a firewall is used, more steps are performed at the beginning of the file transfer.

These steps depend on the method specified in the last part of the -FIREWALL command.

OPEN - Establish a Socket connection to the firewall host and issue the following command over the connection in this order:

OPEN ftp_host USER ftp_user PASS ftp_pass

SITE - Establish a Socket connection to the firewall host and issue the following command over the connection in this order:

USER fw_user PASS fw_pass SITE ftp_host USER ftp_user PASS ftp_pass

TRANSPARENT - Establish a Socket connection to the firewall host and issue the following command over the connection in this order:

USER fw_user PASS fw_pass USER ftp_user PASS ftp_pass

USERFW - Establish a Socket connection to the firewall host and issue the following command over the connection in this order:

USER ftp_user@ftp_host fw_user PASS ftp_pass USER ftp_user PASS ftp_pass

USERFWPASS - Establish a Socket connection to the firewall host and issue the following command over the connection in this order:

USER ftp_user@fw_user@ftp_host PASS ftp_pass@fw_pass

USERLOGON or USER - Establish a Socket connection to the firewall host and issue the following command over the connection in this order:

USER fw_user PASS fw_pass USER ftp_user@ftp_host PASS ftp_pass USER

USERLOGONFW or USERFW - Establish a Socket connection to the firewall host and issue the following command over the connection in this order:

USER fw_user@ftp_host PASS fw_pass USER ftp_user PASS ftp_pass

URL syntax

As the syntax for the rest of the URL varies depending on the scheme selected, URL schemes use direct IP-based protocol for a specified host on the Internet follow a common syntax for the scheme-specific data:

//user:password@host:port/url_path

The scheme-specific data may exclude some or all parts of the following components: user:password@, :password, :port, and /url_path

The scheme-specific data starts with a double slash (//), indicating compliance with the common Internet scheme syntax. The user: password component conforms to the following rules:

user: An optional username. Some schemes allow the specification of a username.

password: An optional password. When present, it follows the username and is separated by a colon. The username and password are followed by an at sign (@). Any :, @, or / characters must be encoded. See URL encoding.

The url_path of an FTP URL has the following syntax:

cwd1/cwd2/.../cwdN/name; type = xfer_type

Where cwd1 through cwdN and name are possibly encoded strings and xfer_type is one of the characters a, i, or d. The part;type= xfer_type be omitted. The cwdx and name parts are empty. The whole url_path be omitted, including the /, delimiting it from the prefix containing user, password, host, and port.

The url_path is interpreted as a series of FTP commands as follows:

• Each cwd element will be sequentially supplied as the argument to a CWD, change working directory, command.
• If the type code is "d," perform an NLST, name list, or command with name as the argument and interpret the results as a file directory listing.
• Otherwise, perform a TYPE command with xfer_type as the argument and then access the file named name. For example, using the RETR command.

  The xfer_type argument has been extended beyond what the RFC supports, specifically the D1, D2, D3, and D4 sections. Also, host:port be excluded, although it is rarely useful to do so; the host defaults to localhost.

FTP URL

Specifies the file names to be retrieved (adapter source) or created and appended (adapter target). This command is required to establish a connection to an FTP server.

The corresponding adapter command is -URL

Generally, the command format is:

-URL [FTP:[//]][ftp_user[:ftp_pass]@][ftp_host[:ftp_port]]
[/[/]][dir/[dir/...]] [filename][;type=xfer_type[+]]

If specified, an additional forward slash (/) is required to separate the user and host parameters from the file and transfer type.

GXS

Allows proper connectivity with the GXS VAN using an FTPS connection. The corresponding adapter command is -GXS.

When this command is in use, the -IMPLICIT adapter command is not necessary.

Generally, the command format is:

-TV -GXS -URL FTPS://john_doe:1234@gxsics.com/send/sendfile;type=A

This command performs several functions:

-TV-> Creates a trace verbose file in the directory where the map is located.

-GXS-> Specifies that a GXS (-GXS) secure connection to the server is used.

_URL FTPS://-> Specifies sending the file using FTPS to the URL address secure.com.

User id and Password-> Specifies the user id name John Doe and a password of 1234 is used to login to this account.

/Send/-> Specifies send will be the directory where the send file is stored.

sendfile;type=A-> specifies that sendfile will be transferred in ASCII mode (type=A).

Ignore

Allows the adapter to ignore the specific FTP error codes. The corresponding adapter command is -I or (-IGNORE).

-IGNORE error_code[:error_code...]

error_code: Specifies the FTP error codes that the adapter should ignore. A colon (:) should be used to separate multiple error codes.

For example, if you specified the command: -I450:550. The adapter ignores errors of type 450 (file busy) and errors of type 550 (file not available) and returns a zero-length file to the map.

Implicit

Specifies implicit FTPS secure connections to a server for sending or receiving data. This command implies the use of port number 990 as the default. If an alternate port number is required, it must be included on the command line after the specified URL. For example, ftps://secure.com:6377.

The corresponding adapter command is -IMPLICIT.

For example:

-TV -IMPLICIT -URL FTPS://john_doe:1234@secure.com/upload/mail_list;type=A

This command performs several functions:

-TV: Creates a trace verbose file in the directory where the map is located.

-IMPLICIT: Specifies that an implicit (-IMPLICIT) secure connection to the server is used.

-URL FTPS://: Specifies sending the file using FTPS to the URL address secure.com.

user id and password: Specifies the user id name John Doe and a password of 1234 are used to login to this account.

upload/mail_list;type=A: Specifies that the send file will be named mail_list after being transferred in ASCII mode (type=A).

Keep Server

Specifies in a map rule that when retrieving a file from an FTP server, it should not be deleted after transfer. This is an optional command. This option should be used if this behavior is required when using the GET mapping function. Alternatively, when running the adapter from an input card, the same behavior can be accomplished using the card property, OnSuccess, by setting it to Keep.

The corresponding adapter command is -KS.

For example:

-KS -URL ftp://user:pass@server/file.txt

List Option

Allows files to be retrieved based on a user supplied sorting preference. This command is used with the existing FTP URL (-URL) adapter command and supports a subset of FTP options that control the sequence of file transfers. This is an optional command.

The corresponding adapter command is -LS

-LS sort_type

The adapter passes the -LS command value to a remote FTP server as an argument when it lists the files in the directory. One of three events happens:

• The FTP server accepts the option and lists the files in the specified order.
• The FTP server ignores the option and lists the files in the default order.
• The FTP server rejects the option, and the adapter returns an error.

For example:

-URL ftp://testftp:test@host/mydir -ls tr

The -LS command is issued by the adapter before any file transfer, so that its results are used to control the order of the file transfer. In the example above, all files from mydir would be transferred, the oldest file being transferred first.

The following are the command options that are allowed:

t-> Sorts by time stamp.

r-> Reverses the order of sort.

tr-> Reverses the order of sort by time stamp.

rt-> Same as -LS tr.

All other list options result in the error message: invalid ls option logged in the adapter trace file.

Some FTP servers can ignore the List Option (-LS) command options (t, r, tr, and rt).

Make Directory

Creates a directory. For instance, if a file specified in a PUT operation belongs to a directory that does not exist, this command creates a new directory. If the command is not specified and the file specified on a PUT operation points to a directory that does not exist, the adapter will fail. This is an optional command.

The corresponding adapter command is -MKD.

For example:

PUT("FTP", "-URL ftp://jdoe:secret@server1/some/folder/ data.txt -MKD", "Some data")

This will force jdoe/some and create the jdoe/some/folder. A new file called data.txt will be added to this new directory.

Move

Moves files from their original location on the source FTP server to a different location on the source FTP server after the files have been transferred to the target server. On the Move adapter command, you can specify a new name for the original source file as a different file name, path, or both.

The FTP Adapter typically provides options for deleting or keeping files on the source FTP server after they are transferred to the target FTP server. The Move command provides additional functionality that permits you to move the files to a different location on the source server, as opposed to, for example, deleting them.

The corresponding adapter command is -MOVE.

For example:

-MOVE [file_name | directory_location]

file_name: Specifies the new name on the source FTP server for the transferred original file. This can be specified as the source file's absolute (fully qualified) or relative path.

directory_location: Specifies the different directory or subdirectory names on the source FTP server for the original or transferred files. The directory name must be terminated with a path separator. Examples include backward slash (\) for Windows and forward slash (/) for UNIX environments.

If the directory does not exist and the MKD option is also specified on the command line, the directory will be created relative to the current location of the file or files on the source FTP server that have already been downloaded.

The adapter will fail if the directory does not exist, and the MKD option is not specified on the command line.

If you are unsure that the directory exists, use the MKD option. When you specify this command option whether the directory exists, the adapter command will avoid a failure result. If the directory does exist, the MKD option will not attempt to create the directory and the adapter command will continue.

Platform-specific FTP Server limitations

The Move adapter command functionality is subject to platform-specific FTP Server limitations. For example, on z/OS environments, the -MOVE option cannot be executed across different file systems. The Hierarchical File System (HFS) on your UNIX System Services (USS) environment cannot move a file to a data set.

Passive Mode

Specifies that only passive mode should be used for the FTP data connection. This command is primarily useful for firewalls and is considered a preferred connection method for security reasons.

By default, the adapter attempts to connect using passive mode. If unsuccessful, the adapter uses Port Mode. See the Port Mode adapter command (-PT). During a passive mode connection, the server listens for the connection and dictates where the adapter is to connect. Older servers might not support passive mode.

The corresponding adapter command is -PV or (-PASV).

Port Mode

Specifies that only port mode should be used for the FTP data connection. This older connection method might be the only way to connect on older servers. The corresponding adapter command is -PT or -PORT.

By default, the adapter attempts to establish a connection using passive mode. If the adapter is unsuccessful, it uses port mode. See the Passive Mode adapter command -PV.

Submit command after file transfer

Submits a specified command to the FTP server after each file transfer occurs. The corresponding adapter command is -PQUOTE.

-PQUOTEcommand.

command: The command or command string will be submitted to the FTP server.

For example:

The following command records the size of the test.dat file in the adapter trace file after the file transfers:

-PQUOTE 'size test.dat'

Quantity

Specifies the number of files retrieved by the adapter.

In burst mode, each burst might return fewer messages than specified, but the total number of messages returned by the adapter will not exceed the value set by the -QTY command. If not specified, the default quantity is the FetchUnit size of the burst.

The corresponding adapter command is -QTY

-QTYnumber.

number: The number of files to be retrieved by the adapter.

If you want the maximum number of files retrieved in burst mode infinite, you must set the -QTY command option number to 'S' and specify "-LSN 0" on the command line. The -LSN command is currently unsupported; however, it must only be used with the -QTY command in this scenario.

Submit command before file transfer

Submits a specified command to the FTP server when the connection is established and immediately before each file transfer occurs. The corresponding adapter command is -QUOTE.

-QUOTE command.

command: The command or command string is to be submitted to the FTP server.

The following command submits the TYPE B 6 command to a System i® server:

-QUOTE 'TYPE B 6'

Site

Sends an FTP server-specific site command to the FTP server software. The corresponding adapter command is -SITE.

-SITE'command_text'.

'command_text': Specify the FTP-server-specific site command, enclosed in single quotation marks, to send to the FTP server software.

The following command sends the namefmt command to an AS/400 FTP server before files are transferred.

-SITE 'namefmt=1'

To see what commands are accepted by the server, use a BSD-based command line client, typically the FTP command installed with your Windows or UNIX operating system and log in to the server and type the following from the ftp prompt: quote HELP SITE or quote SITE HELP.

The command specified by -SITE is executed before the files are transferred.

SSL Encryption Strength

Specifies the encryption strength for FTP connections. It can be set to either WEAK, only using weak algorithms, or STRONG, only using strong algorithms. If not specified, any available algorithm is used. If STRONG is unavailable, then WEAK is used. However, if the export version of the libraries is used, only weak algorithms are available, and this command is ignored.

This command is applicable only when the SSL secure_mode setting is in the config.yaml configuration file (/runtime/secure_mode) is set to 0, and RSA-based SSL encryption is in effect.

The corresponding adapter command is -STR {WEAK|STRONG|ANY}.

WEAK-> Use strong (non-exportable) encryption only.

STRONG-> Use exportable encryption only.

ANY-> Use any available encryption.

SSL Protocol

Specifies setting the Secure Socket Layer (SSL) protocol level. SSL enables the adapter to process FTPS URLs. The corresponding adapter command is -SPROTO{SSLv2|SSLv3|SSLv23|TLSv1}.

SSLv2: Specify SSL protocol version 2.

SSLv3: Specify SSL protocol version 3.

SSLv23: Specify SSL protocol version 2, version 3, TLSv1, TLSv1.1 or TLSv1.2. Whenever the protocol method of SSLv23 is specified, the protocol of first choice is TLSv1.2, with a fallback to TLSv1.1, then to TLSv1, then to SSLv3, and finally to SSLv2, depending on the GSKit module that is loaded.

TLSv1: Specify Transport Layer Security (TLS) protocol version 1.

If -SPROTO is not specified, the SSL Protocol defaults to SSLv23.

This command is applicable only when the SSL secure_mode setting is in the config.yaml configuration file (/runtime/secure_mode) is set to 0, and RSA-based SSL encryption is in effect. This command is superseded by an SSL secure_mode setting of 1 or 2.

Stage

Use the Stage adapter command to:

• Specify that uploaded data should be staged in a temporary or shadow file.
• Prevent partial updates of a file from being transferred. This is especially important if the FTP server processes uploads in an automated fashion.

During an upload, the FTP server generates a uniquely named temporary file. When the transfer has been completed successfully, the original file is deleted, and the temporary file is renamed. For this process to succeed, you must have access rights associated with your user ID to delete and rename files, and if the optional file name (file_name) is omitted, the server must provide a correct Store Unique (STOU) response. The adapter issues a warning if the server response cannot be interpreted. It is recommended that you run a preliminary test to ensure that the process is completed successfully.

The corresponding adapter command is -STAGE or -STG.

-STAGE[file_name]

file_name: Specifies a unique file name for the temporary file. This option is especially useful if a server does not supply unique file names.

Success

Allows a map to succeed when 300-level error codes, as defined in RFC 959, are returned. If this command option is not specified, the adapter's default behavior of the adapter is to fail on 300-level error codes. This is an optional command.

The corresponding adapter command is -S or (-SUCCESS)

-SUCCESS error_code[:error_code...]

When you specify -SUCCESS on the adapter command line, a numerical integer value between 300 and 399 is required. When this value is returned, the adapter does not fail.

error_code- An FTP error code, defined in RFC 959, between 300 and 399. Separate multiple error codes with a colon (:). For example:

-SUCCESS 301:302:303

System

Specifies the system type when the adapter cannot accurately determine the system type of the FTP server.

The FTP server system type is not necessarily the same as the operating system of the machine it runs on. Some Windows FTP servers use UNIX conventions. If in doubt, consult your server documentation or use the dir command to view the results.

The corresponding adapter command line is:

-SYS {WIN32|UNIX|UNKNOWN}

WIN32: The server follows Windows conventions. For example, directories in pathnames are separated by a backward slash (\).

UNIX: The server follows UNIX conventions. For example, directories in pathnames are separated by a forward slash (/).

UNKNOWN: Because the platform is not known, exercise generic code. Do not perform anything specific to a platform.

Trace

Produces a diagnostic file that contains detailed information about FTP adapter activity. The default filename is m4ftp.mtr, created in the map directory unless otherwise specified.

The corresponding adapter command is -T or (-TRACE)

For example:

-T[E][+][S|V] [full_path]

E-> Produces a trace file containing only the adapter errors during map execution.

+-> Appends trace information to the existing log file.

S-> Summary mode. Record only minimal information in the log file. This is the default value.

V-> Verbose mode. Record all activity occurring while the adapter retrieves data in the log file. If not specified, summary mode is assumed.

full_path-> Creates a trace file with the specified name in the specified directory. The default directory is the map directory. The default file name is m4ftp.mtr.

You can dynamically override the adapter command line trace options using the Management Console. See Dynamic Adapter Tracing in the Launcher documentation for detailed information.

Because summary mode is the default, using -TRACES provides the same output as -TRACE.

Timeout

Specifies the waiting time for the client to connect to the server before the request times out. If this option is not specified, the maximum timeout is 300 seconds, and the connection time for a client varies for different operating systems.

When this option is specified, the connection attempt is made for -TIMEOUT, time in seconds, and fails if it is not connected within the specified period.

The corresponding adapter command is -TIMEOUT.

-TIMEOUT(nnn)

nnn: The number of seconds to wait for activity on the FTP connection before the session ends in error. The default value is 300.