FILE DEVICE {FLOPPY}

     By Kelly Roach.  Last revised: 24-Jan-84.
     This documentation describes Interlisp-D's file device {FLOPPY},
used to interact with floppy drives on Xerox 1108 machines.
     In general, Interlisp-D can be used to read, write, and otherwise
interact with files on Pilot formatted floppy disks through standard
Interlisp input/output functions.  All familiar operations such as
LOAD, OPENFILE, READ, PRINT, BIN, BOUT, GETFILEINFO, SETFILEINFO,
GETFILEPTR, SETFILEPTR, etc. work with file device {FLOPPY}.  COPYFILE
is commonly used to archive and unarchive files between {FLOPPY} and
other file devices.  Files on {FLOPPY} can be compiled, edited,
hardcopied, etc. just as files may be on all other ordinairy file
devices.  The following functions and cababilities are currently
supported:
     (1) (FLOPPY.FORMAT NAME AUTOCONFIRMFLG SLOWFLG) Used to erase and
establish track information on floppies, especially floppies which are
brand new.  The NAME arg becomes the name of your floppy.  It's a good
idea to label the outside of your floppies with the same NAME.
     AUTOCONFIRMFLG controls questioning the user about destroying
floppies that appear to contain valid information.  If AUTOCONFIRMFLG
is T, the user will not be asked to confirm.
     SLOWFLG determines how thorough a formatting job is to be done on
the floppy you format.  If SLOWFLG is T, FLOPPY.FORMAT will completely
erase your floppy, setting down track information and critical Pilot
records on your floppy.  When SLOWFLG is left NIL, only Pilot records
needed to give your floppy an empty directory are written.  Use
SLOWFLG = T with brand new floppies.
     Your floppies should always be 8" double sided/double density
soft sectored floppy disks.  Floppies are inserted into the floppy
drive face up, the edge of the floppy with two 2" long cover holes
(one hole per side) going in first.  The writeprotect notch will be on
the same edge as and to the left of a cover hole as you look down on
the floppy from above.
     (2) (FLOPPY.SET.NAME NAME) This function resets the NAME put onto
a floppy by FLOPPY.FORMAT.
     (3) (FLOPPY.GET.NAME) This function reads the NAME put onto a
floppy by FLOPPY.FORMAT or FLOPPY.SET.NAME.  In the future, I expect
that {FLOPPY} will be using the name of your floppies to preserve open
{FLOPPY} streams across drive door openings and LOGOUTs.  In the
meantime, don't expect good things to happen to streams that are
writing if you pull the floppies out from under them.
     (4) (FLOPPY.CAN.READP) Predicate tests if there is a floppy in
the floppy drive.  FLOPPY.CAN.READP does not provide any debouncing
(protection against not fully closing the floppy drive door).  You may
wish to use FLOPPY.WAIT.FOR.FLOPPY (see below).
     (5) (FLOPPY.CAN.WRITEP) Predicate tests if there is a floppy in
the floppy drive and the floppy drive can write on this floppy.  (The
floppy drive can only write on floppies whose writeprotect notches are
covered with tape.)
     (6) (FLOPPY.WAIT.FOR.FLOPPY NEWFLG).  When NEWFLG = NIL, this
command waits until there is a floppy in the floppy drive before
returning.  When NEWFLG = T, the function first waits until the
existing floppy in the floppy drive, if any, is removed, then waits
for a floppy to be inserted into the drive before returning.
     (7) SYSOUT to {FLOPPY}.  SYSOUTs may be created on floppies
