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 FTP site directory listing prior to accessing information about a file on the FTP site. By default, Robo-FTP obtains a directory listing only when absolutely necessary (e.g., after descending into a new sub-directory) and uses this information to synchronize with local files. This ensures that the synchronization process proceeds as quickly as possible. However, using this method it is possible to miss changes or updates to the FTP site. IF FILES ON THE FTP SITE IS SUBJECT TO CHANGE DURING THE SYNCHRONIZATION PROCESS, USE OF THIS OPTION IS RECOMMENDED. Use of the option is likely to significantly increase the length of time for SYNC to complete.
	/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 one of the SYNC command’s orphan control options (the other is /skip); “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; if neither /delete nor /skip 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; /delete and /skip are mutually exclusive.
	/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.
	/localdate	When storing a file, change the file’s last modified date to match the date and time of the corresponding local file. The /localdate option is not supported for SFTP.
	/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	When storing a file, change the file’s last modified date to match the date and time of the corresponding server file.
	/skip=xx	This is the second of the SYNC command’s orphan control options (the other is /delete); “orphans” are defined as files that exist on either the local PC or the FTP site, but not both; this option takes three forms: /skip=local, / skip=server, or /skip=both; if neither /skip nor /delete is specified, orphans are sent to the opposite system; use this option to ignore orphans if you do not wish to include them in the synchronization process; /delete and /skip are mutually exclusive.
	/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, the default file transfer type set when the FTP site was defined is used; if the FTP site has not been previously defined, type BIN is used.

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 obtains the date/time stamp of the file on the FTP site and changes that of the local file to match. (This is same thing that the /serverdate 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 /localdate is used then after the file is uploaded Robo-FTP obtains the date/time stamp of the local file and changes that of the server file to match. (This is same thing that the /localdate does on the SENDFILE command.) If neither is used then /serverdate is used by default.

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 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 changes that of the server file to match. (This is same thing that the /localdate does on the RCVFILE command.) If neither is used then /serverdate is used by default.

Once these two operation are complete, the files in the designated paths on the local PC and the FTP site are synchronized, namely 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 SYNC command’s /delete and /skip options give you control over orphans if you do not want them automatically uploaded and/or downloaded. As the option names imply, you may instruct Robo-FTP to delete orphans or to skip over (i.e., ignore) them locally, on the FTP site, or in both places.

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 ignors 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 synchronizes a set of files with the same file name extension from a specific local folder with the current directory on the FTP site:

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, then these are compared to verify the integrity of the file. If these do not match then an error is returned. (NOTE: Not all servers support this option.) The possible algorithm 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 accounts for differences in timezones between Robo-FTP and the FTP site. This is important for accurate file date and time stamp comparisons. For example, if you are using Robo-FTP in the Central U.S. timezone and the FTP site is located in the Eastern U.S. timezone there is a one-hour difference between the file system times of Robo-FTP’s PC and the FTP site. To allow for this in the SYNC command, the command would look like the following which indicates that the FTP site is one hour ahead:

Further, if the FTP site is located in the Pacific U.S. timezone there is a two-hour difference the other way between the file system times of Robo-FTP’s PC and the FTP site. To allow for this, the command would look like the following which indicates that the FTP site is two hours behind:

When file date/time stamps are compared. the determination of the newest file is based on a comparison of the time and date each file was last written to. The file write time comparison is based only on the hour and minute (seconds are ignored).

If the FTP site is hosted on a Unix system and the server file was last written to during the current calendar year, the time and date comparison is based on the stored month, day, and year along with the stored hour and minute of each file. However, if the server file was last written to in a previous calendar year, the comparison is based on the stored month, day, and year - but the server file time is assumed to be 12:00 AM (since the actual time is not available to Robo-FTP for comparison purposes.)

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 overrides the default set for a given FTP site. EBCDIC file transfer mode is not permitted unless IBM Host Features mode is enabled.

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.