FTP Get

The FTP Get activity issues an FTP get or mget command to the specified server. The content of the remote files can be placed in the activity’s output or written directly to local storage. If you choose to place the contents of a remote file into the activity’s output, you can only retrieve one remote file (FTP get command) and the file’s content will be stored in memory as part of the activity’s output. If you choose to write the contents of the retrieved files to local storage, you can retrieve one or more files (FTP get or mget commands).

The Configuration tab has the following fields.

Field	Global Var?	Description
Name	No	The name to appear as the label for the activity in the process definition.
Description	No	Short description of the activity.
FTP Connection	No	Path to the shared configuration resource containing the user information such as host name, user name, and password. See FTP Connection for more information.
Quit (post-command)	No	When checked, this field specifies that the FTP connection should be closed after completing this command. If this field is not checked, the FTP connection remains open so that all FTP activities that specify the same FTP session (that is, the same host, port, username, and password) share the FTP session until the connection is closed.
Use Process Data	Yes	Specifies to write contents of the file retrieved from the FTP server to the process data. The activity’s output includes an element that contains the remote file’s contents, and the data can be used by subsequent activities in the process definition. Warning: Do not use this option if you are retrieving multiple files. You can only write the contents of one file to this activity’s output. An error is returned if you specify wildcards in the RemoteFilename input element when this field is checked.
Binary	Yes	Specifies whether to retrieve the file content in binary or ASCII mode (checked signifies binary). When ASCII mode is used, differences in line endings between the FTP server and the machine executing the FTP command are automatically handled. Also, ASCII mode implies text data, and that data can be encoded in a character encoding other than ASCII (such as UTF-8 or Latin-1).
Overwrite Existing File	Yes	When this field is checked, and the Use Process Data field is unchecked, any existing local files are overwritten if the FTP command returns files with the same names. If this field is unchecked, any attempt to write a file to disk with the same name as an existing file results in an exception.
Maintain 2.0 Compatibility	No	This field is present only for activities migrated from TIBCO BusinessWorks 2.0. If checked, this field ensures the output schema retains the elements available in TIBCO BusinessWorks 2.0.

The name to appear as the label for the activity in the process definition.

Description

Short description of the activity.

FTP Connection

Path to the shared configuration resource containing the user information such as host name, user name, and password. See FTP Connection for more information.

Quit (post-command)

When checked, this field specifies that the FTP connection should be closed after completing this command.

If this field is not checked, the FTP connection remains open so that all FTP activities that specify the same FTP session (that is, the same host, port, username, and password) share the FTP session until the connection is closed.

Use Process Data

Yes

Specifies to write contents of the file retrieved from the FTP server to the process data. The activity’s output includes an element that contains the remote file’s contents, and the data can be used by subsequent activities in the process definition.

Warning: Do not use this option if you are retrieving multiple files. You can only write the contents of one file to this activity’s output. An error is returned if you specify wildcards in the RemoteFilename input element when this field is checked.

Binary

Yes

Specifies whether to retrieve the file content in binary or ASCII mode (checked signifies binary).

When ASCII mode is used, differences in line endings between the FTP server and the machine executing the FTP command are automatically handled. Also, ASCII mode implies text data, and that data can be encoded in a character encoding other than ASCII (such as UTF-8 or Latin-1).

Overwrite Existing File

Yes

When this field is checked, and the Use Process Data field is unchecked, any existing local files are overwritten if the FTP command returns files with the same names.

If this field is unchecked, any attempt to write a file to disk with the same name as an existing file results in an exception.

Maintain 2.0 Compatibility

This field is present only for activities migrated from TIBCO BusinessWorks 2.0. If checked, this field ensures the output schema retains the elements available in TIBCO BusinessWorks 2.0.

See TIBCO ActiveMatrix BusinessWorks Process Design for more information about mapping and transforming input data.

The input for the activity is the following.

Input Item	Datatype	Description
RemoteFilename	string	The path and name of the file to retrieve from the remote server. Wildcards (? for any one character, * for one or more characters) are permitted in this field. You can specify an absolute or relative path for the remote file name. Relative paths are relative to the path specified in the RemoteDirectory element or the current directory, if RemoteDirectory is null. Note: Do not specify wildcards for this element if the Use Process Data Configuration field is checked.
LocalFileName	string	This input item is available only if the Use Process Data field on the Configuration tab is unchecked and only one remote file is retrieved. This input item specifies the name and path of the local file where the contents of the retrieved file should be written. If more than one remote file is retrieved, the local files are named to match the remote file names.
Host	string	The name of the FTP server. This overrides the value specified in the FTP Connection resource.
Port	integer	Port number for incoming FTP requests on the FTP server. This overrides the value specified in the FTP Connection resource.
UserName	string	Username for logging into the FTP server. This overrides the value specified in the FTP Connection resource.
Password	string	Password for logging into the FTP server. This overrides the value specified in the FTP Connection resource.
Encoding	string	When the retrieved file is not binary and the Use Process Data field on the Configuration tab is checked, this specifies the character encoding of the retrieved file. If this is not specified, it is assumed that the encoding of the file is the same encoding of the machine where the FTP command is executed. If the encoding of the local machine and the FTP server are different, specify the encoding used by the FTP server in this element and the activity converts the retrieved file into the local machine’s encoding.
Timeout	integer	The amount of time to wait for the FTP server to respond. This timeout is used when the FTP server places the FTP connection used by this activity into a waiting state. This overrides the value specified in the FTP Connection resource. See FTP Connection for more information.

