Main Page   Compound List   File List   Compound Members   File Members  

soarapi.h File Reference

The High Level Interface to Soar. More...

#include "soarkernel.h"
#include "soar_core_api.h"
#include "soar_ecore_api.h"
#include "soarapi_datatypes.h"
#include "debugutil.h"

Go to the source code of this file.

Interaction With Soar

This section deals with four main areas of interaction
  • (Re)Initializing Soar
  • Creating Agents
  • Destroying Agents
  • Starting and Stopping Agents


int soar_ReInitSoar (int argc, char *argv[], soarResult *res)
 soar_ReInitSoar -- This is the command procedure for the "init-soar" command, it (re)initializes the Soar agent. More...

int soar_CreateAgent (int argc, char *argv[], soarResult *res)
 soar_CreateAgent -- This command creates a new agent. More...

int soar_Run (int argc, char *argv[], soarResult *res)
 soar_Run -- This is the command procedure for the "run" command which runs the Soar agent. More...

int soar_DestroyAgent (int argc, char *argv[], soarResult *res)
 soar_DestroyAgent -- This is the command procedure for the "destroy-agent" command, which destroys a Soar agent. More...

int soar_Quit (int argc, char *argv[], soarResult *res)
 soar_Quit -- This is the command procedure for the "quit" command, which prepares Soar to be exited. More...


Modifying Agent Memory

This section deals with two areas of the agent:
  • Production Memory
  • Working Memory


int soar_ReteNet (int argc, char *argv[], soarResult *res)
 soar_ReteNet -- This is the command procedure for the "rete-net" command, which saves or loads a rete-network. More...

int soar_AddWme (int argc, char *argv[], soarResult *res)
 soar_AddWme -- This is the command procedure for the "add-wme" command, which adds an element to working memory. More...

int soar_RemoveWme (int argc, char *argv[], soarResult *res)
 soar_RemoveWme -- This is the command procedure for the "remove-wme" command, which removes a wme from Soar's memory. More...

int soar_Excise (int argc, char *argv[], soarResult *res)
 soar_Excise -- This is the command procedure for the "excise" command, which removes productions from Soar's memory. More...


Modifying the Agents Parameters

int soar_CaptureInput (int argc, char *argv[], soarResult *res)
 soar_CaptureInput -- This is the command procedure for the "capture-input" command which records input wme commands (add|remove) from the INPUT phase. More...

int soar_ReplayInput (int argc, char *argv[], soarResult *res)
 soar_ReplayInput -- This is the command procedure for the "replay-input" command which is used to playback previously recorded input. More...

int soar_ChunkNameFormat (int argc, char *argv[], soarResult *res)
 soar_ChunkNameFormat -- This command specifies the format of names of newly created chunks. More...

int soar_Learn (int argc, char *argv[], soarResult *res)
 soar_Learn -- This is the command procedure for the "learn" command. More...

int soar_MaxElaborations (int argc, char *argv[], soarResult *res)
 soar_MaxElaborations -- This is the command procedure for the "max-elaborations" command, which sets/prints the maximum elaboration cycles allowed. More...

int soar_MaxChunks (int argc, char *argv[], soarResult *res)
 soar_MaxChunks -- This is the command procedure for the "max-chunks" command, which sets/prints the maximum number of chunks allowed. More...

int soar_Operand2 (int argc, char *argv[], soarResult *res)
 soar_Operand2 -- This is the command procedure for the "soar8" command. More...

int soar_WaitSNC (int argc, char *argv[], soarResult *res)
 soar_WaitSNC -- This is the command procedure for the "waitsnc" command. More...

int soar_InputPeriod (int argc, char *argv[], soarResult *res)
 soar_InputPeriod -- This is the command procedure for the "input-period" command, which sets/prints the Soar input period. More...

int soar_MultiAttributes (int argc, char *argv[], soarResult *res)
 soar_MultiAttributes -- This is the command procedure for the "multi-attributes" command, which enables a symbol to have multiple attribute values. More...

int soar_OSupportMode (int argc, char *argv[], soarResult *res)
 soar_OSupportMode -- This is the command procedure for the "o-support-mode" command, which controls the way o-support calculations are done (for the current agent). More...

int soar_ExplainBacktraces (int argc, char *argv[], soarResult *res)
 soar_ExplainBacktraces -- This is the command procedure for the "explain-backtraces" command. More...

int soar_FiringCounts (int argc, char *argv[], soarResult *res)
 soar_FiringCounts -- This is the command procedure for the "firing-counts" command, which prints out how many times a production has fired. More...

int soar_FormatWatch (int argc, char *argv[], soarResult *res)
 soar_FormatWatch -- This is the command procedure for the "format-watch" command, which defines the format to use when printing objects and the Soar goal stack. More...

int soar_IndifferentSelection (int argc, char *argv[], soarResult *res)
 soar_IndifferentSelection -- This is the command procedure for the "indifferent-selection" command which controls indifferent preference arbitration. More...

int soar_InternalSymbols (int argc, char *argv[], soarResult *res)
 soar_InternalSymbols -- This is the command procedure for the "internal-symbols" command which prints information about the Soar agent symbol table. More...

int soar_Matches (int argc, char *argv[], soarResult *res)
 soar_Matches -- This is the command procedure for the "matches" command. More...

int soar_Memories (int argc, char *argv[], soarResult *res)
 soar_Memories -- This is the command procedure for the "memories" command, which prints information about memory use. More...

int soar_ProductionFind (int argc, char *argv[], soarResult *res)
 soar_ProductionFind -- This is the command procedure for the "production-find" command, which finds Soar productions by characteristic. More...

