soar_core_api.h File Reference

The Low Level interface to Soar. More...

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
void	soar_cInitializeSoar (void)
	soar_cInitializeSoar -- Initialize Soar for the very first time.
int	soar_cReInitSoar (void)
	soar_cReInitSoar -- Reset Soar (and agents) to the initial state.
void	soar_cCreateAgent (const char *agent_name)
	soar_cCreateAgent -- Create a new soar agent with the specified name.
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 ...
void	soar_cStopAllAgents (void)
	soar_cStopAllAgents -- Stops all agents.
void	soar_cStopCurrentAgent (const char *reason)
	soar_cStopCurrentAgent -- Stops the current agent.
int	soar_cDestroyAgentByName (const char *name)
	soar_cDestroyAgentByName -- Destroy an agent, given its name
int	soar_cDestroyAllAgentsWithName (char *name)
	soar_cDestroyAllAgentsWithName -- Destroy a set of agents, given a name.
void	soar_cDestroyAgentByAddress (psoar_agent delete_agent)
	soar_cDestroyAgentByAddress -- Destroy an agent, given a pointer to it.
int	soar_cDestroyAgentById (int agent_id)
	soar_cDestroyAgentById -- Destroy an agent, given its unique id.
void	soar_cQuit (void)
	soar_cQuit -- Quit Soar.
Modifying Agent Memory
This section deals with two areas of the agent: Production Memory Working Memory
int	soar_cLoadReteNet (const char *filename)
	soar_cLoadReteNet -- Load a Rete Network into the agent from a specified file.
int	soar_cSaveReteNet (const char *filename)
	soar_cSaveReteNet -- Save a Rete Network from the agent into a specified file.
long	soar_cAddWme (const char *szId, const char *szAttr, const char *szValue, bool accept, psoar_wme *new_wme)
	soar_cAddWme -- Add a working memory element to the current agent's working memory.
int	soar_cRemoveWmeUsingTimetag (int num)
	soar_cRemoveWmeUsingTimetag -- Remove a working memory element, given its timetag.
int	soar_cRemoveWme (psoar_wme wme)
	soar_cRemoveWme -- Remove a working memory element.
void	soar_cExciseAllProductions (void)
	soar_cExciseAllProductions -- Remove all productions from the agents memory and ReInitialize the agent.
void	soar_cExciseAllTaskProductions (void)
	soar_cExciseAllTaskProductions -- Remove all but default productions from the agents memory and ReInitialize the agent.
void	soar_cExciseAllProductionsOfType (byte type)
	soar_cExciseAllProductionsOfType -- Remove all productions of a specific type from the agents memory and ReInitialize the agent.
int	soar_cExciseProductionByName (const char *name)
	soar_cExciseProductionByName -- Remove the production with the specified name.
Modifying the Agents Parameters
void	soar_cSetSystemParameter (int param, long value)
	soar_cSetSystemParameter -- Set a system parameter for the current agent
double	soar_cDetermineTimerResolution (double *min, double *max)
	soar_cDetermineTimerResolution -- Determine the resolution of the system timers Soar uses to gather statistics.
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.
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.
void	soar_cSetChunkNameLong (bool truly)
	soar_cSetChunkNameLong -- Set long or short chunk names according to the specified parameter
int	soar_cSetChunkNameCount (long count)
	soar_cSetChunkNameCount -- Set the chunk count.
int	soar_cSetChunkNamePrefix (const char *prefix)
	soar_cSetChunkNamePrefix -- Set the chunk name prefix.
void	soar_cSetLearning (enum soar_apiLearningSetting setting)
	soar_cSetLearning -- Adjust the learning settings.
int	soar_cSetOperand2 (bool turnOn)
	soar_cSetOperand2 -- Toggles from Soar7 to Soar8 execution mode.
void	soar_cSetWaitSNC (bool wait)
	soar_cSetWaitSNC -- Determine whether Soar should generate explict state-no-change impasses.
int	soar_cMultiAttributes (const char *attr, int value)
	soar_cMultiAttributes -- Modify the multi-attributes setting.
