Computer Corporation of America




















         Datacomputer File Transfer Program User's Guide










                          November 1976
î







                            Overviewî                            ________

     The Datacomputer is a shared large-scale data  base  utility
offering  data  storage  and  data  management  services to other
computers on the Arpanet.  The system is intended to be used as a
centralized facility for archiving data, for sharing  data  among
various  network  hosts,  and  for  providing inexpensive on-line
storage for sites needing to supplement their  local  capability.
The  Datacomputer  is  implemented  on  dedicated  hardware,  and
comprises  a  separate  computing  system  specialized  for  data
management.   Logically, the system can be viewed as a closed box
shared by multiple external processors and accessed in a standard
notation called Datalanguage.

     The  Datacomputer  File  Transfer  Program   (DFTP)   is   a
user-invoked program that stores and retrieves local files on the
Datacomputer.    DFTP   translates   simple  user  commands  into
Datalanguage,  sends   the   Datalanguage   and   data   to   the
Datacomputer,  processes  the messages and data returned from the
Datacomputer, and notifies the user of the  results.   DFTP  also
manages local file input/output and secondary network connections
to and from the Datacomputer.




                          The Directoryî                          _____________

     The DFTP Datacomputer directory is a tree, with  site  nodes
anchored  to  a  common root node, user nodes subordinate to site
nodes, optional subdirectories of  arbitrary  depth  and  breadth
beneath  user  nodes, and user files stored in special leaf nodes
(called '<FILES>' nodes).  Pictorially,
                       <ROOT>
                       /    \
                   SITE      SITE    ...
                  /    \
              USER      USER    ...
             /
       <FILES>     SUBDIRECTORY    ...
                  /            \
            <FILES>             SUBDIRECTORY    ...
                                            \
                                            <FILES>    ...

     The <FILES> nodes are the repositories  of  all  data.   The
user  files  they  contain  are  not  known  individually  to the
Datacomputer (unlike nodes), but are separate  entities  only  to
DFTP.   There  can  be  only  one <FILES> node directly under any
given user or subdirectory node.  DFTP users do not  reference  a
<FILES>  node  directly;   a reference to a file under a specific
user or subdirectory node is expanded into a  reference  to  that
î



DFTP User's Guide                                               2


file in the <FILES> node under the specified node.  (If a node is
not specified a default is supplied).

     There  are  two  basic  types  of  commands  --  those  that
reference  only  nodes and those that reference user files.  Node
level commands operate at the global level of sites,  users,  and
subdirectories.   File  level commands operate at the local level
(inside a <FILES> node) storing, retrieving, and  modifying  data
within  that  node.   The  argument  to  a file level command can
consist only of a file name, or of a file name preceded by a node
argument (such as the node level commands take).



                        Referencing Nodesî                        _________________

     The mechanism for referencing a node, called  a  node  path,
consists of a context and a node list.  A context is an anchoring
point  for  node name references (indicated by one, two, or three
left-angle-brackets);  if none  is  specified,  DFTP  supplies  a
default.   A node list is a sequence of node names, starting from
the anchor, defining the desired branch of the directory tree.

     There are three contexts, TOP, ATTACH, and CONNECT.

  1.  The top context ('<<<') anchors the  node  path  at  the
      root  node  and  is used primarily for referencing other
      site and user nodes.

  2.  The attach context ('<<') is a node  path,  set  by  the
      ATTACH   command  (and  by  DFTP  automatically  at  the
      beginning of a session), and usually  indicates  a  user
      node.   It  is used mainly as a reference point for name
      space division beneath the user node.

  3.  The connect context ('<') is a node path (initially  the
      same as the attach context), set by the CONNECT command,
      and    conventionally   indicates   a   user   node   or
      subdirectory.


     A node  list  consists  of  a   sequence   of   node   names
(consecutive  levels  in  the  tree)  separated  by  right  angle
brackets.  A  password  may  be  necessary  in  acquiring  access
privileges  at  a particular node, in which case the node name is
followed by a colon and the  password.   Sets  of  nodes  can  be
referenced  --  all  nodes at a particular level are indicated by
'*', and all inferior nodes are designated  by  '**'  (which  can
occur only at the end of the node list).

î



DFTP User's Guide                                               3


     For example,

        <<<CCA>HACKER:>WALDO

Starting  at  the  top  context,  the  node  path  references the
subdirectory WALDO under user HACKER at site CCA (with a password
supplied to gain access to HACKER).

        <<WALDO>**

Starting at the attach context,  the  node  path  references  the
subdirectory  WALDO  and  all  inferior nodes (note that WALDO is
included -- the REMOVE command, for  example,  would  delete  the
node WALDO as well as its inferiors).


                        Referencing Filesî                        _________________

     User file names have the same form as TENEX  file  names:  a
