Revised August 2023; see History
ATSYNC {hostdir} {,pcdir} {switches}
(Used only from ATE) ATSYNC does a one-way synchronization of the contents of a directory or a set of files, from the server to the ATE client. This is particularly useful for resources—images, icons, auxiliary files—that are distributed with an application—i.e., on the server—but which need to be present on each individual client.
Parameters
hostdir
specifies the source of the files to be transferred. It can be either a directory on the host, in DevPPN or native format, or a file containing a list of files to transfer; see /F switch below. If hostdir is not specified—i.e. the command line starts with a comma or a switch or is blank—it uses the current directory. If hostdir contains forward slashes, enclose it in quotes.
pcdir
specifies the target directory on the PC, using native Windows directory syntax, with optional embedded environment variables using the %envvar% syntax. If not present, the default is %ATEPERMCACHE%. In the case of the /F switch, pcdir just sets the default directory for entries in the list file that do not contain explicit target directories.
Switches
Switch |
Function |
|---|---|
/A{UX} |
Use the ATE aux port transfer protocol as an alternative to FTP. The switch is set automatically in the ATSD environment, where FTP is usually not configured. |
/C{ONT} |
Continue trying even after a transfer error. |
/D{DELETE} |
Delete files from PC target directory not in host source directory. |
/F{ILES} |
Replaces the HostDir parameter with a file containing the list of files to transfer. See Comments, plus History note for 6.1.1366. |
/L{IST}{:file} |
Output to file rather than screen. If filename ("f") is not specified, output file is atsync.lst. |
/NOERR |
Don't display FTP errors, just return status. |
/NOHASH |
Don't use file hash to determine if updated needed. This may speed up the process slightly for large files. |
/NOTIME |
Disable any use of the timestamp to decide whether the file needs to be transferred. This is a moot point, except when the /NOHASH switch is also used, in which case the determination will be based solely on the file size. The /NOTIME switch will be ignored for ATE versions prior to 6.1.1368.1. |
/P{RGDLG} |
Display progress dialog. |
/U{PDATE} |
Transfer file only if source newer than destination. |
/V2 |
Requests the new FTP implementation in ASHNET 1.6.138. Note that if the switch is specified, it will still use the old (FTPDLX) implementation if the ASHNET is not version 138+. This switch should significantly reduce the amount of time it takes to synchronize many files. /V2 is the default value. |
/? |
Writes switch listing and usage info to the screen. |
Comments
ATSYNC only replicates files from the server to the client; it is not a general purpose two-way synchronization utility.
Files are transferred if they are different and the modification timestamp on the server is newer than that on the client. To ignore the timestamp, use the /NOTIME switch.
Unless the server and client copies of a file are identical, based on hash, modification time, and/or file size (see /NOHASH and /NOTIME switches), ATSYNC transfers the server's copy of the file to the client, even if the timestamp on the client copy of the file is newer than that on the server copy.
ATSYNC relies on FTP (or SFTP) as configured on the ATE client. The FTP root directory must agree with the root directory as seen by A-Shell on the server. See FTP Debugging.
The ATSYNC protocol is optimized to minimize latency time, especially if the /V2 switch is used, and to eliminate unnecessary transfers. It is therefore much more efficient than simply doing a wildcard transfer from the server to the client.
The /F{ILES} switch uses ATEAPX which must be present in the BAS: directory.
See Also
| • | Discussion on the ATE environment variable. |
History
2023 August, A-Shell 6.5.1470, ATSYNC 1.3(123): /V2is now the default. 1.3(123)
2015 September, A-Shell 6.1.1417: AG_FTPSYNC (ATSYNC) fixes and refinements:
| • | Client will now accept a timestamp from the server which it uses to fine-tune the test for whether the source file is newer or older than the destination. This is useful in situations where the system clock and/or time zone is different enough between the server and client to create confusion as to which version is actually newer. |
| • | Now, when the hashes are different (unless /NOHASH specified) or when the file sizes are different, the file is only transferred if the source timestamp is newer. Disable that logic with /NOTIME to force a transfer unless the hashes and sizes are the same. Previously it was always transferring files if the sizes were different. |
| • | New version of ATSYNC adapts to the behavior of the client (based on whether it is before 6.1.1417.0 or not). This fixes an issue in which the /NOHASH switch was previously being misinterpreted by the client, causing the sync operation to not take place even if needed. |
| • | Setting DEBUG mode was causing the final FTP operation to fail. |
| • | Clean up the ambiguity in the atsync.lst file relating to the client transfer log which is normally appended to the end. In cases where no files needed to be transferred, a previous copy of the client transfer log was being included. |
| • | Clean up several other minor user interface issues. |
Note that the updated ATE client will resolve these issues regardless of whether the copy of ATSYNC.LIT on the server is updated.
2014 June, A-Shell 6.1.1387: /D now explicitly ignored with /F mode. The delete option doesn't really make much sense when not syncing an entire directory; attempting it could have had strange side effects.
2013 December, A-Shell 6.1.1368, 1369, 1370:
| • | In SBX mode, the normal /L message ("See ...") is eliminated, allowing for totally silent operation. For all other cases, it now reports the total time of the transfer operation, making it easier to see how much faster sync operations are with the /V2 switch. |
| • | Add /V2 switch. |
| • | Zero-byte files are now transferred just like any other files. Previously they were flagged to be transferred but then skipped by the actual transfer routine. |
| • | Add /NOTIME switch. |
2013 November, A-Shell 6.1.1366, ATSYNC.LIT 1.3(114): Now includes the switch /F{ILES} allows you to replace the HostDir parameter with a file containing the list of files to transfer:
.ATSYNC HostDir{,PCdir}/FILES
The layout of the HostDir file should be a series of lines in the following format:
hostfile{,pcfile}
Each hostfile specification may be in either DevPPN or native format and may be partially or fully qualified. The pcfile specification can be omitted, in which case the files will be transferred to the directory specified by the PCdir parameter on the ATSYNC command line. To override that, provide a fully qualified PC filespec in the pcfile parameter.
You may insert a ";" at the start of the line to comment it out.
ATE will create a log file called %atecache%\ateftp.log for each file transfer, using the format:
status,hostfile,pcfile
Where status will be 0 for a successful transfer, else an error code. Hostfile and pcfile will be the fully qualified host and PC file specifications for the transfer.
If you specify the ATSYNC /L switch, the ateftp.log file contents will be appended to the list file. Otherwise, you can retrieve it manually using AG_FTP or some other method.
2013 August, A-Shell 6.1.1359, ATSYNC 1.2(112): Now works both as a LIT and as a subroutine; just copy the LIT to SBX. The XCALL syntax consists of just one parameter containing the command line otherwise passed to the LIT, i.e.
CMD$ = "MYICONS:,%ATE%\myicons /P/L"
xcall ATSYNC, CMD$
to retrieve the exit status, you can call it via XFUNC, i.e.:
STATUS = XFUNC("ATSYNC", CMD$)
STATUS values:
Value |
Meaning |
|---|---|
0 |
Ok |
1 - 200 |
ASB error except for "1" and "3," which see see below |
< -7 |
|
=> 30000 |
|
1 |
Login failure or ^C interrupt |
3 |
Invalid SFTP port, or invalid local directory, or unable to link to FTPDLX, or unable to create temp file |
-2 |
Command line syntax error (missing comma?), or out of memory |
-3 |
Unable to open temp file |
-4 |
File sync disabled by ATE |
-5 |
Can't link to ashnet library, or opcode sequence error |
-6 |
Temp file error or opcode sequence error |
-7 |
No hostdir (not specified and not logged in) |
If you'd like to customize the display, contact us for the source code.
2013 May, A-Shell 6.1.1353, ATSYNC: Add /A{UX} switch.
2009 January, A-Shell 5.1.1177: The ATSYNC mechanism can now be disabled by creating a registry item DisableFileSync (DWORD) within the current ATE profile (HKCU\Software\MicroSabio\JBCT\ATE\Hosts\profile-name\DisableFileSync) and setting it to 1. The motivation behind this odd feature is to accommodate certain "power users" (presumably developers or tech support staff) who have to connect remotely to multiple sites (running different versions of the application) and who don't necessarily want to have icons, bitmaps, subroutines, etc. synchronised to the PC each time. You are on your own to create and set this registry value, but once set, ATSYNC will abort immediately with error -4.
2008 December, A-Shell 5.1.1131, ATSYNC.LIT 1.0(107): Now supports hash codes as a way of making sure whether files are different or not. Also, it now works from within a CMD or DO file. Previously, the CMD file interfered with the input of status responses coming from the ATE client, causing it to act as if no files needed transferring.
