Main Page   Compound List   File List   Compound Members   File Members  

soar_core_api.h File Reference

The Low Level interface to Soar. More...

#include "soarkernel.h"
#include "callback.h"
#include "soarapi_datatypes.h"

Go to the source code of this file.

Modifying the Agents Parameters

void soar_cSetSystemParameter (int param, long value)
 soar_cSetSystemParameter -- Set a system parameter for the current agent. More...

void soar_cInitializeDCHistogram (int size, int freq)
 soar_cInitializeDCHistogram -- Prepare an array of time structures which will be used to store the time executing a sets of decision cycles. More...

void soar_cInitializeKTHistogram (int size)
 soar_cInitializeKTHistogram -- Prepare an array of time structures which will be used to store the kernel time executing a each successive decision cycle. More...

void soar_cSetChunkNameLong (bool truly)
 soar_cSetChunkNameLong -- Set long or short chunk names according to the specified parameter. More...

int soar_cSetChunkNameCount (long count)
 soar_cSetChunkNameCount -- Set the chunk count. More...

int soar_cSetChunkNamePrefix (char *prefix)
 soar_cSetChunkNamePrefix -- Set the chunk name prefix. More...

void soar_cSetLearning (enum soar_apiLearningSetting setting)
 soar_cSetLearning -- Adjust the learning settings. More...

int soar_cSetOperand2 (bool turnOn)
 soar_cSetOperand2 -- Toggles from Soar7 to Soar8 execution mode. More...

void soar_cSetWaitSNC (bool wait)
 soar_cSetWaitSNC -- Determine whether Soar should generate explict state-no-change impasses. More...

int soar_cMultiAttributes (char *attr, int value)
 soar_cMultiAttributes -- Modify the multi-attributes setting. More...

int soar_cAttributePreferencesMode (int mode)
 soar_cAttributePreferencesMode -- Determine how preferences for non-context slots should be handled. More...


Interaction With Soar

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


void soar_cInitializeSoar (void)
 soar_cInitializeSoar -- Initialize Soar for the very first time. More...

int soar_cReInitSoar (void)
 soar_cReInitSoar -- Reset Soar (and agents) to the initial state. More...

void soar_cCreateAgent (char *agent_name)
 soar_cCreateAgent -- Create a new soar agent with the specified name. More...

int soar_cRun (long n, bool all, enum go_type_enum type, enum soar_apiSlotType slot)
 soar_cRun -- Run the current agent, or all agents for a specified period ... More...

void soar_cStopAllAgents (void)
 soar_cStopAllAgents -- Stops all agents.

void soar_cStopCurrentAgent (char *reason)
 soar_cStopCurrentAgent -- Stops the current agent. More...

int soar_cDestroyAgentByName (char *name)
 soar_cDestroyAgentByName -- Destroy an agent, given its name. More...

int soar_cDestroyAllAgentsWithName (char *name)
 soar_cDestroyAllAgentsWithName -- Destroy a set of agents, given a name. More...

void soar_cDestroyAgentByAddress (psoar_agent delete_agent)
 soar_cDestroyAgentByAddress -- Destroy an agent, given a pointer to it. More...

int soar_cDestroyAgentById (int agent_id)
 soar_cDestroyAgentById -- Destroy an agent, given its unique id. More...

void soar_cQuit (void)
 soar_cQuit -- Quit Soar. More...


Modifying Agent Memory

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


int soar_cLoadReteNet (char *filename)
 soar_cLoadReteNet -- Load a Rete Network into the agent from a specified file. More...

int soar_cSaveReteNet (char *filename)
 soar_cSaveReteNet -- Save a Rete Network from the agent into a specified file. More...

unsigned long soar_cAddWme (char *szId, char *szAttr, char *szValue, bool accept, psoar_wme *new_wme)
 soar_cAddWme -- Add a working memory element to the current agent's working memory. More...

int soar_cRemoveWmeUsingTimetag (int num)
 soar_cRemoveWmeUsingTimetag -- Remove a working memory element, given its timetag. More...

int soar_cRemoveWme (psoar_wme wme)
 soar_cRemoveWme -- Remove a working memory element. More...

void soar_cExciseAllProductions (void)
 soar_cExciseAllProductions -- Remove all productions from the agents memory and ReInitialize the agent. More...

void soar_cExciseAllTaskProductions (void)
 soar_cExciseAllTaskProductions -- Remove all but default productions from the agents memory and ReInitialize the agent. More...

void soar_cExciseAllProductionsOfType (byte type)
 soar_cExciseAllProductionsOfType -- Remove all productions of a specific type from the agents memory and ReInitialize the agent. More...

int soar_cExciseProductionByName (char *name)
 soar_cExciseProductionByName -- Remove the production with the specified name. More...


Callbacks

void soar_cAddInputFunction (agent *a, soar_callback_fn f, soar_callback_data cb_data, soar_callback_free_fn free_fn, char *name)
 soar_cAddInputFunction -- Adds an input function to the specified agent. More...

