A-Shell Consolidated Reference

! transfer dsk0:test.dat[100,1] on server to dsk0:test.sav[100,999] on PC

? TAB(-10,AG_FTP);"0/vm/miame/dsk0/100001/test.dat";chr(126); &

"%MIAME%\dsk0\100999\test.sav";chr(127);

xcall ACCEPN,A

! transfer c:\xfer\test.new from PC to /import/test.dat on server using FTP2 client if avail.

? TAB(-10,AG_FTP);"1/import/test.dat";chr(126);"c:\xfer\test.new";chr(126);"4096";chr(127);

xcall ACCEPN,A

! equivalent to above but using MX_AGWRAPPER

xcall MIAMEX, MX_AGWRAPPER, AG_FTP, "1/import/test.dat~c:\xfer\test.new~4096",response$

if asc(response$) = 3 then <error>  ! (^C response)

! transfer dsk0:*.*[1,2] on server to TEMP directory on PC

? TAB(-10,AG_FTP);"0/vm/miame/dsk0/001002/*";chr(126);"%TEMP%;chr(127);

xcall ACCEPN,A

? transfer all files from PC "ATELOCALDIR" directory to /vm/miame/dsk0/033033

? TAB(-10,AG_FTP);"1/vm/miame/dsk0/033033";chr(126); &

"%ATELOCALDIR%\*";chr(127);

xcall ACCEPN,A

AG_FTP effectively invokes FTPDLX or, if options value 4096 specified, FTP2. The two routines have slightly differing sets of capabilities; consult the subroutine documentation for each for further details.

The file wildcard "*" may be used to transfer all the files in a particular directory; see the last two examples above.

This command only works when the client is ATE. If you have a mixture of ZTERM and ATE clients, you would be better off using the ZTERM Escape Sequences, which work for both ZTERM and ATE. In either case, you are limited to transferring files between the server where the application is running, and the client workstation, using the FTP login credentials stored in the ZTERM or ATE configuration.

In the case of ATE, the actual protocol used for the file transfer will be either FTP or SFTP, according to the options on the File Transfer tab of the ATE Connection Properties dialog. The typical and recommended protocol is SFTP using the same login credentials as for the SSH login.

If you are running locally under A-Shell/Windows and want to transfer files to an arbitrary FTP server, then use FTPDLX.SBX or FTP2xs, both of which allow you to specify the server IP address and login parameters. For debugging ideas, see FTP Debugging.

Note that while your application (running on the server) requests the operation by sending the AG_FTP command, in the context of the FTP / SFTP protocols, it is actually the ATE workstation that acts as the file transfer client, and the A-Shell application server acts as the file transfer server. (We might call this server/client/server protocol.) Even though the file transfer service is running on the same server as the A-Shell session, it runs in a different process and may have a completely different security environment from A-Shell. It may even be "homed" or "sandboxed" to a directory other than the true root of the file system (this is particularly common for FTP servers) and thus it may not be possible to access files that are otherwise visible to A-Shell running on the same server.

Within an SSH connection (i.e. using SFTP file transfer), AG_FTP automatically adds the file.ext from the localpath to the hostpath when transferring to the host and the hostpath does not include a filename and extension. While it is often the case with file transfers, as with file copy operations, that a destination consisting of just a directory will be automatically updated to use the source filename, that is not the case with SFTP, often leading to confusion as to why file transfers fail. This refinement hopefully smooths things over.

Since both FTP and SFTP are standard protocols, one way to rule out whether the problem is in the client or the server would be to use another client (e.g. FileZilla) to try to connect to your server. If it can't connect, ATE won't be able to either.

Depending on whether ATE is using FTPDLX or FTP2 to implement the client side, there are different debugging options. In the case of FTPDLX, there will always be a ftpdlx.log file in the [1,4] directory on the ATE workstation with details for the last transfer attempt. In addition, if you set the environment variable ASHFTPDEBUG=1 (on the ATE side, e.g. through the Windows applet or using AG_SETENV), then a detailed log file will be in %temp%\ftpdebug.log.

See FTP Debugging for more details. In the case of FTP2, file transfer errors will cause a dialog box with extensive details to automatically appear.

2023 November, A-Shell 1751:  Within an SSH connection (i.e. using SFTP file transfer), AG_FTP now automatically adds the file.ext from the localpath to the hostpath when transferring to the host and the hostpath does not include a filename and extension.

2014 December, A-Shell 1399:  MX_AGWRAPPER enhanced to properly handle the ^C failure response from AG_FTP. Previously it may have aborted the program; now it just shows up as a data character in the response buffer.

2013 December, A-Shell 1369, ASHNET 138:  Implement the FTP2 alternative client for file transfers; add the options parameter to AG_FTP

2009 December, A-Shell 1131:  You can now request that the PC file name be set to match that assigned to the last file printed via the AUXLOC: channel, by specifying a PC filespec ending in "-#." + the extension. For example,

TAB(-10,AG_FTP);"0/tmp/abcdef.dat~%abcdef-#.dat";chr(127);

This will send the file /tmp/abcdef.dat to the PC, where it will given the full spec ??????.dat, where ????? is the complete path of the last printfile captured by ATE (minus the extension). Note that the only part of the PC filespec which matters in this case was "-#.dat"; including the "abcdef-#.dat" only serves as a fallback if the version of ATE doesn't support the feature, or there was no prior printed filespec to refer to.

This trick can be useful for sending metadata files which should be associated with print files, perhaps containing routing or archiving instructions.

2007 April, A-Shell 986:  FTP transfers now support more flexible wildcards. Previously, the only wildcard option was "*" to transfer all files in the source directory. Now you can separately wildcard the file name and extension, and you can include partial literals in both parts of the name. Examples:

/vm/miame/dsk0/007006/*.dat

/vm/miame/dsk0/007006/ab*

c:\vm\miame\dsk0\007006\xyz*.d*

Notes: