Main Page   Compound List   File List   Compound Members   File Members  

soar_ecore_api.h File Reference

The Extended Low Level interface to Soar. More...

#include "soarkernel.h"
#include "soar_ecore_utils.h"
#include "soar_core_api.h"

Go to the source code of this file.

Modifying the Agents Parameters

void soar_ecBuildInfo (void)
 soar_BuildInfo -- Indicates compile time setting which affect the current instantiation of Soar. More...

void soar_ecExcludedBuildInfo (void)
 soar_ecExcludedBuildInfo -- Indicates compile time setting which affect the current instantiation of Soar. More...

void soar_ecSetDefaultWmeDepth (int depth)
 soar_ecSetDefaultWmeDepth -- Set the default wme depth to a new value. More...

int soar_ecOpenLog (char *mode, char *filename)
 soar_ecOpenLog --. More...

int soar_ecCloseLog ()
 soar_ecCloseLog -- Close the log file. More...

int soar_ecCaptureInput (char *filename)
 soar_ecCaptureInput -- Captures the input sent to the agent during by external calls to add-wme and remove-wme. More...

int soar_ecReplayInput (char *filename)
 soar_ecReplayInput -- Replays the input previously captured using the CaptureInput command. More...

void soar_ecGDSPrint ()
 soar_ecGDSPrint -- Debug routine for examing the GDS when necessary. More...

void soar_ecExplainChunkTrace (char *chunk_name)
 soar_ecExplainChunkTrace -- Explain how a chunk came into being. More...

void soar_ecExplainChunkCondition (char *chunk_name, int cond_number)
 soar_ecExplainChunkCondition -- Explain how a particular condition of a chunk came into being. More...

void soar_ecExplainChunkConditionList (char *chunk_name)
 soar_ecExplainChunkConditionList -- Explain how a chunks conditions came into being. More...

void soar_ecPrintFiringsForProduction (char *name)
 soar_ecPrintFiringsForProduction -- Print the number of times a production has fired. More...

void soar_ecPrintTopProductionFirings (int n)
 soar_ecPrintTopProductionFirings -- Print the top <n> productions with respect to their frequency of firing. More...

void soar_ecPrintMemoryPoolStatistics (void)
 soar_ecPrintMemoryPoolStatistics -- Print detailed information about Soar's internal memory usage. More...

void soar_ecPrintMemoryStatistics (void)
 soar_ecPrintMemoryStatistics -- Print information about Soar's internal memory usage. More...

void soar_ecPrintReteStatistics (void)
 soar_ecPrintReteStatistics -- Print information about the rete. More...

void soar_ecPrintSystemStatistics (void)
 soar_ecPrintSystemStatistics -- Print information about the state of Soar. More...

int soar_ecPrintDCHistogram (void)
 soar_ecPrintDCHistogram -- Print the decision cycle time histogram (if one has been kept). More...

int soar_ecPrintKTHistogram (void)
 soar_ecPrintKTHistogram -- Print the kernel time histogram (if one has been kept). More...

int soar_ecPrintAllProductionsOfType (int type, bool internal, bool print_fname, bool full_prod)
 soar_ecPrintAllProductionsOfType -- Print all productions of the specified type. More...

int soar_ecAddWmeFilter (char *szId, char *szAttr, char *szValue, bool adds, bool removes)
 soar_ecAddWmeFilter -- Add a wme filter to control which wmes are displayed. More...

int soar_ecRemoveWmeFilter (char *idStr, char *attrStr, char *valueStr, bool adds, bool removes)
 soar_ecRemoveWmeFilter -- Remove a previously specified wme filter. More...

int soar_ecResetWmeFilters (bool adds, bool removes)
 soar_ecResetWmeFilters -- Remove all wme filters. More...

void soar_ecListWmeFilters (bool adds, bool removes)
 soar_ecListWmeFilters -- Print a list of the wme filters which are currently active. More...

int soar_ecSp (char *rule, char *sourceFile)
 soar_ecSp -- Source a production. More...

void soar_ecPrintMatchSet (wme_trace_type wtt, ms_trace_type mst)
 soar_ecPrintMatchSet -- Print the current match set (the productions which are matched). More...

int soar_ecPrintMatchInfoForProduction (char *name, wme_trace_type wtt)
 soar_ecPrintMatchInfoForProduction -- Show detailed information as to why a production does or doesn't match. More...

void soar_ecPrintInternalSymbols (void)
 soar_ecPrintInternalSymbols -- Print Soar's internally allocated symbols. More...

int soar_ecPrintPreferences (char *szId, char *szAttr, bool print_prod, wme_trace_type wtt)
 soar_ecPrintPreferences -- Print the preferences for a particular (id, attribute) pair. More...

