===						     DISview [908]
ftp
===

_________________________________________________________________
ftp <nodename>
_________________________________________________________________
The command 'ftp' is used to initiate an FTP session with
<nodename>. When the session is established, you will enter
converse mode.

When in converse mode with an FTP server, you can use the FTP
client sub-commands described below at the ftp> prompt.

When the connection between the two machines is opened, you'll
get a banner from the remote machine, followed by a prompt for
your user name and then your password. If you don't have an
account on <nodename>, login with the user name "anonymous"
and give your email address (e.g. ian@dowrmain.demon.co.uk) as 
the password.

NB In the special case of the Demon FTP server (ftp.demon.co.uk),
you can use the login name "ftp" if you can't spell "anonymous"!

>> Example:  ftp ftp.demon.co.uk


The ftp client's 'cd, 'get' and 'mget' commands described below
are logged in the YAN logfile. All three record the Internet 
address and name of the remote host. 'cd' records the directory 
name changed to. 'get' and 'mget' record the local and remote 
filenames.

_________________________________________________________________
ftp <@scriptname>
_________________________________________________________________
The command 'ftp' is used to initiate a NULL FTP session and then
automatically run the script <scriptname>. All subcommands can be
run from the script (see the source command).

The standard script comment character (#) in the first character
position is honoured.
Note that each line is checked for a LF termination character and
a warning issued if it's missing. You should *never* see this,
except, perhaps, on the last line.

>> Example:  ftp @index.scr

===============
FTP SUBCOMMANDS
===============
During converse mode with an FTP server, everything typed on the
console is first examined to see if it is a locally-known
command.  If not, the line is passed intact to the remote server
on the control channel.

However, if it is one of the following commands, it is executed
locally.

-----------------------------------------------------------------
ftp> ascii
-----------------------------------------------------------------
Set the file transfer mode to ASCII.  This is the same as the
'type a' command.



-----------------------------------------------------------------
ftp> batch [on|off]                                  Default: off
-----------------------------------------------------------------
Display or set the command batch flag.

>> Example:  batch on



-----------------------------------------------------------------
ftp> binary
-----------------------------------------------------------------
Set the file transfer mode to binary, or "image" mode.  This is
the same as the 'type i' command.



-----------------------------------------------------------------
ftp> cd <remote_directory>
-----------------------------------------------------------------
Change the directory on the remote host to <remote_directory>.
The directory specified can be relative to the current directory,
or absolute, with the name beginning at the root (/).

>> Example:  cd /pub/ibmpc/DIS



-----------------------------------------------------------------
ftp> close
-----------------------------------------------------------------
Close the current connection. 

(You can then open a new connection with another host if 
required, using the 'open' command described below, without 
quitting the current FTP session).


-----------------------------------------------------------------
ftp> delete <remote_filename>
-----------------------------------------------------------------
Asks the remote server to delete file <remote_filename>.

N.B. <remote_filename> may contain a mixture of upper-case
and lower-case characters. The name you type here must match
exactly.

>> Example: delete readme.dat

-----------------------------------------------------------------
ftp> dir [<remote_filename>|<remote_dir> [<local_filename>]]
ftp> list [<remote_filename>|<remote_dir> [<local_filename>]]
-----------------------------------------------------------------
Without arguments, 'dir' and 'list' request that a full directory
listing of the remote server's current directory be sent to the 
console. The listing gives the file names, sizes and creation 
dates.

If one argument is given, the remote filename or directory are
listed at the console.

If two arguments are given, the second argument is taken as the
local file into which the directory listing should be put
(instead of being sent to the console).  

>> Example:  dir public


-----------------------------------------------------------------
ftp> get <remote_filename> [<local_filename>]
-----------------------------------------------------------------
Asks the remote server to send <remote_filename>.

The second argument, if given, will be the name by which the
transferred file is to be known on the local machine; otherwise 
it will have the same name as on the remote machine. 

N.B. <remote_filename> may contain a mixture of upper-case
and lower-case characters. The name you type here must match
exactly.

Before using 'get' you must set the correct transfer mode, using
either the 'ascii' or 'binary' command.

Caution: make sure you have enough room on your disk before
starting the transfer. YAN does not check this.

If you want to terminate the transfer before it has been 
completed, escape to the KA9Q Session Manager (F10 by default)
and then give 'abort' command at the "net>" prompt.

>> Examples:  get ls-lR.gz
              get StRaNgE.file.name.2  strange.2


[Test files for checking file transfer rates are available on
ftp.demon.co.uk in /pub/test].


-----------------------------------------------------------------
ftp> hash
-----------------------------------------------------------------
A synonym for the 'verbose 3' command.



-----------------------------------------------------------------
ftp> ls   [<remote_filename> | <remote_dir> [<local_ filename>]]
ftp> nlst [<remote_filename> | <remote_dir> [<local_ filename>]]
-----------------------------------------------------------------
The 'ls' and 'nlst' commands produce a short listing (i.e. 
filenames only).

>> Example:  ls pub


-----------------------------------------------------------------
ftp> mget <remote_filename> [<remote_filename> ...]
-----------------------------------------------------------------
Fetch a collection of files from the server.  File names may
include wild card characters; they will be interpreted and
expanded into a list of files by the remote system using the NLST
command.  The files will have the same name on the local system
that they had on the server -- this means that you can only use
'mget' where the remote filenames conform to the standard 8.3
filename convention.

Before using 'mget' you must set the correct transfer mode, using
the 'ascii' or 'binary' command.

Caution: make sure you have enough room on your disk before
starting the transfer. YAN does not check this.

If you want to terminate the transfer before it has been 
completed, escape to the KA9Q Session Manager (F10 by default)
and then give 'abort' command at the "net>" prompt.

>> Example:  mget *.txt


-----------------------------------------------------------------
ftp> mkdir <remote_directory>
-----------------------------------------------------------------
Create a directory on the remote machine.  You must have write
privilege on the remote machine to use this command.

>> Example:  mkdir tmp



-----------------------------------------------------------------
ftp> mput <local_filename> [<local_filename> ...]
-----------------------------------------------------------------
Send a collection of files from your machiner to the remote 
server.  File names may include wild card characters; they will 
be expanded locally into a list of files to be sent.  The files 
will have the same name on the server as on the local system.

Before using 'mput' you must set the correct transfer mode, using
the 'ascii' or 'binary' command.

You must have write privilege on the remote host to use this
command.

If you want to terminate the transfer before it has been 
completed, escape to the KA9Q Session Manager (F10 by default)
and then give 'abort' command at the "net>" prompt.

>> Example:  mput *.txt


-----------------------------------------------------------------
ftp> mv <remote_old_filename> <remote_new_filename>]
-----------------------------------------------------------------
Asks the remote server to rename <remote_old_filename> to
<remote_new_filename>.

N.B. <remote_old_filename> may contain a mixture of upper-case
and lower-case characters. The name you type here must match
exactly.

>> Example: mv index.txt index.lst

-----------------------------------------------------------------
ftp> open <nodename>
-----------------------------------------------------------------
Open a new connection with <nodename>.

>> Example:  open dowrmain.demon.co.uk



-----------------------------------------------------------------
ftp> pager [on|off]
-----------------------------------------------------------------
Display or set screen display flow control.  When set to 'on', a
-More- prompt is displayed after each screenful of output. Hit
the spacebar to get the next screenful.

>> Example:  pager on



-----------------------------------------------------------------
ftp> put <local_filename> [<remote_filename>]
-----------------------------------------------------------------
Send a local file to the server.  The second argument, if given,
will be the name by which the file will be known on the remote 
machine; otherwise it will have the same name as on the local 
machine. 

Before using 'put' you must set the correct transfer mode, using
the 'ascii' or 'binary' command.

You must have write privilege on the remote host to use this
command.

If you want to terminate the transfer before it has been 
completed, escape to the KA9Q Session Manager (F10 by default)
and then give 'abort' command at the "net>" prompt.

>> Example:  put myfile.dat
             put myfoo.txt yourfoo.txt



-----------------------------------------------------------------
ftp> quit
-----------------------------------------------------------------
Terminate the FTP session and returns you to the "net>" prompt.


-----------------------------------------------------------------
ftp> rename <remote_old_filename> <remote_new_filename>]
-----------------------------------------------------------------
Asks the remote server to rename <remote_old_filename> to
<remote_new_filename>.

N.B. <remote_old_filename> may contain a mixture of upper-case
and lower-case characters. The name you type here must match
exactly.

>> Example: mv index.txt index.lst

