How To Read The Reference Documents

A brick is the nickname that many contractors give to the thick book of specifications that accompanies the prints for a large construction project. In this "brick" (so called for its dimensions and weight -- they are usually at least 500 pages thick) are the gory details of the project: what kind of nails and screws must be used, the paint company's codes for the colours of paint used on the walls, the types of adhesives used to glue the carpet down, etc.

The software effort for ESI has produced a set of documents (mercifully, these are generated by software) which go into this level of detail about the keywords, the backend database, the software components, etc. Like the contractor's brick, these documents are cross-referenced to some schematic drawings; in our case, the drawings show the flow of information between software and hardware modules.

Memes Bricks

Several of the bricks are "memes" documents, meaning that they are generated from data in the "memes" database -- the database of keywords, parameters, etc. describing the ESI software and its configuration. These are shown on the main page as:

Keyword Brick

This documents all the keywords in the service "esi". Each keyword has a name, a "long name" that is more human-readable (the "show" command displays it), a datatype, and other attributes. Some keyword definitions may include test points where a scope probe can check the signal represented by the keyword. This document is the definitive reference for all the keywords that can be used in "show" and "modify" commands for the service.

Environment Variables

This documents the environment variables used by various software modules in the ESI system. These are not keywords, so concepts like "readable/writable" or "units" are not relevant. Upper case names indicate envars, whereas mixed case names may indicate groups of envars which are closely associated. This doc explains the environment variable settings in the ESI startup scripts, or (alternatively) how you might have to set up a user account to get direct access to ESI system commands.

Command Line Flags/Args

This documents the command line arguments that can be used with various software modules in the ESI system. As with environment variables, some keyword attributes are irrelevant. The "long name" attribute here is used to indicate the syntax of the command line argument, for example:

	DispNumber (CommandLine), int / int / int, access 
     	-n (DispNumber)
         This flag provides the number of the dispatcher2 process, 
	 if there should be more than one for the KTL service. It is 
	 used to construct the traffic name. 

This entry indicates that the Dispatcher Number argument is provided on the command line by a -n followed by the dispatcher number. Strings in parentheses should be replaced in real life by the suggested value. This document explains the syntax used in the ESI startup scripts when various commands are invoked.

Database Map

This is a graphical image linked to the Database Brick. If you click on a table, its definition in the brick is shown. Because fields in tables are "just like" keywords in a service, the layout of this brick is identical to those previously described. Keywords, environment variables, command line arguments, and database table elements are all fundamentally similar. They are all described in the memes database, and the same documentation generator produces reference manuals for these 4 different types of information.

Agents Brick

This is a different kind of brick. It documents the "agents" -- active participants, whether human, hardware, or software -- in the ESI system. An agent is anything that originates, transmits, alters, stores, or accepts information. Information, of course, is anything that can be described as a "meme" -- a keyword, environment variable, etc.

The Agents Brick is tied closely to a series of Diagrams which describe substantial chunks of ESI system design and function. The drawings are "live" to the brick, that is, you can click on agents and see their definitions; the Agent Brick is "live" to both the drawings and the keyword brick, so you can look up an agent in the brick and find the drawing(s) in which it appears or the keyword(s) it affects or uses.

Test Brick

This is a guide to the ESI functional test suite. Each test in the suite is documented briefly in this brick. For more information about testing, you should read the "RegressionTest" Technical Documents.

The Whole Service

This is a large diagram integrating the whole ESI control system (all the diagrams referred to by the Agents Brick). This is a huge mapped GIF. We don't recommend you try to access it over a slow network link.

Source Tree Maps

This document gives you access to some "aerial views" of the ESI source code tree. If you are on a trusted host, clicking on these drawings can take you immediately into the ESI source tree itself, where you can review README files and examine the source code.