GETFILE         Get properties of local file(s)

Top  Previous  Next

Syntax:

GETFILE

[ file name ] [ /options ]

Arguments:

[ file name ]

Variable or string defining a file or path name to look for; wildcard characters allowed; if no path is defined

Options:

/incldirs

Search sub-folders for files matching the [ file name ] argument.

 

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

 

 

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

 

This script command searches the current local directory for the file specified in the [ file name ] argument.  If a match found, a set of internal variables is populated as follows: the file name is saved in the %nextfile variable; the %nextpath variable contains the full local path and filename; the %nextfolder variable contains the path without the filename; the date and time of the file are saved in the %nextfiledate, %nextfiledatetime, and %nextfiletime variables; and the size of the file, in bytes, is saved in the %nextfilesize variable. Your command scripts may conditionally branch to appropriate logic depending on values of these variables. For example, your script may evaluate %nextfiledatetime to transfer only .TXT files created within the past 24 hours.

 

GETFILE is commonly used either to check the status of a specific file with a known file name or to find a group of files using a wildcard pattern and then process them one at a time. 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 folder during the waiting period. If the file does not appear before the timeout expires $ERROR_WAIT_TIMED_OUT is returned.

 

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

 

GETFILE ignores flies exclusively locked by other applications. This command also ignores all files with the "hidden" or "system" file system attribute. You can use the DOS attrib.exe program to change these attributes.

 

This command is functionally equivalent to the GETNEXTFILE script command except for two important differences. The first difference between GETFILE and GETNEXTFILE is their behavior when called repetitively with a wildcard character in the [ file name ] argument. In this situation, each subsequent call to GETFILE 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 GETFILE each return a different set of internal variable values and the fourth call results in a "No File Found" error. The GETREWIND command may be used to start over at the top of the list. In contrast, when GETNEXTFILE 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 a file named "ReadMe.txt" exists in the current local directory. In the following example, the first line will successfully populate %nextfile and the other internal variables but the second line will cause a "No File Found" error.

 

GETFILE "ReadMe.txt"

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

 

The second line returns an error because subsequent calls to GETFILE 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 GETNEXTFILE if you only need to check the existence, timestamp, or size of a single file with a known filename.

 

Important

Please use the GETNEXTFILE command without the /next option instead of GETFILE if you need to process a group of files found using a wildcard pattern and your script logic moves or deletes files out of the working folder. If you project requirements include wildcards and processing dynamic folders (where files may be added, renamed, moved, or deleted during processing) please use the DIFF command instead of either GETFILE or GETNEXTFILE.

 

If your script logic loops through the current folder and deletes or moves files out of the folder please use the GETNEXTFILE command without the /next option instead of GETFILE. Please use the DIFF command instead of either GETFILE or GETNEXTFILE if your project requirements include processing dynamic folders where files may be added, renamed, moved or deleted during processing.

 

Important

If your script logic deletes files or moves them out of the current folder you may use GETNEXTFILE 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 DIFF command instead of either GETFILE or GETNEXTFILE if you 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 GETFILE command. When either of these options is used, Robo-FTP always returns the newest or oldest file respectively.

 

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

 

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

 

To understand this second difference, suppose the current local 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 GETFILE with various arguments and options. (Assuming GETREWIND is executed between calls to GETFILE.)

Command syntax

Error

%nextfile

%nextfolder

GETFILE "one.txt"

No

one.txt

<working>

GETFILE "sub" /incldirs

Yes

empty

emtpy

GETFILE "two.txt" /incldirs

No

two.txt

<working>\sub

GETFILE "deep" /incldirs

Yes

empty

empty

GETFILE "three.txt" /incldirs

No

three.txt

<working>\sub\deep

 

Contrast the results of GETFILE above with the results of GETNEXTFILE below:

Command syntax

Error

%nextfile

%nextfolder

GETNEXTFILE "one.txt"

No

one.txt

empty

GETNEXTFILE "sub" /incldirs

No

empty

sub

GETNEXTFILE "two.txt" /incldirs

Yes

empty

empty

GETNEXTFILE "deep" /incldirs

Yes

empty

empty

GETNEXTFILE "three.txt" /incldirs

Yes

empty

empty

 

 

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

 

:fetch_file

GETFILE "*"

IFERROR= $ERROR_NO_FILE_FOUND GOTO no_more_files

SENDFILE %nextfile

IFERROR!= $ERROR_SUCCESS GOTO send_error

GOTO fetch_file

:no_more_files

[ ... ]

:send_error

[ ... ]

 

 

The last modified date and time of files found with GETFILE are saved to three internal variables named %nextfiledate, %nextfiledatetime, and %nextfiletime. Consider the following example that cycles through all files in the current directory and any subdirectories until it finds one created after a specified date.

 

:fetch_file

GETFILE "*" /incldirs

IFERROR= $ERROR_NO_FILE_FOUND GOTO no_more_files

IFDATE< %nextfiledate "07-31-11" GOTO fetch_file

MESSAGEBOX "File " & %nextfile & " created on or after July 31, 2011!"

STOP

:no_more_files

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

STOP

 

The following example sets the /timeout option to zero which causes Robo-FTP to wait indefinitely, polling the current local directory periodically until a file with a name matching *.rdy is found. Script execution resumes on the next line when a matching file is found.

 

GETFILE "*.rdy" /timeout=0

MESSAGEBOX "Found a file named " & %nextfile

STOP

 

If you only need to confirm the existence of a specific local file with a known filename you may wish to use the IFFILE or IFNFILE command instead.

 

FTPGETFILE is the equivalent function for getting details about a remote file.

 

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): GETREWIND, GETNEXTFILE, FTPGETFILE, FTPGETREWIND, GETSITEFILE, FILECOMPARETO, FILECOMPAREFROM

See also: Using the %nextfile, %nextpath, and %nextfolder Variables, Using the %nextfiledate, %nextfiledatetime, %nextfilesize, and %nextfiletime Variables