file  designation, an optional extension, and an optional version
number.  The file designation is separated from the extension  by
a  period,  and  the  extension  from  the  version  number  by a
semicolon.  File sets may be indicated by an asterisk in  any  or
all  of  the  file  designation,  extension,  and  version number
fields.

     Version numbers allow unambiguous reference  of  files  with
the same file designation and extension.  Each file has a version
number  assigned  to  it by DFTP (which is unrelated to its TENEX
version number) -- version numbers cannot be  set  by  the  user.
Later  versions  of  a  file  with  the same file designation and
extension receive higher version numbers.  A version  number  may
be explicitly supplied in referencing an existing file, otherwise
a default is provided.

     All commands that accept as input  a  file  name  will  also
accept  a  file path, which consists of a node path followed by a
file name, with the two parts separated by a right angle  bracket
(unless  the node path is only a context, in which case the right
angle bracket is omitted).  If a node path  is  given,  the  file
name is used in the <FILES> node under the node referenced.  If a
node path is not given, the file name is used in the <FILES> node
under  the  connect  context  --  the  default context for a file
reference is the connect context.

     For example:
        MAIL.TXT
The file name references the file MAIL.TXT in  the  <FILES>  node
under the connect context.
        <*.SAV;*
The  file  name  references  all  versions  of all files with the
extension SAV in the <FILES> node under the connect context.
î



DFTP User's Guide                                               4


        <<MACROS>COMMON>SYSMAC.MAC
Starting at the attached context (presumably a  user  node),  the
file  path  references  the  file  SYSMAC.MAC in the <FILES> node
under the COMMON subdirectory of the MACROS subdirectory.


                         Command Summaryî                         _______________

     DFTP command and argument input is similar  to  TENEX,  with
command recognition and TENEX editing controls.  In particular,

      <control-A> deletes a character,

      <control-R> retypes the line,

      <control-X> and <rubout> delete the line,

      <escape> and <space> are separators, and

      <carriage   return>,   <line   feed>   and   <eol>   are
      terminators.


     The DFTP commands and their arguments are:

      ATTACH <node path>

      CONNECT <node path>

      DELETE <file path>

      DIRECTORY <file path>

           TERSE

           VERBOSE


      EXPUNGE <node path>

      GET <file path> [local synonym]
      RETRIEVE is exactly equivalent to GET.

      LIST <node path>

      NO-DATALANGUAGE

î



DFTP User's Guide                                               5


      PUT <file path> [remote synonym]
      STORE is exactly equivalent to PUT.

      QUIT

      REMOVE <node path>

      SHOW-DATALANGUAGE

      TIME-TRANSFERS

      UNDELETE <file path>

      UNTIME-TRANSFERS

Items  in  angle brackets are required arguments; items in square
brackets are optional ones.

     The connect context is   the   default   context   for   all
commands   except   ATTACH  and  CONNECT,  which  have  as  their
respective defaults the top context and the attach context.

     Many commands have  default  arguments  and  trailers  which
are invoked  by  giving  a  space  or  escape  as the argument or
argument terminator.   The  default  argument  is  '<<'  for  the
CONNECT  command,  '<'  for  EXPUNGE,   and  '**'  for  LIST  and
REMOVE,  which  is also the default trailer.  For DIRECTORY, GET,
PUT, DELETE, and UNDELETE,  the   default  argument  and  trailer
(after a '>') is '*.*;*'.



                     Node Oriented Commandsî                     ______________________

     The ATTACH command sets the  attach  context  and  initiates
Datacomputer accounting functions.

     The CONNECT command sets the connect  context  (and  creates
new subdirectories).

     The EXPUNGE command removes files marked as deleted from the
<FILES>  node  under  the node given as the command argument.  If
the <FILES> node contains no files (deleted or undeleted)  it  is
deleted from the Datacomputer directory.

     The LIST command lists  Datacomputer  nodes  (sites,  users,
subdirectories,  and  <FILES>)  and  information about them.  The
information displayed by the VERBOSE option comes  directly  from
the Datacomputer.

î



DFTP User's Guide                                               6


     The REMOVE  command  removes  nodes  from  the  Datacomputer
directory;   they  must either have no inferior nodes, or be part
of a node set specified using "**".  In  the  latter  case,  data
stored under the nodes will also be deleted.


                     File Oriented Commandsî                     ______________________

     File deletion operates as with TENEX.   The  DELETE  command