The path and name of the file to retrieve from the remote server. Wildcards (? for any one character, * for one or more characters) are permitted in this field.

You can specify an absolute or relative path for the remote file name. Relative paths are relative to the path specified in the RemoteDirectory element or the current directory, if RemoteDirectory is null.

Note: Do not specify wildcards for this element if the Use Process Data Configuration field is checked.

LocalFileName

string

This input item is available only if the Use Process Data field on the Configuration tab is unchecked and only one remote file is retrieved.

This input item specifies the name and path of the local file where the contents of the retrieved file should be written.

If more than one remote file is retrieved, the local files are named to match the remote file names.

Host

string

The name of the FTP server. This overrides the value specified in the FTP Connection resource.

Port

integer

Port number for incoming FTP requests on the FTP server. This overrides the value specified in the FTP Connection resource.

UserName

string

Username for logging into the FTP server. This overrides the value specified in the FTP Connection resource.

Password

string

Password for logging into the FTP server. This overrides the value specified in the FTP Connection resource.

Encoding

string

When the retrieved file is not binary and the Use Process Data field on the Configuration tab is checked, this specifies the character encoding of the retrieved file.

If this is not specified, it is assumed that the encoding of the file is the same encoding of the machine where the FTP command is executed. If the encoding of the local machine and the FTP server are different, specify the encoding used by the FTP server in this element and the activity converts the retrieved file into the local machine’s encoding.

Timeout

integer

The amount of time to wait for the FTP server to respond. This timeout is used when the FTP server places the FTP connection used by this activity into a waiting state.

This overrides the value specified in the FTP Connection resource. See FTP Connection for more information.

The output for the activity is the following.

Output Item	Datatype	Description
Data	string	When Use Process Data is checked and only one file is retrieved, this element contains the data retrieved from the remote file.
FilesTransferred	complex	When one or more remote files are retrieved and written to local storage, this element contains a list of the remote filenames that were retrieved. This element contains two elements, Name and NumOfBytes. If an error occurred while retrieving files, the activity output is not available, but the Error Output tab lists the successfully transferred files and the files that failed to be transferred.
Name	integer	The name of the remote file retrieved.
NumOfBytes	integer	The number of bytes contained in the associated file name.
Success	boolean	Only available when Maintain 2.0 compatibility is checked on the Configuration tab. True or false depending upon whether the FTP get command was successfully executed by the FTP server.
Errormsg	string	Only available when Maintain 2.0 compatibility is checked on the Configuration tab. Any error messages returned from the FTP server.

When Use Process Data is checked and only one file is retrieved, this element contains the data retrieved from the remote file.

FilesTransferred

complex

When one or more remote files are retrieved and written to local storage, this element contains a list of the remote filenames that were retrieved. This element contains two elements, Name and NumOfBytes.

If an error occurred while retrieving files, the activity output is not available, but the Error Output tab lists the successfully transferred files and the files that failed to be transferred.

Name

integer

The name of the remote file retrieved.

NumOfBytes

integer

The number of bytes contained in the associated file name.

Success

boolean

Only available when Maintain 2.0 compatibility is checked on the Configuration tab.

True or false depending upon whether the FTP get command was successfully executed by the FTP server.

Errormsg

string

Only available when Maintain 2.0 compatibility is checked on the Configuration tab.

Any error messages returned from the FTP server.

The Error Output tab lists the possible exceptions that can be thrown by this activity. See TIBCO ActiveMatrix BusinessWorks Error Codes for more information about error codes and corrective action to take.

Exception	Thrown When...
GetFilesException	An error occurred during the FTP get operation.
ConnectionErrorException	An error occurred when connecting to the FTP server.
CommandExecutionException	An error occurred when executing the FTP command.
ConnectionTimeoutException	The connection to the FTP server has timed out before the command has completed its execution.

Exception

Thrown When...

GetFilesException

An error occurred during the FTP get operation.

ConnectionErrorException

An error occurred when connecting to the FTP server.

CommandExecutionException

An error occurred when executing the FTP command.

ConnectionTimeoutException

The connection to the FTP server has timed out before the command has completed its execution.