-- Copyright (C) 1981, 1984, 1985 by Xerox Corporation. All rights reserved.
-- Transport mechanism: DEFS for logging facilities
-- LogDefs.mesa, HGM, 14-Sep-85 20:20:31
-- 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],
PupTypes USING [PupAddress];
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: LONG 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: LONG 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: LONG 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: LONG 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: LONG STRING];
-- writes all characters of the string into the typescript using
-- WriteChar.
WriteLine: PROCEDURE [s: LONG 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: LONG 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: LONG 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: LONG STRING];
ShowTwoStrings: PROCEDURE [head: LONG STRING, tail: LONG STRING];
ShowThreeStrings: PROCEDURE [head: LONG STRING, middle: LONG STRING, tail: LONG STRING];
ShowNumber: PROCEDURE [head: LONG STRING, number: LONG CARDINAL, tail: LONG STRING];
ShowRejection: PROCEDURE [what: LONG STRING, who: PupTypes.PupAddress];
END.