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

This script command searches the current remote directory for the file or folder specified in the [ file name ] argument. If a match is found, a set of internal variables is populated as follows: if 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. Your command scripts may conditionally branch to appropriate logic depending on values of these variables. For example, your script may evaluate %sitefiledatetime to transfer only .TXT files created within the past 24 hours.

GETSITEFILE is commonly used either to check the status of a specific file or folder with a known name or to find a group of files using a wildcard pattern and then process them one at a time. 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. Although both files and sub-folders may be returned, there is no guaranteed sort order. Without this option, repeated calls to GETSITEFILE will continue to 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.

For most reliable operation, use the /next option only on static folders (i.e., where no new files are being added and none are being deleted) because each successive /next moves one ordinal position in the directory listing. Do not use the /next option if you need to process a group of files found using a wildcard pattern and your script logic adds, moves, or deletes files. Use the FTPDIFF command if you project requirements include processing dynamic folders.

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

The GETSITEFILE 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.

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. Use of these 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” 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. 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.