Skip to main content

Establishing an FTP Session

Establishing an FTP Session

To establish an FTP session, do the following:

  1. Create an instance of %Net.FtpSessionOpens in a new tab.

  2. Optionally set properties of this instance in order to control the general behavior of the session:

    • Timeout specifies how long to wait for a reply from the FTP server, in seconds.

    • SSLConfiguration specifies the activated SSL/TLS configuration to use for the connection, if any. Use this if the FTP server uses https.

      For information on creating and managing SSL/TLS configurations, see InterSystems TLS Guide. The SSL/TLS configuration includes an option called Configuration Name; this is the string to use in this setting.

    • TranslateTable specifies the translation table to use when reading the contents of a file or writing the contents of a file.

      To find the name of the table for a given character set, use the %Net.CharsetOpens in a new tab class.

    • UsePASV enables PASV mode.

    • SSLCheckServerIdentity applies when the FTP server uses https. By default, when an instance of %Net.FtpSessionOpens in a new tab connects to a SSL/TLS server, it checks whether the certificate server name matches the DNS name used to connect to the server. If these names do not match, the connection is not permitted. This default behavior prevents man in the middle attacks and is described in RFC 2818Opens in a new tab, section 3.1; also see RFC 2595Opens in a new tab, section 2.4.

      To disable this check, set the SSLCheckServerIdentity property to 0.

    • SSLUseSessionResumption if true, specifies that when making the SSL connection for the data channel, reuse session parameters from the command channel. This feature requires OpenSSL v1.1.x+. If you set the flag on an instance using OpenSSL v1.0.x, it is ignored.

  3. Call the Connect() method to connect to a specific FTP server.

  4. Call the Ascii() or Binary() method to set the transfer mode to ASCII mode or binary mode, respectively. To see the current transfer mode, check the value of the Type property of your instance.

Note:

Each method of %Net.FtpSessionOpens in a new tab returns a status, which you should check. The methods also set the values of properties that provide useful information on the state of the session:

  • Connected is true if you are currently connected, and is false otherwise.

  • ReturnCode contains the return code from the last communication with the FTP server.

  • ReturnMessage contains the return message from the last communication with the FTP server.

The Status() method returns (by reference) the status of the FTP server.

For details, see the class documentation for %Net.FtpSessionOpens in a new tab.

Translate Table for Commands

%Net.FtpSessionOpens in a new tab uses the technique described in RFC 2640Opens in a new tab to automatically handle character set translation when looking at filenames and pathnames on an FTP server. When an instance of %Net.FtpSessionOpens in a new tab connects to an FTP server, it uses the FEAT message to determine whether the server UTF-8 characters. If so, it switches the command channel communication to UTF-8 so that all filenames and pathnames will be correctly translated to and from UTF-8.

If the server does not support the FEAT command or does not report that it supports UTF-8, the %Net.FtpSessionOpens in a new tab instance uses RAW mode and reads or writes the raw bytes.

In rare cases, if you need to specify the translation table to use, set the CommandTranslateTable property of the %Net.FtpSessionOpens in a new tab instance. It should not be generally necessary to use this property.

Next sectionFTP File and System Methods
FeedbackOpens in a new tab