filesys.def

DEFINITION MODULE FileSys;

	(****************************************************************)
	(*								*)
	(*			File operations				*)
	(*								*)
	(*	This version is functionally equivalent to module	*)
	(*	Files, but it uses standard library calls rather than	*)
	(*	working through the PMOS device drivers.  It is		*)
	(*	recommended for use in cases where the Files module	*)
	(*	is unsuitable for reasons such as (a) I/O on a device	*)
	(*	for which a PMOS device driver does not exist, or	*)
	(*	(b) conflicts caused by a cache system which does not	*)
	(*	recognise changes to directories.			*)
	(*								*)
	(*	Note, however, that use of this module rather than	*)
	(*	module Files can limit the real-time response and	*)
	(*	cause difficulties in effective multitasking.  In	*)
	(*	particular, if the underlying operating system is	*)
	(*	MS-DOS then multiple tasks should not attempt to	*)
	(*	perform file operations in parallel.			*)
	(*								*)
	(*	Note too that the error code returned on an I/O		*)
	(*	error is a rough guess, because of the lack of		*)
	(*	correspondence between the library error codes and	*)
	(*	the standard PMOS error codes.				*)
	(*								*)
	(*	Programmer:	P. Moylan				*)
	(*	Last edited:	14 April 1993				*)
	(*	Status:		OK					*)
	(*								*)
	(****************************************************************)

FROM SYSTEM IMPORT
    (* type *)	BYTE, ADDRESS;

FROM FIO IMPORT
    (* type *)	File;

FROM IOErrorCodes IMPORT
    (* type *)	ErrorCode;

PROCEDURE OpenFile (VAR (*OUT*) f: File;  name: ARRAY OF CHAR;
					newfile: BOOLEAN): ErrorCode;

    (* Opens the file named by the given character string, and returns	*)
    (* f as the identification to be used when specifying this file in	*)
    (* future.  The caller must specify newfile = TRUE to create a new	*)
    (* file, or newfile = FALSE if the intention is to open an existing	*)
    (* file.  It is illegal to open a new file with the same name as an	*)
    (* existing file; this is to protect against accidental deletions.	*)
    (* The value returned is an error code (OK if no error).		*)

PROCEDURE CloseFile (VAR (*INOUT*) f: File);

    (* Closes file f.	*)

PROCEDURE EOF (f: File): BOOLEAN;

    (* Returns TRUE iff we are currently at the end of file f.	*)

PROCEDURE ReadByte (f: File): BYTE;

    (* Returns the next byte from the file.	*)

PROCEDURE ReadRecord (f: File;  buffaddr: ADDRESS;  desired: CARDINAL;
				VAR (*OUT*) actual: CARDINAL): ErrorCode;

    (* Reads up to "desired" bytes from file f to memory location	*)
    (* "buffaddr".  On return, "actual" gives the number of bytes read.	*)

PROCEDURE WriteByte (f: File;  value: BYTE): ErrorCode;

    (* Writes one byte to the file.	*)

PROCEDURE WriteRecord (f: File;  buffaddr: ADDRESS;
					count: CARDINAL): ErrorCode;

    (* Writes count bytes from memory location buffaddr.	*)

PROCEDURE SetPosition (f: File;  position: LONGCARD): ErrorCode;

    (* Ensures that the next read or write on this file will be at	*)
    (* byte number position in the file.  (The first byte in the file	*)
    (* is byte number 0.)  If a position greater than the file size	*)
    (* is specified, the length of the file will increase.		*)

PROCEDURE SavePosition (f: File): LONGCARD;

    (* Returns the current byte number in file f.	*)

PROCEDURE FileSize (f: File): LONGCARD;

    (* Returns the length of the file in bytes.	*)

END FileSys.