class %Net.FtpSession extends %Library.RegisteredObjectThe %Net.FtpSession class provides a way of interacting with a FTP server so you can send/receive files, get a list of the files on the server, rename files, delete files, etc.
All the methods will return a boolean that is true if the method succeeded and false if it failed. They will also set the two properties ReturnCode and ReturnMessage with information from the ftp server you are connected to. This often contains useful information if a method fails. You should at the very least check the return value from each of the methods after every call.
Once you have created an object of this class you need to login to the server you wish to communicate with before you can do anything else, this is done with the Connect() method. You can tell if you are connected to a server by looking at the property Connected.
If an ftp server at 'TestMachine' had a binary file called 'test.exe' in the root ftp directory then the following example will pull this file into Cache.
Set ftp=##class(%Net.FtpSession).%New() If 'ftp.Connect("TestMachine","ftp","email@example.com") Write "Not connected",! Quit Write "Ftp server messsage:",!,ftp.ReturnMessage,! Set stream=##class(%GlobalCharacterStream).%New() If 'ftp.Binary() Write "Can not swap to binary mode",! Quit Write "Mode now: ",ftp.Type,! If 'ftp.Retrieve("test.exe",stream) Write "Failed to get file",! Quit Write "Length of file received: ",stream.Size,! If 'ftp.Logout() Write "Failed to logout",! Quit
property AutoDetectPrivate as %Integer [ InitialExpression = 1 ];
When using PASV mode (see UsePASV) the remote server supplies the IP address and port to connect to. On misconfigured servers it is possible this may report a private IP address when we are connecting to it from a public IP address so the PASV connection fails. We automatically detect this and use the initial IP address we had connected to in this case, but if you set this property =0 it turns this detection off. If this property is 2 then we never use the PASV supplied server IP and always use the original server address.
Property methods: AutoDetectPrivateDisplayToLogical(), AutoDetectPrivateGet(), AutoDetectPrivateIsValid(), AutoDetectPrivateLogicalToDisplay(), AutoDetectPrivateNormalize(), AutoDetectPrivateSet()
property Callback as %Net.FtpCallback;
The Callback property is designed to allow user code in the class %Net.FtpCallback to be called at regular intervals during an ftp Store() or Retrieve(). This can display the progress of the ftp operation to the user and could allow the user to abort the transfer.
Property methods: CallbackGet(), CallbackGetSwizzled(), CallbackIsValid(), CallbackNewObject(), CallbackSet()
property CommandTranslateTable as %String;
The translate table to use for the command channel, specifically for the filename/pathnames. Normally this should not be specified in which case if the ftp server supports UTF-8 then we will use that for the filename/pathnames, if the server does not support UTF-8 then we will use RAW mode and just read the bytes as sent.
Property methods: CommandTranslateTableDisplayToLogical(), CommandTranslateTableGet(), CommandTranslateTableIsValid(), CommandTranslateTableLogicalToDisplay(), CommandTranslateTableLogicalToOdbc(), CommandTranslateTableNormalize(), CommandTranslateTableSet()
property Connected as %Boolean [ InitialExpression = 0 ];
True if we are currently connected to an ftp server and false if not.
Property methods: ConnectedDisplayToLogical(), ConnectedGet(), ConnectedIsValid(), ConnectedLogicalToDisplay(), ConnectedNormalize(), ConnectedSet()
property IsIPV6 as %Boolean [ InitialExpression = 0 ];
True if the connection is IPV6 protocol.
Property methods: IsIPV6DisplayToLogical(), IsIPV6Get(), IsIPV6IsValid(), IsIPV6LogicalToDisplay(), IsIPV6Normalize(), IsIPV6Set()
property LegacySSL as %Boolean [ InitialExpression = 0 ];
If true and you specify a SSLConfiguration then this class will use non-standard implied SSL on the data and command channel rather than using RFC4217. Depending on the configuration of the server you are talking to it may be needed to also send 'PBSZ 0' and 'PROT P' before you can communicate, this can be done with 'Set rc=ftp.sendCommand("PBSZ 0"),rc2=ftp.sendCommand("PROT P")'.
Property methods: LegacySSLDisplayToLogical(), LegacySSLGet(), LegacySSLIsValid(), LegacySSLLogicalToDisplay(), LegacySSLNormalize(), LegacySSLSet()
property ReturnCode as %Integer [ InitialExpression = 0 ];
ReturnCode is a the three digit number that the ftp server reponds to commands with. This can be used to determine if the command completed or if there were problems. See the rfc on ftp for more information on these codes.
Property methods: ReturnCodeDisplayToLogical(), ReturnCodeGet(), ReturnCodeIsValid(), ReturnCodeLogicalToDisplay(), ReturnCodeNormalize(), ReturnCodeSet()
property ReturnMessage as %String;
ReturnMessage is set to the text message that the ftp server responds with, this often contains useful information if a method failed, or useful information such as the text banner you get when you first login to an ftp server.
Property methods: ReturnMessageDisplayToLogical(), ReturnMessageGet(), ReturnMessageIsValid(), ReturnMessageLogicalToDisplay(), ReturnMessageLogicalToOdbc(), ReturnMessageNormalize(), ReturnMessageSet()
property SSLCheckServerIdentity as %Boolean [ InitialExpression = 0 ];
When making an SSL connection check the server identity in the server certificate matches the name of the system we are connecting to. This defaults to being off and matches based on the rules layed out in section 3.1 of RFC 2818.
Property methods: SSLCheckServerIdentityDisplayToLogical(), SSLCheckServerIdentityGet(), SSLCheckServerIdentityIsValid(), SSLCheckServerIdentityLogicalToDisplay(), SSLCheckServerIdentityNormalize(), SSLCheckServerIdentitySet()
property SSLConfiguration as %String;
The name of the activated TLS configuration to use for ftp requests. If specified then we use TLS on the FTP connection as specified in RFC4217. Both the data and the command channel will be secured with TLS after the initial connect on the command channel tells the remote server to switch to TLS mode.
Property methods: SSLConfigurationDisplayToLogical(), SSLConfigurationGet(), SSLConfigurationIsValid(), SSLConfigurationLogicalToDisplay(), SSLConfigurationLogicalToOdbc(), SSLConfigurationNormalize(), SSLConfigurationSet()
property ServerAddr as %String;
Server's IP address to be used in EPSV mode with IPV6 protocol.
Property methods: ServerAddrDisplayToLogical(), ServerAddrGet(), ServerAddrIsValid(), ServerAddrLogicalToDisplay(), ServerAddrLogicalToOdbc(), ServerAddrNormalize(), ServerAddrSet()
property Timeout as %Integer [ InitialExpression = 10 ];
Timeout is the amount of time to wait for a response from the ftp server before assuming that the server is not responding or the network connection is not working. The default value is 10 seconds.
Property methods: TimeoutDisplayToLogical(), TimeoutGet(), TimeoutIsValid(), TimeoutLogicalToDisplay(), TimeoutNormalize(), TimeoutSet()
property TranslateTable as %String;
The translate table to be used when reading or writing files.
Property methods: TranslateTableDisplayToLogical(), TranslateTableGet(), TranslateTableIsValid(), TranslateTableLogicalToDisplay(), TranslateTableLogicalToOdbc(), TranslateTableNormalize(), TranslateTableSet()
property Type as %String [ Calculated ];
Type returns the transfer mode the ftp server is currently set to. This can be either Ascii or Binary. The methods Ascii() and Binary() change the mode the server is currently set to.
Property methods: TypeDisplayToLogical(), TypeGet(), TypeIsValid(), TypeLogicalToDisplay(), TypeLogicalToOdbc(), TypeNormalize()
property UseExtensions as %Boolean [ InitialExpression = 0 ];
Indicates whether to use FTP Extensions for IPv6 and NATs. When set, the extension commands EPRT and EPSV will be used in place of the PORT and PASV commands. The default value is 0, but UseExtentions is automatically set to 1 when an IPV6 address is used. The FTP Extension commmands are useful to avoid problems using FTPS with Network Address Translation (NAT) as when traversing firewalls.
Property methods: UseExtensionsDisplayToLogical(), UseExtensionsGet(), UseExtensionsIsValid(), UseExtensionsLogicalToDisplay(), UseExtensionsNormalize(), UseExtensionsSet()
property UsePASV as %Boolean [ InitialExpression = 1 ];
Ftp connections are formed from two TCP/IP connections to the remote server, a command channel where the ftp commands are sent down and command responses are retrieved and a data channel for streaming large pieces of data. The way the data channel is connected is determined by this property. In PASV mode, the default, this ftp client asks the server where to connect for the data channel and it then initiates this connection to the remote server. If PASV mode is not used then the client tells the remote server where to connect to and the remote server initiates the data connection to this client machine. PASV mode is turned on by default because when going through a firewall having the remote ftp server initiate the data channel often does not work, but PASV mode will work in this case.
Property methods: UsePASVDisplayToLogical(), UsePASVGet(), UsePASVIsValid(), UsePASVLogicalToDisplay(), UsePASVNormalize(), UsePASVSet()
Append the data contained in Stream to the file named in Filename.
method Ascii() as %Boolean