int soar_Preferences (int argc, char *argv[], soarResult *res)
 soar_Preferences -- This is the command procedure for the "preferences" command, which prints all the preferences for the given slot. More...

int soar_Print (int argc, char *argv[], soarResult *res)
 soar_Print -- This is the command procedure for the "print" command, which prints various Soar items. More...

int soar_PWatch (int argc, char *argv[], soarResult *res)
 soar_PWatch -- This is the command procedure for the "pwatch" command which enables the tracing of production firing. More...

int soar_Pool (int argc, char *argv[], soarResult *res)
 soar_Pool -- This is the command procedure for the "pool" command, which yields debugging information on various internal memory pools. More...

int soar_Sp (int argc, char *argv[], soarResult *res)
 soar_Sp -- This is the command procedure for the "sp" command, which defines a new Soar production. More...

int soar_Stats (int argc, char *argv[], soarResult *res)
 soar_Stats -- This is the command procedure for the "stats" command, which prints out internal statistical information. More...

int soar_Stop (int argc, char *argv[], soarResult *res)
 soar_Stop -- This is the command procedure for the "stop-soar" command, halts the Soar agents. More...

int soar_Verbose (int argc, char *argv[], soarResult *res)
 soar_Verbose -- This is the command procedure for the "verbose" command. More...

int soar_Warnings (int argc, char *argv[], soarResult *res)
 soar_Warnings -- This is the command procedure for the "warnings" command, which enables/disables the printing of warning messages. More...

int soar_Log (int argc, char *argv[], soarResult *res)
 soar_Log -- This is the command procedure for the "log" command which records session information to a log file. More...

int soar_AttributePreferencesMode (int argc, char *argv[], soarResult *res)
 soar_AttributePreferencesMode -- This is the command procedure for the "attribute-preferences-mode" command, which controls how (certain) preferences are handled. More...

int soar_Watch (int argc, char *argv[], soarResult *res)
 soar_Watch -- This is the command procedure for the "watch" command, which controls run-time tracing. More...

int soar_DefaultWmeDepth (int argc, char *argv[], soarResult *res)
 soar_DefaultWmeDepth -- This is the command procedure for the "default-wme-depth" command, which sets/prints the default print depth. More...

int soar_BuildInfo (int argc, char *argv[], soarResult *res)
 soar_BuildInfo -- This is the command procedure for the "build-info" command, which yields information about Soar. More...

int soar_ExcludedBuildInfo (int argc, char *argv[], soarResult *res)
 soar_ExcludedBuildInfo -- This is the command procedure for the "ex-build-info" command, which yields information about Soar. More...


Detailed Description

The High 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:
soarapi.h,v 1.3 2001/01/12 18:49:52 swallace Exp


Function Documentation

int soar_AddWme ( int argc,
char * argv[],
soarResult * res )
 

soar_AddWme -- This is the command procedure for the "add-wme" command, which adds an element to working memory.

This command surgically modifies Soar's working memory. Add-wme adds a new wme with the given id, attribute, value, and optional acceptable preference. The given id must be an existing identifier. If '*' is given in place of the attribute or value, Soar creates a new identifier (gensym) for that field.

WARNING: this command is inherently unstable and may have weird side effects (possibly even including system crashes). For example, the chunker can't backtrace through wmes created via add-wme. Removing input wmes or context/impasse wmes may have unexpected side effects. You've been warned.

See also:
soar_RemoveWme
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           add-wme id [^] { attribute | '*'} { value | '*' } [+]
   

Returns:
Returns a standard SOAR completion code
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains information about the new wme in the following format: "<timetag>: <state> ^ <value>"
Side effects:
Adds the given wme to working memory.

int soar_AttributePreferencesMode ( int argc,
char * argv[],
soarResult * res )
 

soar_AttributePreferencesMode -- This is the command procedure for the "attribute-preferences-mode" command, which controls how (certain) preferences are handled.

This command affects the handling of preferences (other than acceptable and reject preferences) for non-context slots. It takes a single numeric argument:

  • 0 - Handle them the normal (Soar 6) way.
  • 1 - Handle them the normal (Soar 6) way, but print a warning message whenever a preference other than + or - is created for a non-context slot.
  • 2 - Whenever a preferences other than + or - is created for a non-context slot, print an error message and ignore (discard) that preference. For non-context slots, the set of values installed in working memory is always equal to the set of acceptable values minus the set of rejected values.
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           attribute-preferences-mode {0 | 1 | 2}
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the current attribute preferences mode.
Side effects:
Sets current_agent(attribute_preferences_mode).

int soar_BuildInfo ( int argc,
char * argv[],
soarResult * res )
 

soar_BuildInfo -- This is the command procedure for the "build-info" command, which yields information about Soar.

This function 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_ExcludedBuildInfo
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           build-info
   

Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.

int soar_CaptureInput ( int argc,
char * argv[],
soarResult * res )
 

soar_CaptureInput -- This is the command procedure for the "capture-input" command which records input wme commands (add|remove) from the INPUT phase.

This command may be used to start and stop the recording of input wmes as created by an external simulation. wmes are recorded decision cycle by decision cycle. Use the command replay-input to replay the sequence.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           capture-input <action>
            <action> ::= -open pathname 
            <action> ::= -query
            <action> ::= -close
   

Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the status of the capture file
Side effects:
Opens and/or closes captured input files.

int soar_ChunkNameFormat ( int argc,
char * argv[],
soarResult * res )
 

