Note
When referring to file and directory locations in this document, <install-home> is the directory where the Agent Controller package was unzipped. This directory is also referred as TPTP_AC_HOME in the configuration files.
Contents
When referring to file and directory locations in this document, <install-home> is the directory where the Agent Controller package was unzipped. This directory is also referred as TPTP_AC_HOME in the configuration files.
The serviceconfig.xml file is read by the Agent Controller to obtain user-configurable settings. It is read only once, at startup. Modifications to this file are typically restricted since any changes impact all users.
The serviceconfig.xml file contains the following segments:
Agent Controller Environment –
Defines environment variable settings which are applied to the existing
environment according to the specified position. The resulting environment
becomes the default for all agents and applications subsequently launched
via the Agent Controller. This default can be modified later for specific
launch requests.
Logging – Defines the severity
level
of information that should be written to the common log file, the format of
this information, and the location of the log file. The log file
name is tptpAgentCtlr.log
.
Agent
– Defines the location of a directory identifying Agents that should be
known to the Agent Controller. Each subdirectory under the main agents
directory contains an
agent.xml file. All subdirectories at the specified path are expected to
represent names of Agents that can be used by a Client. The
agent.xml file
within each subdirectory typically contains information on how to start
the Agent.
Process Controller – Defines
the pathname of the Agent that the Agent Controller will use to launch
Agents and applications.
Connection – Defines the
information to be used by the Agent Controller and Agents to establish
several different types of connections that are used for communication. Each type of connection is described in a Transport Layer block
containing different elements according to the type of connection being
described. Currently, "socket",
"named-pipe", and "shared memory" connections are
required.
Application Aliases – Defines a set of alternate names (i.e., aliases) for starting applications that use predefined launch information. This allows platform-specific launch information for specific applications to be contained on the target platform. This segment makes it possible to restrict the list of applications that can be launched to those specified in this list.
If the environment variable TPTP_AC_HOME is defined, the Agent Controller looks for config/serviceconfig.xml relative to the path defined by it, otherwise it looks relative to its own installed location. The default location for the is serviceconfig.xml file is <install-home>/config/serviceconfig.xml.
Each instance of an Agent Controller running on the same system requires its own version of serviceconfig.xml with different transport layer configurations.
Agents also read the serviceconfig.xml file to get the information from the Connection segment, thus allowing an Agent to communicate with a particular Agent Controller.
Agents read their command line to get an alternate location in which to find the serviceconfig.xml file. The predefined option name for specifying the location is –serviceconfig followed by the pathname of the configuration file. If not specified on the command line, the agent looks for serviceconfig.xml in the same locations as described above for the Agent Controller.
The hierarchy of the elements contained in the serviceconfig.xml file is shown below. The order of elements shown at the same level is unimportant. Only one occurrence of each of the first level of elements (i.e. AgentControllerEnvironment, Logging, Agent, ProcessController, Connection, ApplicationAliases) is expected. Hyperlinks in the hierarchy link to the formal element description in the Elements and Attributes section.
AgentControllerConfiguration
AgentControllerEnvironment
Variable
Logging
Agent
ProcessController
Connection
TransportLayer
Configuration
Port
PipeName
MemName
CommandExtractor
ApplicationAliases
Application
Variable
Parameter
Sub-elements: AgentControllerEnvironment
Logging
Agent
ProcessController
Connection
ApplicationAliases
Element: AgentControllerEnvironment
Defines the global environment settings for all applications and agents launched
through the Agent Controller. If this element is omitted, the environment
passed on remains identical to that of the Agent Controller itself. Variables
defined here do not affect the environment settings of the Agent Controller
itself.
Used by: AgentControllerConfiguration
Sub-elements: Variable
Element: Variable
This Variable element defines an environment variable and how it should be
positioned within the existing environment to form the default environment for
all applications and agents launched. There can be zero or more of these
elements defined for the AgentControllerEnvironment
Used by: AgentControllerEnvironment
Attributes:
- name
- This string value specifies the name of the environment variable.
- value
- This string value specifies the value of the environment variable.
- position
- (optional) This string value is one of "append", "prepend", or "replace", indicating where to place this environment relative to the default environment.
Element: Logging
Defines the severity level of information to log, in which format, and to which
location. If this element is omitted, all critical and severe warnings will be
logged, using CBE format, into the same directory in which the Agent Controller
is running. Note that the log file name (tptpAgentCtrl.log) is not
configurable; only its location.
Used by: AgentControllerConfiguration
Attributes:
- level
- (optional) This string value indicates the level of severity of messages that should be logged. Each level includes itself and all events that are more severe. Specify one of the following (listed in order of increasing severity):
DEBUG - includes messages that provide low-level details about the internal flow of code execution of the Agent Controller and agents.
INFORMATION - includes events that are normal but may be of interest to the user of the program.
WARNING - includes events that are unexpected but shouldn’t interfere with program operation.
CRITICAL - (default) includes events that indicate normal program operation was interrupted by an error.
SEVERE - is restricted to events that result in program termination.
- format
- (optional) This string value specifies the format to use when writing the messages to the log file. Specify one of the following:
- CBE - (default) messages will be written in Common Base Event format (includes detailed information on the context and origin of the message) suitable for consumption by a CBE log reading utility.
- Simple - messages will be written as simple text.
directory (optional) This string value specifies the location in which the log file will be created. The default is the directory from which the Agent Controller is run.
Element: Agent
This required element specifies the directory in which agents that will be known
to the Agent Controller will have placed subdirectories that identify the agent
by name and contain an agent.xml configuration file with information on how to
launch and manage the agent.
Element: ProcessControllerUsed by: AgentControllerConfiguration
Attributes:
- path
- This string value specifies the full pathname of the directory in which to look for agent configurations.
Element: ConnectionUsed by: AgentControllerConfiguration
Used by: AgentControllerEnvironment
Sub-elements: TransportLayer
Attributes:
- name
- This string value provides a name for the connection configuration.
Used by: Connection
Sub-elements: Configuration
CommandExtractor
Attributes:
- loadlib
- This string value specifies the name of the library to be loaded for this transport layer, without its suffix (i.e., do not include .dll or .so). The normal system path search for locating the library is used.
Element: Configuration
The Configuration element contains a sub-element that specifies the interprocess
communication mechanism for each TransportLayer. The communication mechanisms
provided for here are socket, named-pipe, and shared memory. Custom
TransportLayers might have other configuration elements that are specific to it.
Used by: TransportLayer
Sub-elements: Port (only with socketTL)
PipeName (only with namedPipeTL)
MemName (only with sharedMemTL)
Element: Port
The Port element specifies the transport layer used for socket communication.
The Port element is only valid when used with the
socketTL loadlib. It’s
integer value specifies the actual port number to use in making the socket
connection.
Used by: Configuration
Element: PipeName
The PipeName element indicates the transport layer is for named-pipe
communication. The PipeName element is only valid when used with the
namedPipeTL loadlib. Its string value specifies the name of the pipe to use in making
the connection.
Used by: Configuration
Element: MemName
The MemName element indicates the transport layer is for shared memory
communication. The MemName element is only valid when used with the
sharedMemTL loadlib. Its string value specifies the name of the shared memory
resource to use in making this connection.
Used by: Configuration
Element: CommandExtractor
This element defines a Command Extractor which is a pluggable component in a
Transport Layer that extracts commands from the interprocess communication
stream. It’s string value specifies the name of the library to be loaded without
its suffix (i.e., do not include .dll or .so) or prefix (i.e., "lib" for Linux). The normal system path search for
locating the library is used.
Used by: TransportLayer
Element: ApplicationAliases
The ApplicationAliases element is an optional list of application alias
definitions.
Used by: AgentControllerConfiguration
Sub-elements: Application
Attributes:
- launchAliasesOnly
- (optional) This string attribute is either "true" or "false" (default). If set to "true", only applications that have been defined within this element will be launched. If the attribute is set to “false” or omitted, any application can be launched.
Element: Application
The Application element defines an alias name and launch information for an
application.
Used by: ApplicationAliases
Sub-elements: Variable
Parameter
Attributes:
- executable
- This string value specifies the alias name for the application executable specified in the path attribute.
- location
- (optional) This string value specifies the directory from which the executable is to be launched, sometimes referred to as the working directory for the executable while it is running.
- path
- This string value specifies the full pathname of the application to launch. This is used in place of the alias name when launching the application executable.
Element: Variable
This Variable element defines an environment variable and how it should be
positioned within the existing environment when the application is launched.
There can be zero or more of these elements defined for an Application.
Used by: Application
Attributes:
- name
- This string value specifies the name of the environment variable.
- value
- This string value specifies the value of the environment variable.
- position
- (optional) This string value is one of "append", "prepend", or "replace", indicating where to place this environment relative to the default environment.
Element: Parameter
The Parameter element defines a command line argument to be given the
application when launched. There can be zero or more of these elements defined
for an Application.
Used by: Application
Attributes:
- value
- This string value specifies a command line argument.
- position
- (optional) This string value is one of "append", "prepend", or "replace" indicating where to place this argument relative to the existing command line arguments.
This example shows a sample Agent Controller configuration file:
<?xml version="1.0" encoding="UTF-8"?>
<AgentControllerConfiguration>
<AgentControllerEnvironment>
<Variable name="JAVA_PATH" value="C:\j2sdk1.4.2_06\bin\java.exe" position="replace"/>
<Variable name="TPTP_AC_HOME" value="C:\tptp" position="replace"/>
<Variable name="PATH" value="%TPTP_AC_HOME%\bin" position="prepend"/>
<Variable name="SYS_TEMP_DIR" value="C:\Temp" position="replace"/>
<Variable name="LOCAL_AGENT_TEMP_DIR" value="%SYS_TEMP_DIR%" position="replace"/>
</AgentControllerEnvironment>
<Logging level="DEBUG" format="CBE" directory="c:\tptp\log"></Logging>
<Agent path="C:\tptp\agents"></Agent>
<ProcessController>tptpProcessController.exe</ProcessController>
<Connection name="Dev">
<TransportLayer loadlib="socketTL">
<Configuration>
<Port>10002</Port>
</Configuration>
<CommandExtractor>tptpCmdExtr</CommandExtractor>
</TransportLayer>
<TransportLayer loadlib="namedPipeTL">
<Configuration>
<PipeName>acmaster</PipeName>
</Configuration>
<CommandExtractor>tptpCmdExtr</CommandExtractor>
</TransportLayer>
<TransportLayer loadlib="sharedMemTL">
<Configuration>
<MemName>acbuffer</MemName>
</Configuration>
<CommandExtractor>tptpCmdExtr</CommandExtractor>
</TransportLayer>
</Connection>
<ApplicationAliases launchAliasesOnly="false">
<Application executable="TimeCollector" path="C:\tptp\bin\TimeCollector.exe">
</Application></ApplicationAliases>
</AgentControllerConfiguration>
Copyright (C) 2005, Intel Corporation.