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 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 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	Timezone adjustment (in hours) between the local PC and the FTP site; value is expressed as a positive or negative integer; used when local and server file’s time/date stamps are compared. 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 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 may be used to account for differences in timezones 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. timezone and the remote server is located in the Eastern U.S. timezone then files created at the exact same time 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. timezone 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.

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