-----------------------------------------------------------------
ftp> rget <remote_filename> [<local_filename>]
-----------------------------------------------------------------
Asks the remote server to restart an interrupted send of the
<remote_filename> file. The filespecs must be the same as for the
original request and, obviously, the partial file must still be
on the disk. This file is examined to determine the restart point
and the server is asked for the missing portion.

The second argument, if given, will be the name by which the
transferred file is to be known on the local machine; otherwise 
it will have the same name as on the remote machine. 

N.B. <remote_filename> may contain a mixture of upper-case
and lower-case characters. The name you type here must match
exactly.

Before using 'rget' you must set the correct transfer mode, using
either the 'ascii' or 'binary' command, which must the be the
same as for the original request.

Caution: make sure you have enough room on your disk before
         starting the transfer. YAN does not check this.
Note: Not all servers allow resuming interrupted transfers and
      even those which do may not like the method used here to
      do it. Unix servers, on the whole, are fine.

If you want to terminate the transfer before it has been 
completed, escape to the KA9Q Session Manager (F10 by default)
and then give 'abort' command at the "net>" prompt.

Depending on how the transfer was terminated, FTP or even YAN,
may have exited. This doesn't matter because provided the partial
file remains on the disk it can be resumed at any time.
If a transfer does terminate and FTP doesn't, it can be is such
a state that the attempt to resume is ignored. The workaround
is to quit FTP, restart FTP and retry 'rget'.

>> Examples:  rget ls-lR.gz
	      rget StRaNgE.file.name.2	strange.2


-----------------------------------------------------------------
ftp> rm <remote_filename>
-----------------------------------------------------------------
Asks the remote server to delete file <remote_filename>.

N.B. <remote_filename> may contain a mixture of upper-case
and lower-case characters. The name you type here must match
exactly.

>> Example: rm readme.dat


-----------------------------------------------------------------
ftp> rmdir <remote_directory>
-----------------------------------------------------------------
Delete a directory on the remote machine.  You must have delete
privilege on the remote host to use this command.

>>  Example:  rmdir tmp


-----------------------------------------------------------------
ftp> source <local_ftp_script_filename>
-----------------------------------------------------------------
Run a script containing a sequence of ftp> commands. Comment
lines in scripts start with #.

>> Example:  source getdir.scr


>> Example of an FTP script:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# getdir.scr
# Gets long directory listing
open ftp.demon.co.uk
anonymous                             {login name}
ian@dowrmain.demon.co.uk              {password}
cd /pub
hash
binary
get ls-lR.gz
close
quit

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are scripting and a connection fails, _all_ commands meant
for that host are still executed (they really whiz past the
screen) up to the next correct connection or EOF <sourcefile>.
This is not a bug. This method allows a script to continue to
completion even if one or more hosts are unavailable.

If using a script to login to a remote host (as in the above
example), you must put the username and password in plain text in
the script file. If the account is not an anonymous account this
may be a security issue.



-----------------------------------------------------------------
ftp> type [a | i | l <bytesize>]                       Default: a
-----------------------------------------------------------------
Tells both the local client and remote server the type of file
that is to be transferred.  The 'type' command sets the local
transfer mode and generates the TYPE command on the control
channel.

Type 'a' means ASCII (i.e. a text file).  In ASCII mode, files
are sent as varying length lines of text in ASCII separated by
CR/LF sequences.  The 'type a' command is the same as 'ascii'.

Type 'i' means image (i.e. binary).  In image mode, files are
sent exactly as they appear in the file system.  The 'type i'
command is the same as 'binary'.

Type 'l' (logical byte size) is used when exchanging binary files
with remote servers having oddball word sizes (eg. DECSYSTEM-10s
and 20s).  Locally it works exactly like image, except that it
notifies the remote system how large the byte size is.  The
parameter <bytesize> is typically 8.

ASCII mode should be used whenever transferring text between
dissimilar systems (eg. UNIX and DOS) because of their different
end-of-line and/or end-of-file conventions.  When exchanging text
files between machines of the same type, either mode will work
but image mode is usually faster.

Naturally, when exchanging raw binary files (executables,
compressed archives, etc) image mode must be used.

See also the 'ftpopt' command.

>> Example:  type a



-----------------------------------------------------------------
ftp> verbose [0 | 1 | 2 | 3| 4]                        Default: 2
-----------------------------------------------------------------
Set or display the level of message output in file transfers.
Verbose 0 gives the least output, and verbose 3 the most, as
follows:

0:  Display error messages only.

1:  Display error messages plus a one-line summary after each
    transfer giving the name of the file, its size, and the
    transfer time and rate.

2:  Display error and summary messages plus the progress messages
    generated by the remote FTP server.

3:  Display all messages. In addition, a "hash mark" (+) is
    displayed for every 1,024 bytes sent or received with a !
    every tenth one. 'verbose 3' is equivalent to 'hash'.

4:  Display all messages. In addition, a bytecount display tracks
    transfer progress as an alternative indication to the verbose
    3 hash mark. This bytecount display is only produced when the
    session is currently visible.

If a command is sent to the remote server because it is not
recognized locally, the response is always displayed, regardless
of the setting of 'verbose'.  This is necessary for commands like
'pwd' (display working directory), which would otherwise produce
no message at all if 'verbose' were set to 0 or 1.

>> Example:  verbose 0


-----------------------------------------------------------------
ftp> view <remote_file>
-----------------------------------------------------------------
Get a remote (text) file and display it on the console, without
saving it locally. This is useful for quick inspection of text
files which describe the contents of compressed archives, for
example.

>> Example:  view disview.txt


-----------------------------------------------------------------
ftp> xview <option>
-----------------------------------------------------------------
Fetch a directory list from the server and display it with a
lightbar selector. The lines under the lightbar can be actioned
with what that action is depending upon what the line holds.
The litebar itself can be moved with up/down arrows.
The + key is a toggle between the long and short display formats.
The long format displays all of the information provided by the
server while the short format shows names only.

The option controls the format of the direrctory listing. The
default is normally alphabetical order with the display format
depending on the setting of ftpopt xshort. Option overrides the
ftopt setting and can change the data requested from the server.

There are four options:
0:  Long format, alphabetical order
1:  Long format, time order
2:  Short format, alphabetical order
3:  Short format, time order

Currently, only two actions - files fetched and directories
changed (using either directory names or links) are implemented.
Before a file is fetched a check is made to see if it is already
on the local disk and, if so, queries about whether to resume, to
which there are three possible replies:
        1. y = resume downloading the existing file
        2. n = overwrite existing file with new download
        3. filename = start a completely new download, saving
                      under the new name, which *isn't* checked.
	4. Enter without any input aborts
If the file isn't already on the disk, a check is made to see if
the (truncated) filename is valid and if not, a new one is
requested. This is also checked to see if it's on the disk as in
the earlier case and is followed by the same dialogue.

Note 1: because of the interaction between the way the viewer
        code works and the demands of the lightbar, page up/down
        is somewhat idiosyncratic. I call it a feature :)
Note 2: Files are fetched in whatever is the current mode. In
        general, it's a good bet to make BINARY the default (see
        ftpopt).
Note 3: Files are saved under the displayed name, truncated if
        needed. This will be a problem with a series of files
        which all truncate to the same DOS name, but you will get
        the chance to enter new names.
Note 4: Some sites may not handle the way it gets its directory
        lists. If so, Xview is screwed and you'll get a blank
        screen.

Control:
        Key                     Letter  Action
        Home                    h       Go to start of list.
        End                     e       Go to end of list.
        Pgdn                    D       Move down one page.
        Pgup                    U       Move up one page.
        down arrow              d       Move down one line.
        up arrow                u       Move up one line.
        left arrow                      change to previous dir
	+				Toggles between the long
                                        and short display format
        Ctrl + up arrow                 Move litebar/cursor up
        Ctrl + down arrow               Move litebar/cursor down
        Enter                           Action line under litebar
        Del, Ins                q,Q,R   Quit.
        ESC                             Quit if *not* defined as
                                        escape to command session
                                        key.

>> Examples:  xview
	      x 1



=====================
FILE UPLOADS TO DEMON
=====================
When uploading files to Demon for general distribution, connect
to ftp.demon.co.uk and change to the /incoming directory. Upload
the files into this directory, using 'put'. Remember to set the
mode to binary if uploading binary files (e.g. ZIP files).

N.B. The /incoming directory is write-only -- you cannot read the
     directory to verify successful upload. This is a security
     precaution.

Also send an email message to "uploads@demon.net", to alert 
Demon to the existence of the uploaded files, and to suggest
where the files should be moved to.