marks files as deleted, but does not eliminate them.  They can be
listed via the VERBOSE option of the DIRECTORY command, and their
deleted  status  can  be  changed  by  the  UNDELETE command. The
removal  of  deleted  files  is  deferred  until  an  EXPUNGE  is
performed  on  the  <FILES>  node  containing  them.  The default
version number is the lowest undeleted,  unless  a  file  set  is
indicated, in which case all versions in the set are deleted.

     The DIRECTORY command  lists  files  and  information  about
them.  The VERBOSE option lists deleted and undeleted files (with
deleted  ones indicated by a D after the name), the date and time
created (for TOPS-10 sites), the date and time last written  (for
TENEX  sites), the date and time stored, and the size.  For files
stored from TENEX sites the  size  information  is  in  the  form
<number  of  bytes>(<byte  size>).  For files stored from TOPS-10
sites  the  information  is  in  the  form  <number  of  36   bit
words>(-<data mode)).  The TERSE option lists undeleted files and
their  sizes  (as  with the VERBOSE option).  The default version
number is the highest undeleted, unless a file set is  indicated,
in  which case information for all versions in the set is listed.

     The GET and PUT commands retrieve and store local disk files
on the Datacomputer. Files of any type (text or binary image, for
example) can be stored.   If  a  synonym  is  not  supplied,  the
Datacomputer  file  name  is used as the local file name.  If the
first argument to either command is completed with an escape or a
space, the synonym  option  is  invoked  and  the  commands  then
operate in the form
        GET Datacomputer file [AS] local file, and
        PUT local file [AS] Datacomputer file.
For  the  GET  command  the default version number is the highest
undeleted, unless a file set is  indicated,  in  which  case  all
versions  of  the  set  are  retrieved.  The PUT command sets the
version number of the file being stored to be  one  greater  than
the  highest  version  of  existing  files  with  the  same  file
designation and extension (note that a file set indicated in  any
file  name field is treated as if all existing files had the same
field -- storing  *.*  results  in  the  stored  files  receiving
version numbers one greater than the highest version number found
in any existing file).

î



DFTP User's Guide                                               7


     The UNDELETE command rescinds a file's deleted status.   The
default  version number is the highest deleted, unless a file set
is  indicated,  in  which  case  all  versions  in  the  set  are
undeleted.


                     Miscellaneous Commandsî                     ______________________

     ENABLE causes DFTP to recognize an expanded set of commands,
including  the  privileged  commands discussed below.  Its action
is marked by a change in the prompt character, from "*" to"!".

     The   SHOW-DATALANGUAGE   and    NO-DATALANGUAGE    commands
respectively  allow and inhibit the output to the user's terminal
of the messages sent to and received from the Datacomputer.

     Data transfer rates are calculated and  given  to  the  user
when   the   TIME-TRANSFERS   command   has  been  invoked.   The
calculations are avoided with the UNTIME-TRANSFERS command.

     QUIT   exits   gracefully   from   DFTP,   closing   network
connections.


                     Site Dependent Featuresî                     _______________________

     For the TOPS-10 version, the LOCAL-DIRECTORY  command  lists
the user's local file directory.

     For the TENEX version, the EXEC command  provides  the  user
with  an inferior exec, which is flushed when the user returns to
DFTP.  Where a local file name is possible (in the  GET  and  PUT
commands)   an   initial  space  or  escape  invokes  TENEX  name
recognition, indicated  by  a  right  angle  bracket  prompt.   A
control-O  can  be  used  to  halt  the  output from the LIST and
DIRECTORY commands.


                            Responsesî                            _________

     There are three types of messages that DFTP gives the  user.
Comments    surrounded   by   square   brackets   are   primarily
informational  messages,  and  are  never  errors.    Parentheses
enclose non-fatal errors and informational Datacomputer messages,
such  as  '(LEBAR2:  ERROR:  NO  SUCH  FILE)',  resulting from an
attempt to DELETE a nonexistent file, and '(SXPF9:  STAGING  DATA
FOR FILE = DFTP.CCA.DFTP.<FILES>)', indicating that data is being
moved from tertiary mass memory to secondary buffer memory.

These  messages come directly from the Datacomputer, indicated by
the name and colon at the  head  of  the  message.   Fatal  error
messages  are  surrounded  by question marks, and of course never
occur.
î



DFTP User's Guide                                               8


                         Access Controlî                         ______________

     Access  control  in  DFTP  uses  a  subset   of   the   full
