Using FTP

Use FTP

IRIS Provides a class %Net.FtpSession, You can use it from InterSystems IRIS Internal establishment and FTP Server session .

establish FTP conversation

To build FTP conversation , Do the following ：

1. establish %Net.FtpSession Example .
2. You can choose to set the properties of this instance , To control the general behavior of the session ：

• Timeout Timeout specifies wait FTP The time the server replied ( In seconds ).
• SSLConfiguration Specifies the active for the connection SSL/TLS To configure ( If there is ). If FTP Server usage HTTPS, Please use this option .
• TranslateTable Specifies the conversion table to use when reading or writing file contents .
• UsePASV Enable PASV Pattern .
• When FTP Server usage https when ,SSLCheckServerIdentity apply . By default , When %Net.FtpSession Connect to SSL/TLS Server time , It checks whether the certificate server name matches the name used to connect to the server DNS Name match . If these names do not match , Connection is not allowed .

To disable this check , Please put SSLCheckServerIdentity Property is set to 0.

1. call Connect() Method to connect to a specific FTP The server .
2. call ascii() or binary() Method to set the transmission mode to ASCII Mode or binary mode . To view the current transfer mode , Please check the of the instance Type The value of the property .

Be careful ：%Net.FtpSession Each method of returns a state , The status should be checked . These methods also set the values of properties that provide useful information about session state ：

• If currently connected , be CONNECTED by TRUE, Otherwise FALSE.
• ReturnCode Contains the last and FTP Return code when communicating with the server .
• ReturnMessage Contains the last and FTP Return message when communicating with the server .

Status() Method returns ( By quoting )FTP The state of the server .

Conversion table of command

%Net.FtpSession stay FTP When viewing the file name and path name on the server , Use RFC 2640 The technology introduced in automatically handles character set conversion . When %Net.FtpSession Connect to FTP Server time , It will use Feat Message to determine whether the server uses UTF-8 character . If it is , It switches the command channel communication to UTF-8, So that all file names and pathnames can be correctly associated with UTF-8 transformation .

If the server does not support FEAT Command or not reported support UTF-8,%Net.FtpSession The instance will use RAW Mode and read or write RAW byte .

In rare cases , If necessary, specify the conversion table to use , Please set up %Net.FtpSession Example of CommandTranslateTable attribute . In general , It should not be necessary to use this property .

FTP File and system methods

Once established FTP conversation , You can call the method of the session instance to execute FTP Mission .%Net.FtpSession Provide the following methods for reading and writing files ：

Delete()

Delete file .

Retrieve()

The file from FTP The server is copied to InterSystems IRIS Streaming , And return the stream by reference . To use this stream , Please use the standard flow method ：Write()、WriteLine()、Read()、ReadLine()、Rewind()、MoveToEnd() and Clear(). You can also use the of streams Size attribute .

RetryRetrieve()

Allow continued retrieval of files , Because the given stream was last used Retrieve() Created .

Store()

take IRIS The contents of the stream are written to FTP Files on the server .

Append()

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

Rename()

Rename file .

Besides ,%Net.FtpSession Provides navigation and modification FTP Method of file system on server ：GetDirectory()、SetDirectory()、SetToParentDirectory() and MakeDirectory().

To check the contents of the file system , Please use list() or NameList() Method .

• List() Create a stream , It contains a list of all files whose names match the given pattern , And return the stream by reference .
• NameList() Create an array of file names and return the array by reference .

You can also use ChangeUser() Method changed to another user ; This is faster than logging out and logging in again . Use Logout() Method to log off .

System() Method returns ( By quoting ) About hosting FTP Information about the computer type of the server .

Size() and MDTM() Method returns the size and modification time of the file respectively .

Use generic sendCommand() Method direction FTP The server sends the command and reads the response . This method can be used to send %Net.FtpSession Commands not explicitly supported in .

Upload large files using linked streams

If you want to upload a large file , Consider using a stream interface LinkToFile() Method . in other words , Instead of creating a stream and reading files into it , Instead, create a stream and link it to a file . Calling %Net.FtpSession Of Store() Use this method when linking streams .

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 }
    
    // 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

Customize FTP Callback from the server

You can customize FTP Callback generated by the server . for example , By doing so , You can provide the user with an indication that the server is still processing large transfers , Or allow the user to abort the transmission .

To customize FTP Callback , Do the following ：

1. establish %Net.FtpCallback Subclasses of .
2. In this subclass , Realization RetrieveCallback() Method , The method starts from FTP The server calls... Periodically when it receives data .
3. We need to achieve StoreCallback() Method , Writing data to FTP This method is called periodically when the server is running .
4. establish FTP Conversation time ( Such as “ establish FTP conversation ” Described in ), Set the callback property to a subclass equal to %Net.FtpCallback.