FILE DEVICE {FLOPPY}


     By Kelly Roach.  Last revised: 14-Feb-85.
     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.
     NAME becomes the name of your floppy.  It's a good idea to label the outside of your floppies with the same NAME using sticky labels and a soft marker.
     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.
     Typically you will leave AUTOCONFIRMFLG and SLOWFLG as NIL.  For example, doing
        (FLOPPY.FORMAT "MY FLOPPY")
will create a blank floppy named "MY FLOPPY".  Because formatting floppies is a very intensive operation for the IOP, the IOP has less time to look at the mouse and keyboard.  While formatting floppies, the cursor will not track the mouse as well and keystrokes may be lost.  This is normal behaviour and simply means you will not be able to do a lot else while formatting a floppy.
     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) GENERIC IO.  As mentioned in the introduction, all familiar Interlisp input/output operations work with {FLOPPY}.  You can COPYFILE to, COPYFILE from, MAKEFILE to, LOAD from, TEDIT Put to, TEDIT Get from, and OPENFILE on {FLOPPY}.  You can READ and PRINT to any file you have open on {FLOPPY}.  All Interlisp input/output functions are honored just as they are by any other device.
     (3) ARCHIVE TO {FLOPPY}.  As a convenience, two special functions are offered to users to make archival to {FLOPPY} exceptionally easy:
        (FLOPPY.ARCHIVE FILES NAME)
        (FLOPPY.UNARCHIVE HOST/DIRECTORY)
     FLOPPY.ARCHIVE will format a floppy inserted into the floppy drive, giving the floppy the name NAME#1.  FLOPPY.ARCHIVE will then copy each file in FILES to the freshly formatted floppy.  If necessary, FLOPPY.ARCHIVE will overflow onto successive floppies which it will name NAME#2, NAME#3, each time prompting the user to insert a new floppy when needed.  It is very convenient to archive an entire directory or subdirectory using FLOPPY.ARCHIVE in conjunction with Interlisp's DIRECTORY function.  For example,
        (FLOPPY.ARCHIVE (DIRECTORY '{SERVER}<USER>PROJECT>*) 'PROJECT)
would copy all files on {SERVER}<USER>PROJECT> to floppies.
     FLOPPY.UNARCHIVE is the inverse of FLOPPY.ARCHIVE.  FLOPPY.UNARCHIVE will copy all files on the current floppy to directory HOST/DIRECTORY.  Thus,
        (FLOPPY.UNARCHIVE '{SERVER}<USER>PROJECT>)
would copy each file on the current floppy to the directory {SERVER}<USER>PROJECT>.  If there is more than one floppy to unarchive, you should FLOPPY.UNARCHIVE each of them.     
     (4) 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.)
     (5) (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>LISP.SYSOUT '{FLOPPY})
would put the current Interlisp-D LISP.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.
     (6) 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.
     (7) (FLOPPY.NAME NAME) This function resets the NAME put onto a floppy by FLOPPY.FORMAT.  If NAME is NIL, then FLOPPY.NAME reads the NAME put onto a floppy by FLOPPY.FORMAT or FLOPPY.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.
     (8) (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).
     (9) (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.)
     (10) (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.
     (11) (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.
     (12) (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.
     (13) (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).
     (14) CPM.  CPM is a particular kind of operating system that runs on many smaller computers.  Such computers that also have 8" floppy drives, including the Xerox 820-II, can trade information with Xerox 1108 machines via CPM formatted floppies.  There are a number of CPM formats to be found, but single-density single-sided (SDSS) CPM is standard, and SDSS CPM formatted floppies are supported on 1108s.  It is possible to create, read, and write CPM SDSS formatted floppies on 1108 machines.
     CPM formatted floppies are formatted differently than Pilot floppies, so the user should use FLOPPY.MODE to switch to CPM mode when planning to work with CPM floppies.  To create, read, or write CPM formatted floppies, switch to CPM:
         (FLOPPY.MODE 'CPM)
After switching to CPM mode, you may use FLOPPY.FORMAT to create CPM formatted floppies.
     When in CPM mode, the usual input/output operations will work with CPM formatted floppies just as they do with Pilot formatted floppies when you are in PILOT mode.  There are a few limitations however.  CPM filenames have to be short because the CPM format does not allow many characters in filenames.  CPM filenames do not have version numbers.  And CPM files are padded out with blanks to make filelengths a multiple of 128.
     To switch back to ordinairy {FLOPPY} operations, do
         (FLOPPY.MODE 'PILOT).
This will take you out of CPM mode and put you into PILOT mode allowing you to resume formatting, reading, and writing of ordinairy Xerox Pilot floppies.