void soar_cRemoveInputFunction (agent *a, char *name)
 soar_cRemoveInputFunction -- Remove an input function with the specified name. More...

void soar_cAddOutputFunction (agent *a, soar_callback_fn f, soar_callback_data cb_data, soar_callback_free_fn free_fn, char *output_link_name)
 soar_cAddOutputFunction -- Similar to soar_cAddInputFunction(), but adds a function which is called durnig each output phase. More...

void soar_cRemoveOutputFunction (agent *a, char *name)
 soar_cRemoveOutputFunction -- Remove an output function with the specified name. More...

void soar_cPushCallback (soar_callback_agent a, SOAR_CALLBACK_TYPE type, soar_callback_fn fn, soar_callback_data data, soar_callback_free_fn free_fn)
 soar_cPushCallback -- Push a callback onto the specified callback stack. More...

void soar_cAddCallback (soar_callback_agent a, SOAR_CALLBACK_TYPE type, soar_callback_fn fn, soar_callback_data data, soar_callback_free_fn free_fn, soar_callback_id id)
 soar_cAddCallback -- Add a callback onto the specified callback stack. More...

void soar_cPopCallback (soar_callback_agent a, SOAR_CALLBACK_TYPE type)
 soar_cPopCallback -- Pops off the last callback to be added to the specified callback stack. More...

void soar_cRemoveCallback (soar_callback_agent a, SOAR_CALLBACK_TYPE type, soar_callback_id id)
 soar_cRemoveCallback -- Remove the callback from the specified callback stack which has the specified id. More...

void soar_cAddGlobalCallback (SOAR_GLOBAL_CALLBACK_TYPE type, soar_callback_fn fn, soar_callback_data data, soar_callback_free_fn free_fn, soar_callback_id id)
 soar_cAddGlobalCallback -- Add a callback onto the specified global callback stack. More...

void soar_cRemoveGlobalCallback (SOAR_GLOBAL_CALLBACK_TYPE type, soar_callback_id id)
 soar_cRemoveGlobalCallback -- Remove a callback onto the specified /global/ callback stack. More...

void soar_cListAllCallbacks (soar_callback_agent a, bool monitorable_only)
 soar_cListAllCallbacks -- List the callbacks registered to the agent. More...

void soar_cListAllCallbacksForEvent (soar_callback_agent agent, SOAR_CALLBACK_TYPE type)
 soar_cListAllCallbacksForEvent -- List the all callbacks of a specific type registered to the agent. More...

void soar_cRemoveAllMonitorableCallbacks (soar_callback_agent agent)
 soar_cRemoveAllMonitorableCallbacks -- Remove all of the callbacks (other than PRINT or LOG callbacks) registered to the specified agent. More...

void soar_cRemoveAllCallbacksForEvent (soar_callback_agent agent, SOAR_CALLBACK_TYPE type)
 soar_cRemoveAllCallbacksForEvent -- Remove all of the callbacks of a specified type which have been registered to the specified agent. More...

void soar_cTestAllMonitorableCallbacks (soar_callback_agent the_agent)
 soar_cTestAllMonitorableCallbacks -- Register a simple print function on all the monitorable callback stacks (all but PRINT and LOG). More...

SOAR_CALLBACK_TYPE soar_cCallbackNameToEnum (char *name, bool monitor_only)
 soar_cCallbackNameToEnum -- Return the enumerated type (the callback type) given an event name. More...


Etc

Miscellanous controls, including:
  • Multi Agent Controls
  • Accessors for Encapsulated Data


char* soar_cGetWmeId (psoar_wme w, char *buff)
 soar_cGetWmeId -- An accessor function for a psoar_wme. More...

char* soar_cGetWmeAttr (psoar_wme w, char *buff)
 soar_cGetWmeAttr -- An accessor function for a psoar_wme. More...

char* soar_cGetWmeValue (psoar_wme w, char *buff)
 soar_cGetWmeValue -- An accessor function for a psoar_wme. More...

unsigned long soar_cGetWmeTimetag (psoar_wme w)
 soar_cGetWmeTimetag -- An accessor function for a psoar_wme. More...

unsigned long soar_cAddIntWme (char *szId, char *szAttr, int value, bool acceptable_preference, psoar_wme *new_wme)
 soar_cAddIntWme -- A wrapper for the soar_cAddWme() function which allows easy addition of a wme whose value is an integer. More...

unsigned long soar_cAddFloatWme (char *szId, char *szAttr, float value, bool acceptable_preference, psoar_wme *new_wme)
 soar_cAddFloatWme -- A wrapper for the soar_cAddWme() function which allows easy addition of a wme whose value is a float. More...

void soar_cInitAgentIterator (soar_apiAgentIterator *ai)
 soar_cInitAgentIterator -- Fill in a soar_apiAgentIterator structure for first use. More...

