The serviceconfig.xml File

Contents

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.

Introduction

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:

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. 

Note

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.

 

Agent Controller Configuration

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

Elements and Attributes


Element:
AgentControllerConfiguration
This is the root element of the Agent Controller configuration. The settings are used by the Agent Controller as it first starts up. There can be only one of each sub-element.

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.

Used by:     AgentControllerConfiguration

Attributes:

path
This string value specifies the full pathname of the directory in which to look for agent configurations.
 
Element: ProcessController
The ProcessController element simply contains a value which specifies the pathname of the executable which the Agent Controller will start and then call upon to launch agents and applications. By default, the Agent Controller will launch the tptpProcessController(.exe) agent located in the same directory as the Agent Controller itself. The executable must register itself with the Agent Controller and be able to process the command set for that interface. Because its launch information is restricted to the pathname contained here, this agent is not required to have a subdirectory specified in the agents directory like other agents and it cannot take command line arguments. This may change, see bugzilla 114441.

Used by:     AgentControllerConfiguration
    

Element: Connection
This element is required and, at a minimum, must contain a TransportLayer element to define each of the following types of connections which are used by the Agent Controller: socket, named-pipe, and shared memory.

Used by:     AgentControllerEnvironment

Sub-elements:     TransportLayer
                           
Attributes:

name
This string value provides a name for the connection configuration.

Element: TransportLayer
This element defines a Transport Layer which is a pluggable component inside the Agent Controller responsible for sending and receiving data between components in the system via an interprocess communication mechanism.

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.


Example serviceconfig.xml File

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.