A-Shell 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 invokes FTP2xs using either FTP or SFTP protocol, depending on the options on the File Transfer tab of the ATE Connection Properties dialog. Typically this will be set to use the same protocol and credentials as the ATE terminal connection.

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.

If you are running locally under A-Shell/Windows and want to transfer files to an arbitrary FTP server, then use FTP2xs, 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.

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:

To transfer files to or from a machine other than the A-Shell server or the ATE client, you should use FTP2xs directly, as it allows specification of an arbitrary remote server address and credentials.

To transfer files between two arbitrary machines both running A-Shell, but without relying on any external file transfer services, you can implement your own file transfer protocol using TCPXxs. The sample program TCPXFR in EXLIB:[908,25] provides a working example of such a protocol, complete with interactive and command line server and client interfaces.

It is also possible to transfer files in both directions between the A-Shell server and the ATE client over the terminal connection using the xcalls ATEAPXxs and ATEGFKxs.

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 FTPDLXxs or FTP2xs to implement the client side, there are different debugging options. In the case of FTPDLXxs, 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.

2025 December, A-Shell 7.0.1781:  Simulate support for the FTP ASCII conversion option (LF-CRLF) when the transfer protocol is actually SFTP.

2024 January, A-Shell 7.0.1754:  AG_FTP now invokes FTP2 in all cases, regardless of the options. FTPDLX no longer supported.

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.