Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
LinearizedStructures

NAME

LinearizedStructures - save and load cyclic data structures

SYNOPSIS

TYPE Object = PersistentObjects.Object;



CONST missingReset = 0;      (* Reset must be called before switching mode *)
CONST cannotReadHeader = 1;  (* failed to read object header *)
CONST invalidHeader = 2;     (* corrupted/invalid object header *)
CONST cannotReadObject = 3;  (* failed to read object *)
CONST unknownKey = 4;        (* unknown key encountered *)
CONST cannotWriteHeader = 5; (* failed to write object header *)
CONST cannotWriteObject = 6; (* failed to write object *)
CONST typeGuardFailure = 7;
CONST errors = 8;
TYPE ErrorCode = SHORTINT; (* missingReset.. *)
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      errorcode: ErrorCode;
   END;
VAR error: Events.EventType;
VAR errormsg: ARRAY errors OF Events.Message;



PROCEDURE Reset(s: Streams.Stream);
PROCEDURE Read(s: Streams.Stream; VAR object: Object) : BOOLEAN;
PROCEDURE GuardedRead(s: Streams.Stream; guard: Services.Type;
                      VAR object: Object) : BOOLEAN;
PROCEDURE Write(s: Streams.Stream; object: Object) : BOOLEAN;

DESCRIPTION

LinearizedStructures supports the export and import of persistent data structures which may contain reference cycles. Just replace PersistentObjects.Read by LinearizedStructures.Read, PersistentObjects.GuardedRead by LinearizedStructures.GuardedRead, and PersistentObjects.Write by LinearizedStructures.Write. Additionally, NIL can be given to LinearizedStructures.Write and LinearizedStructures.Read may return NIL.

LinearizedStructures works by attaching disciplines to the given stream and the objects being read. Reset allows to remove these disciplines and is required on switching from reading to writing and vice versa.

Please note that the objects must be read in the same order as they have been written before. It's wise to call Reset before and after a sequence of read and write operations and to avoid seek operations during saving/loading and stream positioning inside a group of objects.

DIAGNOSTICS

Errors and failures detected by LinearizedStructures lead to events which are related to the stream. Following error codes are implemented:
missingReset
Reset wasn't called before switching from reading to writing mode.
cannotReadHeader
Read wasn't able to read an object header.
invalidHeader
An invalid or corrupted header was read by Read.
cannotReadObject
PersistentObjects.Read failed for some reason.
unknownKey
An object header references a yet unknown object. This may happen if reading didn't start at the beginning of the list or some objects were skipped.
cannotWriteHeader
Write was unable to write an object header.
cannotWriteObject
PersistentObjects.Write failed for some reason.
typeGuardFailure
The guard of GuardedRead did not match the type of the object read.

SEE ALSO

ModularizedStructures
distributed graphs of persistent objects across multiple byte sequences
PersistentObjects
input and output of persistent objects
RelatedEvents
error handling
Edited by: borchert, last change: 2004/06/03, revision: 1.4, converted to HTML: 2004/06/03

Oberon || Library || Module Index || Search Engine || Definition || Module