int	soar_cAttributePreferencesMode (int mode)
	soar_cAttributePreferencesMode -- Determine how preferences for non-context slots should be handled.
Callbacks
void	soar_cAddInputFunction (agent *a, soar_callback_fn f, soar_callback_data cb_data, soar_callback_free_fn free_fn, const char *name)
	soar_cAddInputFunction -- Adds an input function to the specified agent.
void	soar_cRemoveInputFunction (agent *a, const char *name)
	soar_cRemoveInputFunction -- Remove an input function with the specified name.
void	soar_cAddOutputFunction (agent *a, soar_callback_fn f, soar_callback_data cb_data, soar_callback_free_fn free_fn, const char *output_link_name)
	soar_cAddOutputFunction -- Similar to soar_cAddInputFunction(), but adds a function which is called durnig each output phase.
void	soar_cRemoveOutputFunction (agent *a, const char *name)
	soar_cRemoveOutputFunction -- Remove an output function with the specified name.
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.
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.
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.
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.
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.
void	soar_cRemoveGlobalCallback (SOAR_GLOBAL_CALLBACK_TYPE type, soar_callback_id id)
	soar_cRemoveGlobalCallback -- Remove a callback onto the specified /global/ callback stack.
void	soar_cListAllCallbacks (soar_callback_agent a, bool monitorable_only)
	soar_cListAllCallbacks -- List the callbacks registered to the agent
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
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
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
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).
SOAR_CALLBACK_TYPE	soar_cCallbackNameToEnum (const char *name, bool monitor_only)
	soar_cCallbackNameToEnum -- Return the enumerated type (the callback type) given an event name.
void	soar_cDefaultAskCallback (soar_callback_agent the_agent, soar_callback_data data, soar_call_data call_data)
Etc
Miscellanous controls, including: Multi Agent Controls Accessors for Encapsulated Data
char *	soar_cGetWmeId (psoar_wme w, char *buff, size_t buff_size)
	soar_cGetWmeId -- An accessor function for a psoar_wme.
char *	soar_cGetWmeAttr (psoar_wme w, char *buff, size_t buff_size)
	soar_cGetWmeAttr -- An accessor function for a psoar_wme.
char *	soar_cGetWmeValue (psoar_wme w, char *buff, size_t buff_size)
	soar_cGetWmeValue -- An accessor function for a psoar_wme.
unsigned long	soar_cGetWmeTimetag (psoar_wme w)
	soar_cGetWmeTimetag -- An accessor function for a psoar_wme.
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.
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
void	soar_cInitAgentIterator (soar_apiAgentIterator *ai)
	soar_cInitAgentIterator -- Fill in a soar_apiAgentIterator structure for first use.
bool	soar_cStepAgentIterator (soar_apiAgentIterator *ai)
	soar_cStepAgentIterator -- Increment an agent iterator srtucture.
psoar_agent	soar_cGetAgentByName (char *name)
	soar_cGetAgentByName -- Get a pointer to a soar agent
int	soar_cGetIdForAgentByName (char *name)
	soar_cGetIdForAgentByName -- Get the unique id of a particular agent
bool	soar_cSetCurrentAgentByName (char *name)
	soar_cSetCurrentAgentByName -- Set the 'current agent'.
void	soar_cSetCurrentAgent (psoar_agent agent)
	soar_cSetCurrentAgent -- Set the 'current agent'.
psoar_agent	soar_cGetCurrentAgent ()
	soar_cGetCurrentAgent -- Get the 'current agent'.
char *	soar_cGetAgentInputLinkId (psoar_agent a, char *buff, size_t buff_size)
	soar_cGetAgentInputLinkId -- * An accessor function for a psoar_agent.
char *	soar_cGetAgentOutputLinkId (psoar_agent a, char *buff, size_t buff_size)
	soar_cGetAgentOutputLinkId -- * An accessor function for a psoar_agent.
int	soar_cGetAgentId (psoar_agent a)
	soar_cGetAgentId -- * An accessor function for a psoar_agent.
void	print (char *format,...)
	print -- Print a given string using the agent's current print function
void	print ()

---

Detailed Description

The Low Level interface to Soar.

