Revised February 2018

? tab(-10, AG_FTP); dirflag; hostpath; chr(126); localpath; {chr(126); options;} chr(127);

AG_FTP (22) may be used on server installation of A-Shell to cause the ATE client to initiate a file transfer with the server.

Parameters

dirflag

A single character indicating the file transfer type and direction, from the following choices:

Codes A though D are not ZTERM-compatible, so should only be used when you know the client is ATE. Note that with ATE, the msg/dialog is hardly noticeable (unlike with ZTERM, where it looks just like the standard interactive FTP dialog), so the silent feature isn't that much of an improvement. Still, some people prefer to have their file transfers be invisible to the user.

hostpath

Native specification for the file on the server. If sending to the server, this may specify just the directory, in which case the filename will be taken from the localpath.

localpath

Native (PC) specification of the source file. When transferring to the PC, this may be just a directory, in which case the filename is taken from hostpath.

options

Optional flags affecting the transfer protocol, expressed as a decimal value representing the sum of options taken from the table of FTPDLX opcodes. The most likely flag to be used here is XFTPF_VERSION2 (4096), to request use of the newer FTP2 implementation of the client side of the transfer.

Return value

A single byte will be placed in the keyboard buffer to indicate success (ASCII 13, aka RETURN) or failure (ASCII 3, aka Control-C).

Examples

! 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

Comments

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 FTP2.SBR, 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.

Alternatives

To transfer files to or from a machine other than the A-Shell server or the ATE client, you should use FTPDLX or FTP2 directly, as they allow 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 TCPX.SBR. 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 ATEAPX and ATEGFK.

Debugging:

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.

See Also

•   FTPDLX

•   FTP2

•   ATEAPX

•   ATEGFK

•   ZTXFER.LIT

History

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:

•   The only wildcard character remains "*" (? is not supported)

•   PC filespecs are not case sensitive, but HOST filespecs are.

•   The actual code change is in the module ftpdlxcall.dll 1.2.0.117, which is normally found in the same directory as ashw32.exe. It gets loaded on demand when transferring a file via AG_FTP or FTPDLX.SBR or the ZTERM file transfer ESCAPE sequence.