IBM Agent Building Environment Developer's Toolkit


Chapter 4. Library Reference

Compiling and Linking Your Application with IALibrary

Refer to Chapter 1. "Building ABE-Related Components" for assistence in compiling and linking with the IBM Agent Building Environment Developer's Toolkit Library Component classes that follow.

Class IALibrary

As explained in "Library Build and Start-up" of the User's Guide book, You can use the agent Library in several ways: in the agent itself for loading conduct sets for inferencing, by applications for authoring rules and facts, etc.. For the former (you do not work directly with an IALibrary object, but you work with an IALibraryHandle instead. This is to prevent you from accidentally affecting the internal workings of the agent itself. However, for application use of the agent Library, you are expected to use the IALibrary object directly.

Specifically you construct an IALibrary ojbect to represent the instance of the library that you want to access. Then you use the addImplementation() method of IALibrary to dynamically link to the Library. You can do this from the same, or a different process and thread than the one in which the agent is running. This allows you to concurrently change rules and facts while the agent is running.

When your application constructs an IALibrary object for direct use of the Library by the application, and does an attachImplementation() for that IALibrary object, generally you will also want to do a get() for the library top Collector to fill the top Collector object that is associated with the IALibrary object. After doing this, you can use the top Collector (and its sub-Collectors), you have completed the initialization of the Library and are ready to use the Library from your application.

One example of using the Library is to establish IALibrary and its top Collector instantiation in your application in such a way as to preserve these objects over time, such as in a server where client activities are represented by threads that come and go. In this case you can initialize the Library once and retain it globally, passing it for use by the client activity threads. A single top Collector thus shared across threads is implicitly kept current by the Library implementation for any and all changes through the Library interface as long as that common Collector object instance is employed. This top Collector sharing model is practical only within the scope of the shared object, a process, for example. When employing this common IALibrary and top Collector sharing model, you must be careful to avoid loss of those objects. For example, you should take precautions to avoid Java implicit garbage collection of these objects. &iabtk. does not take actions to prevent such garbage collection.

As mentioned above, when you configure the Library Component of an agent, you do not use the IALibrary object directly. Instead you construct an IALibraryHandle object and pass it as a parameter on the addLibrary() method of the IAAgent object. The addLibrary() method makes the IALibraryHandle operable for you to reference the agent Library. That is, it enables you to use the IALibraryHandle in other methods. This is consistent with other agent components (engines and adapters) that also provide for use of "handles" as representations of their corresponding top objects (IAEngine, IAAgent etc.). Like engines and adapters, it is conceptually possible to configure more than one Library instance for an agent, although this is not supported at this time.

When you statically link (makfile) you select the general interface to the Library based on the dll selection (iaglibr for c++, iaglibj for Java). At runtime, you dynamically link to the library implementation. Currently there is only one implementation of the Library: iaglibf (dll), a file system implementation, although this file implementation runs on several system platforms. The attachImplementation() method of IALibrary allows you to dynamic link to the Library file implementation. If more implementations are added, such as a data base implementation, this choice would become more significant. Should another implementation become available, the intention is that it would plug in dynamically as a new IALibrary dll.

IALibrary is also a "factory" object through which you can construct and destruct the various library objects: such as IALibInferenceCollector and IALibInferenceRuleSet.

Finally, it includes methods that allow use of a high level interface to the Library for obtaining inferencing material from the Library: getConductSet() and getInferenceSet(). These are used by the agent (internally) when conduct sets are loaded. They aree not appropriate for Rule Editors because they do not allow for updating inferencing material.

A shortened form of object names is used in some of the following descriptions, leaving off the "IALibInference" class name prefix.

Constructors

IALibrary
   C++ :  IALibrary()

   Java:  IALibrary()

Creates a new IALibrary object.

Parameters:

None

Basic Member Functions

attachImplementation
   C++ :  void attachImplementation(const char* map,
                                   const char* type,
                                   const char* dllname
                                   const char* libname,
                                   int numColLevels)
                                   throw(IAError)

   Java:  void attachImplementation(String map,
                                   String type,
                                   String dllname
                                   String libname,
                                   int numColLevels)
                                   throws IAError

This member function establishes the particular IALibrary implementation based on parameters supplied (dllname and type). It also creates the Library top Collector object. It does not do a get() for the top Collector, therefore the top Collector object is not filled from persistent storage. To use the top Collector you should use the get() method of the top Collector object to fill the top Collector.

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 would have no drive and have forward slashes, e.g. home/x/y/z/. The attachImplementation() method internally appends string that you provide in this map parameter with the string that you provide in the libname parameter (described below) to form the path to the top Collector. For example, C:\x\y\z\libtop.

type - the type of Library implementation. Currently file is the only supported implementation.

dllname - the name of the library dll that is to be dynamically linked. Currently you can only select iaglibf for the file implementation.

libname - 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.

numColLevels - This is the number of levels of Collectors that you expect to have in your Library. It is used in managing the cache of Collectors for engines that use getConductSet or getInferenceSet, where Collectors are created and managed implicitly by the Library (read only). For rule editors, where Collectors are not managed implicitly, and where getConductSet() is not intended for use, this parameter is not significant (can default and is ignored by the Library).

Returns:
none

getMap
   C++ :  const char* getMap() const throw(IAError)

   Java:  String getMap() throws IAError

This gets the map attribute. It is null until set by attachImplementation().

Parameters:

None.

Returns:
const char* (in Java, String) - extracted map.

getType
   C++ :  const char* getType() const throw(IAError)

   Java:  String getType() throws IAError

This gets the type attribute. It is null until set by attachImplementation().

Parameters:

None.

Returns:
const char* (in Java, String) - extracted type.

getDllName
   C++ :  const char* getDLLName() const throw(IAError)

   Java:  String getDllName() throws IAError

This gets the dllname attribute. It is null until set by attachImplementation().

Parameters:

None.

Returns:
const char* (in Java, String) - extracted dllname.

getLibName
   C++ :  const char* getLibName() const throw(IAError)

   Java:  String getLibName() throws IAError

This gets the libname attribute. It is null until set by attachImplementation().

Parameters:

None.

Returns:
const char* (in Java, String) - extracted libname.

getTop
   C++ :  IALibInferenceCollector* getTop() const

   Java:  IALibInferenceCollector getTop()

This gets a pointer (in Java, the object) to the current Top Collector of the Library. This is used by an agent to build a library handle, which is used by IAEngine to use the Library to get inferencing material. It is also used by rule editors as a starting point (parent) for instantiating additional Collectors.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceCollector * - pointer to the Library's top Collector.

width=60 scale=auto.Java: IALibInferenceCollector - the Library's top Collector.

getConductSet
   C++ :  void getConductSet(const char* csName,
                             const char mdName,
                             const char* qualifiedCollectorName,
                             IALibInferenceRuleSet* * ruleSet,
                             IALibInferenceLTFactSet* * factset)
                             throw(IAError)

   Java:  void getConductSet(String csName,
                             char mdName,
                             String qualifiedCollectorName,
                             IALibInferenceRuleSet ruleSet,
                             IALibInferenceLTFactSet factset)
                             throws IAError

This member function gets a rule set and optional long term fact set from the Library. The qualifiedCollectorName specifies the qualified Collector name and the csName indicates the conduct set name that is to be retrieved. In C++, The invoker is responsible for destructing the IALibInferenceRuleSet and IAInferenceLTFactSet objects when pointers to them are returned.

Only "active" rules and long term facts are loaded.

When no exceptions are thrown, pointers (in Java, the objects) to these objects are returned, whether or not they are found in persistent storage; however, they may have size=0 (empty). Size of 0 may indicate that the object did not exist prior to this or than it existed, but had no rules or facts in it. In either case, you cannot use the contents of the object with size=0 to do inferencing (because it is empty).

You cannot use this method for obtaining inference material that is to be changed. That is, the put() method on the returned objects is not to be used. The mdName parameter specifies that metadata for the rule set be obtained with the rule set.

Parameters:

csName - This parameter contains a string that specifies the conduct set name.

mdName - is the name of the metadata that is associated with the conduct set. Currently 0. should be specified. This metadata is returned with the rule set.

qualifiedCollectorName - Collector hierarchy, that establishes the Collector that contains the desired conduct set. The string has the form \x\y\ (or /x/y/ for UNIX-based platforms), for example. The Collector that contains the conduct set is the last part of the qualified name, y in this example. In this example, x its the name of the first Collector under the top Collector. That is, the top Collector is not to be included in the qualifiedCollectorName (it is implied).

ruleset - is the returned pointer to a pointer (in Java, the object) to the rule set that is constructed as a result of the current method. In C++, the invoker is responsible for destructing this IALibInferenceRuleSet when finished with it.

factset - is the returned pointer to a pointer (in Java, the object) to the long term fact set that is constructed as a result of the current method. In C++, the invoker is responsible for destructing this IALibInferenceLTFactSet when finished with it. This object is only returned when there is one (optional).

Returns:
None.

getInferenceSet
   C++ :  void getInferenceSet(const char* rsName,
                             const char* ltfsName,
                             const char rsmdName,
                             const char ltfsmdName,
                             const char* qualifiedCollectorName,
                             IALibInferenceRuleSet* * ruleSet,
                             IALibInferenceLTFactSet* * factset)
                             throw(IAError)

   Java:  void getInferenceSet(String rsName,
                             String ltfsName,
                             char rsmdName,
                             char ltfsmdName,
                             String qualifiedCollectorName,
                             IALibInferenceRuleSet ruleSet,
                             IALibInferenceLTFactSet factset)
                             throws IAError

This gets a rule set and optional long term fact set from the Library. The qualifiedCollectorName specifies the qualified Collector name for rsName (rule set) and optional ltfsName (optional long term fact set) that are to be retrieved. In C++, The invoker is responsible for destructing the IALibInferenceRuleSet and IAInferenceLTFactSet objects when pointers to them are returned. Only "active" rules and long term facts are loaded.

When no exceptions are thrown, pointers (in Java, the objects) to these objects are returned, whether or not they are found in persistent storage; however, they may have size=0 (empty). Size of 0 may indicate that the object did not exist prior to this or than it existed, but had no rules or facts in it. In either case, you cannot use the contents of a object with size=0 to do inferencing (because it is empty).

You cannot use this method for obtaining inference material that is to be changed. That is, the put() method on the returned objects is not to be used. The rsmdName parameter and optional ltfsmdName parameter specify that metadata for the rule set and optional metadata for the long term fact set be obtained with the rule set and optional long term fact set. The IALibInferenceLTFactSet is returned only when one is found.

Parameters:

rsName - This parameter contains a string that specifies the rule set name that is to be retrieved.

ltfsName - This parameter contains a string that specifies the long term fact set name that is to be retrieved.

rsmdName - is the name of the rule set metadata that is associated with the rule set. This metadata is to be returned with the rule set.

ltfsmdName - is the name of the long term fact set metadata that is associated with the long term fact set. This metadata is to be returned with the long term fact set.

qualifiedCollectorName - Collector hierarchy, that establishes the Collector that contains the desired conduct set. The string has the form \x\y\ (or /x/y/ for UNIX-based platforms), for example. The Collector that contains the conduct set is the last part of the qualified name, y in this example. In this example, x its the name of the top Collector.

ruleSet - is the returned pointer to a pointer (in Java, the object) to the rule set that is constructed as a result of the current method. In C++, The invoker is responsible for destructing this IALibInferenceRuleSet when finished with it.

factSet - is the returned pointer to a pointer (in Java, the object) to the long term fact set that is constructed as a result of the current method. In C++, The invoker is responsible for destructing this IALibInferenceLTFactSet when finished with it. This object is only returned when there is one (optional).

~IALibrary
  void ~IALibrary()

(C++ only) This is the destructor for IALibrary. When IALibrary is destroyed, the top Collector is also destructed (implicitly).

Parameters:

None.

Returns:
None.

Factory Member Functions

new_IALibInferenceCollector
   C++ :  IALibInferenceCollector* new_IALibInferenceCollector(
                                                  IALibInferenceCollector* Parent,
                                                  const char* CollectorName)

   Java:  IALibInferenceCollector  new_IALibInferenceCollector(
                                                  IALibInferenceCollector Parent,
                                                  String CollectorName)

Creates a new IALibInferenceCollector.

Parameters:

Parent - pointer (in Java, the object) to an IALibInferenceCollector that is to be the parent hierarchically of the one created by this constructor.

CollectorName - name to be assigned to the new Collector. The name is restricted to the number of characters allowed by the platform used. For example, if you use OS/2 HPFS, names longer than 8 characters are permitted.

Returns

a pointer (in Java, the object) to an IALibInferenceCollector

new_IALibInferenceContentsElement
   C++ :  IALibInferenceContentsElement* new_IALibInferenceContentsElement(
                               const char* ObjectName="",
                               IALibInferenceContentsElementType
                                        ObjectType=IALibICET_ceunknown,
                                char MetadataName=' ')

   Java:  IALibInferenceContentsElement new_IALibInferenceContentsElement(
                               String ObjectName, char ObjectType, char MetadataName)
                               throws IAError
           IALibInferenceContentsElement new_IALibInferenceContentsElement(
                               String ObjectName, char ObjectType)
                               throws IAError
           IALibInferenceContentsElement new_IALibInferenceContentsElement(
                               String ObjectName) throws IAError
           IALibInferenceContentsElement new_IALibInferenceContentsElement()
                               throws IAError

Returns a new IALibInferenceContentsElement. The most common way for ContentsElements to be instantiated is implicitly through a get member function of a Collector object, which instantiates a ContentsElement for each object contained in the Collector contents in persistent storage. The get function constructs the ContentsElements and orders them by object name.

Parameters:

ObjectName - name of the object that the ContentsElement represents.

ObjectType - following are defined IALibInferenceContentsElementTypes (case sensitive) that you can specify:

MetadataName - only required if type is metadata. This defaults to blank.

Returns

a pointer (in Java, the object) to an IALibInferenceContentsElement

new_IALibInferenceRuleSet
   C++ :  IALibInferenceRuleSet* new_IALibInferenceRuleSet(
                               IALibInferenceCollector* Parent,
                               const char* RuleSetName="default",
                               const char* RuleSetID="",
                               char RulesMetadataName=' ',
                               char* RuleSetMetadata="",
                               char RuleSetMetadataName=' ',
                               const char* RuleSetState=ACTIVERS)
   Java:  IALibInferenceRuleSet new_IALibInferenceRuleSet(
                               IALibInferenceCollector Parent, String RuleSetName,
                               String RuleSetID, char RulesMetadataName,
                               String RuleSetMetadata, char RuleSetMetadataName,
                               String RuleSetState)
                               throws IAError
           IALibInferenceRuleSet new_IALibInferenceRuleSet(
                               IALibInferenceCollector Parent, String RuleSetName,
                               String RuleSetID, char RulesMetadataName,
                               String RuleSetMetadata, char RuleSetMetadataName)
                               throws IAError
           IALibInferenceRuleSet new_IALibInferenceRuleSet(
                               IALibInferenceCollector Parent, String RuleSetName,
                               String RuleSetID, char RulesMetadataName,
                               String RuleSetMetadata)
                               throws IAError
           IALibInferenceRuleSet new_IALibInferenceRuleSet(
                               IALibInferenceCollector Parent, String RuleSetName,
                               String RuleSetID, char RulesMetadataName)
                               throws IAError
           IALibInferenceRuleSet new_IALibInferenceRuleSet(
                               IALibInferenceCollector Parent, String RuleSetName,
                               String RuleSetID)
                               throws IAError
           IALibInferenceRuleSet new_IALibInferenceRuleSet(
                               IALibInferenceCollector Parent, String RuleSetName)
                               throws IAError
           IALibInferenceRuleSet new_IALibInferenceRuleSet(
                               IALibInferenceCollector Parent)
                               throws IAError

