\begindata{text,538380552}
\textdsversion{12}
\template{help}
\define{global
}
\chapter{LACC:  How to Program the Instrument Console

}
\section{Introduction}


\leftindent{\italic{\helptopic{Console}} is intended to be the only 
system-monitoring program you'll ever need in normal use of the Andrew system. 
 It can monitor a wide range of functions of the system, and can display the 
results of its monitoring in a number of formats.  The easiest way to use 
Console is to use one of the predefined console formats named in the program's 
menu.  (You can select them from the menu or provide the console name as an 
argument to the program when it starts up.)  


More adventurous souls can program new console formats themselves, using LACC 
(Language for Andrew Console Construction), described in this document.}


\section{Quick Reference}


\leftindent{A quick reference page for LACC is available.  See the 
 \italic{\helptopic{lacc-quickref} } help document.}


\section{Overview}


\leftindent{Consoles are defined in LACC (Language for Andrew Console 
Construction), a language that looks something like Scribe source files.  The 
current parser is actually much too liberal, and will accept all sorts of 
non-Scribe looking syntax, but the syntax described here is the only one you 
can expect to continue to work in future versions.  

A console consists of a number of instruments, each of which measure a 
particular function of the system and presents the information in a particular 
displaytype, such as a bar graph or a dial.  A definition of a very simple 
instrument might look like this:


\typewriter{@Instrument(

	Function LoadCPU,

	DisplayType BarGraph,

	Xmin 10, Xmax 20, Ymin 10, Ymax 20)}


Such a definition will cause a bar graph monitoring the load on the Central 
Processing Unit to appear in a certain region of the console window.  In 
particular, it will appear in the second tenth of the screen in both the x and 
y directions, because the xmin, xmax, ymin, and ymax coordinates are specified 
in relative coordinates, with 0 being the top or left edge of the window and 
100 being the bottom or right edge.


In order to be interpreted meaningfully, each instrument must specify at least 
the six attributes given in the previous example, defining its location, 
function, and display style.  There are many other attributes which may be 
specified, as explained later in this description.}


\section{Useful Tip on Designing a Console}


\leftindent{One of the menu items in console is a "Restart" item, which tells 
console to read in the console file it first started with.  This is especially 
useful for iteratively designing a console file; just start up console from a 
typescript with the command "console NewName", where "NewName" is the name of 
your new console file.  You can then "recompile" the console file by simply 
changing it with an editor and then selecting the "restart" menu item.  This 
is a handy time saver.}


\section{Defining a Console}


\leftindent{A LACC description consists simply of a series of @Instrument 
commands to define particular instruments to be displayed, along with a few 
@set commands to set certain options that apply to the whole console (not just 
a single instrument within the console).}


\section{Global Settings}


