GETSITEFILE - Get properties of remote file(s) or folder(s)

Syntax:	GETSITEFILE	[ file name ] [ /options ]
Alt Syntax:	GETSERVERFILE
Arguments:	[ file name ]	Variable or string defining a file name to look for; wildcard characters are allowed
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 the names of sub-folders that match the [ file name ] argument. (Formerly this was the /subdirs option.)
	/newest	Get the newest file in the directory (cannot be combined with /next option).
	/next	Get the next file in the directory; omit this option to obtain the first file from a given site directory; if you wish to obtain subsequent files from this same directory, use this option until you find the desired file or no more files are found (see Important below). This option cannot be combined with the /timeout option.
	/oldest	Get the oldest file in the directory (cannot be combined with /next option).
	/skip_changing	Ignore any file if its size is not stable for one second.
	/skip_changing_seconds=nn	Ignore any file if its size is not stable for the specified number of seconds. Values between 1 and 60 are allowed.
	/timeout=nn	Time-out in seconds to wait for presence of the file, if the time 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 option cannot be combined with the /next option.

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

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 or folder with the name 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 the matching item is a folder then the folder's name is saved in the %sitefolder and %sitedir variables. If the matching item is a file, the name is saved in %sitefile and the %sitepath variable contains the full remote path and filename. The date and time of the file are saved in the %sitefiledate, %sitefiledatetime, and %sitefiletime variables. 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. The polling feature associated with the /timeout option can be used to implement the hot receive behavior whereby Robo-FTP automatically downloads files as they are added to a remote site.

Use the FTPCD command to change the current directory before calling GETSITEFILE if the file you want to find is not in the current directory.

The /next option, when used in a loop, allows command scripts to iterate through the entire contents of a directory and process all files and sub-folders matching the wildcard pattern. The matches are not returned in a guaranteed sort order. Without the /next option, repeated calls to GETSITEFILE will return the same file or sub-folder that first matched the [ file name ] argument unless it was deleted or renamed after the previous call. Use of the /next option together with the /timeout option is not supported.

If your script logic deletes files or moves them out of the current folder you may use GETSITEFILE in a loop without the /next option. The /next option should only be used on static folders. Using the /next option in a folder where files may be added, renamed, moved, or deleted may result in some files being skipped and other files processed multiple times because each successive /next moves one ordinal position in the directory listing. Please use the FTPDIFF command instead of either FTPGETFILE or GETSITEFILE if you project requirements include processing dynamic folders where files may be added, renamed, moved or deleted during processing.

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

Consider the following example where Robo-FTP waits indefinitely for any file with a .rdy extension to appear on the site.

Once a matching file appears on the remote site, the file name is saved in the %sitefile variable and script execution resumes.

Consider the following example where all the files in the current directory are retrieved from a remote site.

The /newest and /oldest options are normally used with a wildcard [ file name ] to obtain the name of the newest or oldest file present. 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. Use of the /newest and /oldest options with the /next option is not supported.

Consider the following example where all files are retrieved from a remote site beginning with the oldest.

If you wish to monitor a site directory other than the current directory, you must issue an FTP CWD command first to change to this directory. Consider the following example where the current directory is changed before looking for any file with a .txt or .rtf extension.

The /incldirs option may be used if you wish remote site directory names to be returned along with regular file names as they are found. When a directory is found, it is saved in the %sitedir variable and the %sitefile variable is set to an empty string. The /oldest and /newest options have no affect on the directory names returned by the GETSITEFILE command. Consider the following example that shows how directory files are distinguished from other files.

To descend into the directory returned by GETSITEFILE, you’d use the following command.

The date and time of the file obtained with the command is saved to three internal variables named %sitefiledate, %sitefiledatetime, and %sitefiletime. This permits you to directly compare the file’s date and time to values of your choosing. Consider the following example that shows how a file created on a specified date after a specified time may be found.

When connected to HTTP/HTTPS sites you may encounter situations where the name of a resource on the remote site contains characters that are reserved, unsafe, or otherwise unprintable. In these situations, web servers allow you to "percent encode" the required character by replacing it with a percent sign and the two digit hexadecimal representation of the character's position in the ASCII character set.

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 raw directory listing format that is currently unsupported.

GETNEXTFILE is the equivalent function for getting details about local files and folders.

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.