Skip to main content

Using FTP

InterSystems IRIS® data platform provides a class, %Net.FtpSessionOpens in a new tab, that you can use to establish a session with an FTP server from within InterSystems IRIS.

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.

FTP File and System Methods

Once you establish an FTP session, call methods of your session instance to perform FTP tasks. %Net.FtpSessionOpens in a new tab provides the following methods for reading and writing files:

Delete()

Deletes a file.

Retrieve()

Copies a file from the FTP server into an InterSystems IRIS stream and returns the stream by reference. To work with this stream, use the standard stream methods: Write(), WriteLine(), Read(), ReadLine(), Rewind(), MoveToEnd(), and Clear(). You can also use the Size property of the stream.

RetryRetrieve()

Allows you to continue retrieving a file, given a stream created by a previous use of Retrieve().

Store()

Writes the contents of an InterSystems IRIS stream into a file on the FTP server.

StoreFiles()

Given a local directory, and a wildcard mask, this method writes multiple files to that directory. Note that this method ignores directories, and uses the current transfer mode (binary or ASCII), which means that you cannot upload a mixed set of binary and ASCII files in one call.

Append()

Appends the contents of a stream to the end of the specified file.

Rename()

Renames a file.

In addition, %Net.FtpSessionOpens in a new tab provides methods for navigating and modifying the file system on the FTP server: GetDirectory(), SetDirectory(),SetToParentDirectory(), and MakeDirectory().

To examine the contents of the file system, use the List() or NameList() methods.

  • List() creates a stream that contains a list of all the files whose names match a given pattern and returns this stream by reference.

  • NameList() creates an array of filenames and returns this array by reference.

You can also use the ChangeUser() method to change to a different user; this is faster than logging out and logging in again. Use the Logout() method to log out.

The System() method returns (by reference) information about the type of computer that is hosting the FTP server.

The Size() and MDTM() methods return a file’s size and its modification time, respectively.

Use the generic sendCommand() method to send a command to the FTP server and to read the response. This method may be used to send commands that are not explicitly supported in %Net.FtpSessionOpens in a new tab.

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

Using a Linked Stream to Upload Large Files

If you have a large file to upload, consider using the LinkToFile() method of the stream interface. That is, instead of creating a stream and reading the file into it, create a stream and link it to the file. Use this linked stream when you call the Store() method of %Net.FtpSessionOpens in a new tab.

For example:

Method SendLargeFile(ftp As %Net.FtpSession, dir As %String, filename As %String)
{
    Set filestream=##class(%FileBinaryStream).%New()
    Set sc=filestream.LinkToFile(dir_filename)
    If $$$ISERR(sc) {do $System.Status.DisplayError(sc) quit }
    
    //Uploaded file will have same name as the original
    Set newname=filename

    Set sc=ftp.Store(newname,filestream)
    If $$$ISERR(sc) {do $System.Status.DisplayError(sc) quit }
}

Customizing Callbacks Issued by the FTP Server

You can customize the callbacks generated by the FTP server. By doing so, you can for example, give the user an indication that the server is still working on a large transfer, or allow the user to abort the transfer.

To customize the FTP callbacks:

  1. Create a subclass of %Net.FtpCallbackOpens in a new tab.

  2. In this subclass, implement the RetrieveCallback() method, which is called at regular intervals when receiving data from the FTP server.

  3. Also implement the StoreCallback() method, which is called at regular intervals when writing data to the FTP server.

  4. When you create an FTP session (as described in Establishing an FTP Session), set the Callback property equal to your subclass of %Net.FtpCallbackOpens in a new tab.

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

FeedbackOpens in a new tab