<< Click to Display Table of Contents >> Navigation:  Robo-FTP User's Guide > Script Programming > Script Commands > All Script Commands > FTPGETFILE         Get properties of remote file(s)

 

 

If you need to download a file please see the Help page for the RCVFILE script command.

 

Note

Robo-FTP offers numerous commands for monitoring for files and iterating over directory structures on local and remote servers. There is significant overlap in capabilities between these commands, but there are also important differences that often make one command better suited to a particular task than the others. Please see the chapter Monitoring for Files and Iterating over Directory Structures for a description of these commands and recommendations for which commands to use in a particular situation.

 

This script command searches the current remote directory for the file specified in the [ file name ] argument. If a matching file is found, a set of internal variables is populated which may then be used for various tasks like checking the status of a specific file, processing a group of files with names matching a wildcard pattern or executing a set of commands only when certain conditions exists. For example, a script might use the date and size variables to choose which files in a folder should be transferred, deleted or ignored.

 

When a match is found, the file name is saved in the %sitefile variable; the %sitepath variable contains the full remote path and filename, %sitefolder and %sitedir both contain the path as returned by the remote server (without the filename); the date and time of the file are saved in the %sitefiledate, %sitefiledatetime, and %sitefiletime variables; and the size of the file, in bytes, is saved in the %sitefilesize variable.  

 

The /skip_changing and /skip_changing_seconds options are useful when there is a chance that a file being processed by Robo-FTP is also being modified by some other process.

 

This command returns $ERROR_NO_FILE_FOUND when no file matches the [ file name ] argument. The /timeout option can be used to wait for the existence of an expected file. This is accomplished by periodically polling the remote folder during the waiting period. If the file does not appear before the timeout expires $ERROR_WAIT_TIMED_OUT is returned.

 

Use the FTPCD command to change the current directory before calling FTPGETFILE if the file you want to find is not in the current directory or, alternatively, the /incldirs option may be use to find files in any subdirectory of the current directory.

 

This command is functionally equivalent to the GETSITEFILE script command except for two important differences. The first difference between FTPGETFILE and GETSITEFILE is their behavior when called repetitively with a wildcard character in the [ file name ] argument. In this situation, each subsequent call to FTPGETFILE automatically returns the next file in the list of all files matching the wildcard pattern.  If there are three files matching the pattern, the first three calls to FTPGETFILE each return a different set of internal variable values and the fourth call results in a "No File Found" error.

 

The FTPGETREWIND command may be used to start over at the top of the list. In contrast, when GETSITEFILE is called repetitively with a wildcard character in the [file name] argument it returns the same set of values every time unless the /next option is specified.

 

Suppose Robo-FTP is connected to a remote site with a file named "ReadMe.txt" in the current directory. In the following example, the first line will successfully populate %sitefile and the other internal variables but the second line will cause a "No File Found" error.  

 

FTPGETFILE "ReadMe.txt"

FTPGETFILE "ReadMe.txt"        ;; No File Found error expected

 

The second line returns an error because subsequent calls to FTPGETFILE always return the next matching file in the list of files matching the [ file name ] argument.  Since there can never be two files in the same folder with the same name, there can never be a next "ReadMe.txt" file. Because of this quirk it is safer to use GETSITEFILE if you only need to check the existence, timestamp, or size of a single file with a known filename.

 

Important

Do not use the FTPGETFILE command to construct a loop that moves or deletes files; such loops may be built using GETSITEFILE without the /next option. Use the FTPDIFF command instead of either FTPGETFILE or GETSITEFILE if your project requirements include processing dynamic folders where files may be added, renamed, moved or deleted during processing.

 

Use of the /newest or /oldest options negates the auto-incrementing next behavior of the FTPGETFILE command. When either of these options is used, Robo-FTP always returns the newest or oldest file respectively. This behavior requires checking the date of every file in the folder so combining either option with the /skip_changing or /skip_changing_seconds option will result in longer script execution times.

 

The FTPGETREWIND command may be used to start over at the top of the list of files that match the wildcard pattern.

 

The second difference between FTPGETFILE and GETSITEFILE involves the /incldirs option. If FTPGETFILE is used with the /incldirs option it searches the current remote directory and any subdirectories. If a file matching the [ file name ] argument is found then %sitefile, %sitefolder and all the other internal variable values are populated as discussed above. If GETSITEFILE is used with the /incldirs option it searches only the current remote directory. If a matching file name is found then the %sitefile variable is populated and the %sitefolder variable is empty; but if a sub-folder name matches the [ file name ] argument then the %sitefolder variable is populated and the %sitefile variable is empty.

 

To understand this second difference, suppose Robo-FTP is connected to a remote site and the root directory contains a file named one.txt and a sub-folder named /sub and further suppose that sub-folder contains a file named two.txt and its own sub-folder named /deep which contains a file named three.txt as follows:

