Using Caché Internet Utilities
Using FTP
[Back] [Next]
Go to:

Caché provides a class, %Net.FtpSession, that you can use to establish a session with an FTP server from within Caché. This chapter describes the following:

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:
  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.
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:
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:
Deletes a file.
Copies a file from the FTP server into a Caché 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.
Allows you to continue retrieving a file, given a stream created by a previous use of Retrieve().
Writes the contents of a Caché stream into a file on the FTP server.
Appends the contents of a stream to the end of the specified file.
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.
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.
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 $$$ERROR()
    //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 $$$ERROR()
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.