- Managing the progress of the transfer
- Transfer timeout
- Rights of users
- Relative and absolute path
- AS/400 FTP server
In french: FTPRécupèreFichier
Transfers a file from an FTP (File Transfer Protocol) server to the current computer.
Remark: This function allows you to recover only one file. This file must exist on the FTP server. In this case, FTPGetFile
is faster than FTPGet
// Download the "/Document/File.txt" file found on the FTP server
// in the "D:\Temp" directory on the current computer
ResRetrieve = FTPGetFile(7, "/Document/File.txt", "D:\Temp")
<Result> = FTPGetFile(<Connection identifier> , <File to get> , <Destination file/directory> [, <WLanguage procedure> [, <Transfer mode>]])
- True if the transfer was performed,
- False otherwise. To get more details on the error, use ErrorInfo with the errMessage constant.
Remark: The result may be incorrect on some Unix servers: an existing file may not be found.
<Connection identifier>: Integer
Connection identifier, returned by FTPConnect.
<File to get>: Character string
Name and absolute (or relative) path of the file to get. This file is located on the FTP server. The different path sections are separated by "slashes" ("/").
Caution: the name of the directory is case sensitive. You must use the same case as the one used on the FTP server (uppercase/lowercase characters).
No wildcard character (* or?) can be used. To retrieve several files, use FTPListFile beforehand to get the name of the files to retrieve.
An absolute path has the following format: "/<DirectoryName>/<FileName>". The tree structure has the following format: "/<DirectoryName>/<FileName>".
A relative path has the following format: "<DirectoryName>/<FileName>". The tree structure has the following format: "/<CurrentServerDirectory>/<DirectoryName>/<FileName>".
When retrieving the file:
- if <Destination file/directory> is a directory found on the current computer, the file to retrieve is copied to the destination directory.
- if <Destination file/directory> is a file found on the current computer, the file to retrieve is copied and renamed.
<Destination file/directory>: Character string
Name and full (or relative) path of the destination file (or directory). A UNC path can be used.
If this parameter corresponds to a name of an existing directory on the client computer, a file with the same name as the file to get is created in this directory.
<WLanguage procedure>: Procedure name
Name of WLanguage procedure automatically called to check the transfer progress. This procedure can be a global method of the class (in the following format: <Class name>::<GlobalMethodName>).
<Transfer mode>: Optional Integer constant
Transfer mode used:
|ftpASCIIMode||Transfer performed in ASCII mode. This mode is used to transfer data between two different types of operating systems, from UNIX to Windows for example: the transferred file is changed into the ASCII format of destination system.|
|Transfer performed in binary mode. The file is strictly identical between the sending and the receiving.|
Managing the progress of the transfer
FTPGetFile is a blocking function: no other action can be performed until the end of current transfer.
To check the progress of the transfer, FTPGetFile can automatically call the <WLanguage procedure> procedure at regular intervals (every 64 KB).
This procedure is declared as follows:
PROCEDURE <Procedure name>(<Total size>, <Transferred size>)
- <Total size> is an integer corresponding to the total size of file currently transferred.
- <Transferred size> is an integer corresponding to the number of bytes already transferred.
In this procedure, you can:
- display a progress bar (using a Progress Bar control for example),
- find out whether the transfer is completed (<Total size> = <Transferred size>).
FTPGetFile cannot be interrupted until the transfer is completed. To force the interruption of the browse, use the following line of code in the <Procedure name> procedure:
In any other case (to continue the browse), <Procedure name> MUST return True.
An error is generated if <Procedure name> returns no value (neither True nor False).
By default, all the FTP functions fail if the FTP server does not respond within 20 seconds. This timeout can be modified with FTPConnect
when connecting to the FTP server.
Rights of users
Only a user who has read rights on the FTP server can retrieve the files found on an FTP server. In most cases, the read rights are granted to the "anonymous" users.
Relative and absolute path
The notions of relative path and absolute path are very important in an FTP application.
- A path starting with a slash is considered as being an absolute path: it is the path in relation to the root of the FTP server (parameter specific to the server).
- A path not starting with a slash is considered as being a relative path, which means a path given in relation to the current directory. This current directory can be returned or modified by FTPCurrentDir.
When connecting to an FTP site, the initial directory (the "home directory" of the user) is not necessarily found at the root of the FTP server. Therefore, we recommend that you use relative paths.
AS/400 FTP server
FTPGetFile does not work properly on an AS/400 FTP server.
In this case, we recommend that you use FTPCommand
with the FTP "RETR" command (for more details, see the documentation about the FTP server).
This page is also available for…