Alto Pup File Transfer Program




FTP is a Pup-based File  Transfer Program for moving files to  and from
an Alto file system.  The program comes in 3 parts:

    1) An FTP Server, which listens for file transfer requests from
    other hosts,

    2) An FTP User, which initiates file transfers under control of
    either the keyboard or the command line, and

    3) A User Telnet for  logging into a remote host using  the Pup
    Telnet protocol.



1. Concepts and Terminology


Tranferring  a file  from one  machine (or  "host") to  another  over a
network requires the active  cooperation of programs on  both machines.
In a  typical scenario for  file transfer, a  human user (or  a program
acting  on his  behalf)  invokes a  program  called an  "FTP  User" and
directs it to establish contact with an "FTP Server" program on another
machine.  Once  contact has  been established,  the FTP  User initiates
requests  and supplies  parameters for  the actual  transfer  of files,
which the User and Server proceed to carry out cooperatively.   The FTP
User and FTP  Server roles differ in  that the FTP User  interacts with
the human user (usually through some sort of keyboard  interpreter) and
takes  the  initiative  in user/server  interactions,  whereas  the FTP
Server plays a comparatively passive role.

The question  of which machine  is the  FTP User and  which is  the FTP
Server is  completely independent  of the  direction of  file transfer.
The  two  basic  file transfer  operations  are  called  "Retrieve" and
"Store"; the Retrieve  operation causes a file  to move from  Server to
User, whereas Store causes a file to move from User to Server.

The Alto  FTP subsystem contains  both an FTP  User and an  FTP Server,
running as independent processes.  Therefore, to transfer files between
a  pair  of  Altos, one  should  start  up the  FTP  subsystem  on both
machines, then issue  commands to the FTP  User process on  one machine
directing it to  establish contact with the  FTP Server process  in the
other machine.  Subsequent file transfers are controlled  entirely from
the FTP  User end, with  no human intervention  required at  the Server
machine.

Transferring  files  to  or  from a  Maxc  system  or  an  IFS involves
establishing contact with FTP Server processes that run all the time on
those machines.  Hence,  one may simply  invoke the Alto  FTP subsystem
and direct its FTP User process to connect to the machine.

In the  descriptions that  follow, the terms  "local" and  "remote" are


                             ------------
                   Copyright Xerox Corporation 1982


Alto Pup FTP               December 12, 1981                          2




relative to the machine on which the FTP User program is  active.  That
is, we  speak of typing  commands to our  "local" FTP User  program and
directing it to establish contact  with an FTP Server on  some "remote"
machine.  A Retrieve command then copies a file from the  "remote" file
system to  the "local" file  system, whereas a  Store command  copies a
file from the "local" file system to the "remote" file system.

Furthermore, we  refer to "local"  and "remote" filenames.   These must
conform  to  the conventions  used  by the  "local"  and  "remote" host
computers, which  may be  dissimilar (for  example, Alto  versus Maxc).
The  Alto FTP  knows nothing  about Maxc  filename conventions  or vice
versa.

The Alto FTP  subsystem also includes a  third process, called  a "User
Telnet", which simulates  a terminal in  a manner exactly  analogous to
the Chat  subsystem (though  lacking some of  its finer  features).  By
this  means,  you  may  log  in to  a  file  sytem  machine  to perform
operations  not  directly   available  via  the  basic   file  transfer
mechanisms.  If you log into Maxc, it is even possible to run "PupFTP",
the Maxc FTP User program, and direct it to establish contact  with the
FTP Server in your own  Alto.  You should probably not try  this unless
you  really understand  what you  are doing,  however, since  the terms
"local" and  "remote" are  relative to  Maxc rather  than to  your Alto
(since the FTP User program is running on Maxc in this case), which can
be confusing.



2. Calling the FTP Subsystem


A  number  of options  are  available when  running  FTP.   The program
decides which parts  of itself to enable  and where user  commands will
come from  by inspecting  the command  line.  The  general form  of the
command line to invoke FTP looks like:

        FTP[/<Global-switches>] [<Host-name> [<Command-list>] ]


The  square  brackets denote  portions  of the  command  line  that are
optional and may be omitted.

Global switches,  explained below, select  some global  program options
such as using the Trident disk instead of the Diablo.  The  first token
after the <global-switches>, if present, is assumed to be a <host-name>
(a discussion of which appears  later in the description of  the "Open"
command).  The User  FTP will attempt to  connect to the FTP  Server on
that  host.  After  connecting to  the server,  if a  <command-list> is
present, an interpreter  is started which  feeds these commands  to the
User FTP.  When the command list is exhausted, FTP returns to  the Alto
Executive.   If no  command list  is present,  an  interactive keyboard
command interpreter is started.

Each global switch has a default  value which is used if the  switch is
not  explicitly set.   To set  a switch  to 'false'  proceed it  with a
'minus' sign (thus FTP/-S means 'no Server'), to set a switch to 'true'
just mention the switch.

Switch   Default   Function


Alto Pup FTP               December 12, 1981                          3




/S       true      [Server] starts the  FTP Server.  The Server  is not
                   started  if  the  User  is  enabled  and   is  being
                   controlled from the command line.

/U       true      [User] starts the FTP User.  As explained above, the
                   interactive command interpreter or the  command line
                   interpreter  will   be  started  depending   on  the
                   contents of the command line.

/C       true      [Chat] starts the Telnet.  The Telnet is not started
                   if the User is enabled and is being  controlled from
                   the  command  line,  or  if  the  system  disk  is a
                   Trident.

/T       false     [Trident]  sets  the  system disk  to  be  a Trident
                   drive.   The default  is 0,  but can  be  changed by
                   following  the  /T  with a  unit  number.   The unit
                   number  is  octal;  the  high  byte  is  the logical
                   filesystem number and  the low byte is  the physical
                   drive  number.  User  and Server  commands  apply to
                   files on  this disk but  command line input  and log
                   output use the Diablo drive.

