DEFINITION MODULE ScreenIO;

(* Author:         Andrew Trevorrow
   Implementation: University of Hamburg Modula-2 under VAX/VMS version 4
   Date Started:   September, 1984

   Description:
   These terminal i/o routines are highly system dependent and have been
   targeted at just one client: DVItoVDU.
   Other client modules need to be aware of a few implementation details:
   - The terminal channel will be set automatically to /ttsync/nowrap.
     Client should call RestoreTerminal before finishing or use Halt to finish.
     Note that Halt will NOT display any message, unlike Hamburg's HALT.
     It can also be used to set the VMS $SEVERITY value:
        Halt(0) exits and sets $SEVERITY to Warning.
        Halt(1) exits and sets $SEVERITY to Success.
        Halt(2) exits and sets $SEVERITY to Error.
   - Output buffering is used to minimize QIO overheads.
     WriteBuffer or WriteLn must be called to update the terminal
     (e.g., just before a read) or to synchronize output with writes
     from other modules that don't use ScreenIO.

   Revised:
   December, 1984
 - Added BusyRead and RestoreTerminal.
   May, 1985
 - Added Read, ReadString and Halt.
   August, 1985
 - BusyRead now a function.
 - WriteCard and WriteInt no longer have a field width
   parameter; they simply write the minimum number of
   characters needed.  (There was only ONE place that used
   a fixed field width and that was in debugging code!)
*)

PROCEDURE Read (VAR ch : CHAR);
(* Read one character from terminal keyboard. *)

PROCEDURE ReadString (VAR s : ARRAY OF CHAR);
(* Read a string of characters from terminal keyboard.
   DEL can be used to erase the last character entered.
   The routine is terminated upon CR, CTRL/Z, or an ESC sequence if line
   editing is enabled, otherwise upon 0..37C (except for LF, VT, FF, TAB, BS).
   Got that?!  Termination also occurs if s becomes full.
   If s is not full then NULLs are used to pad out the string.
   Under version 4 of VMS, line editing is possible on a VT100 compatible VDU.
*)

PROCEDURE BusyRead (VAR ch : CHAR) : BOOLEAN;
(* Return TRUE iff ch is read (with no echo) from type-ahead buffer.
   If nothing in type-ahead buffer then ch is undefined and we return FALSE.
*)

PROCEDURE Write (ch: CHAR);
(* Write given character to output buffer. *)

PROCEDURE WriteString (s: ARRAY OF CHAR);
(* Write given string of characters to output buffer.
   s is terminated by first NULL (unless full).
*)

PROCEDURE WriteInt (i : INTEGER);
(* Write a string of characters representing given integer to output buffer. *)

PROCEDURE WriteCard (c : CARDINAL);
(* Write a string of characters representing given cardinal to output buffer. *)

PROCEDURE WriteLn;
(* Write CR LF and then send output buffer to terminal. *)

PROCEDURE WriteBuffer;
(* Send output buffer to terminal; this is done automatically when it becomes
   full but an explicit call may be necessary to ensure the terminal screen
   is up-to-date.
*)

PROCEDURE RestoreTerminal;
(* Restore previous terminal channel characteristics. *)

PROCEDURE Halt (status : CARDINAL);
(* Calls WriteBuffer, RestoreTerminal and then SYS$EXIT with
   the given status: 0 = warning, 1 = success, 2 = error.
   No message is generated.
*)

END ScreenIO.
