Skip to main content
Previous sectionNext section

Using FTP

InterSystems IRIS provides a class, %Net.FtpSession, 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.FtpSession.

  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 “Using SSL/TLS with InterSystems IRIS” in the Security Administration 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.Charset class described in “Other %Net Tools.”

    • UsePASV enables PASV mode.

    • SSLCheckServerIdentity applies when the FTP server uses https. By default, when an instance of %Net.FtpSession 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 2818, section 3.1; also see RFC 2595, section 2.4.

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

  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.FtpSession 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.FtpSession.

Translate Table for Commands

%Net.FtpSession uses the technique described in RFC 2640 to automatically handle character set translation when looking at filenames and pathnames on an FTP server. When an instance of %Net.FtpSession 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.FtpSession 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.FtpSession 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.FtpSession 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.

Append()

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

Rename()

Renames a file.

In addition, %Net.FtpSession 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.FtpSession.

For details, see the class documentation for %Net.FtpSession.

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.FtpSession.

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 }
}
Copy code to clipboard

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.FtpCallback.

  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.FtpCallback.

For details, see the class documentation for %Net.FtpCallback.