New documentation May 2016
xcall ATEAPX, hostspec, pcdir, pcfile, flags, status
ATEAPX.SBX transfers a file from application server to ATE client PC. It supports multiple protocols, pre/post verification, logging, etc.
Parameters
hostspec (String) [in]
File spec of source file on server; AMOS-style or native; may contain embedded %env% variables)
pcdir (String) [in]
Destination directory on PC using Windows native syntax; default %ate%\dsk0\001004
pcfile (String) [in]
File.ext for destination. May be left blank to use same file.ext from source. May also contain complete path, in which case pcdir should be empty. Note that if pcdir blank, and pcfile contains format file.ext and file is longer than 10 characters, you should prepend a ".\" to eliminate ambiguity.
flags (Num) ( [in]
One or more of the following options.
Symbol |
Value |
Description |
|---|---|---|
APXF_BINARY |
&h0000 |
binary transfer |
APXF_ASCII |
&h0002 |
ascii transfer |
APXF_NULL |
&h0004 |
'null' printer mode, always set; see Comments |
APXF_FTP |
&h0008 |
use FTP if server not Windows |
APXF_NOPOSTVERIFY |
&h0010 |
skip post-transfer verification |
APXF_PREVERIFY |
&h0020 |
pre-verify; skip transfer if destination already matches source |
APXF_NOVER |
&h0040 |
ignore version 0 when comparing versions |
APXF_LOGCURDIR |
&h0080 |
write ateapx.log entries to current ppn rather than opr: directory |
Definition file: ashinc:ateapx.def |
||
status (Signed Num) [out]
Value |
Description |
|---|---|
>0 |
file transferred / number of bytes transferred |
0 |
File transfer not needed or applicable |
-1 |
ATE required |
-2 |
host file doesn't exist |
-3 |
file transferred but failed to verify afterwards |
-4 |
FTP transfer error |
-98 |
A-Shell version on server not high enough for binary transfer |
- 99 |
ATE version not high enough |
Comments
If running in a local Windows environment—i.e. A-Shell/Windows standalone, P2P or remote desktop—then ATEAPX does nothing and returns status 0; file transfer not applicable.
If the APXF_PREVERIFY flag set, ATEAPX uses the MX_FILESTATS function to compare the source and destination files to determine if the transfer is actually needed. The small overhead of the pre-verification is almost always worth the chance to omit the transfer, except when the file to be transferred is very small or the chance of the destination matching the source is very slim.
If APXF_FTP flag set and the server is not Windows/ATSD, then ATEAPX first attempts to transfer the file using FTP protocol via the AG_FTP command sequence. If the FTP operation fails, it will retry one time before giving up and returning status -4.
If not using FTP, then instead it uses the existing ATE terminal channel to transfer the file—aka the 'null' auxiliary printer protocol.
The ateapx.log file in OPR: or the current directory, depending on the APXF_LOGCURDIR flag, provides useful information about the success or failure of transfers. To increase the level of detail in the log file, use SET DEBUG prior to the transfer.
See Also
| • | ATSYNC.LIT to transfer/sync many files from server to client |
| • | AG_FTP: invoke FTP from client directly |
| • | FTP2: invoke FTP from server directly |
| • | ATEGFK: retrieve file from ATE client via keyboard channel |
| • | Source, samples and related functions, including the source for ATEAPX, can be found in SOSLIB:[907,33]. |