void soar_ecPrintProductionsBeingTraced ()
 soar_ecPrintProductionsBeingTraced -- Print a list of all the productions currently being traced (watched). More...

void soar_ecStopAllProductionTracing ()
 soar_ecStopAllProductionTracing -- Stop tracing all productions. More...

int soar_ecBeginTracingProductions (int n, char **names)
 soar_ecBeginTracingProductions -- Begin tracing a set of productions. More...

int soar_ecStopTracingProductions (int n, char **names)
 soar_ecStopTracingProductions -- Stop tracing a set of productions. More...

void soar_ecPrintMemories (int num, int to_print[])
 soar_ecPrintMemories -- Prints information about the memory usage of different production types. More...

int soar_ecWatchLevel (int level)
 soar_ecWatchLevel -- Set the watch level (the verbosity of output). More...


Detailed Description

The Extended Low Level interface to Soar.

Copyright (c) 1995-1999 Carnegie Mellon University, University of Michigan, University of Southern California/Information Sciences Institute. All rights reserved.

The Soar consortium proclaims this software is in the public domain, and is made available AS IS. Carnegie Mellon University, The University of Michigan, and The University of Southern California/Information Sciences Institute make no warranties about the software or its performance, implied or otherwise. All rights reserved.

Id:
soar_ecore_api.h,v 1.4 2001/02/21 20:27:30 swallace Exp


Function Documentation

int soar_ecAddWmeFilter ( char * szId,
char * szAttr,
char * szValue,
bool adds,
bool removes )
 

soar_ecAddWmeFilter -- Add a wme filter to control which wmes are displayed.

Normally, when wmes are printed during execution (as when watch 5 is set) all changes to working memory are displayed. Adding a wme filter, allows the user to select a subset of these changes for display.

wmes which match the filter are printed.

if the parameters to this function refer to identifiers, the identifier must already be in existence when then filter is added.

Parameters:
szId ->   the id of a matching wme, or * for wildcard
szAttr ->   the attribute of a matching wme, or *
szValue ->   the value of a matching wme, or *
adds ->   TRUE iff the filter should be applied to wmes which are being put into wm.
removes ->   TRUE iff the filter should be applied to wmes which are being taken out of wm.

Returns:
An integer status
Return values:
0   Success.
-1   Fail, the specified identifier is invalid.
-2   Fail, the specified attribute is invalid.
-3   Fail, the specified valus is invalid.
-4   Fail, the filter already exists.

int soar_ecBeginTracingProductions ( int n,
char ** names )
 

soar_ecBeginTracingProductions -- Begin tracing a set of productions.

Parameters:
n ->   the number of productions to begin tracing
names ->   an array (length n ) of production names corrseponding to those which will be traced.

Returns:
An integer status value
Return values:
0   Success
-n   The (n-1)th entry of the name array holds an invalid production name. No productions after this index were added to the watch list.

void soar_ecBuildInfo ( void )
 

soar_BuildInfo -- Indicates compile time setting which affect the current instantiation of Soar.

For example, the DETAILED_TIMERS options must be set at compile time. This function prints such compile time options that were defined for the particular build.

Note that the options which are printed using this function are filtered. They are expected to be the most pertanant of all the compile time options.

See also:
soar_ecExcludedBuildInfo

int soar_ecCaptureInput ( char * filename )
 

soar_ecCaptureInput -- Captures the input sent to the agent during by external calls to add-wme and remove-wme.

Parameters:
-> filename   the name of the capture file or NIL to stop capturing
Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Tried to close the capture file, but no file was open
-2   Tried to open the capture file, but a capture file was already open
-3   Could not open the specified file.
Side Effects:
A (potentially) big file will be created containing all the input which was received by the agent during execution.

int soar_ecCloseLog ( )
 

soar_ecCloseLog -- Close the log file.

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, attempted to close, but no log file was open
Side Effects:
The log file (if opened) is closed.

void soar_ecExcludedBuildInfo ( void )
 

soar_ecExcludedBuildInfo -- Indicates compile time setting which affect the current instantiation of Soar.

Note that the options which are printed using this function are filtered. The options presented using this command are those which are expected to be of lesser importance. However, using this command in conjunction with soar_ecBuildInfo will list all compile time options for the current build.

See also:
soar_ecBuildInfo

void soar_ecExplainChunkCondition ( char * chunk_name,
int cond_number )
 

soar_ecExplainChunkCondition -- Explain how a particular condition of a chunk came into being.

Parameters:
chunk_name ->   the name of the chunk to explain
cond_number ->   the number of the condition to examine

