[Indigo]<JaM>Core>CoreDefs.mesa!2

-- file CoreDefs.Mesa

-- Last edited by Horning, December 20, 1977 10:45 AM.
-- Last edited by Kierr, February 8, 1978 3:08 PM.
-- Last edited by Wegbreit, November 18, 1977 11:33 AM.
-- Last edited by Wyatt, October 14, 1980 5:34 PM.

-- This file is part of a set. See [IFS]<DMS>OverviewDefs.mesa for more info.

DIRECTORY
AltoFileDefs: FROM "AltoFileDefs",
gsD: FROM "GlobalStorageDefs",
SegmentDefs: FROM "SegmentDefs",
ovD: FROM "OverviewDefs";

crD: DEFINITIONS = -- [6] Core Division -- BEGIN

-- Purpose: provides an MC style interface to files and raw storage/structures.

------------------------------------------------

-- Attachment Department of the Core Division. This is a stub, attachments will not be implemented initially.

-- (Not Implemented) FileAttachmentCore: PROCEDURE [capability: Capability, user: DMSUser, filename: UFilename] RETURNS [ovD.ErrorCode];
-- Exchanges messages with the appropriate attachment manager to obtain the file corresponding to the capability. Creates a file named filename and moves the file into it. Catches all Signals generated by communication procedures and turns them into ErrorCode’s and Strings. Possible errors: "Can’t open file", "Can’t find attachment manager", "Invalid capability".

-- (Not Implemented) FileToCapability: PROCEDURE [user: DMSUser, filename: UFilename] RETURNS [ovD.ErrorCode, Capability];
-- Exchanges messages with the appropriate attachment manager to obtain a capability for the attachment. Sends the file named filename to the attachment manager. Catches all Signals generated by communication procedures and turns them into ErrorCode’s and Strings. Possible errors: "Can’t find file", "Can’t find attachment manager".

-------------------------------------------

-- Distributed File Department of the Core Division. This is a mini file system for DMS. It uses several, and as yet unspecified, file servers. The name of the file server is encoded in the UFilename (DMS generalized filename).

-- Common attributes of file department interfaces:

-- (1) INDEX STRUCTURE. Files are indexed by page number and byte within each page. The data pages in a file are numbered starting at 0, and the bytes in a page are numbered [0 .. 511]. The header page on Alto files is totally invisible to Core interface users.

-- (2) NAMING BYTES. UFilePosition: PsuedoTYPE = RECORD[ i: CARDINAL, j: [0 .. 512) ] then i*512+j = byte number (byte numbers start with 0). For file length, the UFilePosition of the first free byte is used.
-- Some cases:
-- an empty file -0,0
-- a file with 1 good byte -0,1
-- a file with 511 good byes -0,511
-- a file with 512 good bytes -1,0
-- a file with 513 good bytes -1,1