\leftindent{Global values can be set with the @set command.  This command 
takes the form


\typewriter{@set(attribute value, 

	attribute value, ....)  }


to set one or more parameters of the console as a whole.  The global 
parameters of interest and their possible values are:


\italic{MinHeight} -- the minimum acceptable height for the console window.


\italic{MaxHeight} -- the maximum acceptable height for the console window.


\italic{MinWidth} -- the minimum acceptable width for the console window.


\italic{MaxWidth} -- the maximum acceptable width for the console window.


\italic{DesiredWidth} -- the width you would have the console window be, in an 
ideal world.  (The window manager will take your desired width into 
consideration before it assigns you a width at random.)  This should be an 
integer number of pixels.


\italic{DesiredHeight} -- the height you would like this window to be, in 
pixels.


\smaller{\smaller{\indent{\leftindent{[\bold{NOTE:} Given the choice between 
min and max dimensions, console will always give the max value precedence.  It 
is unclear whether the min values actually serve any purpose, other than 
possibly causing the console window to hide itself when another window is 
brought up in the same column that desires more space.  The Desired dimensions 
will take precedence over the min and max dimensions.]}}}}


\italic{Period} -- the number of seconds the console will sleep before it 
updates its displays.  The default is one second, and the period must be an 
integer greater than zero. 


\italic{VMPollPeriod} -- the number of times the console will wake up before 
it computes the vmstat statistics regarding CPU load, etc.


\italic{DiskPollPeriod} -- the number of times the console will wake up before 
it computes the statistics on disk usage.  This is a relatively expensive 
operation, and the numbers don't change very fast, so it makes sense to make 
this number fairly large -- e.g., if your period is 1, setting this to 60 will 
make your disk statistics recomputed only once a minute.


\smaller{\smaller{\indent{\leftindent{[\bold{NOTE:} As both the Disk and VM 
PollPeriods are now being passed to a seperate forked program - reading in new 
consoles after having started one, will not change the polling frequency for 
either of these groups of functions.]}}}}


\italic{MailPollPeriod} -- the number of times the console will wake up before 
it checks to see if you have mail.  Again, this is a relatively expensive 
operation that doesn't really need to be performed every second.


\italic{ClockPollPeriod} -- the number of times the console will wake up 
before it updates the clock.  If you aren't using a second hand, do you really 
need to have it check the time every second?


\italic{WindowPollPeriod} -- the number of times the console will wake up 
before it checks the current number of windows.


\smaller{\smaller{\indent{\leftindent{[\bold{NOTE:} this is not used in ATK 
console - it is treated as a no-op]}}}}


\italic{DirPollPeriod} -- the number of wakeups before it will check the 
status of any random directories being monitored.


\italic{PrintPollPeriod }-- the number of wakeups before console will check 
the status of the print queue.


\italic{VenusPollPeriod} -- the number of wakeups before console will check 
with the cache manager about your file system quota and authentication status.


\italic{ScaleFactor} -- The scale factor to be used in interpreting the xmin, 
ymin, xmax, and ymax parameters.  This is normally 100, but can be set 
otherwise to facilitate building new console files from old ones.


\italic{FontFamily} -- The family of fonts to be used in adjustable text and 
label fonts.  Default is "Andy".


\italic{AlarmRectangle} -- No longer user-definable - this will always use the 
entire console window to flash when the alram goes off.


\italic{InternalMenus} --  This is used to set the menu choices to be listed 
when internal variables are used.  Internal variables are Boolean variables 
which are toggled by menu selection, and which can affect which instruments 
are displayed (using if and unless -- see below).  There are three parameters 
to internalmenus, which specify which variable is being discussed, the menu 
string that turns off the variable, and the menu string that turns on the 
variable.  Thus, the menus for a variable which was being used to toggle 
between a digital and analog clock might say '@set(internalmenus 1 "Make clock 
analog" "make clock digital")'.


\italic{DynamicRectangle} -- This is used to specify the portion of the 
console window which will grow when the window is made larger than the 
requested size.  In particular, you can use the dynamic rectangle to make sure 
that the text logs get the extra screen space, and that icons are given only 
the amount of space they really need.  The format is @set(dynamicrectangle x1 
x2 y1 y2).  All extra space in the x dimension will be allocated to 
instruments in the x range x1 to x2, and similarly extra window height will be 
allocated to instruments in the y range y1 to y2.


\italic{ExternalErrorFile} -- This is used to send error messages to a file 
rather than to a console log.  This is a VERY BAD IDEA for user consoles.  The 
format is @set(externalerrorfile=<filename>), but you should not use this 
without a very good reason, as it tends to hide error messages from users.


\italic{InitExec} -- This is used to specify a program to automatically run 
when you start your console.  The program will be killed when console exits or 
you change to another console file.  This is useful for automatically linking 
up sources to EXTERNAL instrument monitoring.


\indent{\leftindent{\smaller{\smaller{[\bold{NOTE:} InitExec'd programs do not 
get killed unless console's Quit menu item is used - people using such 
features should be careful to Quit console before exiting the window manager]}}}}


\italic{OutgoingAge} -- This is the number of seconds mail will sit 
undelivered in your ~/.Outgoing directory before it will be counted by the 
"OutgoingMail" instrument.  The default is 3600.}


\section{The Definition of an Instrument}


