FTP_SCRIPT

FTP_SCRIPT

This activity will execute a script of FTP subcommands.  It is supported only on IBM i servers.

The FTP script may contain substitution variables that are replaced at run-time by the values of Processing Sequence variables.  See below for details on this feature.

Other supplied FTP activities (including FTP_INBOUND, FTP_OUTBOUND and FTP_COMMANDLIST) use the LANSA Integrator FTPService in their implementation.  However, in some cases it is desirable or necessary to take advantage of IBM i QSYS.LIB file system object support that is provided by the native IBM i5/OS FTP client but NOT available through the LANSA Integrator FTPService.  This activity is provided for such cases.  For example, this activity can be used for transferring IBM i5/OS save files (*FILE objects with SAVF attribute) between IBM i systems.

Notes:

1.  The script is executed using the native IBM i5/OS FTP client.

2.  The FTP script will run to completion irrespective of any errors that may occur during its execution.  If errors occur in the FTP operations, the activity does not end in error - see the description of the output parameter FTPERRORCOUNT for more information.

3.  Because the FTP functions performed by this activity are determined by the user-provided FTP script, it does not inherently have any "inbound" or "outbound" sense.  The script can perform any combination of FTP subcommands supported by the i5/OS FTP client, including PUT/MPUT, GET/MGET or both.

INPUT Parameters:

FTPCONFIG : Optional

This parameter can contain the name of an FTP configuration.  If specified, it is recommended that you use an FTP configuration of type 'Command List', although you can also specify an Inbound or Outbound configuration.  This activity will, at most, use the following attributes of the FTP configuration:

- Remote Host

- Remote Port Address

- Remote User

- Remote Password

- Command list file

You may specify *NONE for the 'Remote Host'.  If you do so, then the 'Remote Port Address' will not be used and your script should usually contain an FTP 'open' subcommand to establish the connection to a remote host that you specify.

Similarly, if the FTP configuration is not specified, then your script must contain the FTP subcommands (such as 'open') necessary to establish the required connection along with the necessary credentials.  In this case, you must provide the remote host, port (if necessary) and credentials through the FTP subcommands in the script.

FTPSCRIPTFILE : Optional

This parameter is optional, but if it is not provided, then you must provide the FTP subcommand script either through the FTPSCRIPTLIST parameter or in the 'Command list file' field of the FTP configuration.  If this parameter is provided, then it must specify the full path to a text file that contains the FTP subcommand script to be executed.  See FTP Subcommand Script below for more information.

FTPSCRIPTLIST : Optional

This parameter is optional, but if it is not provided, then you must provide the FTP subcommand script either through the FTPSCRIPTFILE parameter or in the 'Command list file' field of the FTP configuration.  If this parameter is provided, then it must contain a list of the FTP subcommands to be executed.  See FTP Subcommand Script below for more information.

OUTPUT Parameters:

FTPOUTPUT:

Upon completion, this parameter will contain a list of FTP log output lines generated by running the FTP script.  (The FTP log results are also available in the Processing Sequence log, depending on the logging level in effect.)

FTPERRORCOUNT:

Upon completion, this parameter will contain a count of the lines in the FTP log that the activity interprets as representing errors.  This is defined as lines that begin with an FTP response code in the range 400-499 and 500-599.

Note that:

- the error count will be incremented for some "normal" messages such as '467 bytes transferred ...'

- response codes counted as errors are generally issued by the FTP server

- errors (usually syntax errors) issued by the FTP client may not have a recognisable response code and so may not be counted as errors

- in any event, it may be normal for some scripts to generate errors.

For all these reasons, the activity does NOT return an error status if the apparent error count is greater than zero. It is up to you to test the output parameters to determine the success of the operation and to handle error conditions in your Processing Sequence.

FTP Subcommand Script

Whether you specify your FTP script through the FTP configuration, or through the FTPSCRIPTFILE or FTPSCRIPTLIST parameters, you should compose your script according to the following guidelines:

• Your script can consist of any valid FTP subcommands supported by the FTP client software

• Each FTP subcommand should be on a separate line or in a separate list entry

• Lines or list entries beginning with '*' are ignored and may contain comments

• If you have specified an FTP configuration and the 'Remote Host' is not *NONE, then the activity will insert the remote user id and password from the FTP configuration in the first line of the script.  In this case, there is no need to specify the credentials inside your script unless the remote FTP server requires additional account information or unless your script closes the connection and you subsequently wish to open another connection.

Refer to the documentation for the FTP client software for information on the FTP subcommands supported.  On IBM i servers, you can start the FTP client by typing the command FTP RMTSYS(*NONE) at a command line.  When the FTP client has started type the command HELP and press Enter to access on-line help about the supported FTP subcommands.

Substituting Processing Sequence Variables in the FTP Subcommand script

The activity supports substitution variables in the FTP script.  When found, they will be replaced by the value of the named variable in the Processing Sequence variable pool.

You can specify a substitution variable in the following form:

   %%var.<variable-name>%%

where <variable-name> is the name by which the variable is known in the Processing Sequence variable pool.  See the example FTP script below for an example of using substitution variables in an FTP script.

If you specify substitution variables in your FTP script, it is your responsibility to ensure that the variables named exist and have valid values assigned to them in the Processing Sequence that uses the script. The variables values may be set by any supported means - for example, they might be received as Processing Sequence parameters, explicitly set with an ASSIGN directive, or set as the result of running some other activity.  If the named variables do not exist in the Processing Sequence when the FTP script is executed, this activity will issue a warning but execution will continue (the variable reference is removed from the FTP script).

Note that the following advanced forms of variable references are NOT supported by this feature:

1. Compound or qualified variables - for example: *tradingpartner.xxx

2. Indexed variables - for example: mylist(3)

Typically you could circumvent these limitations, if necessary, by assigning the desired compound or indexed variables to a simple variable name before executing the script.

Example FTP Subcommand Script

The following script might be used with a correctly configured FTP configuration to copy the contents of a source library on the source IBM i system to a target library on the target IBM i system.  The processing sequence must set the value of the processing sequence variables SOURCELIB and TARGETLIB in order to specify the respective library names.  The FTP configuration used must specify the remote host name and the remote user and password used to connect to the remote host.