Creates a new IALibInferenceRuleSet.

Parameters:

Parent - pointer (in Java, the object) to an IALibInferenceCollector that is to be the parent hierarchically of the new RuleSet created by this constructor.

RuleSetName - name to be assigned to the new RuleSet. The default is the name "default". The name is restricted in size to the number of characters of the platform used. For example, if you use OS/2 HPFS, names longer than 8 characters are permitted. Objects of a different type (Collector, RuleSet, and LTFactSet) can have the same name because they are distinguished internally by a type.

RuleSetID - RuleSet identifier.

RulesMetadataName - a single character 0-9 or A-Z to name the Rules level metadata. There can only be one such instance of Rules level metadata. The default of ' ' (blank) means no metadata name.

RuleSetMetadata - a char* for the actual RuleSet level metadata.

RuleSetMetadataName - a single character 0-9 or A-Z that names an instance of RuleSet level metadata. There can be as many instances of RuleSet level metadata as there are names (36), but only one can be named and associated with a RuleSet at a time. The default of ' ' (blank) means no metadata name.

RuleSetState - "A" for active; "I" for inactive. This can be used to indicate whether a RuleSet can be considered active or inactive when selected for inferencing. The default is active.

Returns

a pointer (in Java, the object) to an IALibInferenceRuleSet

new_IALibInferenceRule
   C++ :  IALibInferenceRule* new_IALibInferenceRule(
                               const char* RuleName="", const char* RuleID="",
                               const char* Kif="", const char* RuleMetadata="",
                               const char* RuleState=ACTIVER,
                               IABool RuleDelete=NOTDELETEDR)

   Java:  IALibInferenceRule new_IALibInferenceRule(
                               String RuleName, String RuleID,
                               String Kif, String RuleMetadata,
                               String RuleState, boolean RuleDelete)
                               throws IAError
           IALibInferenceRule new_IALibInferenceRule(
                               String RuleName, String RuleID,
                               String Kif, String RuleMetadata,
                               String RuleState)
                               throws IAError
           IALibInferenceRule new_IALibInferenceRule(
                               String RuleName, String RuleID,
                               String Kif, String RuleMetadata)
                               throws IAError
           IALibInferenceRule new_IALibInferenceRule(
                               String RuleName, String RuleID,
                               String Kif)
                               throws IAError
           IALibInferenceRule new_IALibInferenceRule(
                               String RuleName, String RuleID)
                               throws IAError
           IALibInferenceRule new_IALibInferenceRule(
                               String RuleName)
                               throws IAError
           IALibInferenceRule new_IALibInferenceRule() throws IAError

Creates a new IALibInferenceRule.

Parameters:

RuleName - name assigned to the Rule.

RuleID - Rule Identifier.

Kif - Rule itself in linear KIF (subset) format.

RuleMetadata - string of metadata that is associated with this Rule.

RuleState - "A" for active; "I" for inactive. This can be used to indicate whether a Rule is considered active or inactive when selected for inferencing. The default is active.

RuleDelete - true if deleted; false if not deleted. This controls the initial delete state of a rule. The default is not deleted.

Returns

a pointer (in Java, the object) to an IALibInferenceRule

