AAFID(tm) Configuration mechanisms
----------------------------------

 ======================================================================
 This file is Copyright 1998,1999 by the Purdue Research Foundation and
 may only be used under license.  For terms of the license, see the
 file named COPYRIGHT included with this software release.
 AAFID is a trademark of the Purdue Research Foundation.
 All rights reserved.
 ======================================================================


Within the AAFID2/config directory (see Directory_hierarchy.txt), the 
configuration files follow a specific naming scheme that allows the
specification of configuration information at the following levels:

- AAFID Global (all entities and programs in the AAFID2 prototype)
- Per entity class
- Per entity instance

The configuration information is inheritable. For example, if a
parameter is specified for the AAFID::Entity class, it is
automatically inherited by all entities in the AAFID2 prototype,
because they are all subclasses of AAFID::Entity.

File format
-----------

Each file has a format that resembles X11 resources:

  ResourceName:   value

The ResourceName is the name of the configuration variable to set, and
the value can be a string (it has to be quoted if there are several
words), a number, a boolean value (true/false, yes/no), or an anonymous
reference to a hash or list, in Perl syntax. Within anonymous 
references, any Perl expressions are valid.

The class to which the parameters are assigned depends on the file in
which the parameter specification appears. See below.


File naming
-----------

- Global AAFID parameters are specified in a file called "AAFID"

- Per-entity-class parameters are specified in a file with the name of
  the entity class. So for example, parameters for all entities in the
  system would be stored in a file called "Entity"; parameters for all
  agents would be stored in a file called "Agent"; and so on.

- Per-entity-instance parameters are specified in files that match a
  prefix of the entity identifiers that they are intended for. Entity
  identifiers in AAFID2 have the following form:
	host:classname:version:instance_number
  So for example, parameters for all entities in host fiji would be
  stored in a file called "fiji"; parameters for all Agents in host
  fiji would be stored in a file called "fiji:Agent"; and so on.


Standard configuration parameters
---------------------------------

The following are standard global parameters. This means that they are
inherited by everything (entities and programs) in AAFID2 if they are
specified in the AAFID file. If they are specified in other files,
they affect only the corresponding entities.

- ListenPort (44777): the port in which Monitors listen for
  connections from other hosts. It is a global parameter because it is
  used by other programs, such as the Starter.

- BaseDir (no default): the base directory for the distribution. See
  Directory_hierarchy.txt.

- ClassDir (BaseDir/classes): the directory in which the base AAFID2
  classes are located and can be loaded from. By default it is
  BaseDir/classes. If that directory does not exist, each entity
  computes its own ClassDir as the directory from which
  AAFID/classname.pm was loaded, where classname is the corresponding
  class name.

- AgentsDir (ClassDir/Agents): the directory in which agent class
  files are located.

- ConfigDir (BaseDir/config): the directory under which the
  configuration files are stored.

- LogCategories (["messages", "errors", "params"]): the log categories
  that are active by default.
	The following log categories exist:
  signals, I/O, messages, errors, debug, params

- LogFile ("AAFID.log"): the file to which log messages will be sent.

- TmpDir ("/tmp"): temporary directory to use. If any of the
  environment variables TMP, TMPDIR, TEMP or TEMPDIR is set, its value 
  is used.

Notice that all the directory parameters (BaseDir, ClassDir,
AgentsDir, ConfigDir) are automatically detected and set if you are
using the standard directory structure (see Directory_hierarchy.txt).

Each entity (in fact, any AAFID class) may define its own standard
parameters, stored in the %PARAMETERS hash specified in the class file
(defined using the AAS PARAMS keyword for agents). Look at
classes/AAFID/{Entity.pm, Agent.pm, ControllerEntity.pm} and at the
files in aas/ for some examples.

The following are standard parameters for the Monitor class:

- RemoteExecCmd (/bin/sh -c 'nohup ssh $host $remotecmd
  >/dev/null 2>/dev/null' &): the command used by a monitor to execute
  the remote command necessary to start a new transceiver in another
  host. The $host is replaced by the host where the command will be
   executed, and $remotecmd is the command itself (given by the
  Monitor.StarterExecCmd parameter, see below).

- StarterExecCmd (perl -w -mAAFID::Starter -e0 -- --host $myhost
  --port $myport): the command used to execute the starter in a remote
  host. The command will be executed in the remote host. $myhost is
  replaced by the host to which the Starter has to connect (where the
  Monitor is running), and $myport is the port in which the monitor
  will be listening (given by default by the ListenPort global
  parameter).

The following is a standard parameter for the ControllerEntity class:

- TmpCodeBaseDir (defaults to the value of TmpDir) and TmpCodeDirName
  (defaults to "ControllerEntityCode"): the directory in which
  dynamically downloaded code will be stored, both by Monitors and
  Transceivers (both of which are subclasses of ControllerEntity) will
  be a subdirectory called as the value of TmpCodeDirName, under the
  directory given by TmpCodeBaseDir. To the directory name given, the
  process ID will be automatically appended.


Other configuration parameters
------------------------------

Any non-standard configuration parameters that are specified in the
configuration files are simply set as entity parameters in the
corresponding entities, overriding their default values if they have
any.
