GETNEXTFILE - Get properties of local file(s) or folder(s)

Syntax:	GETNEXTFILE	[ 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 Robo-FTP’s working folder is used.
Options:	/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 or folder name in a local folder; omit this option to obtain the first file from a given local folder; if you wish to obtain subsequent files from this same folder, 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 folder.
	/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 local 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 its saved in the %nextfolder and %nextdir variables. If the matching item is a file, the name is saved in the %nextfile variable and its full path name is saved in the %nextpath variable. The date and time of the file are also saved in the %nextfiledate, %nextfiledatetime, and %nextfiletime variables. The size of the file, in bytes, is saved in the %nextfilesize 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.

GETNEXTFILE ignores flies that are exclusively locked by other applications or that are inaccessible due to security permissions. 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. GETNEXTFILE will not ignore a hidden file if you specify that file's name explicitly.

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. The polling feature associated with the /timeout option can be used to implement the hot send behavior whereby Robo-FTP automatically uploads files when they are placed in a specific folder.

Use the WORKINGDIR command to change the current directory before calling GETNEXTFILE if the file or folder you want to find in 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. Although both files and sub-folders may be returned, there is no guaranteed sort order. Without the /next option, repeated calls to GETNEXTFILE 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 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.

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

Consider the following example where Robo-FTP waits indefinitely for any file with a .txt or .rtf extension to be created in its working folder.

When a file with a matching name exists, its name is saved in the %nextfile variable, its path and name is saved in the %nextpath variable, and script execution resumes. If no such file exists, Robo-FTP waits for the file to appear.

Consider the following example where all the files in a specified sub-folder of the current working folder are sent to an FTP site.

Consider the following example in which the file and folder names in the current local folder are identified and displayed by using the /next option.

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 sent to an FTP site beginning with the newest. Since each file is deleted after it is uploaded, a different file will be newest on each loop iteration.

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

The date and time of the file obtained with the command is saved to three internal variables named %nextfiledate, %nextfiledatetime, and %nextfiletime. 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 newer than a specified date 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.

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.

GETSITEFILE is the equivalent function for getting details about remote 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.