new_IALibInferenceLTFactSet
   C++ :  IALibInferenceLTFactSet* new_IALibInferenceLTFactSet(
                               IALibInferenceCollector* Parent,
                               const char* LTFactSetName="default",
                               const char* LTFactSetID="",
                               char LTFactsMetadataName=' ',
                               char* LTFactSetMetadata="",
                               char LTFactSetMetadataName=' ',
                               const char* LTFactSetState=ACTIVEFS)

   Java:  IALibInferenceLTFactSet new_IALibInferenceLTFactSet(
                               IALibInferenceCollector Parent, String LTFactSetName,
                               String LTFactSetID, char LTFactsMetadataName,
                               String LTFactSetMetadata, char LTFactSetMetadataName,
                               String LTFactSetState)
                               throws IAError
          IALibInferenceLTFactSet new_IALibInferenceLTFactSet(
                               IALibInferenceCollector Parent, String LTFactSetName,
                               String LTFactSetID, char LTFactsMetadataName,
                               String LTFactSetMetadata, char LTFactSetMetadataName)
                               throws IAError
          IALibInferenceLTFactSet new_IALibInferenceLTFactSet(
                               IALibInferenceCollector Parent, String LTFactSetName,
                               String LTFactSetID, char LTFactsMetadataName,
                               String LTFactSetMetadata)
                               throws IAError
          IALibInferenceLTFactSet new_IALibInferenceLTFactSet(
                               IALibInferenceCollector Parent, String LTFactSetName,
                               String LTFactSetID, char LTFactsMetadataName,
                               throws IAError
          IALibInferenceLTFactSet new_IALibInferenceLTFactSet(
                               IALibInferenceCollector Parent, String LTFactSetName,
                               String LTFactSetID)
                               throws IAError
          IALibInferenceLTFactSet new_IALibInferenceLTFactSet(
                               IALibInferenceCollector Parent, String LTFactSetName)
                               throws IAError
          IALibInferenceLTFactSet new_IALibInferenceLTFactSet(
                               IALibInferenceCollector Parent)
                               throws IAError

Creates a new IALibInferenceLTFactSet.

Parameters:

Parent - pointer (in Java, the object) to an IALibInferenceCollector that is to be the parent hierarchically of the new LTFactSet created by this constructor.

LTFactSetName - name to be assigned to the new LTFactSet. The default is the name "default". The name is restricted in size to the number of characters of the platform used. For example, if you use OS/2 HPFS, names longer than 8 characters are permitted. Objects of a different type (Collector, RuleSet, and LTFactSet) can have the same name because they are distinguished internally by a type.

LTFactSetID - LTFactSet identifier.

LTFactsMetadataName - a single character 0-9 or A-Z to name the LTFacts level metadata. There can only be one such instance of LTFacts level metadata. The default of ' ' (blank) means no name.

LTFactSetMetadata - a string for the actual LTFactSet level metadata.

LTFactSetMetadataName - a single character 0-9 or A-Z that names an instance of LTFactSet level metadata. There can be as many instances of LTFactSet level metadata as there are names (36), but only one can be named and associated with a LTFactSet at a time. The default of ' ' (blank) means no name.

LTFactSetState - "A" for active; "I" for inactive. This can be used to indicate whether a RuleSet can be considered active or inactive when selected for inferencing. The default is active.

Returns

a pointer (in Java, the object) to an IALibInferenceLTFactSet

new_IALibInferenceLTFact
   C++ :  IALibInferenceLTFact* new_IALibInferenceLTFact(
                               const char* LTFactName="",
                               const char* LTFactID="",
                               const char* Kif="",
                               const char* LTFactMetadata="",
                               const char* LTFactState=ACTIVEF,
                               IABool LTFactDelete=NOTDELETEDF)

   Java:  IALibInferenceLTFact new_IALibInferenceLTFact(
                               String LTFactName, String LTFactID,
                               String Kif, String LTFactMetadata,
                               String LTFactState, boolean LTFactDelete)
                               throws IAError
          IALibInferenceLTFact new_IALibInferenceLTFact(
                               String LTFactName, String LTFactID,
                               String Kif, String LTFactMetadata,
                               String LTFactState)
                               throws IAError
          IALibInferenceLTFact new_IALibInferenceLTFact(
                               String LTFactName, String LTFactID,
                               String Kif, String LTFactMetadata)
                               throws IAError
          IALibInferenceLTFact new_IALibInferenceLTFact(
                               String LTFactName, String LTFactID,
                               String Kif)
                               throws IAError
          IALibInferenceLTFact new_IALibInferenceLTFact(
                               String LTFactName, String LTFactID)
                               throws IAError
          IALibInferenceLTFact new_IALibInferenceLTFact(
                               String LTFactName)
                               throws IAError
          IALibInferenceLTFact new_IALibInferenceLTFact()
                               throws IAError

Creates a new IALibInferenceLTFact.

Parameters:

LTFactName - name assigned to the LTFact.

LTFactID - LTFact Identifier.

Kif - LTFact itself in linear KIF (subset) format.

LTFactMetadata - string of metadata that is associated with this LTFact.

LTFactState - "A" for active; "I" for inactive. This can be used to indicate whether a LTFact is considered active or inactive when selected for inferencing. The default is active.

LTFactDelete - true if deleted; false if not deleted. This controls the initial delete state of a LTFact. The default is not deleted.

Returns

a pointer (in Java, the object) to an IALibInferenceLTFact

new_IALibLogRecordSet
   C++ :  IALibLogRecordSet* new_IALibLogRecordSet(
                 IALibInferenceCollector* cparent,
                 char* name,
                 int cacheSize = 40,
                 int logSize = 800,
                 unsigned int level = IALibLRT_activity_normal+IALibLRT_error,
                 unsigned int metadataSize = 1,
                 char metadataName = ' ')

   Java:  IALibLogRecordSet new_IALibLogRecordSet(
                 IALibInferenceCollector cparent,
                 String name,
                 int cacheSize,
                 int logSize,
                 int level,
                 int metadataSize,
                 char metadataName)
                 throws IAError

           IALibLogRecordSet new_IALibLogRecordSet(
                 IALibInferenceCollector cparent,
                 String name,
                 int cacheSize,
                 int logSize,
                 int level,
                 int metadataSize)
                 throws IAError

           IALibLogRecordSet new_IALibLogRecordSet(
                 IALibInferenceCollector cparent,
                 String name,
                 int cacheSize,
                 int logSize,
                 int level)
                 throws IAError

           IALibLogRecordSet new_IALibLogRecordSet(
                 IALibInferenceCollector cparent,
                 String name,
                 int cacheSize,
                 int logSize)
                 throws IAError

           IALibLogRecordSet new_IALibLogRecordSet(
                 IALibInferenceCollector cparent,
                 String name,
                 int cacheSize)
                 throws IAError

           IALibLogRecordSet new_IALibLogRecordSet(
                 IALibInferenceCollector cparent,
                 String name)
                 throws IAError

Creates a new IALibLogRecordSet.

Parameters:

cparent - pointer (in Java, the object) to an IALibInferenceCollector that is to be the parent hierarchically of the LogRecordSet created by this constructor.

name - name to be assigned to the LogRecordSet. The name is restricted in size to the number of characters in a directory name of the platform used. Objects of a different type (Collector, RuleSet, and LTFactSet) can have the same name because they are distinguished internally by a type.

cacheSize - the number of log records written in memory before being written to persistent storage. The default cacheSize is 40.

logSize - the number of log records stored in persistent storage before wraparound occurs. The default logSize is 800. The size of individual log records can vary based on type, category, originator, source id, message id, and the number and size of the tokens.

metadataSize - the size (expressed in number of characters) of the metadata in the LogRecrodSet. The default metadata size is 1. This is the size of an individual metadata cell, which is the unit of metadata that is available for each LogRecord in the LogRecordSet for log readers to use to mark log records that are viewed. This is applicable only when metadataName is not blank. The size can be set for a new log and connot be changed for an existing log. The same size applies to all instances of metadata for a particular LogRecordSet.

metadataName - named instance of metadata to be used to stor/retrieve metadata. When not specified, metadataName defaults to blank. Allowable characters include letters, a-z (lower case), and numbers (0-9). Metadata can be used by log readers to mark log records. Multiple instances of metadata allow for multiple instances of reader markup. That is, separate sets of metadata recording. Such multiple instances could allow for one viewer to have different recordings of metadata or for multiple viewers to each have their individual instances of metadata. This is optional, even if metadata already exists by this name. It controls whether or not the current LogRecordSet allows for retrieving or storing metadata.

level - indicates the type(s) of log records to be read by getRecord. The default level is IALibLRT_activity_normal and IALibLRT_error. The library does not enforce what types of log records can be written to the LogRecordSet.

Returns

a pointer (in Java, the object) to an IALibLogRecordSet

new_IALibLogRecord
   C++ :  IALibLogRecord* new_IALibLogRecord(
                      unsigned int type = IALibLRT_activity_normal,
                      int category = 0, char* originator = "",
                      char* sourceid = "", unsigned long messageid = 0,
                      char* token1 = "");

   Java:  IALibLogRecord new_IALibLogRecord(
                      int type,
                      int category,
                      String originator,
                      String sourceId,
                      int messageId,
                      String token1) throws IAError

           IALibLogRecord new_IALibLogRecord(
                      int type,
                      int category,
                      String originator,
                      String sourceId,
                      int messageId)
                      throws IAError

           IALibLogRecord new_IALibLogRecord(
                      int type,
                      int category,
                      String originator,
                      String sourceId)
                      throws IAError

           IALibLogRecord new_IALibLogRecord(
                      int type,
                      int category,
                      String originator)
                      throws IAError

           IALibLogRecord new_IALibLogRecord(
                      int type,
                      int category)
                      throws IAError

           IALibLogRecord new_IALibLogRecord(
                      int type)
                      throws IAError

           IALibLogRecord new_IALibLogRecord()
                      throws IAError

Creates a new IALibLogRecord. The date and time attributes of a LogRecord are initially set to the current date and time by the LogRecord constructor.

Parameters:

type - describes the type of information contained in the LogRecord. The values are binary equivalents such that the level setting of the containing LogRecordSet can be used to specify combinations of types. For example, a level setting of 10 would cause the LogRecordSet to only work with error (2) and detail (8) activity type log records. and are currently defined as follows:

category - a user-defined value. This can be used for whatever the user feels is appropriate.

originator - an identifier of the provider of the LogRecord information (e.g., adapter domain name or engine id).

sourceid - source id. An identifier that can be used to identify the cause of the LogRecord (e.g., event id, error id, rule name, RuleSet name).

messageid - message id. An identifier that can be used to find associated text in a repository (such as a message repository), where, optionally, NLS translation can be applied and parameters substituted in message text from the tokens attribute.

token1 - the first token (of possibly several tokens). A suggested use of the token(s) is for parameter substitution in a message file. Another is to simply record a line of text. This formatting decision can be based on type and category. A token should not contain newline (\n) characters.

If this first token is provided, then the internal cursor for the sequence of tokens is set to this token.

Returns

a pointer to an IALibLogRecord

delete_IALibInferenceCollector
   C++ :  void delete_IALibInferenceCollector(IALibInferenceCollector *p)

This provides for destructing a Collector. It destroys the object and its contained ContentsElements, but does not have any affect on persistent storage objects. Persistent storage is affected primarily by the put member function.

Parameters:

p - a pointer to the IALibInferenceCollector.

Returns:
No returned values.

delete_IALibInferenceContentsElement
   C++ :  void delete_IALibInferenceContentsElement(IALibInferenceContentsElement *p)

This provides for destructing a ContentsElement. It destroys the object, but does not have any affect on persistent storage objects. Persistent storage is affected primarily by the put member function.

Parameters:

p - a pointer to the IALibInferenceContentsElement.

Returns:
No returned values.

delete_IALibInferenceRuleSet
   C++ :  void delete_IALibInferenceRuleSet(IALibInferenceRuleSet *p)

This provides for destructing a RuleSet and its contained Rules. It destroys the object, but does not have any affect on persistent storage objects. Persistent storage is affected primarily by the put member function.

Parameters:

p - a pointer to the IALibInferenceRuleSet.

Returns:
No returned values.

delete_IALibInferenceRule
   C++ :  void delete_IALibInferenceRule(IALibInferenceRule *p)

This is the destructor for a Rule. It is normally invoked implicitly through the deleteRule member function of RuleSet or by the del() member function of Rule.

Parameters:

p - a pointer to the IALibInferenceRule.

Returns:
No returned values.

delete_IALibInferenceLTFactSet
   C++ :  void delete_IALibInferenceLTFactSet(IALibInferenceLTFactSet *p)

This is the destructor for a LTFactSet. It destroys the object and its contained LTFacts, but does not have any effect on persistent storage objects. Persistent storage is changed primarily by the put member function.

Parameters:

p - a pointer to the IALibInferenceLTFactSet.

Returns:
No returned values.

delete_IALibInferenceLTFact
   C++ :  void delete_IALibInferenceLTFact(IALibInferenceLTFact *p)

This is the destructor for a LTFact. It is normally invoked implicitly through the deleteLTFact member function of LTFactSet or by the del() member function of LTFact.

Parameters:

p - a pointer to the IALibInferenceLTFact.

Returns:
No returned values.

delete_IALibLogRecordSet
   C++ :  void delete_IALibLogRecordSet(IALibLogRecordSet *p)

This provides for destructing a LogRecordSet and its contained LogRecords. It destroys the object, but does not have any affect on persistent storage objects. Persistent storage is affected primarily by the put and del member functions.

Parameters:

p - a pointer to the IALibLogRecordSet.

Returns:
No returned values.

delete_IALibLogRecord
   C++ :  void delete_IALibLogRecord(IALibLogRecord *p)

This is the destructor for a LogRecord. You cannot delete a LogRecord that has been added through addRecord to an IALibLogRecordSet except by deleting the IALibLogRecordSet that contains it, or by writing enough records in the log that the log wraps-around over existing log records.

Parameters:

p - a pointer to the IALibInferenceRule.

Returns:
No returned values.

Class IALibInferenceCollector

An IALibInferenceCollector lets you group objects for inferencing. The objects that you can group include IALibInferenceRuleSets and IALibInferenceLTFactSets. In addition you can also nest IALibInferenceCollectors. That is, an IALibInferenceCollector can contain other IALibInferenceCollector objects. This grouping of objects is similar to and can be implemented on many platforms as hierarchical directories. The benefits include scoping of contained object's names, improved performance on searches, and definition of control points for security and concurrency management.

A shortened form of these object names is used in some of the following descriptions, leaving off the "IALibInference" class name prefix.

The objects that a Collector has in its contents are each represented by an IALibInferenceContentsElement. Each IALibInferenceContentsElement (ContentsElement for short) represents an object that is grouped in persistent storage in a particular (parent) Collector. The set of ContentsElements for a Collector are referred to as contents of the Collector.

The contents of a Collector object is maintained implicitly when Library methods are employed that specify that Collector as the parent. For example, if you add a RuleSet to a Collector, a ContentsElement for that new RuleSet is implicitly added to the contents of the containing Collector. Further, multiple threads can share a common Collector and dynamically change its contents.

The ContentsElements of a Collector are ordered by the object name. There can be more than one object with the same name, in which they are further distinguished by a type code. Then, in the case of metadata ContentsElements, multiple instances of metadata are permitted, each with the same name and type. Therefore, this case requires further distinction by a metadata name. ContentsElements for a Collector are not ordered by type or metadata name within object name, although you can attain ordering within a type by specifying a limiting scope for a Collector's internal cursor (IALibInferenceCollectorCursorScope).

Constructors

IALibInferenceCollector

See IALibrary for constructing an IALibInferenceCollector.

IALibInferenceCollector
   C++ :  IALibInferenceCollector(const IALibInferenceCollector &from);

   Java:  IALibInferenceCollector(IALibInferenceCollector from);

This member function is the copy constructor.

Member Functions

extractName
   C++ :   const char* extractName() const

   Java:   String extractName()

This member function extracts the name of the Collector.

Parameters:

None.

Returns:

const char* (in Java, String) - name of the Collector.

setMetadataName
   C++ :   void setMetadataName (const char MetadataName='0')
                                 throw(IAError)
   Java:   void setMetadataName (char MetadataName) throws IAError
                  void setMetadataName () throws IAError

This member function sets the metadata name that is used to get or put metadata that is associated with the current Collector. The default MetadataName is '0' (zero).

Parameters:

MetadataName - This name is limited to 1 character: values 0-9 or A-Z.

Returns:

None.

extractVersion
   C++ :   unsigned int extractVersion() const

   Java:   String extractVersion()

This member function extracts the version of the Collector.

Parameters:

None.

Returns:

const char* (in Java, String) - version of the Collector.

extractMetadataName
   C++ :   char extractMetadataName ()

   Java:   char extractMetadataName()

This member function extracts the metadata name that is associated with the current Collector.

Parameters:

None.

Returns:

char - MetadataName that is extracted.

extractMetadata
   C++ :   const char* extractMetadata () const

   Java:   String extractMetadata ()

This member function extracts the metadata that is associated with the current Collector.

Parameters:

None.

Returns:

const char* (in Java, String) - Metadata that is extracted.

setMetadata
   C++ :   void setMetadata (const char* Metadata)
                                            throw(IAError)

   Java:   void setMetadata(String Metadata) throws IAError

This member function sets the metadata that can be used to put or update metadata in persistent storage via the put member function. Metadata can be any character string values, including new line characters.

Parameters:

Metadata - a string that is to be associated with the Collector

Returns:

None.

size
   C++ :   int size () const

   Java:   int size ()

This member function extracts number of ContentsElements in the contents of the Collector.

Parameters:

None.

Returns:

int - number of ContentsElements currently in the Collector.

extractLibraryPtr
   C++ :   IALibrary* extractLibraryPtr () const

   Java:   IALibrary extractLibrary ()

This member function extracts a pointer(in Java, the object) to the IALibrary object that owns the current Collector.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibrary * - pointer an IALibrary object.

width=60 scale=auto.Java: IALibrary - an IALibrary object.

del
   C++ :   void del () throw(IAError)

   Java:   void del() throws IAError

This member function deletes the persistent storage object that is associated with the Collector. The Collector must not contain any objects other than Collector-level metadata. Collector-level metadata is also deleted. The Collector is implicitly deleted from the parent Collectors contents. The destructor for the Collector object is not implicitly invoked.

You cannot delete the top Collector for the library. Currently, attempting to delete the top Collector will fail (but no return value will indicate this).

Parameters:

None.

Returns:

None.

delMetadata
   C++ :   IABool delMetadata (char MetadataName) throw(IAError)

   Java:   boolean delMetadata (char MetadataName) throws IAError

This member function deletes the named metadata in persistent storage. It also deletes the named metadata from the contents of the current Collector object.

Parameters:

MetadataName - the name of the metadata that is to be deleted.

Returns:

IABool (in Java, boolean) - false if metadata not found; otherwise, true.

setCursorElementScope
   C++ :   void setCursorElementScope (IALibInferenceCollectorCursorScope CursorScope)
                      throw(IAError)

   Java:   void setCursorElementScope (int CursorScope)
                      throws IAError

This member function establishes the scope of subsequent cursor operations. That is, it specifies which ContentsElements the cursor will position on. If the cursorscope is IALibICCS_collectors, for example, nextElement will ignore any non-Collector type ContentsElements. When the cursorscope is IALibICCS_all, all ContentsElements are considered in cursor positioning. The find member function is also sensitive to the setting of cursorscope. If you try to find a type of ContentsElement that is not in the cursorscope, the find will result in false (not found).

When a Collector is instantiated, its internal cursor is initialized to a cursorscope of IALibICCS_all. If you do not change the cursorscope, then you will get the "all" scope as set by the Constructor.

Following are the member functions that are affected by CursorScope:

Parameters:

CursorScope - following are the valid values:

Returns:

None.

find
   C++ :   IABool find (
                    IALibInferenceContentsElement& ContentsElement,
                    const char* EntryName,
                    IALibInferenceContentsElementType EntryType,
                    const char MetadataName = ' ')
                    throw(IAError)

   Java:   boolean find (
                    IALibInferenceContentsElement ContentsElement,
                    String EntryName,
                    char EntryType,
                    char MetadataName)
                    throws IAError

           boolean find (
                    IALibInferenceContentsElement ContentsElement,
                    String EntryName,
                    char EntryType)
                    throws IAError

This member function searches for a ContentsElement in the Collector and positions the internal cursor on that ContentsElement when found. Where IABool is returned, it is false if not found and true if found. The cursor position is undefined when not found results. The search uses the EntryName and IALibInferenceContentsElementType, along with an optional MetadataName, which is only applicable when the IALibInferenceContentsElementType indicates a metadata type. Following are the IALibInferenceContentsElementTypes that you can specify:

If the cursor scope (see setCursorElementScope) is incompatible with the type of search, the result is not found.

Parameters:

ContentsElement - an IALibInferenceContentsElement object that was found by the search.

EntryName - name of the element that is to be used for the search

EntryType - type of the ContentsElement that is to be used for the search

MetadataName - name of the metadata that is to be used for the search. This is optional but necessary when the IALibInferenceContentsElementType indicates that the search is for metadata.

Returns:

IABool (in Java, boolean) - true (found and cursor positioned on the found ContentsElement) or false (not found and cursor is undefined).

find
   C++ :  IALibInferenceContentsElement* find (
                    const char* EntryName,
                    IALibInferenceContentsElementType EntryType,
                    const char MetadataName = ' ')
                    throw(IAError)

   Java:  IALibInferenceContentsElement find (
                    String EntryName,
                    char EntryType,
                    char MetadataName)
                    throws IAError

           IALibInferenceContentsElement find (
                    String EntryName,
                    char EntryType)
                    throws IAError

This member function searches for a ContentsElement in the Collector and positions the internal cursor on that ContentsElement when found. Where IABool is returned, it is false if not found and true if found. The cursor position is undefined when not found results. The search uses the EntryName and IALibInferenceContentsElementType, along with an optional MetadataName, which is only applicable when the IALibInferenceContentsElementType indicates a metadata type. Following are the IALibInferenceContentsElementTypes that you can specify:

If the cursor scope (see setCursorElementScope) is incompatible with the type of search, the result is not found.

Parameters:

EntryName - name of the element that is to be used for the search

EntryType - type of the ContentsElement that is to be used for the search

MetadataName - name of the metadata that is to be used for the search. This is optional but necessary when the IALibInferenceContentsElementType indicates that the search is for metadata.

Returns:

IALibInferenceContentsElement* (in Java, an IALibInferenceContentsElement) - an IALibInferenceContentsElement object that was found by the search.

firstElement
   C++ :   IABool firstElement(
                       IALibInferenceContentsElement& ContentsElement)
                       throw(IAError)

   Java:   boolean firstElement(
                       IALibInferenceContentsElement ContentsElement)
                       throws IAError

This member function positions the cursor on the first ContentsElement of the cursor scope in the sequence of the Collector's contents. If the Collector's contents is empty, the cursor is undefined and the result returned is false. If the Collector is not empty (relative to the current cursor scope) the ContentsElement parameter is updated to the first ContentsElement of the Collector contents and the result returned is set to true.

Parameters:

ContentsElement - an IALibInferenceContentsElement object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid and Collector contents not empty) or false (Collector contents empty relative to the current cursor scope and cursor is undefined).

firstElement
   C++ :  IALibInferenceContentsElement* firstElement()
                       throw(IAError)

   Java:  IALibInferenceContentsElement firstElement()
                       throws IAError

This member function positions the cursor on the first ContentsElement of the cursor scope in the sequence of the Collector's contents. If the Collector's contents is empty, the cursor is undefined and the result returned is false. If the Collector is not empty (relative to the current cursor scope) the ContentsElement parameter is updated to the first ContentsElement of the Collector contents and the result returned is set to true.

Parameters:

None.

Returns:

IALibInferenceContentsElement* (in Java, IALibInferenceContentsElement) - an IALibInferenceContentsElement object that was found by the search.

lastElement
   C++ :   IABool lastElement(
                       IALibInferenceContentsElement& ContentsElement)
                       throw(IAError)

   Java:   boolean lastElement(
                       IALibInferenceContentsElement ContentsElement)
                       throws IAError

This member function positions the cursor on the last ContentsElement of the cursor scope in the sequence of the Collector's contents. If the Collector's contents is empty, the cursor is undefined and the result returned is false. If the Collector is not empty (relative to the current cursor scope) the ContentsElement parameter is updated to the first ContentsElement of the Collector contents and the result returned is set to true.

Parameters:

ContentsElement - an IALibInferenceContentsElement object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid and Collector contents not empty) or false (Collector contents empty relative to the current cursor scope and cursor is undefined).

lastElement
   C++ :  IALibInferenceContentsElement* lastElement()
                       throw(IAError)

   Java:  IALibInferenceContentsElement lastElement()
                       throws IAError

This member function positions the cursor on the last ContentsElement of the cursor scope in the sequence of the Collector's contents. If the Collector's contents is empty, the cursor is undefined and the result returned is false. If the Collector is not empty (relative to the current cursor scope) the ContentsElement parameter is updated to the first ContentsElement of the Collector contents and the result returned is set to true.

Parameters:

None.

Returns:

IALibInferenceContentsElement* (in Java, IALibInferenceContentsElement) - an IALibInferenceContentsElement object that was found by the search.

nextElement
   C++ :   IABool nextElement(
                       IALibInferenceContentsElement& ContentsElement)
                       throw(IAError)

   Java:   boolean nextElement(
                       IALibInferenceContentsElement ContentsElement)
                       throws IAError

This member function positions the cursor on the next ContentsElement of the cursor scope in the sequence of the Collector's contents. If the Collector's contents is empty, the cursor is undefined and the result returned is false. If the Collector is not empty (relative to the current cursor scope) the ContentsElement parameter is updated to the first ContentsElement of the Collector contents and the result returned is set to true.

Parameters:

ContentsElement - an IALibInferenceContentsElement object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid and Collector contents not empty) or false (Collector contents empty relative to the current cursor scope and cursor is undefined).

nextElement
   C++ :  IALibInferenceContentsElement* nextElement()
                       throw(IAError)

   Java:  IALibInferenceContentsElement nextElement()
                       throws IAError

This member function positions the cursor on the next ContentsElement of the cursor scope in the sequence of the Collector's contents. If the Collector's contents is empty, the cursor is undefined and the result returned is false. If the Collector is not empty (relative to the current cursor scope) the ContentsElement parameter is updated to the first ContentsElement of the Collector contents and the result returned is set to true.

Parameters:

None.

Returns:

IALibInferenceContentsElement* (in Java, IALibInferenceContentsElement) - an IALibInferenceContentsElement object that was found by the search.

