IBM Agent Building Environment Developer's Toolkit


Chapter 2. Agent Reference

Compiling and Linking with IAAgent and Associated Classes

Refer to Chapter 1. "Building ABE-Related Components" for assistance in compiling and linking with IAAgent and associated classes that are described below.

Class IAAgent

An IAAgent is the Abstract agent interface object, from which all concrete (application-specific) agents are derived.

IAAgent contains two categories of member functions:

  1. Service Functions: provided by the IBM Agent Building Environment Developer's Toolkit and used by concrete agents to configure and control the components of the agent. Concrete agents do not override these member functions.

  2. Callback Functions: defined as virtual functions in the IAAgent class. The concrete agent that is derived from IAAgent overrides and implements these functions. The IBM Agent Building Environment Developer's Toolkit calls functions in this category to request actions such as alert handling. This category includes the handleAlert() function.

Header File

#include <iatk/agent.h>

Constructors

This class is abstract and cannot be instantiated.

An application builds an agent by deriving an application-specific (concrete) agent class from IAAgent and invoking the concrete agent's constructor.

Service Functions

addAdapter
   C++:  void addAdapter(const char *domain, const char *module,
                        void *parm, IAAdapterHandle &ahdl)
                        throw(IAError);

   Java: void addAdapter(String domain, String module,
                        String parm, IAAdapterHandle ahdl)
                        throws IAError;

Adds a specific adapter into the agent configuration.

An application calls the agent's addAdapter() function to create and initialize a concrete adapter and to add it to the agent's configuration.

Parameters:

domain
The name of the adapter's domain.

module
The name of the dll that contains the implementation of the adapter. The addAdapter() function will load this dll.

Note that the dll extension should not be included as part of the name.

parm
The parameter list that is input to the adapter's newAdapter() factory function. See the specific adapter's newAdapter() interface for the content and layout of the parameter list.

ahdl
An IAAdapterHandle into which the addAdapter() function will place the handle for the resulting adapter. The handle is a token that is used as an input parameter for other agent functions, and identifies to those functions which concrete adapter to act upon.

Returns

Nothing.

Exceptions (IAError):

IA_E_WRONG_STATE
The agent is in the wrong state for the addition of new adapters. Adapters can only be added prior to invoking the agent's start() function.

addEngine
   C++: void addEngine(const char *kind, const char *module,
                             void *parm, IAEngineHandle &ehdl)
                             throw(IAError);

   Java: String addEngine(String kind, String module,
                             void parm, IAEngineHandle ehdl)
                             throws IAError;

Adds a specific engine into the agent configuration.

An application calls the agent's addEngine() function to create and initialize a concrete engine and to add it to the agent's configuration.

Parameters:

kind
The type or name of the engine.

module
The name of the dll that contains the implementation of the engine. The addEngine() function will load this dll.

Note that the dll extension should not be included as part of the name.

parm
The parameter list that is input to the engine's newEngine() factory function. See the specific engine's newEngine() interface for the content and layout of the parameter list.

ehdl
An IAEngineHandle into which the addEngine() function will place the handle for the resulting engine. The handle is a token that is used as an input parameter for other agent functions, and identifies to those functions which concrete engine to act upon.

Returns

Nothing.

Exceptions (IAError):

IA_E_WRONG_STATE
The agent is in the wrong state for the addition of new engines. Engines can only be added prior to invoking the agent's start() function.

addLibrary
   C++:  void addLibrary(const char *map,
                         const char *topCollector, const char *ImplDllName,
                         const char *ImplType, int levels, IALibraryHandle &lhdl)
                         throw(IAError);

   Java: void addLibrary(String map,
                         String topCollector, String ImplDllName,
                         String ImplType, int levels, IALibraryHandle lhdl)
                         throws IAError;

Adds a specific library into the agent configuration.

An application calls the agent's addLibrary() function to create and initialize a library and to add it to the agent's configuration.

Parameters:

