FTPGETFILE - Get file from directory structure on FTP site

Syntax:	FTPGETFILE	[ file name ] [ /options ]
Arguments:	[ file name ]	Variable or string defining a file name to look for; wildcard characters are allowed; this should be a file name only (do not include a directory name).
Options:	/ignorecase	Test for file name matches after forcing the local and site files to be lower case effectively making the match case-insensitive.
	/incldirs	Return FTP site directory name(s) as they are found.
	/newest	Return the one absolute newest file in the directory tree.
	/oldest	Return the one absolute oldest file in the directory tree.
	/timeout=nn	Time-out in seconds to wait for presence of the file, if the timeout elapses before the file is found $ERROR_WAIT_TIMED_OUT is returned. If this option is omitted Robo-FTP looks for the file and immediately returns $ERROR_NO_FILE_FOUND if no match is found.

This script command checks for (and optionally waits for) the existence of a remote file defined by the [ file name ] argument within the current directory on a remote site. This command is commonly used either to find a group of files using a wildcard pattern and then process them one at a time or to check the status of a specific file with a known file name. When a matching file is detected a set of internal variable values are populated: 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.

FTPGETFILE returns $ERROR_NO_FILE_FOUND when no file matches the [ file name ] argument. 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.

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.

Changing the contents of the remote directory during processing may cause FTPGETFILE to skip files. Please use the GETSITEFILE command with the /next option instead of FTPGETFILE if you need to process a group of files found using a wildcard pattern and your script logic adds, moves, or deletes files.

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.

The second difference between FTPGETFILE and GETSITEFILE involves the /incldirs option. If FTPGETFILE is used with the /incldirs option it searches the current directory on the remote site and any subdirectories. If a file matching the [ file name ] argument is found then %sitefile and the other internal variable values are populated as discussed above. In contrast, if GETSITEFILE is used with the /incldirs option it searches only the current directory on the remote site. If a file name matches the [ file name ] argument then the %sitefile variable is populated and the %sitefolder variable is empty. Conversely 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:

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.)

Command syntax	Error	%sitefile	%sitefolder
FTPGETFILE "one.txt"	No	one.txt	/
FTPGETFILE "sub" /incldirs	Yes	empty	empty
FTPGETFILE "two.txt" /incldirs	No	two.txt	/sub/
FTPGETFILE "deep" /incldirs	Yes	empty	empty
FTPGETFILE "three.txt" /incldirs	No	three.txt	/sub/deep/

Command syntax	Error	%sitefile	%sitefolder
GETSITEFILE "one.txt"	No	one.txt	empty
GETSITEFILE "sub" /incldirs	No	empty	sub
GETSITEFILE "two.txt" /incldirs	Yes	empty	empty
GETSITEFILE "deep" /incldirs	Yes	empty	empty
GETSITEFILE "three.txt" /incldirs	Yes	empty	empty

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.

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.

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

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.

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 directory listings at all. Contact technical support if you have an urgent need related to a directory listing format that is currently unsupported.