previousElement
   C++ :   IABool previousElement(
                       IALibInferenceContentsElement& ContentsElement)
                       throw(IAError)

   Java:   boolean previousElement(
                       IALibInferenceContentsElement ContentsElement)
                       throws IAError

This member function positions the cursor on the previous ContentsElement of the cursor scope in the sequence of the Collector's contents. If the Collector's contents is empty, the cursor is undefined and the result returned is false. If the Collector is not empty (relative to the current cursor scope) the ContentsElement parameter is updated to the first ContentsElement of the Collector contents and the result returned is set to true.

Parameters:

ContentsElement - an IALibInferenceContentsElement object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid and Collector contents not empty) or false (Collector contents empty relative to the current cursor scope and cursor is undefined).

previousElement
   C++ :  IALibInferenceContentsElement* previousElement()
                       throw(IAError)

   Java:  IALibInferenceContentsElement previousElement()
                       throws IAError

This member function positions the cursor on the previous ContentsElement of the cursor scope in the sequence of the Collector's contents. If the Collector's contents is empty, the cursor is undefined and the result returned is false. If the Collector is not empty (relative to the current cursor scope) the ContentsElement parameter is updated to the first ContentsElement of the Collector contents and the result returned is set to true.

Parameters:

None.

Returns:

IALibInferenceContentsElement* (in Java, IALibInferenceContentsElement) - an IALibInferenceContentsElement object that was found by the search.

get
   C++ :   void get () throw(IAError)

   Java:   void get () throws IAError

This member function retrieves persistent storage objects to fill the contents of the Collector with the inferencing material. At the completion of this function you can do find or use the cursor functions of a Collector. If a metadata name is has been set in the Collector, metadata is also retrieved and filled in the Collector.

Parameters:

None.

Returns:

No returned values.

getWithoutMetadata
   C++ :   void getWithoutMetadata () throw(IAError)

   Java:   void getWithoutMetadata () throws IAError

This member function retrieves persistent storage objects to fill the contents of the Collector with the inferencing material. At the completion of this function you can do find or use the cursor functions of a Collector. Metadata is not retrieved, even if a metadata name is set in the Collector.

Parameters:

None.

Returns:

No returned values.

put
   C++ :   int put () throw(IAError)

   Java:   int put () throws IAError

This member function creates a Collector if one does not already exist and adds the new Collector to the contents of the parent Collector. If the Collector already exists, a new one is not created. If a metadata name is set in the Collector, the metadata is written to persistent storage, either creating a new instance of metadata or replacing an existing instance of metadata.

For the top Collector, a put only stores metadata (if any).

Parameters:

None.

Returns:

int - always returns 0

putWithoutMetadata
   C++ :   int putWithoutMetadata () throw(IAError)

   Java:   int putWithoutMetadata () throws IAError

This member function creates a Collector if one does not already exist and adds the new Collector to the contents of the parent Collector. If the Collector already exists, a new one is not created. Metadata is not stored by this function, even if a metadata name is set in the Collector.

Parameters:

None.

Returns:

int - always returns 0

~IALibInferenceCollector

(C++ only) You must use the IALibrary delete_IALibInferenceCollector() method to destruct a Collector.

Class IALibInferenceContentsElement

An IALibInferenceContentsElement represents a single element of the contents of an IALibInferenceCollector (Collector for short). Each IALibInferenceContentsElement (ContentsElement for short) represents an object that is grouped in persistent storage in a particular (parent) Collector. The set of ContentsElements for a Collector are referred to as contents of the Collector.

The ContentsElements of a Collector are ordered by the object name. There can be more than one object with the same name, in which they are further distinguished by a type code. Then, in the case of metadata ContentsElements, multiple instances of metadata are permitted, each with the same name and type. Therefore, this case requires further distinction by a metadata name. ContentsElements for a Collector are not ordered by type or metadata name within object name, although you can attain limited ordering within a type by specifying a limiting scope for a Collector's internal cursor (IALibInferenceCollectorCursorScope). Refer to IALibInferenceCollector for more information on the manipulation of ContentsElements.

Constructors

IALibInferenceContentsElement

See IALibrary for constructing ContentsElements.

IALibLogRecord
   C++ :  IALibInferenceContentsElement(const IALibInferenceContentsElement &from);

   Java:  IALibInferenceContentsElement(IALibInferenceContentsElement from);

This member function is the copy constructor.

Member Functions

extractElementName
   C++ :   const char* extractElementName() const

   Java:   String extractElementName()

This member function extracts the name of the object represented by the ContentsElement.

Parameters:

None.

Returns:

const char* (in Java, String) - name of the object represented by the ContentsElement.

extractType ()
   C++ :   IALibInferenceContentsElementType extractType () const

   Java:   char extractType ()

This member function extracts the object type that is associated with the current ContentsElement.

Parameters:

None.

Returns:

IALibInferenceContentsElementType (in Java, char) ObjectType that is extracted. See types listed with the constructor in Chapter 4. "Library Reference".

extractMetadataName
   C++ :   char extractMetadataName () const

   Java:   char extractMetadataName()

This member function extracts the metadata name that is associated with the current ContentsElement.

Parameters:

None.

Returns:

char - Metadata that is extracted.

~IALibInferenceContentsElement

(C++ only) You must use the IALibrary delete_IALibInferenceContentsElement() method to destruct a ContentsElement.

Class IALibInferenceRuleSet

An IALibInferenceRuleSet holds a set of rules and some metadata that can describe those rules. It represents a persistent storage object that stores the set of rules and the optional metadata that describe the set of rules. The actual retrieval of the set of rules from persistent storage and optional metadata is accomplished through a get member function. Conversely, sets of rules are stored in persistent storage through a put member function. The object also supports finding rules by name and operating an internal cursor to examine, replace, and delete rules in the set.

A shortened form of these object names is used in some of the following descriptions (omitting the IALibInference prefix).

Constructors

IALibInferenceRuleSet

See IALibrary for constructing an IALibInferenceRuleSet.

Member Functions

extractName
   C++ :   const char* extractName() const

   Java:   String extractName()

This member function extracts the name of the RuleSet.

Parameters:

None.

Returns:

const char* (in Java, a String) - name of the RuleSet.

extractID
   C++ :   const char* extractID() const

   Java:   String extractID()

This member function extracts the ID of the RuleSet.

Parameters:

None.

Returns:

const char* (in Java, a String) - ID of the RuleSet.

extractVersion
   C++ :   unsigned int extractVersion() const

   Java:   String extractVersion()

This member function extracts the version of the RuleSet.

Parameters:

None.

Returns:

const char* (in Java, String) - version of the RuleSet.

setMetadataName
   C++ :   void setMetadataName (const char MetadataName='0')
                                 throw(IAError)
   Java:   void setMetadataName (char MetadataName) throws IAError

           void setMetadataName () throws IAError

