Oberon || Library || Module Index || Search Engine || Definition || Module
CONST raw = 0; (* no intermediate processing is done *)
CONST halfcooked = 1; (* compress outgoing stuff *)
CONST cooked = 2; (* check for tags & compress outgoing stuff *)
TYPE Mode = SHORTINT; (* raw..cooked *)
TYPE Tag = INTEGER;
TYPE ListOfObjects = POINTER TO ListOfObjectsRec;
TYPE ListOfObjectsRec = RECORD (Disciplines.ObjectRec) END;
TYPE Event = POINTER TO EventRec;
TYPE EventRec =
RECORD
(Events.EventRec)
s: Streams.Stream; (* NeWS stream *)
tag: Tag;
END;
CONST syntaxError = 0; (* syntax error in NEWSSERVER environment variable *)
CONST rejectedConnection = 1; (* network security violation *)
CONST errorInHexString = 2; (* bad syntax of hex string *)
CONST badInputToken = 3; (* corrupted input token *)
CONST connectionFinished = 4; (* no longer connected to NeWS server *)
CONST outOfTagNumbers = 5; (* no more unique tag numbers available *)
CONST errorcodes = 6;
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
RECORD
(Events.EventRec)
errorcode: SHORTINT;
END;
VAR errormsg: ARRAY errorcodes OF Events.Message;
VAR error: Events.EventType;
PROCEDURE Open(VAR s: Streams.Stream; mode: Mode;
errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE DefineUserToken(s: Streams.Stream; token: ARRAY OF CHAR);
(* token output operations *)
PROCEDURE PutInt(s: Streams.Stream; intval: INTEGER);
PROCEDURE PutReal(s: Streams.Stream; realval: REAL);
PROCEDURE PutString(s: Streams.Stream; string: ARRAY OF CHAR);
PROCEDURE PutUserToken(s: Streams.Stream; code: INTEGER);
(* input operations for cooked NeWS streams *)
PROCEDURE GetListOfObjects(s: Streams.Stream; tag: Tag;
VAR list: ListOfObjects) : BOOLEAN;
PROCEDURE Length(list: ListOfObjects) : INTEGER;
PROCEDURE IsInteger(list: ListOfObjects) : BOOLEAN;
PROCEDURE GetInt(list: ListOfObjects; VAR intval: LONGINT) : BOOLEAN;
PROCEDURE IsReal(list: ListOfObjects) : BOOLEAN;
PROCEDURE GetReal(list: ListOfObjects; VAR realval: REAL) : BOOLEAN;
PROCEDURE IsString(list: ListOfObjects) : BOOLEAN;
PROCEDURE GetString(list: ListOfObjects;
VAR string: ARRAY OF CHAR) : BOOLEAN;
PROCEDURE GetStringAsStream(list: ListOfObjects;
VAR s: Streams.Stream) : BOOLEAN;
PROCEDURE CreateCondition(VAR condition: Conditions.Condition;
s: Streams.Stream; tag: Tag; minlen: INTEGER);
PROCEDURE GetNotice(s: Streams.Stream; tag: Tag; minlen: INTEGER;
eventType: Events.EventType);
PROCEDURE GetUniqueTag(s: Streams.Stream; VAR tag: Tag);
PROCEDURE GetUniqueTags(s: Streams.Stream; VAR tag: Tag; count: INTEGER);
In addition to the usual text representation, the NeWS-server supports some special encodings for many tokens of the PostScript language (i.e. for numbers, strings, frequent system tokens and optionally for user defined tokens). These encodings are always introduced by a non-ASCII character and may be embedded anywhere in the ASCII-text. Encoded tokens reduce the network traffic and the overhead of the lexical analysis on the server side.
Output of the NeWS-system can be read as input. E.g. writing "(It works) print" to a NeWS stream causes "It works" to be returned on subsequent reading. Further, the NeWS-server supports the operations tagprint and typedprint which allow to send a list of objects which is introduced by a tag number. Tag numbers and objects printed by typedprint are encoded like the tokens on the input side of the NeWS-server. Typically, events of the NeWS-server side which are of interest for the client (like pressing a button) are encoded in this way.
NeWS offers three working modes with different support of token compression and input processing:
Open connects to the NeWS server and returns a stream to it with the requested working mode. Open uses the algorithm of OpenWindows Version 3 to connect to the server. Firstly, the environment variables DISPLAY and NEWSSERVER are checked and compared against the local host. If one of them is given and does not point to the local hostname, Open opens an Internet socket on port 2000 (or 2000+n for display n) of the given host. For local hosts (or if neither DISPLAY nor NEWSSERVER has been given), the UNIX domain socket at /tmp/.NeWS-unix/N followed by the display number is used.
After having connected successfully, Open passes the authorization information to the server. The X11/NeWS-server of Sun Microsystems expects X11-authorization data (even for NeWS connections) which is usally stored in the users home directory in .Xauthority and maintained by the xauth(1) command. Alternatively, it is possible to specify another authority file by use of the XAUTHORITY variable. The authorization data is passed in a way which does not confuse NeWS servers which do not require it. Open checks for successful authorization.
Streams returned by Open are buffered (independent of the working mode) and support read and write operations. They are bidirectional in the sense of Streams and do not support seek, tell or trunc operations. Further, NeWS supports the conditions of StreamConditions and a special condition type for cooked streams which allows to wait for tagged sequences with a given tag number. Implicit flushing occurs if conditions for the input side are evaluated or waited for.
DefineUserToken allows to specify frequently used tokens (e.g. names of objects or own operators). The calling order of DefineUserToken is important: the first tokens need less bytes to be encoded than tokens which has been defined later. The number of possible encodable user tokens is limited and DefineUserToken silently ignores the call if the limit is exceeded. DefineUserToken must not be called for raw streams.
While halfcooked and cooked streams compress all registered user tokens, PutUserToken allows to encode user tokens for raw streams or to circumvents the lexical analysis of halfcooked or cooked streams.
PutInt, PutReal, PutString, and PutUserToken output their parameter in encoded form. These operations may be mixed with usual output operations but note that these routines terminate most tokens but may not be used inside strings or hexstrings.
GetListOfObjects returns a list of objects which has been introduced by tag and removes it from the input queue. This operation is valid for cooked streams only. Note that the NeWS server does not support an end-of-list notation. Thus, lists are terminated by tags or ordinary input. Because GetListOfObjects is free to return a list immediately after seeing the tag, the list may grow even after accessing the list. Usually, the expected list length is known and CreateCondition allows to wait for a tag followed by a list of a given length (see below).
Not all objects of the NeWS version of PostScript are supported by typedprint. Regrettably, the current documentation about the NeWS server does not contain any hints for these cases but states that strings and numbers (integers or floating point numbers) are supported. In fact, arrays are supported too. Encoded arrays on the input side are expanded by NeWS to avoid the introduction of a non-documented NeWS-feature in the NeWS module, e.g. [ 1 2 3] typedprint is converted to three integer objects. Other objects are encoded as non-objects and converted to zero-valued integers by NeWS to achieve the correct length.
Length returns the current number of objects of the given list. As described above, the length may grow.
IsInteger returns TRUE if the next object in the list is an integer object. GetInt returns and removes an integer object from the given length. GetInt returns FALSE if the next object is not an integer or at the end of the list. IsReal and GetReal work like IsInteger and GetInt but allow also to read integer objects as reals. IsString returns TRUE if the next object in the list is a string object. Strings may be retrieved either by GetString which puts the string into a fixed-sized character arrays (silent truncation is possible; 0X-termination is guaranteed), or GetStringAsStream which allows a stream access to the string object which is suitable for arbitrary long strings.
CreateCondition creates a condition which evaluates to TRUE if a tagged sequence with the given minimal length can be accessed from the input queue. Shorter lengths are possible if the sequence has been terminated by other input (tags or ordinary input).
GetNotice causes events of type eventType to be raised for each tagged sequence with the given minimal length. The length may be shorter if the sequence has been terminated.
GetUniqueTag and GetUniqueTags assure the use of unique tags. While GetUniqueTag returns one tag number, GetUniqueTag returns count consecutive tag numbers.
By default, error messages of the NeWS server are printed onto the console window. It would be more convenient to catch those errors (by defining another error handler) and convert them into events which are related to the NeWS stream.
Oberon || Library || Module Index || Search Engine || Definition || Module