soar_ChunkNameFormat -- This command specifies the format of names of newly created chunks.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           chunk-name-format  [-short|-long]
                              [-prefix [<prefix>]]
                              [-count [<start-chunk-number>]]
   
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Sets indicated format style, prefix, and starting chunk number. Prints current <prefix> if -prefix is used without a <prefix>. Prints current <start-chunk-number> if -count is used without a <start-chunk-number>.

int soar_CreateAgent ( int argc,
char * argv[],
soarResult * res )
 

soar_CreateAgent -- This command creates a new agent.

If there were no agents previously, the current agent is defined as the newly created agent. Otherwise, the current agent remains the same.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           create-agent [name]
   

Returns:
Returns a standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error
  • On SOAR_OK: Is empty
Side effects:
Creates a new agent, and possibly changes the current agent

int soar_DefaultWmeDepth ( int argc,
char * argv[],
soarResult * res )
 

soar_DefaultWmeDepth -- This is the command procedure for the "default-wme-depth" command, which sets/prints the default print depth.

With no arguments, this command prints the current default print depth used by the "print" command. With an integer argument, it sets the current default print depth. This default print depth can be overridden on any particular invocation of the "print" command by using the -depth flag, e.g., print -depth 10 args.... The default print depth is initially 1.

See also:
soar_Print
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           default-wme-depth [integer]
   

Returns:
Returns a standard Tcl completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Sets the default print depth for the agent.

int soar_DestroyAgent ( int argc,
char * argv[],
soarResult * res )
 

soar_DestroyAgent -- This is the command procedure for the "destroy-agent" command, which destroys a Soar agent.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           destroy-agent [agent-name]
   

Returns:
Returns a standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Destroys a Soar agent; resets the current agent if necessary

int soar_Excise ( int argc,
char * argv[],
soarResult * res )
 

soar_Excise -- This is the command procedure for the "excise" command, which removes productions from Soar's memory.

"excise -chunks" removes all chunks and justifications from the agent. "excise -task" removes all non-default productions from the agent and performs an init-soar command. excise -all removes all productions from the agent. The switches may be abbreviated to 2 characters (e.g, -c for chunks).

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           excise production-name | -chunks | -default | -task 
                                  |-user | -all
   

Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Removes the indicated productions from the agent memory. For -all and -task, does an init-soar.

int soar_ExcludedBuildInfo ( int argc,
char * argv[],
soarResult * res )
 

soar_ExcludedBuildInfo -- This is the command procedure for the "ex-build-info" command, which yields information about Soar.

This function 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_BuildInfo will list all compile time options for the current build.

See also:
soar_BuildInfo
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           ex-build-info
   

Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.

int soar_ExplainBacktraces ( int argc,
char * argv[],
soarResult * res )
 

soar_ExplainBacktraces -- This is the command procedure for the "explain-backtraces" command.

Explain provides some interpretation of backtraces generated during chunking. Explain mode must be ON when the chunk/ justification is CREATED or no explanation will be available. Explain mode is toggled using the save_backtraces variable. When explain mode is on, more memory is used, and building chunks/justifications will be slower.

The two most useful commands are 'explain-backtraces <name>' and *'explain-backtraces <name> <cond-num>'. The first command lists all of the conditions for the named chunk/justification, and the 'ground' which resulted in inclusion in the chunk/justification. A 'ground' is a WME which was tested in the supergoal. Just knowing which WME was tested may be enough to explain why the chunk/justification exists. If not, the conditions can be listed with an integer value. This value can be used in 'explain <name> <cond-num>' to obtain a list of the productions which fired to obtain this condition in the chunk/justification (and the crucial WMEs tested along the way). Why use an integer value to specify the condition? To save a big parsing job.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           explain-backtraces arg
           arg := ''                 list chunks/justifications if 
                                     explain is on
           arg := <name>             list all conditions & grounds for 
                                     a chunk/justification
           arg := <name> -full       give the backtrace for a named
                                     chunk/justification
           arg := <name> <cond-num>  explain why this condition is in 
                                     the chunk/justification
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
None.

int soar_FiringCounts ( int argc,
char * argv[],
soarResult * res )
 

soar_FiringCounts -- This is the command procedure for the "firing-counts" command, which prints out how many times a production has fired.

This command prints how many times certain productions have fired. With no arguments, it lists all the productions sorted according to how many times they have fired. If an integer argument (call it k) is given, only the top k productions are listed. If k=0, only the productions which haven't fired at all are listed. Note that firing counts are not reset by an (init-soar); the counts indicate the number of firings since the productions were loaded or built.

NB: this is slow, because the sorting takes time O(n*log n)

With one or more production names as arguments, this command prints how many times each of those productions fired.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           firing-counts [[integer] | production-name* ]
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: (Currently this never happens)
  • On SOAR_OK: Is unmodified.
Side effects:
Prints information about production firings.

int soar_FormatWatch ( int argc,
char * argv[],
soarResult * res )
 

soar_FormatWatch -- This is the command procedure for the "format-watch" command, which defines the format to use when printing objects and the Soar goal stack.

Object trace formats control how Soar prints an object-- e.g., a certain operator, problem-space, etc. (This is like trace-attributes in Soar 5.) Stack trace formats control how Soar prints its context stack selections in 'watch 0' and 'pgs' printouts. You specify a trace format by indicating two things:

  • a format string, indicating the printout format to be used
  • what things this format string can be applied to The format string can be any string. Certain 'escape sequences' can be used within the string; for example, 'dc' means print the current decision cycle number.
