Reviewed and revised December 2023
tab(-10, AG_FTP); dirflag; hostpath; "~"; localpath; {"~"; 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:
Value
|
Direction
|
Type
|
Feedback
|
0
|
Host to PC
|
Binary
|
message/dialog
|
1
|
PC to host
|
2
|
Host to PC
|
ASCII
|
3
|
PC to host
|
A
|
Host to PC
|
Binary
|
silent
|
B
|
PC to host
|
C
|
Host to PC
|
ASCII
|
D
|
PC to host
|
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 message/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.
Response
A single byte will be placed in the keyboard buffer to indicate success (ASCII 13, aka RETURN) or failure (ASCII 3, aka Control-C).
u 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
|
u 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, 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.
|
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. 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 ATEAPX and ATEGFK.
u 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
u History
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:
• | 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 FTP2 or the ZTERM file transfer ESCAPE sequence. |
|