This member function sets the metadata name that is used to get or put metadata that is associated with the current Ruleset. The default MetadataName is for this method is '0' (zero). The default (for the constructor is blank (no name).

Parameters:

MetadataName - This name is limited to 1 character: 0-9 or A-Z

Returns:

None.

extractMetadataName
   C++ :   char extractMetadataName ()

   Java:   char extractMetadataName()

This member function extracts the metadata name that is associated with the current RuleSet.

Parameters:

None.

Returns:

char - Metadata name that is extracted.

setMetadata
   C++ :   void setMetadata (const char* Metadata)

   Java:   void setMetadata(String Metadata) throws IAError

This member function sets the metadata that can be used to put or update metadata in persistent storage via the put member function.

Parameters:

Metadata - a string that is to be copied into the RuleSet.

Returns:

None.

extractMetadata
   C++ :   const char* extractMetadata () const

   Java:   String extractMetadata ()

This member function extracts the metadata that is associated with the current RuleSet.

Parameters:

None.

Returns:

const char* (in Java, a String) - Metadata that is extracted.

setRulesMetadataName
   C++ :   void setRulesMetadataName (const char RulesMetadataName)
                                    throw(IAError)

   Java:   void setRulesMetadataName (char RulesMetadataName) throws IAError

This member function sets the metadata name that can be used to put or update metadata in persistent storage via the put member function.

Parameters:

RulesMetadataName - Rules-level metadata name that is to be set. Name is a single character 0-9 or A-Z. The default MetadataName is for this method is '0' (zero). The default (for the constructor is blank (no name).

Returns:

None.

extractRulesMetadataName
   C++ :   const char extractRulesMetadataName () const

   Java:   char extractRulesMetadataName ()

This member function extracts the Rules level metadata name that is associated with the current RuleSet.

Parameters:

None.

Returns:

const char (in Java, char) - Rules-level Metadata Name that is extracted.

size
   C++ :   int size () const

   Java:   int size ()

This member function extracts number of Rules in the current RuleSet.

Parameters:

None.

Returns:

int - number of Rules currently in the RuleSet.

activate
   C++ :   void activate ()

   Java:   void activate() throws IAError

This member function sets state of the RuleSet to "active". This state can be used to determine which RuleSets to select for loading.

Parameters:

None.

Returns:

None.

inactivate
   C++ :   void inactivate ()

   Java:   void inactivate() throws IAError

This member function sets state of the RuleSet to "inactive". This state can be used to determine which RuleSets to select for loading.

Parameters:

None.

Returns:

None.

isActive
   C++ :   IABool isActive () const

   Java:   boolean isActive()

This member function determines the RuleSet's current active/inactive state and returns "true" for active and "false" for inactive.

Parameters:

None.

Returns:

IABool (in Java, boolean): True means the RuleSet has an "active" state. False means the Ruleset has an "inactive" state.

del
   C++ :   void del () throw(IAError)

   Java:   void del() throws IAError

This member function deletes the persistent storage object that is associated with the RuleSet. RuleSet level metadata and Rules level metadata are also deleted. The RuleSet is implicitly deleted from the parent Collectors contents. The RuleSet object is not deleted from memory (the destructor is not implicitly invoked).

Parameters:

None.

Returns:

None.

delMetadata
   C++ :   IABool delMetadata (char MetadataName) throw(IAError)

   Java:   boolean delMetadata (char MetadataName) throws IAError

This member function deletes the named RuleSet level metadata in persistent storage. It also deletes the named Ruleset level metadata from the contents of the current Collector object.

Parameters:

MetadataName - the name of the metadata that is to be deleted.

Returns:

IABool (in Java, boolean) - false if not found; otherwise true

delRulesMetadata
   C++ :   void delRulesMetadata (char MetadataName) throw(IAError)

   Java:   void delRulesMetadata (char MetadataName) throws IAError

This member function deletes the named Rules-level metadata in persistent storage. It also deletes the named Rules level metadata from the contents of the current Collector object.

Parameters:

MetadataName - the name of the metadata that is to be deleted.

Returns:

None.

deleteRule
   C++ :   IABool deleteRule () throw(IAError)

   Java:   boolean deleteRule () throws IAError

This member function logically deletes the Rule from the containing RuleSet. Rule-level metadata is also logically deleted. For a Rule that is in a RuleSet, you should not invoke the Rule Destructor, because the del member function is a logical delete (marked for deletion). The rule is retained until the RuleSet is put to persistent storage, whereupon the Rule delete becomes an actual delete.

The cursor is positioned on the next Rule (one following the deleted Rule). If there is no next Rule, the cursor is positioned on the previous Rule. If there are no remaining Rules, the cursor is undefined.

Refer to undelete for a member function to reverse a delete.

Parameters:

None.

Returns:

IABool (in Java, boolean) - true if cursor is positioned; false if cursor is undefined.

addRule
   C++ :   void addRule (const IALibInferenceRule& NewRule) throw(IAError)

   Java:   void addRule (IALibInferenceRule NewRule) throws IAError

This member function adds a new Rule to the RuleSet. The new Rule is added at the end of the RuleSet's sequence of Rules. If Rule level metadata name is set in the Rule, and if the RuleSet names Rule level metadata, then metadata is also added to the RuleSet. The addition does not affect persistent storage until the RuleSet is put.

The cursor is positioned on the new Rule by this member function.

Parameters:

NewRule - Rule object for rule to be added to the RuleSet.

Returns:

None.

addRuleAsNext
   C++ :   void addRuleAsNext (const IALibInferenceRule& NewRule)
                              throw(IAError)
   Java:   void addRuleAsNext (IALibInferenceRule NewRule)
                              throws IAError

This member function adds a new Rule to the RuleSet. The new Rule is added at the next position from the current cursor, if the cursor is defined. If the RuleSet names Rule-level metadata, then metadata is also added to the RuleSet. The addition does not affect persistent storage until the RuleSet is put.

The cursor is positioned on the new Rule by this member function.

Parameters:

NewRule - Rule object for rule to be added to the RuleSet.

Returns:

None.

addRuleAsPrevious
   C++ :   void addRuleAsPrevious (const IALibInferenceRule& NewRule)
                                  throw(IAError)

   Java:   void addRuleAsPrevious (IALibInferenceRule NewRule)
                                  throws IAError;

This member function adds a new Rule to the RuleSet. The new Rule is added at the previous position from the current cursor, if the cursor is defined. If the RuleSet names Rule-level metadata, then metadata is also added to the RuleSet. The addition does not affect persistent storage until the RuleSet is put.

The cursor is positioned on the new Rule by this member function.

Parameters:

NewRule - Rule object for rule to be added to the RuleSet.

Returns:

None.

updateRule
   C++ :   int updateRule (IALibInferenceRule& NewRule)
                          throw(IAError)

   Java:   int updateRule (IALibInferenceRule NewRule)
                          throws IAError

This member function updates a Rule in the RuleSet where the cursor is currently positioned. If Rule level metadata name is set in the Rule, and if the RuleSet names Rule level metadata, then metadata is also updated in the RuleSet. The update does not affect persistent storage until the RuleSet is put.

The cursor is not modified by this member function.

Parameters:

NewRule - Rule object of rule to be copied to the RuleSet at the current cursor position.

Returns:

int - a return value of zero indicates the update was successful; a non-zero return value indicates the update was not successful (e.g., the RuleSet is empty).

find
   C++ :   IABool find (const char* RuleName, IALibInferenceRule& Rule)
                       throw(IAError)

   Java:   boolean find (String RuleName, IALibInferenceRule Rule)
                       throws IAError

This member function searches for a Rule in the RuleSet by name and positions the internal cursor on that Rule object when found. IABool(in Java, boolean) returns false if not found and true if found. The cursor position is undefined when not found results. If found, the rule object is updated with the found rule. Logically deleted rules are not found.

Parameters:

RuleName - name of the Rule that is to be used for the search

Rule - a Rule object to be updated with the rule that was found by the search.

Returns:

IABool (in Java, boolean) - true (found and cursor positioned on the found Rule) or false (not found and cursor is undefined).

find
   C++ :   IALibInferenceRule* find (const char* RuleName)
                                     throw(IAError)

   Java:   IALibInferenceRule find (String RuleName)
                                     throws IAError

This member function searches for a Rule in the RuleSet by name and positions the internal cursor on that Rule object when found. The cursor positioning is undefined when not found results. If found, the rule object pointer (in java, the object) is returned. Logically deleted rules are not found.

Parameters:

RuleName - name of the Rule that is to be used for the search

Returns:

width=60 scale=auto.C++ : IALibInferenceRule * - a pointer to the IALibInferenceRule object that was found or null pointer (not found and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceRule - the IALibInferenceRule object that was found.

firstRule
   C++ :   IABool firstRule (IALibInferenceRule& Rule) throw(IAError)

   Java:   boolean firstRule (IALibInferenceRule Rule) throws IAError

This member function positions the cursor on the first Rule in the sequence of the RuleSet's Rules. If the RuleSet contains no Rules, the cursor is undefined and the result returned is false. If the Ruleset contains at least one Rule, the rule object is updated to the first Rule of the RuleSet and the result returned is set to true. Positioning does not occur on logically deleted Rules.

Parameters:

Rule - a Rule object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid and RuleSet contains at least one Rule) or false (RuleSet contains no Rules and cursor is undefined).

firstRule
    C++ :  IALibInferenceRule* firstRule () throw(IAError)

    Java:  IALibInferenceRule firstRule() throws IAError

This member function positions the cursor on the first Rule in the sequence of the RuleSet's Rules. If the RuleSet contains no Rules, the cursor is undefined and the NULL pointer (in C++) is returned. If the Ruleset contains at least one Rule, a pointer to the first Rule (in Java, the object itself) of the RuleSet is returned. Positioning does not occur on logically deleted Rules.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceRule * - pointer to the first Rule in the RuleSet (positioning is valid and RuleSet contains at least one Rule) or NULL (RuleSet contains no Rules and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceRule - the first Rule in the RuleSet (positioning is valid and RuleSet contains at least one Rule).

lastRule
   C++ :   IABool lastRule (IALibInferenceRule& Rule) throw(IAError)

   Java:   boolean lastRule (IALibInferenceRule Rule) throws IAError

This member function positions the cursor on the last Rule in the sequence of the RuleSet's Rules. If the RuleSet contains no Rules, the cursor is undefined and the result returned is false. If the Ruleset contains at least one Rule, the rule object is updated to the last Rule of the RuleSet and the result returned is set to true. Positioning does not occur on logically deleted Rules.

Parameters:

Rule - a Rule object where the cursor is positioned.

Returns:

IABool (in Java, boolean)- true (positioning is valid and RuleSet contains at least one Rule) or false (RuleSet contains no Rules and cursor is undefined).

lastRule
    C++ :  IALibInferenceRule* lastRule () throw(IAError)

    Java:  IALibInferenceRule lastRule() throws IAError

This member function positions the cursor on the last Rule in the sequence of the RuleSet's Rules. If the RuleSet contains no Rules, the cursor is undefined and the NULL pointer (in C++) is returned. If the Ruleset contains at least one Rule, a pointer (in Java, the object itself) to the last Rule of the RuleSet is returned. Positioning does not occur on logically deleted Rules.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceRule * - pointer to the last Rule in the RuleSet (positioning is valid and RuleSet contains at least one Rule) or NULL (RuleSet contains no Rules and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceRule - the last Rule in the RuleSet (positioning is valid and RuleSet contains at least one Rule).

nextRule
   C++ :   IABool nextRule (IALibInferenceRule& Rule) throw(IAError)

   Java:   boolean nextRule (IALibInferenceRule Rule) throws IAError

This member function positions the cursor on the next Rule in the sequence of the RuleSet's Rules. If the cursor was already positioned on the last Rule, the cursor is undefined and the result returned is false. Otherwise, the Rule parameter is updated to the next Rule of the RuleSet and the result returned is set to true. Positioning does not occur on logically deleted Rules.

Parameters:

Rule - a Rule object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid) or false (RuleSet contains no more Rules and cursor is undefined).

nextRule
    C++ :  IALibInferenceRule* nextRule () throw(IAError)

    Java:  IALibInferenceRule nextRule() throws IAError

This member function positions the cursor on the next Rule in the sequence of the RuleSet's Rules. If the cursor was already positioned on the last Rule, the cursor is undefined and the NULL pointer (C++) is returned. Otherwise, a pointer (in Java, the object itself) to the next Rule of the RuleSet is returned. Positioning does not occur on logically deleted Rules.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceRule * - pointer to the next Rule in the RuleSet (positioning is valid) or NULL (RuleSet contains no Rules and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceRule - the next Rule in the RuleSet (positioning is valid).

previousRule
   C++ :   IABool previousRule (IALibInferenceRule& Rule) throw(IAError)

   Java:   boolean previousRule (IALibInferenceRule Rule) throws IAError

This member function positions the cursor on the previous Rule in the sequence of the RuleSet's Rules. If the cursor was already positioned on the first Rule, the cursor is undefined and the result returned is false. Otherwise, the Rule parameter is updated to the previous Rule of the RuleSet and the result returned is set to true. Positioning does not occur on logically deleted Rules.

Parameters:

Rule - a Rule object where the cursor is positioned.

Returns:

IABool (in Java, boolean)- true (positioning is valid) or false (RuleSet contains no more Rules and cursor is undefined).

previousRule
    C++ :  IALibInferenceRule* previousRule () throw(IAError)

    Java:  IALibInferenceRule previousRule() throws IAError

This member function positions the cursor on the previous Rule in the sequence of the RuleSet's Rules. If the cursor was already positioned on the first Rule, the cursor is undefined and the NULL pointer (C++) is returned. Otherwise, a pointer (in Java, the object itself) to the previous Rule of the RuleSet is returned. Positioning does not occur on logically deleted Rules.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceRule * - pointer to the previous Rule in the RuleSet (positioning is valid) or NULL (RuleSet contains no Rules and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceRule - the previous Rule in the RuleSet (positioning is valid).

currentRule
   C++ :   IABool currentRule (IALibInferenceRule& Rule) throw(IAError)

   Java:   boolean currentRule (IALibInferenceRule Rule) throws IAError

This member function does not change the cursor position in the sequence of the RuleSet's Rules. If the cursor is undefined, the result returned is false. Otherwise, the Rule parameter is updated to the current Rule of the RuleSet and the result returned is set to true.

Parameters:

Rule - a Rule object where the cursor is positioned.

Returns:

IABool (in Java, boolean)- true (positioning is valid) or false (RuleSet contains no Rules or cursor is undefined).

currentRule
    C++ :  IALibInferenceRule* currentRule () throw(IAError)

    Java:  IALibInferenceRule currentRule() throws IAError

This member function does not change the cursor position in the sequence of the RuleSet's Rules. If the cursor is undefined, the NULL pointer(C++) is returned. Otherwise, a pointer (in Java, the object itself) to the current Rule of the RuleSet is returned.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceRule * - pointer to the previous Rule in the RuleSet (positioning is valid) or NULL (RuleSet contains no Rules and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceRule - the previous Rule in the RuleSet (positioning is valid).

get
   C++ :   int get () throw(IAError)

   Java:   int get () throws IAError

This member function retrieves persistent storage objects to fill the contents of the Ruleset with the Rule objects. At the completion of this function you can do find or use the cursor functions of the RuleSet. If metadata names have been set in the RuleSet, metadata is also retrieved and filled in the RuleSet.

Parameters:

None.

Returns:

int - 0 indicates success. Non-0 indicates failure.

getWithoutMetadata
   C++ :   int getWithoutMetadata () throw(IAError)

   Java:   int getWithoutMetadata () throws IAError

This member function retrieves persistent storage objects to fill the contents of the RuleSet with Rule objects. At the completion of this function you can do find or use the cursor functions of the Ruleset. Metadata is not retrieved, even if a metadata names are set in the RuleSet.

Parameters:

None.

Returns:

int - 0 indicates success. Non-0 indicates failure.

put
   C++ :   int put () throw(IAError)

   Java:   int put () throws IAError

This member function creates a RuleSet object in persistent storage if one does not already exist and adds the new RuleSet to the contents of the parent Collector. If the RuleSet already exists, a new one is not created, but the existing one is replaced. If metadata names are set in the RuleSet, the metadata is written to persistent storage, either creating a new instance of metadata or replacing an existing instance of metadata. Rules that are logically deleted are not put to persistent storage.

Validation of Rules is done when a put is invoked for the containing RuleSet. However, this validation is minimal for the alpha version of the Agent Building Environment Developer's Toolkit.

Parameters:

None.

Returns:

int - 0 is success; > 0 indicates the position of the Rule in the sequence in which a KIF validation failed. For the failure case, you must correct the KIF syntax and repeat the put.

putWithoutMetadata
   C++ :   int putWithoutMetadata () throw(IAError)

   Java:   int putWithoutMetadata () throws IAError

This member function creates a Ruleset if one does not already exist and adds the new RuleSet to the contents of the parent Collector. If the RuleSet already exists, a new one is not created, but the existing one is replaced. Metadata is not stored by this function, even if a metadata name is set in the Collector.

Parameters:

None.

Returns:

int - 0 is success; > 0 indicates the position of the Rule in the sequence in which a KIF validation failed. For the failure case, you must correct the KIF syntax and repeat the put.

~IALibInferenceRuleSet

(C++ only)You must use the IALibrary delete_IALibInferenceRuleSet() method to destruct a RuleSet.

Class IALibInferenceRule

An IALibInferenceRule (Rule for short) represents a rule that is normally built by a rule editor and then used for inferencing. Rules are grouped into RuleSets, an object that contains them.

Metadata can be associated with each Rule object and can be instantiated with it. Although the set of metadata for Rules is named through the containing RuleSet, when you prepare to store rule-level metadata or when you retrieve it, it becomes a part of the Rule object with which it is associated. Rule-level metadata is stored separate from Rules in persistent storage and all metadata for the Rules in a particular RuleSet are stored together and with the same name. Only when the RuleSet and the contained Rules are instantiated is the metadata split up and made available with its associated Rule objects.

Constructors

IALibInferenceRule

See IALibrary for constructing these objects.

IALibInferenceRule
   C++ :  IALibInferenceRule(const IALibInferenceRule &from);

   Java:  IALibInferenceRule(IALibInferenceRule from);

This member function is the copy constructor.

Member Functions

setName
   C++ :   void setName (const char* RuleName)

   Java:   void setName (String RuleName) throws IAError

This member function sets name of the Rule object.

Parameters:

RuleName - the name of the Rule object.

Returns:

None.

extractName
   C++ :   const char* extractName() const

   Java:   String extractName()

This member function extracts the name of the Rule.

Parameters:

None.

Returns:

const char* (in Java, a String) - name of the Rule.

setID
   C++ :   void setID (const char* RuleID)

   Java:   void setID (String RuleID) throws IAError

This member function sets ID of the Rule object.

Parameters:

RuleID - the ID of the Rule object.

Returns:

None.

extractID
   C++ :   const char* extractID () const

   Java:   String extractID()

This member function extracts the ID of the Rule.

Parameters:

None.

Returns:

const char* (in Java, a String) - ID of the Rule.

setMetadata
   C++ :   void setMetadata (const char* Metadata)

   Java:   void setMetadata(String Metadata) throws IAError

This member function sets the metadata that can be used to put or update metadata in persistent storage via the put member function of the containing RuleSet.

Parameters:

Metadata - a string of metadata associated with the Rule.

Returns:

None.

extractMetadata
   C++ :   const char* extractMetadata () const

   Java:   String extractMetadata()

This member function extracts the metadata that is associated with the current Rule.

Parameters:

None.

Returns:

const char* (in Java, a String) - Metadata that is extracted.

activate
   C++ :   void activate ()

   Java:   void activate() throws IAError

This member function sets the state of the Rule to "active". This state can be used to determine which Rules to select for loading.

Parameters:

None.

Returns:

None.

inactivate
   C++ :   void inactivate ()

   Java:   void inactivate() throws IAError

This member function sets state of the Rule to "inactive". This state can be used to determine which Rules not to select for loading.

Parameters:

None.

Returns:

None.

isActive
   C++ :   IABool isActive ()

   Java:   boolean isActive()

This member function determines the Rule's current active/inactive state and returns "true" for active and "false" for inactive.

Parameters:

None.

Returns:

IABool (in Java, boolean): True means the Rule has an "active" state. False means the Rule has an "inactive" state.

isDeleted
   C++ :   IABool isDeleted ()

   Java:   boolean isDeleted()

This member function determines if the Rule is currently logically deleted and returns "true" for deleted and "false" for not deleted.

Note: Since you can only position on a non-deleted Rule in a RuleSet, this member function will always return false when the Rule is contained in a RuleSet.

Parameters:

None.

Returns:

IABool (in Java, boolean): False means the Rule has been logically deleted. True means the Rule has not been deleted.

setKif
   C++ :   void setKif (const char* RuleKif)

   Java:   void setKif(String RuleKif) throws IAError

This member function sets the current KIF string in the Rule object.

Parameters:

RuleKif - KIF string for setting in the Rule object.

Returns:

None.

extractKif
   C++ :   const char* extractKif () const

   Java:   String extractKif()

This member function extracts the current KIF string in the Rule object.

Parameters:

None.

Returns:

const char* (in Java, a String)- extracted KIF string form of the Rule.

del
   C++ :   void del ()

   Java:   void del() throws IAError

This member function logically deletes the Rule from the containing RuleSet. Rule-level metadata is also logically deleted. For a Rule that is in a RuleSet, you should not invoke the Rule Destructor, because the del member function is a logical delete (marked for deletion). The rule is retained until the RuleSet is put to persistent storage, whereupon when the Rule delete becomes an actual delete.

This is effectively the same as the deleteRule member function for a RuleSet (refer to that function for a description of the effect on the implicit cursor positioning).

Parameters:

None.

Returns:

None.

undelete
   C++ :   void undelete ()

   Java:   void undelete() throws IAError

This member function undeletes the Rule. This is possible because the normal delete is a logical delete. Rule level metadata is also undeleted.

Note: Since you can only position on a non-deleted Rule in a RuleSet, this member function will effectively do nothing when the Rule is contained in a RuleSet.

Parameters:

None.

Returns:

None.

validate
   C++ :   IABool validate ()

   Java:   boolean validate()

This member validates a Rule. This means that is checks the syntax of the KIF syntax in the Rule. For the Agent Building Environment Developer's Toolkit alpha release, this function only checks that parentheses are properly balanced and the Rule begins with the string "(=>".

Parameters:

None.

Returns:

IABool (in Java, boolean)- false if the validation fails; true if the validation passes.

~IALibInferenceRule

(C++ only) You must use the IALibrary delete_IALibInferenceRule() method to destruct a Rule.

Class IALibInferenceLTFactSet

An IALibInferenceLTFactSet holds a set of LTFacts (long term facts) and some metadata that can describe those LTFacts. It represents a persistent storage object that stores the set of LTFacts and the optional metadata that describe the set of LTFacts. The actual retrieval of the set of LTFacts from persistent storage and optional metadata is accomplished through a get member function. Conversely, sets of LTFacts are stored in persistent storage through a put member function. The object also supports finding LTFacts by name and operating an internal cursor to examine, replace, and delete LTFacts in the set.

A shortened form of these object names is used in some of the following descriptions (omitting the IALibInference prefix).

Constructors

IALibInferenceLTFactSet

See IALibrary for constructing an IALibInferenceLTFactSet.

Member Functions

extractName
   C++ :   const char* extractName() const

   Java:   String extractName()

This member function extracts the name of the LTFactSet.

Parameters:

None.

Returns:

const char* - name of the LTFactSet.

extractID
   C++ :   const char* extractID() const

   Java:   String extractID()

This member function extracts the ID of the LTFactSet.

Parameters:

None.

Returns:

const char* (in Java, a String) - ID of the LTFactSet.

extractVersion
   C++ :   unsigned int extractVersion() const

   Java:   String extractVersion()

This member function extracts the version of the LTFactSet.

Parameters:

None.

Returns:

const char* (in Java, String) - version of the LTFactSet.

setMetadataName
   C++ :   void setMetadataName (const char MetadataName='0')
                                 throw(IAError)
   Java:   void setMetadataName (char MetadataName) throws IAError
           void setMetadataName () throws IAError

This member function sets the metadata name that is used to get or put metadata that is associated with the current LTFactset. The default MetadataName is '0' (zero).

Parameters:

MetadataName - This name is limited to 1 character: 0-9 or A-Z

Returns:

None.

extractMetadataName
   C++ :   char extractMetadataName ()

   Java:   char extractMetadataName()

This member function extracts the metadata name that is associated with the current LTFactSet.

Parameters:

None.

Returns:

char - Metadata name that is extracted.

setMetadata
   C++ :   void setMetadata (const char* Metadata)

   Java:   void setMetadata(String Metadata) throws IAError

This member function sets the metadata that can be used to put or update metadata in persistent storage via the put member function.

Parameters:

Metadata - a string that is to be copied into the LTFactSet.

Returns:

None.

extractMetadata
   C++ :   const char* extractMetadata () const

   Java:   String extractMetadata ()

This member function extracts the metadata that is associated with the current LTFactSet.

Parameters:

None.

Returns:

const char* (in Java, a String) - Metadata that is extracted.

setLTFactsMetadataName
   C++ :   void setLTFactsMetadataName (const char LTFactsMetadataName)
                                    throw(IAError)

   Java:   void setLTFactsMetadataName (char LTFactsMetadataName) throws IAError

This member function sets the metadata name that can be used to put or update metadata in persistent storage via the put member function. The default MetadataName is for this method is '0' (zero). The default (for the constructor is blank (no name).

Parameters:

LTFactsMetadataName - LTFacts-level metadata name that is to be set. Name is a single character 0-9 or A-Z.

Returns:

None.

extractLTFactsMetadataName
   C++ :   const char extractLTFactsMetadataName () const

   Java:   char extractLTFactsMetadataName ()

This member function extracts the LTFacts level metadata name that is associated with the current LTFactSet.

Parameters:

None.

Returns:

const char (in Java, char) - LTFacts-level Metadata Name that is extracted.

size
   C++ :   int size () const

   Java:   int size ()

This member function extracts number of LTFacts in the current LTFactSet.

Parameters:

None.

Returns:

int - number of LTFacts currently in the LTFactSet.

activate
   C++ :   void activate ()

   Java:   void activate() throws IAError

This member function sets state of the LTFactSet to "active". This state can be used to determine which LTFactSets to select for loading.

Parameters:

None.

Returns:

None.

inactivate
   C++ :   void inactivate ()

   Java:   void inactivate() throws IAError

This member function sets state of the LTFactSet to "inactive". This state can be used to determine which LTFactSets to select for loading.

Parameters:

None.

Returns:

None.

isActive
   C++ :   IABool isActive () const

   Java:   boolean isActive()

This member function determines the LTFactSet's current active/inactive state and returns "true" for active and "false" for inactive.

Parameters:

None.

Returns:

IABool (in Java, boolean): True means the LTFactSet has an "active" state. False means the LTFactset has an "inactive" state.

del
   C++ :   void del () throw(IAError)

   Java:   void del() throws IAError

This member function deletes the persistent storage object that is associated with the LTFactSet. LTFactSet level metadata and LTFacts level metadata are also deleted. The LTFactSet is implicitly deleted from the parent Collector's contents. The LTFactSet object is not deleted from memory (the destructor is not implicitly invoked).

Parameters:

None.

Returns:

None.

delMetadata
   C++ :   IABool delMetadata (char MetadataName) throw(IAError)

   Java:   boolean delMetadata (char MetadataName) throws IAError

This member function deletes the named LTFactSet level metadata in persistent storage. It also deletes the named LTFactset level metadata from the contents of the current Collector object.

Parameters:

MetadataName - the name of the metadata that is to be deleted.

Returns:

IABool (in Java, boolean) - false if not found; otherwise true

delLTFactsMetadata
   C++ :   void delLTFactsMetadata (char MetadataName) throw(IAError)

   Java:   void delLTFactsMetadata (char MetadataName) throws IAError

This member function deletes the named LTFacts-level metadata in persistent storage. It also deletes the named LTFacts level metadata from the contents of the current Collector object.

Parameters:

MetadataName - the name of the metadata that is to be deleted.

Returns:

None.

deleteLTFact
   C++ :   IABool deleteLTFact () throw(IAError)

   Java:   boolean deleteLTFact() throws IAError

This member function logically deletes the LTFact from the containing LTFactSet. LTFact-level metadata is also logically deleted. For a LTFact that is in a LTFactSet, you should not invoke the LTFact Destructor, because the del member function is a logical delete (marked for deletion). The LTFact is retained until the LTFactSet is put to persistent storage, whereupon the LTFact delete becomes an actual delete.

The cursor is positioned on the next LTFact (one following the deleted LTFact). If there is no next LTFact, the cursor is positioned on the previous LTFact. If there are no remaining LTFacts, the cursor is undefined.

Refer to undelete for a member function to reverse a delete.

Parameters:

None.

Returns:

IABool (in Java, boolean) - true if cursor is positioned; false if cursor is undefined.

addLTFact
   C++ :   void addLTFact (const IALibInferenceLTFact& NewLTFact) throw(IAError)

   Java:   void addLTFact (IALibInferenceLTFact NewLTFact) throws IAError

This member function adds a new IALibInferenceLTFact to the IALibInferenceLTFactSet. The new LTFact is added at the end of the LTFactSet's sequence of LTFacts. If LTFact level metadata name is set in the LTFact, and if the LTFactSet names LTFact level metadata, then metadata is also added to the LTFactSet. The addition does not affect persistent storage until the LTFactSet is put.

The cursor is positioned on the new LTFact by this member function.

Parameters:

NewLTFact - LTFact object to be added to the LTFactSet.

Returns:

None.

addLTFactAsNext
   C++ :   void addLTFactAsNext (const IALibInferenceLTFact& NewLTFact)
                              throw(IAError)
   Java:   void addLTFactAsNext (IALibInferenceLTFact NewLTFact)
                              throws IAError

This member function adds a new IAInferenceLTFact to the IALibInferenceLTFactSet. The new LTFact is added at the next position from the current cursor, if the cursor is defined. If the LTFactSet names LTFact-level metadata, then metadata is also added to the LTFactSet. The addition does not affect persistent storage until the LTFactSet is put.

The cursor is positioned on the new LTFact by this member function.

Parameters:

NewLTFact - LTFact object to be added to the LTFactSet.

Returns:

None.

addLTFactAsPrevious
   C++ :   void addLTFactAsPrevious (const IALibInferenceLTFact& NewLTFact)
                                  throw(IAError)

   Java:   void addLTFactAsPrevious (IALibInferenceLTFact NewLTFact)
                                  throws IAError;

This member function adds a new IALibInferenceLTFact to the IALibInferenceLTFactSet. The new LTFact is added at the previous position from the current cursor, if the cursor is defined. If the LTFactSet names LTFact-level metadata, then metadata is also added to the LTFactSet. The addition does not affect persistent storage until the LTFactSet is put.

The cursor is positioned on the new LTFact by this member function.

Parameters:

NewLTFact - LTFact object to be added to the LTFactSet.

Returns:

None.

updateLTFact
   C++ :   int updateLTFact (IALibInferenceLTFact& NewLTFact)
                          throw(IAError)

   Java:   int updateLTFact (IALibInferenceLTFact NewLTFact)
                          throws IAError

This member function updates a IALibInferenceLTFact in the IALibInferenceLTFactSet where the cursor is currently positioned. If LTFact level metadata name is set in the LTFact, and if the LTFactSet names LTFact level metadata, then metadata is also updated in the LTFactSet. The update does not affect persistent storage until the LTFactSet is put.

The cursor is not modified by this member function.

Parameters:

NewLTFact - LTFact object reference of fact to be copied to the LTFactSet at the current cursor position.

Returns:

int - a return value of zero indicates the update was successful; a non-zero return value indicates the update was not successful (e.g., the LTFactSet is empty).

find
   C++ :   IABool find (const char * LTFactName, IALibInferenceLTFact& LTFact)
                                       throw(IAError)

   Java:   boolean find(String LTFactName, IALibInferenceLTFact LTFact)
                                       throws IAError

This member function searches for a LTFact in the LTFactSet by name and positions the internal cursor on that LTFact object when found. False is returned if not found and true if found. The cursor position is undefined when not found results. If found, the LTFact parameter is updated. Logically deleted LTFacts are not found.

Parameters:

LTFactName - name of the LTFact that is to be used for the search

LTFact - a reference to a LTFact object that was found by the search.

Returns:

IABool (in Java, boolean) - true (found and cursor positioned on the found LTFact) or false (not found and cursor is undefined).

find
   C++ :   IALibInferenceLTFact* find (const char* LTFactName)
                                     throw(IAError)

   Java:   IALibInferenceLTFact find (String LTFactName)
                                     throws IAError

This member function searches for a LTFact in the LTFactSet by name and positions the internal cursor on that LTFact object when found. The cursor positioning is undefined when not found results. If found, the LTFact object pointer (in Java, the object itself) is returned. If not found, a null pointer (C++) is returned. Logically deleted LTFacts are not found.

Parameters:

LTFactName - name of the LTFact that is to be used for the search

Returns:

width=60 scale=auto.C++ : IALibInferenceLTFact * - a pointer to the IALibInferenceLTFact object that was found or null pointer (not found and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceLTFact - the IALibInferenceLTFact object that was found.

firstLTFact
   C++ :   IABool firstLTFact (IALibInferenceLTFact& LTFact) throw(IAError)

   Java:   boolean firstLTFact (IALibInferenceLTFact LTFact) throws IAError

This member function positions the cursor on the first LTFact in the sequence of the LTFactSet's LTFacts. If the LTFactSet contains no LTFacts, the cursor is undefined and the result returned is false. If the LTFactset contains at least one LTFact, the LTFact parameter is updated to the first LTFact of the LTFactSet and the result returned is set to true. Positioning does not occur on logically deleted LTFacts.

Parameters:

LTFact - a LTFact object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid and LTFactSet contains at least one LTFact) or false (LTFactSet contains no LTFacts and cursor is undefined).

firstLTFact
    C++ :  IALibInferenceLTFact* firstLTFact () throw(IAError)

    Java:  IALibInferenceLTFact firstLTFact() throws IAError

This member function positions the cursor on the first LTFact in the sequence of the LTFactSet's LTFacts. If the LTFactSet contains no LTFacts, the cursor is undefined and the NULL pointer (C++) is returned. If the LTFactset contains at least one LTFact, a pointer (in Java, the object itself) to the first LTFact of the LTFactSet is returned. Positioning does not occur on logically deleted LTFacts.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceLTFact * - pointer to the first LTFact in the LTFactSet (positioning is valid and LTFactSet contains at least one LTFact) or NULL (LTFactSet contains no LTFacts and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceLTFact - the first LTFact in the LTFactSet (positioning is valid and LTFactSet contains at least one LTFact).

lastLTFact
   C++ :   IABool lastLTFact (IALibInferenceLTFact& LTFact) throw(IAError)

   Java:   boolean lastLTFact (IALibInferenceLTFact LTFact) throws IAError

This member function positions the cursor on the last LTFact in the sequence of the LTFactSet's LTFacts. If the LTFactSet contains no LTFacts, the cursor is undefined and the result returned is false. If the LTFactset contains at least one LTFact, the LTFact parameter is updated to the last LTFact of the LTFactSet and the result returned is set to true. Positioning does not occur on logically deleted LTFacts.

Parameters:

LTFact - a LTFact object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid. LTFactSet contains at least one LTFact) or false (LTFactSet contains no LTFacts and cursor is undefined).

lastLTFact
    C++ :  IALibInferenceLTFact* lastLTFact () throw(IAError)

    Java:  IALibInferenceLTFact lastLTFact() throws IAError

This member function positions the cursor on the last LTFact in the sequence of the LTFactSet's LTFacts. If the LTFactSet contains no LTFacts, the cursor is undefined and the NULL pointer (C++) is returned. If the LTFactset contains at least one LTFact, a pointer (in Java, the object itself) to the last LTFact of the LTFactSet is returned. Positioning does not occur on logically deleted LTFacts.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceLTFact * - pointer to the last LTFact in the LTFactSet (positioning is valid and LTFactSet contains at least one LTFact) or NULL (LTFactSet contains no LTFacts and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceLTFact - the last LTFact in the LTFactSet (positioning is valid and LTFactSet contains at least one LTFact).

nextLTFact
   C++ :   IABool nextLTFact (IALibInferenceLTFact& LTFact) throw(IAError)

   Java:   boolean nextLTFact (IALibInferenceLTFact LTFact) throws IAError

This member function positions the cursor on the next LTFact in the sequence of the LTFactSet's LTFacts. If the cursor was already positioned on the last LTFact, the cursor is undefined and the result returned is false. Otherwise, the LTFact parameter is updated to the next LTFact of the LTFactSet and the result returned is set to true. Positioning does not occur on logically deleted LTFacts.

Parameters:

LTFact - a LTFact object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid) or false (LTFactSet contains no more LTFacts and cursor is undefined).