through Interlisp's SYSOUT function, then later installed on the same
or other Xerox 1108s through the "Installation Utility."  SYSOUTs may
also be taken off of other file devices and be put onto floppies
through the use of function FLOPPY.MODE (see below).  To conduct a
SYSOUT to floppies, simply do
	(SYSOUT '{FLOPPY})
MAKESYS is exactly similar.  Just do (MAKESYS '{FLOPPY})).
     The user is prompted to insert new floppies as they are needed.  It
will generally take 3 to 5 floppies to store a sysout.  To load a
sysout in from floppies, the user may do a 0002 boot with the
Installation Utility floppy in the floppy drive.  Once in the
Installation Utility, it is possible to load a sysout onto logical
volumes with names LISP, LISP2, and LISP3.  (Unfortunately, the
Installation Utility, which is not written in lisp, is very limited in
the choice of filenames, floppy names, and logical volume names you
may use.  Hopefully these restrictions can be lifted sometime in the
future, but I'm neither predicting when or if.)
     (8) (FLOPPY.MODE MODE).  The normal mode of operation for
{FLOPPY} is to be (FLOPPY.MODE 'PILOT).  Two other special modes of
operation for {FLOPPY}, SYSOUT and HUGEPILOT, are available.  The user
can put {FLOPPY} into either of these two latter modes in order to
copy sysouts or huge files off of file servers to floppies or from
floppies to file servers.
     In SYSOUT mode, the user may use COPYFILE to move a sysout off
another file device onto floppies.  To do this, the user must first
set {FLOPPY} into SYSOUT mode, then do the COPYFILE.  For example,
	(FLOPPY.MODE 'SYSOUT)
	(COPYFILE '{PHYLUM}<LISP>CURRENT>FULL.SYSOUT '{FLOPPY})
would put the current Interlisp-D FULL.SYSOUT onto floppies.  While in
SYSOUT mode, the user can copy as many sysouts as he likes onto
floppies.  The Installation Utility is then used to load these sysouts
onto a Xerox 1108.  Similarly, sysouts can be copied off of floppies
onto another file device using COPYFILE when in SYSOUT mode.
	(FLOPPY.MODE 'SYSOUT)
	(COPYFILE '{FLOPPY} '{PHYLUM}<USERNAME>LISP>MY.SYSOUT)
To get back to ordinairy floppy operation, the user types
	(FLOPPY.MODE 'PILOT)
     It is possible to write and read Pilot huge files across multiple
floppies in HUGEPILOT mode (FLOPPY.MODE 'HUGEPILOT).  This mode is
practically identical to SYSOUT mode, with the exception that the user
has control over the names of file and floppies.  (It would make sense
not to have a separate SYSOUT mode if it were not for the friendly
Installation Utility).
     In the future you may expect additional modes CPM, and BLANK.
     (9) Copying floppies.  The ability to copy Pilot floppies is
supported through two functions:
	(FLOPPY.TO.FILE TOFILE)
	(FLOPPY.FROM.FILE FROMFILE)
FLOPPY.TO.FILE copies the contents of the current floppy to a file and
FLOPPY.FROM.FILE is FLOPPY.TO.FILE's inverse.  A typical example of
how these functions might be used:
	(* User inserts floppy to be copied into floppy drive. *)
	(FLOPPY.TO.FILE '{PHYLUM}<ROACH>LISP>FLOPPY.TEMP)
	(* User removes first floppy and inserts a blank floppy. *)
	(FLOPPY.FROM.FILE '{PHYLUM}<ROACH>LISP>FLOPPY.TEMP)
	(* First floppy has been copied. *)
The TOFILE outputted by FLOPPY.TO.FILE will be approximately 2500
pages long and can be placed on a file server or a logical volume
of your machine.  FLOPPY.FROM.FILE can be used more than once if you
would like to make more than one copy.  As an alternative to using
FLOPPY.SCAVENGE (described below), the TOFILE produced by
FLOPPY.TO.FILE can be usefully editted to salvage the contents of a
floppy that has gone sour.
     (10) (FLOPPY.FREE.PAGES).  Returns number of unallocated free pages
on the current floppy.  Pilot floppy files are contiguously represented on
floppy disks. If you are going to use your floppy interactively (you
are not just doing a simple series of COPYFILEs after a FLOPPY.FORMAT),
I suggest you don't cram your floppy to capacity.  Try to keep such a
floppy <75% full.  (Two miscellaneous functions to get an idea of how
space is being allocated on a floppy: FLOPPY.LENGTHS and
FLOPPY.ALLOCATIONS.)
     (11) (FLOPPY.COMPACT).  If your floppy is stable--there are no
extant {FLOPPY} streams--FLOPPY.COMPACT may be used to compact your
floppy, moving files towards the front of your floppy so that all free
blocks on your floppy can be combined into one free block.  (A
compactor that works well when there are open {FLOPPY} streams is in
the pipeline.)
     (12) (FLOPPY.SCAVENGE).  This function attempts to repair a floppy
whose critical records have become confused.  If you accidentally
delete files on {FLOPPY} you shouldn't have deleted, FLOPPY.SCAVENGE
will get them back for you (provided you don't wait till after they
have been overwritten by new files).
     (13) (FLOPPY.RESTART).  A last resort way to try to restart
{FLOPPY} if you think {FLOPPY} is smashed.  FLOPPY.RESTART will
recreate all of {FLOPPY}'s internal globals.  Be warned that any
outstanding {FLOPPY} streams will be lost if you do (FLOPPY.RESTART).
Try switching floppies or opening then closing the floppy drive door
first.