bool soar_cStepAgentIterator (soar_apiAgentIterator *ai)
 soar_cStepAgentIterator -- Increment an agent iterator srtucture. More...

psoar_agent soar_cGetAgentByName (char *name)
 soar_cGetAgentByName -- Get a pointer to a soar agent. More...

int soar_cGetIdForAgentByName (char *name)
 soar_cGetIdForAgentByName -- Get the unique id of a particular agent. More...

bool soar_cSetCurrentAgentByName (char *name)
 soar_cSetCurrentAgentByName -- Set the 'current agent'. More...

void soar_cSetCurrentAgent (psoar_agent agent)
 soar_cSetCurrentAgent -- Set the 'current agent'. More...

psoar_agent soar_cGetCurrentAgent ()
 soar_cGetCurrentAgent -- Get the 'current agent'. More...

char* soar_cGetAgentInputLinkId (psoar_agent a, char *buff)
 soar_cGetAgentInputLinkId -- * An accessor function for a psoar_agent. More...

char* soar_cGetAgentOutputLinkId (psoar_agent a, char *buff)
 soar_cGetAgentOutputLinkId -- * An accessor function for a psoar_agent. More...

int soar_cGetAgentId (psoar_agent a)
 soar_cGetAgentId -- * An accessor function for a psoar_agent. More...

void print (char *format,...)
 print -- Print a given string using the agent's current print function. More...


Detailed Description

The 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_core_api.h,v 1.5 2001/05/08 18:36:07 swallace Exp

Conventions: Above each function is a short description of what it does. The arguments and return values are also explained as well as side effects of calling the function.

Each argument is described an arrow of some sort is placed between the argument's name and its description. This arrow indicates what role the argument plays, and may be one of:


Function Documentation

void print ( char * format,
... )
 

print -- Print a given string using the agent's current print function.

This function invokes the current agent's top level PRINT_CALLBACK & LOG_CALLBACK to perform an agent specific print operation. This operation mimics the output generated internally by the soar kernel, and so using this function provides an easy way to guarentee that input produced by you interface, and by the soar kernel will be handled the same way.

void soar_cAddCallback ( soar_callback_agent a,
SOAR_CALLBACK_TYPE type,
soar_callback_fn fn,
soar_callback_data data,
soar_callback_free_fn free_fn,
soar_callback_id id )
 

soar_cAddCallback -- Add a callback onto the specified callback stack.

Unlike soar_cPushCallback(), this function is also designed for callback which will be registered for a longer term. Each callback must have an id string which is assumed to be unique within the specified callback stack. This string is used later, for removal.

Parameters:
-> a   the agent which will utilize the function
-> type   the destination stack for this callback function
-> fn   the function to be called during the input phase
-> cb_data   a pointer to a data structure known at the time of registration, which will be passed to the callback function when it is invoked (e.g. a filehandle)
-> free_fn   a function to free the cb_data
-> id   a registeration name

unsigned long soar_cAddFloatWme ( char * szId,
char * szAttr,
float value,
bool acceptable_preference,
psoar_wme * new_wme )
 

soar_cAddFloatWme -- A wrapper for the soar_cAddWme() function which allows easy addition of a wme whose value is a float.

Parameters:
-> szId   the identifier on which the wme should be added
-> szAttr   the attribute of the wme. This value may or may not start with a '^'. If a new identifier is requested, this argument should be "*"
-> value   the value of the wme. This is a float.
-> accept   TRUE if the wme should receive an acceptable preference
<- new_wme   a pointer to a psoar_wme structure which is set to point to the new wme during the execution of this function

Returns:
a timetag

void soar_cAddGlobalCallback ( SOAR_GLOBAL_CALLBACK_TYPE type,
soar_callback_fn fn,
soar_callback_data data,
soar_callback_free_fn free_fn,
soar_callback_id id )
 

soar_cAddGlobalCallback -- Add a callback onto the specified global callback stack.

Unlike soar_cAddCallback(), this function adds to an agent independent callback stack. Note that this does not add the callback to each agent's callback stack, but rather specifies a new set of callback stacks which are agent-independent.

Parameters:
-> type   the global destination stack for this callback function
-> fn   the function to be called
-> data   a pointer to a data structure known at the time of registration, which will be passed to the callback function when it is invoked (e.g. a filehandle)
-> free_fn   a function to free the cb_data
-> id   a registeration name

void soar_cAddInputFunction ( agent * a,
soar_callback_fn f,
soar_callback_data cb_data,
soar_callback_free_fn free_fn,
char * name )
 

soar_cAddInputFunction -- Adds an input function to the specified agent.

This is called during each input phase. This function is really just a wrapper for the more general soar_cAddCallback() using the INPUT_PHASE_CALLBACK specifier

