class %Net.FtpSession
extends %RegisteredObject
The %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","username@domain.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 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 Connected
as %Boolean [ InitialExpression = 0 ];
True if we are currently connected to an ftp server and false if not.
• property IsIPV6
as %Boolean [ InitialExpression = 0 ];
True if the connection is IPV6 protocol.
• 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
• 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 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 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 ServerAddr
as %String;
Server's IP address to be used in EPSV mode with IPV6 protocol.
• 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 TranslateTable
as %String;
The translate table to be used when reading or writing files.
• 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 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.
• method Append(Filename As %String, Stream As %AbstractStream)
as %Boolean
Append the data contained in Stream to the file named in Filename.
• method Ascii()
as %Boolean
Switch the ftp server transfer type to Ascii. This will for example convert Cr/Lf
to Lf for Unix systems. When transfering text files you should use this mode. The
current mode can be found by looking at the property Type.
• method Binary()
as %Boolean
Switch the ftp server transfer type to Binary. This will store the data in exactly
the same format it is sent in. When transfering any binary files you should use
this mode. The current mode can be found by looking at the property Type.
• method ChangeUser(Username As %String, Password As %String)
as %Boolean
Change the user that we are logged in as. This assumes you are already connected
to the ftp server at this point.
• method Connect(Server As %String, Username As %String, Password As %String, Port As %Integer = 21)
as %Boolean
Connect to an Ftp server. You should supply the server IP address or domain name
to connect to as the Server parameter. Also most Ftp server will require
a Username and a Password in order to allow you to login. To login to
an anonymous Ftp server use the Username="anonymous" and the Password is your email address.
Port is an optional parameter that specifies the IP port number to connect
on if it is not the standard port of 21.
• method Delete(Filename As %String)
as %Boolean
Delete the file Filename on the Ftp server.
• classmethod GetDevice()
as %String
• method GetDirectory(ByRef Path As %String)
as %Boolean
Return the current directory the Ftp server is in the paramater Path that
is passed by reference.
• method List(Pattern As %String, ByRef Stream As %AbstractStream)
as %Boolean
Read in the files that match the Pattern in a human readable format
into Stream. The Pattern can include a path as well pattern to
search for, and if no pattern is specified then it will list all the files
in this directory.
• method Logout()
as %Boolean
Logoff and disconnect from the Ftp server.
• method MakeDirectory(ByRef Path As %String)
as %Boolean
Create a new directory on the Ftp server. Path should be passed by
reference and it will return the name of the directory created. The Ftp server
will translate the path you give it into its own format (which may be different)
and is the value returned by in Path.
• method NameList(Path As %String, ByRef FileArray As %ArrayOfDataTypes)
as %Boolean
Given a Path this will return an array of filenames in the parameter
FileArray, this parameter should be passed by reference and if not already
created it will create a new %ArrayOfDataTypes. An example of its
use assuming is:
New fileArray,key
If 'ftp.NameList("",.fileArray) Write "Failed to get name list",!
Set key=""
Write "List of Files:",!
For Write fileArray.GetNext(.key),! Quit:(key="")
• method RemoveDirectory(Path As %String)
as %Boolean
Delete the directory passed in Path from the Ftp server.
• method Rename(OldFilename As %String, NewFilename As %String)
as %Boolean
Rename a file from OldFilename to NewFilename.
• method Retrieve(Filename As %String, ByRef Stream As %AbstractStream)
as %Integer
Retrieve the file specified by Filename into Stream.
If Stream is not specified it will be created, in which case you
should pass it by reference so it can be returned to the caller.
• method RetryRetrieve(Filename As %String, Stream As %AbstractStream)
as %Integer
If a Retrieve failed because the connection was lost this allows
you to retry getting the file. So if you have got 1/2 of the original file in
the first attempt for Filename you pass the Stream with this half
into this method and it will start where the other transfer left off.
• method SetDirectory(Path As %String)
as %Boolean
Set the directory on the Ftp server to Path.
• method SetToParentDirectory()
as %Boolean
Move to parent directory on the Ftp server.
• method Status(ByRef Status As %String)
as %Boolean
Return the status of the Ftp server in the Status parameter which should
be passed by reference.
• method Store(Filename As %String, Stream As %AbstractStream)
as %Boolean
Store the data in Stream in the Filename on the Ftp server.
• method System(ByRef System As %String)
as %Boolean
Return information about the type of computer you are connected to in the
by reference parameter System.
• method TypeGet()
as %String
This is a Get accessor method for the Type property.