/L       *         [Log] causes  all output to  the User FTP  window to
                   also go  to the file  "FTP.log" on  DP0, overwriting
                   the previous contents.  Log  is true if the  User is
                   enabled  and is  being controlled  from  the command
                   line.

/A       false     [AppendLog] enables the  log but appends  to FTP.log
                   rather than overwriting it.

/E       true      [Error]  causes  FTP  to  ask  you  if  you  want to
                   continue  when  a  non-fatal  error  happens  during
                   execution of a command line.  FTP/-E will  cause FTP
                   to  recover  automatically  from  non  fatal  errors
                   without consulting you.

/R       true      [Ram] allows FTP to use some microcode  which speeds
                   things up slightly.  If  your Alto has no  ram, this
                   switch is ignored.

/D       false     [Debug] starts FTP in debug mode.

The  rest of  the  global switches  are explained  below  under 'Server
Options'.


2.1. FTP User Log

FTP can keep a log (typescript) file for the FTP User window.  The file
name is 'FTP.log'.  It is  always enabled when FTP is  being controlled
from the  command line;  otherwise it is  controlled by  the /L  and /A
global switches.


Alto Pup FTP               December 12, 1981                          4




2.2. Using a Trident Disk

Starting FTP with the /T global switch causes FTP to store and retreive
files from a Trident disk.  By default, FTP will open TP0;  other disks
may be opened by appending  their unit numbers to the /T  switch.  Thus
"FTP/T1" will open TP1,  and "FTP/T400" will open logical  filesystem 1
on physical unit 0.

Accessing a file on a Trident requires more code and more  free storage
than accessing a file on the Diablo.  Since FTP is very short on space,
only a User or a Server FTP is started when the /T switch is  set.  The
default is  to start a  User FTP, but  specifying no user  (FTP/T-U) or
specifying a server (FTP/TS) will start a Server FTP instead.


2.3. Server Options

Server options  are controlled  by switches on  the subsystem  name and
subcommands of the SERVER  keyboard command.  There are  currently four
options:

switch   Default   Function

none               If no server option is specified,  retrieve requests
                   (disk to net)  are allowed.  Store requests  (net to
                   disk) are allowed  unless the store  would overwrite
                   an  existing  file.   Delete  and  Rename   are  not
                   permitted.

/P       false     [Protected]  Retrieve  requests  are   allowed.   No
                   stores  are  allowed.   Delete  and  Rename  are not
                   permitted.

/O       false     [Overwrite]  Retrieve requests  are  allowed.  Store
                   requests can overwrite files.  Delete and rename are
                   permitted.

/K       false     [Kill] FTP  will return  to the  Alto Exec  when the
                   server  connection  is  closed.   A  simple  form of
                   remote job  entry can be  performed by  storing into
                   Rem.cm.



3. The FTP Display


The top inch or so of  the display contains a title line  that displays
the release date of that version of FTP, the current date and time, the
machine's internetwork  address, and  the number of  free pages  on the
disk.  A window is  created below the title  line for each part  of FTP
which is enabled during a session (server, user, and telnet).

If the FTP Server is enabled, it opens a window and  identifies itself.
If a User FTP subsequently connects to this Server, the  User's network
address will be displayed.  The Server will log the commands it carries
out on behalf  of the remote  User in this  window.  The Server  is not
enabled when FTP is being controlled from the command line.


Alto Pup FTP               December 12, 1981                          5




The FTP  User opens the  next window down  and identifies  itself.  The
command herald is an asterisk.

The User  Telnet opens  the bottommost  window, identifies  itself, and
waits for a host  name to be entered.   The Telnet is not  enabled when
FTP is being controlled from the command line.



4. Keyboard Command Syntax


FTP's interactive  command interpreter presents  a user  interface very
similar to that of the  Alto Executive.  Its command structure  is also
very similar to that of the Maxc Pup FTP program (PupFTP), and the Maxc
ArpaNet FTP  program (FTP).  The  standard editing  characters, command
recognition features, and help facility (via "?") are  available.  When
FTP is  waiting for keyboard  input, a blinking  cursor appears  at the
next character position.


4.1. Directing Keyboard input to the User and Telnet
     Windows

The bottom two unmarked keys control which window gets  characters from
the keyboard.  Hitting the  unmarked key to the right  of 'right-shift'
(also known  as the 'Swat  key') directs keyboard  input to  the Telnet
window.  Hitting  the unmarked  key to  the right  of the  'return' key
(also known as the 'Chat  key') directs keyboard input to the  FTP User
window.   The window  which currently  owns the  keyboard will  blink a
cursor at the next character position if it is waiting for type-in.


4.2. Keyboard Commands

OPEN <host name>
     Opens a connection to the  FTP Server in the specified  host.  FTP
     permits only  one user connection  at a time.   In most  cases the
     word OPEN  may be omitted:  i.e., a well  formed <host name>  is a
     legal command  and implies  a request to  OPEN a  connection.  FTP
     will try for one minute to connect to the specified host.   If you
     made  a  mistake  typing  the host  name  and  wish  to  abort the
     connection attempt, hit the  middle unmarked key (to the  right of
     <return>).

     Ordinarily, host name should be  the name of the machine  you wish
     to connect  to (e.g.,  "Maxc").  Most Altos  have names  which are
     registered  in Name  Lookup  Servers.  So  long as  a  name lookup
     server  is  available,  FTP  is  able  to  obtain  the information
     necessary  to  translate a  known  host name  to  an inter-network
     address.

     If the host name of the server machine is not known or if  no name
     lookup  servers are  available, you  may specify  an inter-network
     address in place of the host name.  The general form of  an inter-
     network address is:

                     <network> # <host> # <socket>


Alto Pup FTP               December 12, 1981                          6




     where each of the three fields is an octal number.   The <network>
     number  designates  the  network  to  which  the  Server  host  is
     connected (which may be different  from the one to which  the User
     host is connected); this (along with the "#" that follows  it) may
     be omitted if the Server and User are known to be connected to the
     same  network.  The  <host>  number designates  the  Server host's
     address  on  that  network.  The  <socket>  number  designates the
     actual  Server  process  on that  host;  ordinarily  it  should be
     omitted,  since  the default  is  the regular  FTP  server socket.
     Hence, to connect  to the FTP server  running in Alto  host number
     123 on the directly-connected Ethernet, you should say "OPEN 123#"
     (the trailing "#" is required).