\leftindent{In the definition of an instrument, there are many optional 
parameters you can specify.  Some of these may be ignored by certain types of 
display, but trying to set them anyway will not generate an error.  The 
general syntax for an instrument definition is 


@Instrument(attribute <value>, 

	attribute <value>, ...)


Although most of the attributes require values, not all of them do.  The legal 
attributes and their possible values are listed below:


\italic{Xmin} -- the leftmost coordinate of the instrument, in relative 
coordinates on a scale of 0 to 100.


\italic{Xmax} -- the rightmost coordinate of the instrument, also on a scale 
of 0 to 100.


\italic{Ymin} -- the topmost coordinate of the instrument, scale of 0 to 100.


\italic{Ymax} -- the bottommost coordinate of the instrument, scale of 0 to 
100.


\italic{Function }-- the name of the function being monitored by the 
instrument.  A complete list is given below.  Note that not all functions 
chart percentages, or even numbers; some keep track of text values or numeric 
values that are not percentages.


\italic{DisplayType} -- the type of display to be used, e.g. "BarGraph".  A 
complete list is given below.


\italic{DisplayStyle} -- an optional specification such as "DialHidden" used 
by some of the display types.  Relevant display styles are listed in the list 
of display types, below.


\italic{Boxed} -- specifies that a box should be drawn around the indicator. 
 No value may be specified.


\italic{UpdateAlways} -- specifies that a display should be updated every time 
its value is checked, even if it hasn't changed.


\italic{Noclip} -- specifies that the instrument should not be clipped if it 
goes outside the bounding box defined by the x and y coordinates.  By default, 
all instruments are clipped to remain within that box.  Be warned, however, 
that anything that ges outside of the box may never be erased until the entire 
window is redrawn.  It is not clear if "noclip" is really at all useful, and 
it may go away eventually if no one finds a use for it.


\italic{NoInvisibleClick} -- specifies that clicks should have no effect if 
the item is not being displayed because it is out of range.


\italic{Label} -- specifies a label to be printed under the indicator.  The 
value is the label itself, enclosed in quotes "like this" if it is to be more 
than one word.  As in the "text" parameter, you can include a "$" which will 
be replaced by the numeric value of the instrument and/or a "*" which will be 
replaced by the text value of the instrument.  Actually, \italic{label} is a 
synonym for \italic{bottomlabel}.  Labels can be positioned elsewhere, as the 
following suggest:


\italic{Toplabel} -- like "label foo", "toplabel foo" specifies "foo" as the 
label, but toplabel prints labels at the top of the box instead of the bottom.


\italic{Leftlabel} -- Ditto, but printing the label on the left of the box.


\italic{Rightlabel} -- Ditto, but printing the label on the right.  (This is 
by far the most useless of the four, but was included for completeness.)


\italic{LabelFont} -- specifies the font that the label should be printed in. 
 The value may be any font name.


\italic{AdjustLabelFont} -- specifies that, instead of always using one font 
for the label, the console should choose a font suitable to the size of the 
instrument.  The value should be an integer greater than zero.  The label will 
occupy a vertical fraction of the instrument's area no bigger than the 
reciprocal of the value times the height of the instrument.  Thus, 
"AdjustLabelFont 10" means that the label will be at most 1/10 the height of 
the instrument.


\italic{TextFont} -- specifies a font in which an indicator display will be 
written.  The value is a font name.


\italic{AdjustTextFont} -- like AdjustLabelFont, gives a ratio by which to 
adjust the text font.  Any value but "1" is of questionable utility.


\italic{Threshhold} -- specifies a threshhold for the value of the instrument, 
below which the instrument will not be displayed.  This is good for making 
things "light up", e.g. making a mailbox appear when the value of the mail 
indicator is greater than or equal to 1.  (A value equal to the threshhold 
will cause it to be displayed; by default, everything has threshhold zero, and 
is hence always displayed.)


\italic{Ceiling} -- The opposite of threshhold; a maximum value for displaying 
an instrument.


NOTE:  Console supports four types of highlighting, specified by the following 
key words.  However, they are mutually exclusive; an instrument may either 
flash, be highlighted in reverse video, be highlighted with a notch, or be 
highlighted with a thick box, but only one of these highlighting methods may 
be used on a single instrument.


\italic{FlashMin} -- The minimum value of the range in which the instrument 
will flash wildly.


\italic{FlashMax} -- The maximum value of the range in which the instrument 
will flash wildly.


\italic{HighlightInvertMin, HighlightInvertMax }-- The range in which the 
instrument will be drawn in reverse video.


\italic{HighlightNotchMin, HighlightNotchMax }-- The range in which the 
instrument will be drawn with a highlighting notch in the upper left corner.


\italic{HighlightBoxMin, HighlightBoxMax} -- The range in which the instrument 
will be drawn surrounded by a thick box.


\italic{ValueMax} -- specifies a "maximum" value that an instrument may take 
on.  This is simply used for calculating percentages; for things like CPU 
load, 100 is the only reasonable valuemax, but it is sometimes desirable to 
choose ValueMax'es arbitrarily for things like displaying your mail status on 
a bar graph, ekg, or dial..  


\italic{HandLength} -- specifies the length of the dial hand.  The hand length 
will be this number times the radius of the dial divided by ten.  This is 
ignored for everything but dials.


\italic{HandWidth} -- the width of the dial hand.  The width in degrees will 
be twice this argument, approximately.  Again, ignored for everything but 
dials.


\italic{InitString} -- a string to be passed to the instrument for 
initialization purposes.  For a mariner (cache manager monitoring) instrument, 
this can be "cmu", "itc", or "Both".    For disk status instruments, it can be 
the name of a mounted device, although the default devices are most likely to 
be right.  For Directory polling it should be the full path of the directory 
to be checked (see entry for "Directory" for more information about this 
usage).


\italic{Text }-- The text to be displayed for displaytype Indicator.


\italic{Icon} -- Same as \italic{Text}, but indicates that the text to be used 
is in an icon font, for purposes of compting character widths.  Also, unlike 
Text, all but the first character of the Icon will be ignored.


\italic{IconFont }-- Same as \italic{TextFont}.


\italic{MaxTextFontSize} -- The maximum size to be given to an adjustable text 
font.


\italic{MaxLabelFontSize} -- The maximum size to be given to an adjustable 
label font.


\italic{NoBlank} -- Specifies that the instrument's display should not be 
"blanked out" when the value is not between the threshhold and the ceiling. 
 This is useful only when several instruments are sharing the same screen 
space, if then.


\italic{LeftClickTo} -- This may be followed by "Errorlog", "Reportlog", 
"userlog", or "sillylog", and specifies the log to which a message will be 
added when the left button is clicked on this instrument.  The default is 
"Errorlog".


\italic{LeftClickString} -- This specifies the string which will be sent to 
the log when a left click occurs.  The defaults are reasonable.  See the 
section on "The text logs" below.


\italic{ExternalName} -- The name by which data for an "External" indicator 
will be communicated through the console service.  See the discussion of 
"External" functions in the following section.


\italic{if} -- Specifies that the instrument will be displayed only if the 
internal variable named as a parameter is true.  Thus, "if 1" means the 
instrument will be displayed only when internal variable number 1 is true. 
 There are 21 such variables, the first of which (0) is identical to the 
"Errors" function -- a count of the number of new errors sent to the console 
recently.  For an example of internal variables, check out any console which 
includes an option that toggles between digital and analog clocks.


\italic{unless} -- the opposite of "if" -- specifies that the instrument will 
be displayed only when the internal variable named is false.}


