filefns documentation

[LEWIS at BBN-TENEXD]

Release 3 of TOPS20 contains a major change in the way one "talks"
about directories.  First, what is thought of on TENEX as a
USERNAME/NUMBER has been split into two catagories:

  1.  A USERNAME is something you login or attach to (and that is
      all!).  A USERNUMBER isn't good for much (except when used in
      conjunction with certain system tables) and can only be
      guarenteed to remain consistent with a particular USERNAME
      during a system's up-time (i.e.  they may change when a
      system is brought up).  A USERNAME has the same format
      (essentially) as a TENEX USERNAME (i.e., a string of
      characters not enclosed in <>'s).

  2.  There are two new entities called DIRECTORYNAME and
      DIRECTORYNUMBER.  These are essentially what one thinks of as
      USERNAME/NUMBER on TENEX and are what one uses to talk about
      directories and files.  A DIRECTORYNAME has the format
      "STRUCTURE:<DIRECTORYNAME>" where STRUCTURE:  can be thought
      of as a "device" in TENEX mode, but is a way of partitioning
      the disk (so there can be mountable structures that don't
      clutter up the disk space most of the time).  When you ask
      for a DIRECTORYNAME from TOPS20 you'll always get back one of
      these -- including the STRUCTURE and <>'s (e.g.
      PS:<TEITELMAN>).  A DIRECTORYNUMBER should be thought of as
      very temporary (akin to a JFN) and remains consistent with a
      particular DIRECTORYNAME only for the lifetime of the program
      that got the DIRECTORYNUMBER and only for that program (i.e.
      you can't pass DIRECTORYNUMBERs between programs).
 
      Both DIRECTORYNUMBER and USERNUMBER are full 36 bit quantites
      and are never the same number.

Obviously, this change has a major impact on a single TENEX/TOPS20
Interlisp-10.  The following new functions have been added (and
changes to the use of some current functions) to "hide" the
differences between between the two systems.  To help keep things
straight whenever a current system function (and its current use) is
referred to it will be preceded by the string "old" (e.g.  the
current USERNUMBER will appear as oldUSERNUMBER in the text).

Essentially, the change is to is rename the functions oldUSERNAME and
oldUSERNUMBER to DIRECTORYNAME and DIRECTORYNUMBER respectively
(details of all new functions will appear below).  These are the
functions to use when dealing with the file system.  The functions
USERNAME and USERNUMBER should then only be used to identify a user
(not a directory).  To alleviate calls to DIRECTORYNUMBER (i.e.
oldUSERNUMBER) and USERNUMBER which become expensive (because of the
boxing of the number) on TOPS20 there are two new functions:
DIRECTORYNAMEP and USERNAMEP which determine if what they are given
is legitimate directory or user name -- this was the major use of
oldUSERNUMBER used in conjunction with oldUSERNAME.  Also,
DIRECTORYNAME and USERNAME have been expanded to take directory and
user names (with escapes) as opposed to the oldUSERNAME which only
took T, NIL, or a number.  And finally, there is a new system
function CONNECTDIR which should be used for connecting to another
directory inside of Interlisp-10 (connecting to a directory on TOPS20
is radically different implementation wise).

The documentation for the functions follows.  The parameter names
DIRNAME and USERNAME can either be a litatom or string.


DIRECTORYNAME[DIRNAME;STRPTR]

  -  Returns a "full directory name" for DIRNAME.  If DIRNAME=NIL
     then return the login directory.  If DIRNAME=T then return the
     connected directory.  If DIRNAME is a string or litatom with an
     $ (escape) on the end then name completion will be attempted;
     if unsuccessful NIL will be returned.  DIRNAME can also be a
     number, in which case if DIRNAME is a valid directory number
     return its corresponding directory name.  Normally the
     directory name is returned as a string.  If STRPTR is a string
     pointer then it is smashed with the new string pointer.  If
     STRPTR=T then the directory name is returned as an atom.

DIRECTORYNAMEP[DIRNAME]

  -  Returns T if DIRNAME is a legitimate directory name.  If
     DIRNAME ends with an $ (escape) then name completion is
     attempted and T returned if successful, otherwise NIL.  This
     function is provided for efficency so the DIRECTORYNAME string
     doesn't have to be created.  [Footnote:  if DIRNAME=T or NIL
     then DIRECTORYNAMEP will return T since they are valid DIRNAMEs
     to DIRECTORYNAME.]

