                             gapFTP
                    (c)1998,99 Gary A. Priest
                    -------------------------

gapFTP is a freeware command line FTP client for the Atari ST/STE/TT/Falcon
and compatibles, using the TCP/IP stacks STinG or STiK.

It is TOS based instead of the usual GEM based clients, and is similar to
FTP clients in NOS, Unix and Windows95. Being TOS based it may seem
complicated and daunting but by it's very nature it is *extremely* powerful
and fast.

It can be used as a plug in for CAB via CAB's Internet Clients option.

It also features very powerful scripting capabilities, that allow 
totally automated uploading/downloading of files to/from FTP sites.

It fully supports the use of long file names.

It was written in assembler and is based on the FTP protocol defined
in RFC959.


USING GAPFTP.TTP
----------------
The program can either be started with a command line (which is assumed to
be the name of an FTP server to connect to) or with no command line, in
which case the OPEN command must be used to make a connection.


GETTING HELP
------------
At the ftp> prompt simply type HELP or ? to display the current 
version number, credits, and list of currently supported commands.
Typing HELP or ? followed by a command will display associated help 
text for that command ie. 'help view' will display help text for 
command 'view'.


STARTUP PARAMETERS
------------------
The following parameters can be specified in the command line when 
starting the program. They must precede any host and port information.
ie.
 gapftp.ttp -p -i ftp.demon.co.uk


-d	Turns on debugging. All commands and responses will be logged 
	in a file called gapftp.log.

-i	Turns off interactive prompting during multiple file transfers.

-p	Turns off use of PASV command and uses PORT instead.
	
-s:	Executes the specified script file. eg. -s:script


SUPPORTED COMMANDS
------------------
Commands are not case sensitive, thus HelP, help, HELP are all 
exactly the same.
See GAPFTP.HLP for a detailed description of each command.


SCRIPTING
---------
Scripts are simply files that contain a sequential list of commands 
that will be read and processed by gapftp. This provides *very* 
powerful automation of mundane tasks such as updating a web site or 
ftp site, or downloading a large number of files from various sites.

A script can be executed in two different ways.

Running a script from the command line via -s:
----------------------------------------------
The startup paramter -s: can be used to execute a script from the 
command line eg. gapftp.ttp -s:[script] {host} {port}

The host is optional and if omitted, the OPEN command must be specified
in the script, immediately followed by two lines containing user and 
password, to connect to a host.
If specified, then connection is made to the host, and then the script
is executed. In this case it is *mandatory* that the first two lines in
the script are the user and password for logon to the host.

Running a script from the ftp> prompt
-------------------------------------
The SOURCE command can be used to run a script from within gapftp.
After the script has been processed, the ftp> prompt will be 
redisplayed ready for a new command.

Contents of scripts
-------------------
Scripts can contain any valid ftp command supported by gapftp, and can 
also contain comment lines beginning with the # symbol.
See the example scripts supplied in the scripts\ folder.

Launching scripts from the desktop
----------------------------------
By use of the tiny program EXECFTP.TOS, scripts can be launched 
directly from the desktop. The desktop must allow the association of a 
file type with a program in order for this to work. All modern 
desktops should be fine.

EXECFTP.TOS *must* be in the same folder as GAPFTP.TTP.

EXECFTP.TOS works by accepting a filename as a parameter, and then 
passing it to GAPFTP.TTP prefixed with a '-s:'.

I suggest the use of .FTP for FTP scripts, and installing EXECFTP.TOS 
as an application to be launched when any *.FTP file is clicked on.

All my scripts end in .FTP, thus if I double click on any of them, they
are automatically run by GAPFTP. These scripts must obviously contain an
OPEN command to make the connection. See example RFC.FTP in scripts\


USING AS A CAB CLIENT
---------------------
GAPFTP.TTP accepts ftp:// urls passed via the command line.

This allows it be used as a 'Internet Client' for CAB so that any 
ftp:// url clicked on in CAB is passed to GAPFTP.TTP for downloading.

The url *must* contain a filename and must not simply be a directory.
They can contain user and password information, although if not 
present then an anonymous logon will be performed.

No screen output is visible, but GAPFTP.LOG will be written to.
The system bell is chimed upon successful downloading of the file.

To enable anonymous logon to be performed, an EMAIL variable must be 
defined in STinG or STiK's DEFAULT.CFG to contain your email address.
A lot of other clients use this information so it will probably 
already be defined.

The retrieved file is stored in whatever path is pointed to by the 
GEMDOS (not STiK) TEMP or TMP variables. If they don't exist, then it
is stored in the current gemdos directory.


SHOULD I USE PORT OR PASV MODES?
--------------------------------
Without going into too much detail, FTP transfers files by opening a 
connection to a data port. This can be achieved by passing the FTP 
server either a PASV command or a PORT command. 

By default GAPFTP uses the PASV method, which almost all servers 
support (RFC959 demands that they do, so any server that doesn't is 
breaking the rules!).

One exception appears to be VAX machines. They don't cope with the 
PASV command at all well. So for these machines, the PORT method must 
be used instead. This can be achieved either by the -p startup 
parameter, or by the use of the PORT command. 

As a general rule, stick witht the default PASV method, unless you are 
experiencing problems, and then try the PORT method.


FREEWARE
--------
gapFTP is FREEWARE! I make no charge for using it.

If you use and like it, then please drop me an email and tell me 
so. Without encouragement it may not develop. So, even if it's 
just a one liner, please make the effort.


DISCLAIMER
----------
gapFTP is used at your own risk. I will not be held responsible for any
damage caused either directly or indirectly from it's use, or the loss of
any electronic data.


KNOWN PROBLEMS/LIMITATIONS
--------------------------
.I have done limited testing with STiK, and offer no guarantees that it
 will work. It definately works with STinG.
 
.Seems to randomly crash when running under VT52 in MagiC. I believe 
 this a bug in VT52 and not my program, thus am unable to do anything 
 about it.
 

NEW VERSIONS
------------
The latest version of gapFTP can be found on my website:

http://www.the-gap.demon.co.uk/

Gary Priest 02/01/99
gary@the-gap.demon.co.uk