Datacomputer  facilities.   The  full  discussion of Datacomputer
privilege facilities is in the current Datacomputer User  manual;
however,  the  following  summary  should  suffice  for most DFTP
users.  Access privileges are  specified  in  "privilege  blocks"
attached  to  nodes in the directory.  A node may have any number
of privilege blocks attached to it; each specifies  a  particular
set  of  access privileges, and a class of users to whom that set
applies.  DFTP provides two classes of access:

   -  CONTROL allows users to create and allocate nodes  under
      the  node  at  which it is granted, change privileges at
      that node and below, and read, write,  and  delete  data
      stored below that node.

   -  READ allows users to attach to  a  node  and  read  data
      stored  under  it,  but  not to perform any of the other
      functions granted by CONTROL.

All other users are prevented from any access to the data.  Users
may be may be  identified  in  DFTP  by  their  network  identity
(defined  by  the  host  and  socket  from  which they access the
Datacomputer),  and  by   passwords.    (Some   systems   enforce
assignment  of socket numbers according to the user's identity on
that system, thus providing a convenient automatic identification
to DFTP.)

     When a user attempts to ATTACH to a  node,  or  to  read  or
write  data stored under it, the Datacoputer checks to see if the
user is in any of the user-sets identified in privilege blocks on
that  node,  and  if  so,  assigns  the  corresponding  class  of
privileges.   If  no set matches the user, then no privileges are
allowed.  The scan is done in the order of creation of  privilege
blocks,  and if a user matches more than one, the first one takes
effect.  Access  controls  are  set  by  the  CHANGE  and  CREATE
commands, described in the following section.


                       Privileged Commandsî                       ___________________

     Certain administrative functions are performed by a  set  of
restricted  commands,  known as "privileged commands."  These are
not normally available to the user; they are recognized  by  DFTP
only after execution of the ENABLE command.

î



DFTP User's Guide                                               9


   -  The ALLOCATE command is used to set the  maximum  number
      of  megabits  a user may consume (it can also be used to
      set subdirectory  limits).   Allocations  are  made  and
      reported in Megabits (actually 1,013,760 bits), which is
      55 512-word pages, or 220 128-word blocks.

   -  The CHANGE command resets the access control information
      for  a  given node. It first deletes all existing access
      control  specifications  (privilege  blocks);   then  it
      builds new privilege blocks interactively with the user.
      The  PROTECTION  subcommand  of  the LIST command can be
      used to examine the privilege blocks of nodes.

   -  The CREATE command is used to create a node  for  a  new
      user;   after  the  node has been created, it falls into
      the same  access  control  specificaion  as  the  CHANGE
      command.

   -  The DISABLE command returns  the  user  from  Privileged
      Command  mode  to  normal  use;   this is signalled by a
      return to an asterisk as a prompt character.

   -  The LINK command allows the user to send Datalanguage to
      the Datacomputer directly.  In this mode, prompted by  a
      left  angle bracket, each line typed by the user is sent
      directly to  the  Datacomputer.   It  is  terminated  by
      submission  of  an empty line, whereupon DFTP returns to
      ENABLE  mode,  as  signalled  by  an   exclamation-point
      prompt.

î







                      DFTP Command Summaryî                      ____________________
                              Paths

<node path> ::=   <context>
                | <node list>
                | **
                | <context> **
                | <context> <node list>
                | <context> <node list> > **î                                        _
                | <node list> > **î                              _
<context> ::=  <                (connect context)î               _
                | <             (attach context)î                  _
                | <<<           (top context)î                  ___
<node list> ::=  <node>
                | <node> > <node list>î                         _
<node> ::=       <name>
                | <name> : <password>
                | *

<file path> ::=  <file name>
                | <context> <file name>
                | <node list> > <file name>î                              _
                | <context> <node list> > <file name>î                                        _
<file name> ::=  <file>
                | <file> .
                | <file> . <extension>
                | <file> ; <version>
                | <file> . ; <version>
                | <file> . <extension> ; <version>
<file> ::=       <name> | *
<extension> ::=  <name> | *
<version> ::=    <number> | *


Notes:
     Underscored angle brackets should be included literally.
     Any printing ASCII characters except <, >, ., :,  *,  ?,  ',
          and " may be used in a <name>.
     Any printing ASCII characters (plus space) except >,  .,  ',
          and " may be used in a <password>.
î





                            Commands

ATTACH <node path>

CONNECT <node path> (1)

DELETE <file path> (4) (5)

DIRECTORY <file path> (4) (6)
        TERSE
        VERBOSE

ENABLE

EXPUNGE <node path> (2)

GET (RETRIEVE) <file path> [local file name synonym] (4) (6)

LIST <node path> (3)
        TERSE
        VERBOSE

NO-DATALANGUAGE

PUT (STORE) <file path> [remote file path synonym] (4)

QUIT

REMOVE <node path> (3)