DIRECTORYNUMBER[DIRNAME]

  -  Returns the directory number for DIRNAME.  DIRNAME may end with
     an $ (escape) in which case name completition is attempted.  if
     DIRNAME=NIL then login directory number is returned.  If
     DIRNAME=T then the connected directory is returned.

USERNAME[USERNAME;STRPTR]

  -  Returns a user name for USERNAME.  If USERNAME=NIL then return
     the login user.  If USERNAME is a string or litatom with an $
     (escape) on the end then name completion will be attempted; if
     unsuccessful NIL will be returned.  USERNAME can also be a
     number, in which case if USERNAME is a user number return its
     user name.  Normally the user name is returned as a string.  If
     STRPTR is a string pointer then it is smashed with the new
     string pointer.  If STRPTR=T then the user name is returned as
     an atom.  [Footnote:  USERNAME=T is meaningless (by the old
     interpretation, this would mean something like "connected login
     user") and will simply return NIL.]

USERNAMEP[USERNAME]

  -  Returns T if USERNAME is a legitimate user name.  If USERNAME
     ends with an $ (escape) then name completion is attempted and T
     returned if successful, otherwise NIL.  [Footnote:  If
     USERNAME=NIL then T is returned.]

USERNUMBER[USERNAME]

  -  Returns the user number for USERNAME.  USERNAME may end with an
     $ (escape) in which case name completition is attempted.  if
     USERNAME=NIL then login user number is returned.

CONNECTDIR[DIRNAME;PASSWORD;-]

  -  Tries to connect to DIRNAME and if successful returns a full
     directory name (as an atom) for DIRNAME otherwise it returns
     NIL.  If PASSWORD (a string or litatom) is supplied it is used
     to aid in the connecting process.
 
     [Footnote:  The third parameter FLG is only used on TOPS20 and
     is used to specify different ways to "connect".  If FLG is the
     atom NIL or CONNECT then the normal "connection" is made.  If
     FLG is the atom T or ACCESS then the normal connection is not
     made but files in that directory will be accessible to you.]

Interactions with PACKFILENAME, UNPACKFILENAME, and FILENAMEFIELD:

Since STRUCTURE looks exactly like DEVICE, UNPACKFILENAME works fine
as is.  PACKFILENAME on TOPS20 would have to check for a structure
being on the "front" of a directory name.  If it is there and there
is no DEVICE specified then PACKFILENAME works essentially like it
does now.  If a device is specified separately and there is one in
the directory name, whichever occurs first is the one used (this is
similiar to the way BODY is used).  STRUCTURE is also a synonym for
DEVICE.  PACKFILENAME and FILENAMEFIELD would accept either on both
TENEX and TOPS20.  UNPACKFILENAME will return with either the field
being called DEVICE or STRUCTURE based on which type of system
Interlisp-10 is running on.

Impact on the system and user code:

In system code all calls to USERNUMBER should be looked at to
determine if it was being used in conjunction with USERNAME to get a
legitimate and complete USERNAME.  If so, these should be
consolidated to one call to DIRECTORYNAME.  All calls to USERNAME
which exist after the previous alteration should just be renamed to
DIRECTORYNAME Since the parameters are compatable, this should be
easy.  Some files in LISPUSERS will also certainly be effected
(especially EXEC), but the changes are similiar.

Old user code running on TENEX should notice no difference since
USERNAME and USERNUMBER work the same for them.  They should however
be advised of the new directory functions and to use them instead.
Old user code running on TOPS20 will have to be modified similiarly
to the system code.