map
The information needed to find a top Collector in the persistent storage implementation. For the current file-based Library it is a path to (but not including) the directory in the file system that represents the Library's top Collector. It is expressed as C:\x\y\z\, for example, where C: is the drive and x, y, and z are directories in the path above the one that is used to implement the top Collector. The slash delimiters match the platform of the current implementation. For UNIX it has no drive and uses forward slashes, e.g. home/x/y/z/. The method internally appends the string that you provide in this map parameter with the string that you provide in the topCollector parameter (described below) to form the path to the top Collector. For example, C:\x\y\z\libtop.
The map to the library. For a file system, this would be the path to the library. addLibrary() passes this token to the IALibrary::attachImplementation() function. See the IALibrary class for more information.

topCollector
The name of the top collector of the library. addLibrary() passes this to the IALibrary::attachImplementation() function. See the IALibrary class for more information. This is the name that is assigned to the top Collector in the selected Library. If this is a new Library, the current file implementation requires that you have created an empty directory in the file system, specify its name here, and the path to it via the map parameter above.

ImplDllName
The name of the dll that contains the implementation of the library. addLibrary() passes this token to the IALibrary::attachImplementation() function, which will load the dll. See the IALibrary class for more information.

Note that the dll extension should not be included as part of the name.

ImplType
The type of library implies a particular implementation. Currently file is the only supported implementation. addLibrary() passes this information to the IALibrary::attachImplementation() function. See the IALibrary class for more information.

levels
The number of collector levels contained in the library. In the hierarchical library provided with the IBM Agent Building Environment Developer's Toolkit, the top collector is level 1, collectors that are children of the top collector are level 2, collectors that are grandchildren of the top collector are level 3, etc. addLibrary() passes this token to the IALibrary::attachImplementation() function. See the IALibrary class for more information.

lhdl
An IALibraryHandle into which the addLibrary() function will place the handle of the resulting library. The handle is a token that is used as an input parameter for other agent functions, and identifies to those functions which library to act upon.

Returns

Nothing.

connect
   C++:  void connect(const IAAdapterHandle &ahdl,
                              const IAEngineHandle &ehdl) throw(IAError);

   Java: void connect(IAAdapterHandle ahdl,
                              IAEngineHandle ehdl) throws IAError;

Connects a specific concrete adapter to a specific concrete engine in the agent configuration.

An application calls the agent's connect() function to connect a concrete adapter to a concrete engine in the agent's configuration. This connection causes the specified adapter's events to be delivered to the specified engine for processing.

Parameters:

ahdl
The IAAdapterHandle that was returned by the agent's addAdapter() function. The handle tells the connect function which concrete adapter to connect.

ehdl
The IAEngineHandle that was returned by the agent's addEngine() function. The handle tells the connect function which concrete engine to connect.

Returns

Nothing.

Exceptions (IAError):

IA_E_ADAPTER_HANDLE_BAD
The IAAdapterHandle is invalid.

IA_E_ENGINE_HANDLE_BAD
The IAEngineHandle is invalid.

IA_E_WRONG_STATE
The agent is in the wrong state for the addition of adapter-engine connections. Connections can only be made prior to invoking the agent's start() function.

getEventsCompleted
   C++:  long getEventsCompleted() const;

   Java:  int getEventsCompleted();

Returns the number of events that have been processed since the agent was started.

Parameters:

None.

Returns:

The number of events that have been processed since the agent was started.

loadConductSet
   C++:  void loadConductSet(const IALibraryHandle &lhdl,
                             const IAEngineHandle &ehdl,
                             const char *csname, const char *selector)
                             throw(IAError);

   Java:  void loadConductSet(IALibraryHandle lhdl,
                             IAEngineHandle ehdl,
                             String csname, String selector)
                             throws IAError;

Loads a conduct set from the library into the engine.

An application calls the loadConductSet() function to load a specific conduct set into the engine. The engine will process the conduct set when the next event occurs for the given selector.

