Robo-FTP User's Guide > Script Programming > Script Commands > All Script Commands > GETDIFF - Get specific changes within local PC file system

Syntax:	GETDIFF	[ dbfile ]
Arguments:	[ dbfile ]	Optional Variable or string specifying a snapshot database file. If omitted, the default value is “snapshot_local.sql”. When [ dbfile ] is specified without a full path the default path is used.
Options:	/commitlast	Mark current difference "done" on the next call to GETDIFF.
	/incldirs	Allows returning new or deleted directories.
	/smallerthan=xx	Only retrieve changes for which the file is smaller than the provided file size (in bytes). Also accepts special value "unset" (see section "Special value unset", below).
	/largerthan=xx	Only retrieve changes for which the file is larger than the provided file size (in bytes). Also accepts special value "unset" (see section "Special value unset", below).
	/olderthan=xx	Only retrieve changes for which the file's last modified time is older than the provided date-time (using the same format as the built-in %datetime variable). Also accepts special value "unset" (see section "Special value unset", below).
	/newerthan=xx	Only retrieve changes for which the file's last modified time is newer than the provided date-time (using the same format as the built-in %datetime variable). Also accepts special value "unset" (see section "Special value unset", below).
	/difftype=xx	Specify the type of changes for which to look. You can either use this option multiple times or separate the values with a pipe character. See the section regarding %difffileid below for a list of possible options.
	/tag=xx	(For advanced users only.) Retrieve only changes corresponding to rows in the diff table for which tag column matches the provided tag or is NULL. Any such rows will subsequently be marked with the given tag if not already marked as such.
	/replay=xx	(For advanced users only.) When xx is true, and GETDIFF is provided with option /tag=TAGNAME, the command will return rows in the diff table for which the tag column is equal to TAGNAME. If xx is true, a /tag=TAGNAME option must be provided or the command will return an error.
	/clearnonmatching	(For advanced use) Removes any pre-existing entries from the diff table in the snapshot database that do not match the specified path.

The DIFF and GETDIFF commands work together to identify and process changes to local files.

The GETDIFF command sets the values of seven internal variables with details describing a change to a single local file. These details are pulled from a snapshot database where they were inserted by a previous call to the DIFF command. Subsequent calls to GETDIFF fetch the details of subsequent changes from the database. The GETDIFF command is typically used in a loop so that each detected change is processed during one iteration of the loop. Depending on your needs, the processing may involve one or more of the internal variables set by this command. It is possible for GETDIFF to report file changes in alphabetical order rather than folder hierarchical order depending on how the records are stored in the snapshot database. This command returns $ERROR_READ_EOF when there are no more differences in the database. The DIFFREWIND command is available to reset the file pointer to the first change recorded in the database.

If the [ dbfile ] argument is omitted, the default file name “snapshot_local.sql” file is used. An error occurs if the snapshot database file does not exist.

The GETDIFF command sets the values of the following variables that you can use in your script logic:

%difffileid	Type of change detected
%difffiletext	Text description of type of change detected
%difffilename	Name of changed file
%difffilepath	Full path of changed file
%diffnum	Sequential change number
%diffsize	The size of the file, in bytes
%diffdatetime	The date and time of the file

The possible values of %difffileid and %difffiletext are:

$DIFF_FILE_NOT_FOUND	5001	** File not found
$DIFF_FILE_IS_NEW	5002	** File is new
$DIFF_FILE_SIZE	5003	** File size changed
$DIFF_FILE_DATETTIME	5004	** File date/time stamp changed
With /incldirs:
$DIFF_DIRECTORY_NOT_FOUND	5005	** File not found
$DIFF_DIRECTORY_IS_NEW	5006	** File is new

To monitor only for specific type(s) of changes, use the /difftype option. To monitor for multiple types of changes, you can either use the /difftype option multiple times (for example, /difftype=$DIFF_FILE_SIZE /difftype=$DIFF_FILE_DATETIME) or separate the values with a pipe character (for example, /difftype=$DIFF_FILE_SIZE|$DIFF_FILE_DATETIME).

Here is a simple example that shows how GETDIFF might be used inside a loop to write a text file that lists all the changes found by DIFF:

DIFF "*"

:loop

GETDIFF

IFERROR= $ERROR_READ_EOF GOTO done

SET change = "File: " + %difffilepath + " " + %difffiletext

WRITEFILE "differences.txt" change /append

GOTO loop

:done

The following example loops through all changes and uploads only the new files to a remote site:

DIFF "*"

:loop

GETDIFF

IFERROR= $ERROR_READ_EOF GOTO done

IFNUM!= %difffileid $DIFF_FILE_IS_NEW GOTO loop

SENDFILE %difffilepath

GOTO loop

:done

If you need to restart the loop, use the DIFFREWIND command to reset the file pointer to the first difference recorded in the snapshot database.

Normally, all current differences are marked "done" when DIFF is called again. The /commitlast option increases fault tolerance by causing GETDIFF to mark the previously retrieved difference done. This way, a difference should not be processed twice if loop processing is interrupted after GETDIFF is called but before the full loop iteration is complete.

Note: Snapshot database files are small SQLite database files created by Robo-FTP to support the DIFF and FTPDIFF family of script commands.

Special value unset

The /smallerthan=xx, /largerthan=xx, /olderthan=xx, and /newerthan=xx options also accept a special value "unset". When provided, that corresponding option will be effectively disabled. This allows each option to be turned on or off selectively depending on the values of passed in variables. Consider the following usage:

SET upperlimit = "unset" ;; ensure that /smallerthan option is turned off

SET lowerlimit = 1024

GETDIFF /smallerthan=upperlimit /largerthan=lowerlimit

Related command(s): DIFF, DIFFREWIND, FTPGETDIFF