Parameters:
-> a   the agent which will utilize the input function
-> f   the function to be called during the input phase
-> cb_data   a pointer to a data structure known at the time of registration, which will be passed to the callback function when it is invoked (e.g. a filehandle)
-> free_fn   a function to free the cb_data
-> name   a registeration name (this should be unique)

See also:
soar_cAddCallback

unsigned long soar_cAddIntWme ( char * szId,
char * szAttr,
int value,
bool acceptable_preference,
psoar_wme * new_wme )
 

soar_cAddIntWme -- A wrapper for the soar_cAddWme() function which allows easy addition of a wme whose value is an integer.

Parameters:
-> szId   the identifier on which the wme should be added
-> szAttr   the attribute of the wme. This value may or may not start with a '^'. If a new identifier is requested, this argument should be "*"
-> value   the value of the wme. This is an integer
-> accept   TRUE if the wme should receive an acceptable preference
<- new_wme   a pointer to a psoar_wme structure which is set to point to the new wme during the execution of this function

Returns:
a timetag

See also:
soar_cAddWme

void soar_cAddOutputFunction ( agent * a,
soar_callback_fn f,
soar_callback_data cb_data,
soar_callback_free_fn free_fn,
char * output_link_name )
 

soar_cAddOutputFunction -- Similar to soar_cAddInputFunction(), but adds a function which is called durnig each output phase.

This function is really just a wrapper for the more general soar_cAddCallback() using the OUTPUT_PHASE_CALLBACK specifier which the important expection that it also checks to ensure that the output_link_name (i.e. the registration name) is unique. This registration /must/ correspond to the symbol used to represet the output-link (e.g. I3)

