362 lines
14 KiB
Plaintext
362 lines
14 KiB
Plaintext
DEFINITION MODULE FileSystem;
|
||
(*
|
||
file manipulation routines
|
||
|
||
Derived from the Modula-2 system developed by the
|
||
group of Prof. N. Wirth, ETH Zurich, Switzerland.
|
||
*)
|
||
|
||
|
||
FROM SYSTEM IMPORT ADDRESS, WORD;
|
||
|
||
EXPORT QUALIFIED
|
||
(* file operations: *)
|
||
File, Response, Command,
|
||
Create, Close, Lookup, Rename, Delete,
|
||
SetRead, SetWrite, SetModify, SetOpen,
|
||
Doio, SetPos, GetPos, Length,
|
||
|
||
(* Streamlike I/O: *)
|
||
Flag, FlagSet,
|
||
Reset, Again,
|
||
ReadWord, ReadChar, ReadByte, ReadNBytes,
|
||
WriteWord, WriteChar, WriteByte, WriteNBytes,
|
||
|
||
(* Medium Handling: *)
|
||
FileProc, DirectoryProc,
|
||
MediumType, CreateMedium, RemoveMedium,
|
||
|
||
FileNameChar;
|
||
|
||
|
||
TYPE MediumHint = CARDINAL;
|
||
(*- medium index used in DiskFiles *)
|
||
|
||
MediumType = ARRAY [0..2] OF CHAR;
|
||
(*- medium name (A, B...) *)
|
||
|
||
Flag = (er, ef, rd, wr, ag, txt);
|
||
(*- status flag for file operations
|
||
|
||
er = error occured, ef = end-of-file reached, rd = in read mode, wr = in
|
||
write mode, ag = "Again" has been called after last read, txt = text-file
|
||
(the last access to the file was a 'WriteChar' or 'ReadChar').
|
||
*)
|
||
|
||
FlagSet = SET OF Flag;
|
||
(*- status flag set *)
|
||
|
||
Response = (done, notdone, notsupported, callerror, unknownmedium,
|
||
unknownfile, paramerror, toomanyfiles, eom, userdeverror);
|
||
(*- result of a file operation *)
|
||
|
||
Command = (create, close, lookup, rename, delete, setread, setwrite,
|
||
setmodify, setopen, doio, setpos, getpos, length);
|
||
(*- commands passed to DiskFiles *)
|
||
|
||
BuffAdd = POINTER TO ARRAY [0..0FFFEH] OF CHAR;
|
||
(*- file buffer pointer type *)
|
||
|
||
File = RECORD
|
||
bufa: BuffAdd; (* Buffer Address *)
|
||
buflength: CARDINAL;
|
||
(* size of buffer in bytes. In the current release
|
||
it is always a multiple of 128 *)
|
||
validlength: CARDINAL;
|
||
(* Number of valid bytes in the buffer. *)
|
||
bufind: CARDINAL;
|
||
(* Byte-Index of current position in the buffer *)
|
||
flags: FlagSet; (* status of the file *)
|
||
eof: BOOLEAN;
|
||
(* TRUE, if last access was past end of file *)
|
||
res: Response; (* result of last operation *)
|
||
lastRead:CARDINAL;(* the last read word or byte (char) *)
|
||
mt: MediumType;
|
||
(* selects the driver that supports that file *)
|
||
fHint: CARDINAL; (* internally used by the device-driver *)
|
||
mHint: MediumHint; (* internally used by medium-handler *)
|
||
CASE com: Command OF
|
||
lookup: new: BOOLEAN;
|
||
| setpos, getpos, length: highpos, lowpos: CARDINAL;
|
||
END;
|
||
END;
|
||
(*- file structure used for bookkeeping by DiskFiles *)
|
||
|
||
PROCEDURE Create (VAR f: File; mediumName: ARRAY OF CHAR);
|
||
(*- create a temporary file
|
||
in: mediumName name of medium to create file on, in char format
|
||
out: f initialized file structure
|
||
|
||
A temporary file is characterised by an empty name. To make the file
|
||
permanent, it has to be renamed with a non-empty name before closing it.
|
||
For subsequent operations on this file, it is referenced by "f".
|
||
*)
|
||
|
||
PROCEDURE Close (VAR f: File);
|
||
(*- Close a file
|
||
in: f structure referencing an open file
|
||
out: f the field f.res will be set appropriately.
|
||
|
||
Terminates the operations on file "f". If "f" is a temporary file, it will
|
||
be destroyed, whereas a file with a non-empty name remains on its medium
|
||
and is accessible through "Lookup". When closing a text-file after writing,
|
||
the end-of-file code 32C is written on the file (MS-DOS and CP/M convention).
|
||
*)
|
||
|
||
PROCEDURE Lookup (VAR f: File; filename: ARRAY OF CHAR; newFile: BOOLEAN);
|
||
(*- look for a file
|
||
in: filename drive and name of file to search for
|
||
newFile TRUE if file should be created if not found
|
||
out: f initialized file structure; f.res will be set
|
||
appropriately.
|
||
|
||
Searches the medium specified in "filename" for a file that matches the
|
||
name and type given in "filename". If the file is not found and "newFile"
|
||
is TRUE, a new (permanent) file with the given name and type is created.
|
||
If it is not found and "newFile" is FALSE, no action takes place and
|
||
"notdone" is returned in the result field of "f".
|
||
*)
|
||
|
||
PROCEDURE Rename (VAR f: File; newname: ARRAY OF CHAR);
|
||
(*- rename a file
|
||
in: f structure referencing an open file
|
||
newname filename to rename to, with device:name.type specified
|
||
out: f file name in f will be changed and the f.res field will
|
||
be set appropriately.
|
||
|
||
The medium, on which the files reside can not be changed with this command.
|
||
The medium name inside "newname" has to be the old one.
|
||
*)
|
||
|
||
PROCEDURE Delete (name: ARRAY OF CHAR; VAR f: File);
|
||
(*- delete a file
|
||
in: name name of file to delete, with dev:name.type specified
|
||
out: f the result field f.res will be set appropriately.
|
||
*)
|
||
|
||
PROCEDURE ReadWord (VAR f: File; VAR w: WORD);
|
||
(*- Returns the word at the current position in f
|
||
in: f structure referencing an open file
|
||
out: w word read from file
|
||
f the result field f.res will be set appropriately.
|
||
|
||
the file will be positioned at the next word when the read is done.
|
||
*)
|
||
|
||
PROCEDURE WriteWord (VAR f: File; w: WORD);
|
||
(*- Write one word to a file
|
||
in: f structure referencing an open file
|
||
w word to write
|
||
out: f the field f.res will be set appropriately.
|
||
*)
|
||
|
||
PROCEDURE ReadChar (VAR f: File; VAR ch: CHAR);
|
||
(*- Read one character from a file
|
||
in: f structure referencing an open file
|
||
out: ch charatcter read from file
|
||
f the result field f.res will be set appropriately.
|
||
|
||
the file will be positioned at the next character when the read is done.
|
||
*)
|
||
|
||
PROCEDURE WriteChar (VAR f: File; ch: CHAR);
|
||
(*- Write one character to a file
|
||
in: f structure referencing an open file
|
||
ch character to write
|
||
out: f the result field f.res will be set apporopriately.
|
||
*)
|
||
|
||
PROCEDURE ReadByte (VAR f: File; VAR b: CHAR);
|
||
(*- Read one byte from a file
|
||
in: f structure referencing an open file
|
||
out: b byte read from file
|
||
f the result field f.res will be set appropriately.
|
||
|
||
the file will be positioned at the next byte when the read is completed.
|
||
*)
|
||
|
||
PROCEDURE WriteByte (VAR f: File; b: CHAR);
|
||
(*- Write one byte to a file
|
||
in: f structure referencing an open file
|
||
b byte to write
|
||
out: f the result field f.res will be set appropriately.
|
||
*)
|
||
|
||
PROCEDURE ReadNBytes (VAR f: File; bufPtr: ADDRESS;
|
||
requestedBytes: CARDINAL; VAR read: CARDINAL);
|
||
(*- Read a specified number of bytes from a file
|
||
in: f structure referencing an open file
|
||
bufPtr pointer to buffer area to read bytes into
|
||
requestedBytes number of bytes to read
|
||
out: bufPtr^ bytes read from file
|
||
f the result field f.res will be set appropriately.
|
||
read the number of bytes actually read.
|
||
|
||
the file will be positioned at the next byte after the requested string.
|
||
*)
|
||
|
||
PROCEDURE WriteNBytes (VAR f: File; bufPtr: ADDRESS;
|
||
requestedBytes: CARDINAL; VAR written: CARDINAL);
|
||
(*- Write a specified number of bytes to a file
|
||
in: f structure referencing an open file
|
||
bufPtr pointer to string of bytes to write
|
||
requestedBytes number of bytes to write
|
||
out: f the result field f.res will be set appropriately.
|
||
written the number of bytes actually written
|
||
*)
|
||
|
||
PROCEDURE Again (VAR f: File);
|
||
(*- returns a character to the buffer to be read again
|
||
in: f structure referencing an open file
|
||
out: f the f.res field will be set appropriately.
|
||
|
||
This should be called after a read operation only (it has no effect
|
||
otherwise). It prevents the subsequent read from reading the next element;
|
||
the element just read before will be returned a second time. Multiple calls
|
||
to Again without a read in between have the same effect as one call to
|
||
Again. The position in the file is undefined after a call to Again (it is
|
||
defined again after the next read operation).
|
||
*)
|
||
|
||
PROCEDURE SetRead (VAR f: File);
|
||
(*- Set the file in reading-state, without changing the current position.
|
||
in: f structure referencing an open file
|
||
out: f f.res will be set appropriately.
|
||
|
||
Upon calling SetRead, the current position must be before the eof.
|
||
In reading-state, no writing is allowed.
|
||
*)
|
||
|
||
PROCEDURE SetWrite (VAR f: File);
|
||
(*- Sets the file in writing-state, without changing the current position.
|
||
in: f structure referencing an open file
|
||
out: f f.res will be set appropriately.
|
||
|
||
Upon calling SetWrite, the current position must be a legal position in
|
||
the file (including eof). In writing-state, no reading is allowed, and
|
||
a write always takes place at the eof. The current implementation does
|
||
not truncate the file.
|
||
*)
|
||
|
||
PROCEDURE SetModify (VAR f: File);
|
||
(*- Sets the file in modifying-state, without changing the current position.
|
||
in: f structure referencing an open file
|
||
out: f f.res will be set appropriately.
|
||
Upon calling SetModify, the current position must be before the eof.
|
||
In modifying-state, reading and writing are allowed. Writing is done
|
||
at the current position, overwriting whatever element is already there.
|
||
The file is not truncated.
|
||
*)
|
||
|
||
PROCEDURE SetOpen (VAR f: File);
|
||
(*- Set the file to opened-state, without changing the current position.
|
||
in: f structure referencing an open file
|
||
out: f f.res will be set appropriately.
|
||
|
||
The buffer content is written back on the file, if the file has been in
|
||
writing or modifying status. The new buffer content is undefined.
|
||
In opened-state, neither reading nor writing is allowed.
|
||
*)
|
||
|
||
PROCEDURE Reset (VAR f: File);
|
||
(*- Set the file to opened state and position it to the top of file.
|
||
in: f structure referencing an open file
|
||
out: f f.res will be set appropriately.
|
||
*)
|
||
|
||
PROCEDURE SetPos (VAR f: File; high, low: CARDINAL);
|
||
(*- Set the current position in file
|
||
in: f structure referencing an open file
|
||
high high part of the byte offset
|
||
low low part of the byte offset
|
||
out: f f.res will be set appropriately.
|
||
|
||
The file will be positioned (high*2^16 +low) bytes from top of file.
|
||
*)
|
||
|
||
PROCEDURE GetPos (VAR f: File; VAR high, low: CARDINAL);
|
||
(*- Return the current byte position in file
|
||
in: f structure referencing an open file
|
||
out: high high part of byte offset
|
||
low low part of byte offset
|
||
|
||
The actual position is (high*2^16 +low) bytes from the top of file.
|
||
*)
|
||
|
||
PROCEDURE Length (VAR f: File; VAR high, low: CARDINAL);
|
||
(*- Return the length of the file in bytes.
|
||
in: f structure referencing an open file.
|
||
out: high high part of byte offset
|
||
low ;pw part of byte offset
|
||
|
||
The actual length is (high*2^16 +low) bytes.
|
||
*)
|
||
|
||
PROCEDURE Doio (VAR f: File);
|
||
(*- Do various read/write operations on a file
|
||
in: f structure referencing an open file
|
||
out: f f.res will be set appropriately.
|
||
|
||
The exact effect of this command depends on the state of the file (flags):
|
||
opened = NOOP.
|
||
reading = reads the record that contains the current byte from the
|
||
file. The old content of the buffer is not written back.
|
||
writing = the buffer is written back. It is then assigned to the
|
||
record, that contains the current position. Its content
|
||
is not changed.
|
||
modifying = the buffer is written back and the record containing
|
||
the current position is read.
|
||
Note that 'Doio' does not need to be used when reading through the
|
||
'stream-like' I/O routines. Its use is limited to special applications.
|
||
*)
|
||
|
||
|
||
PROCEDURE FileNameChar (c: CHAR): CHAR;
|
||
(*- Check the character c for legality in an MS-DOS filename.
|
||
in: c charater to check
|
||
out: 0C for illegal characters and c otherwise; lowercase
|
||
letters are transformed into uppercase letters.
|
||
*)
|
||
|
||
TYPE FileProc = PROCEDURE (VAR File);
|
||
(*- Procedure type to be used for internal file operations
|
||
|
||
A procedure of this type will be called for the functions:
|
||
setread, setwrite, setmodify, setopen, doio,
|
||
setpos, getpos, length, setprotect, getprotect,
|
||
setpermanent, getpermanent.
|
||
*)
|
||
|
||
DirectoryProc = PROCEDURE (VAR File, ARRAY OF CHAR);
|
||
(*- Procedure type to be used for operations on an entire file
|
||
|
||
A procedure of this type will be called for the functions:
|
||
create, close, lookup, rename, delete.
|
||
*)
|
||
|
||
PROCEDURE CreateMedium (mt: MediumType;
|
||
fproc: FileProc; dproc: DirectoryProc;
|
||
VAR done: BOOLEAN);
|
||
(*- Install the medium "mt" in the file system
|
||
in: mt medium type to install
|
||
fproc procedure to handle internal file operations
|
||
dproc procedure to handle operations on an entire file
|
||
out done TRUE if medium was successfully installed.
|
||
|
||
Before accessing or creating a file on a medium, this medium has to be
|
||
announced to the file system by means of the routine CreateMedium.
|
||
FileSystem calls "fproc" and "dproc" to perform operations on a file of
|
||
this medium. Up to 24 mediums can be announced.
|
||
*)
|
||
|
||
PROCEDURE RemoveMedium (mt: MediumType; VAR done: BOOLEAN);
|
||
(*- Remove the medium "mt" from the file system
|
||
in: mt medium type to remove
|
||
out: done true if medium was successfully removed
|
||
|
||
Attempts to access a file on this medium result in an error (unknownmedium).
|
||
*)
|
||
|
||
|
||
END FileSystem.
|
||
|