-- Copyright (C) 1981, 1984  by Xerox Corporation. All rights reserved. 
-- Transport mechanism: DEFS for logging facilities

-- [Juniper]<Grapevine>ms>LogDefs.mesa

-- HGM, 18-Nov-84  0:56:45
-- Roy Levin  February 6, 1980  5:14 PM
-- Andrew Birrell  11-Mar-81 12:32:49
-- Mark Johnson  19-May-81 13:39:52

DIRECTORY
  Process USING [Seconds];

LogDefs: DEFINITIONS =

  BEGIN
  --  The LogDefs interface defines of three separate entities:  a statistics
  -- display, a typescript, and a long-term log file.  The statistics display
  -- presents a client-defined collection of numbers that are kept up-to-date
  -- on the display screen by the implementation of LogDefs.  Each of these
  -- numbers may be displayed in one of several formats with client-supplied
  -- captions.  The typescript is a self-scrolling region of the screen to
  -- which arbitrary (ASCII) characters may be written.  The size of the
  -- region is client-controlled, and text that is scrolled off the screen
  -- is discarded.  The long-term log file contains arbitrary (ASCII)
  -- entries supplied by the client, each of which is automatically
  -- time-stamped.  This file is kept up-to-date on backing storage so as to
  -- provide a complete record of client actions.  This log does not appear
  -- on the display screen.

  -- Types and Related Constants --

  Format: TYPE = {short, long, percent};
  Percentage: TYPE = [0..100];
  DisplayItem: TYPE = RECORD [
    SELECT format: Format FROM
    short => [p: POINTER TO UNSPECIFIED],
    long => [p: POINTER TO LONG CARDINAL],
    percent => [p: POINTER TO Percentage],
    ENDCASE];

  -- Miscellaneous Declarations --
  CR: CHARACTER = 015C;
  SP, Space: CHARACTER = 040C;
  TAB: CHARACTER = 011C;
  BS: CHARACTER = 010C;
  noLimit: CARDINAL = 177777B;
  defaultRefreshInterval: Process.Seconds = 5;
  defaultTypescriptLines: CARDINAL = 4;

  -- Start/Stop Procedures --
  StatisticsOn: PROCEDURE [heading: STRING];
  -- called after all statistics specification procedures
  -- (SetStatisticsParameters and DisplayNumber) have been called. 
  -- 'heading' is an ASCII string that will be displayed at the top of
  -- the screen.  The 'heading' string need not persist in the client's
  -- storage after DisplayOn has returned.  StatisticsOn concludes with
  -- an implicit ScreenOn.

  TypescriptOn: PROCEDURE;
  -- called after the typescript specification procedure
  -- (SetTypescriptParameters) has been called.  The typescript is
  -- initialized and made ready for calls on WriteChar, WriteString, and
  -- related output procedures.  TypescriptOn concludes with an implicit
  -- ScreenOn.

  DisplayOff: PROCEDURE;
  -- DisplayOff first performs an implicit ScreenOff, then causes an
  -- orderly cleanup of the display data structures.  All information
  -- previously supplied via SetStatisticsParameters, DisplayNumber,
  -- and SetTypescriptParameters is discarded and all internal data
  -- structures are released.

  ScreenOff: PROCEDURE;
  -- turns off the display screen without affecting any of the underlying
  -- data structures.

  ScreenOn: PROCEDURE;
  -- undoes the effect of ScreenOff.


  -- Statistics Display Procedures --

  SetStatisticsParameters: PROCEDURE [
    bmPages: CARDINAL ← noLimit, font: STRING ← NIL,
    refreshInterval: Process.Seconds ← defaultRefreshInterval];
  -- This procedure alters the defaults for the statistics region of the
  -- display.  'bmPages' defines a limit on the number of bitmap pages to
  -- be allocated for statistics display.  The actual number of pages
  -- allocated will depend of the number of DisplayItems registered via
  -- DisplayNumber.  'font', if not defaulted, specifies the name of a
  -- file to be used as the font for the statistics region (don't forget
  -- ".al"!); otherwise, "Sysfont.al" will be used.  'refreshInterval' is
  -- the time in seconds between updates of the statistics display.  This
  -- procedure, if called at all, must be called before StatisticsOn.

  DisplayNumber: PROCEDURE [caption: STRING, item: DisplayItem];
  -- registers a value to be maintained on the display.  'item' defines
  -- the main memory location of the value (which must not change) and
  -- the format in which it is to be displayed.  'caption' is
  -- accompanying ASCII text.  The 'caption' string need not persist in
  -- the client's storage after DisplayNumber has returned. 
  -- DisplayNumber must be called before StatisticsOn.


  -- Typescript Procedures --

  SetTypescriptParameters: PROCEDURE [
    tsPages: CARDINAL ← noLimit, tsLines: CARDINAL ← defaultTypescriptLines,
    font: STRING ← NIL];
  -- This procedure alters the defaults for the typescript region ot the
  -- display.  Up to 'tsLines' of text will be displayed, subject to the
  -- constraint that no more than 'tsPages' of bitmap will be consumed. 
  -- 'font', if not defaulted, specifies the name of a file to be used as
  -- the font for the typescript region (don't forget ".al"!); otherwise,
  -- "Sysfont.al" will be used.  This procedure, if called at all, must
  -- be called before TypescriptOn.

  WriteChar: PROCEDURE [char: CHARACTER];
  -- writes the argument character into the typescript.  Characters > 177C
  -- will be ignored and ASCII control characters (other than CR, TAB, SP,
  -- and BS) will be printed as though the sequence WriteChar['↑];
  -- WriteChar[char+100B] had been executed.  CR, TAB, and SP cause
  -- appropriate white space to be introduced. WriteChar must be called
  -- after TypescriptOn.

  WriteString: PROCEDURE [s: STRING];
  -- writes all characters of the string into the typescript using
  -- WriteChar.

  WriteLine: PROCEDURE [s: STRING];
  -- equivalent to WriteString[s]; WriteChar[CR].

  WriteDecimal: PROCEDURE [n: CARDINAL];
  -- writes 'n' on the typescript as an unsigned, decimal quantity.


  -- Log File Procedures --

  WriteLogEntry: PROCEDURE [s: STRING];
  -- appends the argument string to the log file, prefixing it with the
  -- current time and suffixing it with a CR.

  EnableLogSpilling: PROC [name, pwd, host, path: STRING];
  -- causes the log file to be spilled to the given host each time it
  -- wraps around, using the given credentials and the Leaf protocol.
  -- the file titles used are path-name followed by our PUP address
  -- followed by serial number 0 through 39.  E.g. if path is <DMS>Log>,
  -- and we are 3#14#, files are <DMS>Log>3#14#00.



  -- Shortcuts for putting things on the screen and into the log file
  
  ShowLine: PROCEDURE [s: STRING];
  ShowTwoStrings: PROCEDURE [head: STRING, tail: STRING];
  ShowThreeStrings: PROCEDURE [head: STRING, middle: STRING, tail: STRING];
  ShowNumber: PROCEDURE [head: STRING, number: LONG CARDINAL, tail: STRING];
 
  END.