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

Ulm's Oberon Library:


NeWS - interface to the Network/extensible Window System


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 ListOfObjects = POINTER TO ListOfObjectsRec;
TYPE ListOfObjectsRec = RECORD (Disciplines.ObjectRec) END;
TYPE Event = POINTER TO EventRec;
TYPE EventRec =
      s: Streams.Stream; (* NeWS stream *)
      tag: Tag;
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 =
      errorcode: SHORTINT;
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);


NeWS provides the basic communication facilities for the equally named window system. The window system is represented by a server process whose protocol is based upon an extension of PostScript. Hence, the communication is based on ordinary texts in ASCII representation in comparison to other protocols (e.g. X11) which use binary records.

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:

provides a raw connection to the NeWS-server. No input or output processing is done. While the advanced input operations may not be used for this mode, the output operations (PutInt, PutReal etc.) may be used to compress tokens.
requests the lexical analysis of the PostScript language to be done on the client side and to encode tokens whenever possible. The input side remains unprocessed.
offers the facilities of the halfcooked mode and removes all tagged object lists from the input queue. Further, it guarantees that write operations will never block due to not yet processed input. Tagged object lists may be accessed by giving a tag number. Accesses to tagged object lists need not to be in the order of arrival. It is in the responsibility of the NeWS stream user to process everything which has been requested before to be sent over the communication channel. The stream implementation collects everything on the input side until it gets processed. The more unprocessed input the more memory usage.

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.


Beside of connection related I/O errors, following errors are detected by the NeWS module and lead to error events which are related to the stream or the errors parameter:
a syntax error has been found either in the DISPLAY or NEWSSERVER environment variable. See below for the correct format.
indicates a network security violation, i.e. the authentication was not successful. This may result from missing or wrong authentication files.
a hex string was given in an invalid form.
an input token which has been written by the NeWS server has been found in a corrupted form.
the connection has been either broken or finished.
indicates that no more unique tag numbers are available.


specifies the host of the NeWS server and the display to be used in the form hostname:display.
specifies the users home directory.
specifies the Internet address, the port number, and the host name of the NeWS server in the form address.port;hostname.
specifies the name of the X authority file.


UNIX domain socket of the NeWS server
default X authority file


generates a string for the NEWSSERVER environment variable
X authority file utility
X11/NeWS server
error event handling
stream operations
stream conditions which allow to wait for available input or nonblocking output
PostScript Language
Reference Manual, Adobe Systems Inc., Addison-Wesley
NeWS Programmer's Guide
documents the extensions of the PostScript language and the NeWS protocol


NeWS is part of the NeWS-library, i.e. +lNeWS must be specified for mmo.


The implementation of NeWS depends on the current version of the NeWS protocol and the current version of UNIX. While all dependencies are documented above, the interface itself is independent of the NeWS version and client modules should not rely on these informations (e.g. trying to send arrays by typedprint or printing error messages which mention one of the environment variables).

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.

Edited by: borchert, last change: 2003/07/10, revision: 1.3, converted to HTML: 2003/07/10

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