SYNC - Synchronize local folder(s) with an FTP site

Syntax:	SYNC	[ /options ]
	SYNC	[ local path ] [ /options ]
	SYNC	[ local path ] [ server dir ] [ /options ]
Arguments:	[ local path ]	An optional variable or string defining a local folder or a path name containing a wildcard pattern that defines the beginning point on the local PC from which to begin synchronization; if this parameter is omitted Robo-FTP’s working folder is the starting point.
	[ server dir ]	An optional variable or string defining the FTP site directory to synchronize; [ server dir ] is only permitted when [ local path ] is specified and may be a directory name only (no file names or wildcard patterns permitted).
Options:	/activelist	Force Robo-FTP to obtain an updated listing of the remote folder prior to processing each file on the remote site. Without this option, Robo-FTP maximizes the speed of the synchronization process by obtaining directory listings only when absolutely necessary. The /activelist option may significantly increase the time required to complete a SYNC operation so it should be used only if files on the remote site are likely to change during the synchronization process.
	/allowerrors	Normally SYNC will stop if a local file system or FTP site file I/O error occurs (e.g. a file is write-protected); specify this option if you want SYNC to ignore such errors and synchronize all the files it possibly can.
	/delete=xx	This is the SYNC command’s orphan control option; “orphans” are defined as files that exist on either the local PC or the FTP site, but not both; this option takes three forms: /delete=local, /delete=server, or /delete=both; unless /delete is specified, orphans are sent to the opposite system; use this option to control the deletion of orphans if you do not wish to include them in the synchronization process; the /delete and /skip options may be combined to create a one-way mirroring effect.
	/emptydirs	Normally SYNC will not create directories on the the FTP site nor empty folders on the local PC if there are no files in the corresponding folder or directory on the remote system. You can alter this behavior and allow empty directories and folders to be created by including this option.
	/integrity=xx	Use file integrity checking as the files are synchronized (FTP and FTPS servers only).
	/localdate	Always preserve the date and time stamp of the local file. This option overrides the default behavior of preserving the local date on uploads and the server date on downloads.
	/lower	Convert file / path name to lower case before comparing file names and before uploading files to the FTP site.
	/nospaces	Replace space characters embedded in local file names with underscores, and replace underscore characters embedded in file names found on the FTP site with space characters, when file names are compared, and then possibly uploaded or downloaded respectively.
	/serverdate	Always preserve the date and time stamp of the server file. This option overrides the default behavior of preserving the local date on uploads and the server date on downloads.
	/skip=xx	Do not synchronize changes from the specified location. The supported values are: /skip=local and / skip=server;
	/skip_changing	Ignore any file if its size is not stable for one second.
	/skip_changing_seconds=xx	Ignore any file if its size is not stable for the specified number of seconds. Values between 1 and 60 are allowed.
	/subdirs	Descend into all folders beneath the current or specified local folder and contiue synchronization on all files therein; the corresponding directory structure is created on the FTP site if it does not exist when files are uploaded and vice versa when files are downloaded.
	/type=xx	The type of FTP file transfer to perform: ASCII, BIN, or EBCDIC; if this option is omitted type BIN is used unless Robo-FTP is connected to a Managed Site, in which case the site's Default Transfer Mode is used.
	/tz=xx	Set the number of hours to add or subtract to the timestamp of server files when comparing them to local files. This value is expressed as a positive or negative integer. This option is unnecessary if the remote site supports the /precisetime option of the FTPLOGON command. This option is functionally equivalent to calling the TIMEZONE command so this adjustment persists after the execution of the current line of script. This option is deprecated in favor of the TIMEZONE command.
	/upper	Convert file / path name to upper case before comparing or saving it on the FTP site.
	/verbose	Include transfer details (e.g., file sizes, transfer times) in the log file and console window for each file transferred during the synchronization process. By default this information is suppressed and only summary information is output.

Beginning with v2.0, the behavior of the SYNC command has been changed. Much of the console window and log file output during the synchronization process has been eliminated by default (old behavior restored using the /verbose option). Furthermore, the performance of the synchronization process has been significantly improved by caching FTP site directory information by default (old behavior restored using the /activelist option).

This script command synchronizes files between the local PC and the FTP site. By synchronization we mean a process whereby individual files stored on the local PC and the FTP site are identical in content and also have the same date/time stamp. Upon completion of the command, the %synccount script variable contains the total number of files transferred during synchronization.

Synchronization can be a time-consuming process especially if the /activelist option is used and if there are many files in the local folder and/or on the FTP site.

To accomplish this, Robo-FTP begins by scanning the specified local folder and comparing file names against those presently on the FTP site. If a file name is the same, Robo-FTP then compares the two files’ date/time stamps. If they are the same or the local file is older, Robo-FTP moves on to the next file. If the local file is newer or does not exist on the FTP site, Robo-FTP uploads the file to the FTP site and, once the file is successfully saved on the FTP site, Robo-FTP attempts to modify the date and time of the server's copy of the file to match the date and time of the local file. (This is the same thing that the /localdate does on the SENDFILE command.) Robo-FTP continues with all files in the [ local path ], and in subfolders (if /subdirs is specified), until all files are compared. If /serverdate is used then after the file is uploaded Robo-FTP obtains the date/time stamp of the remote file and sets the local file to match. (This is the same thing that the /serverdate does on the SENDFILE command.)

