Modules/Files

From vishap oberon compiler
Jump to: navigation, search

Deutsch (de) | English (en) | Հայերեն (hy)

Module Files

Module Files provides operations on files and the file directory.

Definition

Module Files has the following interface.

DEFINITION Files;
 
 IMPORT SYSTEM;
 
 TYPE
   File = POINTER TO Handle;
  Rider = RECORD
     eof: BOOLEAN;
     res: LONGINT;
  END;
 
   PROCEDURE Old (name: ARRAY OF CHAR): File;
   PROCEDURE New (name: ARRAY OF CHAR): File;
   PROCEDURE Register (f: File);
   PROCEDURE Close (f: File);
   PROCEDURE Purge (f: File);
   PROCEDURE Delete (name: ARRAY OF CHAR; VAR res: INTEGER);
   PROCEDURE Rename (old, new: ARRAY OF CHAR; 
			  VAR res: INTEGER);
   PROCEDURE Length (f: File): LONGINT;
   PROCEDURE GetDate (f: File; VAR t, d: LONGINT);
   PROCEDURE Set (VAR r: Rider; f: File; pos: LONGINT);
   PROCEDURE Pos (VAR r: Rider): LONGINT;
   PROCEDURE Base (VAR r: Rider): File;
   PROCEDURE Read (VAR r: Rider; VAR x: SYSTEM.BYTE);
   PROCEDURE ReadInt (VAR R: Rider; VAR x: INTEGER);
   PROCEDURE ReadLInt (VAR R: Rider; VAR x: LONGINT);
   PROCEDURE ReadReal (VAR R: Rider; VAR x: REAL);
   PROCEDURE ReadLReal (VAR R: Rider; VAR x: LONGREAL);
   PROCEDURE ReadNum (VAR R: Rider; VAR x: LONGINT);
   PROCEDURE ReadString (VAR R: Rider; VAR x: ARRAY OF CHAR);
   PROCEDURE ReadSet (VAR R: Rider; VAR x: SET);
   PROCEDURE ReadBool (VAR R: Rider; VAR x: BOOLEAN;
   PROCEDURE ReadBytes (VAR r: Rider;
			     VAR x: ARRAY OF SYSTEM.BYTE;
 			     n: LONGINT);
   PROCEDURE Write (VAR r: Rider; x: SYSTEM.BYTE); 
   PROCEDURE WriteInt (VAR R: Rider; x: INTEGER);
   PROCEDURE WriteLInt (VAR R: Rider; x: LONGINT);
   PROCEDURE WriteReal (VAR R: Rider; x: REAL);
   PROCEDURE WriteLReal (VAR R: Rider; x: LONGREAL);
   PROCEDURE WriteNum (VAR R: Rider; x: LONGINT);
   PROCEDURE WriteString (VAR R: Rider; x: ARRAY OF CHAR);
   PROCEDURE WriteSet (VAR R: Rider; x: SET);
   PROCEDURE WriteBool (VAR R: Rider; x: BOOLEAN);
   PROCEDURE WriteBytes (VAR r: Rider; 
			      VAR x: ARRAY OF SYSTEM.BYTE; 
			      n: LONGINT)
END Files.

Types

  • A File represents a stream of bytes usually stored on an external medium. It has a certain length as well as the date and time of its last modification.
  • A file directory is a mapping from file names to files. A file that is not registered in the directory is considered temporary.
  • A Rider is a read/write position in a file (positions start with 0). There may be multiple riders set to the same file. The field eof is set to TRUE if an attempt was made to read beyond the end of the file. The field res reports the success of ReadBytes and WriteBytes operations. Writing data overwrites old data at the rider position. When data is written beyond the end of the file, the file length increases.

Operations on files and the file directory

  • Old(fn) searches the name fn in the directory and returns the corresponding file. If the name is not found, it returns NIL.
  • New(fn) creates and returns a new file. The name fn is remembered for the later use of the operation Register. The file is only entered into the directory when Register is called.
  • Register(f) enters the file f into the directory together with the name provided in the operation New that created f. The file buffers are written back. Any existing mapping of this name to another file is overwritten.
  • Close(f) writes back the file buffers of f. The file is still accessible by its handle f and the riders positioned on it. If a file is not modified it is not necessary to close it.
  • Purge(f) resets the length of file f to 0.
  • Delete(fn, res) removes the directory entry for the file fn without deleting the file. If res=0 the file has been successfully deleted. If there are variables referring to the file while Delete is called, they can still be used.
  • Rename(oldfn, newfn, res) renames the directory entry oldfn to newfn. If res=0 the file has been successfully renamed. If there are variables referring to the file while Rename is called, they can still be used.
  • Length(f) returns the number of bytes in file f.
  • GetDate(f, t, d) returns the time t and date d of the last modification of file f. The encoding is: hour = t DIV 4096; minute = t DIV 64 MOD 64; second = t MOD 64; year = d DIV 512; month = d DIV 32 MOD 16; day = d MOD 32.

Operations on riders

  • Set(r, f, pos) sets the rider r to position pos in file f. The field r.eof is set to FALSE. The operation requires that 0 <= pos < Length(f).
  • Pos(r) returns the position of the rider r.
  • Base(r) returns the file to which the rider r has been set.

Operations for unformatted input and output

In general, all operations must use the following format for external representation:

  • 'Little endian' representation (i.e., the least significant byte of a word is the one with the lowest address on the file).
  • Numbers: SHORTINT 1 byte, INTEGER 2 bytes, LONGINT 4 bytes
  • Sets: 4 bytes, element 0 is the least significant bit
  • Booleans: single byte with FALSE = 0, TRUE = 1
  • Reals: IEEE standard; REAL 4 bytes, LONGREAL 8 bytes
  • Strings: with terminating 0X

Reading

  • Read(r, x) reads the next byte x from rider r and advances r accordingly.
  • ReadInt(r, i) and ReadLInt(r, i) read a (long) integer number i from rider r and advance r accordingly.
  • ReadReal(r, x) and ReadLReal(r, x) read a (long) real number x from rider r and advance r accordingly.
  • ReadNum(r, i) reads an integer number i from rider r and advances r accordingly. The number i is compactly encoded (see remarks below).
  • ReadString(r, s) reads a sequence of characters (including the terminating 0X) from rider r and returns it in s. The rider is advanced accordingly. The actual parameter corresponding to s must be long enough to hold the character sequence plus the terminating 0X.
  • ReadSet(r, s) reads a set s from rider r and advances r accordingly.
  • ReadBool(r, b) reads a Boolean value b from rider r and advances r accordingly.
  • ReadBytes(r, buf, n) reads n bytes into buffer buf starting at the rider position r. The rider is advanced accordingly. If less than n bytes could be read, r.res contains the number of requested but unread bytes.

Writing

  • Write(r, x) writes the byte x to rider r and advances r accordingly.
  • WriteInt(r, i) and WriteLInt(r, i) write the (long) integer number i to rider r and advance r accordingly.
  • WriteReal(r, x) and WriteLReal(r, x) write the (long) real number x to rider r and advance r accordingly.
  • WriteString(r, s) writes the sequence of characters s (including the terminating 0X) to rider r and advances r accordingly.
  • WriteNum(r, i) writes the integer number i to rider r and advances r accordingly. The number i is compactly encoded (see remarks below).
  • WriteSet(r, s) writes the set s to rider r and advances r accordingly.
  • WriteBool(r, b) writes the Boolean value b to rider r and advances r accordingly.
  • WriteBytes(r, buf, n) writes the first n bytes from buf to rider r and advances r accordingly. r.res contains the number of bytes that could not be written (e.g., due to a disk full error).

Examples

VAR f: Files.File; r: Files.Rider; ch: CHAR;

Reading from an existing file xxx:

  f := Files.Old("xxx");
  IF f # NIL THEN
    Files.Set(r, f, 0);
    Files.Read(r, ch);
    WHILE ~ r.eof DO ... Files.Read(r, ch) END
  END;

Writing to a new file yyy:

  f := Files.New("yyy");
  Files.Set(r, f, 0);
  Files.WriteInt(r, 8); Files.WriteString(r, " bytes");
  Files.Register(f)

Remarks

WriteNum and ReadNum, should use the following encoding algorithms for conversion to and from external format.

PROCEDURE WriteNum (VAR r: Rider; x: LONGINT);
BEGIN
   WHILE (x < - 64) OR (x > 63) DO 
	    Write(r, CHR(x MOD 128 + 128)); x := x DIV 128
   END;
   Write(r, CHR(x MOD 128))
END WriteNum;
 
PROCEDURE ReadNum (VAR r: Rider; VAR x: LONGINT);
   VAR s: SHORTINT; ch: CHAR; n: LONGINT;
BEGIN 
   s := 0; n := 0;
   Read(r, ch);
   WHILE ORD(ch) >= 128 DO
      INC(n, ASH(ORD(ch) - 128, s) );
      INC(s, 7);
      Read(r, ch)
   END;
   x := n + ASH(ORD(ch) MOD 64 - ORD(ch) DIV 64 * 64, s)
END ReadNum;
  • The reason for the specification of the file name in the operation New is to allow allocation of the file on the correct medium from the beginning (if the operating system supports multiple media).

The operations Read, Write, ReadBytes and WriteBytes require the existence of a type SYSTEM.BYTE with the following characteristics:

  • If a formal parameter is of type SYSTEM.BYTE the corresponding actual parameter may be of type CHAR, SHORTINT, or SYSTEM.BYTE.
  • If a formal variable parameter is of type ARRAY OF SYSTEM.BYTE the corresponding actual parameter may be of any type. Note that this feature is dangerous and inherently unportable. Its use should therefore be restricted to system-level modules.

Origin

This module is part of the ETH Oberon System. The above specification was proposed by H. Mössenbock, ETH.

This article was created by using Oakwood Guidelines as a source.