There are two ways to restrict what objects a format string applies to. The {s|o|*} argument restricts the types of objects: 's' indicates that the format only applies to states; 'o' means it only applies to operators; and '*' means it applies to any type of object. The [object-name] argument (for object trace formats), if given, means it only applies to objects with that ^name. The [ps-name] argument (for stack trace formats) means it only applies within problem spaces with that ^name.

With an -add argument, these commands add new trace formats (replacing any existing ones with identical applicability conditions). With a -remove argument, they remove trace formats with the given applicability conditions. With no arguments, they print out all current trace formats.

The following escape sequences can be used within trace format strings. The S indicates the sequence is ONLY usable in stack traces:

  • cs S- print the current state
  • co S- print the current operator * The cg, cp, cs, and co sequences use the appropriate object trace format.
  • dc S- print the current decision cycle number
  • ec S- print the current elaboration cycle number * The dc and ec sequences are NOT * meaningful in stack traces produced by the "pgs" command. In these cases, nothing is printed.
  • sd S- print the current subgoal depth * The sd sequence uses 0 as the top level).
  • rsd[pattern] S- repeat (subgoal depth) times: print the given pattern.
  • left[num,pattern] - print the pattern left justified in a field of num spaces.
  • right[num,pattern] - print the pattern right justified in a field of num spaces.
  • id - print the identifier of the current object.
  • v[foo] - print the value(s) of attribute ^foo on the current object. If there is no ^foo on the current object, nothing is printed.
  • v[foo.bar.baz] - same as the above, only follow the given attribute path to get the value(s).
  • v[*] - print all values of all attributes on the current object.
  • o[args] - same as v, except that if the value is an identifier it is printed using the appropriate object trace format.
  • av[args] - same as v, except the printed value is preceeded with "^attr " to indicate the attribute name.
  • ao[args] - a combination of the above two.
  • ifdef[pattern] - print the given pattern if and only if all escape sequences inside it are "meaningful" or "well-defined." For example, "ifdef[foo has value: v[foo]]" will print nothing if there is no ^foo on the current object.
  • nl - print a newline.
  • %% - print a percent sign.
  • %[ - print a left bracket.
  • %] - print a right bracket.
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           format-watch {-object | -stack} 
                     [{ { -add    {s|o|*} [name] format}  | 
                        { -remove {s|o|*} [name]       }  }]
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Sets the indicated format.

int soar_IndifferentSelection ( int argc,
char * argv[],
soarResult * res )
 

soar_IndifferentSelection -- This is the command procedure for the "indifferent-selection" command which controls indifferent preference arbitration.

With no arguments, this command prints the current setting of indifferent-selection. With an argument, it sets indifferent-selection to the given value. This controls how Soar's decision procedure chooses between multiple indifferent items:

  • -first -- just choose the first one found (deterministically)
  • -last -- choose the last one found (deterministically)
  • -ask -- ask the user to choose one of the items
  • -random -- choose one randomly
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           indifferent-selection [-first | -ask | -last | -random ]
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Modifies the setting of the indifferent-selection option.

int soar_InputPeriod ( int argc,
char * argv[],
soarResult * res )
 

soar_InputPeriod -- This is the command procedure for the "input-period" command, which sets/prints the Soar input period.

With no arguments, this command stores the current period used to control the input rate to the Soar agent in the SoarResult. With an integer argument, it sets the current input period. If the argument is 0, Soar behaves as it did in versions before 6.2.4, accepting input every elaboration cycle. An input period of "n" means that input is accepted only every "n" decision cycles. The input period is initially set to 0. Negative integer values are disallowed.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           input-period [integer]
   

Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains the current input period.
Side effects:
Sets/prints the input period for the agent.

----------------------------------------------------------------------

int soar_InternalSymbols ( int argc,
char * argv[],
soarResult * res )
 

soar_InternalSymbols -- This is the command procedure for the "internal-symbols" command which prints information about the Soar agent symbol table.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           internal-symbols
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints the current Soar agent symbol table

int soar_Learn ( int argc,
char * argv[],
soarResult * res )
 

soar_Learn -- This is the command procedure for the "learn" command.

With no arguments, this command prints out the current learning status. Any of the following arguments may be given:

  • on - turns all learning on
  • off - turns all learning off
  • only - learning is off except as specified by RHS force-learn
  • except - learning is on except as specified by RHS dont-learn
  • list - print lists of force-learn and dont-learn states
  • all-goals - when learning is on, this allows learning at all goal stack levels (in contrast to bottom-up learning)
  • bottom-up - when learning is on, this allows learning at only the lowest goal stack level; i.e., a chunk is learned at a given level only if no chunk has yet been learned at a lower level.
See also:
chunk-free-problem-spaces , soar_Watch
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           learn arg*
              arg  ::=  -on | -only | -except | -off 
              arg  ::=  -all-goals | -bottom-up
              arg  ::=  -list
   

Returns:
Returns a standard Tcl completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains info from the 'list' sub-command.
Side effects:
Sets booleans for whether or not chunking done.

int soar_Log ( int argc,
char * argv[],
soarResult * res )
 

soar_Log -- This is the command procedure for the "log" command which records session information to a log file.

This command may be used to open and close log files. With the -add argument, specific strings can also be added to the log file.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           log <action>
            <action> ::= [-new | -existing] pathname 
            <action> ::= -add string
            <action> ::= -query
            <action> ::= -off
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the state of the log file
Side effects:
Opens and/or closes log files.

int soar_Matches ( int argc,
char * argv[],
soarResult * res )
 

soar_Matches -- This is the command procedure for the "matches" command.

This command prints partial match information for a selected production. It also prints information about the current match set.

