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

Ulm's Oberon Library:
PersistentEvents

NAME

PersistentEvents - support of persistent events

SYNOPSIS

TYPE WriteProc = PROCEDURE (s: Streams.Stream; event: Events.Event) : BOOLEAN;
TYPE ReadProc = PROCEDURE (s: Streams.Stream;
                           VAR event: Events.Event) : BOOLEAN;
TYPE Interface = POINTER TO InterfaceRec;
TYPE InterfaceRec =
   RECORD
      (Objects.ObjectRec)
      write: WriteProc;
      read: ReadProc;
   END;



CONST bogusInput = 0; unknownEventType = 1; errors = 2;
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      code: SHORTINT;
      typeName: ARRAY 80 OF CHAR; (* in case of unknownEventType *)
   END;
VAR errormsg: ARRAY errors OF Events.Message;
VAR error: Events.EventType;



PROCEDURE Init(eventType: Events.EventType;
               name: ARRAY OF CHAR; if: Interface);
PROCEDURE Write(s: Streams.Stream; event: Events.Event) : BOOLEAN;
PROCEDURE Read(s: Streams.Stream; VAR event: Events.Event) : BOOLEAN;
PROCEDURE WriteErrors(s: Streams.Stream;
                      errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE ReadErrors(s: Streams.Stream;
                     VAR errors: RelatedEvents.Object) : BOOLEAN;

DESCRIPTION

PersistentEvents supports the exchange of events and error lists through PersistentObjects or similar methods. Events are not persistent objects in the sense of PersistentObjects but in cases of a close relationship between event record types and event types it is possible to attach the associated marshalling procedures at the event type. In cases where no support for persistence is given, only texts of error messages (including the output of Errors.Write) are preserved.

Init allows to attach marshalling procedures to an event type which will be later used if this event type is given in the type component of the event record. The interface is expected to meet following specification:

write: PROCEDURE(s: Streams.Stream; event: Events.Event) : BOOLEAN;: convert the given event record into a sequence of bytes. Note that the basic components of the event record (i.e. message and type) are not saved by the calling environment and that there is no guarantee about the type of event. FALSE is to be returned in case of errors.
read: PROCEDURE(s: Streams.Stream; VAR event: Events.Event) : BOOLEAN;: create and restore the event from the input.

Write outputs the given event to the stream s in a form which may be later read by Read.

WriteErrors is intended for error objects which have an event queue (see RelatedEvents) and writes the list of queued error events which is attached to errors to the given stream. Despite to Conclusions, the error queue gets not removed afterwards. A error list written by WriteErrors may be later read by ReadErrors.

DIAGNOSTICS

All procedures return FALSE in case of failures. Errors are related to the given streams.

bogusInput: is raised by Read (or ReadErrors) in case of invalid input (which does not look as it would have been generated by the corresponding Write operation).
unknownEventType: is raised by Read (or ReadErrors) if the event type is not supported by the reading side even after trying to load the necessary modules dynamically.

BUGS

Unlike PersistentObjects, PersistentEvents is not able to skip events in the input correctly if it is unable to read it (error unknownEventType). Thus, events should be embedded in persistent objects (in the sense of PersistentObjects) if error recovery is a concern.

Edited by: borchert, last change: 1995/12/13, revision: 1.2, converted to HTML: 1997/04/28