nextLTFact
    C++ :  IALibInferenceLTFact* nextLTFact () throw(IAError)

    Java:  IALibInferenceLTFact nextLTFact() throws IAError

This member function positions the cursor on the next LTFact in the sequence of the LTFactSet's LTFacts. If the cursor was already positioned on the last LTFact, the cursor is undefined and the NULL pointer(C++) is returned. Otherwise, a pointer (in Java, the object itself) to the next LTFact of the LTFactSet is returned. Positioning does not occur on logically deleted LTFacts.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceLTFact * - pointer to the next LTFact in the LTFactSet (positioning is valid) or NULL (LTFactSet contains no LTFacts and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceLTFact - the next LTFact in the LTFactSet (positioning is valid).

previousLTFact
   C++ :   IABool previousLTFact (IALibInferenceLTFact& LTFact) throw(IAError)

   Java:   boolean previousLTFact (IALibInferenceLTFact LTFact) throws IAError

This member function positions the cursor on the previous LTFact in the sequence of the LTFactSet's LTFacts. If the cursor was already positioned on the first LTFact, the cursor is undefined and the result returned is false. Otherwise, the LTFact parameter is updated to the previous LTFact of the LTFactSet and the result returned is set to true. Positioning does not occur on logically deleted LTFacts.

Parameters:

LTFact - a LTFact object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid) or false (LTFactSet contains no more LTFacts and cursor is undefined).

previousLTFact
    C++ :  IALibInferenceLTFact* previousLTFact () throw(IAError)

    Java:  IALibInferenceLTFact previousLTFact() throws IAError

