Advanced Options

The following advanced configuration properties are provided:

Character Encoding

Character Encoding sets the character encoding for the control channel. If you are using file names or directory names that are outside the standard ASCII character set, you may need to set this to make sure that the remote server can correctly interpret the data you are sending. In this case, you should also ensure the encoding you are using is accepted by the remote server and/or the OS it is running on.

It defaults to ASCII.

Active Mode IP Address

Active Mode IP Address sets the local IP address to send to the remote server when using FTP in active mode. This should be a valid IPv4 address. This can be left blank if not required, in which case the communication point would use a sensible default.

Active Mode Port Range

Active Mode Port Range sets the range of ports that will be used when using FTP in active mode. This can be left blank if not required, in which case the communication point will use a sensible default. The port range should be specified as two valid port numbers, separated by a dash, for example 23456-34567.

FTP Options

The FTP options are a set of optional settings that may be required for compatibility with certain servers.

^{None enabled by default.}

FTPS Options

FTPS Options provides options to work around some known bugs in various FTPS servers. A number of FTPS servers do not correctly close SSL channels when closing either the data or control sockets. This can manifest itself as either the client communication point freezing until a timeout occurs or raising connection errors when attempting to close data or control sockets. If this occurs then the appropriate options can then be enabled. Note that these options should not be enabled unless required to fix a specific FTPS server issue otherwise as they instruct the FTP communication point to use non-standard SSL closure mechanisms.

^{† Default option.}

Input Locales

Input Locales holds the ordered list of Java locales to use when required for parsing input directory listings. If set, the specified locales are used in the ordered specified until one is successful. If not, this is equivalent to setting English first followed by the Rhapsody locale. Refer to JDK 8 and JRE 8 Supported Locales for details.

The extended directory listings requested by the FTP communication point normally include a last modified date in the listing. While this date is not actually used by the communication point, the directory listing parsers still need to be able to parse these dates correctly. Most date formats are locale-dependent (for example 04/05/2013 could be interpreted as 5 April 2013 or 4 May 2013) and sometimes even included month names in the default language of the FTP server. As there is no FTP command to ask an FTP server what locale it is using, this needs to be configured on the communication point. By default the FTP communication point will try English first, followed by the Rhapsody system locale. This is likely to work correctly in many cases, however it can be configured using the Input Locales configuration property on the communication point. This configuration property is set as a list of strings representing Java locales. If it is set, then each specified locale is attempted in the order that they are configured until one of them is successful.

Directory Listing Parser

Directory Listing Parser selects a directory listing parser to parse directory listings returned from the FTP server.

An FTP client retrieves the contents of a directory from an FTP server using either the LIST or NLIST commands. These commands return a formatted directory listing, but the format of this listing is entirely determined by the FTP server in use. As a result, the FTP client needs a mechanism to parse these returned values in order to interpret them, as it expects a list of files and sub-directories.

The (S)FTP communication point has a number of directory listing parsers built in corresponding to commonly used formats. The following list refers to the directory listing format and not necessarily the operating system that the FTP server is running on. For example, FileZilla Server returns Unix style directory listings even when running on Windows.

^{† Default option.}

JavaScript Directory Parser

JavaScript Directory Parser is the custom JavaScript used to parse directory listings returned from the FTP server.

If the default directory listing parsers are not sufficient for particular FTP server purposes, then it is possible to write a custom directory listing parser using JavaScript. To enable the custom directory listing parser, the Parsing Directory Listings configuration property should be set to Custom JavaScript Parser. The JavaScript parser can then be configured in the JavaScript Directory Parser configuration property.

The configured JavaScript is executed once for each line returned by the FTP server in its directory listing. It is completely up to the custom JavaScript parser as to how it interprets this line and whether it recognizes it as a file, sub-directory, or symbolic link. Compilation errors in the script prevent the communication point being successfully configured, and any runtime errors are treated as a connection error within the communication point.

JavaScript Variables

The following JavaScript variables are placed into the scope of the custom JavaScript directory parser:

DirectoryContents Object

The contents JavaScript variable is a DirectoryContents object as described in the following table. The same instance of the DirectoryContents object is used for each line when parsing a directory listing.

File Object

The File object is a simple JavaScript hash with the properties listed in the following table. It is expected that these are created inline within the JavaScript method and all available attributes are provided at construction time.

Raising Connection Errors

Connection errors are raised by throwing an exception within the script. Normally this is done by throwing a string describing the problem, for example:

throw 'Failed to parse line \"' + line + '\".';

There is no need to raise an error if a line should not correspond to a file - simply do not call the contents.add() method and no file object will be created for it.

Additional Information

• Refer to JavaScript Object Reference for details on JavaScript and the objects that Rhapsody exposes.
• Refer to Shared JavaScript Libraries for details on how to manage shared JavaScript libraries.

Examples

Simple Windows Regular Expression Directory Parser

This sample parses a directory listing like the following:

07/06/2013  02:57 PM             2,113 .bash_history
05/09/2012  10:26 AM                 0 .cookies
20/08/2012  08:08 PM    <DIR>          .dia
23/08/2012  04:25 PM    <DIR>          .eclipse
30/05/2013  08:34 AM    <DIR>          .fop
03/06/2013  10:17 AM    <DIR>          .gimp-2.8
05/06/2013  10:24 AM               346 .gitconfig
07/06/2013  06:44 AM                62 .hgrc

The regular expression is configured so that if it matches, group 5 contains the file name and group 2 contains either the file size in bytes (with the thousands separators) or <DIR> if it is a directory.

var pattern = /(\d{2}\/\d{2}\/\d{4}\s+\d{2}:\d{2}\s*[AP]M)\s+(([\d,]+)|(<DIR>))\s+([^\s]+)/g;
var match = pattern.exec(line);
if (!match) {
  // Pattern didn't match - panic (connection error)
  throw 'Failed to parse line \"' + line + '\".';
} else {
  // Add the file
  contents.add({
    name: match[5],
    isDirectory: '<DIR>' == match[2]
  });
}

Simple Unix Fixed Width Directory Parser

This sample will parse a directory listing like the following:

drwxr-xr-x 1 ftp ftp              0 Jun 13  15:09 dir
-rw-r--r-- 1 ftp ftp            417 Mar 12  2013 request.txt
-rw-r--r-- 1 ftp ftp           2021 Mar 12  2013 request2.txt
-rw-r--r-- 1 ftp ftp           2307 Mar 12  2013 request3.txt

The first character contains the type and d is for a directory, and the file name starts at position 49 (zero-based):

if (line.length > 49) { 
  contents.add({
    name: line.substring(49),
    isDirectory: line[0] == 'd'
  });
}

Output Directory Navigation Mode

Output Directory Navigation Mode specifies whether the communication point should use FTP commands to traverse the target directory path and create the target directory if required during the file upload, or perform a direct file upload to the target directory.

This property is disabled when the Duplicate Filename Behaviour property is set to Rename the file or Append date and time to filename.

^{† Default option.}

Input Directory Navigation Mode

Input Directory Navigation Mode specifies whether the communication point should use FTP commands to access the target directory directly to download, or via home directory.

This property is not enforced when the Input Directory property is using an absolute path (in other words, when the input directory path begins with a forward slash).

^{† Default option.}