SHOW-DATALANGUAGE

TIME-TRANSFERS

UNDELETE <file path> (4) (7)

UNTIME-TRANSFERS


Notes:
     Required input is indicated by angle brackets.
     Optional input is indicated by square brackets.
     The connect context is the default context for all  commands
          except   ATTACH   and  CONNECT,  which  have  as  their
          respective defaults the  top  context  and  the  attach
          context.
     (1) The default argument is <<.
     (2) The default argument is <.
     (3) The default argument (and trailer) is **.
     (4) The default argument (and trailer) is *.*;*.
     (5) The default version is the lowest undeleted.
     (6) The default version is the highest undeleted.
     (7) The default version is the highest deleted.
î












           Privileged Commands and Their Subargumentsî           __________________________________________


ALLOCATE <node path>
    Megabits: [decimal integer]

CHANGE <node path>
    Add a new privilege? [Y(es)] or [N(o)]
        Allow write? [Y(es)] or [N(o)]
        Restrict via network? [Y(es)] or [N(o)]
            Restrict via local host? [Y(es)] or [N(o)]
                Host number (octal): [octal integer]
                  (if host not local)
            Restrict via user? [Y(es)] or [N(o)]
                Socket number (octal): [octal integer]
                  (if user restricted and host not local)
                User: [user name]
                  (if user restricted and host local)
                  (a directory name if TENEX)
                  (a programmer number if TOPS-10)
        Restrict via password? [Y(es) or N(o)]
            Password: [string]

CREATE <node path>
    (see CHANGE)

LIST
    PROTECTION

LINK
    (A null input line returns the user to command mode.)
î







               Examples Using Privileged Commandsî               __________________________________




;Attach to a node.
; (gain control at site CCA by supplying the proper password)
*ATTACH <<<CCA:

*ENABLE

;Create a user and privileges.
; (the first privilege allows creation and deletion for
;   local user HACKER upon supplying the password "ETAOIN")
; (the second privilege allows creation and deletion for
;   anyone from Harvard (host 11) upon supplying the password "SHRDLU")
; (the third privilege allows anyone read)
!CREATE HACKER
 [OK]
 Add a new privilege? Yes
  Allow control? Yes
  Restrict via network? Yes
   Restrict via local host? Yes
   Restrict via user? Yes
    User: HACKER
  Restrict via password? Yes
   Password: ETAOIN
  [OK]
 Add a new privilege? Yes
  Allow control? Yes
  Restrict via network? Yes
   Restrict via local host? No
    Site: 11
   Restrict via user? No
  Restrict via password? Yes
   Password: SHRDLU
  [OK]
 Add a new privilege? Yes
  Allow control? No
  Restrict via network? No
  Restrict via password? No
  [OK]
 Add a new privilege? No

;List the privileges.
; (in Datacomputer format (passwords are never listed))
!LIST HACKER
!!PROTECTION
    CCA
        HACKER
            ] (1),U=**,H=31,S=12582928,G=CLWRA
            ] (2),U=**,H=9,S=ANY,G=CLWRA
î





            ] (3),U=**,H=ANY,S=ANY,G=LR
î





;Replace the privileges.
; (the first privilege allows creation and deletion for
;   local user HACKER)
; (the second privilege allows anyone read
;   upon supplying the password "WALDO")
; (the "[OK]" indicates that the previous privileges have been deleted)
!CHANGE HACKER
 [OK]
 Add a new privilege? Yes
  Allow control? Yes
  Restrict via network? Yes
   Restrict via local host? Yes
   Restrict via user? Yes
    User: HACKER
  Restrict via password? No
  [OK]
 Add a new privilege? Yes
  Allow control? No
  Restrict via network? No
  Restrict via password? Yes
   Password: WALDO
  [OK]
 Add a new privilege? No

;List the privileges.
!LIST HACKER
!!PROTECTION
    CCA
        HACKER
            ] (1),U=**,H=31,S=12582928,G=CLWRA
            ] (2),U=**,H=ANY,S=ANY,G=LR

;List all information.
; ("MX-U" indicates the maximum allocation in megabits)
!LIST HACKER
!!VERBOSE
    CCA
        HACKER
            ] MX-U=10.00 CHRG=0.00
            ] IN-N=0 IN-F=0
            ] CREA=761101052805

;Change the allocation.
; (decrease the allocation from 10 megabits to 2 megabits)
!ALLOCATE HACKER
 [Megabits:2]
î





;List all information.
!LIST HACKER
!!VERBOSE
    CCA
        HACKER
            ] MX-U=2.00 CHRG=0.00
            ] IN-N=0 IN-F=0
            ] CREA=761101052805
î