The match set is a list of productions that are about to fire or retract in the next preference phase. With no arguments, this command prints out the production names for both Assertions and Retractions. The first optional argument specifies listing of either Assertions or Retractions.

The last optional argument specifies the level of detail wanted: -counts (the default for single productions) prints out just the partial match counts; -names (the default for match sets) prints out just the production names; -timetags also prints the timetags of wmes matched; and -wmes prints the wmes rather than just their timetags.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           matches production-name [ -count | -timetags | -wmes]
           matches production-name [ 0 | 1 | 2 ]
           ms [-assertions | -retractions] [-names| -timetags | -wmes]
           ms [-assertions | -retractions] [ 0 | 1 | 2 ]
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints production match information.

int soar_MaxChunks ( int argc,
char * argv[],
soarResult * res )
 

soar_MaxChunks -- This is the command procedure for the "max-chunks" command, which sets/prints the maximum number of chunks allowed.

With no arguments, this command returns the current value of the system variable "max-chunks" in the SoarResult. With an integer argument, it sets the current value. This variable controls the maximum number of chunks allowed in a single decision cycle. After this many chunks have been executed, Soar proceeds to decision phase even if quiescence hasn't really been reached yet. (Max-chunks is initially 50.) The maximum number of chunks can also be limited by setting the soar variable max_chunks.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           max-chunks [integer]
   

Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains the current value of max-chunks
Side effects:
Sets the maximum chunks allowed.

----------------------------------------------------------------------

int soar_MaxElaborations ( int argc,
char * argv[],
soarResult * res )
 

soar_MaxElaborations -- This is the command procedure for the "max-elaborations" command, which sets/prints the maximum elaboration cycles allowed.

With no arguments, this command returns the current value of the system variable "max-elaborations" in the SoarResult. With an integer argument, it sets the current value. This variable controls the maximum number of elaboration cycles allowed in a single decision cycle. After this many elabloration cycles have been executed, Soar proceeds to decision phase even if quiescence hasn't really been reached yet. (Max-elaborations is initially 100.)

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           max-elaborations [integer]
   

Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains the current value of max-elaborations
Side effects:
Sets the maximum elaborations allowed.

----------------------------------------------------------------------

int soar_Memories ( int argc,
char * argv[],
soarResult * res )
 

soar_Memories -- This is the command procedure for the "memories" command, which prints information about memory use.

Information is displayed about the memory usage in tokens, of partial matches of productions. If a production-name is given, memory use for that production is printed. If no production name is given, memories will list 'count' productions of the specified type (or all types, if no type is specified). If 'count' is omitted, memory use of all productions is printed.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           memories [arg*]
            arg  ::=  -chunk | -user | -default | -justification 
                             | production-name | count
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints information about memory usage of partial matches.

int soar_MultiAttributes ( int argc,
char * argv[],
soarResult * res )
 

soar_MultiAttributes -- This is the command procedure for the "multi-attributes" command, which enables a symbol to have multiple attribute values.

If given, the value must be a positive integer > 1. The default is 10. If no args are given on the cmdline, the list of symbols that are multi-attributed is printed.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           multi-attributes symbol [value]
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Defines the symbol to be multi-attributed or prints a list of symbols that are declared to multi-attributed.

int soar_OSupportMode ( int argc,
char * argv[],
soarResult * res )
 

soar_OSupportMode -- This is the command procedure for the "o-support-mode" command, which controls the way o-support calculations are done (for the current agent).

It takes a single numeric argument:

  • 0 - do o-support calculations the normal (Soar 6) way.
  • 1 - do o-support calculations the normal (Soar 6) way, but print a warning message whenever a preference is created that would get different support under Doug's proposal.
  • 2 - do o-support calculations according to Doug Pearson's proposal. (See osupport.c for details.)
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           o-support-mode {0 | 1 | 2}
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the current o-support mode.
Side effects:
Sets current_agent(o_support_calculation_type).

int soar_Operand2 ( int argc,
char * argv[],
soarResult * res )
 

soar_Operand2 -- This is the command procedure for the "soar8" command.

With no arguments, this command prints out the current operand state. Otherwise it turns on or off soar8 mode.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           operand2 arg*
              arg  ::=  -on | -off 
   

Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains the current operand state.
Side effects:
re-initializes soar and puts it in the requested mode. Also modifies the soar_version_string.

int soar_PWatch ( int argc,
char * argv[],
soarResult * res )
 

soar_PWatch -- This is the command procedure for the "pwatch" command which enables the tracing of production firing.