OpenFile: PROCEDURE [user: DMSUser, filename: UFilename, mode: OpenMode]
RETURNS [ovD.ErrorCode, UFileHandle];
-- Opens the specified file in the specified mode, and returns a handle to the opened file. (Handles are useable until a CloseFile or DeleteFile. When OpenFile fails, i.e. ErrorCode # ok, a special handle, NIL, is returned.)
-- Error Codes: diskError, diskFull, diskCorrupted, illegalFilename, fileInUse, fileTooBig.

-- Note: All of the following operations require a UFileHandle which has been returned by a successful call to OpenFile and not yet "closed" or "deleted". And if given a UFileHandle which has been "closed" or "deleted", their operation is unpredictable. Exception: CloseFile and DeleteFile on NIL (i.e. the return of an unsuccessful call to OpenFile) is a no-op.

CloseFile: PROCEDURE [UFileHandle] RETURNS[ovD.ErrorCode];
-- Closes the specified file. (Special Case: a nop if handle = NIL.) The handle is closed and should not be re-used by the caller.
-- Error Codes: diskError.

DeleteFile: PROCEDURE [UFileHandle] RETURNS[ovD.ErrorCode];
-- Deletes the file associated with the file handle. (Special case: a nop if handle = NIL.) The handle is closed and should not be re-used by the caller.
-- Error Codes: diskError.

UFileLength: PROCEDURE [UFileHandle]
RETURNS [erc: ovD.ErrorCode, lastPage: PageNumber, byteFF: CARDINAL[0..512)];
-- Returns the first free byte in the file, i.e. its length, via the formula (lastPage*512 + byteFF). Any data that has been written since the file was opened is included. (Note, empty files return [0,0].)
-- Error Codes: (None for Alto.)

UFileTruncate: PROCEDURE [lastPage: PageNumber, byteFF: CARDINAL[0..512), uFH: UFileHandle] RETURNS[ovD.ErrorCode];
-- Shorten a file which has been opened by OpenFile. The position has the same semantics as UFileLength.
-- Do NOT use to LENGTHEN a file!
-- Error Codes: fileIsReadOnly, diskError.

ReadPages: PROCEDURE [buffer: gsD.MemoryPagePtr, byteCount: CARDINAL,
pageNumber: PageNumber, uFH: UFileHandle]
RETURNS [erc: ovD.ErrorCode, bytesRead: CARDINAL];
-- Reads up to "byteCount" bytes of data from the file asscoiated with uFH beginning with page "pageNumber" into the memory page(s) beginning at "buffer". The byteCount must be a multiple of 512 (an even page). The bytesRead returned is the count of bytes actually read and will be equal to the requested byteCount except at EOF, when it may be less. (Note that if pageNumber is beyound the end-of-file then bytesRead=0 is returned.)
-- Error Codes: diskError.

WritePages: PROCEDURE [buffer: gsD.MemoryPagePtr, byteCount: CARDINAL,
pageNumber: PageNumber, uFH: UFileHandle]
RETURNS [erc: ovD.ErrorCode];
-- Writes byteCount of data from memory, beginning at buffer, to pageNumber of the file uFH. The operation is legal only if the file was opened in update OpenMode. This can be used to extend the file’s size by writing beyond the current end. (Note, however, that the file is never shortened.) The byteCount must always be a multiple of 512, an even page, except on the last page of the file.
-- Regarding byteCount, let "remainder" be (byteCount MOD 512). If non-zero, remainder denotes the number of bytes supplied by the client to be written on the last page of the current transaction. The number of byte actually written will be the MAX[current-bytes-on-that-file-page, remainder]; the value of all bytes beyond remainder are indeterminate.
-- Side effects: Updates the file size in the uFH as needed.
-- Error Codes: fileIsReadOnly, diskFull, diskError.

-- Interfaces to file-servers. There is an Open here for each file-server; the rest of the server-specific procedures are in server-implementing modules.

AltoOpenFile, IFSOpenFile:
PROCEDURE [user: DMSUser, filename: UFilename, mode: OpenMode]
RETURNS [ovD.ErrorCode, UFileHandle];

--------------------------------------------------------------

-- I don’t know where to put this, so until it becomes obvious it goes here. This procedure is valid for the Alto only. It is exported by AltoCore (which is current an internal module to Core). I don’t know what we will provide for other file servers.

InsertInFileCache: PUBLIC PROCEDURE
[name: STRING -- to be copied--,
fH: SegmentDefs.FileHandle -- possibly NIL--];
-- Return immediately iff fH=NIL. Else insert the name/fH into the cache.

SetAltoFreePageMonitor: PROCEDURE [proc: PROCEDURE [count: CARDINAL]] ;
-- The arg, proc, is called immediately and whenever the tally of Alto free pages changes. (Note that this tally is only a hint.) To inhibit the function, call InhibitAltoFreePageMonitor.

InhibitAltoFreePageMonitor: PROCEDURE ;
-- Any free page monitoring set up by SetAltoFreePageMonitor is discontinued.

CountAltoFreePages: PROCEDURE RETURNS [freePages: CARDINAL] ;
-- Returns the number of pages available on the Alto dsik pack. This number is a real count, not just a hint.

--------------------------------------------------------------

-- Data Structures and Types.

DMSUser: TYPE = RECORD [name: DMSName, password: Password];
DMSName: TYPE = RECORD [name: STRING];
Password: TYPE = RECORD [password: STRING];

UFilename: TYPE = RECORD [filename: STRING];
-- format is: [Site]<Directory>SimpleName.Extension

UFileHandle: TYPE = POINTER TO UFileObject;

UFileObject: PRIVATE TYPE = RECORD [
access: OpenMode,
lastFilePage: PageNumber, -- Last page of the file; may contain 0 bytes.
byteFF: CARDINAL [0..512), -- First free on lastFilePage.
-- File server specific procedures.
close: PROCEDURE [UFileHandle] RETURNS [ovD.ErrorCode],
delete: PROCEDURE [UFileHandle] RETURNS [ovD.ErrorCode],
length: PROCEDURE [UFileHandle] RETURNS [ovD.ErrorCode, PageNumber, CARDINAL[0..512)],
truncate: PROCEDURE [PageNumber, CARDINAL[0..512), UFileHandle] RETURNS [ovD.ErrorCode],
read: PROCEDURE [gsD.MemoryPagePtr, CARDINAL, PageNumber, UFileHandle] RETURNS [ovD.ErrorCode, CARDINAL],
write: PROCEDURE [gsD.MemoryPagePtr, CARDINAL, PageNumber, UFileHandle] RETURNS [ovD.ErrorCode],
varpart: SELECT UFileObjectType:* FROM
alto => [handle: SegmentDefs.FileHandle,
vDATable: VDATablePtr],
iFS => [handle: POINTER --Dummy--],
ENDCASE];

OpenMode: TYPE = {
read, -- SegmentDefs.Read only; the file must exist
update --SegmentDefs.(Read+Write+Append); if the file exists then the old version is referenced; otherwise, a new file is created.
};

PageNumber: TYPE = CARDINAL;

----------------------------------------------

-- These are used by AltoCore, and are needed for AltoFileHandle.

-- This block defines the vDATable

VDATablePtr: TYPE = POINTER TO VDATable;

VDATable: TYPE = ARRAY [0 .. numberOfChunks) OF VDAsPtr;

VDAsPtr: TYPE = POINTER TO ARRAY [0 .. 0) OF AltoFileDefs.vDA;

numberOfChunks: CARDINAL = 128;

----------------------------------------------

END.; -- of Core Division definitions.

D. Wyatt, October 14, 1980 5:33 PM
increased numberOfChunks from 16 to 128