one.txt  

/sub/two.txt

/sub/deep/three.txt

 

The chart below shows the results of calling FTPGETFILE in the root folder with various arguments and options. (Assuming FTPGETREWIND is executed between calls to FTPGETFILE.)

 

Contrast the results of FTPGETFILE above with the results of GETSITEFILE below:

 

Note: The platform of the remote server controls which path-separator character appears in the %sitefolder internal variable.

 

Consider the following example where FTPGETFILE uses the "*" wildcard to match all the files in the current remote directory and then download each of them.

 

:fetch_file

FTPGETFILE "*"

IFERROR= $ERROR_NO_FILE_FOUND GOTO no_more_files

RCVFILE %sitefile

IFERROR!= $ERROR_SUCCESS GOTO rcv_error

GOTO fetch_file

:no_more_files

[ ... ]

:rcv_error

[ ... ]

 

The date and time of files found with FTPGETFILE are saved to three internal variables named %sitefiledate, %sitefiledatetime, and %sitefiletime. Consider the following example that cycles through all files on the remote site until it finds one created after a specified date.

 

:fetch_file

FTPGETFILE "*"

IFERROR= $ERROR_NO_FILE_FOUND GOTO no_more_files

SET filedatetime = "file date is " & %sitefiledatetime

DISPLAY filedatetime

IFDATE< "07-31-10" GOTO fetch_file

MESSAGEBOX "Found a file named " & %sitefile & " created on or after July 31, 2010!"

STOP

:no_more_files

MESSAGEBOX "All files were created before July 31, 2010!"

STOP

 

The following example causes Robo-FTP to wait indefinitely, polling the remote site periodically until the network connection is disrupted or a file with a name matching *.rdy is found. Script execution resumes on the next line when either of these events occurs.

 

FTPGETFILE "*.rdy" /timeout=0

IFERROR= $ERROR_NO_FILE_FOUND GOTO network_error

MESSAGEBOX "Found a file named " & %sitefile

STOP

:network_error

MESSAGEBOX "No file found.  Connection to remote site was lost!"

STOP

 

In the next example, we use FTPGETFILE with the /incldirs option to select a deeply nested file that matches pattern "*csv" from a remote subdirectory to the current local directory. We have to be careful here. The RCVFILE "path/to/file.csv" does not download a file named "file.csv" from remote directory "path/to". Instead, it downloads "file.csv" from the remote working directory, and places it in the local directory "path/to", relative to the current local working directory. However, in this example we instead want to actually download from a particular remote working directory, and place the file directly in the current local working directory. To do so, we employ the RCVFILE "/from=" option, which has precisely that meaning:

   

       FTPGETFILE "*csv" /incldirs

       RCVFILE %sitefile /from=%sitepath       ;; evalutes to, for example: RCVFILE "file.csv" /from="path/to/file.csv"

                                               ;; downloads the remote file "path/to/file.csv"

                                               ;; and places "file.csv" directly inside the current local working directory

       

In this example, we also want to download a file from a particular remote directory other than the remote working directory. However instead of placing the downloaded file in the current local working directory, we want to construct a copy of the directory structure in the remote path but on the local filesystem. The FTPGETFILE command itself is the same, but the RCVFILE command is altered to use the "/copydirs" option which performs this operation:

 

       FTPGETFILE "*csv" /incldirs

       RCVFILE %sitepath /copydirs             ;; evalutes to, for example: RCVFILE "path/to/file.csv" /copydirs

                                               ;; downloads the remote file "path/to/file.csv"

                                               ;; and places "file.csv" in local directory "path/to/"

 

Important

The success of this command depends on Robo-FTP's ability to automatically read and understand the directory listings returned by the remote site. Most HTTP/HTTPS sites do not return listings in a supported format and many return no raw directory listings in response to HTTP GET requests based on slash-terminated URLs. Some servers respond to HEAD requests and are partially compatible. Some supported HTTP listing types like APACHE_DEFAULT include file sizes rounded to the nearest megabyte or kilobyte and are therefore not fully compatible with this command. Contact technical support if you have an urgent need related to a directory listing format that is currently unsupported.

 

GETFILE is the equivalent function for getting details about local files.

 

Important

This command returns $ERROR_NO_FILE_FOUND when no file matches the [ file name ] argument. This is not the same error as $ERROR_NO_FILES_FOUND. Please be sure to test for the correct error code.

 

 

Related command(s): GETSITEFILE, FTPGETREWIND, GETFILE, GETNEXTFILE, GETREWIND, FILECOMPARETO, FILECOMPAREFROM

See also: Using the %sitefile and %sitedir Variables, Using the %sitefiledate, %sitefiledatetime, %sitefilesize, and %sitefiletime Variables, Using Wildcards