This command enables tracing of the firings and retractions of individual productions. (This mechanism is orthogonal to the watch -firings mechanism. See the "watch" command for more information. PWatch, with no arguments, lists the productions currently being traced. With one or more production name arguments, it enables tracing of those productions. Using the -on or -off option explicitly turns tracing on or off for the given productions. Tracing persists until disabled, or until the production is excised.

See also:
soar_Watch , soar_Excise
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           pwatch [-on | -off] production-name*
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Enables the tracing of the specified productions.

int soar_Pool ( int argc,
char * argv[],
soarResult * res )
 

soar_Pool -- This is the command procedure for the "pool" command, which yields debugging information on various internal memory pools.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           pool [-all] <pool-name> <pool-args>
   

pool-name is one of: -wme -condition -preference -instantiation -identifier -production

pool-arguements:

for -instantiation, one of: -none (no wme information) -full (full wme information)

for -production, one of: -name (print production name only) -full (print entire production)

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
None

int soar_Preferences ( int argc,
char * argv[],
soarResult * res )
 

soar_Preferences -- This is the command procedure for the "preferences" command, which prints all the preferences for the given slot.

This command prints all the preferences for the slot given by the 'id' and 'attribute' arguments. The optional 'detail' argument must be one of the following (-none is the default):

  • -none -- prints just the preferences themselves
  • -names -- also prints the names of the productions that generated them
  • -timetags -- also prints the timetags of the wmes matched by the productions
  • -wmes -- prints the whole wmes, not just their timetags.
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           preferences [id] [attribute] [-none | -names | -timetags | -wmes]
           preferences [id] [attribute] [ 0 | 1 | 2 | 3 ]
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints preference information.

int soar_Print ( int argc,
char * argv[],
soarResult * res )
 

soar_Print -- This is the command procedure for the "print" command, which prints various Soar items.

The print command is used to print items from production memory or working memory. It can take several kinds of arguments. When printing items from working memory, the objects are printed unless the -internal flag is used, in in which case the wmes themselves are printed.

See also:
default-wme-depth
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           print <stack>|<items>
            <stack>  ::= -stack [-state | -operator]*
            <items>  ::= [-depth n] [-internal] [-filename] <arg>*
            <arg>    ::= production-name  print that production
            <arg>    ::= production type  [-name | -full] -all | -chunks | 
                                          -defaults | -user | -justifications
            <arg>    ::= identifier       id of the object to print
            <arg>    ::= integer          timetag of wme--the identifier 
                                          from the wme indicates the object 
                                          to be printed
            <arg>    ::= <pattern>        pattern--same as if you listed 
                                          as arguments the timetags of all 
                                          wmes matching the pattern,
                                          often results in multiple copies
                                          of the same object being printed
   
          <pattern> ::= '{' '('  {identifier | '*'} 
                               ^ {attribute  | '*'} 
                                 {value      | '*'} 
                                 [+] ')' '}'
   

The optional [-depth n] argument overrides default-wme-depth. The optional [-internal] argument tells Soar to print things in their internal form. For productions, this means leaving conditions in their reordered (rete net) form. For wmes, this means printing the individual wmes with their timetags, rather than the objects. The optional [-filename] argument tells Soar to print the filename for source'd productions.

-depth 0 is meaningful only for integer and pattern arguments. It causes only the matching wmes to be printed, instead of all wmes whose id is an id in one of the matching wmes.

-name | -full apply to printing productions. For the specified production type, only the production name will be printed, unless the -full flag is specified. For named productions, the default is to print the entire production unless -name is specified. (-name for an individual prod seems silly, but it's included for completeness...)

The -depth n, -internal, -name, and -full flags apply only to the args that appear after them on the command line.

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints the selected objects.

kjh CUSP(B11) = "Soar should know the file name from which a given production was loaded."

The changes here to PrintCmd are meant to be more illustrative of how to provide a production's file name to the user than they are meant to be final changes to PrintCmd, which is undergoing concurrent work at this time.

print -filename <production-name>+

int soar_ProductionFind ( int argc,
char * argv[],
soarResult * res )
 

soar_ProductionFind -- This is the command procedure for the "production-find" command, which finds Soar productions by characteristic.

pf is a production finding facility. It allows you to find productions that either test a particular LHS pattern or produce particular RHS preferences.

The syntax of the lhs-conditions or rhs-actions is exactly their syntax within SP's. In addition, the symbol '*' may be used as a wildcard for an attribute or value. Note that variable names do not have to match the specific names used in productions.

Specifying -chunks means only chunks are searched (and -nochunks means no chunks are searched).

Note that leading blanks in the clause will cause pf to fail.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the

Examples:

Find productions that test that some object gumby has attribute ^alive t, and test an operator named foo: production-find {(<s> ^gumby <gv> ^operator.name foo)(<gv> ^alive t)}

Find productions that propose foo: production-find -rhs {(<x> ^operator<op> +)(<op> ^name foo)}

Find productions that test the attribute ^pokey: production-find {(<x> ^pokey *)}

Find productions that test the operator foo production-find {(<s> ^operator.name foo)}

Syntax:
           production-find [side] [chnks] [-show-bindings] {clauses}
                side  :==  -rhs | -lhs
                chnks :==  -chunks | -nochunks
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints the productions found

int soar_Quit ( int argc,
char * argv[],
soarResult * res )
 

soar_Quit -- This is the command procedure for the "quit" command, which prepares Soar to be exited.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           quit
   

Returns:
Returns a standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
turns logging off, does some clean up.

int soar_ReInitSoar ( int argc,
char * argv[],
soarResult * res )
 

soar_ReInitSoar -- This is the command procedure for the "init-soar" command, it (re)initializes the Soar agent.

This command removes all wmes from working memory, wiping out the goal stack, and resets all statistics (except the counts tracking how many times each individual production has fired which is used by the "firing-counts" command).

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the function.
Syntax:
  
           init-soar
   

Returns:
A standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about the error.
  • On SOAR_OK: Is empty
Side effects:
Empties working memory, removes the goal stack, and resets statistics.

int soar_RemoveWme ( int argc,
char * argv[],
soarResult * res )
 

soar_RemoveWme -- This is the command procedure for the "remove-wme" command, which removes a wme from Soar's memory.

WARNING: this command is inherently unstable and may have weird side effects (possibly even including system crashes). For example, the chunker can't backtrace through wmes created via add-wme. Removing input wmes or context/impasse wmes may have unexpected side effects. You've been warned.

See also:
soar_AddWme
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           remove-wme integer
   

Returns:
Returns a standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Removes the selected working memory element from Soar.

int soar_ReplayInput ( int argc,
char * argv[],
soarResult * res )
 

soar_ReplayInput -- This is the command procedure for the "replay-input" command which is used to playback previously recorded input.

Input originally obtained using the "capture-input" command is replayed with this command

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           replay-input <action>
            <action> ::= -open pathname 
            <action> ::= -query
            <action> ::= -close
   

Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the status of the replay file
Side effects:
Opens and/or closes replay files.

int soar_ReteNet ( int argc,
char * argv[],
soarResult * res )
 

soar_ReteNet -- This is the command procedure for the "rete-net" command, which saves or loads a rete-network.

The rete-net is a binary file containing the contents of production memory. Because productions are decomposed into their constituent conditions before being added to the network, the productions themselves are difficult to recognize. Although this file format is not encrypted in any real sense, it does obfuscate productions to a degree similar to compilation of source code.

Moreoever, if productions are saved as a rete-net, they can be loaded by a version of Soar which does not contain a productions parser (and supporting elements) this allows a significantly smaller footprint for the executable when memory is at a premium.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           rete-net {-save | -load} {filename}
   

Returns:
Returns a standard SOAR completion code
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Adds the given wme to working memory.

int soar_Run ( int argc,
char * argv[],
soarResult * res )
 

soar_Run -- This is the command procedure for the "run" command which runs the Soar agent.

This is the command for running Soar agents. It takes two optional arguments, one specifying how many things to run, and one specifying what type of things to run (by default all agents are run). The following types are available:

  • p - run Soar for n phases. A phase is either an input phase, preference phase, working memory phase, output phase, or decision phase.
  • e - run Soar for n elaboration cycles. (For purposes of this command, decision phase is counted as an elaboration cycle.)
  • d - run Soar for n decision cycles.
  • s - run Soar until the nth time a state is selected.
  • o - run Soar until the nth time an operator is selected.
  • out - run Soar by decision cycles until output is generated.
  • context-variable - run Soar until the nth time a selection is made for that particular context slot, or until the context stack pops to above that context. Unlike Soar 6 "go" , "run" has no memory of settings from previous run commands.
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           run [integer | 'forever'] [type] [-self]
           type ::= p | e | d | s | o | context-variable
           if no integer given, but [type] is specified, n = 1 assumed
           if no [type] given, but [int] specified, decisions assumed
  
Examples:
  • run 5 d -> run all agents for 5 decision cycles
  • run d -self -> run the current agent only for 5 decision cycles
  • run 3 -> run all agents for 3 decision cycles
  • run e -> run all agents for 1 elaboration cycle
  • run 1 s -> run all agents until the next state is selected (i.e., until the next time an impasse arises)
  • run <so> -> run until the next superoperator is selected (or until the supergoal goes away)
  • run 3 <o> -> run for 3 operator selections at this level (continuing through any subgoals that arise)
Returns:
Returns a standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Runs the Soar agents for the indicated duration

int soar_Sp ( int argc,
char * argv[],
soarResult * res )
 

soar_Sp -- This is the command procedure for the "sp" command, which defines a new Soar production.

This command adds a new production to the system. (If another production with the same name already exists, it is excised.) The optional flags are as follows:

  • :o-support -- specifies that all the RHS actions are to be given o-support when the production fires
  • :no-support -- specifies that all the RHS actions are only to be given i-support when the production fires
  • :default -- specifies that this production is a default production (this matters for (excise-task) and (watch task))
  • :chunk -- specifies that this production is a chunk (this matters for (learn trace))
See also: lhs-grammar, rhs-grammar
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           sp {rule-body}
            rule-body := name 
                        ["documentation-string"] 
                        [ flag ]*
                        LHS
                        ->
                        RHS
  
            flag  ::=  :o-support
            flag  ::=  :i-support
            flag  ::=  :default
            flag  ::=  :chunk
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty -- note OK so long as the proper number of arguments is supplied. Invalid productions don't cause an error....
Side effects:
Runs the agent for the indicated number of decision cycles.

int soar_Stats ( int argc,
char * argv[],
soarResult * res )
 

soar_Stats -- This is the command procedure for the "stats" command, which prints out internal statistical information.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           stats [-system <stype> | -memory <mtype> | -rete <rtype>] 
           <stype> ::= -default-production-count
                       -user-production-count
                       -chunk-count
                       -justification-count
                       -all-productions-count
                       -dc-count
                       -ec-count
                       -ecs/dc
                       -firings-count
                       -firings/ec
                       -wme-change-count
                       -wme-addition-count
                       -wme-removal-count
                       -wme-count
                       -wme-avg-count
                       -wme-max-count
                       -total-time             |T
                       -ms/dc                  |T
                       -ms/ec                  |T
                       -ms/firing              |T
                       -ms/wme-change          |T
                       -match-time             |D
                       -ownership-time         |D
                       -chunking-time          |D
  
           The items marked |T are available when Soar has been
           compiled with the NO_TIMING_STUFF flag NOT SET and 
           the items marked |D are available when Soar has been
           compiled with the DETAILED_TIMING_STATS flag SET.
   
           <mtype> ::= -total
                       -overhead
                       -strings
                       -hash-table
                       -pool [-total | pool-name [<aspect>]]
                       -misc
          <aspect> ::= -used                   |M
                       -free                   |M
                       -item-size
                       -total-bytes
  
            The items marked |M are available only when Soar has
            been compiled with the MEMORY_POOL_STATS option.
  
            <rtype> ::= -total-nodes
                        -dummy-top-nodes
                        -pos-nodes
                        -unhashed-pos-nodes
                        -neg-nodes
                        -unhashed-neg-nodes
                        -cn-nodes
                        -cn-partner-nodes
                        -production-nodes
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is unmodified.
Side effects:
Prints the selected statistics

int soar_Stop ( int argc,
char * argv[],
soarResult * res )
 

soar_Stop -- This is the command procedure for the "stop-soar" command, halts the Soar agents.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           stop-soar [-s[elf] [reason-string]]
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
All agents are halted.

int soar_Verbose ( int argc,
char * argv[],
soarResult * res )
 

soar_Verbose -- This is the command procedure for the "verbose" command.

With no arguments, this command prints out the current verbose state. Any of the following arguments may be given:

  • on - turns verbose on
  • off - turns verbose off
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           verbose arg*
             arg  ::=  -on | -off 
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
none. it just sets soar_verbose_flag.

int soar_WaitSNC ( int argc,
char * argv[],
soarResult * res )
 

soar_WaitSNC -- This is the command procedure for the "waitsnc" command.

With no arguments, this command stores the current wait/snc state in the SoarResult. If this mode is on, soar waits (in its current state) for new things to happen. If it is off, then soar generates impasses when the state does not change.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           waitsnc arg*
              arg  ::=  -on | -off 
   

Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains the current wait/snc state.
Side effects:
Changes the wait/snc state

----------------------------------------------------------------------

int soar_Warnings ( int argc,
char * argv[],
soarResult * res )
 

soar_Warnings -- This is the command procedure for the "warnings" command, which enables/disables the printing of warning messages.

warnings -on enables the printing of warning messages. This is the default. warnings -off turns off most warning messages. warnings prints an indication of whether warning messages are enabled or not.

Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Synax:
           warnings [-on | -off]
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the state of the warnings.
Side effects:
Sets the warnings option.

int soar_Watch ( int argc,
char * argv[],
soarResult * res )
 

soar_Watch -- This is the command procedure for the "watch" command, which controls run-time tracing.

This command controls what information gets printed in the run-time trace. With no arguments, it just prints out the current watch status. The numeric arguments are different from the semantics in Soar 5 and 6; for details, see help watch. Setting either the -on or -off switch selectively turns on or off only that setting. Setting the -inclusive switch (which can be abbreviated as -inc) or setting no flag at all has the effect of setting all levels up to and including the level specified. For example, watch productions -on selectively turns on the tracing of production firings/retractions; watch productions -off selectively turns it off again. watch productions [-inc] turns on the tracing of productions and also turns on tracing of all levels below productions: decisions and phases, too. Individual watch parameters may be used to modify the inclusive settings as well, selectively turning on or off and levels outside or inside the inclusive range.

The following keyword arguments may be given to the 'watch' command:

  • 0|none -- turns off all printing about Soar's internals
  • 1|decisions -- controls whether state and operator decisions are printed as they are made
  • 2|phases -- controls whether phase names are printed as Soar executes
  • 3|productions -- controls whether the names of productions are printed as they fire and retract. See individual production-type args below.
  • 4|wmes -- controls whether changes to working memory are printed
  • 5|preferences -- controls whether the preferences generated by the traced productions are printed when those productions fire or retract. When a production fires, all the preferences it generates are printed. When it retracts, only the ones being removed from preference memory are printed (i.e., the i-supported ones).
  • -nowmes|-timetags|-fullwmes -- controls the level of detail given about the wmes matched by productions whose firings and retractions are being traced. Level 0|-nowmes means no information about the wmes is printed. Level 1|-timetags means the wme timetags are printed. Level 2|-fullwmes means the whole wmes are printed.
  • -all|-default|-chunks|-justifications|-user {-noprint|-print|-fullprint} allows user to selectively print production *types* as they fire and retract. -noprint prints nothing, -print prints the production name, -fullprint prints the entire production. (fullprint not yet implemented) NOTE: these args can be abbreviated by the first char ONLY, otherwise the full arg must be specified.
  • -prefs|-noprefs -- turns on|off the printing of preferences for the productions being watched. These args need to be made to apply to just the given production type, instead of to all productions.
  • aliases -on|-off -- controls the echoing of aliases as they are defined.
  • backtracing -on|-off -- controls the printing of backtracing information when a chunk or justification os created.
  • learning -noprint|-print|-fullprint -- controls the printing of chunks/justifications as they are created. -noprint is don't print anything, -names prints just the names, -fullprint prints the entire chunk/justification.
  • loading -on|-off -- controls the printing of '*' for each production loaded and a '#' for each production excised.
Currently the following args apply to all productions being watched, but they need to be changed to apply to only the specified production type. This requires the addition of many new kernel flags, one for each arg for each production type. -nowmes|-timetags|-fullwmes -noprint|-print|-fullprint -prefs|-noprefs

See also:
soar_Learn , soar_PWatch , soar_Print
Parameters:
-> argc   The number of arguments is the argv block
-> argv   An array of strings, each of which is a word in the argument list to this function
<- res   A SoarResult structure which will be filled in by the
Syntax:
           watch arg*
             arg  ::=  0 | 1 | 2 | 3 | 4 | 5
             arg  ::=  0 | none
             arg  ::=  decisions | phases | productions | wmes | preferences
                          [-on | -off | -inc[lusive]]
             arg  ::=  -nowmes | -timetags | -fullwmes
             arg  ::=  aliases  {-on|-off}
             arg  ::=  backtracing {-on|-off}
             arg  ::=  learning {-noprint|-print|-fullprint}
             arg  ::=  loading  {-on|-off}
   

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Sets booleans for printing information during Soar execution cycles.


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