\begindata{text,538512684}
\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 command window 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,538546944}
\enddata{bp,538546944}
\view{bpv,538546944,1,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL 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,538512684}