Only rules with an "Active" state are loaded.

Parameters:

lhdl
The IALibraryHandle that was returned by the agent's addLibrary() function. The handle tells the loadConductSet() function which library to load the conduct set from.

ehdl
The IAEngineHandle that was returned by the agent's addEngine() function. The handle tells the loadConductSet() function which concrete engine to load the conduct set into.

csname
The name of the conduct set that is to be loaded. If the conduct set is not in the top collector of the IALibrary, then the name includes the path of collectors (not including the top Collector itself) that must be traversed to reach the conduct set. For example:
     \collectorA\collectorB\conductSetName       (OS/2, Windows)
     /collectorA/collectorB/conductSetName       (AIX)

selector
The selector that identifies the conduct set. This can be a userid or a group name, and is used to associate related conduct sets. Only events that contain this selector will cause processing of this conduct set to occur.

Returns

Nothing.

reset
   C++:  void reset(const char *selector) throw(IAError);

   Java:  void reset(String selector) throws IAError;

Requests that the agent discard all information for a particular selector.

An application calls the reset() function to cause the agent to stop processing events for the specified selector, and then to discard all information and state related to the specifed selector. Generally, the intended effect of this call is that after it completes the agent (including all adapters and engines) are in the same state as if it had never processed any work on behalf of the given selector. However, achieving this intent depends on the correct behavior of the adapters and engines in their response to calls made to them.

The specific sequence of actions taken during the reset() call is described below in the section "Reset Sequence".

Parameters:

selector
The selector whose agent-related information is to be discard.

Returns

Nothing.

Exceptions (IAError):

IA_E_WRONG_STATE
The agent is in the wrong state for the reset() call. Calls to the reset() function can be made while the agent is in the running state; that is, after a call to the agent's start() function returns, and before a call to the agent's stop() function is made.

Reset Sequence

The processing of the reset() call comprises the following steps:

start
   C++:  void start() throw(IAError);

   Java:  void start() throws IAError;

Start the agent.

An application calls the agent's start() function to start the agent and all of it's configured adapters and engines.

Parameters:

None.

Returns

Nothing.

stop
   C++:  void stop() throw(IAError);

   Java:  void stop() throws IAError;

Stops the agent.

An application calls the agent's stop() function to stop the agent and all of it's configured adapters and engines.

Parameters:

None.

Returns

Nothing.

Exceptions (IAError):

IA_E_WRONG_STATE
The agent is in the wrong state to be stopped. The agent can only be stopped after having invoked the agent's start() function.

unloadConductSet
   C++:  void unloadConductSet(const IALibraryHandle &lhdl,
                              const IAEngineHandle  &ehdl,
                              const char *csname, const char *selector)
                              throw(IAError);

   Java:  void unloadConductSet(IALibraryHandle lhdl,
                              IAEngineHandle  ehdl,
                              String csname, String selector)
                              throws IAError;

Unloads a conduct set from an engine.

An application calls the agent's unloadConductSet() function to remove a specific conduct set from the engine. The engine will unload the conduct set as soon as all pending events for this conduct set have completed.

Parameters:

lhdl
The IALibraryHandle that was returned by the agent's addLibrary() function. The handle tells the unloadConductSet() function which library to obtain conduct set information from.

ehdl
The IAEngineHandle that was returned by the agent's addEngine() function. The handle tells the unloadConductSet() function which concrete engine to unload the conduct set from.

csname
The name of the conduct set that is to be unloaded. If the conduct set is not in the top collector of the IALibrary, then the name includes the path of collectors (not including the top Collector itself) that must be traversed to reach the conduct set. For example:
     \collectorA\collectorB\conductSetName       (OS/2, Windows)
     /collectorA/collectorB/conductSetName       (AIX)

selector
The selector that identifies the conduct set. This should match the selector that was used when this conduct set was originally loaded.

Returns

Nothing.

