Chapter 10 Using FTP

IRIS provides a class % net.ftpSession that you can use to establish a session with an FTP server from within InterSystems IRIS.

Setting up an FTP Session

To set up an FTP session, do the following:

  1. create%Net.FtpSessionThe instance.
  2. Optionally, you can set the properties of this instance to control the general behavior of the session:
  • TimeoutTimeout Specifies the time (in seconds) to wait for the REPLY from the FTP server.
  • SSLConfigurationSpecifies the activation used for the connectionSSL/TLSConfiguration (if any). ifFTPIf the server uses HTTPS, use this option.
  • TranslateTableSpecifies the conversion table to use when reading or writing file contents.
  • UsePASVEnable PASV mode.
  • whenFTPServer usagehttpsWhen,SSLCheckServerIdentityApply. By default, when%Net.FtpSessionIs connected to an instance ofSSL/TLSServer, it checks if the certificate server name matches the DNS name used to connect to the server. If these names do not match, the connection is not allowed.

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

  1. callConnect()Method to connect to a specific FTP server.
  2. callascii()orbinary()Method sets the transport mode to ASCII mode or binary mode, respectively. To see the current transport mode, check the value of the Type property of the instance.

Note: each method of % net.ftpSession returns a status that should be checked. These methods also set the values of properties that provide useful information about the state of the session:

  • If it is currently connectedCONNECTEDTRUE, otherwise FALSE.
  • ReturnCodeContains the return code from the last time you communicated with the FTP server.
  • ReturnMessageContains the return message from the last communication with the FTP server.

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

Command conversion table

% net.ftpSession Automatically handles character set conversion using the technique described in RFC 2640 when viewing file names and pathnames on the FTP server. When an instance of % net.ftpSession connects to an FTP server, it uses the Feat message to determine whether the server uses UTF-8 characters. If so, it switches command channel communication to UTF-8 so that all file names and pathnames can be correctly converted to and from UTF-8.

If the server does not support the FEAT command or does not report utF-8 support, the % net.ftpSession instance will use RAW mode and read or write RAW bytes.

In rare cases, if you need to specify the conversion table to use, set the CommandTranslateTable property of the % net.ftpSession instance. In general, it should not be necessary to use this attribute.

FTP files and system methods

Once an FTP session is established, methods of the session instance can be invoked to perform FTP tasks. % net.ftpSession provides the following methods for reading and writing files:

Delete()

Delete files.

Retrieve()

Copy the file from the FTP server to the InterSystems IRIS stream and return the stream by reference. To use this stream, use the standard stream methods: Write(), WriteLine(), Read(), ReadLine(), Rewind(), MoveToEnd(), and Clear(). You can also use the Size attribute of the stream.

RetryRetrieve()

Allows file retrieval to continue, since the given stream was created from the previous Retrieve() use.

Store()

Write the contents of the IRIS stream to a file on the FTP server.

Append()

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

Rename()

Rename the file.

In addition, % net.ftpSession provides methods to navigate and modify file systems on the FTP server: GetDirectory(), SetDirectory(), SetToParentDirectory(), and MakeDirectory().

To check the contents of a file system, use the list() or NameList() methods.

  • List()Creates a stream that contains a list of all files whose names match the given pattern and returns the stream by reference.
  • NameList()Creates an array of file names and returns it by reference.

You can also change to another user using the ChangeUser() method; This is faster than logging out and logging in again. Logout using the Logout() method.

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

The Size() and MDTM() methods return the file Size and modification time, respectively.

Send the command to the FTP server and read the response using the generic sendCommand() method. This method can be used to send commands that are not explicitly supported in % net.ftpSession.

Upload large files using linked streams

If you want to upload large files, consider using the LinkToFile() method of the stream interface. That is, instead of creating a stream and reading a file into it, you create a stream and link it to a file. This link flow is used when calling the Store() method of % net.ftpSession.


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

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

Custom callback sent by FTP server

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

To customize the FTP callback, do the following:

  1. create%Net.FtpCallbackThe subclass.
  2. In this subclass, implementRetrieveCallback()Method, which is called periodically when receiving data from the FTP server.
  3. To achieveStoreCallback()Method that is periodically called when data is written to the FTP server.
  4. createFTPSession time (as described in “Setting up an FTP Session”), sets the callback property to a subclass equal to%Net.FtpCallback.