void soar_ecExplainChunkConditionList ( char * chunk_name )
 

soar_ecExplainChunkConditionList -- Explain how a chunks conditions came into being.

Prints the chunk, and then each condition and its associated ground wme. This is a less verbose version of soar_ecExplainChunkTrace

Parameters:
chunk_name ->   the name of the chunk to explain

See also:
soar_exExplainChunkTrace

void soar_ecExplainChunkTrace ( char * chunk_name )
 

soar_ecExplainChunkTrace -- Explain how a chunk came into being.

This function prints information about the productions which fired to yield the specified chunk. It is a more verbose version of soar_ecExplainChunkConditionList

Parameters:
chunk_name ->   the name of the chunk to explain

void soar_ecGDSPrint ( )
 

soar_ecGDSPrint -- Debug routine for examing the GDS when necessary.

This is horribly inefficient and should not generally be used except when something is going wrong and you want to take a peak at the GDS

void soar_ecListWmeFilters ( bool adds,
bool removes )
 

soar_ecListWmeFilters -- Print a list of the wme filters which are currently active.

param "adds ->" TRUE iff the filters applying to wme additions should be listed param "removes ->" TRUE iff the filters applying to wme removals should be listed

int soar_ecOpenLog ( char * mode,
char * filename )
 

soar_ecOpenLog --.

Parameters:
-> mode either w   to write to a new file or "a" to append to an existing file
-> filename   the file's name

Returns:
An integer value with the following semantics:
Return values:
0   Success
-2   Fail, attempted to open, but a lo
Side Effects:
A log file is opened to which output is echoed.

int soar_ecPrintAllProductionsOfType ( int type,
bool internal,
bool print_fname,
bool full_prod )
 

soar_ecPrintAllProductionsOfType -- Print all productions of the specified type.

Parameters:
type ->   the type of production
internal ->   TRUE iff the internal representation should be used
print_fname ->   TRUE iff the file from which the production was loaded should also be printed
full_prod ->   TRUE if the full production should be printed FALSE if only the name should be printed

Returns:
An integer representing the status of the operation
Return values:
0   Success
-1   Fail, invalid type

int soar_ecPrintDCHistogram ( void )
 

soar_ecPrintDCHistogram -- Print the decision cycle time histogram (if one has been kept).

void soar_ecPrintFiringsForProduction ( char * name )
 

soar_ecPrintFiringsForProduction -- Print the number of times a production has fired.

This prints the number of times that particular production has fired, or "No production named <name>" if the specified production is not defined.

Parameters:
-> name   the name of the specified production

Side Effects:

void soar_ecPrintInternalSymbols ( void )
 

soar_ecPrintInternalSymbols -- Print Soar's internally allocated symbols.

int soar_ecPrintKTHistogram ( void )
 

soar_ecPrintKTHistogram -- Print the kernel time histogram (if one has been kept).

int soar_ecPrintMatchInfoForProduction ( char * name,
wme_trace_type wtt )
 

soar_ecPrintMatchInfoForProduction -- Show detailed information as to why a production does or doesn't match.

Parameters:
name ->   the name of the production being scrutenized
wtt ->   specifies how much information about the wmes which are part of the match should be printed. Must be one of:
  • NONE_WME_TRACE don't print anything
  • TIMETAG_WME_TRACE print only the timetag
  • FULL_WME_TRACE print the entire wme
Returns:
An integer status
Return values:
0   Success
-1   Fail, production not found.

void soar_ecPrintMatchSet ( wme_trace_type wtt,
ms_trace_type mst )
 

soar_ecPrintMatchSet -- Print the current match set (the productions which are matched).

Parameters:
wtt ->   specifies how much information about the wmes which are part of the match should be printed. Must be one of:
  • NONE_WME_TRACE don't print anything
  • TIMETAG_WME_TRACE print only the timetag
  • FULL_WME_TRACE print the entire wme
mst ->   specifies which type of matches should be printed. Must be onw of:
  • MS_ASSERT_RETRACT print all matches
  • MS_ASSERT print only assertions
  • MS_RETRACT print only retractions

void soar_ecPrintMemories ( int num,
int to_print[] )
 

soar_ecPrintMemories -- Prints information about the memory usage of different production types.

Parameters:
num ->   the number of productions in each category to print or -1 to print all of them
to_print ->   An array of size NUM_PRODUCTIONS_TYPES in which each slot:
  • USER _PRODUCTION_TYPE
  • DEFAULT_PRODUCTION_TYPE
  • CHUNK_PRODUCTION_TYPE
  • JUSTIFICATION_PRODUCTION_TYPE is set to TRUE if it is to be printed and FALSE otherwise.