Copyright 1995-2003 Carnegie Mellon University, University of Michigan, University of Southern California/Information Sciences Institute. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE SOAR CONSORTIUM ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE SOAR CONSORTIUM OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Carnegie Mellon University, the University of Michigan, the University of Southern California/Information Sciences Institute, or the Soar consortium. =======================================================================

Id

soar_core_api.h,v 1.6 2003/11/10 17:36:07 toolshed 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:

• -> the argument is read (but not written to) by the function
• <- the argument is written to by the function (the function may check to see if its value is NULL)
• <-> the argument is expected to contain a valid entry which is first read by the function, and then modified before the function returns

Definition in file soar_core_api.h.

---

Function Documentation

void print (   )

Referenced by abort_with_fatal_error(), abs_rhs_function_code(), add_input_wme(), add_named_superstate_attribute_to_grounds(), add_preference_to_tm(), add_rhs_function(), atan2_rhs_function_code(), backtrace_through_instantiation(), calculate_compile_time_o_support(), calculate_support_for_instantiation_preferences(), capitalize_symbol_rhs_function_code(), check_context_slot_decisions(), chunk_instantiation(), collect_root_variables(), compute_heading_rhs_function_code(), compute_range_rhs_function_code(), cos_rhs_function_code(), create_instantiation(), deallocate_inst_members_to_be_rewritten(), deallocate_instantiation(), deallocate_preference(), decision_consistent_with_current_preferences(), determine_highest_active_production_level_in_stack_apply(), determine_highest_active_production_level_in_stack_propose(), determine_type_of_constituent_string(), div_rhs_function_code(), do_input_cycle(), do_one_top_level_phase(), do_output_cycle(), do_print_for_production_name(), dont_learn_rhs_function_code(), examine_memory_pool(), excise_production(), explain_list_chunks(), explain_trace(), explain_trace_chunk(), find_chunk(), find_goal_for_match_set_change_retraction(), find_ground(), find_impasse_wme(), float_rhs_function_code(), force_learn_rhs_function_code(), fp_divide_rhs_function_code(), generate_chunk_name_sym_constant(), get_all_node_count_stats(), get_io_symbol_from_tio_constituent_string(), get_item_in_pool_block(), get_next_char(), goal_stack_consistent_through_goal(), highest_active_goal_apply(), highest_active_goal_propose(), ifeq_rhs_function_code(), inform_output_module_of_wm_changes(), initialize_consistency_calculations_for_new_decision(), int_rhs_function_code(), lex_quote(), lex_unknown(), lex_vbar(), load_rete_net(), make_preference(), make_production(), minus_rhs_function_code(), mod_rhs_function_code(), neatly_print_wme_augmentation_of_id(), p_node_left_addition(), p_node_left_removal(), parse_attr_value_make(), parse_attr_value_tests(), parse_cond(), parse_disjunction_test(), parse_format_string(), parse_function_call_after_lparen(), parse_head_of_conds_for_one_id(), parse_memory_stats(), parse_preferences_soar8_non_operator(), parse_production(), parse_relational_test(), parse_rete_stats(), parse_rhs_action(), parse_rhs_value(), parse_system_stats(), post_link_addition(), post_link_removal(), ppmi_aux(), print(), print_all_identifiers_in_block(), print_assertion(), print_augs_of_id(), print_candidates(), print_consed_list_of_condition_wmes(), print_consed_list_of_conditions(), print_current_learn_settings(), print_current_watch_settings(), print_item_info_header(), print_location_of_most_recent_lexeme(), print_match_set(), print_multi_attribute_symbols(), print_node_count_statistics(), print_null_activation_stats(), print_partial_match_information(), print_preference_and_source(), print_retraction(), print_saved_test_list(), print_startup_banner(), print_trace_format_list(), print_tracing_rule(), print_whole_token(), printTimingInfo(), process_o_rejects_and_deallocate_them(), re_fill_in_instantiation_stuff_for_modified_lhs(), read_identifier_or_context_variable(), read_pattern_and_get_matching_productions(), read_pattern_and_get_matching_wmes(), read_pattern_component(), read_rhs_pattern_and_get_matching_productions(), remove_input_wme(), remove_operator_if_necessary(), remove_preference_from_tm(), reorder_action_list(), reorder_lhs(), reorder_simplified_conditions(), replay_input_wme(), reset_id_counters(), reset_wme_timetags(), restore_and_deallocate_saved_tests(), retract_instantiation(), round_off_air_rhs_function_code(), round_off_heading_air_rhs_function_code(), run_preference_semantics(), save_rete_net(), second_stage_chunk_instantiation(), set_sysparam(), sin_rhs_function_code(), soar_cAddOutputFunction(), soar_CaptureInput(), soar_cDefaultAskCallback(), soar_ChunkNameFormat(), soar_cInitAgentIterator(), soar_cListAllCallbacks(), soar_cListAllCallbacksForEvent(), soar_cLoadReteNet(), soar_cSaveReteNet(), soar_cTestCallback(), soar_default_create_agent_procedure(), soar_ecAddWmeFilter(), soar_ecBeginTracingProductions(), soar_ecBuildInfo(), soar_ecExcludedBuildInfo(), soar_ecExplainChunkConditionList(), soar_ecGDSPrint(), soar_ecListWmeFilters(), soar_ecPrintAllProductionsOfType(), soar_ecPrintAllProductionsWithInterruptSetting(), soar_ecPrintAttentionLapseSettings(), soar_ecPrintDCHistogram(), soar_ecPrintFiringsForProduction(), soar_ecPrintKTHistogram(), soar_ecPrintMemories(), soar_ecPrintMemoryPoolStatistics(), soar_ecPrintMemoryStatistics(), soar_ecPrintPreferences(), soar_ecPrintReteStatistics(), soar_ecPrintSystemStatistics(), soar_ecPrintTopProductionFirings(), soar_ecReplayInput(), soar_ecResetWmeFilters(), soar_ecSp(), soar_ecStopTracingProductions(), soar_exPrintMemoryPoolStatistics(), soar_Interrupt(), soar_Memories(), soar_Operand2(), soar_Print(), soar_ProductionFind(), soar_Verbose(), soar_WaitSNC(), soar_Watch(), sqrt_rhs_function_code(), start_log_file(), stop_lex_from_file(), stop_log_file(), stop_timer(), test_timers(), and user_select_rhsfun().

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. Definition at line 211 of file print.c.

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 Definition at line 1722 of file soar_core_api.c. References agent, callback_struct::data, callback_struct::free_function, callback_struct::function, callback_struct::id, soar_callback, soar_callback_agent, soar_callback_data, soar_callback_fn, soar_callback_free_fn, and soar_callback_id. Referenced by soar_cAddInputFunction(), soar_cAddOutputFunction(), and soar_cTestAllMonitorableCallbacks().

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 Definition at line 2081 of file soar_core_api.c. References psoar_wme, and soar_cAddWme().

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 Definition at line 1838 of file soar_core_api.c. References cons, callback_struct::data, cons_struct::first, callback_struct::free_function, callback_struct::function, callback_struct::id, cons_struct::rest, soar_callback, soar_callback_data, soar_callback_fn, soar_callback_free_fn, soar_callback_id, and soar_global_callbacks.