Next, Robo-FTP does the opposite. It scans the FTP site beginning in the current directory (or in [ server dir ] if specified) and when a matching file name is found, the two files’ date/time stamps are compared. If they are the same or the file on the FTP site is older, Robo-FTP moves on to the next file. If the file on the FTP site is newer or does not exist locally, Robo-FTP downloads the file to the local PC and changes the local PC file’s date/time stamp to match the file on the FTP site. (This is the same thing that the /serverdate does on the RCVFILE command.) Robo-FTP continues with all files in the FTP site directory, and in subdirectories (if /subdirs is specified), until all files are compared. If /localdate is used then after the file is downloaded Robo-FTP obtains the date/time stamp of the local file and attempts to change the server file to match. (This is the same thing that the /localdate does on the RCVFILE command.)

Once these two operation are complete, the files in the designated paths on the local PC and the FTP site are synchronized, they are the same and share the same date/time stamps.

When synchronizing you may want to consider what to do when there is a file on the local PC that is not on the FTP site and vice versa. Such files are referred to as “orphans”. Normally, Robo-FTP simply transfers the orphan to the opposite system. This is not always what you want to do. The /delete option instructs Robo-FTP to delete orphans locally, on the FTP site, or in both places.

Use the /skip option to perform a one-way synchronization. The supported values are: /skip=local and / skip=server. The /delete and /skip options may be combined for a one-way mirroring effect. To do a one-way mirror from the local machine to the server:

The following example synchronizes Robo-FTP’s working folder with the current directory on the FTP site:

The following example synchronizes Robo-FTP’s working folder with the current directory on the FTP site and ignores any file I/O errors (e.g., a file is write-protected or in use by another process) that may occur:

The following example synchronizes a specific local folder with the current directory on the FTP site:

The following example uses a wildcard to synchronize files with the same file extension from a specific local folder with the current directory on the FTP site:

The success of wildcard matching 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. Some respond to HEAD requests and are partially compatible. Some supported HTTP listing types like APACHE_DEFAULT include file sizes rounded to the nearest megabyte or kilobyte and are therefore not fully compatible. Contact technical support if you have an urgent need related to a raw directory listing format that is currently unsupported.

The following example synchronizes files from a specific local folder with the specific directory on the FTP site:

The following example descends into local subfolders (and corresponding server subdirectories) as well as deleting orphans on both sides:

The /integrity option enables file integrity checking to be used during the synchronization. When using file integrity checking, the checksum is calculated for both the server file and the local file, using the algorithm specified. These checksums are then compared to verify the integrity of the file. If these do not match then an error is returned. The /integrity option is only supported by FTP and FTPS servers that support the specified file hashing algorithm, and will not work on SFTP, HTTP, or any other type of server. The possible algorithms are:

Consider the following example where all files are synchronized with file integrity checking using the SHA256 algorithm.

If you are not using the TIMEZONE script command, the /tz option may be used to account for differences in time zones between Robo-FTP and the remote server. This is important for accurate file date and time stamp comparisons. For example, if you are in the Central U.S. time zone and the remote server is located in the Eastern U.S. time zone then files created at the exact same moment will appear one hour older on the remote server. The syntax for subtracting one hour from the server time is as follows:

Further, if the remote server is located in the Pacific U.S. time zone there is a two-hour difference the other way between local time and the remote server. To allow for this, the following syntax adds two hours to the server time:

When file date/time stamps are compared, the determination of the newest file is based on the last modified date and time. If the remote server does not return seconds in the time the comparison is based only on the hour and minute

FTP sites hosted on Unix systems often return dates without times for any files that were last modified six (6) or more months prior to the current date. When connected to this type of FTP site, Robo-FTP assumes 12:00 AM since the actual time is not available for comparison purposes.

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.

The /nospaces option causes Robo-FTP to convert space characters found in the local folder and file names to underscores before comparisons are performed and before creating corresponding directories on the FTP site and uploading files. This resolves an incompatibility in file naming between Windows and Unix since Unix does not allow space characters in file names.

The /lower and /upper options cause Robo-FTP to convert local folder and file name(s) specified by [ file name ] and [ new file ] to lower or upper case, respectively, before comparisons are performed and before creating corresponding directories on the FTP site and when uploading files.

The /type option specifies the type of file transfer to perform. If this option is used while connected to a Managed Site, the specified value overrides the site's Default Transfer Mode. EBCDIC file transfer mode is not permitted unless IBM Host Features mode is enabled and should only be attempted after verifying /type=ascii produces unsatisfactory results with a given site.

If you cancel a SYNC command while it is in progress, most likely it will be necessary to log off and log back on the FTP site to resume any further file transfers.

For all successfully completed operations performed by the SYNC command, the %downloadfiles, %uploadfiles, %deletefiles, %ftpdeletefiles, and %copyfiles internal script variables are set accordingly.