This member function positions the cursor on the previous LTFact in the sequence of the LTFactSet's LTFacts. If the cursor was already positioned on the first LTFact, the cursor is undefined and the NULL pointer (C++) is returned. Otherwise, a pointer (in Java, the object itself) to the previous LTFact of the LTFactSet is returned. Positioning does not occur on logically deleted LTFacts.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceLTFact * - pointer to the previous LTFact in the LTFactSet (positioning is valid) or NULL (LTFactSet contains no LTFacts and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceLTFact - the previous LTFact in the LTFactSet (positioning is valid).

currentLTFact
   C++ :   IABool currentLTFact (IALibInferenceLTFact& LTFact) throw(IAError)

   Java:   boolean currentLTFact (IALibInferenceLTFact LTFact) throws IAError

This member function does not change the cursor position in the sequence of the LTFactSet's LTFacts. If the cursor is undefined, the result returned is false. Otherwise, the LTFact parameter is updated to the current LTFact of the LTFactSet and the result returned is set to true.

Parameters:

LTFact - a LTFact object where the cursor is positioned.

Returns:

IABool (in Java, boolean) - true (positioning is valid) or false (LTFactSet contains no LTFacts or cursor is undefined).

currentLTFact
    C++ :  IALibInferenceLTFact* currentLTFact () throw(IAError)

    Java:  IALibInferenceLTFact currentLTFact() throws IAError

This member function does not change the cursor position in the sequence of the LTFactSet's LTFacts. If the cursor is undefined, the NULL pointer (C++) is returned. Otherwise, a pointer (in Java, the object itself) to the current LTFact of the LTFactSet is returned.

Parameters:

None.

Returns:

width=60 scale=auto.C++ : IALibInferenceLTFact * - pointer to the current LTFact in the LTFactSet (positioning is valid) or NULL (LTFactSet contains no LTFacts and cursor is undefined).

width=60 scale=auto.Java: IALibInferenceLTFact - the current LTFact in the LTFactSet (positioning is valid).

get
   C++ :   int get () throw(IAError)

   Java:   int get () throws IAError

This member function retrieves persistent storage objects to fill the contents of the LTFactset with the LTFact objects. At the completion of this function you can do find or use the cursor functions of the LTFactSet. If metadata names have been set in the LTFactSet, metadata is also retrieved and filled in the LTFactSet.

Parameters:

None.

Returns:

int - 0 indicates success. Non-0 indicates failure.

getWithoutMetadata
   C++ :   int getWithoutMetadata () throw(IAError)

   Java:   int getWithoutMetadata () throws IAError

This member function retrieves persistent storage objects to fill the contents of the LTFactSet with LTFact objects. At the completion of this function you can do find or use the cursor functions of the LTFactset. Metadata is not retrieved, even if a metadata names are set in the LTFactSet.

Parameters:

None.

Returns:

int - 0 indicates success. Non-0 indicates failure.

put
   C++ :   int put () throw(IAError)

   Java:   int put () throws IAError

This member function creates a LTFactSet object in persistent storage if one does not already exist and adds the new LTFactSet to the contents of the parent Collector. If the LTFactSet already exists, a new one is not created, but the existing one is replaced. If metadata names are set in the LTFactSet, the metadata is written to persistent storage, either creating a new instance of metadata or replacing an existing instance of metadata. LTFacts that are logically deleted are not put to persistent storage.

Validation of LTFacts is done when a put is invoked for the containing LTFactSet. However, this validation is minimal (only checks that parentheses are balanced) for the alpha version of the Agent Building Environment Developer's Toolkit.

Parameters:

None.

Returns:

int - 0 is success; > 0 indicates the position of the LTFact in the sequence in which a KIF validation failed. For the failure case, you must correct the KIF syntax and repeat the put.

putWithoutMetadata
   C++ :   int putWithoutMetadata () throw(IAError)

   Java:   int putWithoutMetadata () throws IAError

This member function creates a LTFactset if one does not already exist and adds the new LTFactSet to the contents of the parent Collector. If the LTFactSet already exists, a new one is not created, but the existing one is replaced. Metadata is not stored by this function, even if a metadata name is set in the Collector.

Parameters:

None.

Returns:

int - 0 is success; > 0 indicates the position of the LTFact in the sequence in which a KIF validation failed. For the failure case, you must correct the KIF syntax and repeat the put.

~IALibInferenceLTFactSet

(C++ only) You must use the IALibrary delete_IALibInferenceLTFactSet() method to destruct a LTFactSet.

Class IALibInferenceLTFact

An IALibInferenceLTFact (LTFact for short) represents a long term fact that is normally built by a rule editor and then used for inferencing. LTFacts are grouped into LTFactSets, an object that contains them.

Metadata can be associated with each LTFact object and can be instantiated with it. Although the set of metadata for LTFacts is named through the containing LTFactSet, when you prepare to store LTFact-level metadata or when you retrieve it, it becomes a part of the LTFact object with which it is associated. LTFact-level metadata is stored separate from LTFacts in persistent storage and all metadata for the LTFacts in a particular LTFactSet are stored together and with the same name. Only when the LTFactSet and the contained LTFacts are instantiated is the metadata split up and made available with its associated LTFact objects.

Constructors

IALibInferenceLTFact

See IALibrary

IALibInferenceLTFact
   C++ :  IALibInferenceLTFact(const IALibInferenceLTFact &from);

   Java:  IALibInferenceLTFact(IALibInferenceLTFact from);

This member function is the copy constructor.

Member Functions

setName
   C++ :   void setName (const char* RuleName)

   Java:   void setName (String RuleName) throws IAError

This member function sets name of the LTFact object.

Parameters:

LTFactName - the name of the LTFact object.

Returns:

None.

extractName
   C++ :   const char* extractName() const

   Java:   String extractName()

This member function extracts the name of the LTFact.

Parameters:

None.

Returns:

const char* (in Java, String) - name of the LTFact.

setID
   C++ :   void setID (const char* LTFactID)

   Java:   void setID (String LTFactID) throws IAError

This member function sets ID of the LTFact object.

Parameters:

LTFactID - the ID of the LTFact object.

Returns:

None.

extractID
   C++ :   const char* extractID () const

   Java:   String extractID()

This member function extracts the ID of the LTFact.

Parameters:

None.

Returns:

const char* (in Java, String) - ID of the LTFact.

setMetadata
   C++ :   void setMetadata (const char* Metadata)

   Java:   void setMetadata(String Metadata) throws IAError

This member function sets the metadata that can be used to put or update metadata in persistent storage via the put member function of the containing LTFactSet.

Parameters:

Metadata - a string that is to be copied into the LTFact.

Returns:

None.

extractMetadata
   C++ :   const char* extractMetadata () const

   Java:   String extractMetadata()

This member function extracts the metadata that is associated with the current LTFact.

Parameters:

None.

Returns:

const char* (in Java, String) - Metadata that is extracted.

activate
   C++ :   void activate ()

   Java:   void activate() throws IAError

This member function sets the state of the LTFact to "active". This state can be used to determine which LTFacts to select for loading.

Parameters:

None.

Returns:

None.

inactivate
   C++ :   void inactivate ()

   Java:   void inactivate() throws IAError

This member function sets state of the LTFact to "inactive". This state can be used to determine which LTFacts not to select for loading.

Parameters:

None.

Returns:

None.

isActive
   C++ :   IABool isActive ()

   Java:   boolean isActive()

This member function determines the LTFact's current active/inactive state and returns "true" for active and "false" for inactive.

Parameters:

None.

Returns:

IABool (in Java, boolean): True means the LTFact has an "active" state. False means the LTFact has an "inactive" state.

isDeleted
   C++ :   IABool isDeleted ()

   Java:   boolean isDeleted()

This member function determines if the LTFact is currently logically deleted and returns "true" for deleted and "false" for not deleted.

Note: Since you can only position on a non-deleted LTFact in a LTFactSet, this member function will always return false when the LTFact is contained in a LTFactSet.

Parameters:

None.

Returns:

IABool (in Java, boolean): False means the LTFact has been logically deleted. True means the LTFact has not been deleted.

setKif
   C++ :   void setKif (const char* LTFactKif)

   Java:   void setKif(String LTFactKif) throws IAError

This member function sets the current KIF string in the LTFact object.

Parameters:

LTFactKif - KIF string for setting in the LTFact object.

Returns:

None.

extractKif
   C++ :   const char* extractKif () const

   Java:   String extractKif()

This member function extracts the current KIF string in the LTFact object.

Parameters:

None.

Returns:

const char* (in Java, String)- extracted KIF string form of the LTFact.

del
   C++ :   void del ()

   C++ :   void del() throws IAError

This member function logically deletes the LTFact from the containing LTFactSet. LTFact-level metadata is also logically deleted. For a LTFact that is in a LTFactSet, you should not invoke the LTFact Destructor, because the del member function is a logical delete (marked for deletion). The LTFact is retained until the LTFactSet is put to persistent storage, whereupon when the LTFact delete becomes an actual delete.

This is effectively the same as the deleteLTFact member function for a LTFactSet (refer to that function for a description of the effect on the implicit cursor positioning).

Parameters:

None.

Returns:

None.

undelete
   C++ :   void undelete ()

   C++ :   void undelete() throws IAError

This member function undeletes the LTFact. This is possible because the normal delete is a logical delete. LTFact level metadata is also undeleted.

Note: Since you can only position on a non-deleted LTFact in a LTFactSet, this member function will effectively do nothing when the LTFact is contained in a LTFactSet.

Parameters:

None.

Returns:

None.

validate
   C++ :   IABool validate ()

   Java:   boolean validate()

This member validates a LTFact. This means that is checks the syntax of the KIF syntax in the LTFact. For the Agent Building Environment Developer's Toolkit alpha release, this function only checks that parentheses are properly balanced.

Parameters:

None.

Returns:

IABool (in Java, boolean) - false if the validation fails; true if the validation

~IALibInferenceLTFact

(C++ only) You must use the IALibrary delete_IALibInferenceLTFact() method to destruct a LTFact.

Class IALibLogRecordSet

An IALibLogRecordSet holds a fixed number of log records in a wraparound buffer. It represents a persistent storage object that stores a partial collection of log records. The actual retrieval of the set of log records from persistent storage is accomplished through get and getRecord member functions. Conversely, log records are stored in persistent storage through a put member function, or an addRecord member function when the internal memory buffer is full. The object also supports operating an internal cursor to examine log records in the set.

A shortened form of these object names is used in some of the following descriptions (omitting the IALib prefix).

Constructors

IALibLogRecordSet

See IALibrary (new_IALibLogRecordSet) for constructing a IALibLogRecordSet.

Member Functions

setLevel
  C++ :  void setLevel(unsigned int newLevel) throw(IAError)

  Java:  void setLevel(int newLevel) throws IAError

This member function dynamically changes the LogRecordSet level attribute. On log write operations (addRecord), level controls the type of log records that currently can be written. The log record types are set in the IALibLogRecord objects. They have values that are powers of two and are currently defined as follows:

These types are extendible. The library enforces via addRecord() what types of log records are accepted. The level is a binary combination of the acceptable types. For example, if level is 5, type 1 or type 4 log record types would be accepted by addRecord(), and type 2 or type 8 would be rejected. THe next available user defined type is 16. A level of 0 means that no addRecord() rejects any and attempts to use it to write log records.

For log reads, the level represents the highest type that is to be read by getRecord(). For example, if you specify level 7, getRecord() would not show you type 8 records, but on types 4,2, and 1 (if any are found).

Parameters:

newLevel - level

Returns:

None.

extractLevel
   C++ : unsigned int extractLevel() const

   Java: int extractLevel()

This member function extracts the level of the LogRecordSet.

Parameters:

Returns:

unsigned int (in Java, int) - level of the LogRecordSet.

extractCacheSize
  C++ :  unsigned int extractCacheSize() const

  Java:  int extractCacheSize()

This member function extracts the cacheSize of the LogRecordSet.

Parameters:

Returns:

unsigned int (in Java, int) - cacheSize of the LogRecordSet.

extractLogSize
  C++ :  unsigned int extractLogSize() const

  Java:  int extractLogSize()

This member function extracts the logSize of the LogRecordSet.

Parameters:

Returns:

unsigned int (in Java, int) - logSize of the LogRecordSet.

extractCurrentLogSize
  C++ :  unsigned int extractCurrentLogSize() const

  Java:  int extractCurrentLogSize()

This member function extracts the current size of the LogRecordSet.

Parameters:

Returns:

unsigned int (in Java, int) - current size of the LogRecordSet.

extractName
  C++ : char* extractName() const

  Java: String extractName()

This member function extracts the name of the LogRecordSet.

Parameters:

Returns:

char* (in Java, String) - name of the LogRecordSet.

setMetadataName
   C++ : void setMetadataName(char mdName) throw(IAError)

   Java: void setMetadataName(char mdName) throws IAError

This member function sets the metadata name attribute value. It can be used in lieu of the constructor parameter. When set, it indicates that metadata applies to the LogRecordSet and indicates the names the instance of metadata that applies. However, once the parm is set for the current LogRecordSet, it cannot be changed. This is enforced to prevent attempts to change metadata instances dynamically.

Parameters:

mdName - The metadata name that is to be assigned to the LogRecordSet. Values allowed are: a-z (lower case) and 0-9. The default MetadataName is for this method is '0' (zero). The default (for the constructor is blank (no name).

Returns:

Error when input too long or contains invalid characters.

setMetadata
  C++ : void setMetadata(char* metadata) throw(IAError)

  Java: void setMetadata(String metadata) throws IAError

This member function sets the metadata value for the current LogRecord - the one that is at the current cursor position.

Parameters:

metadata - The metadata that is to be set in the current log record. When the input string is shorter than the metadataSize, the input is automatically padded to the right with blanks when storing it. If it is too long, an error results.

Returns:

Error when input too long.

setMetadata
  C++ :  void setMetadata(char* metadata, logKey KeyPosition)
                                         throw(IAError)
  Java:  void setMetadata(String metadata, logKey KeyPosition)
                                         throws IAError

This member function sets the metadata value for an identified LogRecord - the one that located by the KeyPosition identifier that is provided. The KeyPosition is independent of the cursor positioning for LogRecords.

Parameters:

metadata - The metadata that is to be set at the identified KeyPosition. When the input string is shorter than the metadataSize, the input is automatically padded to the right with blanks when storing it. If it is too long, an error results.

KeyPosition - identifier of the log record for which the metadata is to be set. KeyPosition is an identifier, which is in the form of a struct named logKey The logKey is associated with a a previously retrieved log record. When you have a log record you can used the extractKeyPosition() method on it to get its KeyPosition (logKey); then use this KeyPosition (logKey) as the KeyPosition in the setMetadata() LogRecordSet method or use it to re-position for log reads (getRecord()) by specifying it as the KeyPosition for a get() LogRecordSet method. The format of a logKey struct is implementation dependent and should not be interpreted for use by a invoker. The logKey is an struct for holding the identifier needed by the KeyPosition. When a log record is read through the getRecord() method, its KeyPosition can be extracted and used later (even when not still positioned on that log record) to position on that same record (through get()) for subsequent getRecord() member functions.

Returns:

Error when input too long.

extractVersion
   C++ :  unsigned int extractVersion() const

   Java:  int extractVersion()

This member function extracts the version of the LogRecordSet.

Parameters:

None.

Returns:

unsigned int (in Java, int) - current version of the LogRecordSet.

extractMetadataSize
  C++ : unsigned int extractMetadataSize() const

  Java: int extractMetadataSize()

This member function extracts the metadata size for the LogRecordSet.

Parameters:

None.

Returns:

unsigned int (in Java, int) - current size of the metadata for the LogRecordSet.

extractMetadataName
  C++ :  char extractMetadataName() const

  Java:  char extractMetadataName()

This member function extracts the metadata name for the LogRecordSet.

Parameters:

None.

Returns:

char - current name of the metadata for the LogRecordSet.

extractMetadata
  C++ : char*  extractMetadata() const

  Java: String extractMetadata()

This member function extracts the metadata for the LogRecord that is located at the current cursor position.

Parameters:

None.

Returns:

char* (in Java, a String) - metadata for the log record at the current cursor position.

extractMetadata
  C++ : char*  extractMetadata(logKey KeyPosition) const
                                              throw(IAError)

  Java: String extractMetadata(logKey KeyPosition)
                                              throws IAError

This member function extracts the metadata for the LogRecord that is located using the KeyPosition identifier.

Parameters:

KeyPosition - identifier for the LogRecord for which the metadata is to be extracted.

Returns:

char* (in Java, String) - metadata for the log record that is associated with the specified KeyPosition identifier that is provided.

del
  C++ :  void del() throw(IAError)

  Java:  void del() throws IAError

This member function deletes the LogRecordSet in persistent storage. It does not run the destructor for the LogRecordSet object itself (in memory). Optionally you can use the memory object and its attributes to create the log again. The del() is considered a log write for concurrency purposes., which means that it should be used only be used serially by a single write thread at a time and there is no locking to serialize multiple log writers.

Parameters:

Returns:

Nothing.

clear
  C++ :  void clear() throw(IAError)

  Java:  void clear() throws IAError

This member function clears out all log records for the current LogRecordSet in memory and in persistent storage, keeping all the other attributes of the LogRecordSet in memory and saving them in persistent storage. The clear() is considered a log write for concurrency purposes., which means that it should be used only be used serially by a single write thread at a time and there is no locking to serialize multiple log writers.

Parameters:

Returns:

Nothing.

addRecord
  C++ : void addRecord(const IALibLogRecord& newLogRecord)
                                      throw(IAError)

  Java: void addRecord(IALibLogRecord newLogRecord)
                                      throws IAError

This member function adds a new LogRecord to the LogRecordSet. The new LogRecord is added at the end of the LogRecordSet's sequence of log records. This is a memory-only operation as long as the LogRecordSet is not full. When it is filled (according to cacheSize and the number of preceding addRecords), there is an also an implicit write to persistent storage and the internal set of LogRecords is cleared.

The write to persistent storage is under the control of the currentBlockId (internal) and may wrap-around according to the value of logSize. When the write to persistent storage is done, the LogRecordSet is also added to the contents of the parent Collector.

You cannot have had a previous getRecord() for this same object. That is, the input/output mode is established by the first getRecord or addRecord operation. The addRecord() is considered a log write for concurrency purposes., which means that it should be used only be used serially by a single write thread at a time and there is no locking to serialize multiple log writers.

The setting of the level attribute (see setLevel()) controls the types of log records that you can successfully write with this member function.

Parameters:

NewLogRecord - LogRecord object reference (for Java, the object) for log record to be added to the LogRecordSet.

Returns:

None.

getRecord
  C++ :  IALibLogRecord* getRecord() throw(IAError)

  Java:  IALibLogRecord getRecord() throws IAError

This member function gets the next LogRecord from the LogRecordSet. This is a memory operation as long as the LogRecordSet has not been depleted in the logList in the memory object. When depleted, there is an implicit read from persistent storage to get additional LogRecords. An addRecord cannot have been done previously for this same object.

The setting of the level attribute (see setLevel()) controls the types of log records that you can successfully read with this member function.

Parameters:

None.

Returns:

A pointer to a LogRecord (in Java, the object itself) retrieved from the LogRecordSet.

IAError - actual codes will be assigned later:

get
  C++ :  void get(int RelativePosition)
                                 throw(IAError)

  Java:  void get(int RelativePosition)
                                 throws IAError

This member function initializes the LogRecordSet from persistent storage. This initialization includes the persistent attributes of the and, depending on the RelativePosition parameter, may also read in a block (cacheSize) of log records. For writing to an existing log, get is used to obtain the log attributes, position at the end of the existing log, and prime the read buffer accordingly. For log reads, the get allows for reading the log attributes and priming the read buffer. Optionally, get for read can also read named metadata.

Parameters:

RelativePosition - controls whether or not a block of records are read, and what, if any, positioning occurs for the cursor of the resulting logList.

Returns:

Nothing.

get
  C++ : void get(logKey KeyPosition)
                                throw(IAError)

  Java: void get(logKey KeyPosition)
                                throws IAError

This is an alternaive signature for get() that allows for positioning using a KeyPosition - an identifier that is obtained from known log record. KeyPosition (logKey) is to be set from one of the known set of KeyPosition values that are set in existing LogRecords of the associated LogRecordSet. It can be used to position at the end of the set of previously read set of log records, for example, by specifying the KeyPosition of the last viewed log record. In this way the reader of the log would only retireve log records that have been added after after those that were previously viewed.

Regardless of the positioning value, and when the log actually exists, the get causes the attributes to be loaded from persistent storage into the LogRecordSet object. When the file does not exist, an IAError is thrown. currentLogSize, logSize, firstBlockId, LastBlockId, currentFirstBlockSequenceNumber, metadataSize and wrapDone.

If the get() does not fill the logList (position value of 0 or error detected on the positioning), and the log exists, then seuqsequent getRecord() or addRecord() will fail. In other words, get() must be used to prime an existing file, but it can also be used to determine if a file exists. If you try to write (addRecord) to an existing log without priming with a get(), the assumption used by addRecord() is that you are creating a new log; however, it will fail when it detects that a log already exists with the same name. In other words, you cannot use getRecord() or addRecord() for an existing file without starting with a new get(). However, for a new file, you can start with addRecord() without a get(). You can also use get with a position of 0 to check if a log already exists. with the current name.

Parameters:

KeyPosition - controls the record positioning by specifying an identifier of type logKey, that is associated with a previously viewed log record. You can get the logKey of a IALibLogRecord by using its extractlogKey() member function. The format of the logKey is implementation dependent and should not be interpreted for use by a invoker. The logKey is a struct for holding the identifier needed by the KeyPosition. identifier. When a log record is read through the getRecord() method, its KeyPosition can be extracted and used (even when not still positioned on that log record) to position on that same record (through get()) for subsequent getRecord() member functions.

Returns:

Nothing.

put
  C++ : void put() throw(IAError)

  Java: void put() throws IAError

This member function writes the attributes of the LogRecordSet and LogRecords currently in memory to persistent storage. Put should be used whenever terminating the current logging session to ensure that all log records are written to persistent storage, including those in the logList (buffer).

You can continue after a put() by writing more log records (addRecord). The effect of the put is the same as if you had restarted at the end of the log by using a get(RelativePosition = 1), allowing you to continue where you left off. You should be careful of using numerous intermediate puts, because poor performance can result from writing the same log records to persistent storage more than once. Consider an example. If you have a cacheSize of 10; addRecord 5 times, then put (the first 5 records), addRecord 6 more times, then you will have written the first 5 records twice: 1) first when you did the put, the again when the logList filled up (reached 10) and had to be written to persistent storage to make room for the 11th record to go in the logList in memory. The second write (of the 10 records in the logList) writes over the 5 records written by the put(). The net effect is okay because it involved the same 5 records, but it takes extra time to do all of this. If you are concerned with the system creshing before you can write the log to persistent storage, it is better to minimize cacheSize, rather than doing intermediate puts.

Put is especially important for writing out the last log records in the logList when there is an orderly shutdown.

Parameters:

Returns:

Nothing.

putMetadata()
  C++ : void putMetadata() throw(IAError)

  Java: void putMetadata() throws IAError

This member function writes the current metadata from memory object, where it has been set, to persistent storage. putMetadata() does not write log records that are associated with that metadata. It writes all metadata for the LogRecordSet and associates the metadata with the currently established metadata name (see setMetadataName()). This member function is intended to be used by log readers to associate "mark-up" with the log records. There can be multiple named instance of metadata for each LogRecordSet. After a successful putMetadata(), the metadata can be retrieved (implicit) with a subsequent get() to the same LogRecordSet is the associated metadatai name has been set for the LogRecordSet (see setMetadataName).

Parameters:

Returns:

Nothing.

~IALibLogRecordSet()

You must use the IALibrary delete_IALibLogRecordSet() method to destruct a LogRecordSet.

Class IALibLogRecord

An IALibLogRecord (LogRecord for short) represents a log record that is normally built by an adapter or inference engine to record information. The attributes of a LogRecord that will be saved in persistent storage include:

LogRecords are grouped into LogRecordSets, an object that contains them.

Constructors

IALibLogRecord

See IALibrary (new_IALibLogRecord) for constructing a IALibLogRecord.

IALibLogRecord
    C++ : IALibLogRecord(const IALibLogRecord &from)

    Java: IALibLogRecord(IALibLogRecord from)

This member function is the copy constructor.

Member Functions

setType
   C++ :  void setType(unsigned int type)

   Java:  void setType(int type) throws IAError

This member function sets the type of the LogRecord object. Type defines the type of activity represented by the log record. Although these are basically user-defined types, in the sense that the Library does not examine their specific values, some types are suggested:

These types are intended to be binary values such that the level setting of the containing LogRecordSet can be used to specify combinations of types. For example, a level setting of 10 would cause the LogRecordSet to only work with error (2) and detail (8) activity type log records.

Parameters:

type - the type of the LogRecord object.

Returns:

Nothing.

extractType
  C++ : unsigned int extractType() const

  Java: int extractType()

This member function returns the type of the LogRecord. Refer to setType for an explanation of type.

Parameters:

Returns:

unsigned int (int in Java)- type of the LogRecord.

setCategory
  C++ :  void setCategory(int category) throw(IAError)

  Java:  void setCategory(int category) throws IAError

This member function sets the category of the LogRecord object. Category is a user-defined value that can be used in anyway that makes sense for the LogRecordSet.

Parameters:

category - the category of the LogRecord object.

Returns:

Nothing.

extractCategory
  C++ :  int extractCategory() const

  Java:  int extractCategory()

This member function returns the category of the LogRecord. Category is a user-defined value that can be used in anyway that makes sense for the LogRecordSet.

Parameters:

Returns:

int - category of the LogRecord.

setOriginator
  C++ :  void setOriginator(const char* originator)
                                           throw(IAError)

  Java:  void setOriginator(String originator) throws IAError

This member function sets the originator of the LogRecord object. Originator is an identifier of the provider of the LogRecord information (e.g., adapter domain name or engine id).

Parameters:

originator - the originator of the LogRecord object.

Returns:

Nothing.

extractOriginator
  C++ : const char* extractOriginator() const

  Java: String extractOriginator()

This member function returns the originator of the LogRecord. Originator is an identifier of the provider of the LogRecord information (e.g., adapter domain name or engine id).

Parameters:

Returns:

const char* (in Java, a String) - originator of the LogRecord.

extractDate
   C++ : const char* extractDate() const

   Java: String extractDate()

This member function returns the date of the LogRecord. Date is set by the Library implicitly based on the current time when an addRecord() occurs.

Parameters:

Returns:

const char* (in Java, String) - date of the LogRecord in the format YYYY-MM-DD.

The date of a LogRecord is initially set by the LogRecord constructor and then is updated when the LogRecord is added to a LogRecordSet.

extractTime
   C++ : const char* extractTime() const

   Java: String extractTime()

This member function returns the time of the LogRecord. Time is set by the Library implicitly based on the current time when an addRecord() occurs.

Parameters:

Returns:

const char* (in Java, String) - time of the LogRecord in the format HH:MM:SS.

The time of a LogRecord is initially set by the LogRecord constructor and then is updated when the LogRecord is added to a LogRecordSet.

setSourceId
   C++ : void setSourceId(const char* sourceId)
                                         throw(IAError)

   Java: void setSourceId(String sourceId) throws IAError

This member function sets the source id of the LogRecord object. The sourceid is an identifier that can be used to identify the cause of the LogRecord (e.g., event id, error id, rule name, RuleSet name).

Parameters:

sourceId - the source id of the LogRecord object.

Returns:

Nothing.

extractSourceId
   C++ : const char* extractSourceId() const

   Java: String extractSourceId()

This member function returns the source id of the LogRecord. The sourceid is an identifier that can be used to identify the cause of the LogRecord (e.g., event id, error id, rule name, RuleSet name).

Parameters:

Returns:

const char* (in Java, a String) - source id of the LogRecord.

setMessageId
  C++ :  void setMessageId(unsigned long messageId)

  Java:  void setMessageId(int messageId)

This member function sets the source id of the LogRecord object. Messageid is an identifier that can be used to find associated text in a repository (such as a message repository), where, optionally, NLS translation can be applied and parameters substituted in message text from the tokens attribute.

Parameters:

messageId - the message id of the LogRecord object.

Returns:

Nothing.

extractMessageId
  C++ : unsigned long extractMessageId() const

  Java: int extractMessageId()

This member function returns the message id of the LogRecord. Messageid is an identifier that can be used to find associated text in a repository (such as a message repository), where, optionally, NLS translation can be applied and parameters substituted in message text from the tokens attribute.

Parameters:

Returns:

unsigned long (in Java, int) - message id of the LogRecord.

extractKeyPosition
  C++ : logKey extractKeyPosition() const

  Java: logKey extractKeyPosition()

This member function returns the KeyPosition (a struct named logKey) for the LogRecord. KeyPosition is an internally assigned value that can be extracted and used to reference a particular log record in a LogRecordSet. In particular it is used by the setMetadata() and extractMetadata() LogRecordSet member functions.

Parameters:

Returns:

logKey - KeyPosition identifier for the LogRecord.

addToken
  C++ :  void addToken(const char* sourceToken)
                                      throw(IAError)

  Java:  void addToken(String sourceToken)
                                      throws IAError

This member function adds a token to the end of the sequence of tokens in the LogRecord. The internal cursor for this sequence of tokens is set to the first token in the sequence, so that it is always ready for getToken() functions. A suggested use of the token(s) is for parameter substitution in a message file. Another is to simply record a line of text. This formatting decision can be based on type and category. A token should not contain newline (\n) characters.

Parameters:

sourceToken - the token to be added. non-zero indicates the token was not added.

Returns:

Nothing.

getToken
  C++ :   char* getToken() throw(IAError)

  Java:   String getToken() throws IAError

This member function returns the next token from the sequence of tokens in the LogRecord. The internal cursor for this sequence of tokens is updated to point to the next token (after the one returned) or is undefined if the last token has been retrieved.

Parameters:

Returns:

char* (in Java, a String) - the next token in the LogRecord, or the NULL pointer if there is no token to return.

~IALibLogRecord()

You must use the IALibrary delete_IALibLogRecord() method to destruct a LogRecord.


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