GETSITEFILE        Get file and directory names from a remote site

Top  Previous  Next

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 site directory name(s) as they are found. (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.

 

 

In versions prior to v1.50, this command was named GETSERVERFILE. Both are accepted.

 

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. If a matching file or directory is detected, the file name is saved in the %sitefile or %sitedir variables. The date and time of the file or directory are also saved in the %sitefiledate, %sitefiledatetime, and %sitefiletime variables. The size of the file (excluding a directory), in bytes, is saved in the %sitefilesize variable.

 

This command can be used to implement the hot receive behavior whereby Robo-FTP automatically retrieves files as they are added to a remote site.

 

The /next option allows the entire contents, both files and subdirectory names, of site directories to be traversed and saved in variables for use in script processing. See Displaying Files and Directories on an FTP Site for an example. The FTPGETREWIND command may be used to start over at the top of the of files. Use of this option with the /timeout option is not supported.

 

Important

For most reliable operation, use the /next option only on static server directories (i.e., where no new files are being added and none are being deleted) since each successive /next skips one file as Robo-FTP scans through a given directory. When /next is omitted, this command always returns the first file that appears in the directory (i.e., the first file that appears in the directory listing resulting from an FTP LIST command).

 

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

 

GETSITEFILE "*.rdy" /timeout=0

 

Once such a file exists, 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.

 

GETSITEFILE "*" /timeout=2

IFERROR= $ERROR_WAIT_TIMED_OUT GOTO rcvd_last_file

RCVFILE %sitefile

IFERROR GOTO rcv_error

:label

GETSITEFILE "*" /next

IFERROR= $ERROR_NO_FILE_FOUND GOTO rcvd_last_file

RCVFILE %sitefile

IFERROR GOTO rcv_error

GOTO label

:rcvd_last_file

 

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.

 

:next_file

GETSITEFILE "*" /oldest

IFERROR= $ERROR_NO_FILE_FOUND goto label

RCVFILE %sitefile

FTPDELETE %sitefile

GOTO next_file

:label

 

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.

 

FTPCD "newdir/test"

GETSITEFILE "*.txt" /timeout=2

 

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.

 

:look_for_directory

GETSITEFILE "*" /incldirs

IFERROR= $ERROR_NO_FILE_FOUND GOTO error

IFNSTRCMP %serverfile "" GOTO look_for_directory

; both %sitefile and %sitedir will not be empty at same time

DISPLAY %sitedir

GOTO look_fordirectory

:error

 

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

 

FTPCD %sitedir

 

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.

 

:not_new

GETSITEFILE "*" /next

IFERROR= $ERROR_NO_FILE_FOUND GOTO error

SET filedatetime = "file date is " & %sitefiledatetime

DISPLAY filedatetime

IFDATE!= "06-30-02" GOTO not_new

IFTIME< "12.00.00" GOTO not_new

MESSAGEBOX "found file created after 12PM on June 30, 2002"

STOP

:error

 

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.

 

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

 

 

Related Commands: FTPGETFILE, FTPGETREWIND

See also:GETFILE, GETNEXTFILE, GETREWIND, FILECOMPARETO, FILECOMPAREFROM,
The Hot Receive Feature, Using the %sitefile and %sitedir Variables,
Using the %sitefiledate, %sitefiledatetime, %sitefilesize, and %sitefiletime Variables