dbgInfo
   C++:  void dbgInfo(ostream &o) const;

   Java:  void dbgInfo(OutputStream o);
   Java:  void dbgInfo(Writer o);

Prints a debugging representation of this agent.

Parameters:

o
The output stream to which the output is written.

Returns:

Nothing.

Callback Functions

handleAlert
   C++:  virtual void handleAlert(const char *id,
                                  const IAAlertLevel sev,
                                  IAFactSet &fset);

   Java: void handleAlert(String id,
                          IATypes.IAAlertLevel sev,
                          IAFactSet fset)

This method gets control when a component of the agent (engine, adapter, library, etc.) generates an alert. The alert could be a warning of some potential problem, a notification that the component is disabled in some way, or an indication that a fatal condition has caused the component to cease all operations.

Parameters

*id
String containing an alert identifier, in the form of component:domain:problemType.

sev
An IAAlertLevel indication of the severity of the alert.

Valid IAAlertLevel values are:

(C++) IAWarning

(Java) IATypes.IAAlertLevel.IAWarning

Indicates that there is potential for a problem, and some action may be required to prevent it from happening.

(C++) IADegraded

(Java) IATypes.IAAlertLevel.IADegraded

Indicates that the component is working in a degraded mode. Generally, the degradation would have a limited scope (i.e. broken for only a particular selector, or only a particular function isn't working). This is more severe than a warning, but the component is still able to 'limp along'.

(C++) IAFatal

(Java) IATypes.IAAlertLevel.IAFatal

Indicates that the component is no longer functional.

*fset
Fact set containing facts that describe the error.

Standard facts that are included by the IBM Agent Building Environment Developer's Toolkit with every alert (not necessarily in this order) are:

FailingComponentType(String)
FailingType(String)
FailingDomain(String)
FailingName(String)

The type, domain, and name are analogous to EventType, EventName and EventDomain.

If the alert is related to the processing of a particular event, then the following facts may also be included by the IBM Agent Building Environment Developer's Toolkit (not necessarily in this order):

FailingEventId(String)
FailingEventType(String)
FailingEventName(String)
FailingEventDomain(String)
FailingEventSelector(String)
FailingEventTime(String String)

Any additional facts that may be included in the fact set are determined by (and set by) the failing component, and should be documented by the component (most likely in the documentation describing the component's generateAlert() method).

Default Actions

If the handleAlert() method is not implemented in the concrete adapter, the default implementation will display an alert message, followed by the alert id, the severity, and the facts

The default implementation takes additional action based on the severity of the alert, as follows:

IAWarning
Agent continues running. No additional action is taken.

IADegraded
Agent continues running. No additional action is taken.

IAFatal
Agent shuts down.

The shutdown occurs on a separate thread to prevent deadlocks with the calling component. Control is returned to the calling component immediately after the shutdown thread is started. The shutdown is accomplished by calling the concrete agent stop() method, and then exiting the process.

Threading and Locking Considerations

This method receives synchronous control directly from the reporting component. The component may be in the middle of processing an event, and could be delaying the event from completing. Therefore, if you implement any actions that involve invoking any of the IBM Agent Building Environment Developer's Toolkit API's, you must implement those actions on a separate thread, and return immediately on the handleAlert() thread. Otherwise, your agent may experience a deadlock condition.

You do not need to start a new thread to loop through the input fact set analyzing or printing the facts.

Returns

Nothing.

Exceptions (IAError)

The synchronous interface allows the agent to throw an IAError back to the adapter. The types of error are dependent on the specific agent's implementation of handleAlert().

The default implementation of handleAlert() does not throw any IAErrors.

Class IAAdapterHandle

An IAAdapterHandle is a token that is used to access the IAAgent's IAAdapter objects. An agent program instantiates the handle, and then initializes it through the IAAgent::addAdapter() function. The agent program then uses the IAAdapterHandle as an input parameter to other IAAgent functions.

Header File

#include <iatk/handles.h>

Constructors

IAAdapterHandle
   C++:  IAAdapterHandle()

   Java:  IAAdapterHandle()

Creates a new adapter handle object.

Parameters:

None.

Member Functions

== (operator overload)
   C++:  int operator ==(const IAAdapterHandle &rhs) const

This is the equality operator overload.

Parameters:

rhs
An adapter handle object

Returns

true(1)
the adapter handles are equal - both handles represent the same IAAdapter object.

false(0)
the adapter handles are not equal - the handles represent different IAAdapter objects.

!= (operator overload)
   C++:  int operator !=(const IAAdapterHandle &rhs) const

This is the inequality operator overload.

Parameters:

rhs
An adapter handle object

Returns

true(1)
the adapter handles are not equal - the handles represent different IAAdapter objects

false(0)
the adapter handles are equal - both handles represent the same IAAdapter object.

isValid
   C++:  int isValid() const

The isValid() function checks to see whether the adapter handle object is valid. The adapter handle object is valid if it has been associated with a valid IAAdapter object. The IAAgent::addAdapter() function is one method that sets up this valid association.

Parameters:

None.

Returns

true(1)
the adapter handle is valid - it is associated with an IAAdapter object.

false(0)
the adapter handle is not valid - it is not associated with any IAAdapter object.

Class IAEngineHandle

An IAEngineHandle is a token that is used to access the IAAgent's IAEngine object. An agent program instantiates the handle, and then initializes it through the IAAgent::addEngine() function. The agent program then uses the IAEngineHandle as an input parameter to other IAAgent functions.

Header File

#include <iatk/handles.h>

Constructors

IAEngineHandle
   C++:  IAEngineHandle()

   Java:  IAEngineHandle()

Creates a new engine handle object.

Parameters:

NONE.

Member Functions

== (operator overload)
   C++:  int operator ==(const IAEngineHandle &rhs) const

This is the equality operator overload.

Parameters:

rhs
An engine handle object

Returns

true(1)
the engine handles are equal - both handles represent the same IAEngine object

false(0)
the engine handles are not equal - the handles represent different IAEngine objects.

!= (operator overload)
   C++:  int operator !=(const IAEngineHandle &rhs) const

This is the inequality operator overload.

Parameters:

rhs
An engine handle object

Returns

true(1)
the engine handles are not equal - the handles represent different IAEngine objects.

false(0)
the engine handles are equal - both handles represent the same IAEngine object.

Class IALibraryHandle

An IALibraryHandle is a token that is used to access the IAAgent's IALibrary object. An agent program instantiates the handle, and then initializes it through the IAAgent::addLibrary() function. The agent program then uses the IALibraryHandle as an input parameter to other IAAgent functions.

Header File

#include <iatk/handles.h>

Constructors

IALibraryHandle
   C++:  IALibraryHandle()

   Java:  IALibraryHandle()

Creates a new library handle object.

Parameters:

NONE.

Member Functions

== (operator overload)
   C++:  int operator ==(const IALibraryHandle &rhs) const

This is the equality operator overload.

Parameters:

rhs
A library handle object

Returns

true(1)
the library handles are equal - both handles represent the same IALibrary object.

false(0)
the library handles are not equal - the handles represent different IALibrary objects.

!= (operator overload)
   C++:  int operator !=(const IALibraryHandle &rhs) const

This is the inequality operator overload.

Parameters:

rhs
A library handle object

Returns

true(1)
the library handles are not equal - the handles represent different IALibrary objects.

false(0)
the library handles are equal - both handles represent the same IALibrary object.

isValid
   C++:  int isValid() const

The isValid function checks to see whether the library handle object is valid. The library handle object is valid if it has been associated with a valid library object. The IAAgent::addLibrary() function is one method that sets up this valid association.

Parameters:

None.

Returns

true(1)
the library handle is valid - it is associated with an IALibrary object.

false(0)
the library handle is not valid - it is not associated with any IALibrary object.


[ Top of Page | Previous Page | Next Page | Table of Contents ]