File Access from a Cedar 5 Workstation
CEDAR 5.0
File Access from a Cedar 5 Workstation
The FS, FSBackdoor and FSExtras interfaces
Release as	[Indigo]<PreCedar>Documentation>FSDoc.Tioga
Written by	M. D. Schroeder
Last edited	November 16, 1983 10:05 am.



XEROX			Xerox Corporation
				Palo Alto Research Center
				3333 Coyote Hill Road
				Palo Alto, California 94304
				
For Internal Xerox Use Only
1. Introduction
Purpose of document
This document describes the standard facilities available for file access from a Cedar 5 workstation.  These facilities are available through the interfaces FS, FSBackdoor, and FSExtras.  FS contains facilities of interest to all users.  FSBackdoor contains facilities of interest to experts.  FSExtras contains items that will be added to FS or FSBackdoor the next time they can be recompiled.  In cases where the descriptions of functions in the interface files differ from the descriptions in this document, this document should be viewed as the truth.  All interfaces are available through /Indigo/PreCedar/Top/FS.df.  The implementation of FS is contained in the Cedar 5 boot file.   
Location of interfaces
All interfaces are available through /Indigo/PreCedar/Top/FS.df.  The implementation of FS is contained in the Cedar 5 boot file.
Overview of Functions
FS is a file system for use on a Cedar workstation.  It provides access both to remote file servers and to the local disk.  Remote files accessible from FS must reside on a file server that supports the FTP protocol, in particular IFS's and Alpine servers.  These file servers may be accessed from many Cedar instances on different workstations at the same time.  Local files are accessed through an abstraction called the local server.  The local server is the set of logical volumes on the local disk of a Cedar instance.  One of these logical volumes may be designated the system volume.  FS provides a directory for each volume, and a cache for remote files on the system volume.
FS allows clients to provide the implementation of open files.  Open files obtained from client packages may be presented to FS procedures that operate on open files.  Client-provided open files may be local or remote, or many not be disk files at all.  Direct, page-at-a-time access to Alpine servers is provided through this mechanism.
FS also contains facilities for creating IO.STREAM's on files, for binding local names to remote files, for finding the version of a file that was created at a particular time, and for limiting the number of extant versions of local files.
History
FS is a successor to the Cedar Interim File System (CIFS) that was developed by Dave Gifford with help from Larry Stewart.  The design of FS benefited from advice offered by Andrew Birrell, Mark Brown, Butler Lampson, Roy Levin, Roger Needham, Eric Schmidt, Larry Stewart, Paul Rovner, and Ed Taft.  The main designer and implementor of FS was Michael Schroeder.
2. Everything you really wanted to know about file access
Simple file stream creation
Most clients of FS 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 FS.  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 _ FS.StreamOpen[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 _ FS.StreamOpen[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 _ FS.StreamOpen[r, $append];
Finally, if your program will both read and write the file named by r (it treats the file as an extendable, random-access sequence of bytes that it updates "in place"), it should call
s _ FS.StreamOpen[r, $write];
It is an unusual program that requires $write mode, while $create mode is used frequently.  The last three forms only work for local files.
Simple error handling
If you do not wish to land in the debugger when the file name r is misspelled or otherwise garbled, your calls on FS.StreamOpen should be protected with a catch phrase something like
! FS.Error => IF error.group = user
THEN { YourProcedureToShowRopeToUser[error.explanation]; CONTINUE }
The moral
The moral of this tale: doing simple things is simple.  You do not need to understand the multitude of parameters to FS.StreamOpen and FS.StreamFromOpenFile, since they default correctly for most purposes.  You do not need to use any procedure from this interface except FS.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 IO.SetIndex extend the file, and what does IO.Reset do?  To answer these questions, read the "File Streams" section below.
It is also possible that you are not interested in streams at all, but want to do something else like enumerate a directory.  Read on, the answer is here somewhere.
3. Error handling
FS.Error
Client's of FS should only have to catch the single ERROR FS.Error.  In particular, errors from the File package and the STP package are mapped into FS.Error's.  Other packages that hand out FS.OpenFile's (see section 10) are expected to raise FS.Error. 
FS.Error: ERROR [error: FS.ErrorDesc];
FS.ErrorDesc: TYPE = RECORD [group: FS.ErrorGroup, code: ATOM, explanation: ROPE]
_ [ok, NIL, NIL];
FS.ErrorGroup: TYPE = {
ok, -- initial group for a new FS.ErrorDesc
bug, -- caused by an internal bug
environment, -- something's wrong in the environment; human intervention required
lock, -- conflict over locks
client, -- illegal operation, probably due to bug in client program
user -- illegal operation, probably due to user action
};
FS error codes are partitioned into five groups:  bugs, environment errors, lock conflicts, client errors,  and user errors.  A bug usually indicates that something unexpected has gone wrong inside the implementation of FS or lower packages.  An environment error means that something in the external environment has changed that requires human intervention.  A lock conflict means that some other client has the locks that this client needs to get its job done.  A client error is an attempted illegal operation that probably is caused by a bug in a client program.  A user error is an attempted illegal operation that probably is caused by a human user's actions.  The distinction between the last two groups is somewhat arbitrary.
An error description reports the group, as well as a specific code ATOM indicating exactly what went wrong.  In the descriptions of procedures that follow, all codes from the error groups "client" and "user" that can be raised are specifically listed.  Errors in the other groups should be expected as appropriate.  The "explanation" is intended to be a description of the error suitable for human consumption; it frequently contains the name of the file being operated upon.
Catching all FS.Error's with error.group = user and reporting the error.explanation to the human user is usually sufficient to deal with file names that are mistyped by humans or that do not correspond to existing files.
The FS implementation is careful never to raise FS.Error while locks are held.  Any FS procedure can be called from a catch phrase for FS.Error.
Error code ATOM's
Error codes are ATOM's so that packages implementing FS.OpenFile's via FSBackdoor.CreateProcsOpenFile can extend the set of codes.  Following is a complete list of the codes generated by the FS implementation.  The list is partitioned by the FS.ErrorGroup.
Bugs
$inconsistent -- a local volume's permanent data structures are inconsistent
$software -- label check encountered while reading or writing pages on a local volume
$badFP -- File.FP from directory/cache doesn't correspond to a file on a local volume
Environment Errors
$wentOffline -- local volume is no longer accessible
$hardware -- hard error while reading or writing pages on a local volume
$volumeFull -- no more free pages on a local volume
$fragmented -- file required too many non-contiguous areas on a local volume
$noMoreVersions -- next version number would be too big
$serverInaccessible -- couldn't get a response from a remote server
$connectionRejected -- remote server rejected the connection attempt
$connectionTimedOut -- connection to a remote server timed out
$badCredentials -- remote server rejected the user name or password
$accessDenied -- remote server access controls succeeded
$quotaExceeded -- disk space quota on remote server exceeded
$invalidPropertyPage -- unrecognized property page format for a file on a local volume
$badBTree -- directory/cache BTree is malformed and cannot be opened
Lock Errors
$lockConflict -- required lock cannot be obtained
$fileBusy -- remote file currently being used in an incompatible way
Client Errors
$noCache -- couldn't operate on global file because there is no system volume and no cache
$wrongLock -- operation requires a write lock and only a read lock is held
$globalWriteLock -- tried to open a GName with a write lock
$zeroKeep -- keep of 0 was specified
$badByteCount -- tried to set a byte count that is beyond end of file or negative
$unknownPage -- tried to read or write a page that is beyond end of the file
$invalidOpenFile -- FS.OpenFile is closed, is FS.nullOpenFile, or is an unrecognized TYPE
$notImplemented -- called a procedure that is not provided for this FS.OpenFile
User Errors
$nonCedarVolume -- named volume is not a cedar volume
$unknownServer -- couldn't get a network address for the named server
$unknownVolume -- named local volume cannot be found
$unknownFile -- FName not in the implied directory
$unknownCreatedTime -- no version of the given FName had the specified created-time 
$illegalName -- file name, directory name or pattern has illegal syntax or characters, or is too long, 
$patternNotAllowed -- name presented contained a "*" and procedure doesn't allow patterns
$versionSpecified -- tried to create an FName with a specific version
$globalCreation -- tried to create a GName
$badWorkingDir -- default working directory specified is global or has no volume part
$noKeeps -- tried to set the keep on a server that does not implement keeps
$cantUpdateTiogaFile -- tried open a file stream to write on a .tioga file
4. Naming files
Name structure
Names for FS files are called "FNames".  An FName consists of (in order) a server, a root directory, zero or more subdirectories, a simple name, and a version.  An FName may not exceed 120 characters excluding the version part.  The version part will always fit in 6 characters, so the maximum space an FName can occupy is 126 characters.  Any name discovered that contains more than 120 characters before the version part will cause FS.Error[user, $illegalName] to be raised.
FS.maxFNameLength: CARDINAL = 126;
Both FTP bracket syntax and CIFS slash syntax for FNames are accepted, although bracket syntax is used internally, in all FNames returned from FS procedures, and in FS.Error explanations.  The following constructs are equivalent:
[server]<rootDirectory>subDirectory>simpleName!version
/server/rootDirectory/subDirectory/simpleName!version
The structural characters that delimit the server part of an FName are "[" and "]", or "/".  Non-structural characters allowed in the server part are all alphameric characters plus ".", "$", "-", "+" and "#".  The structural characters allowed in the rest of an FName are "<" and ">", or "/".  The non-structural characters are the same as for the server part with the exception of "#".  The additional structural character "!" is used as the version part prefix.  The rest of the version part can be a number in the range [1 .. 65534], or one of the letters "L" or "H".  Case is not significant in FNames.
An empty server part means the local server.  Otherwise the server part is presumed to name a remote file server.
The names of files on remote servers are called "GNames", for global names.  The detailed requirements on the structure of a GName are defined by the type of server named.  The most common remote servers (IFS and Alpine) require the presence of a root directory part and include version parts in all file names.
The names of files on the local server are called "LNames", for local names.  In an LName, the root directory part is the name of a volume; an empty root directory part refers to the "system" volume (the one from which Cedar was booted).  All LNames have version parts.  For example, the following are complete LNames:
[]<>FS.mesa!3
///FS.mesa!3
[]<Debugger>Temp>DebugTool.bcd!12
//Debugger/Temp/DebugTool.bcd!12
The working directory mechanism described below eliminates the need for the server and root directory part on most LNames presented to FS procedures.
Fine points:
1. Certain remote servers, e.g., Gateways and Grapevine servers, do not have a directory structure or versions.  Such servers require GNames of the form "[server]simpleName" or the form "/server/simpleName".
2. The root directory in an LName may also be identified by its e VolumeID.  The syntax for the root directory part in this case is "#" followed by a 20-digit hexadecimal string.
3. The Cedar debugger interface makes a remote debuggee's disk available to a debugger as if its disks were attached to the debugger's machine.  This is essentially transparent to FS; volumes of the debuggee's disk will appear to be part of the local server, i.e., files will be LNames, not GNames.  This is entirely different from the situation in which the remote machine is operating normally and is running, say, an FTP server.
Version numbers
The local server and most remote servers include version numbers in file names.  Version numbers allow for multiple instances of a file to exist at one time.  FS enforces the policy that the version on any newly created file is one larger than the largest existing version, the so-called "next" or !N version.  It is not possible to create any other version with FS.  When accessing an existing file the version part of an FName may be a number, may be a variable, or may be omitted.  The variables allowed are !L, meaning the lowest existing version number, and !H, meaning the highest existing version number.  When omitted, the version part defaults to !L or !H, depending on the operation being performed.
Working directory
An FName that does not start with a server part is called a partial name and will be interpreted relative to a working directory.  The working directory may be specified as the argument named "wDir" to FS procedures, or may be defaulted.
To expand the arguments "name" and "wDir" of an FS procedure into a full FName, FS checks the first character of "name".  If it is "[" ("/") then "name" is the full FName.  If not then FS looks for a working directory name in three places in order:
1) the "wDir" argument;
2) the value of the $WorkingDirectory property of the process property list;
3) the default working directory (set with FS.SetDefaultWDir).
The first ROPE found whose length is not 0 is preprended to "name" to form the full FName.  A working directory obtained from 1 or 2 can be local or global.  If it does not end with "]" or ">" ("/") then a ">" ("/") is appended.  The default working directory must be local.
The default working directory can be set with the procedure:
FS.SetDefaultWDir: PROC [dir: ROPE _ NIL];
If Rope.Length[dir] is 0 then the default working directory is set to "[]<>", which also is the initial value for the default working directory.  If "dir" does not end with ">" ("/") then a ">" ("/") is appended.
Client errors: none
User errors:  $illegalName, $patternNotAllowed, $badWorkingDir
The default working directory can be read with the procedure:
FS.GetDefaultWDir: PROC RETURNS [ROPE];
Client errors: none
User errors:  none
Parsing and constructing FNames
FS contains utilities for parsing and constructing FNames.
FS.Position: TYPE = RECORD [start, length: CARDINAL];
FS.ComponentPositions: TYPE = RECORD [server, dir, subDirs, base, ext, ver: FS.Position]
FS.ExpandName: PROC[name: ROPE, wDir: ROPE _ NIL] RETURNS [fullFName: ROPE, cp: FS.ComponentPositions, dirOmitted: BOOLEAN];
The full FName determined by "name" and "wDir" is converted to brackets syntax and syntax checked.  The converted FName is returned as "fullFName".  The positions of the components in "fullFName" are returned in "components", expressed as starting index and length.  No check is made to see if a file named "fullFName" actually exists.  A variable or missing version part is not bound.
The "server" is the server part without surrounding "[ ... ]".  The "dir" is the root directory or volume part without the surounding "< ... >".  The "subDirs" is the all the subdirectory part without without surounding "> ... >" but including interior ">"s.  The "base" is the portion of the simple name up to but not including the final "."  The "ext" is the portion of the simple name following the final "."  If there are no "."s in the simple name then it is all considered to be "base".  The "ver" is everything after the "!".
If the "fullFName" is a GName of the form "[server]simpleName", i.e., it has no directory part (not just the empty directory part "<>"), then "dirOmitted" returns TRUE; otherwise it returns FALSE.
If "fullFName" is an LName then "components.server.length" will be 0; if "fullFName" is an GName then "components.server.length" will be greater than 0.
For a Position "p" from a ComponentPositions "c", Rope.Substr[fullFName, c.p.start, c.p.length] is a ROPE containing that component.
An empty or missing component is reported as [start,0], where "start" is the index where the component would have appeared if present.
Client errors:  none
User errors:  $illegalName, $patternNotAllowed
FS.ComponentRopes: TYPE = RECORD [server, dir, subDirs, base, ext, ver: ROPE _ NIL];
FS.ConstructFName: PROC [cr: FS.ComponentRopes, omitDir: BOOLEAN _ FALSE] RETURNS [ROPE];
Constructs an FName from the component ROPE's in "cr".  No syntax checking is done.  The only structural character that should appear in components is ">" within the subdirectory component.  The construction algorithm is as follows:
name _ Rope.Cat[ "[", cr.server, "]" ];
IF NOT omitDir THEN name _ Rope.Cat[ name, "<", cr.dir, ">" ];
IF Rope.Length[cr.subDirs] > 0 THEN name _ Rope.Cat[ name, cr.subDirs, ">" ];
name _ Rope.Cat[ name, cr.base ];
IF Rope.Length[cr.ext] > 0 THEN name _ Rope.Cat[ name, ".", cr.ext ];
IF Rope.Length[cr.ver] > 0 THEN name _ Rope.Cat[ name, "!", cr.ver ];
RETURN [name];
Client errors:  none
User errors:  none
5. File properties
Properties supported
File properties provided by FS are page count, byte count, created-time, and keep.  The page count is the number of pages allocated to the file.  The byte count is the number of meaningful bytes in a file; the byte count is kept up-to-date by explicit client calls on FS procedures.  The created-time is the date and time when the contents of the file were created (or changed).  The keep specifies how many versions of a file to keep around.
Converting page counts to byte or word counts
Procedures are provided for converting between pages counts and byte counts or word counts:
FS.WordsForPages: PROC[pages: INT] RETURNS [words: INT];
FS.BytesForPages: PROC[pages: INT] RETURNS [bytes: INT];
FS.PagesForWords: PROC[words: INT] RETURNS [pages: INT];
FS.PagesForBytes: PROC[bytes: INT] RETURNS [pages: INT];
Keeps
A property for each LName is the "keep", a CARDINAL that specifies the number of versions of an LName that should be kept around.  Whenever an LName is created, its "keep" is inherited from the existing !H version or set from an argument to the procedure doing the creation.  The keep of the existing !H version can be changed with FS.SetKeep.
Keep processing occurs when creating a new version of an LName.  In this case, FS will enumerate existing version in decreasing order from !H.  After "keep - 1" versions are encountered in this enumeration, additional versions will be deleted if not open.  Thus, the keep is the steady state count of versions to be retained.  The local volume file of a deleted version will be reused as the disk file for the new version being created.  For example, if the only existing version of a file is named Example.bcd!4, it has a keep of 1, and no client has it open, then FS.Create[Example.bcd] will cause Example.bcd!4 to be deleted and its disk file to be reused for Example.bcd!5.
Calling FS.SetKeep will have the side effect of deleting files that are obsolete relative to the new keep, even when the keep is not changed.
Note that setting a keep to LAST[CARDINAL] will result in all versions being kept, since there can never be that many versions.  A keep of 0 is illegal.
No remote server implements keeps right now.
6. Name binding
Naming with version variables
For certain FS procedures the identification of which global file to operate on can include the version variables !L or !H, or can be defaulted to the variables !L or !H (depending on the operation).  Binding a version variable to a particular version would be straightforward if the remote server were always accessible and if the client were always willing to incur the cost of accessing it.  In some circumstances, however, a client may wish to complete the binding based on the possibly incomplete information available from the cache.  The "remoteCheck" argument to FS.FileInfo, FS.Open and FS.Copy allows the client to control the scope of the version search.  (FS.Rename and FS.Delete do not include a "remoteCheck" argument because renaming and deletion occur synchronously on the remote server, so there is no option.)  The "remoteCheck" argument is evaluated only when a GName is specified.  When "remoteCheck" is TRUE then FS binds a version variable by searching the versions on the remote server.  The operation fails if the remote server is inaccessible.  When "remoteCheck" is FALSE then FS binds the version variable by searching the versions in the cache; only if no cached version is found is the remote server interrogated.
Naming with created-times
All of the FS procedures that accept an FName argument also include a "wantedCreatedTime" argument.  This time provides an alternative way to name a file.  If  "wantedCreatedTime" is not equal to BasicTime.nullGMT, then the file to be operated upon is determined by a search for the version with the specified created-time.  Any version part included in the name is treated as a hint.  The created-time of a file is treated as a unique identifier of the content.  If a version of a global file with the wanted created-time is found in the cache, then FS will not bother to check with the remote server (even if "remoteCheck" is TRUE) to see if the same created-time to version binding exists there.
Attachments
FS includes facilities for attaching an LName to a GName and created-time.  An attachment is a name binding.  Attachment is a way to give an LName to a global file, and is useful as a cheap way to copy global files into local files.  "BringOver" and "SModel" are the primary clients of the attachment mechanism.
Attachments are created using certain modes of FS.Copy.  For most FS procedures, an attached LName behaves as though the global file were in fact copied into the local file when FS.Copy was invoked.  There are four exceptions.  First, the various procedures for obtaining information about files inform the client when an LName is attached and provide the GName of the attachment.  Second, opening an attached LName requires opening the global file; if the global file is not in the cache and the remote server is down or the file has been deleted on the remote server, then the open will fail.  Third, for a "read" open both the local and global names are read locked.  Fourth, for a "write" open, the attachment is broken and the contents of the global file are copied into a local file; the local file assumes the LName and the GName is forgotten.
7. Credentials and locks
Name and password for server access
For access to remote servers FS uses the credentials obtained from the UserCredentials interface.  If these do not work then FS.Error[environment, $badCredentials] is raised.  FS currently has no facilities for setting or using secondary credentials.  Thus, access to files in password protected directories on servers is not possible.
Locking
There are two types of locks that can be set on files: "read" and "write".  These locks are local to a Cedar instance.  Whenever the required lock cannot be obtained, FS raises FS.Error[lock, $lockConflict].
FS.Lock: TYPE = {read, write};
A "read" lock provides shared access to a file.  Holders of "read" locks for a file may only read its data or properties.  A "read" lock can be set anytime no "write" lock for that name is held.  Thus, multiple "read" locks may be held.  While a "read" lock is held no other client can delete the file or change its name.
A "write" lock provides exclusive access to a file.  The holder of a "write" lock may alter the file's contents and properties.  An implicit "write" lock is required to rename or delete a file.  While a "write" lock is held no other client can open the file, delete it, or alter its name.  A "write" lock can be set only when no other locks are held.
8. Getting information about files
Info on a single file
FS.FileInfo: PROC [name: ROPE, wantedCreatedTime: BasicTime.GMT _ BasicTime.nullGMT, remoteCheck: BOOLEAN _ TRUE, wDir: ROPE _ NIL] RETURNS [fullFName, attachedTo: ROPE, keep: CARDINAL, bytes: INT, created: BasicTime.GMT];
Returns information about the file specified by "name", "wantedCreatedTime", and "wDir".  A missing version part defaults to !H.  If "wantedCreatedTime" is not BasicTime.nullGMT then any version number in "name" is treated as a hint; the information returned is for the file with the wanted created-time, found by searching all versions of the named file as necessary.
If the matching file is a local file not attached to a global file, then the full FName including version part is returned as "fullFName". The keep, byte count, and created-time also are returned.  "attachedTo" will be NIL and the "remoteCheck" argument is ignored.
If the matching file is a local file that is attached to a global file, then the full FName of the local file including version part is returned as "fullFName".  The keep of the local file is returned.  The full FName of the attached global file is returned as "attachedTo".  The byte count and created-time of the global file also are returned.  In this case, if the "remoteCheck" argument is FALSE then the byte count will be returned as -1, thus eliminating the need to open the global file from the cache or check with the remote server to determine this information.  If "remoteCheck"  is TRUE then the byte count of the global file is determined from the cache or remote server as necessary and returned.  Any FS.Error's encountered when trying to determine the byte count of an attachment are suppressed and "bytes" is reported as -1.  Whenever a valid byte count for an attachment is reported then the version part in the "attachedTo" name is the true version number that corresponds to the created-time for the attachment; otherwise this version part will be whatever was recorded by FS.Copy when the attachment was made.
If the matching file is a global file its full FName including version part is returned as "fullFName".  The keep returns as 0.   The byte count and created-time of the global file are returned.  "attachedTo" returns as NIL.  If "name" ends with a version variable and no wanted created-time is specified, then "remoteCheck" controls access to the remote server.  If "remoteCheck" is TRUE, then the remote server is accessed for the file information.  If "remoteCheck" is FALSE, then the version variable is bound relative to the set of versions in the cache; the remote server is interrogated only if no version appears in the cache.
Client errors:  none
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $unknownFile, $unknownCreatedTime, $illegalName, $patternNotAllowed
Enumeration facilities
Enumerations are specified with a "pattern" argument, which is an FName in which the character "*", meaning "match anything", may appear zero or more times.  "*" may not appear in the server part, or in the root directory of an LName.  The presence or absence of a server part in "pattern" controls the use of working directories as usual.  The version part of a "pattern" may be !H, !L, !*, or ! followed by digits; or may be omitted (defaults to !*).  It cannot contain a mixture of "*" and digits.  The order of the enumeration may be different for different sorts of servers.  For the local server and IFS's, the enumeration is in lexical order of LNames expressed in bracket syntax (lower cases letters are mapped to upper case) but without the version part, and then in numeric order by version number.
Monitor locks are not held during an enumeration.  Thus, the client may call FS.Delete from an FS.InfoProc or an FS.NameProc.  Fine point: deleting or storing (by FS.Copy) ahead of the current position in a remote enumeration can produce unexpected results; the change may not be reflected in the enumeration.
FS.InfoProc: TYPE = PROC [fullFName, attachedTo: ROPE, created: BasicTime.GMT, bytes: INT, keep: CARDINAL] RETURNS [continue: BOOLEAN];
FS.EnumerateForInfo: PROC [pattern: ROPE, proc: FS.InfoProc, wDir: ROPE _ NIL];
"proc" is called for each FName selected by the pattern.  Returning "continue" as FALSE stops the enumeration.  "fullFName" reports the complete FName including version part of each name encountered.  The keep, byte length, and created date of a local or global file are reported.  When an LName attached to a GName is encountered, "fullFName" is the LName and "attachedTo" is the GName.  In this case, the "keep" reported is that of the LName but the "bytes" and "created" are that of the GName.  If any FS.Error's are encountered when trying to determine the byte count of an attachment, they are suppressed and "bytes" is reported as -1.  Whenever a valid byte count for an attachment is reported then the version part in an "attachedTo" name is the true version number that corresponds to the created-time for the attachment; otherwise this version part will be whatever was recorded by FS.Copy when the attachment was made.
Client errors:  none
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $illegalName
FS.NameProc: TYPE = PROC [fullFName: ROPE] RETURNS [continue: BOOLEAN];
FS.EnumerateForNames: PROC [pattern: ROPE, proc: FS.NameProc, wDir: ROPE _ NIL];
Because only names are provided to "proc", this enumeration can go faster than the previous one, especially for GNames.
Client errors:  none
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $illegalName
9. Opening files
Introduction
An FS.OpenFile may be presented to other procedures to get access to the file's contents and properties.  All global files opened using the FS procedures defined below are accessed via the FTP protocol and the cache.
FS.OpenFile: TYPE = RECORD [REF];
FS.nullOpenFile: FS.OpenFile = [NIL];
Other packages can include procedures that return FS.OpenFile's.  In such cases, the arguments to the opening procedures and the detailed semantics of operations on the client-provided FS.OpenFile's are defined by that package.  (The operations are defined by providing procedures to FSBackdoor.OpenFileFromProcs).  For example, the FS.OpenFile's obtained by calling the Alpine package directly do permit use of Alpine's special facilities for transaction, locking, and page access.  Generation of such FS.OpenFile's is via Alpine procedures and completely bypasses FS's locking and cache.
Opening an existing file
An existing file may be opened using the following procedure:
FS.Open: PROC [name: ROPE, lock: FS.Lock _ $read, wantedCreatedTime: BasicTime.GMT _ BasicTime.nullGMT, remoteCheck: BOOLEAN _ TRUE, wDir: ROPE _ NIL] RETURNS [FS.OpenFile];
An FS.FileInfo[name, wantedCreatedTime, remoteCheck, wDir] is done.  If an FS.Error is not raised, then the file described by the result of FS.FileInfo is opened.  If an "attachedTo" is returned then that global file is the one opened.  "lock" specifies the lock to be set.  Opening a file with an "write" lock does not change the created-time property; maintaining this property is the client's responsibility.  When a local file that is attached to a global file is opened for writing, the attachment is broken and the contents of the global file are copied into a local file, which local file assumes the LName.  Multiple calls on FS.Open produce different FS.OpenFile's.
Client errors:  $noCache, $globalWriteLock
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $unknownFile, $unknownCreatedTime, $illegalName, $patternNotAllowed
Creating a new file
There are two important restrictions on file creation.  First, no version may be specified; FS always creates the !N version.  Second, global files may not be created; only FS.Copy and FS.Rename can cause new global file to come into existence.
FS.Create: PROC [name: ROPE, setPages: BOOLEAN _ TRUE, pages: INT _ 0, setKeep: BOOLEAN _ FALSE, keep: CARDINAL _ 1, wDir: ROPE _ NIL] RETURNS [FS.OpenFile];
A new local file with the specified name is created and opened with a "write" lock.    The created-time is set to now.  No version part may be specified.  FS will assign the version number that is one larger than the existing !H version, or !1 if no versions exist.  If !1 is being created or "setKeep" is TRUE then the keep is set to "keep"; otherwise the keep for the new file is that from the existing !H version.  If "setPages" is TRUE then the number of pages in the created file is set to "pages".  If "setPages" is FALSE then the number of pages in the new file is the same as the reused file if any, otherwise it set to "pages".
Client errors:  $noCache, $globalWriteLock
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $unknownFile, $unknownCreatedTime, $illegalName, $patternNotAllowed
The following procedure is provided as a convenience for clients that wish to open an existing file for write, but create one if none exists.
FS.OpenOrCreate: PROC [name: ROPE, keep: CARDINAL _ 1, pages: INT _ 5, wDir: ROPE _ NIL] RETURNS [FS.OpenFile];
Performs FS.Open[name: name, lock: write, wDir: wDir].  If FS.Error[$unknownFile] is raised then FS.Create[name: name, pages: pages, keep: keep, wDir: wDir] is called.  Note that "name" may contain no version part in cases where FS.Create is called.
Client errors:  $noCache, $globalWriteLock, $zeroKeep
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $unknownCreatedTime, $illegalName, $patternNotAllowed, $versionSpecified, $globalCreation
10. Operations on open files
Obtaining information
FS.GetClass: PROC [file: FS.OpenFile] RETURNS [ATOM];
Returns an ATOM that identifies the implementation for operations on "file".  If "file" was obtained by calling FS.Open, FS.Create, or FS.OpenOrCreate, then "$FS" is returned.  If "file" was obtained by calling some other package that manufactures FS.OpenFiles via FSBackdoor.CreateProcsOpenFile, then the ATOM returned is that provided by that package.
Client errors: $invalidOpenFile, $notImplemented
User errors: none
FS.SameFile: PROC [file1, file2: FS.OpenFile] RETURNS [BOOLEAN];
Returns TRUE iff "file1" and "file2" are for the same files.  Two FS.OpenFile's obtained from an FS procedure are the same if they refer to the same File.FP.
Client errors:  $invalidOpenFile, $notImplemented
User errors:  none
FS.GetName: PROC [file: FS.OpenFile] RETURNS [fullFName, attachedTo: ROPE];
The full name of the opened file, in brackets syntax with any version number, is returned as "fullFName".  If the name that was opened was an LName attached to a GName, then the name of the attached global file is returned as "attachedTo", which otherwise is NIL.
Client errors:  $invalidOpenFile, $notImplemented
User errors:  none
FS.GetInfo: PROC [file: FS.OpenFile] RETURNS [keep: CARDINAL, pages, bytes: INT, created: BasicTime.GMT, lock: FS.Lock];
The keep (if not defined for the server in question then 0 is returned), number of pages, byte count, created-time, and the lock held are returned.  If the name that was opened was an LName attached to a GName, then the pages, byte count, created-time, and lock are for the global file.
Client errors:  $invalidOpenFile, $notImplemented
User errors:  none
Setting properties
FS.SetPageCount: PROC [file: FS.OpenFile, pages: INT];
Extends or contracts the file until the number of pages is as specified.
Client errors:  $wrongLock, $unknownPage, $invalidOpenFile, $notImplemented
User errors:  none
FS.SetByteCountAndCreatedTime: PROC [file: FS.OpenFile, bytes: INT _ -1, created: BasicTime.GMT _ BasicTime.nullGMT];
Sets the byte count and created-time properties of "file".  If "created" is BasicTime.nullGMT then the created-time of the file is not altered.  If "bytes" is -1 then the byte count is not altered.
Client errors:  $wrongLock, $badByteCount, $invalidOpenFile, $notImplemented
User errors:  none
Reading and writing data
FS.Read: UNSAFE PROC [file: FS.OpenFile, from, nPages: INT, to: LONG POINTER];
Copies "nPages" pages from the file starting at "from" to the virtual memory interval starting at "to".  "to" must be page-aligned.  Note that ERROR's caused by "to" being an invalid address are not mapped to FS.Error's.
Client errors:  $unknownPage, $invalidOpenFile, $notImplemented
User errors:  none
FS.Write: PROC [file: FS.OpenFile, to: INT, nPages: INT, from: LONG POINTER];
Copies "nPages" pages from the virtual memory interval starting at "from" to the file starting at page number "to". "from" must be page-aligned.  Note that ERROR's caused by "from" being an invalid address are not mapped to FS.Error's.
Client errors:  $wrongLock, $unknownPage, $invalidOpenFile, $notImplemented
User errors:  none
Closing open files
FS.Close: PROC [file: FS.OpenFile];
Releases the locks associated with the open "file".  Any further operations on copies of this FS.OpenFile will produce an FS.Error[client, $invalidOpenFile].  The locks will also be released by finalization when all copies of the FS.OpenFile disappear, but this occurs at an unspecified future time.
Client errors:  $invalidOpenFile, $notImplemented
User errors:  none
11. File streams
File stream model
A file is a sequence [0..fileLen) of mutable bytes; the length (fileLen) of a file can be changed.
The state of a file stream is a file (perhaps opened under a transaction trans) with length fileLen, an index streamIndex IN [0..fileLen], plus a number of readonly flags (accessRights, streamOptions) and a BOOL variable closed which jointly determine the effect of stream procs.
Here is what the generic stream operations do when applied to a file stream:
IO.GetChar: PROC [self: STREAM] RETURNS [CHAR]
To be provided.
IO.CharsAvail: PROC [self: STREAM, wait: BOOL] RETURNS [INT]
To be provided.
IO.EndOf: PROC [self: STREAM] RETURNS [BOOL]
To be provided.
IO.PutChar: PROC [self: STREAM, char: CHAR]
To be provided.
IO.Flush: PROC [self: STREAM]
To be provided.
IO.Reset: PROC [self: STREAM]
To be provided.
IO.Close: PROC [self: STREAM, abort: BOOL _ FALSE]
To be provided.
IO.GetIndex: PROC [self: STREAM] RETURNS [INT]
To be provided.
IO.SetIndex: PROC [self: STREAM, index: INT]
To be provided.
IO.GetLength: PROC [self: STREAM] RETURNS [INT]
To be provided.
IO.SetLength: PROC [self: STREAM, length: INT]
To be provided.
Concurrency
File streams provide no interlocks of their own to control concurrent access to files.  Instead, they rely on the underlying file system for concurrency control.  FS uses locking to provide concurrency control.
Individual file streams are independent objects, so there is never any need to synchronize calls to their procedures.  If two processes are to share a single file stream, they must synchronize their accesses to that stream at a level above the file stream calls; individual file stream calls (PutChar, PutBlock, etc.) are not guaranteed to be atomic.
Pragmatics
An FS file is represented as a sequence of disk pages, each containing FS.BytesForPages[1] bytes.  There is a single leader page (overhead) that is used to hold file properties such as the byte count and create time.  There is no functional relationship between the byte count of a file and the allocated size of that file in pages.
Allocating disk pages to a file is an expensive operation, especially when done incrementally (one page at a time).  Extending a file many times can result in a fragmented file.  If a client program can estimate the eventual length of a file it is creating, it should use the "createByteCount" parameter to FS.StreamOpen to allocate enough space to hold the entire length all at once; if a client program is updating an existing file then it should create a stream and then extend the file using IO.SetLength.  If the file stream implementation must extend a file it will always extend it by several pages;  if asked to shorten a file it will simply adjust the byte count field in the leader page without freeing any pages.  If the streamOption "truncatePagesOnClose" is specified (the default), then extra pages are freed when the stream is closed.
Creating file streams
The following TYPE's and constants are used in conjunction with creating file streams.
FS.StreamOptions: TYPE = PACKED ARRAY StreamOption OF FalseBool;
FS.FalseBool: TYPE = BOOL _ FALSE;
FS.defaultStreamOptions: FS.StreamOptions = ALL[TRUE];
FS.StreamOption: TYPE = {
tiogaRead,
-- if accessOptions = $read and file is in Tioga format, read only plain text portion of the file (ignore "looks" and nodes with the comment property).  If accessOptions # $read and file is in Tioga format, raise FS.Error[$cantUpdateTiogaFile].
commitAndReopenTransOnFlush,
-- obsolete, will be removed when FS is recompiled
truncatePagesOnClose,
-- each IO.Flush call causes extra pages of the file to be freed.
finishTransOnClose,
-- obsolete, will be removed when FS is recompiled
closeFSOpenFileOnClose
-- each IO.Close call performs FS.Close on the underlying FS.OpenFile.
};
FS.StreamBufferParms: TYPE = RECORD [vmPagesPerBuffer: INT [1 .. 128], nBuffers: INT [1 .. 4]];
FS.defaultStreamBufferParms: FS.StreamBufferParms = [vmPagesPerBuffer: 16, nBuffers: 2];
FS.minimumStreamBufferParms: FS.StreamBufferParms = [vmPagesPerBuffer: 1, nBuffers: 1];
Control the buffering strategy used by a stream.
FS.ByteCount: TYPE = INT;
FS.ExtendFileProc: TYPE = PROC [--current-- FS.ByteCount] RETURNS [--new-- FS.ByteCount];
Called by a stream when a file is to be extended.  Returns a suggested new allocated byte count for the file; the stream may extend file by more than the requested amount.
FS.AccessOptions: TYPE = {read, create, append, write};
File STREAM's can be open from either a file name or an FS.OpenFile.
FS.StreamOpen: PROC [fileName: ROPE, accessOptions: AccessOptions _ $read, streamOptions: FS.StreamOptions _ defaultStreamOptions, keep: CARDINAL _ 1, createByteCount: FS.ByteCount _ 2560, streamBufferParms: FS.StreamBufferParms _ defaultStreamBufferParms, extendFileProc: FS.ExtendFileProc _ NIL] RETURNS [IO.STREAM];
Create a new stream by (1) generating an FS.OpenFile, then (2) creating a stream on this FS.OpenFile.
(1) The FS procedure called to generate the open file depends on the "accessOptions".  Any FS.Error raised by the open call will propagate through FS.StreamOpen.
$read => FS.Open[name: fileName];
$create => FS.Create[name: fileName, keep: keep, pages: FS.PagesForBytes[createByteCount]];
$append => FS.OpenOrCreate[name: fileName, keep: keep, pages: FS.PagesForBytes[createByteCount]];
$write => FS.Open[name: fileName, lock: $write];
(2) Perform FS.StreamFromOpenFile[ ... , streamOptions, streamBufferParms, extendFileProc] on the resulting FS.OpenFile.  The value of accessOptions determines the set of operations allowed on the stream (disallowed operations raise IO.Error[$NotImplementedForThisStream, stream] when called), and the initial streamIndex, as follows:
read:  PutChar, PutBlock, UnsafePutBlock, and SetLength are disallowed, and the initial streamIndex is 0.
create: all operations are allowed, the length is set to zero at stream creation time, and the initial streamIndex is 0.
append: all operations are allowed, and the initial streamIndex is the file's byte count.
write: all operations are allowed, and the initial streamIndex is 0.
Client errors:  $noCache, $globalWriteLock, $zeroKeep
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $unknownFile, $illegalName, $patternNotAllowed, $versionSpecified, $globalCreation, $cantUpdateTiogaFile
InitialPosition: TYPE = {start, end};
FS.StreamFromOpenFile: PROC [openFile: OpenFile, accessRights: Lock _ $read, initialPosition: FS.InitialPosition _ $start, streamOptions: FS.StreamOptions _ defaultStreamOptions, streamBufferParms: FS.StreamBufferParms _ defaultStreamBufferParms, extendFileProc: FS.ExtendFileProc _ NIL] RETURNS [IO.STREAM];
Create a new stream on the open file.  If AccessRights = $read then PutChar, PutBlock, UnsafePutBlock, and SetLength are disallowed on the resulting stream.  InitialPosition specifies the initial value of streamIndex:  start means 0, end means the file's byte count.
Client errors:  $wrongLock
User errors:  $cantUpdateTiogaFile
It is also possible to get the FS.OpenFile back from a file STREAM.
FS.OpenFileFromStream: PROC [self: IO.STREAM] RETURNS [FS.OpenFile];
Will raise IO.Error[$NotImplementedForThisStream, self] if self is not a stream on an FS.OpenFile.
Client errors:  none
User errors:  none
Finding out about errors from generic STREAM procedures is a two step process.  First IO.Error[$Failure, self] is raised and is caught by the client.  The client then calls FS.ErrorFromStream to obtain more detailed information about the ERROR.
FS.ErrorFromStream: PROC [self: IO.STREAM] RETURNS [FS.ErrorDesc];
Will raise IO.Error[$NotImplementedForThisStream, self] if self is not a stream on an FS.OpenFile.
Client errors:  none
User errors:  none
12. General file manipulation
Copying files, including creating attachments
When copying files, only the !N version of the target file can be created.  Attachments are created by setting the "attach" argument of FS.Copy to TRUE.  Copying from one remote server to another is implemented by retrieving the "from" file into the cache on the system volume.
FSExtras.NewCopy: PROC [from, to: ROPE, setKeep: BOOLEAN _ FALSE, keep: CARDINAL _ 1, wantedCreatedTime: BasicTime.GMT _ BasicTime.nullGMT, remoteCheck: BOOLEAN _ TRUE, attach: BOOLEAN _ FALSE, wDir: ROPE _ NIL] RETURNS [toFName: Rope.ROPE];
Same as FS.Copy (next) except returns the full FName of the "to" file created by the copy. 
FS.Copy: PROC [from, to: ROPE, setKeep: BOOLEAN _ FALSE, keep: CARDINAL _ 1, wantedCreatedTime: BasicTime.GMT _ BasicTime.nullGMT, remoteCheck: BOOLEAN _ TRUE, attach: BOOLEAN _ FALSE, wDir: ROPE _ NIL];
The "to" name cannot contain a version part.  The version of the "to" file created is one larger than the existing !H version, unless "to" is a GName on a server that does not support version numbers, in which case an existing global file will be overwritten. 
Case 1: "to" is a GName and "attach" is FALSE  FS does an FS.Open[from, read, wantedCreatedTime, remoteCheck, wdir] and stores the contents and properties of the opened file directly in the new "to" file on the remote server.
Case 2: "to" is an LName and "attach" is FALSE  FS does an FS.Open[from, read, wantedCreatedTime, remoteCheck, wDir] to generate a "from" open file, and FS.Create[to, setKeep, keep, wDir] to generate a "to" OpenFile.  The contents and properties are copied from the "from" OpenFile to the "to" OpenFile, and both are closed.  (In the case of copying from an uncached global file, the global file is not added to the cache.  The only pages allocated on the local volume are those needed to hold the target local file.)
Case 3: "to" is a GName, "attach" is TRUE, and "from" is a LName  Things proceed as in case 1.  Once the transfer is completed, the LName is attached to the GName.  Case 3 is used by "SModel".
Case 4:  "to" is an LName, "attach" is TRUE, and from" is a GName  Like case 2 except that instead of an actual transfer of contents and properties, the LName is attached to the GName / created-time.  If no "wantedCreatedTime" is specified, or if "remoteCheck" is TRUE, then FS.FileInfo[to, wantedCreatedTime, TRUE] is performed first to determine/check the version number and created-time for the GName and any resulting FS.Error is passed on to the client.  When "remoteCheck" is FALSE (but a wantedCreatedTime" is specified) then the attachment is made to the "from" and "wantedCreatedTime" arguments without checking either the remote server or the cache.  Case 4 is used by "BringOver".
Case 5: both "from" and "to" are LNames, or both are GNames, and "attach is "TRUE"  FS proceeds as though "attach" were FALSE (see cases 1 and 2 above).
Client errors:  $zeroKeep
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $unknownFile, $unknownCreatedTime, $illegalName, $patternNotAllowed, $versionSpecified (on "to" name)
Deleting files
FS.Delete: PROC [name: ROPE, wantedCreatedTime: BasicTime.GMT _ BasicTime.nullGMT, wDir: ROPE _ NIL];
A missing version part defaults to !L.  If "name" is an GName then the file is deleted directly from the remote server (and removed from the cache).  An FS.Error[lock, $lockConflict] occurs if the specified file is currently open.  If "name" is an LName that is attached to some GName, then just the LName is deleted; the global file is not deleted.  Note that deleting the !H version may cause a previous version to become the new !H version, and therefore cause the keep on the previous version to become the controlling keep for the set of versions. 
Client errors:  none
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $unknownFile, $unknownCreatedTime, $illegalName, $patternNotAllowed
Renaming files
Only the !N version of a file may be created by FS.Rename.  Renaming from one server to another is allowed.  In the case of the "from" and "to" names being on the same remote server or the same local volume, remaining occurs without copying.  Otherwise, FS.Rename is like FS.Copy followed by FS.Delete.
FS.Rename: PROC [from, to: ROPE, setKeep: BOOLEAN _ FALSE, keep: CARDINAL _ 1, wantedCreatedTime: BasicTime.GMT _ BasicTime.nullGMT, wDir: ROPE _ NIL];
The "to" name cannot contain a version part.  A missing version part defaults to !H for the "from" name.  An FS.Error[lock, $lockConflict] occurs if the specified file is currently open.  Renaming (and implied copying or deletion) on global servers occurs synchronously.
Client errors:  $zeroKeep
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $unknownFile, $unknownCreatedTime, $illegalName, $patternNotAllowed, $versionSpecified (on "to" name)
Setting keeps on existing files
Only the keep of the !H version may be set.  The "name" argument to FS.SetKeep cannot contain a version part.
FS.SetKeep: PROC [name: ROPE, keep: CARDINAL _ 1, wDir: ROPE _ NIL];
"name" cannot contain a version part.  Setting the keep causes any unopen versions that are beyond the new keep to be deleted.  Setting the keep to "0" leaves the current keep, but does the keep processing.
Client errors:  none
User errors:  $nonCedarVolume, $unknownServer, $unknownVolume, $unknownFile, $unknownCreatedTime, $illegalName, $patternNotAllowed, $versionSpecified, $noKeeps
13. Functions for experts
Introduction
The interface FSBackdoor.mesa contains facilities that should be of interest only to experts.
Client-provided open files
FS provides a way for clients to implement objects with the TYPE FS.OpenFile.  The client provides procedures that implement the operations on an FS.OpenFile.  Refer to section 7 above for the semantics of these procedures.  Note that no locking is done by FS on client-provided FS.OpenFile's.  FS produces FS.Error[client, $notImplemented] when an attempt is make to use any client procedures that are NIL.
FSBackdoor.FileProcs: TYPE;
FSBackdoor.CreateFileProcs: PROC [
GetClass: PROC [clientFile: REF] RETURNS [ATOM] _ NIL,
SameFile: PROC [clientFile1, clientFile2: REF] RETURNS [BOOLEAN] _ NIL,
GetName: PROC [clientFile: REF] RETURNS [fullFName, attachedTo: ROPE] _ NIL,
GetInfo: PROC [clientFile: REF] RETURNS [keep: CARDINAL, pages, bytes: INT, created: BasicTime.GMT, lock: FS.Lock] _ NIL,
SetPageCount: PROC [clientFile: REF, pages: INT] _ NIL,
SetByteCountAndCreatedTime: PROC [clientFile: REF, bytes: INT, created: BasicTime.GMT] _ NIL,
Read: UNSAFE PROC [clientFile: REF, from, nPages: INT, to: LONG POINTER] _ NIL,
Write: PROC [clientFile: REF, to: INT, nPages: INT, from: LONG POINTER] _ NIL,
Close: PROC [clientFile: REF] _ NIL
] RETURNS [REF FileProcs];
SameFile will only get called for two clientFile's with equal "REF FileProcs".
Client errors:  none
User errors:  none
FSBackdoor.CreateProcsOpenFile: PROC [clientFile: REF, fileProcs: REF FSBackdoor.FileProcs] RETURNS [FS.OpenFile];
Whenever any of the procedures above are called for the FS.OpenFile returned by FSBackdoor.CreateProcsOpenFile, the "clientFile" argument to CreateProcsOpenFile is passed on as the identification of the open file that is to be operated upon.
Client errors:  none
User errors:  none
FSBackdoor.GetClientFileAndProcs: PROC [file: FS.OpenFile] RETURNS [clientFile: REF, fileProcs: REF FSBackdoor.FileProcs];
If "file" is a client-provided FS.OpenFile then the "clientFile" and "fileProcs" are returned, otherwise NIL is returned for both results.
Client errors:  $invalidOpenFile
User error:  none
The client procedures should raise FS.Error as appropriate.  Client procedures should generate the code ATOM's used by FS where meaningful, but can produce additional code ATOM's if needed.  FS.Error's with existing code ATOM's should be generated using FSBackdoor.ProduceError (see below).  For any new code ATOM's, the client is responsible for providing the appropriate FS.ErrorGroup.
FSBackdoor.ErrorCode: TYPE = {ok -- used internally-- , inconsistent, software, badFP, wentOffline, hardware, volumeFull, fragmented, noMoreVersions, serverInaccessible, connectionRejected, connectionTimedOut, badCredentials, accessDenied, quotaExceeded, invalidPropertyPage, badBTree, lockConflict, fileBusy, noCache, wrongLock, globalWriteLock, zeroKeep, badByteCount, unknownPage, invalidOpenFile, notImplemented, nonCedarVolume, unknownServer, unknownVolume, unknownFile, unknownCreatedTime, illegalName, patternNotAllowed, versionSpecified, globalCreation, badWorkingDir, noKeeps, cantUpdateTiogaFile};
FSBackdoor.ProduceError: PROC [code: FSBackdoor.ErrorCode, explanation: ROPE];
Raises FS.Error for the code ATOM that corresponds lexically to the "code".  The FS.ErrorGroup in the error is properly set.  The error will contain "explanation".  Clients should use this procedure to generate FS.Error's for existing codes to avoid spelling the ATOM's wrong and to avoid getting the wrong FS.ErrorGroup.
Volume space management
FS provides access to the File package procedures for setting the volume freeboard on the system volume and reading the size, free and freeboard counts from a named volume.
FSBackdoor.SetFreeboard: PROC [freeboard: INT];
Client errors:  none
User errors:  $unknownVolume
FSBackdoor.VolumePages: PROC [volName: ROPE _ NIL] RETURNS [size, free, freeboard: INT];
"volName" = NIL means the system volume.
Client errors:  none
User errors:  $unknownVolume
Manual cache management
FSBackdoor.InfoProc: TYPE = PROC [fullGName: ROPE, created: BasicTime.GMT, bytes: INT, keep: CARDINAL] RETURNS [continue: BOOLEAN];
FSBackdoor.EnumerateCacheForInfo: PROC [proc: FSBackdoor.InfoProc, volName, pattern: ROPE _ NIL];
FSBackdoor.NameProc: TYPE = PROC [fullGName: ROPE] RETURNS [continue: BOOLEAN];
FSBackdoor.EnumerateCacheForNames: PROC [proc: FSBackdoor.NameProc, volName, pattern: ROPE _ NIL];
Like FS.EnumerateForInfo and FS.EnumerateForNames, except that only cached GNames in the named volume are enumerated.  "volName" = NIL means the system volume.  "pattern" = NIL means to match all names.
Client errors:  $noCache
User errors:  $nonCedarVolume, $unknownVolume, $illegalName
FSBackdoor.Flush: PROC [fullGName: ROPE, volName: ROPE _ NIL];
The specified GName is removed from the directory/cache on the named volume and any associated file on that volume is deleted.  "volName" = NIL means the system volume.  Locking is done only for the system volume.  In this case FS.Error[lock, $lockConflict] is generated when a "write" lock cannot be obtained.  Flushing a cached file from other than the system volume is done independent of any locks that may be set, so BE SURE YOU KNOW WHAT YOU ARE DOING.  No FS.Error occurs if the "fullGName" is not in the cache on the indicated volume
Client errors:  none
User errors:  $nonCedarVolume, $unknownVolume
Direct access to the directory and cache on any volume
The directory of LNames and the cache for GName are implemented together as a BTree on a local volume.  The following procedures and TYPE's allow direct access to this BTree.
A "nameBody" is an FName without a version part.  LNames are recorded in the directory/cache without the "[]<>" prefix.  Thus the nameBody for the LName "[]<>foo.mesa!5" will be "foo.mesa", and the nameBody for the GName "[indigo]<Cedar>Top>FS.df!47" will be "[indigo]<Cedar>Top>FS.df".  The version part is represented as a scalar.  The version for a GName that includes no version is "noVersion", which value otherwise will not occur.
FSBackdoor.Version: TYPE = RECORD [CARDINAL];
FSBackdoor.noVersion: FSBackdoor.Version = [LAST[CARDINAL]];
FSBackdoor.highestVersion: FSBackdoor.Version = FSBackdoor.noVersion;
FSBackdoor.lowestVersion: FSBackdoor.Version = [0];
"highestVersion" and "lowestVersion" are used internally as the representation of !L and !H.
An entry in the directory/cache can be gotten at directly via FSBackdoor.Enumerate and the following TYPE's.
*************************************************************
WARNING:  You should treat FSBackdoor.Entry's as READONLY
*************************************************************
FSBackdoor.EntryType: TYPE = {local, attached, cached, notFound}; -- notFound is for internal use only
FSBackdoor.EntryPtr: TYPE = LONG BASE POINTER TO FSBackdoor.Entry;
FSBackdoor.TextRP: TYPE = FSBackdoor.EntryPtr RELATIVE POINTER TO FSBackdoor.TextRep;
FSBackdoor.TextRep: TYPE = MACHINE DEPENDENT RECORD [PACKED SEQUENCE length: CARDINAL OF CHAR];
FSBackdoor.Entry: TYPE = MACHINE DEPENDENT RECORD [
size(0): CARDINAL, -- size in words of entire entry, including TextRep's at end
version(1): FSBackdoor.Version, -- version part of FName
nameBody(2): FSBackdoor.TextRP, -- FName w/o version
rest(3): SELECT type(3): FSBackdoor.EntryType FROM
local => [
keep(4): CARDINAL,
fp(5): File.FP
],
attached => [
keep(4): CARDINAL,
created(5): BasicTime.GMT,
attachedTo(5+SIZE[BasicTime.GMT]): FSBackdoor.TextRP -- includes version part
],
cached => [
used(4): BasicTime.GMT,
fp(4+SIZE[BasicTime.GMT]): File.FP
]
ENDCASE
-- here follows the TextRep for nameBody and possibly for attachedTo
];
FSBackdoor.Enumerate: PROCEDURE [ volName: ROPE, nameBodyPattern: Rope.Text,  localOnly, allVersions: BOOLEAN, version: FSBackdoor.Version, matchProc: UNSAFE PROC [entry: FSBackdoor.EntryPtr] RETURNS [accept, stop: BOOLEAN], acceptProc: PROC RETURNS [stop: BOOLEAN] ];
"volName" is the name of a disk volume.  A NIL "volName" means the system volume.  The directory/cache is enumerated.  The order of enumeration is lexical by nameBody (lower case letters are mapped to upper case) then numerical by version.  Because LNames in the directory/cache do not have the "[]<>" prefix, and because of the constraints on the characters allowed in FNames, all LNames appear in the directory/cache earlier in the enumeration order than all GNames.  The scope of the enumeration is constrained by the "localOnly" argument: if TRUE then only the LNames are enumerated; otherwise the enumeration spans all entries in the directory/cache.  If "allVersions" is TRUE then the enumeration includes all versions of entries; otherwise it includes on the version specified by "version".  The name body pattern is applied literally, without consideration of any working directories.  If you want to enumerate only global names, then be sure the "nameBodyPattern" starts with "[".  "matchProc" is called for each entry that matches the "pattern".  A NIL "pattern" means to start at the beginning of the directory/cache and match everything.  If "stop" is returned as TRUE then the enumeration terminates.  Otherwise, if "accept" is returned as TRUE then "acceptProc" is called.  The "acceptProc" can also stop the enumeration.  The directory/cache is read locked while "matchProc" is called, so other operations on the directory/cache and tasks involving indefinite waits should not be done from this procedure.  Do these from the "acceptProc" instead.
Client errors:  none
User errors:  $nonCedarVolume, $unknownVolume
FSBackdoor.TextFromTextRep: PROCEDURE [nameBody: LONG POINTER TO FSBackdoor.TextRep] RETURNS [Rope.Text];
If "e" is an "EntryPtr", and "e.t" is a contained "TextRP", then "@e[e.t]" is a "LONG POINTER TO TextRep".
Client errors:  none
User errors:  none
FSBackdoor.MakeFName: PROCEDURE [nameBody: ROPE, version: FSBackdoor.Version _ noVersion, prefix: ROPE _ NIL] RETURNS [ROPE];
Makes an FName out of a "nameBody" and "version", and a "prefix".  Does not do a syntax check.  The prefix is prepended if the nameBody does not start with the character "[".  If the nameBody comes from the directory of some named volume other than the system volume, then a prefix of "[]<volumeName>" should be supplied.  If a prefix is needed and NIL is supplied, then "[]<>" is used.  For use in converting the "attachedTo" name from a directory entry to a ROPE, just leave "version" and "prefix" defaulted, since "attachedTo" already starts with "[" and includes the version part.
Client errors:  none
User errors:  none
Directory/cache reconstruction
FSBackdoor.ScavengeDirectoryAndCache: PROC [ volName: ROPE _ NIL ];
The directory/cache BTree for the named volume is rebuilt by enumerating the leader pages of all files on the volume and merging in any attached LNames that can be recovered from an existing BTree.  "volName" = NIL means the system volume.  While scavenging is occurring all FS operations that access the directory will wait.  DO NOT call FSBackdoor.CloseVolume first.
Client errors:  none
User errors:  $nonCedarVolume, $unknownVolume
Reporting activity
FSExtras contains two procedures for reporting the occurance of events.  FSExtras.NextRemoteEvent reports all actions on remote files, and is intended for use by clients like the "WatchTool".  FSExtras.NextCreateEvent reports all creations of new LName - to - data bindings, and is intended for use by clients like "Tioga" that may want to know when new versions of local files come into existence.
FSExtras.RemoteOp: TYPE = {startRetrieving, endRetrieving, startStoring, endStoring, startDeleting, endDeleting, startRenaming, endRenaming, startFlushing, endFlushing};
FSExtras.RemoteEvent: TYPE = RECORD [
op: FSExtras.RemoteOp, -- remote operation that has occurred
fName: Rope.ROPE, -- full GName of the remote file operated upon
chain: REF FSExtras.RemoteEvent -- used internally to chain events together
];
FSExtras.NextRemoteEvent: PROC [REF READONLY FSExtras.RemoteEvent _ NIL] RETURNS [REF READONLY FSExtras.RemoteEvent];
A remote event is the start or conclusion of retrieving, storing, deleting, renaming or flushing (from the cache) a global file.  NextRemoteEvent returns the next event that occurs after the argument RemoteEvent.  When the argument RemoteEvent is NIL then NextRemoteEvent returns the first event to occur after the time of the call.  NextRemoteEvent will WAIT if another event has not occurred yet.  Storing, retrieving and flushing of several files can be in progress simultaneously. 
Client errors:  none
User errors:  none
FSExtras.CreateOp: TYPE = {writeClose, renameTo, copyTo};
FSExtras.CreateEvent: TYPE = RECORD [
op: FSExtras.CreateOp, -- creation operation that has occurred
fName: Rope.ROPE, -- full LName of the local file that has been created
chain: REF FSExtras.CreateEvent -- used internally to chain events together
];
FSExtras.NextCreateEvent: PROC [REF READONLY FSExtras.CreateEvent _ NIL] RETURNS [REF READONLY FSExtras.CreateEvent];
A creation event is the closing of a local file that was open for write (was just created or overwritten), the completion of an FS.Rename call where "to" is an LName, or the completion of an FS.Copy call where "to" is an LName.  NextCreateEvent returns the next event that occurs after the argument CreateEvent.  When the argument CreateEvent is NIL then NextCreateEvent returns the first event to occur after the time of the call.  NextCreateEvent will WAIT if another event has not occurred yet. 
Client errors:  none
User errors:  none
The following is the obsolete facility for reporting on remote events.  
FSBackdoor.EventHandle: TYPE = REF FSBackdoor.EventObject;
FSBackdoor.EventObject: TYPE;
FSBackdoor.EventOp TYPE = {startRetrieving, endRetrieving, startStoring, endStoring, startFlushing, endFlushing};
FSBackdoor.NextEvent: PROC [last: FSBackdoor.EventHandle _ NIL] RETURNS [fName: ROPE, op: FSBackdoor.EventOp, this: FSBackdoor.EventHandle];
An event is the start or conclusion of retrieving, storing, or flushing (from the cache) a global file.  Given a "last" event, a call on FSBackdoor.NextEvent returns in "this" the next event along with the FName of the remote file operated upon and the operation.  When "last" is NIL then the next event in time is returned.  Will WAIT if necessary for another event to occur.  Storing, retrieving and flushing of several files can be in progress simultaneously. 
Client errors:  none
User errors:  none
Other functions
FSBackdoor.CloseVolume: PROC [v: File.Volume];
For experts only!!!  Tells FS to close any directory/cache BTree it has open for the volume.  May cause FS operations in progress to raise various strange BTree and File ERROR's.  After CloseVolume returns, new FS operations will try to reopen a directory/cache BTree for the volume.  Should be called AFTER a volume is erased. 
Client errors:  none
User errors:  none
FSBackdoor.GetFileHandle: PROC [file: FS.OpenFile] RETURNS [File.Handle];
For experts only!!!  Returns the File.Handle that goes with an FS.OpenFile.
Client errors:  $invalidOpenFile, $notImplemented (for client-provided FS.OpenFile's)
User errors:  none
FSBackdoor.FNameFromHandle: PROC [file: File.Handle] RETURNS [ROPE];
Returns the full FName of the named "file".  Will raise FS.Error[environment, $invalidPropertyPage] if the handle is not for an FS file. 
Client errors:  none
User errors:  none




�Ê å–

"cedar" style˜Iblock•MarkcenterHeaderš
œ&˜&K–centerFooterš
Ïk	˜	Ititle˜&Isubtitleš
œ*˜*Iabstractš�
œ-�
œ�œ˜yK˜K˜K˜Iboilerplateš
ÏqœÏoœŸœŸœŸ Ñbox˜’

head˜˜Kšœ�
�œ�œ–
�œ‘�œ�œ*˜±—˜Kšœ:�œ�œ'˜�
—˜Kš
�œ—
�œ0�œ�œæ�œY˜«Kš�œ{�œÒ
˜ÑKš�œ'�œ
�œ½
˜ï
—˜Kš�œ2�œR�œÅ
�œ˜ê——˜9˜š	œ�œ�
�œ�œž
�œ˜„Iunitšœ�œ˜—š
œ›
˜›
Qšœ�œ˜—š
œ»
˜»
Qšœ�œ˜—š
œ·
˜·
Qšœ�œ˜—Kš
œ‹
˜‹
—˜šœr�œB˜¶
Qšœ�œ
�œ˜#Jš�œ5�	œ
˜C——š
œ	˜	Kšœu�œ�œ†
�œW˜èKšœX�œ/�œ)�œM˜ƒKš
œ¤
˜¤
——˜˜šœ�œ&�œ
�œ=�œ�œ(�œ3�œ˜þ
QšÐbkÏbœ�œ	�œ˜&Qš¡¢
œ�œ�œ	�œ�œ�œ	�œ�œ˜c	š¡¢
œ�œ˜JšœÏc'˜+Jšœ£˜!Jšœ
£D˜QJšœ£˜Jšœ£;˜CJšœ£1˜6Jš
œ˜——Kš�œÚ
�œÿ˜ÝKšœC�œ”˜ÛKšœ
�œÍ
˜Ü
Kš	œ�œ*�œ"�œ1�œ˜�
—˜Kš	œ�œ!�œˆ
�œ1�œ˜€˜JšœÐciÏi¤*˜LJšœ
¥K˜UJšœ¥Ðik¥D˜U—˜Jšœ£$˜4Jšœ
¥>˜HJšœ¥'˜3Jšœ¥¤8˜LJšœ¥'˜7Jšœ¥/˜CJšœ¥¤˜DJšœ¥*˜>Jšœ¥3˜CJšœ¥*˜8Jšœ¥-˜<Jšœ¥¤0˜VJšœ
¥¤6˜D—˜Jšœ¥¤ ˜1Jšœ
¥:˜D—˜
Jšœ	¥¤N˜ZJšœ¥¤<˜JJšœ¥¤'˜;Jšœ	¥¤˜$Jšœ¥¤@˜QJšœ
¥¤<˜LJšœ¥¤E˜YJšœ¥¤<˜O—˜Jšœ£"˜5Jšœ£3˜EJšœ£"˜4Jšœ£"˜2Jšœ£=˜TJšœ£W˜gJšœ¥F˜YJšœ£0˜EJšœ£˜*Jšœ£C˜UJšœ	¥B˜KJšœ£2˜J———˜˜šœ
�œ¦�œ(˜ÜQš�œ�œ˜"—š	œ�œ�œo�œ�œ>˜å
Idisplayš
œl˜l—Kšœ°�
œ�
œ&˜ÞKš
œq˜qKšœÍ
�œg˜·š
œ¾˜¾Ršœ�œ�œJ˜]—Kšœ‡
�œ˜•
˜Rš
œÏ
˜Ï
R˜²
Ršœ´
�œî
�œ˜¯——˜KšœŸ
�œŠ
�
œ?�œ“
�
œ3�
œ\�
œ�
œ-˜Å—˜KšœÊ
�œ!˜í
šœ0�œ�œg�œ=˜ø
Ršœ�
�œ˜£
—Kšœ
�œ„˜’˜<	š	¡Ïnœ�œ�œ�œ˜*IindentšœÓ
¥
˜Ô
Sš
¥˜Sš¥¤
¥¤
¥˜>——˜=	š	¡§œ�œ
�œ�œ˜'Sš
¥˜Sš
¥˜———˜š�œ8˜:Qš	¡¢œ�œ�œ�œ˜5Qš	¡¢œ�œ�œ(�œ	˜X	š¡§
œ�œ�œ�œ�œ�œ
�œ�œ �œ˜|Sš
¥�˜�Sš
¥”˜”Sš¥£
¦¥¦¥
˜Ä
Sš
¥˜
˜˜
Sš¥e�¥˜„
Sš
¥†
˜†
Sš
¥˜Sš¥¤¥˜.—Qš¡¢œ�œ�œ(�œ�œ˜T	š¡§œ�œ�œ�œ�œ�œ�œ˜YSš¥'�¥½
˜è
Sš¥(¦¥
¦¥	¦¥,¦¥¦¥M¦¥¦¥'¦¥¦¥'¦¥˜ñSš
¥˜Sš
¥˜————˜˜Kšœ�œî
�œ¬
˜º—˜-š
œ[˜[Qš¡§
œ�œ�œ�œ	�œ˜8Qš¡§
œ�œ�œ�œ	�œ˜8Qš¡§
œ�œ�œ�œ	�œ˜8Qš¡§
œ�œ�œ�œ	�œ˜8——˜Kš	œ+�œ™
�
œa�
œ�œ	˜×KšœO�œ;�
œ©�œm˜¥Kšœ�œƒ
˜�
Kšœ�œ
�œo˜˜
K˜,——˜˜Kšœ�œe�
œ�
œ(�
œ�
œ’�œ�œ
�œF�œ�œð
�œ�œœ
�œ�œ‰
˜Ú	—˜Kšœ�œš�œK�œB˜º—˜Kš�œµ˜·Kšœ/�œ�œn�œž˜Ò——˜˜#Kšœ�œ^�œ1�œ�
˜Ï—˜šœ§
�œ�œ˜Ï
QšÐkn§œ�œ˜—Kš
œÁ˜ÁKš
œÞ˜Þ——˜"š
œ˜	š¨§œ�œ�œ�œ#�œ�œ�œ�œ�œ�œ�œ	�œ�œ˜Þ
Sš¥~¦
¥ñ
˜ðSš¥Û
¦¥+˜‰Sš	¥Š¦¥Ã
¦¥v¦¥÷¦¥#˜êSš¥Ü
¦¥¡
¦¥T¦¥�
˜úSš
¥˜Sš
¥¤¥¤¥¤¥¤¥¤¥¤¥˜‚
——˜Kšœý�
œ�
φ
�œÇ
˜¨Kš	œM�œ�œ�œ0�œ�
˜µQš¨§œ�œ�œ�œ�œ	�œ�œ�œ�œ˜‡
	š
¨§œ�œ�œ�œ�œ�œ˜OSš¥R¦¥¢¦¥€¦¥#˜ Sš
¥˜Sš¥¤¥¤¥¤¥˜K—Qš
¨§œ�œ�œ
�œ�œ�œ˜G	š
¨§œ�œ�œ�œ�œ�œ˜PSš
¥w˜wSš
¥˜Sš¥¤¥¤¥¤¥˜K———˜š
œ˜šœ�œ‡
�œ/�œ˜Ø
Qš¨¢œ�œ�œ
˜!Qš¡¢œ�œ�œ˜%—Kšœ2�œ…
�œ’
�œ¨
�œ=�œ˜Í—˜š
œ=˜=	š¨§œ�œ�œ�œ+�œ#�œ�œ�œ�œ�œ�œ
˜­
Sš	¥K¦¥?¦¥ì¦¥¦¥˜¢Sš¥¤¥˜*Sš
¥¤¥¤¥¤¥¤¥¤¥¤¥˜‚
———˜š	œ\�œ�
œ9�œ
�œ9˜ô
	š¨§œ�œ�œ�œ�œ	�œ�œ�œ�œ�œ�œ�œ�œ
˜�
Sš	¥›
¦¥•
¦¥}¦¥S¦¥m˜üSš¥¤¥˜*Sš
¥¤¥¤¥¤¥¤¥¤¥¤¥˜‚
——š
œ�
˜�
	š¨§œ�œ�œ�œ
�œ�œ�œ�œ�œ
˜oSš	¥	¦¥0¦¥$¦¥‚
¦¥˜ù
Sš¥¤¥¤¥	˜5Sš
¥¤¥¤¥¤¥¤¥¤¥%¤¥˜˜
————˜˜	š¨§œ�œ�œ
�œ�œ˜5Sš
¥¦¥a¦¥¦¥¦¥o¦¥8¦¥+˜áSš¥¤¥˜0Sš
¥˜—	š¨§œ�œ�œ
�œ�œ˜@Sš	¥¦¥6¦¥¦¥7¦¥
˜�
Sš¥ ¤¥˜1Sš
¥˜—	š¨§œ�œ�œ
�œ�œ˜KSš¥ƒ¦¥
˜‡Sš¥ ¤¥˜1Sš
¥˜—	š¨§œ�œ�œ
�œ�œ�œ�œ�œ˜xSš
¥ž˜žSš¥ ¤¥˜1Sš
¥˜——˜	š	¨§œ�œ�œ�œ˜6Sš
¥H˜HSš¥¤¥¤¥¤¥˜KSš
¥˜—	š¨§œ�œ�œ�œ�œ˜uSš
¥Å
˜Å
Sš¥¤¥
¤¥¤¥˜LSš
¥˜——˜	š¨§œ�œ
�œ�œ�œ�œ
�œ˜NSš¥�
¦¥=¦¥	˜Ü
Sš¥¤¥¤¥˜?Sš
¥˜—	š¨§œ�œ�œ�œ
�œ�œ
�œ˜MSš¥œ
¦¥?¦¥	˜ë
Sš¥¤¥¤¥¤¥˜KSš
¥˜——š
§˜	š¨§œ�œ�œ
˜#Sš¥^¦¥¦¥j¦¥C˜«Sš¥ ¤¥˜1Sš
¥˜———˜˜Kš
œb˜bKš
œnÏeœ
�œ0©œ©
œ�œ
©œ4˜—˜LQšÑknzÐnzœ�œ�œ�œ�œ
˜.Sš
¥˜Qš
ª«œ�œ�œ�œ�œ�œ
˜<Sš
¥˜Qšª«œ�œ�œ�œ
�œ
˜,Sš
¥˜Qš	ª«œ�œ�œ�œ
˜+Sš
¥˜Qšª«œ�œ�œ
˜Sš
¥˜Qšª«œ�œ�œ
˜Sš
¥˜Qšª«œ�œ�œ	�œ�œ
˜2Sš
¥˜Qšª«	œ�œ�œ�œ�œ
˜.Sš
¥˜Qš	ª«	œ�œ�œ	�œ
˜,Sš
¥˜Qšª«
œ�œ�œ�œ�œ
˜/Sš
¥˜Qš	ª«
œ�œ�œ
�œ
˜.Sš
¥˜——˜Kšœ£
�œ-˜Ò
Kš
œÞ˜Þ—˜
Kšœ�œB�œƒ˜ÌKšœ³�œ»
�œß˜Ñ—š
œ˜šœ�œD˜VQš	¡¢
œ�œ�
œ
�œ
˜@Jš¡¢	œ�œ�œ
˜"Jš	¡¢œ�œ�œ
�œ˜6š¡¢œ�œ˜š
œ
˜
Jš¥Õ
¦¥˜ô
—š
œ˜Jš
¥2˜2—š
œ˜Jš¥¦¥7˜A—š
œ˜Jš
¥2˜2—š
œ˜Jš¥¦¥¦¥¦¥
˜F—Jš
œ˜—Qš¡¢œ�œ�œ�œ�œ˜_Jš¡¢œ�œ8˜Xš¡¢œ�œ7˜WSš
¥0˜0—Qš¡¢	œ�œ�œ
˜	š¡¢œ�œ�œ£�œ�œ£�œ˜YSš
¥«
˜«
—Qš¡¢
œ�œ!˜7—šœ�œ-�œ
˜D	š¨§
œ�œ�œ7�œ,�œ�œ%�œ>�œ�œ�œ�	œ˜¾Sš¥)¦¥.¦¥
˜eš¥[¦¥6¦¥˜¡
Sš¥	¦¥˜!Sš¥¦¥+¦¥!˜[Sš¥¦¥T˜aSš¥
¦¥$˜0—š¥é
¦¥c˜ÎSš
¥i˜iSš
¥x˜xSš
¥Y˜YSš
¥D˜D—Sš¥¤¥¤¥	˜5Sš
¥¤¥¤¥¤¥¤¥¤¥%¤¥%˜§
—Qš¢œ�œ˜%	š¨§œ�œC�œ)�œ9�œ>�œ�œ�œ�	œ˜´Sš
¥Š˜ŠSš
¥˜Sš
¥"˜"——šœ�œ�œ
˜C	š¨§œ�œ�	œ�œ�œ
˜DSš¥¦¥I¦¥
˜bSš
¥˜Sš
¥˜——š	œ&�œ*�œU�œ?�œ
˜ô
	š¨§œ�œ�	œ�œ�œ˜BSš¥¦¥I¦¥
˜bSš
¥˜Sš
¥˜————˜˜-šœ�
œi�œ	�œ~˜•Qš¡	§œ�œ�œ�œ�œ�œ#�œ#�œ�œ
�œ�œ�œ�œ�œ�œ˜ñ
Sš¥¦¥Q˜[	š¡§œ�œ�œ�œ�œ�œ#�œ#�œ�œ
�œ�œ�œ�œ˜Ë
Sš
¥„˜„Sš¥(¦¥¦¥	¦¥¥
˜â
Sš	¥)¦¥¦¥	¦¥\¦¥ê˜†Sš¥%¦¥˜
˜Á
Sš	¥'¦¥Þ
¦¥*¦¥¨
¦¥Ì
˜´Sš¥M¦¥(¦¥˜™
Sš
¥˜Sš
¥¤¥¤¥¤¥¤¥¤¥¤¥4˜¤
———˜	š
¨§œ�œ�œ�œ�œ�œ˜eSš	¥$¦
¥q¦¥
¦¥Þ
œ¥©
˜©Sš
¥˜Sš
¥¤¥¤¥¤¥¤¥¤¥¤¥˜‚
——˜šœ
�
œ%�œÌ
�œ�œ�œ˜®Qš¨§œ�œ�œ�œ�œ�œ#�œ�œ�œ˜—
Sš¥R¦
¥¦¥Ÿ
˜ŽSš
¥˜Sš
¥¤¥¤¥¤¥¤¥¤¥¤¥4˜¤
——˜šœ�
œ-�œ'˜mQš
¨§œ�œ�œ�œ�œ�œ˜DSš
¥Î
˜Î
Sš
¥˜Sš
¥¤¥¤¥¤¥¤¥¤¥¤¥/˜Ÿ
———˜˜K˜]—˜š�œ:�œ
�œO�œm�œ�œ�œ
�œ^�œ
˜—Qš¨
§
¢	œ�œ
˜	š¨
§œ�œ˜"Jš§œ�œ�œ�œ�œ�œ
˜6Jš§œ�œ�œ�œ�œ�œ
˜GJš§œ�œ�œ�œ�œ�œ
˜LJš§œ�œ�œ�œ�œ�œ�œ�œ	�œ
˜yJš
§œ�œ�œ	�œ�œ
˜7Jš§œ�œ�œ	�œ�œ�œ
˜]Jš§œ�œ
�œ�œ�œ�œ
�œ�œ
˜OJš§œ�œ�œ�œ
�œ�œ
�œ�œ
˜NJš§œ�œ�œ�˜#Jšœ�œ�œ˜Sš¥?¦¥˜NSš
¥˜Sš
¥˜—	š
¨
§œ�œ�œ
�œ�œ�œ˜rSš¥8¦¥·
˜ñ
Sš
¥˜Sš
¥˜—	š
¨
§œ�œ�œ�œ�œ
�œ˜zSš¥¦¥H¦¥˜Š
Sš
¥ ˜ Sš
¥˜——šœ#�œC�œ�œ3�œ�œ�œT�œ<�œ˜ƒQš¨
¢
œ�œ£œ©˜ß	š¨
§
œ�œ+�œ˜NSš
¥¦¥¦¥0¦¥€
¦¥2¦¥(¦¥˜Á———˜š�œª
˜¬
	š¨
§
œ�œ
�œ˜/Sš
¥˜Sš
¥˜—	š¨
§œ�œ�
œ�œ�œ˜XSš¥¦¥˜(Sš
¥˜Sš
¥˜———˜Qš¨
§	œ�œ�œ
�œ�œ	�œ�œ�œ�œ˜ƒ
Qš	¨
§œ�œ/�œ�œ˜aQš
¨
§	œ�œ�œ
�œ�œ�œ˜O	š	¨
§œ�œ/�œ�œ˜bSš	¥¦¥¦¥d¦¥'¦¥˜Ê
Sš
¥˜Sš¥¤¥¤¥˜;—	š¨
§œ�œ
�œ	�œ�œ˜>Sš¥Œ
¦¥U¦¥À
¦¥
¦¥
¦¥
¦¥
¦¥
¦¥
¦¥
¦¥¦¥L˜�Sš
¥˜Sš¥¤¥˜-——˜6Kšœ…
�œ%˜®
š�
œ³˜´Qš	¡
¢œ�œ�œ�œ˜-Qš¡
¢
œ�œ
�œ˜<Qš¡
¢œ,˜EQš¡
¢œ˜3—Kš
œ\˜\Kšœe�œ˜l˜µ
Qš¡
¢
œ�œ(£$˜fQš
¡
¢	œ�œ�œ
�œ
�œ
�œ˜BQš¡
¢œ�œ�œ
�œ
�œ˜UQš¡
¢œ�œ�œ
�	œ
�œ�œ
�œ	�œ
�œ
�œ˜_	š¡
¢œ�œ�œ
�	œ
�œ˜3Jšœ	�	œ
£<˜OJšœ�
œ
£˜8Jšœ £˜4Jšœ	�œ�˜2š
œ
˜
Jšœ	�œ
˜Jšœ�˜Jš
œ˜—š
œ
˜
Jšœ	�œ
˜Jšœ�œ
˜Jšœ
�œ�œ£˜MJš
œ˜—š
œ˜Jšœ�œ
˜Jšœ�œ�œ	�˜"Jš
œ
˜
—Jš
�˜Jš
£D˜DJš
œ˜—	š¨
§
œ�	œ�œ7�œ*�œ
�œ�œ�œ�œ
�œ�œ˜ŒSš¥)¦
¥
¦¥ô¦¥¦¥ø¦
¥
¦¥r¦¥I¦¥°˜™Sš
¥˜Sš¥¤¥˜-—	š
¨
§œ�	œ�œ
�œ
�œ�œ
˜iSš¥Q¦¥
¦¥
¦¥
˜jSš
¥˜Sš
¥˜—	š¨
§
œ�	œ�œ3�œ�œ�œ�œ˜}Sš¥Ý¦¥l�¥x˜ÈSš
¥˜Sš
¥˜———˜	š	¨
§œ�œ�œ�œ˜CSš	¥Ó
¦¥=¦¥2¦¥
¦¥#˜ðSš
¥˜Sš
¥-˜-——˜š
œŽ˜ŽQš¡¢	œ�œ’
˜©
	š¡¢œ�œ�œ˜%Jšœ£%˜<Jšœ�œ£.˜@Jšœ�œ£+˜KJš
œ˜—Qš¡¢
§œ�œ�œ
�œ�œ�œ�œ
�œ˜uSš¥÷
¦¥i¦¥~˜åSš
¥˜Sš
¥˜Qš¡¢	œ�œ"˜9	š¡¢œ�œ�œ˜%Jšœ£'˜>Jšœ�œ£5˜GJšœ�œ£+˜KJš
œ˜—Qš¡¢
§œ�œ�œ
�œ�œ�œ�œ
�œ˜uSš¥Ú¦¥i¦¥(˜òSš
¥˜Sš
¥˜—š
œH˜HQš¡
¢œ�œ�œ˜:Qš¡
¢œ�œ
˜Qš¡
¢œ
�œZ˜q	š¨
§
œ�œ!�œ�œ	�œ8˜Œ
Sš¥˜¦¥0¦¥€
˜ÏSš
¥˜Sš
¥˜———˜	š¨
§œ�œ˜.Sš¥¦¥K¦¥@¦¥$¦¥Y¦¥˜ÈSš
¥˜Sš
¥˜—	š	¨
§œ�œ�œ�œ˜ISš¥?¦¥
˜KSš¥ ¤¥%¦¥˜USš
¥˜—	š	¨
§œ�œ�œ�œ˜DSš¥8¦¥F¦¥˜‰
Sš
¥˜Sš
¥˜—K˜—˜	˜J˜————…—š
(…