PFSDoc.tioga
Carl Hauser, November 21, 1989
Michael Plass, January 4, 1990
Nichols, April 4, 1990 3:50 pm PDT
Chauser, September 28, 1990 2:10 pm PDT
Willie-s, February 20, 1992 3:00 pm PST
1. Quick Guide and Latest PFS News
This is preliminary documentation. Obviously, there is much more to be said about PFS.
News
Attachments are implemented for the -ux view. The FSOnPFSImpl.Copy operation, when told to make an attachment will try to do so; should the attachment fail, the bits will be copied. PFSImpl registers an error explainer for PFS.Error (thanks to Doug Wyatt).
The VUX error reporting has been beefed up to include the file name when possible. (mfp) September 19, 1990
While this document doesn't talk about them, two more interesting views are available: the MapViews command registers a view with PFS for looking at files using a version map as a directory and the XNSRemoteFile command registers a view for looking at files on XNS Filing servers. See the documentation in the respective packages. August 29, 1990
Collection of bug fixes: leading '. should be ok in VUX names; enumeration of / now works; case files get collected when the last file they pertain to is deleted; GetInfo returns fileType~tDirectory for unix directories in both VUX and UX; files (hence directories) without version numbers are visible in VUX views, so the cd command could determine if a directory exists before changing to it. August 29, 1990
New interface: PFSExtras with procedures for converting PFS PATHs to Unix names (for views that are unix-based) and for finding out if any part of a path is case-sensitive. Changes to PFSClass to support the above. August 13, 1990
Algorithmic improvements in the VUX view to reduce allocations and processor use. August 13, 1990
The VUX file enumerator now only matches "*" within a single component. Thus, a pattern like "/pcedar/*" only matchs the first-level subdirs of /pcedar instead of the entire subtree. Also, directories and unversioned files are now matched (and unversioned files have the directory flag set, sorry). Neither were matched before. (nichols) April 4, 1990
PFSBackdoorExtras added, allowing clients access to the Unix file descriptor underlying a (PFS) STREAM obtained from the UX or VUX view. Clients are warned that this interface is preliminary, and I do intend to change or replace it in the very near future. January 18, 1990 thanks to Jim Foote for the implementation.
State of the world after standard .pcr files have been loaded
PFS underlies the PCR world. It provides the PFS interface as well as replacement implementations for TFS (used by Tioga) and DFS (used by QBO, SModel, and various other things that wanted to see version numbers) and FS.
PFS initializes its PrefixMap (see Concepts in section 2, below) to have entries for important directories like /, /xrhome, /pcedar2.0, /fonts, /cedarchest7.0, /cedar7.0, and /pseudo.
You can update the PrefixMap with the command tool commands "PrefixMapAdd" and inspect it with "PrefixMapPrint" (abbreviated "pmp" and "pmp", resp.). The syntax of the arguments for PrefixMapAdd is just what you see printed by PrefixMapPrint.
[Wart: prefix map changes are not yet persistent across PCedar startup.]
Operations with Tioga will use PFS (indirectly through TFS). You'll see actual version numbers on files (instead of .~x~ suffices) and files that you openp will have /pcedar2.0/ at the beginning of their banner line instead of /volume/pixel1/pcedar2.0. Open without a suffix uses the suffix list from your profile and works, as does Open MesaFile.Proc.
[Wart: Openp without a suffix doesn't work.]
Gotchas
Beware the "umask" property of your Unix processes (controlled with the umask command of the C-shell) which may reduce the permissions on files created in the UX view from rw-rw-rw- to rw-rw-r-- or even rw-r--r--. (Also note below about tioga copying the previous mode of a file.)
Tioga Save or Store that fails with an uncaught error wedges Viewers. I don't know of any more user behaviors that will provoke this. I now consider any remaining problems Tioga's and Viewer's pending contrary evidence.
Things to know
In the -ux: view Save`ing from tioga creates a new file, and renames the old one with a ~ at the end of its name. I hope the implementation of this is such that you will never again see all the versions of your bytes disappear due to multiple failing Saves.
[Wart: There is no protection from tioga Save'ing into a "release" directory (such as /pcedar2.0). Please don't do that.]
Remember that (unlike FS) PFS doesn't synchronize multiple clients operating on an underlying Unix file. You can create many read and write OpenFiles for a single file. Do so only with trepidation and care.
Incompletenesses/Known bugs/Suspected bugs
The only implemented client properties are "UnixMode", "UnixOwner" and "UnixGroup".
Attachments are only implemented in the -ux view.
This documentation of incompletenesses is incomplete.
PFS File Access Using IO.STREAMs
Most clients of PFS simply want to create a file stream with which to read or write a file. If that's all you want to do then this section contains all you need to know about PFS. Suppose that r is a ROPE containing a file name. If your program needs to read characters from the file named by r (local or global file name, probably with no version part) from a STREAM "s", it should call
s ← PFS.StreamOpen[PFS.PathFromRope[r]];
If your program will provide all new contents for the file named r (it ignores any existing versions of the file and creates a new version), it should call
s ← PFS.StreamOpen[PFS.PathFromRope[r], $create];
If your program is logging output to the file named by r (it updates the file only by adding new characters to the end, and creates a new file of that name if none exists), it should call
s ← PFS.StreamOpen[PFS.PathFromRope[r], $append];
Finally, if your program will both read and write the file named by r (it treats the file as an extendible, random-access sequence of bytes that it updates "in place"), it should call
s ← PFS.StreamOpen[PFS.PathFromRope[r], $write];
It is an unusual program that requires $write mode, while $create mode is used frequently.
If you do not wish to land in the debugger when the file name r is misspelled or otherwise garbled, your calls on PFS.StreamOpen should be protected with a catch phrase something like
! PFS.Error => IF error.group = user THEN {
YourProcedureToShowRopeToUser[error.explanation]; CONTINUE }
The moral of this tale: doing simple things is simple. You don't need to understand the multitude of parameters to StreamOpen and StreamFromOpenFile, since they default correctly for most purposes. You don't need to use any procedure from this interface except PFS.StreamOpen unless you are doing something special. There is only one signal to catch.
Having created a file stream, you may have questions about the semantics of the generic IO operations when applied to this stream: will SetIndex extend the file, and what does Reset do? To answer these questions, read the "File Streams" section below.
It is also possible that you aren't interested in streams at all, but want to do something else like enumerate a directory. Take a look at the PFS interface.
Files created in the UX view always have unix mode rw-rw-rw to allow the language tools to operate on them. Temporary until the language tools use PFS. November 30, 1989 -- but see above about the "x" bit.
VUX view properly ignores malformed names it encounters (rather than either ignoring the entire directory containing them or raising an uncaught error). November 30, 1989
Tioga Save/Store to an unwritable place now fails gracefully (i.e., viewers don't wedge). November 30, 1989
DFSOnPFSImpl now translates errors so that qbo's that try to store in non-existent -ux: directories get error messages instead of uncaught errors. (Remember that the -ux: view does not provide automatic directory creation). November 30, 1989
Delete command: trying to delete a directory in the -ux: view produces an error message instead of an uncaught error. November 30, 1989
The PFS components have once again been repackaged. PFSPackage no longer contains the pieces needed to give you commands, or to support Tioga and DF software. These have been moved to PFSControlPackage. PFS.install has been updated to reflect this, and runs everything needed. This is in anticipation of including PFSPackage among the standard packages available at a very low level in the system. November 30, 1989
Added documentation of the prefix map manipulation commands in the "Installing PFS" section below. November 28, 1989
Changed the stream buffer size to 4K bytes, hoping to improve SModel performance. November 28, 1989
Implemented Copy, Rename and Delete Commands. Took over the List and LS commands. PFSLS is decommissioned. November 28, 1989
Separated the Commands implementation from the rest of the package and provided a new module, PFSPrefixMapInit to initialize the prefix map in a standard way. November 28, 1989
PFSImpl.EnumerateForInfo and EnumerateForNames implement the enumeration bounds. January 18, 1990
Bug fixes to PFSImpl.FileInfo and FSOnPFSImpl.ExpandName. January 18, 1990
PFS is now run by all the standard .pcr files. It is no longer necessary to install it. Deleted instructions for such from this document. January 18, 1990
PFSImpl.FileLookup is now implemented. January 18, 1990
Added some things to PFSPrefixMapInit. (mfp) January 4, 1990
Removed dependency on CommandTool; also fixed some bugs in some of the esoteric options of the LS and Copy commands. (mfp) January 3, 1990
MONITORed several critical sections in the UX and VUX view implementations in hopes of allowing concurrent operations on a single PFS.OpenFile. (I now contend it's better to use multiple OpenFiles). December 21, 1989
Fixed the behavior of opening for "write" access in the UX view so the file is not truncated. December 21, 1989
Fixed the behavior of creating a stream for append access so the stream index is positioned at the end of the file. December 21, 1989
Added semantics for IO.Flush[PFSReadStream] -- forgets any buffered data for the stream. Allows clients to synchronize independent read and write streams on the same file. I don't see a lot of need for ever implementing PFS.StreamFromOpenStream. Yell if you disagree. December 21, 1989
Added finalization for PFS.OpenFiles. December 21, 1989
Added interpretation of directory components "." and ".." to PFS.AbsoluteName. I'm not convinced this is the right place, but it supports the new CommandTool nicely. December 21, 1989
The UX and VUX views support "UnixMode", "UnixOwner" and "UnixGroup" as PFS client properties. December 7, 1989
PFS.Copy preserves the execute bit of the source file's unix mode in the unix mode of the destination file (if both are on Unix systems). December 7, 1989
TFSOnPFSImpl.Create preserves the unix mode of the previous version of a file as the mode of the version being created. December 7, 1989