\section{Functions Available}


\leftindent{The instrument console can monitor the following functions.  (Note 
that all functions are simply numeric counts unless they are specifically 
described as percentages or texts.)


\italic{LoadCPU} -- The total load on the CPU, as a percentage of maximum 
load. \italic{LoadIO} -- The total IO load on the system, percentage of 
maximum load. \italic{LoadUser} -- The percentage of CPU load due to user 
processes.


\italic{LoadSys} -- The percentage of CPU load due to system processes.


\italic{LoadIdle} -- The percentage of time the CPU is idle.


\italic{VM} -- Percentage of available virtual memory that you are using.


\italic{PageIn} -- Pages paged in


\italic{PageErr} -- Pages paged out


\italic{PageReplacable} -- page reclaims (simulating reference bits) -- the 
number of pages the system thinks are replacable.


\italic{PageDeficit} -- anticipated short term memory shortfall -- number of 
pages short of the sum of "all" working sets, where "all" is defined only by a 
study of the kernel code.


\italic{MemActive} -- the number of active virtual pages.


\italic{MemFree} -- the size of the free list.


\italic{QueueRun}  -- the number of processes in the run queue.


\italic{QueueBlock }-- the number of processes blocked for resources.


\italic{QueueMem} -- the number of runnable or short sleeper processes that 
are swapped out.


\italic{IntsIO }-- non-clock device interrupts per second


\italic{IntsSys} -- system calls per second


\italic{IntsSwap} -- cpu context switch rate (switches/second)


\italic{NDStatIn} -- Network disk driver in.  This statistic will become 
useless in the near future.


\italic{NDStatOut} -- Network disk driver out.  This statistic will become 
useless in the near future.


\italic{NDStatErr} -- Network disk driver errors.  This statistic will become 
useless in the near future.


\italic{DiskN }-- (where N = 1 to 50) Monitors the status (% full) of one disk 
each.  The disk to be monitored may be specified with the InitString, but most 
people should just use the defaults.


\italic{MarinerFetch} -- a value that is one or zero depending on whether or 
not a file is currently being stored or fetched from the file system.  The 
InitString can specify the CMU fileservers, ITC fileservers, or "Both".  The 
text value contains the latest message from the Cache Manager.


\italic{MarinerOther} -- a text log of all Cache Manager activity, except that 
logged by marinerfetch.  This may contain some CRUCIAL messages from other 
machines, so if you are talking to a Cache Manager and not monitoring 
marinerother, then marinerother messages will be automatically redirected to 
the error log.  Important note:  it is possible for you to avoid seeing these 
crucial messages, for example by monitoring marinerother but setting a strange 
threshhold/ceiling.  (The value of this instrument is always 1)  This is NOT 
recommended; the kind of messages you will be throwing away will be things 
like "Failed to store your file on server".  You really do want to see those 
messages, so don't fool around.


\italic{ClockHours} -- a number from one to twelve, depending on the time of 
day.


\italic{ClockHourFifths} -- a number from one to sixty (\italic{ClockHours} 
multiplied by 5), allowing hours to easily be displayed on the dial of an 
analog clock with \italic{ClockMinutes} and \italic{ClockSeconds}.


\italic{ClockMinutes} -- a number from one to sixty.  The text form of this 
instrument is a digital clock without seconds.


\italic{ClockSeconds} -- a number from one to sixty.  The text form of this 
instrument is a digital clock with seconds.


\italic{ClockAll} -- The number of seconds since New Year's.  


\italic{Date} -- today's date, in text form.


\italic{Mail} -- the number of pieces of mail currently waiting for you.


\italic{Errors} -- the number of errors that have been received at the 
console.  The text contains the latest error, and the history mechanism is 
always turned on to its maximum, although the history may not be displayed in 
a particular console.  Errors can be received at the console in several ways: 
 First, there is a network udp console service.  Second, on some machines 
anything directed to /dev/console may be intercepted by the console program. 
 Finally, a network udp conslog service is also maintained by console; 
messages sent to that service are considered errors unless one or more of the 
syslog monitoring functions (see below) is turned on.


\italic{Alarm} -- a number that is 1 if an alarm is set, zero otherwise.  This 
instrument also has a text value which is set to the alarm time and message.


\italic{Always} -- an instrument which always has value 1 and is never 
updated.  Useful for displaying unchanging text on the console.


\italic{ProcsUser} - The numbers of processes you are currently running, as a 
percentage of the maximum number of processes you are permitted to run.


\italic{ProcsTotal} -- The number of processes currently running on your 
machine, as a percentage of the maximum number of processes that can exist on 
your machine.


\italic{ProcsOther} -- The number of processes in use by a user other than 
yourself or root.  This is a useful indicator of whether other people are 
running remote processes on your machine.


\italic{ErrorLog} -- Displays the contents of the error log.  Should only be 
used with display type drawlog.


\italic{ReportLog} -- Displays the contents of the report log.  Should only be 
used with display type drawlog.


\italic{UserLog} -- Displays the contents of the user log.  Should only be 
used with display type drawlog.


\italic{SillyLog} -- Displays the contents of the silly log.  Should only be 
used with display type drawlog.


\italic{Trouble} -- The number of instruments that are currently signalling 
trouble using display type signaltrouble.


\italic{WindowUse} -- The percentage of possible windows you might have which 
are now in use.


\indent{\leftindent{\smaller{\smaller{[\bold{NOTE:} this feature does not 
really work in ATK, and hence lies about the number of window allowable]}}}}


\italic{PrintQueue} -- The number of files you currently have queued for 
printing.


\italic{PrintSent} -- The number of files queued for printing and already sent 
to the printer.  Such files are counted in both the PrintQueue and PrintSent 
functions.


\italic{PrintErrors }-- The number of files which were rejected by the printer 
or print spooler.  Such files are not counted in the PrintQueue or PrintSent 
counts, because, left alone, they will never be printed.


\smaller{\smaller{\indent{\leftindent{[\bold{NOTE:} The PrintSent and 
PrintErrors functions may not work due to some changes which were made to the 
printing software.]

}}}}
\italic{VicePersonal} -- The percentage of your file system quota that is 
currently being used.


\italic{VicePartition} -- The percentage of space on the physical partition on 
which your files are stored that is currently being used.


\italic{UDPIdle} -- The number of seconds since the last time console read 
anything from the UDP console service.  Useful as a warning if you're feeding 
console external information and the feeding process has died (see below).


\italic{UnAuthenticated} -- This is always zero unless you have an 
unauthenticated file system connection, in which case it goes to 1.  This is 
useful for warning you when your authentication times out and you need to 
reauthenticate yourself with the file system.


\italic{OutgoingMail} -- This is the number of undelivered mail files in your 
~/.Outgoing directory; it is mail that has been sent but not yet delivered. 
 By default, console only counts mail that has been there for more than an 
hour, but this time interval can be modified using the global setting 
"OutgoingAge".


\italic{External1, External2, ... External20} -- Specifies that data will be 
obtained from some external source writing the data to the console service. 
  You must also specify an external name, e.g. "ExternalName foo", which tells 
console how to identify the data for this instrument.  Lines which come to the 
console service that begin "!@#EXTERNAL: foo " will be interpreted as destined 
for this instrument.  The rest of the line will be interpreted as simply a 
numeric value and a text string, as in "!@#EXTERNAL: foo 17 There are 17 
machines on fire".  IMPORTANT NOTE:  You MUST, at present, use the external 
indicators in order.  That is, you must define External1 first, External2 
second, and so on.  If you don't do this, results may be odd.


\smaller{\smaller{\indent{\leftindent{[\bold{NOTE:} some external functions 
may not behave properly in ATK console]}}}}


\italic{Directory1, Directory2, ... Directory20} -- These instruments can be 
used to monitor the number of files in arbitrary directories.  Just supply the 
name of the directory as an initstring, and the instrument's value will be the 
number of files (not counting . and ..).  The directory may be specified using 
%ENVIRONMENT_VARIABLE% when you want the value of $\{ENVIRONMENT_VARIABLE\} to 
be substituted.  (So, %HOME%/.Outgoing could be used for monitoring a 
.Outgoing directory.)  In addition to the default method, there are three 
specializations that you can make when specifying a directory to be polled in 
console, via the InitString:


The three modes of operation available at this time are:

\leftindent{1) Ignore Dot Files Completely

2) Count only files begining with a certain string