CLOSE
     Closes the currently open User FTP connection.  CLOSE  cancels any
     defaults set  by CONNECT, DIRECTORY,  DEVICE, BYTE, TYPE,  or EOLC
     commands.

LOGIN <user name> <password>
     Supplies any login parameters required by the remote server before
     it will  permit file transfers.   FTP will use  the user  name and
     password in the Operating System, if they are there.  Logging into
     FTP will set  the user name  and password in  the OS (in  the same
     manner as the Alto Executive's "Login" command).

     When you  issue the  "Login" command, FTP  will first  display the
     existing user name known to the OS.  If you now type a  space, FTP
     will prompt you for a  password, whereas if you want to  provide a
     different user name, you  should first type that name  (which will
     replace the previous one) followed by a space.  The command may be
     terminated by carriage return after entering the user name to omit
     entering the password.

     The  parameters  are  not immediately  checked  for  legality, but
     rather are  sent to  the server  for checking  when the  next file
     transfer command is issued.  If a command is refused by the server
     because the name or password is incorrect, FTP will prompt  you as
     if you had  issued the LOGIN command  and then retry  the transfer
     request.  Hitting delete in this context will abort the command.

     A user name and password must be supplied when  transferring files
     to and from a Maxc system or an IFS.  The Alto FTP Server requires
     a user-password  to be  supplied if the  server machine's  disk is
     password-protected and if the password in the server  machine's OS
     does  not match  the password  on the  disk.  Thus  if the  OS was
     booted  and  FTP  invoked  because  a  Request-for-Connection  was
     received  (which  bypasses  password  checking),  FTP  will refuse
     access to files unless a password is supplied.  However if  the OS
     was booted normally, FTP assumes that the disk owner (who knew the
     password) will control access by using the server option switches.
     The user-name is ignored.

CONNECT <directory name> <password>
     Requests  the  FTP  server  to  "connect"  you  to  the  specified
     directory  on  the remote  system,  i.e., to  give  you owner-like
     access  to it.   The password  may be  omitted by  typing carriage
     return after the directory name.  As with LOGIN,  these parameters
     are  not  verified  until the  next  transfer  command  is issued.
     CONNECT cancels the effect of any previous DIRECTORY  command.  At


Alto Pup FTP               December 12, 1981                          7




     present,   the   "Connect"  command   is   meaningful   only  when
     transferring files to  or from a Maxc  system or an IFS;  the Alto
     FTP server currently  ignores connect requests.  If  the "multiple
     directory" feature  of the Alto  Operating System ever  comes into
     widespread use, this may be changed.

COMPARE <remote filename>
     Compares  the contents  of <remote  filename> with  a file  in the
     local file system.   It tells you how  long the files are  if they
     are identical or the byte  position of the first mismatch  if they
     are not.  FTP will suggest a local filename based on the name body
     of  <remote  filename>.   If you  like  this  name,  type Carriage
     Return; if you wish to abort the compare command type  Delete.  If
     you would  like to  compare against  a local  file by  a different
     name, type the new name.  The old one will disappear, and you then
     have the same three choices as before.

DIRECTORY <directory name>
     Causes <directory name> to be used as the default remote directory
     in data transfer commands (essentially it  causes <directory-name>
     to  be attached  to all  remote filenames  that do  not explicitly
     mention a  directory).  Specifying a  default directory in  no way
     modifies  your  access privileges,  whereas  CONNECTing  gives you
     'owner  access'  (and usually  requires  a  password).  Explicitly
     mentioning  a  directory  in a  file  name  overrides  the default
     directory,   which  overrides   the  connected   directory,  which
     overrides the login directory.  Punctuation  separating <directory
     name>  from  other  parts  of  a  remote  filename  should  not be
     included.   For  example  you  might  type  "Directory  Alto"  not
     "Directory <Alto>".

RETRIEVE <remote filename>
     Initiates transfer of the specified remote file to the local host.
     The syntax of <remote filename> must conform to the  remote host's
     file  system name  conventions.  Before  transferring a  file, FTP
     will suggest a local-filename  (generally the same as  the remote-
     filename without directory or version), and will tell  you whether
     or not the file already exists on your local disk.  At  this point
     you may make one of three choices:

     1.  Type Carriage Return  to cause the  data to be  transferred to
         the local filename.

     2.  Type  Delete  to  indicate   that  the  file  is  not   to  be
         transferred.

     3.  Type  any  desired  local filename  followed  by  Return.  The
         previous local filename will disappear, the new  filename will
         replace it, and FTP will  tell you whether a file  exists with
         that name.  This  filename must conform to  local conventions.
         You now have the same three choices.

     If the remote-filename designates multiple files (the  remote host
     permits "*" or some equivalent  in file names), each file  will be
     transferred separately  and FTP will  ask you to  make one  of the
     above three choies for each  file.  At present, only Maxc  and IFS
     support  this capability.   That is,  you may  supply "*"s  in the
     remote-filename when retrieving files  from a Maxc or an  IFS, but
     not when retrieving files from another Alto.


Alto Pup FTP               December 12, 1981                          8




STORE <local filename>
     Initiates transfer of the specified local file to the remote host.
     Alto  file name  conventions apply  to the  <local  filename>; "*"
     expansion is not supported.  FTP will suggest a remote-filename to
     which you  should respond  in a manner  similar to  that described
     under RETRIEVE except that if you supply a different  filename, it
     must conform to the remote file system's conventions.  The default
     remote filename  is one with  the same name  and extension  as the
     local file; the remote server defaults other fields  as necessary.
     If the remote host is a Maxc system or an IFS, then  the directory
     is that most  recently supplied in  LOGIN or CONNECT  or DIRECTORY
     commands and the version is the next higher.

DUMP <remote filename>
     Bundles together a group of files from the local file  system into
     a 'dump-format' file (see the Alto Executive documentation for the
     dump-file format and more on dump-files in general) and stores the
     result as <remote  filename>.  FTP will ask  you for the  names of
     local files to  include in the  dump-file.  Terminate the  dump by
     typing  just  <return> when  FTP  asks for  another  filename.  By
     convention, files in dump-format have extension '.dm'.

LOAD <remote filename>
     Performs the inverse  operation of DUMP, unbundling  a dump-format
     file from the remote file system and storing the constituent files
     in the  local file system.   For each file  in the  dump-file, FTP
     will suggest a local file name and tell you whether a file by that
     name  exists  on your  disk.   You should  respond  in  the manner
     described under RETRIEVE.

LIST <remote file designator>
     Lists  all files  in the  remote file  system which  correspond to
     <remote file designator>.  The remote file designator must conform
     to file naming conventions  on the remote host, and  may designate
     multiple files  if "*" expansion  or some equivalent  is supported
     there.  If  the <remote file  designator> is terminated  by <comma
     return> rather than just a  <return>, FTP prints a prompt  of "**"
     at the left margin and prepares to accept one or more subcommands.
     These subcommands request printout of additional information about
     each  file.  To  terminate subcommand  input, type  a  <return> in
     response to the subcommand prompt.  The subcommands are:

     Type               Print file type and byte size.
     Length             Print length of file in bytes.
     Creation           Print date of creation.
     Write              Print date of last write.
     Read               Print date of last read.
     Times              Print times as well as dates.
     Author             Print author (creator) of file.
     Verbose            Same as Type+Write+Read+Author.
     Everything         Print all information about the file.

     This information is only  as reliable as the Server  that provided
     it,  and not  all Servers  provide all  of these  file properties.
     Altos derive  much of this  information from hints,  so do  not be
     alarmed if it is sometimes wrong.

DELETE <remote filename>
     Deletes <remote filename> from the remote filesystem.   The syntax


Alto Pup FTP               December 12, 1981                          9




     of  the remote  filename must  conform to  the remote  host's file
     system name conventions.   After determining that the  remote file
     exists, FTP asks you to  confirm your intention to delete  it.  If
     the  remote filename  designates multiple  files (the  remote host
     permits "*"  or some equivalent  in file names),  FTP asks  you to
     confirm the deletion of each file.

RENAME <old filename> <new filename>
     Renames  <old  filename>  in  the  remote  filesystem  to  be <new
     filename>.  The syntax  of the two  filenames must conform  to the
     remote host's file system name conventions, and each filename must
     specify exactly one file.

QUIT
     Returns  control   to  the  Alto   Executive,  closing   all  open
     connections.

TYPE <data type>
     Forces the data to be interpreted according to the specified <data
     type>,  which  may  be  TEXT or  BINARY.   Initially  the  type is
     UNSPECIFIED, meaning that the source process should,  if possible,
     decide on the appropriate type based on local information.

BYTE-SIZE <decimal number>
     Applicable only to files  of type Binary, BYTE-SIZE  specifies the
     logical byte size of the  data to be transferred.  The  default is
     8.

EOL <convention>
     Applicable only to files  of type Text, EOL specifies  the End-of-
     Line  Convention  to be  used  for transferring  text  files.  The
     values  for  <convention>  are  CR,  CRLF,  and  TRANSPARENT.  The
     default is CR.

DEVICE <string>
     Causes <string> to be used as the default device in  data transfer
     commands (essentially  it causes  <device> to  be attached  to all
     remote  filenames  that  do  not  explicitly  mention  one).   The
     punctuation  separating <device>  from the  other components  of a
     remote filename  should not  be included.   For example  you might
     specify "Device DSK" to Tenex, not "Device DSK:"

VERSION <string>
     Causes <string> to be used as the default version in data transfer
     commands (essentially it causes the version string to  be attached
     to all remote filenames that do not explicitly mention  one).  The
     punctuation   separating  the   version  information   from  other
     components  of  a remote  filename  should not  be  included.  For
     example  you might  specify "Version  123", to  IFS,  not "Version
     !123"

USER
     Allows you to toggle  switches which control operation of  the FTP
     User.  There is currently only one: DEBUG, which  controls display
     of  protocol  interactions.   Warning:  this  printout   (and  the
     corresponding one in the SERVER command below)  sometimes includes
     passwords.

SERVER


Alto Pup FTP               December 12, 1981                         10




     Allows you to toggle  switches which control operation of  the FTP
     Server.  The switches  are PROTECTED, OVERWRITE, KILL,  and DEBUG,
     corresponding to the global switches /P, /O, /K, and /D.

TELNET
     Allows  you  to toggle  switches  which control  operation  of the
     Telnet.   There is  currently only  one: CLOSE,  which  closes the
     Telnet connection if one is open.



5. Command Line Syntax


The  User  FTP  can  also be  controlled  from  the  command  line.  As
explained above, the  first token after  the subsystem name  and server
switches must be a  legal host name; if  the User FTP can't  connect to
the FTP Server  on that host  it will abort  and return control  to the
Alto Executive.  If a command  list follows the host name,  the command
line  interpreter  is  invoked  instead  of  the  interactive  keyboard
interpreter.  This permits the full capabilities of the  Alto Executive
(filename recognition, "*" expansion,  command files, etc.) to  be used
in constructing commands for FTP.

Each command is of the form:

                <Keyword>/<SwitchList> <arg> ... <arg>

To get a special character (any one of "*#';") past the Alto Executive,
it  must be  preceded by  a single  quote.  To  get a  "/" into  an FTP
argument, the "/"  must be proceeded by  two single quotes  (the second
one  tells  FTP  to treat  the  "/"  as an  ordinary  character  in the
argument,  and  the  first  one  gets  the  second  one  past  the Alto
Executive).

Unambiguous  abbreviations of  command  keywords (which  in  most cases
amount  to the  first letter)  are legal.   However,  when constructing
command  files, you  should always  spell commands  in full,  since the
uniqueness  of  abbreviations in  the  present version  of  FTP  is not
guaranteed in future versions.

A command is  distinguished from arguments  to the previous  command by
having a switch on it, so every command must have at least  one switch.
The switch "/C" has no  special meaning and should be used  on commands
where no other switches are needed or desired.


5.1. Command Line Errors

Command line errors fall into three groups: syntax errors, file errors,
and connection errors.  FTP can  recover from some of these,  though it
leaves the decision about whether to try up to you.

Syntax  errors such  as unrecognized  commands or  the wrong  number of
arguments to a  command cause FTP's command  interpreter to get  out of
sync with  the command  file.  FTP  can recover  from syntax  errors by
simply ignoring text until it encounters another command  (i.e. another
token with a switch).


Alto Pup FTP               December 12, 1981                         11




File errors such as trying to retrieve a file which does not  exist are
relatively harmless.   FTP recovers  from file  errors by  skipping the
offending file.

Connection errors such  as executing a store  command when there  is no
open  connection could  cause  FTP to  crash.  FTP  can't  recover from
connection errors.

When FTP  detects an error,  it displays an  error message in  the User
window.  If the error is fatal, FTP waits for you to type any character
and then aborts,  causing the Alto Executive  to flush the rest  of the
command line,  including any commands  to invoke other  subsytems after
FTP.  If FTP can recover from the error, it asks you to confirm whether
you wish  to continue.   If you  confirm, it  plunges on,  otherwise it
aborts.  The confirmation request can be bypassed by invoking  FTP with
the global error switch false (FTP/-E ...) in which case it will plunge
on after  all non  fatal errors.  If  you aren't  around when  an error
happens and  you have  told FTP to  get confirmation  before continuing
after an error, the remote Server will probably time out and  close the
connection.  If you then return and tell FTP to continue, it will get a
fatal connection error and abort.


5.2. Command Line Switches

Most commands take local switches.  These switches have  default values
which are  used if the  switch is not  mentioned.  Proceeding  a switch
with a  minus sign  inverts its sense:  Retrieve/-O means  retrieve but
don't  overwrite.   While  the  interpretation  of  a  switch sometimes
depends on the command, the general idea is:

Switch   Default   Function

/C       --        [Command] null switch  which tells the  command line
                   parser that this token is a command.

/S       false     [Selective] the remote and local file  names differ.
                   The   LOAD   command  uses   this   switch  slightly
                   differently.

/D       update    [Dates] show file creation dates.

/V       false     [Verify] request confirmation from the keyboard.

/O       true      [Overwrite] allow overwriting existing files.

Transfers may be conditioned  upon comparison of the creation  dates of
corresponding local and remote files.  The comparison is  <source file>
<operator> <destination file>.  For STORE, the source file is the local
file; for RETRIEVE, the source file is the remote file.   The operators
are:

Switch   Function

/#       [NotEqual] transfer  the file  if the  creation dates  are not
         equal.  This  must be  quoted  (/'#)  to keep  it  out  of the
         clutches of the Alto Exec.

/=       [Equal] transfer the file if the creation dates are equal.


Alto Pup FTP               December 12, 1981                         12




/>       [Greater] transfer the file  if the source's creation  date is
         greater than the destination's.

/<       [Less] transfer the file if the source's creation date is less
         than the destination's.

/U       [Update] same as /> (for backward compatibility).

/A       [All] transfer the file  even if no corresponding  file exists
         in the other file system.

If more  than one switch  is present, they  are ORed together,  so, for
example, "/>=" means transfer the file if the source's creation date is
greater than or equal to the destination's.

The sense of a switch is  inverted if it is preceeded by a  minus sign.
Thus:
        /-= is equivalent to /#,
        /-# is equivalent to /=,
        /-< is equivalent to />=, and
        /-> is equivalent to /<=.

Note that a minus sign  inverts the sense of the  immediately following
character, not the entire operator expression.


5.3. Command Line Commands

OPEN/C <host name>
     See description in "Keyboard commands".  The first token after the
     subsystem name and  global switches is assumed  to be a  host name
     and no OPEN verb is required  (in fact if you supply it,  FTP will
     try  to make  a connection  the host  named OPEN  which  is almost
     certainly not what you want).

CLOSE/C
     Closes the currently open User FTP connection.

LOGIN/C <user name> <password>
     See  description in  "Keyboard commands".   The <password>  may be
     omitted.

LOGIN/Q <user name>
     Causes FTP  to prompt you  for the password.   This form  of LOGIN
     should  be  used in  command  files since  including  passwords in
     command files is a bad practice.

CONNECT/C <directory name> <password>
     See  description in  "Keyboard commands".   The <password>  may be
     omitted.

CONNECT/Q <directory name>
     Causes FTP to prompt you for the password needed to connect to the
     specified <directory name>.  This  form of CONNECT should  be used
     in command files since  including passwords in command files  is a
     bad practice.

DIRECTORY/C <default directory>
     See discription in "Keyboard commands".


Alto Pup FTP               December 12, 1981                         13




RETRIEVE/C <remote filename> ... <remote filename>
     Retrieves each <remote  filename>, constructing a local  file name
     from the actual remote file name as received from the Server.  FTP
     will  overwrite  an existing  file  unless the  /N  (No overwrite)
     switch is appended to the RETRIEVE command keyword.

     If the remote host allows "*" (or some equivalent) in  a filename,
     a single remote  filename may result  in the retrieval  of several
     files.  (Note that you must quote the "*" to get it past  the Alto
     Executive's  command  scanner.)  As  mentioned   previously,  this
     capability  is implemented  only by  Maxc and  IFS FTP  Servers at
     present.

RETRIEVE/S <remote filename> <local filename>
     Retrieves <remote filename> and  names it <local filename>  in the
     local file system.  This version of RETRIEVE must have exactly two
     arguments.  FTP will overwrite an existing file unless the /-O (No
     Overwrite)  switch  is  also  appended  to  the  RETRIEVE  command
     keyword.  The remote filename should not cause the server  to send
     multiple files.

RETRIEVE/> <remote filename> ... <remote filename>
     Retrieves <remote filename> if  its creation date is  greater than
     that of the local  file.  If the corresponding local  file doesn't
     exist,  the remote  file  is not  retrieved.  This  option  can be
     combined with RETRIEVE/S to rename the file as it is transferred.

RETRIEVE/>A <remote filename> ... <remote filename>
     Same as RETRIEVE/> except if the corresponding local  file doesn't
     exist, the remote file is retrieved anyway.

RETRIEVE/V
     Requests  confirmation from  the keyboard  before writing  a local
     file.  This option is useful in combination with the Update option
     since creation date is  not a fool-proof criterion for  updating a
     file.

RETRIEVE/-O  Retrieves  a file  only  if the  corresponding  local file
     doesn't exist.

STORE/C <local filename> ... <local filename>
     Stores each  <local filename> on  the remote host,  constructing a
     remote filename from the name body of the local filename.  A local
     filename may contain  "*", since it will  be expanded by  the Alto
     Executive  into  the  actual  list  of  filenames  before  the FTP
     subsystem is invoked.

STORE/S <local filename> <remote filename>
     Stores <local filename> on  the remote host as  <remote filename>.
     The remote filename must  conform to the file name  conventions of
     the  remote host.   This version  of store  must have  exactly two
     arguments.

STORE/> <local filename> ... <local filename>
     Stores  each <local  filename>  on the  remote host  if  the local
     file's creation date  is greater than  the remote file's.   If the
     corresponding remote  file doesn't  exist, the  local file  is not
     stored.  This option  can be combined  with STORE/S to  rename the
     file as it is transferred.


Alto Pup FTP               December 12, 1981                         14




STORE/>A <local filename> ... <local filename>
     Same as  STORE/> except if  the corresponding remote  file doesn't
     exist, the local file is stored anyway.

STORE/V
     Requests confirmation  from the keyboard  before writing  a remote
     file.  This option is useful in combination with the Update option
     since creation date is  not a fool-proof criterion for  updating a
     file.

DUMP/C <remote filename> <local filename>...<local filename>
     See the description in "keyboard Commands".

LOAD/C <remote filename> ... <remote filename>
     See the description in  "keyboard Commands".  If the /V  switch is
     appended to the LOAD command keyword, FTP will request confimation
     before writing each file.  Type <return> to write the  file, <del>
     to skip it.  FTP will overwrite an existing file unless the /N (No
     overwrite) switch is appended to the LOAD command keyword.

LOAD/> <remote filename> ... <remote filename>
     Loads files  from <remote  filename> if  their creation  dates are
     greater than the corresponding creation dates of local  files.  If
     the corresponding local file doesn't exist, the remote file is not
     loaded.

LOAD/>A <remote filename> ... <remote filename>
     Same  as LOAD/>  except if  the corresponding  local  file doesn't
     exist, the remote file is loaded anyway

LOAD/S <remote filename> <filename 1> ... <filename n>
     Loads files from <remote filename> if their names are in  the list
     <filename 1> ...  <filename n>.  Files  within the dump  file that
     are not in the list are skipped.  This option can be combined with
     the /U, /V, and /N options.

LIST/C <remote filename> ... <remote filename>
     See the description  in "Keyboard Commands".  The  subcommands are
     specified by local switches:

     /T       Type,
     /L       Length in bytes,
     /D       Creation date (see below),
     /W       Write date,
     /R       Read date,
     /A       Author (creator),
     /V       Verbose = /TWRA, and
     /E       Everything = /TLDWRA.

     Dates always include times.  /C should have been the creation date
     but that  collides with  the use of  /C to  mean no  local options
     (sigh).

DELETE/C <remote filename>
     See the description in  "Keyboard Commands".  If the /V  switch is
     appended  to  the   DELETE  command  keyword,  FTP   will  request
     confirmation before deleting  each file.  Type <return>  to delete
     the file, and <del> (oops!) if you don't want to delete it.

COMPARE/C <remote filename>...<remote filename>


Alto Pup FTP               December 12, 1981                         15




     Compares the contents  of <remote filename>  with the file  by the
     same name  in the local  file system.  It  tells you how  long the
     files are if they are identical or the byte position of  the first
     mismatch if they are not.

COMPARE/S <remote filename> <local filename>
     Compares  <remote  filename> with  <local  filename>.   The remote
     filename must conform to  the file name conventions of  the remote
     host.  This version of COMPARE must have exactly two arguments.

COMMENT/S <arbitrary text>
     The <arbitrary text> is ignored until a token with an imbedded "/"
     is encountered.   This token  is taken as  the next  command.  The
     quote  character  is a  single  quote.  Thus  "foo'/bar"  does not
     terminate a comment.

RENAME/C <old filename> <new filename>
     See the description in "Keyboard Commands".

TYPE/C <data type>
     See the description in "Keyboard Commands".

BYTE-SIZE/C <decimal number>
     See the description in "Keyboard Commands".

EOL/C <convention>
     See the description in "Keyboard Commands".

DEVICE/C <string>
     See the description in "Keyboard Commands".

VERSION/C <string>
     See the description in "Keyboard Commands".

DEBUG/C
     See the description of the DEBUG subcommand under the USER command
     in "Keyboard Commands".


5.4. CLI Examples

To transfer files FTP.run and FTP.syms from the Alto called "Michelson"
to the Alto  called "Morley", one might  start up FTP on  Michelson (to
act as an FTP Server), then walk over to Morley and type:

     FTP Michelson Retrieve/C FTP.run FTP.syms

Alternatively, one could start an FTP server on Morley (invoking  it by
"FTP/O" to permit files to be overwritten on Morley's disk), then issue
the following command to Michelson:

     FTP Morley Store/C FTP.run FTP.syms

The latter  approach is  recommended for  transferring large  groups of
files such as "*.run" (since expansion of the "*" will be  performed by
the Alto Executive).

To retrieve User.cm from the  FTP server running on Alto  serial number
123 (name unknown, but it is on the local Ethernet):


Alto Pup FTP               December 12, 1981                         16




     FTP 123'# Retrieve/C User.cm

Note that the "#" must be preceded by a single quote when included in a
command line, since otherwise the Alto Executive does funny things with
it.   (Quotes  are  not  necessary  when  typing  to  FTP's interactive
keyboard interpreter).

To  start FTP,  have the  FTP  User connect  to Maxc,  and  then accept
further commands from the keyboard:

     FTP Maxc

To retrieve <System>Pup-Network.txt from Maxc and store it on  the Alto
as   PupDirectory.bravo,   and  store   PupRTP.bcpl,   Pup1b.bcpl,  and
PupBSPStreams.bcpl on <DRB> with their names unchanged:

     FTP Maxc Connect/C drb mypassword Retrieve/S <System>Pup-
     Network.txt PupDirectory.bravo Store/C PupRTP.bcpl Pup1b.bcpl
     PupBSPStreams.bcpl

To  retrieve  the  latest  copy  of  all  .RUN  files  from  the <alto>
directory, overwriting  copies on  the Alto disk  (The single  quote is
necessary to prevent the Alto Executive from expanding the "*"):

     FTP Maxc Retrieve/C <alto>'*.run

To update the Alto disk with new copies of all <alto> files whose names
are contained  in file  UpdateFiles.cm, requesting  confirmation before
each retrieval:

     FTP Maxc Directory/C Alto Ret/>V @UpdateFiles.cm@

To store  all files with  extension .BCPL from  the local Alto  disk to
your login directory on  Maxc (the Alto Executive will  expand "*.bcpl"
before invoking FTP):

     FTP Maxc Store/C *.bcpl

To retrieve <System>Host-name/descriptor-file.txt;43 (two single quotes
are  necessary to  get the  "/"  past the  Alto Executive  and  the FTP
command scanner,  and one quote  is necessary to  get the ";"  past the
Alto Executive):

     FTP Maxc Ret/C <System>Host-name''/descriptor-file.txt';43

To cause  Memo.press to be  spooled for printing  by the  Maxc printing
system:

     FTP Maxc Store/S Memo.press LPT:

This also works unformatted text files if you know what you  are doing.
It does not do the right thing for Bravo-format files.

To use FTP as a stop-gap IFS:

     FTP/T-UO

This starts only a server with overwriting of existing files permitted.
When using the trident, there  isn't enough space to start both  a User
and a Server.


Alto Pup FTP               December 12, 1981                         17




6. File Property Defaulting


Without  explicit  information  from  the  file  system,  it  is  often
difficult to  determine whether a  file is Binary  or Text,  if Binary,
what  its byte-size  is, and  if Text,  what End-Of-Line  convention is
used.  The User and Server FTPs use some simple heuristics to determine
the  correct  manner  in  which to  transfer  a  file.   The heuristics
generally do the right thing in the face of incomplete information, and
can be  overridden by  explicit commands  from a  human user  who knows
better.

The FTP protocol specifies  a standard representation for a  file while
in transit over a network.  If the file is of type Binary, each logical
byte is packed  right-justified in an  integral number of  8-bit bytes.
The byte-size is sent as a  property along with the file.  If  the file
is of  type Text, each  character is sent  right-justified in  an 8-bit
byte.  An EOL convention may  be sent as a file property.   The default
is that <return> marks the end of a line.


6.1. File Types

FTP determines the type of a  local file by reading it and  looking for
bytes with the high-order bit on.  If any byte in the file has  a high-
order bit on, the  file is assumed to  be Type Binary, otherwise  it is
assumed to be Type Text.  FTP will generate a warning, but allow you to
send  what  it thinks  to  be a  text  file as  type  Binary,  since no
information is  lost.  It  will refuse to  send a  binary file  as type
text.

         Don't specify a Type unless you know what you are  doing.  The
         heuristic will not lose information.


6.2. Byte-Size

If a  file is  type Binary,  the byte-size  is assumed  to be  8 unless
otherwise specified.  The FTP  User and Server will both  accept binary
files of any byte-size and write  them as 8 bit bytes on the  disk.  No
transformation is done on the data as it is written to the disk:  it is
stored in network default format.  Since there is no place in  the Alto
file system to save the byte-size property, it is lost.

Similarly,  requests for  Binary files  will be  honored with  any byte
size, and  whatever is  on the  disk will  be sent  to the  net without
transformation.  Since  Alto files have  no byte size  information, the
byte-size property  will be defaulted  to 8 unless  otherwise specified
(by the BYTE command),  in which case whatever was  otherwise specified
will be sent as the byte size.

         Don't specify a Byte-size unless you know what you  are doing.
         Alto-Alto transfers can't go wrong.  Alto-Maxc  transfers with
         weird byte-sizes will not work unless the  byte-size specified
         in the Alto to Maxc direction is the same as the  byte-size in
         which the file was stored on the Alto.  If it isn't,  the Alto
         will not  give any  error indication, but  the result  will be
         garbage.


Alto Pup FTP               December 12, 1981                         18




6.3. End-of-Line Conventions

FTPs are expected  to be able to  convert text files between  the local
file system  End-Of-Line (EOL) convention  and the  network convention.
Conveniently enough, the Alto file system's internal  representation of
a text file is the same as the network standard (a bare  <return> marks
the end of a  line).  The Alto FTP  does not do any  transformations on
text files.  It will refuse to store a text file coming in from the net
whose EOL convention is CRLF.

As  an  escape  to  bypass  conversion  and  checking,  EOL  convention
'transparent' tells both ends  NOT to convert to network  standard, but
rather send  a file  'as is'.  This  is included  for Lisp  files which
contain internal character pointers that are messed up by removing line
feed characters.

         Don't specify an EOL  convention unless you know what  you are
         doing.  If your text file  is a Lisp source file,  specify EOL
         convention 'Transparent'.


6.4. File Dates

The Alto file system keeps three dates with each file:  Creation, Read,
and  Write.   FTP  treats  the  read  and  write  dates  as  properties
describing the local copy  of a file: when  the file was last  read and
written in the  local file system.  FTP  treats the creation date  as a
property of the file  contents: when the file contents  were originally
created, not when  the local copy was  created.  Thus when FTP  makes a
file on the local disk, the  creation date is set to the  creation date
supplied by the remote FTP, the write date is set to 'now' and the read
date is set to 'never read'.



7. Abort and Error messages


The most common Abort message is "Timeout.  Good bye", generated when a
server process has not received any commands for a long time (typically
3 minutes).

The  most  common Error  message  is "Port  IQ  overflow"  indicating a
momentary shortage of input  buffers at the remote host.   Receiving an
Error Pup  does not imply  that the file  in transit has  been damaged.
Loss of or damage to a file will be indicated by an explicit message in
the User FTP  window.  The next iteration  of Pup will  probably rename
'Error Pups' to be 'Information Pups'.



8. Telnet


FTP provides a simple User  Telnet as a convenience for logging  into a
remote host (e.g., Maxc) to poke around without having to leave the FTP
subsystem and start Chat.  It lacks most of the creature  comforts Chat
provides,  such  as  automatic attaching  to  detached  jobs, automatic
logging in, etc.  The Telnet is not enabled when the User FTP  is being


Alto Pup FTP               December 12, 1981                         19




controlled from  the command line.   When the Telnet  does not  have an
open connection, it waits for you  to type a host name with  the syntax
explained above for the OPEN  command, and then attempts to  connect to
the specified host.  If you  wish to abort the connection  attempt, hit
the bottom unmarked key  (opposite right-shift).  You can get  a larger
Telnet window by not starting a server (type FTP/-S to the Executive).



9. Revision History


April 1976

First release.

May 1976

/Q switch added  to CONNECT.  Connection requests  to the User  FTP and
Telnet can be aborted.   Login prompt changed.  1 minute  Timeout added
when  waiting  to  finish  after  a  command  line  error.    User  FTP
automatically recovers from more "No" responses from the remote server.

June 1976

Dos version released.  DIRECTORY and LIST, commands added.  Update (/U)
option added.  File creation dates added.  3 minute no-activity timeout
added to  FTP Server.   FTP version,  time-of-day, and  machine address
added  in top  window.   "Ding" now  flashes only  the  affected window
instead of the whole display.

August 1976

RDos version released.  Same as June release for Dos and Alto.

October 1976

DUMP and LOAD  commands added to user  FTP.  KILL command  added.  Free
disk page count added to  the title line.  Verify (/V) switch  added to
the RETRIEVE command.

November 1976

Bug fixes to the October release.

May 1977

This version was  only released to  friends.  KILL command  removed and
turned into  a server option.   DEBUG command moved  into new  USER and
SERVER commands.   Trident disk option  (/T) added.  User  LIST command
improved and  Server LIST response  implemented.  Password  checking by
the FTP server implemented.   Telnet window enlarged at the  expense of
possibly losing information from the top of the window if the lines are
very  full.  DELETE,  RENAME,  and DEVICE  commands  implemented.  Much
internal reorganization so that  the protocol modules could be  used in
IFS and released as a package.

July 1977


Alto Pup FTP               December 12, 1981                         20




Global switches changed.   <Shift-Swat> should work more  reliably now.
User LIST  command further improved.   Keyboard command  interpreter is
much more robust and consistant.   Command line STORE and DUMP  go much
faster since they look up  files using MDI.  FTP/Tx opens  Trident unit
'x'.  LOGIN command added to command line interpreter.

November 1977

Microcode added to speed up execution.

March 1978

User  log option  added (see  /L  and /A  switches and  'FTP  User Log'
section).  AllocatorDebug  switch removed.   New command  line commands
COMPARE,  OPEN,  and  CLOSE added.   Command  line  errors  are handled
differently (see /E global  switch and 'Command Line  Errors' section).
When using a Trident, either a User or a Server FTP is started  but not
both (see the section on Trident disks).

September 1979

This is a maintenance release coordinated with OS17, fixing a  few bugs
and  reloading with  current  packages.  CONNECT  cancels  any previous
DIRECTORY.   CLOSE  cancels any  previous  CONNECT,  DIRECTORY, DEVICE,
TYPE, BYTE, or EOLC.  Multiple logical file systems on a T-300  can now
be addressed: Ftp/T400 opens logical filesystem 1 on physical unit 0.

October 1979

The command line version of the OPEN command retries  failed connection
attempts every five seconds under control of the error  flag.  Ftp.boot
is now a type B boot file.  It EtherBoots faster and consumes less disk
space  in  boot  servers.   It now  works  with  all  Alto  file system
configurations.

June 1980

New command line commands:  LIST, LOAD/U and LOAD/S.  Ftp  handles file
creation dates in dump-format  files.  Subcommand mode in  the keyboard
LIST command  is the same  as Maxc and  IFS, namely one  terminates the
filename with <comma carriage-return>, and the VERBOSE  option includes
file lengths.  The keyboard DIRECTORY and DEVICE commands display their
previous values.  STORE and  RETRIEVE report bits per second.   The TFS
option now works on Alto/Sugart systems.

September 1980

New  commands  STORE/U,  STORE/V, COMMENT/C,  and  VERSION.   /A switch
during date  controlled transfers controls  whether to transfer  a file
when the corresponding file in the other filesystem doesn't  exist.  /D
switch controls display of file creation dates.

October 1980

New  switches:  /=,  /#,  />,  /<,  which   generalize  date-controlled
transfers (see section  5.2).  When Ftp  finishes, it only  updates the
username and  password in  the OS if  no password  was present  when it
started.  Thus, if you log in as "guest" to access a file on  a foreign
file server, Ftp won't clobber your real identity.


Alto Pup FTP               December 12, 1981                         21




December 1981

New keyboard  command COMPARE.  The  keyboard and command  line COMPARE
commands  now give  the exact  byte position  of the  first difference.
Store and retrieve go faster.