Building and starting an agent includes the following run time functions:
More information on writing your own agent program can be found in Chapter 10. "Adding an Agent to Your Application".
The IAAgent class (refer to Chapter 2. "Agent Reference" of the Components and Adapter Reference book) is provided to give you the ability to write your own agent program. You configure the agent by using the addEngine(), addAdapter(), and addLibrary() methods. The configuration requirements can be either imbedded (hard-coded) in your agent program or provided as input to your agent program through menus, files, commands, or other methods that are appropriate for your application.
You can use the loadConductSet() and unloadConductSet() methods to initially load and subsequently change the loaded conduct sets for your application. The loaded conduct sets represent the currently available rules and facts that can control inferencing for your application. Refer to Chapter 2. "Agent Reference" of the Components and Adapter Reference book for more information on loading and unloading conduct sets for your application.
After establishing your agent configuration and initial conduct sets, your agent program can use the IAAgent start() method to start the agent. It can also use stop() to stop the agent program.
When an adapter uses the Java interface, (such as the sample Stock Adapter) it requires the use of the Java Interface Adapter (loadable module iagajava) and a Java class to represent the adapter.
The Java Interface Adapter is a special adapter that supports adapters that are written in Java. You do not have to be aware of what it does for your Java adapter because it is all done for you internally. In general it handles some of the adapter initialization and callback functions for your Java adapter and gets them to your adapter in a manner that is consistent with the Java adapter interface. You only need to specify the the Java interface adapter loadable module (iagajava) when configuring an adapter that is written in Java. If you write your own agent program, Java adapters are specified by using the addAdapter() method of IAAgent (refer Chapter 2. "Agent Reference" of the Components and Adapter Reference book for use of the method). The addAdapter() method's second parameter (loadable module name) is always iagajava.
To specify the class name for an adapter that is written in Java via your own agent program, use addAdapter (refer to Chapter 2. "Agent Reference" of the Components and Adapter Reference book for details of the method). The addAdapter() method's third parameter allows you to pass parameters for initializing the adapter. In the case of a Java adapter, this parm must be a string and the first word of that string must be the Java package and class name that contains the IAAdapter methods for that adapter. For example, were you to specify the Java package and class name for the sample Stock Adapter, it would be: ibm.AgentBuilder.samples.stock.StockAdapter. If your adapter requires additional start-up parameters, they would follow this classname parm that is required for adapters written in Java.
The java classes needed by the Java Interface Adapter to support the adapters that are written in Java are in the abesampl.jar file. This file should be in your CLASSPATH statement along with the Java runtime class files. (For any adapter written in Java your CLASSPATH should identify a directory that contains all of the Java classes used to implement that adapter).
Whether you write your own agent program or use the sample agent program (both described below), you may want to use one or more of the adapters that are provided by the IBM Agent Building Environment Developer's Toolkit. To configure these particular adapters, you will need to know the domain name and dll name (loadable module name) for each of these adapters. Following is a summary of that information:
Domain Name DLL Name Java Package/Class File iagafile HTTP iagahttp NNTP iaganntp Time iagatime Util iagautil SampMail sampmail StockAdapter iagajava ibm.AgentBuilder.samples.stock.StockAdapter (for the StockAdapter, as for any Java adapter, iagajava is the DLL for the for the Java Interface Adapter. The Java Interface Adapter is an internal adapter that is used to bridge some IAAdapter methods from Java to C++).The domain name is a case-sensitive, unique identifier for each adapter and is used in various ways to identify an adapter by the agent and/or engines. The DLL name is used to load the code for the adapter at run time. For adapters written in Java, the DLL name specified is the DLL for the internally supplied Java Interface Adapter, DLL name iagajava.
There are two sample agent programs, one written in C++ and one in Java. You run the C++ sample agent by invoking iagent. To start the Java sample agent you invoke the following:
The java classes needed by the Java sample program are in the agentbld.jar file. This file must be in your CLASSPATH statement along with the Java runtime class files.
The options that you can specify with either of these sample agent programs are described below.
If you use one of these sample agent programs, your agent is built at run time based on configuration selections in a configuration file that you set up before you run the agent program. This configuration file includes statements for defining the parts of the IBM Agent Building Environment Developer's Toolkit that are to be selected for use, as well as the conduct sets that are to be initially loaded for inferencing by the agent. The agent is automatically started by the sample agent program after this initial configuration is completed.
-fFILENAME where FILENAME is the name of the configuration file to use. By default, iagent.cfg in your current directory is used. The configuration file is used to control which engines and adapters are to be configured for the agent program. The configuration file is described below. -c Check the configuration file. The named engines and adapters are loaded, but the agent is not started. -v Verbose. Causes the agent registry to be printed to standard output before starting the agent. -d Run the agent as a background program (a "daemon"). In this mode, after starting the agent, commands will not be read from standard input. The agent is terminated by sending one of the following signals: SIGINT (ctl-C), SIGTERM. This option is in effect automatically if standard input is not a tty. -m Activate throughput monitoring. This option monitors the agent throughput, and regularly prints a message to the console indicating the number of completed events per second (events/second). Currently the monitoring occurs every 3 seconds. -? Display help information for the agent program
A slash may be used instead of a dash to start an option. Further, options may be grouped together in one argument preceded by a dash or slash. For example, "iagent -vd" says to start the agent with the -v and -d options in effect.
After starting the agent program, iagent will read commands from standard input if the daemon option is not in effect. The following commands are recognized:
help or ? - Display help information for available commands quit, stop, or end - Terminate the agent program loadcs csname selector - Dynamically load conduct set. See NOTE below for details on the csname (conduct_set_name) and selector parameters. If this is replacing a conduct set that was loaded previously (same conduct set and selector), then it may be appropriate to use the reset command (below) before using this command (to also reset the adapter's state for the specified selector. unloadcs csname selector - Dynamically unload conduct set. See NOTE below for details on the csname (conduct_set_name) and selector parameters. If you are finished with a conduct set and not wanting to replace it with another one, it is appropriate to use use this command. However, if you also want to reset all state for adapters in scope of this conduct set's selector, you would use the reset command (below) instead of this command. reset selector - Dynamically reset the engine and all adapters state in the scope of the specified selector. This includes unloading conduct set(s) that are associated with the specified selector. If you want to stop inferencing on conduct set(s) for a selector, but preserve adapter's state for that selector, use the unload command instead.
Note: See "Configuration File for the Sample Agent Programs". "conductset". Sending EOF on standard input will cause iagent to cease reading from standard input, waiting exclusively on a signal to terminate the agent program.
When an adapter uses the Java interface, (such as the sample Stock Adapter) it requires the use of the Java Interface Adapter (loadable module iagajava) and a Java class to represent the adapter.
The Java Interface Adapter is a special adapter that supports adapters that are written in Java. You do not have to be aware of what it does for your Java adapter because it is all done for you internally. In general it handles some of the adapter initialization and callback functions for your Java adapter and gets them to your adapter in a manner that is consistent with the Java adapter interface. You only need to specify the the Java interface adapter loadable module (iagajava) when configuring an adapter that is written in Java. For the sample agent, you do this by specifying it in the configuration file, as described in "Configuration File for the Sample Agent Programs". To specify the Java class name via the sample agent for an adapter that is written in Java, see "Configuration File for the Sample Agent Programs".
The java classes needed by the Java Interface Adapter to support the adapters that are written in Java are in the agentbld.jar file. This file should be in your CLASSPATH statement along with the Java runtime class files. (For any adapter written in Java your CLASSPATH should identify a directory that contains all of the Java classes used to implement that adapter).
The Configuration File allows you to communicate your selection of an agent configuration. The default configuration file name is iagent.cfg. You can use the Configuration File to define an agent configuration consisting of components from the IBM Agent Building Environment Developer's Toolkit, and, in the case of adapters, you can configure in adapters that you have written yourself. You have the capability for establishing and changing this configuration each time that you start up an agent using the functions from the IBM Agent Building Environment Developer's Toolkit. With this Level 6 of the IBM Agent Building Environment Developer's Toolkit, some of your configuration choices are limited. As further development takes place, these choices will grow to permit choices of many more adapters, additional engines, and additional library repositories.
The following are the valid statements that you can use in the Configuration File. Each statement occupies a line in the file, where a line ends with a newline character (ENTER key). You separate keywords with one or more blanks. Empty lines in the file are ignored. Lines beginning with # or * can contain your comments. Keywords for an entry must begin in the first position of a line. The first keyword is not case sensitive.
Statements should appear in exactly the following order:
This statement is used once for each engine that you require. For this version, there is only one choice for the engine. You should use the following engine_type:
RAISE
The engine_type is case sensitive.
You should use the following loadable_module_name:
iagerais
parameters allow for entering a string of engine-specific parameters (optional). There are none defined at this time.
Note: For adapters written in Java, refer to another form of the adapter statement, described below.
This statement is used once for each C++ adapter that you require.
The following information can be used to specify one or more (each) of the supplied adapters:
adapter_domain_name: loadable_module_name: (description): File iagafile File Adapter HTTP iagahttp HTTP Adapter NNTP iaganntp NNTP Adapter Time iagatime Time Adapter Util iagautil Utility Adapter SampMail sampmail Sample E-mail
If you add adapters that are not supplied with the IBM Agent Building Environment Developer's Toolkit, you must provide similar information for each via adapter statements.
parameters allow for entering a string of adapter-specific parameters (optional). These are defined by the individual adapters. These parameters are passed through the agent to the adapter via the newAdapter() method (see Chapter 3. "Adapter Reference Material" of the Components and Adapter Reference book).
The adapter_domain_name is case sensitive.
This statement is used once for each Java adapter that you require.
The following information can be used to specify the supplied adapter:
adapter_domain_name: java_class_name: StockAdapter ibm.AgentBuilder.samples.stock.StockAdapter
If you add adapters that are not supplied with the IBM Agent Building Environment Developer's Toolkit, you must provide similar information for each via adapter statements.
parameters allow for entering a string of adapter-specific parameters (optional). These are defined by the individual adapters. These are defined by the individual adapters. These parameters are passed through the agent to the adapter via the newAdapter() method (see Chapter 3. "Adapter Reference Material" of the Components and Adapter Reference book).
The adapter_domain_name is case sensitive.
The library_type is a token that is passed through the interface to the library implementation. If the library has multiple implementations in one loadable module (e.g. a file implementation, a database implementation, etc), this token can be used by the library to determine which implementation the agent wishes to use. For the library implementation provided with this version, there is only one choice for the library type. The library_type is
file
The loadable_module_name is the name of the DLL that contains the implementation of the library. For the library implementation shipped with this version, there is only one choice for the loadable module name.
The loadable_module_name is
iaglibf
The map is your indication to the library for navigating to the persistent storage object that represents the top Collector for the library. In the current platform and library repository, this is a path string to get to a directory that you have previously created to anchor the Agent Building Environment Developer's Toolkit Library persistent objects. Initially, you create and name an empty directory, but this should be done only once.
In this Level 6 of the IBM Agent Building Environment Developer's Toolkit this is the collection point for your rules, as you specify to the rule editor when you built the rules. Although you may use the rule editor to create multiple such collection points for rules, the iagent program does not currently look for more than one Collector (anchor point for rules). That is, to change to a different Collector, you must change the configuration file (map and top_collector_name), then restart the agent program.
You may have multiples of these Collectors (represented by subdirectories in the current platform), but can identify only one of these to the iagent program at a time.
In later versions of the Agent Building Environment Developer's Toolkit this can be the root of the Agent Building Environment Developer's Toolkit Library from which it can be used to instantiate multiple Collectors, for multiple, hierarchical sets of inferencing information. See Chapter 8. "Using the ABE Rule Editor" for more information. Your path name has the following form:
drive:\dir1\dir2\
For example,
c:\mytop\mynext\
The top_collector_name is the name that you have assigned to the subdirectory that you created to represent the top Library Collector, as discussed above. This name is directly appended to the the map string given in the previous parameter to form a path to the top library directory.
For example:
c:\mytop\mynext\libtop
c:\mytop\mynext\ is the map and libtop is the top_collector_name.
The collector_levels is the number of collector levels in the library hierarchy. This includes the top collector. This parameter is optional and defaults to 2 levels. The parameter is used by the library to cache all collectors except for the last level, in anticipation of additional conduct sets being loaded from them.
For example, if your library hierarchy looks like this:
top_collector / \ collector_A collector_B / \ collector_A_1 collector_B_1 / \ conduct_set_A conduct_set_B
or in linear terms, the library path to the conduct sets looks like this:
map\top_collector\collector_A\collector_A_1\conduct_set_A map\top_collector\collector_B\collector_B_1\conduct_set_B
Then the number of collector levels is 3 (top_collector is the first level, collector_A and collector_B are both at the second level, and collector_A_1 and collector_B_1 are at the third (and last) level).
You should use just one library statement.
This statement loads some rules, and potentially some long term facts for use in inferencing.
The engine_type associates the engine with the loaded conduct set. Currently, you should use the following engine_type
RAISE
The name that you use here for conduct_set_name should correspond to one of the names assigned to a RuleSet. The conduct_set_name includes any collectors that are needed to traverse from the top collector to the conduct set.
For example, if your library hierarchy looks like this:
top_collector / \ collector_A collector_B / \ collector_A_1 conduct_set_B / conduct_set_A
then to load conduct_set_A you would specify a conduct_set_name of:
conductset \collector_A\collector_A_1\conduct_set_A (OS/2 and Windows)
or conductset /collector_A/collector_A_1/conduct_set_A (AIX)
But if your library hierarchy only has this:
top_collector / \ conduct_set_A conduct_set_B
then to load conduct_set_A you would specify a conduct_set_name of:
conductset conduct_set_A
To load a LTFactSet with the RuleSet, they must have the same name and be in the same collector. LTFactSet loading is optional in that it is loaded with the RuleSet only if one is found with the same name as the RuleSet.
If the conduct_set_name contains imbedded blanks, then it must be specified within double quotes. To imbed a double quote within a quoted conduct_set_name, use a pair of double quotes.
For example, if the conduct set name is: John "Ace" Doe
then you specify:
conductset "John ""Ace"" Doe" selector
But if the conduct set name is just: JohnDoe
then you specify"
conductset JohnDoe selector
The selector is used to associate events with conduct sets. When the parameter is specified, all events which contain the specified selector will be driven through this conduct set. When the parameter is not specified, it defaults to the 'null selector'. In this case, all events that contain the 'null selector' will be driven through this conduct set. A given selector may be used for more than one conduct set (i.e. may appear on more than one conductset statement).
If the selector contains imbedded blanks, then it must be specified within double quotes. To imbed a double quote within a quoted selector, use a pair of double quotes.
For example, if the selector is: Jane "Doe"
then you specify:
conductset conduct_set_name "Jane ""Doe"""
But if the selector is just: JaneDoe
then you specify"
conductset conduct_set_name JaneDoe
You can have as many conduct sets as you wish and you can load as many of them as you wish, each with a separate conductset statement. You should realize, however, that adapter-originated events will drive the rules of all loaded conduct sets whose selector matches the event's selector.
This is an optional indicator of the last line of the Configuration File. It signals the end of the statements and starts the agent. When omitted, end of file has the same meaning. If used, this statement should be the last line of the Configuration File.