void soar_ecPrintMemoryPoolStatistics ( void )
 

soar_ecPrintMemoryPoolStatistics -- Print detailed information about Soar's internal memory usage.

Soar uses its own memory allocation scheme to store much of its data. Memory is allocated from one of a number of memory pools, associated with a particular agent. This function shows information about the size and free space of these pools

void soar_ecPrintMemoryStatistics ( void )
 

soar_ecPrintMemoryStatistics -- Print information about Soar's internal memory usage.

This function gives an overview of Soar's memory usage without examining each pool in any depth.

int soar_ecPrintPreferences ( char * szId,
char * szAttr,
bool print_prod,
wme_trace_type wtt )
 

soar_ecPrintPreferences -- Print the preferences for a particular (id, attribute) pair.

void soar_ecPrintProductionsBeingTraced ( )
 

soar_ecPrintProductionsBeingTraced -- Print a list of all the productions currently being traced (watched).

void soar_ecPrintReteStatistics ( void )
 

soar_ecPrintReteStatistics -- Print information about the rete.

void soar_ecPrintSystemStatistics ( void )
 

soar_ecPrintSystemStatistics -- Print information about the state of Soar.

This function prints a variety of information about Soar's current state. Most importantly, it includes how long Soar has been running (both in seconds, and decision cycles).

void soar_ecPrintTopProductionFirings ( int n )
 

soar_ecPrintTopProductionFirings -- Print the top <n> productions with respect to their frequency of firing.

Prints the top firing produtions and the number of times they have fired. If no productions are defined, then "*** No productions defined ***" is printed.

Parameters:
n ->   the number of productions to print

int soar_ecRemoveWmeFilter ( char * idStr,
char * attrStr,
char * valueStr,
bool adds,
bool removes )
 

soar_ecRemoveWmeFilter -- Remove a previously specified wme filter.

Parameters:
szId ->   the id string specified when the wme was added
szAttr ->   the attribute string specified when the wme was added
szValue ->   the value string specified when the wme was added
adds ->   the same value as specified when the filter was added
removes ->   the same value as specified when the filter was added

Returns:
An integer status
Return values:
0   Success.
-1   Fail, the specified identifier is invalid.
-2   Fail, the specified attribute is invalid.
-3   Fail, the specified valus is invalid.
-4   Fail, the filter could not be found.

int soar_ecReplayInput ( char * filename )
 

soar_ecReplayInput -- Replays the input previously captured using the CaptureInput command.

Parameters:
-> filename   the name of the capture file or NIL to stop capturing

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Could not open the specified file.
-2   Incorrect file header.
Side Effects:
Adds (or removes) an input function corresponding to the current agent. Constructs an array based on the contents of the input file which is used to supply input to the agent at run-time

int soar_ecResetWmeFilters ( bool adds,
bool removes )
 

soar_ecResetWmeFilters -- Remove all wme filters.

Returns:
An interger status
Return values:
0   Success
-1   No removes were performed

void soar_ecSetDefaultWmeDepth ( int depth )
 

soar_ecSetDefaultWmeDepth -- Set the default wme depth to a new value.

The default wme depth indicates how much substructure should be printed when wmes are displayed. The default wme depth can be overridden by using the -depth flag with the print command.

Parameters:
-> depth   the new default wme depth.
Side Effects:
The agent's default wme depth is modified.

int soar_ecSp ( char * rule,
char * sourceFile )
 

soar_ecSp -- Source a production.

Parses a production in text representation and loads it into the rete.

Parameters:
rule ->   the textual representation of the production
sourceFile ->   the file from which the production was loaded or NULL

Returns:
An integer status code
Return values:
0   Success
-1   Fail, production could not be parsed

void soar_ecStopAllProductionTracing ( )
 

soar_ecStopAllProductionTracing -- Stop tracing all productions.

int soar_ecStopTracingProductions ( int n,
char ** names )
 

soar_ecStopTracingProductions -- Stop tracing a set of productions.

Parameters:
n ->   the number of productions to stop tracing
names ->   an array (length n ) of production names corrseponding to those which will no longer be traced .

Returns:
An integer status value
Return values:
0   Success
-n   The (n-1)th entry of the name array holds an invalid production name. No productions after this index were added to the watch list.

int soar_ecWatchLevel ( int level )
 

soar_ecWatchLevel -- Set the watch level (the verbosity of output).

Parameters:
-> level   0 - 5

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Invalid Level


Generated at Wed Aug 8 09:49:33 2001 for The Soar Application Programming Interface by doxygen1.2.6 written by Dimitri van Heesch, © 1997-2001