void soar_cAddInputFunction (  agent *  a, soar_callback_fn  f, soar_callback_data  cb_data, soar_callback_free_fn  free_fn, const 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 Definition at line 1610 of file soar_core_api.c. References agent, INPUT_PHASE_CALLBACK, soar_cAddCallback(), soar_callback_data, soar_callback_fn, and soar_callback_free_fn. Referenced by add_input_function(), and soar_ecReplayInput().

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 Definition at line 2070 of file soar_core_api.c. References psoar_wme, and soar_cAddWme().

void soar_cAddOutputFunction (  agent *  a, soar_callback_fn  f, soar_callback_data  cb_data, soar_callback_free_fn  free_fn, const 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) Definition at line 1639 of file soar_core_api.c. References agent, control_c_handler(), OUTPUT_PHASE_CALLBACK, print(), soar_cAddCallback(), soar_callback_data, soar_callback_fn, soar_callback_free_fn, and soar_exists_callback_id(). Referenced by add_output_function().

long soar_cAddWme (  const char *  szId, const char *  szAttr, const 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 Definition at line 770 of file soar_core_api.c. References ADD_WME, add_wme_to_wm(), sapiwme_st::attr, wme_struct::attr, capture_input_wme(), do_buffered_wm_and_ownership_changes(), FLOAT_CONSTANT_LEXEME, get_lexeme_from_string(), sapiwme_st::id, wme_struct::id, symbol_union::id, IDENTIFIER_LEXEME, INPUT_PHASE, identifier_struct::input_wmes, INT_CONSTANT_LEXEME, identifier_struct::level, make_float_constant(), make_int_constant(), make_new_identifier(), make_sym_constant(), make_wme(), psoar_wme, read_id_or_context_var_from_string(), read_identifier_or_context_variable(), SOAR_ERROR, soarapi_wme, start_timer(), stop_timer(), string_match(), SYM_CONSTANT_LEXEME, Symbol, wme_struct::timetag, sapiwme_st::timetag, sapiwme_st::value, wme_struct::value, VARIABLE_LEXEME, and wme. Referenced by replay_input_wme(), soar_AddWme(), soar_cAddFloatWme(), and soar_cAddIntWme().

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 Definition at line 1544 of file soar_core_api.c. Referenced by soar_AttributePreferencesMode().

SOAR_CALLBACK_TYPE soar_cCallbackNameToEnum (  const 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 Definition at line 1973 of file soar_core_api.c. References NO_CALLBACK, NUMBER_OF_CALLBACKS, soar_callback_names, and SOAR_CALLBACK_TYPE. Referenced by soar_callback_name_to_enum().

void soar_cCreateAgent (  const 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 Definition at line 290 of file soar_core_api.c. References GLB_CREATE_AGENT, soar_call_data, soar_default_create_agent_procedure(), soar_exists_global_callback(), and soar_invoke_global_callbacks(). Referenced by create_soar_agent(), and soar_CreateAgent().

void soar_cDefaultAskCallback (  soar_callback_agent  the_agent, soar_callback_data  data, soar_call_data  call_data )

Definition at line 2249 of file soar_core_api.c. References preference_struct::next_candidate, preference, print(), print_object_trace(), print_string_to_log_file_only(), set_sysparam(), soar_apiAskCallbackData, soar_call_data, soar_callback_agent, soar_callback_data, and preference_struct::value.

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) Definition at line 512 of file soar_core_api.c. References GLB_DESTROY_AGENT, psoar_agent, soar_call_data, soar_default_destroy_agent_procedure(), soar_exists_global_callback(), and soar_invoke_global_callbacks(). Referenced by destroy_soar_agent(), soar_cDestroyAgentById(), soar_cDestroyAgentByName(), and soar_cDestroyAllAgentsWithName().

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 Definition at line 534 of file soar_core_api.c. References agent, all_soar_agents, cons, cons_struct::first, psoar_agent, cons_struct::rest, and soar_cDestroyAgentByAddress().

int soar_cDestroyAgentByName (  const 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 Definition at line 449 of file soar_core_api.c. References agent, all_soar_agents, cons, cons_struct::first, psoar_agent, cons_struct::rest, soar_cDestroyAgentByAddress(), and string_match(). Referenced by soar_DestroyAgent().

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 Definition at line 482 of file soar_core_api.c. References agent, all_soar_agents, cons, cons_struct::first, psoar_agent, cons_struct::rest, soar_cDestroyAgentByAddress(), and string_match().

double soar_cDetermineTimerResolution (  double *  min, double *  max )

soar_cDetermineTimerResolution -- Determine the resolution of the system timers Soar uses to gather statistics. Parameters: <- min  if non NULL, the long pointed to by min is filled with the minimum timer interval encountered during the test or -1 if this value is belived to be corrupt. <- max  if non NULL, the long pointed to by min is filled with the maximum timer interval encountered during the test or -1 if this value is belived to be corrupt. Returns: An interger value with the following semantics: Return values: n  the minimum non-zero value (in microseconds) reported by the system timers during the test. -1  Fail Definition at line 1221 of file soar_core_api.c. References reset_timer(), start_timer(), stop_timer(), and timer_value(). Referenced by printTimingInfo().

void soar_cExciseAllProductions (  void   )

soar_cExciseAllProductions -- Remove all productions from the agents memory and ReInitialize the agent. Side Effects: Production memory is emptied Definition at line 1133 of file soar_core_api.c. References soar_cExciseAllProductionsOfType(), and soar_cReInitSoar(). Referenced by soar_Excise().

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 Definition at line 1172 of file soar_core_api.c. References byte, and excise_production(). Referenced by soar_cExciseAllProductions(), soar_cExciseAllTaskProductions(), and soar_Excise().

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 Definition at line 1154 of file soar_core_api.c. References soar_cExciseAllProductionsOfType(), and soar_cReInitSoar(). Referenced by soar_Excise().

int soar_cExciseProductionByName (  const 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. Definition at line 1188 of file soar_core_api.c. References excise_production(), name_to_production(), and production. Referenced by soar_Excise().

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. Definition at line 2130 of file soar_core_api.c. References agent, all_soar_agents, cons, cons_struct::first, psoar_agent, and cons_struct::rest. Referenced by create_soar_agent(), soar_cGetIdForAgentByName(), and soar_cSetCurrentAgentByName().

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 Definition at line 2231 of file soar_core_api.c. References agent, and psoar_agent.

char* soar_cGetAgentInputLinkId (  psoar_agent  a, char *  buff, size_t  buff_size )

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. Definition at line 2189 of file soar_core_api.c. References agent, psoar_agent, and symbol_to_string().

char* soar_cGetAgentOutputLinkId (  psoar_agent  a, char *  buff, size_t  buff_size )

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. Definition at line 2210 of file soar_core_api.c. References agent, psoar_agent, and symbol_to_string().

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 Definition at line 2173 of file soar_core_api.c. References psoar_agent, and soar_agent.

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. Definition at line 2143 of file soar_core_api.c. References agent, psoar_agent, and soar_cGetAgentByName().

char* soar_cGetWmeAttr (  psoar_wme  w, char *  buff, size_t  buff_size )

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 Definition at line 2032 of file soar_core_api.c. References psoar_wme, symbol_to_string(), and wme.

char* soar_cGetWmeId (  psoar_wme  w, char *  buff, size_t  buff_size )

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 Definition at line 2017 of file soar_core_api.c. References psoar_wme, symbol_to_string(), and wme.

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. Definition at line 2064 of file soar_core_api.c. References psoar_wme, and wme.

char* soar_cGetWmeValue (  psoar_wme  w, char *  buff, size_t  buff_size )

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 Definition at line 2048 of file soar_core_api.c. References psoar_wme, symbol_to_string(), and wme.

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 Definition at line 2091 of file soar_core_api.c. References soar_apiAgentIter_struct::_begin, soar_apiAgentIter_struct::_current, agent, agent_count, all_soar_agents, cons, cons_struct::first, soar_apiAgentIter_struct::more, print(), cons_struct::rest, soar_agent, and soar_apiAgentIterator.

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. Definition at line 1287 of file soar_core_api.c. References reset_timer().

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 Definition at line 1317 of file soar_core_api.c. References reset_timer().

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. Definition at line 120 of file soar_core_api.c. References setup_signal_handling(), soar_agent_ids, soar_init_global_callbacks(), soar_version_string, and UNTOUCHED. Referenced by init_soar().

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. Definition at line 1901 of file soar_core_api.c. References NUMBER_OF_CALLBACKS, print(), soar_callback_agent, soar_callback_enum_to_name(), SOAR_CALLBACK_TYPE, and soar_cListAllCallbacksForEvent(). Referenced by soar_list_all_callbacks().

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) Definition at line 1919 of file soar_core_api.c. References agent, cons, cons_struct::first, callback_struct::id, print(), cons_struct::rest, soar_callback, and soar_callback_agent. Referenced by soar_cListAllCallbacks(), and soar_list_all_callbacks_for_event().

int soar_cLoadReteNet (  const 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 Definition at line 600 of file soar_core_api.c. References allocate_memory(), free_memory(), load_rete_net(), print(), SOAR_ERROR, and SOAR_OK. Referenced by soar_ReteNet().

int soar_cMultiAttributes (  const 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 Definition at line 1499 of file soar_core_api.c. References allocate_memory(), get_lexeme_from_string(), make_sym_constant(), multi_attribute, multi_attributes_struct::next, SYM_CONSTANT_LEXEME, multi_attributes_struct::symbol, Symbol, and multi_attributes_struct::value. Referenced by soar_MultiAttributes().

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. Definition at line 1745 of file soar_core_api.c. References agent, cons_struct::first, list, PRINT_CALLBACK, print_string(), cons_struct::rest, soar_callback, soar_callback_agent, and soar_destroy_callback(). Referenced by soar_cQuit(), and soar_ecCloseLog().

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 Definition at line 1693 of file soar_core_api.c. References agent, callback_struct::data, callback_struct::free_function, callback_struct::function, callback_struct::id, soar_callback, soar_callback_agent, soar_callback_data, soar_callback_fn, and soar_callback_free_fn. Referenced by soar_ecOpenLog().

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) Definition at line 558 of file soar_core_api.c. References just_before_exit_soar(), LOG_CALLBACK, soar_agent, soar_cPopCallback(), soar_exists_callback(), and soar_invoke_first_callback(). Referenced by soar_Quit().

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) Definition at line 171 of file soar_core_api.c. References AFTER_INIT_SOAR_CALLBACK, BEFORE_INIT_SOAR_CALLBACK, clear_goal_stack(), do_preference_phase(), GO_DECISION, INPUT_PHASE, reset_explain(), reset_id_counters(), reset_statistics(), reset_wme_timetags(), set_sysparam(), soar_agent, soar_call_data, and soar_invoke_callbacks(). Referenced by reinitialize_soar(), soar_cExciseAllProductions(), soar_cExciseAllTaskProductions(), soar_cSetOperand2(), and soar_ReInitSoar().

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) Definition at line 1941 of file soar_core_api.c. References agent, cons, cons_struct::first, list, soar_callback, soar_callback_agent, and soar_destroy_callback(). Referenced by soar_cRemoveAllMonitorableCallbacks(), and soar_remove_all_callbacks_for_event().

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 Definition at line 1932 of file soar_core_api.c. References soar_callback_agent, SOAR_CALLBACK_TYPE, and soar_cRemoveAllCallbacksForEvent(). Referenced by soar_remove_all_monitorable_callbacks().

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 Definition at line 1778 of file soar_core_api.c. References agent, cons, cons_struct::first, callback_struct::id, list, cons_struct::rest, soar_callback, soar_callback_agent, soar_callback_id, and soar_destroy_callback(). Referenced by soar_cRemoveInputFunction(), and soar_cRemoveOutputFunction().

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: Definition at line 1871 of file soar_core_api.c. References cons, cons_struct::first, callback_struct::id, list, cons_struct::rest, soar_callback, soar_callback_id, soar_destroy_callback(), and soar_global_callbacks.

void soar_cRemoveInputFunction (  agent *  a, const 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 Definition at line 1625 of file soar_core_api.c. References agent, INPUT_PHASE_CALLBACK, and soar_cRemoveCallback(). Referenced by remove_input_function(), and soar_ecReplayInput().

void soar_cRemoveOutputFunction (  agent *  a, const 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) Definition at line 1660 of file soar_core_api.c. References agent, output_link_struct::cb, agent_struct::existing_output_links, output_link_struct::link_wme, output_link_struct::next, wme_struct::output_link, output_link, agent_struct::output_link_pool, OUTPUT_PHASE_CALLBACK, soar_callback, soar_cRemoveCallback(), and soar_exists_callback_id(). Referenced by remove_output_function().

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. Definition at line 1009 of file soar_core_api.c. References slot_struct::acceptable_preference_wmes, sapiwme_st::attr, capture_input_wme(), do_buffered_wm_and_ownership_changes(), wme_struct::gds, gds_invalid_so_remove_goal(), gds_struct::goal, sapiwme_st::id, symbol_union::id, wme_struct::id, identifier_struct::impasse_wmes, INPUT_PHASE, identifier_struct::input_wmes, slot_struct::next, wme_struct::next, psoar_wme, REMOVE_WME, remove_wme_from_wm(), slot, identifier_struct::slots, soarapi_wme, start_timer(), stop_timer(), Symbol, wme_struct::timetag, sapiwme_st::timetag, sapiwme_st::value, wme, and slot_struct::wmes. Referenced by soar_cRemoveWmeUsingTimetag().

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 Definition at line 979 of file soar_core_api.c. References wme_struct::rete_next, soar_cRemoveWme(), wme_struct::timetag, and wme. Referenced by replay_input_wme(), and soar_RemoveWme().

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 == 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 -4  Fail, agent halted, cannot run specified number of cycles Definition at line 311 of file soar_core_api.c. References agent, all_soar_agents, cons, cons_struct::first, GO_DECISION, GO_ELABORATION, GO_OPERATOR, GO_OUTPUT, GO_PHASE, GO_SLOT, GO_STATE, identifier_struct::higher_goal, symbol_union::id, identifier_struct::level, NO_SLOT, OPERATOR_SLOT, agent_struct::operator_symbol, cons_struct::rest, run_all_agents(), run_for_n_decision_cycles(), run_for_n_elaboration_cycles(), run_for_n_modifications_of_output(), run_for_n_phases(), run_for_n_selections_of_slot(), slot, soar_agent, STATE_SLOT, agent_struct::state_symbol, SUPEROPERATOR_SLOT, SUPERSTATE_SLOT, SUPERSUPEROPERATOR_SLOT, SUPERSUPERSTATE_SLOT, and Symbol.

int soar_cSaveReteNet (  const 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 Definition at line 699 of file soar_core_api.c. References allocate_memory(), free_memory(), print(), save_rete_net(), SOAR_ERROR, and SOAR_OK. Referenced by soar_ReteNet().

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 Definition at line 1363 of file soar_core_api.c. Referenced by soar_ChunkNameFormat().

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 Definition at line 1345 of file soar_core_api.c. References set_sysparam(). Referenced by soar_ChunkNameFormat().

int soar_cSetChunkNamePrefix (  const 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 Definition at line 1389 of file soar_core_api.c. Referenced by soar_ChunkNameFormat().

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 Definition at line 2167 of file soar_core_api.c. References agent, psoar_agent, and soar_agent.

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 Definition at line 2155 of file soar_core_api.c. References agent, psoar_agent, soar_agent, and soar_cGetAgentByName().

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 Definition at line 1410 of file soar_core_api.c. References ALL_LEVELS, BOTTOM_UP, EXCEPT, OFF, ON, ONLY, and set_sysparam(). Referenced by soar_Learn().

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 Definition at line 1453 of file soar_core_api.c. References soar_cReInitSoar(). Referenced by soar_Operand2().

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 Definition at line 1483 of file soar_core_api.c. Referenced by soar_WaitSNC().

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. Definition at line 2110 of file soar_core_api.c. References soar_apiAgentIter_struct::_begin, soar_apiAgentIter_struct::_current, all_soar_agents, cons_struct::first, soar_apiAgentIter_struct::more, cons_struct::rest, soar_agent, and soar_apiAgentIterator.

void soar_cStopAllAgents (  void   )

soar_cStopAllAgents -- Stops all agents. Definition at line 416 of file soar_core_api.c. References control_c_handler(). Referenced by soar_Stop().

void soar_cStopCurrentAgent (  const char *  reason  )

soar_cStopCurrentAgent -- Stops the current agent. Parameters: -> reason  a string indicating why the agent is being stopped prematurely. Definition at line 430 of file soar_core_api.c. Referenced by soar_Stop().

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 Definition at line 1961 of file soar_core_api.c. References soar_cAddCallback(), soar_callback_agent, soar_callback_enum_to_name(), soar_callback_fn, SOAR_CALLBACK_TYPE, and soar_cTestCallback(). Referenced by soar_test_all_monitorable_callbacks().

---