Parameters:
-> a   the agent which will utilize the output function
-> f   the function to be called during the output phase
-> cb_data   a pointer to a data structure known at the time of registration, which will be passed to the callback function when it is invoked (e.g. a filehandle)
-> free_fn   a function to free the cb_data
-> name   a registeration name (must correspond to the output-link's symbol)

unsigned long soar_cAddWme ( char * szId,
char * szAttr,
char * szValue,
bool accept,
psoar_wme * new_wme )
 

soar_cAddWme -- Add a working memory element to the current agent's working memory.

Parameters:
-> szId   the identifier on which the wme should be added
-> szAttr   the attribute of the wme. This value may or may not start with a '^'. If a new identifier is requested, this argument should be "*"
-> szValue the value of the wme. Use *   to indicate that a new identifier should be used as the wme's value
-> accept   TRUE if the wme should receive an acceptable preference
<- new_wme   a pointer to a psoar_wme structure which is set to point to the new wme during the execution of this function

Returns:
An interger value with the following semantics:
Return values:
timetag   Success (an integer > 0)
-1   Fail, invalid ID
-2   Fail, invalid Attribute
-3   Fail, invalid value
-4   Fail, unspecified
Side Effects:
new_wme points to the wme which has just been added into the agent's memory

int soar_cAttributePreferencesMode ( int mode )
 

soar_cAttributePreferencesMode -- Determine how preferences for non-context slots should be handled.

Parameters:
-> mode   either 0,1 or 2
  • 0 - Handle the normal (Soar 6) way
  • 1 - Handle the normal (Soar 6) way but warn when preferences other than + or - are used for non-context slots
  • 2 - Warn when preferences other than + or - are found and ingore their semantics. NOTE: this is the only available mode when using Soar8 (operand2)
Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, invalid mode ( < 0 or > 2 )
-2   Fail, cannot switch modes in Soar8

SOAR_CALLBACK_TYPE soar_cCallbackNameToEnum ( char * name,
bool monitor_only )
 

soar_cCallbackNameToEnum -- Return the enumerated type (the callback type) given an event name.

Parameters:
-> name   the name of the callback type
-> monitor_only   TRUE if only monitorable call backs should be searched. FALSE otherwise

Returns:
the correct callback value, or NO_CALLBACK

void soar_cCreateAgent ( char * agent_name )
 

soar_cCreateAgent -- Create a new soar agent with the specified name.

Parameters:
-> name   the name of the new agent

Returns:
Nothing
Side Effects:
Modifies the global agent list

void soar_cDestroyAgentByAddress ( psoar_agent delete_agent )
 

soar_cDestroyAgentByAddress -- Destroy an agent, given a pointer to it.

Parameters:
-> delete_agent   a pointer to the agent to destroy
Side Effects:
Note: this is probably too drastic aborts with fatal error if the specified agent does not exist in the global data structure (e.g. it has already been deleted)

int soar_cDestroyAgentById ( int agent_id )
 

soar_cDestroyAgentById -- Destroy an agent, given its unique id.

There is a one to one correspondence between agents and ids. Ids are assigned when an agent is created, in increasing (but cyclical) order. The id of a particular agent can be retrieved using soar_cGetIdForAgentByName(). Although slightly less efficient than using a pointer to the psoar_agent structure itself, the agent id gives increased security by encapsulating all the sensitive agent data from the user of the api.

Parameters:
-> agent_id   the agent's unique identifier

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, no such id
Side Effects:
An agent is destroyed and removed from the agent list The current agent may also be changed

See also:
soar_cGetIdForAgentByName

int soar_cDestroyAgentByName ( char * name )
 

soar_cDestroyAgentByName -- Destroy an agent, given its name.

Parameters:
-> name   the name of the agent to be destroyed

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, ambigous name
-2   Fail, no such agent
Side Effects:
An agent may be destroyed and removed from the agent list The current agent may also be changed

int soar_cDestroyAllAgentsWithName ( char * name )
 

soar_cDestroyAllAgentsWithName -- Destroy a set of agents, given a name.

Parameters:
-> name   the name of the agent to be destroyed

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, no such agents
Side Effects:
One or more agents may be destroyed and removed from the agent list. The current agent may also be changed

void soar_cExciseAllProductions ( void )
 

soar_cExciseAllProductions -- Remove all productions from the agents memory and ReInitialize the agent.

Side Effects:
Production memory is emptied

void soar_cExciseAllProductionsOfType ( byte type )
 

soar_cExciseAllProductionsOfType -- Remove all productions of a specific type from the agents memory and ReInitialize the agent.

Parameters:
-> type   One of:
  • DEFAULT_PRODUCTION_TYPE
  • CHUNK_PRODUCTION_TYPE
  • JUSTIFICATION_PRODUCTION_TYPE
  • USER_PRODUCTION_TYPE
Side Effects:
Production memory is modified

void soar_cExciseAllTaskProductions ( void )
 

soar_cExciseAllTaskProductions -- Remove all but default productions from the agents memory and ReInitialize the agent.

Side Effects:
Production memory is modified

int soar_cExciseProductionByName ( char * name )
 

soar_cExciseProductionByName -- Remove the production with the specified name.

Parameters:
-> name   the name of the production to be removed

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, production not found
Side Effects:
A production is removed from long term memory.

psoar_agent soar_cGetAgentByName ( char * name )
 

soar_cGetAgentByName -- Get a pointer to a soar agent.

This function locates a specific agent, and returns a generic pointer to it. Note that the current agent is not affected.

Parameters:
-> name   the name of the agent to look for.

Returns:
a psoar_agent pointer which references the specified agent or NULL if no such agent is found.

int soar_cGetAgentId ( psoar_agent a )
 

soar_cGetAgentId -- * An accessor function for a psoar_agent.

Returns a string containing the agent's unique integer ID. This integer is in the range 0 ... MAX_SIMULTANEOUS_AGENTS and no two agents have the same identifier.

Parameters:
-> a   a psoar_agent

Returns:
the unique integer identifier of the specified agent

char * soar_cGetAgentInputLinkId ( psoar_agent a,
char * buff )
 

soar_cGetAgentInputLinkId -- * An accessor function for a psoar_agent.

Returns a string containing the ID of agent's input-link. Note that memory to hold the string has been allocated within this function and must later be freed by the user when it is no longer in use.

Parameters:
-> w   a psoar_agent
<- buff   a buffer to hold the result, or NULL

Returns:
a string representation of the input-link identifier or NULL if the input-link does not exist Note that an id is guarenteed to be an alphanumeric string in which the first character is an uppercase letter and the remaining characters are digits
Side Effects:
Unless buff is non-NULL, memory is allocated for the returned value. This should be freed by the caller when its use is accomplished.

char * soar_cGetAgentOutputLinkId ( psoar_agent a,
char * buff )
 

soar_cGetAgentOutputLinkId -- * An accessor function for a psoar_agent.

Returns a string containing the ID of agent's output-link. Note that memory to hold the string has been allocated within this function and must later be freed by the user when it is no longer in use.

Parameters:
-> a   a psoar_agent
<- buff   a buffer to hold the result, or NULL

Returns:
a string representation of the ouput-link identifier or NULL if the output-link does not exist Note that an id is guarenteed to be an alphanumeric string in which the first character is an uppercase letter and the remaining characters are digits
Side Effects:
Unless buff is non-NULL, memory is allocated for the returned value. This should be freed by the caller when its use is accomplished.

psoar_agent soar_cGetCurrentAgent ( )
 

soar_cGetCurrentAgent -- Get the 'current agent'.

Returns:
the psoar_agent structure for the agent which is currently affected by API function calls

int soar_cGetIdForAgentByName ( char * name )
 

soar_cGetIdForAgentByName -- Get the unique id of a particular agent.

This function locates a specific agent, and returns its unique identifier.

Parameters:
-> name   the name of the agent to look for.

Returns:
a unique id or -1 if no agent is found.

char * soar_cGetWmeAttr ( psoar_wme w,
char * buff )
 

soar_cGetWmeAttr -- An accessor function for a psoar_wme.

Returns a string containing the Attribute of the specified wme. Note that memory to hold the string has been allocated within this function and must later be freed by the user when it is no longer in use.

Parameters:
-> w   a psoar_wme
<- buff   a buffer to hold the result, or NULL

Returns:
a string
Side Effects:
Unless buff is non-NULL, memory is allocated for the returned value. This should be freed by the caller when its use is accomplished.

See also:
soar_cWmeGetId , soar_cWmeGetValue

char * soar_cGetWmeId ( psoar_wme w,
char * buff )
 

soar_cGetWmeId -- An accessor function for a psoar_wme.

Returns a string containing the ID of the specified wme. Note that memory to hold the string has been allocated within this function and must later be freed by the user when it is no longer in use.

Parameters:
-> w   a psoar_wme
<- buff   a buffer to hold the result, or NULL

Returns:
a string the id of the wme. Note that an id is guarenteed to be an alphanumeric string in which the first character is an uppercase letter and the remaining characters are digits
Side Effects:
Unless buff is non-NULL, memory is allocated for the returned value. This should be freed by the caller when its use is accomplished.

See also:
soar_cWmeGetAttr , soar_cWmeGetValue

unsigned long soar_cGetWmeTimetag ( psoar_wme w )
 

soar_cGetWmeTimetag -- An accessor function for a psoar_wme.

Parameters:
-> w   a psoar_wme

Returns:
The timetag corresponding to the wme.

char * soar_cGetWmeValue ( psoar_wme w,
char * buff )
 

soar_cGetWmeValue -- An accessor function for a psoar_wme.

Returns a string containing the Value of the specified wme. Note that memory to hold the string has been allocated within this function and must later be freed by the user when it is no longer in use.

Parameters:
-> w   a psoar_wme
<- buff   a buffer to hold the result, or NULL

Returns:
a string
Side Effects:
Unless buff is non-NULL, memory is allocated for the returned value. This should be freed by the caller when its use is accomplished.

See also:
soar_cWmeGetId , soar_cWmeGetAttr

void soar_cInitAgentIterator ( soar_apiAgentIterator * ai )
 

soar_cInitAgentIterator -- Fill in a soar_apiAgentIterator structure for first use.

This structure is used to facilitate looping through all soar agents beginning with the currently selected agent.

Parameters:
<- ai   a pointer to a soar_apiAgentIterator structure
Side Effects:
The ai structure is filled in such as described below: ai->more -- TRUE iff there are more agents to iterate through

void soar_cInitializeDCHistogram ( int size,
int freq )
 

soar_cInitializeDCHistogram -- Prepare an array of time structures which will be used to store the time executing a sets of decision cycles.

Note that a a seperate timer is used for this. This may be useful when the resolution of the timers is too rough to be useful at the level of a single decision cycle

Parameters:
-> size   the number of slots (timeslices) in the array
-> freq   the number of decision cycles which are encapsulated by a slot in the array
Side Effects:
data will be stored in the histogram.

void soar_cInitializeKTHistogram ( int size )
 

soar_cInitializeKTHistogram -- Prepare an array of time structures which will be used to store the kernel time executing a each successive decision cycle.

Unlike the DCHistogram, this one uses the kernel timer, and updates onces per decision cycle

Parameters:
-> size   the number of slots (timeslices) in the array this is also the number of decision cycles to be timed
Side Effects:
Memory is allocated for the KTHistogram

void soar_cInitializeSoar ( void )
 

soar_cInitializeSoar -- Initialize Soar for the very first time.

This should be the first Soar related function called, and it should only be called once.

void soar_cListAllCallbacks ( soar_callback_agent a,
bool monitorable_only )
 

soar_cListAllCallbacks -- List the callbacks registered to the agent.

Parameters:
-> agent   the specified soar agent
-> monitorable   TRUE if only monitorable callbacks should be listed FALSE if all callbacks (including PRINT and LOG) should be listed.

void soar_cListAllCallbacksForEvent ( soar_callback_agent agent,
SOAR_CALLBACK_TYPE type )
 

soar_cListAllCallbacksForEvent -- List the all callbacks of a specific type registered to the agent.

Parameters:
-> agent   the specified soar agent
-> type   the specified callback type (stack)

int soar_cLoadReteNet ( char * filename )
 

soar_cLoadReteNet -- Load a Rete Network into the agent from a specified file.

Parameters:
-> filename   the file to be loaded

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, invalid (no) filename specified
-2   Fail, working memory is not empty
-3   Fail, production Memory is not empty
-4   Fail, unable to open specified file

int soar_cMultiAttributes ( char * attr,
int value )
 

soar_cMultiAttributes -- Modify the multi-attributes setting.

Parameters:
-> attr   the attribute to be set
-> value   its new matching priority ( must be > 1 )

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, specified attribute is not a symbolic constant
-2   Fail, value was <= 1

void soar_cPopCallback ( soar_callback_agent a,
SOAR_CALLBACK_TYPE type )
 

soar_cPopCallback -- Pops off the last callback to be added to the specified callback stack.

This function is used to remove temporary callbacks added with soar_cPushCallback().

Parameters:
-> a   the agent to which the function was registered
-> type   the destination stack for this callback function
Side Effects:
removes the callback which was added to the specified stack most recently.

void soar_cPushCallback ( soar_callback_agent a,
SOAR_CALLBACK_TYPE type,
soar_callback_fn fn,
soar_callback_data data,
soar_callback_free_fn free_fn )
 

soar_cPushCallback -- Push a callback onto the specified callback stack.

This is designed for callbacks that will only be regisstered temporarily becuase they do not have a registration name. As a result, the only way to remove these callbacks is using the soar_cPopCallback() function which can be problematic if other callbacks have been added in the meantime.

Parameters:
-> a   the agent which will utilize the function
-> type   the destination stack for this callback function
-> fn   the function to be called
-> cb_data   a pointer to a data structure known at the time of registration, which will be passed to the callback function when it is invoked (e.g. a filehandle)
-> free_fn   a function to free the cb_data

void soar_cQuit ( void )
 

soar_cQuit -- Quit Soar.

This function should be called when Soar (or the application it is embedded within is just about to exit).

Side Effects:
Pops the top function from the Log Callback stack (in an effort to stop logging)

int soar_cReInitSoar ( void )
 

soar_cReInitSoar -- Reset Soar (and agents) to the initial state.

This function reinitializes Soar by clearing the working memory of all agents and preparing them for a "new" execution. In essence, they are put back into the same state as if Soar were just started, and the agents were newly loaded.

Returns:
Error values that may be bitwise ORed
Return values:
0   Success
0x1   Error reseting id counters (memory leak)
0x2   Error reseting wme timetags (memory leak)

void soar_cRemoveAllCallbacksForEvent ( soar_callback_agent agent,
SOAR_CALLBACK_TYPE type )
 

soar_cRemoveAllCallbacksForEvent -- Remove all of the callbacks of a specified type which have been registered to the specified agent.

Parameters:
-> agent   the specified soar agent
-> type   the specified callback type (stack)

void soar_cRemoveAllMonitorableCallbacks ( soar_callback_agent agent )
 

soar_cRemoveAllMonitorableCallbacks -- Remove all of the callbacks (other than PRINT or LOG callbacks) registered to the specified agent.

Parameters:
-> agent   the specified soar agent

void soar_cRemoveCallback ( soar_callback_agent a,
SOAR_CALLBACK_TYPE type,
soar_callback_id id )
 

soar_cRemoveCallback -- Remove the callback from the specified callback stack which has the specified id.

Parameters:
-> a   the agent to which the function was registered
-> type   the destination stack for this callback function
-> id   the registration name
Side Effects:
removes specified the callback

void soar_cRemoveGlobalCallback ( SOAR_GLOBAL_CALLBACK_TYPE type,
soar_callback_id id )
 

soar_cRemoveGlobalCallback -- Remove a callback onto the specified /global/ callback stack.

Parameters:
-> type   the global destination stack for this callback function
-> id   the registeration name

Returns:

void soar_cRemoveInputFunction ( agent * a,
char * name )
 

soar_cRemoveInputFunction -- Remove an input function with the specified name.

Since the name is used to do the removal, it is a good idea if these functions have unique names to begin with!

Parameters:
-> a   the agent from which the input function should be removed
-> name   the registeration name of the function

See also:
soar_cRemoveCallback

void soar_cRemoveOutputFunction ( agent * a,
char * name )
 

soar_cRemoveOutputFunction -- Remove an output function with the specified name.

It is critical that the specified name corresponds to the output-link's symbol.

Parameters:
-> a   the agent from which the output function should be removed
-> name   the registeration name (must correspond to the output-link's symbol)

int soar_cRemoveWme ( psoar_wme wme )
 

soar_cRemoveWme -- Remove a working memory element.

This is not as safe as removing a wme using its timetag. Typically this should be called only during the input phase.

Parameters:
-> psoar_wme   the wme which should be removed. This object is typically obtained using one of the AddWme functions.

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail
Side Effects:
A wme is removed from memory.

int soar_cRemoveWmeUsingTimetag ( int num )
 

soar_cRemoveWmeUsingTimetag -- Remove a working memory element, given its timetag.

Parameters:
-> num   the timetag of the wme which should be removed

Returns:
An interger value with the following semantics
Return values:
0   Success
-1   Fail, timetag does not exist
-2   Fail, unspecified

int soar_cRun ( long n,
bool all,
enum go_type_enum type,
enum soar_apiSlotType slot )
 

soar_cRun -- Run the current agent, or all agents for a specified period ...

Parameters:
-> n   the number of cycles to be run ( -1 --> forever )
-> all   TRUE iff all agents should be run.
-> type   the type of cycle: GO_PHASE, GO_ELABORATION, GO_DECISION GO_STATE, GO_OPERATOR, GO_OUTPUT, GO_SLOT
-> slot   the slot type:
  • if type == \c GO_SLOT, use one of: STATE_SLOT, OPERATOR_SLOT, SUPERSTATE_SLOT, SUPEROPERATOR_SLOT, SUPERSUPERSTATE_SLOT, SUPERSUPEROPERATOR_SLOT
  • otherwise, use: NO_SLOT
Returns:
An integer value, with the following semantics
Return values:
0   Success
-1   Fail, slot specifier is incompatible w/ type specifier
-2   Fail, invalid slot specifier
-3   Fail, no state or operator at the specified level

int soar_cSaveReteNet ( char * filename )
 

soar_cSaveReteNet -- Save a Rete Network from the agent into a specified file.

Parameters:
-> filename   the file to be loaded

Returns:
An integer value with the following semantics
Return values:
0   Success
-1   Fail, justifications exist
-2   Fail, unable to open file

int soar_cSetChunkNameCount ( long count )
 

soar_cSetChunkNameCount -- Set the chunk count.

This must be greater than zero, less than max chunks and greater than the current chunk count.

Parameters:
-> count   the new value for the current chunk count

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, specified count is < 0
-2   Fail, specified count is > max chunks
-3   Fail, specified count is < current chunk count
Side Effects:
Future chunks will have a count value relative to that which was set here

void soar_cSetChunkNameLong ( bool truly )
 

soar_cSetChunkNameLong -- Set long or short chunk names according to the specified parameter.

Parameters:
-> truly   TRUE if the chunk name should be long FALSE if it should be short
Side Effects:
Modifies the chunk name

int soar_cSetChunkNamePrefix ( char * prefix )
 

soar_cSetChunkNamePrefix -- Set the chunk name prefix.

This is a string which is used to descriminate chunks from user productions.

Parameters:
-> prefix   the prefix which should begin a chunk's name

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, desired prefix is not allowed

void soar_cSetCurrentAgent ( psoar_agent agent )
 

soar_cSetCurrentAgent -- Set the 'current agent'.

This function changes the agent that will be affected by subsequent API function calls

Parameters:
-> agent   the psoar_agent structure of the agent which should receive the focus

bool soar_cSetCurrentAgentByName ( char * name )
 

soar_cSetCurrentAgentByName -- Set the 'current agent'.

This function changes the agent that will be affected by subsequent API function calls

Parameters:
-> name   the name of the agent come into focus

Returns:
TRUE iff the operation was successful

void soar_cSetLearning ( enum soar_apiLearningSetting setting )
 

soar_cSetLearning -- Adjust the learning settings.

Parameters:
-> setting   one of:
  • ON
  • OFF
  • ONLY
  • EXCEPT
  • ALL_LEVELS
  • BOTTOM_UP

int soar_cSetOperand2 ( bool turnOn )
 

soar_cSetOperand2 -- Toggles from Soar7 to Soar8 execution mode.

Parameters:
-> turnOn   TRUE to run is Soar8 mode FLASE to run is Soar7 mode

Returns:
An integer value with the following semantics:
Return values:
0   Success
-1   Fail, working memory is not empty
-2   Fail, production memory is not empty

void soar_cSetSystemParameter ( int param,
long value )
 

soar_cSetSystemParameter -- Set a system parameter for the current agent.

Parameters:
-> param   the parameter to be set
-> value   the new value

void soar_cSetWaitSNC ( bool wait )
 

soar_cSetWaitSNC -- Determine whether Soar should generate explict state-no-change impasses.

Parameters:
-> wait   TRUE if Soar should wait FALSE if Soar should generate SNCs

bool soar_cStepAgentIterator ( soar_apiAgentIterator * ai )
 

soar_cStepAgentIterator -- Increment an agent iterator srtucture.

This function increments the agent iterator by one, and signals whether more agents still need to be iterated through. Its results are based on the state of the specified agentIterator.

Parameters:
<-> ai   a pointer to a previously filled in soar_apiAgentIterator structure

Returns:
TRUE if there are more agents to iterate through
Side Effects:
the currently selected agent is changed, if there are more agents to iterate through before returning to the agent which was selected at the time soar_cInitAgentIterator() was called, the "more" slot in the ai structure is set to TRUE.

void soar_cStopCurrentAgent ( char * reason )
 

soar_cStopCurrentAgent -- Stops the current agent.

Parameters:
-> reason   a string indicating why the agent is being stopped prematurely.

void soar_cTestAllMonitorableCallbacks ( soar_callback_agent the_agent )
 

soar_cTestAllMonitorableCallbacks -- Register a simple print function on all the monitorable callback stacks (all but PRINT and LOG).

This is helpful to ensure that callbacks are getting issued as expected.

Parameters:
-> agent   the specified soar agent


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