\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=), 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 , \ attribute , ...) 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 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}