3) Count only files ending with a certain string}


However to get the special checking you have to add one of the following 
"special symbols" to the InitString which specifies what directory you are 
polling:

\leftindent{1) '^' (i.e. /foo/bar/baz^) Ignore Dot Files - count all files in 
/foo/bar/baz that do *not* begin with '.'

2) '*' (i.e. /foo/bar/baz/\italic{prefix}*)  - count *only* files in 
/foo/bar/baz that begin with \italic{prefix}

3) '*' (i.e. /foo/bar/baz/*\italic{suffix})  - count *only* files in 
/foo/bar/baz that end with \italic{suffix}}


NOTES:

\leftindent{1) If you want to do different checking for the same directory, 
you have to use a different Function Directory# for each one.

2) The default LeftClickString remains as is - you should probably define your 
own if you are going to do special directory checking - see entry on 
LeftClickString for details on how to do this.

3) Can be particularly usefull for monitoring various spooler directories. How 
often these are checked is controlled by the DirPollPeriod variable. (use 
/.../.../cf* for initstring).

4) You can have only one '*' in an initstring - and it must be either a prefix 
of suffix extension for the filename part of the path.  i.e. the following are 
\bold{not }acceptable:		

\typewriter{		/foo/bar/baz/*mumble*

		/foo/bar/baz/mum*ble

		/foo/b*r/baz

		/foo/b*r/baz/mumble

}	

}IMPORTANT NOTE:\leftindent{

The "external" and "directory" instruments share storage, although they count 
in different directions; thus, for example, you should not use "directory 17" 
and "external23" in the  same console.}


\italic{Remotefunction} - There are many remote functions available, all are 
used by \helptopic{vopcon}, routercon, and netcon. For more details on these, 
you should read the code for the consoles and for the servers that they use. 
IMPORTANT NOTE: The line remotefunction <foo> must be at the very end of the 
instrument declaration. Any other definitions for that particular instrument 
that appear after remotefunction will only appear in the last copy of the 
instruments.}


\section{Display Types and Styles}


\leftindent{The instruments may displayed in several different ways, as listed 
below:


\italic{Debug} -- All information about the display will be printed in 
horrible form on the standard error.  Very useful.


\italic{Dial} -- The information will be plotted on a circular dial, 
calibrated from 0 to ValueMax for that instrument.  DisplayStyle DialHidden 
will make the circle itself invisible, which is useful to produce overlapping 
dials (e.g. a clock) efficiently.  DisplayStyle SquareDial will draw an 
elegant square clock face.


\italic{BarGraph }-- The information is plotted on a bar graph, on a scale of 
0 to ValueMax..  DisplayStyle Horizontal will make a horizontal bar graph.


\italic{Indicator} -- The information is treated as a text indicator.  The 
text of the indicator is specified via the "Text" parameter.  Any asterisk 
("*") in the text will be replaced by the actual text value of the instrument, 
e.g. an error from the console.  Any dollar sign in the indicator ("$") will 
be replaced by numeric value of the instrument.  Thus, it makes sense to say 
something like

	Text "There are $ errors, the first of which is *."

Also, any up-arrow or caret ("^", shift-6 on most keyboards) in the indicator 
will be replaced by the current ValueMax of the instrument.  Finally, a 
backslash ("\\") can be used to quote any of these magic characters (e.g. 
"\\$\\*\\@\\\\" will produce "$*@\\" on your screen.)  DisplayStyle 
RepeatIndicator repeats the text N times, where N is the current value of the 
instrument.  Thus an instrument description that includes


Function ErrorLog, 

DisplayType Indicator, 

DisplayStyle RepeatIndicator, 

Text "f ", 

textfont shape12


will produce one flamingo for each error received at the console. 
 DisplayStyle LeftIndicator causes the text to be flush left instead of 
centered.


\italic{EKGGraph} -- Produces displays in EKG style, plotting numeric values 
over time on a scale of 0 to ValueMax.


\italic{Gauge} -- Displays a numeric value on a dashboard gauge.


\italic{RingAlarm} -- Flashes the screen madly whenever it is called.  This is 
used with a threshhold on the ClockAll instrument to produce an alarm clock; 
you can also use it to flash madly, for example, whenever you have mail or 
whenever an error is logged at the console.  However, the only way to turn it 
off in such cases is to either change console formats or change the underlying 
entity that is triggering the alarm, e.g. by reading your mail if the alarm is 
ringing because you have mail.


\italic{LogError} -- Send the text of the instrument to the error log as if it 
had come in on the error channel, to be parsed and displayed appropriately. 
 (See "The Text Logs", below, for more information.)


\italic{LogReport} -- Send the text of the instrument to the Report log, to be 
parsed and displayed appropriately.  (See "The Text Logs", below, for more 
information.)


\italic{LogUser} -- Send the text of the instrument to the user log, to be 
parsed and displayed appropriately.  (See "The Text Logs", below, for more 
information.)


\italic{LogSilly} -- Send the text of the instrument to the silly log, to be 
parsed and displayed appropriately.  (See "The Text Logs", below, for more 
information.)


\italic{DrawLog} -- Display one of the logs.  This will only work with 
function ErrorLog, ReportLog, UserLog, or SillyLog.  DisplayStyle 
ReverseScrolling will display the log upside-down  (i.e. with the most recent 
line at the top).


\smaller{\smaller{\indent{[\bold{NOTE:} Any specification of textfont to use 
for the logs, will be completely ignored.  See help file on 
\italic{\bigger{console}} for more information about how to set the font used 
for the logs.]

}}}
\italic{SignalTrouble} -- Causes the instrument to turn on a "TROUBLE" flag 
when it is between the threshhold and the ceiling.  The function "Trouble" 
returns the number of instruments currently signalling trouble.


\italic{DrawTitle} -- Draws the text of the current instrument in the center 
section of the console window's title bar.


\italic{DrawNothing} -- Doesn't draw anything, but is useful in conjunction 
with highlighting and boxing for certain obscure purposes.}


\section{The Text Logs}


\leftindent{The console program provides four text logs which are available to 
the console programmer for both reading and writing.  The logs are called the 
Error, Report, User, and Silly logs, though they can each be used for any 
purpose.  (The names simply reflect the best uses I could come up with for 
four separate logs.)  Things get entered into the log by defining instruments 
with text * (or something including "*") and displaytype LogError, LogReport, 
LogUser, or LogSilly.  The contents of the log are read and displayed using 
displaytype DrawLog, and function ErrorLog, ReportLog, UserLog, or SillyLog.


The things that get sent to these logs are parsed in a rudimentary way before 
they are simply written into the log.  Any line beginning with "ERROR: " has 
those first 7 characters stripped off the front, and is drawn like:


\leftindent{\bold{|>> error message <<|} \smaller{(timestamp)}}


Any line that begins "!@#TROUBLE: " is discarded, but the text lines from all 
the instruments now signalling trouble are inserted instead. 
 "!@#ERRORTROUBLE: " is the same, but will display in a manner similar to 
error messages (shown above).  A line beginning with "!@#EXEC: " will cause 
the rest of the line to be interpreted as a shell command to be executed. 
 However, this feature will not work with data that comes in over the console 
service, but only with ClickStrings, to avoid random users telling your system 
to reboot.  A line beginning with "!@#CUTBUFFERS: " will send the entire 
contents of all of the window manager's cut buffers to the log.  A line 
beginning with "!@#FULLTIME: " will send the full date and time to the log.  A 
line beginning with "!@#PRINTSTATUS: " will print a one-line summary of the 
status of your printing requests.  A line starting "!@#MARINERFETCH: " will 
dump one or more lines of information about the current state of the Cache 
Manager into your text log.  A line starting with "!@#TOGGLE " followed by a 
variable number will toggle the value of that variable, allowing a mouseclick 
on one instrument to alter itself or others.  Finally, lines starting with 
"!@#EXTERNAL: " are interpreted as external data being sent to the console 
service.  The first word following the "!@#EXTERNAL: " is the name of the 
external function, which must match the ExternalName of some instrument 
currently being displayed.  The next word is the integer value for the numeric 
value of the instrument, and the rest of the line is the text value.


RELEVANT NOTE:  Each of the magic phrases just described ends with a SPACE 
character.  Console is very picky about this; it really wants that space 
character to be there.


IMPORTANT NOTE:  There are some ugly bogosities in the text logs that you must 
be careful in programming it.  In particular, for the various log input and 
output functions to interact properly, the inputs to the log should be the 
very first instruments you define, and the output (drawlog) should be the very 
last thing you define.  This allows the sequence of execution to work 
correctly for external data feeding in and for functions feeding data into the 
logs.  This nonsense is, unfortunately, wired fairly deeply into the code, but 
it may get cleaned up eventually.


EVEN MORE IMPORTANT NOTE:  The ErrorLog is hard-wired as the place where 
certain internal error messages will be placed.  If the error log is not 
displayed, you may never receive these messages which indicate that the 
console program itself has had some error condition.  Therefore it is 
recommended that all consoles contain at least one log, and that the first log 
used should be the errorlog.}


\section{General Notes on Console File Syntax}


\leftindent{There are a few more things worth knowing about console files. 
 First of all, comments may be placed anywhere in the files.  Comments begin 
with a number sign ("#") and end at the end of the line, as in C shell 
programs.  In general, the parser separates all words by punctuation or white 
space, but you can enclose text strings in double quotes ("text string" is one 
argument) when you need to.  The current implementation of the console file is 
very liberal in its parsing; if you don't stick to the syntax given here, it 
may well parse your file without thinking it has made any errors.  However, 
you should not count on any bizarre syntax continuing to work in the future; 
use the Scribe-like language given here.}


\section{Program Authors}


\leftindent{Nathaniel S. Borenstein - original

Adam Stoller - ATK conversion}


\section{Changes}


\leftindent{May 1987 - Converted to ATK by Adam Stoller

June 1987 - Removed Features: StartHidden, DrawExposeMe, DrawErrorWindow, and 
DrawBigText

July 1987 - Added additional functionalioty to InitString for Directory 
Polling.

October 1987 - Turned Logs into ATK textviews, doing away with the lacc 
setting of PromptFont.}


\section{Related Tools}


Select (highlight) one of the italicized names and choose "Show Help on 
Selected Word" to see the help document for:


\leftindent{\italic{\helptopic{console}

\helptopic{lacc-quickref}

\helptopic{vopcon}}}


\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1115,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: This software is part of version 6.1 of the 

Andrew User Interface System and is 

the property of IBM, Carnegie Mellon University, 

and the other copyright holders.  The source 

code of this version is for the sole use of 

the individual named in ./config/allsys.h.  

This source code is not to be redistributed.  

Binary object code compiled or derived from 

these sources is not to be distributed to non-

members.  Members may have additional 

distribution rights granted by prior written 

permission of Carnegie Mellon University.



IBM, CARNEGIE MELLON UNIVERSITY, 

AND THE OTHER COPYRIGHT HOLDERS

 DISCLAIM ALL WARRANTIES WITH 

REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANT-

ABILITY AND FITNESS. IN 

NO EVENT SHALL  IBM, CARNEGIE 

MELLON UNIVERSITY, OR ANY OTHER 

COPYRIGHT HOLDER BE LIABLE FOR 

ANY SPECIAL, INDIRECT OR CONSE-

QUENTIAL DAMAGES OR ANY DAMAGES 

WHATSOEVER RESULTING FROM LOSS OF

USE, DATA OR PROFITS, WHETHER IN AN

ACTION OF CONTRACT, NEGLIGENCE OR

OTHER TORTIOUS ACTION, ARISING OUT 

OF OR IN CONNECTION WITH THE USE OR

PERFORMANCE OF THIS SOFTWARE.

 $

}}\enddata{text,538380552}
