Section 4   Embedding CLIPS

CLIPS was designed to be embedded within other programs. When CLIPS is used as an em­bedded application, the user must provide a main program. Calls to CLIPS are made like any other subroutine. To embed CLIPS, add the following include state­ments to the user's main program file:

#include <stdio.h>
#include “clips.h”

(These statements may have to be tailored so the compiler on the user's system can find the CLIPS include file.) The user’s main program must initialize CLIPS by calling the function InitializeEnvironment at some time prior to loading constructs. UserFunctions also must be defined, regardless of whether CLIPS calls any external functions. Compile and link all of the user's code with all CLIPS files except the object version of main.c. When running CLIPS as an embedded pro­gram, many of the capabilities available in the interactive interface (in addition to others) are available through function calls. The functions are documented in the following sec­tions. Prototypes for these functions can be included by using the clips.h header file.

The following function calls control the CLIPS environment:

int AddClearFunction(clearItemName,clearFunction,priority);

char *clearItemName;

void (*clearFunction)();

int priority;

void clearFunction();

Purpose: Adds a user defined function to the list of functions which are called when the CLIPS clear command is executed.

Arguments: 1) The name of the new clear item.

2) A pointer to the function which is to be called whenever a clear command is executed.

3) The priority of the clear item which determines the order in which clear items are called (higher priority items are called first). The values -2000 to 2000 are reserved for CLIPS system defined clear items and should not be used for user defined clear items.

Returns: Returns a zero value if the clear item could not be added, otherwise a non-zero value is returned.

int AddPeriodicFunction(periodicItemName,periodicFunction,

priority);

char *periodicItemName;

void (*periodicFunction)();

int priority;

void periodicFunction();

Purpose: Adds a user defined function to the list of functions which are called periodically while CLIPS is executing. This ability was primarily included to allow interfaces to process events and update displays during CLIPS execution. Care should be taken not to use any operations in a periodic function which would affect CLIPS data structures constructively or destructively, i.e. CLIPS internals may be examined but not modified during a periodic function.

Arguments: 1) The name of the new periodic item.

2) A pointer to a function which is to be called periodically while CLIPS is executing.

3) The priority of the periodic item which determines the order in which periodic items are called (higher priority items are called first). The values -2000 to 2000 are reserved for CLIPS system defined periodic items and should not be used for user defined periodic items.

Returns: Returns a zero value if the periodic item could not be added, otherwise a non-zero value is returned.

int AddResetFunction(resetItemName,resetFunction,priority);

char *resetItemName;

void (*resetFunction)();

int priority;

void resetFunction();

Purpose: Adds a user defined function to the list of functions which are called when the CLIPS reset command is executed.

Arguments: 1) The name of the new reset item.

2) A pointer to the function which is to be called whenever a reset command is executed.

3) The priority of the reset item which determines the order in which reset items are called (higher priority items are called first). The values -2000 to 2000 are reserved for CLIPS system defined reset items and should not be used for user defined reset items.

Returns: Returns a zero value if the reset item could not be added, otherwise a non-zero value is returned.

int Bload(fileName);
char *fileName;

Purpose: Loads a binary image of constructs into the CLIPS data base (the C equivalent of the CLIPS bload command).

Arguments: A string representing the name of the file.

Returns: Returns an integer; if zero, an error occurred. A positive one is returned upon success.

int Bsave(fileName);
char *fileName;

Purpose: Saves a binary image of constructs from the CLIPS data base (the C equivalent of the CLIPS bsave command).

Arguments: A string representing the name of the file.

Returns: Returns an integer; if zero, an error occurred. A positive one is returned upon success.

void Clear();

Purpose: Clears the CLIPS environment (the C equivalent of the CLIPS clear command).

Arguments: None.

Returns: No meaningful return value.

int FunctionCall(functionName,arguments,&result);

char *functionName,*arguments;

DATA_OBJECT result;

Purpose: Allows CLIPS system functions, deffunctions and generic functions to be called from C.

Arguments: 1) The name of the system function, deffunction or generic function to be called.

2) A string containing any constant arguments separated by blanks (this argument can be NULL).

3) Caller’s buffer for storing the result of the function call. See sections 3.2.3 and 3.2.4 for information on getting the value stored in a DATA_OBJECT.

Returns: An integer; zero (0) if an error occurred while evaluating the function, otherwise a one (1).

Example

DATA_OBJECT rtn;

FunctionCall(“+”,“1 2”,&rtn);

int GetAutoFloatDividend();

Purpose: Returns the current value of the auto float dividend behavior (the C equivalent of the CLIPS get-auto-float-dividend command).

Arguments: None.

Returns: An integer; FALSE (0) if the behavior is disabled and TRUE (1) if the behavior is enabled.

int GetDynamicConstraintChecking();

Purpose: Returns the current value of the dynamic constraint checking behavior (the C equivalent of the CLIPS get dynamic constraint checking command).

Arguments: None.

Returns: An integer; FALSE (0) if the behavior is disabled and TRUE (1) if the behavior is enabled.

int GetSequenceOperatorRecognition();

Purpose: Returns the current value of the sequence operator recognition behavior (the C equivalent of the CLIPS get-sequence-operator-recognition command).

Arguments: None.

Returns: An integer; FALSE (0) if the behavior is disabled and TRUE (1) if the behavior is enabled.

int GetStaticConstraintChecking();

Purpose: Returns the current value of the static constraint checking behavior (the C equivalent of the CLIPS get static constraint checking command).

Arguments: None.

Returns: An integer; FALSE (0) if the behavior is disabled and TRUE (1) if the behavior is enabled.

void InitializeEnvironment();

Purpose: Initializes the CLIPS system. Must be called prior to any other CLIPS function call. NOTE: This function should be called only once.

Arguments: None.

Returns: No meaningful return value.

int Load(fileName);
char *fileName;

Purpose: Loads a set of constructs into the CLIPS data base (the C equivalent of the CLIPS load command).

Arguments: A string representing the name of the file.

Returns: Returns an integer; Zero if the file couldn’t be opened, -1 if the file was opened but an error occurred while loading, and 1 if the file was opened an no errors occurred while loading. If syntactic errors are in the constructs, Load still will attempt to read the en­tire file and error notices will be sent to werror.

Other: The load function is not available for use in run-time programs (since individual constructs can’t be added or deleted). To execute different sets of constructs, the switching feature must be used in a run-time program (see section 5 for more details).

int RemoveClearFunction(clearItemName);

char *clearItemName;

Purpose: Removes a named function from the list of functions to be called during a clear command.

Arguments: The name associated with the user defined clear function. This is the same name that was used when the clear function was added with the function AddClearFunction.

Returns: Returns the integer value 1 if the named function was found and removed, otherwise 0 is returned.

int RemovePeriodicFunction(periodicItemName);

char *periodicItemName;

Purpose: Removes a named function from the list of functions which are called periodically while CLIPS is executing.

Arguments: The name associated with the user defined periodic function. This is the same name that was used when the periodic function was added with the function AddPeriodicFunction.

Returns: Returns the integer value 1 if the named function was found and removed, otherwise 0 is returned.

int RemoveResetFunction(resetItemName);

char *resetItemName;

Purpose: Removes a named function from the list of functions to be called during a reset command.

Arguments: The name associated with the user defined reset function. This is the same name that was used when the reset function was added with the function AddResetFunction.

Returns: Returns the integer value 1 if the named function was found and removed, otherwise 0 is returned.

void Reset();

Purpose: Resets the CLIPS environment (the C equivalent of the CLIPS reset command).

Arguments: None.

Returns: No meaningful return value.

int Save(fileName);
char *fileName;

Purpose: Saves a set of constructs to the specified file (the C equivalent of the CLIPS save command).

Arguments: A string representing the name of the file.

Returns: Returns an integer; if zero, an error occurred while opening the file. If non zero no errors were detected while performing the save.

int SetAutoFloatDividend(value);

int value;

Purpose: Sets the auto float dividend behavior (the C equivalent of the CLIPS set-auto-float-dividend command). When this behavior is enabled (by default) the dividend of the division function is automatically converted to a floating point number.

Arguments: The new value for the behavior: TRUE (1) to enable the behavior and FALSE (0) to disable it.

Returns: Returns the old value for the behavior.

int SetDynamicConstraintChecking(value);

int value;

Purpose: Sets the value of the dynamic constraint checking behavior (the C equivalent of the CLIPS command set dynamic constraint-checking). When this behavior is disabled (FALSE by default), newly created data objects (such as deftemplate facts and instances) do not have their slot values checked for constraint violations. When this behavior is enabled (TRUE), the slot values are checked for constraint violations. The return value for this function is the old value for the behavior.

Arguments: The new value for the behavior: TRUE (1) to enable the behavior and FALSE (0) to disable it.

Returns: Returns the old value for the behavior.

int SetSequenceOperatorRecognition(value);

int value;

Purpose: Sets the sequence operator recognition behavior (the C equivalent of the CLIPS set-sequence-operator-recognition command). When this behavior is disabled (by default) multifield variables found in function calls are treated as a single argument. When this behaviour is enabled, multifield variables are expanded and passed as separate arguments in the function call.

Arguments: The new value for the behavior: TRUE (1) to enable the behavior and FALSE (0) to disable it.

Returns: Returns the old value for the behavior.

int SetStaticConstraintChecking(value);

int value;

Purpose: Sets the value of the static constraint checking behavior (the C equivalent of the CLIPS command set static constraint-checking). When this behavior is disabled (FALSE), constraint violations are not checked when function calls and constructs are parsed. When this behavior is enabled (TRUE by default), constraint violations are checked when function calls and constructs are parsed. The return value for this function is the old value for the behavior.

Arguments: The new value for the behavior: TRUE (1) to enable the behavior and FALSE (0) to disable it.

Returns: Returns the old value for the behavior.

int BatchStar(fileName);
char *fileName;

Purpose: Evaluates the series of commands stored in the specified file without replacing standard input (the C equivalent of the CLIPS batch* command).

Arguments: A string representing the name of the file.

Returns: Returns an integer; Zero if the file couldn’t be opened or 1 if the file was opened.

Other: The BatchStar function is not available for use in run-time programs.

int Build(constructString,);

char *constructString;

Purpose: Allows a construct to be defined (the C equivalent of the CLIPS build command).

Arguments: 1) A string containing the construct to be added.

Returns: Returns an integer. 1 if the construct was successfully parsed, otherwise 0.

Other: The Build function is not available for use in run-time programs (since individual constructs can’t be added or deleted).

int Eval(expressionString,&result);

char *expressionString;

DATA_OBJECT result;

Purpose: Allows an expression to be evaluated (the C equivalent of the CLIPS eval command).

Arguments: 1) A string containing the expression to be evaluated.

2) Caller’s buffer for storing the result of the evaluation. See sections 3.2.3 and 3.2.4 for information on getting the value stored in a DATA_OBJECT.

Returns: Returns an integer. 1 if the expression was successfully evaluated, otherwise 0.

Other: The Eval function is not available for use in run-time programs

The following function call controls the CLIPS debugging aids:

int DribbleActive();

Purpose: Determines if the storing of dribble information is active.

Arguments: None.

Returns: Zero if dribbling is not active, non-zero otherwise.

int DribbleOff();

Purpose: Turns off the storing of dribble information (the C equivalent of the CLIPS dribble-off command).

Arguments: None.

Returns: A zero if an error occurred closing the file; otherwise a one.

int DribbleOn(fileName);

char *fileName;

Purpose: Allows the dribble function of CLIPS to be turned on (the C equivalent of the CLIPS dribble-on command).

Arguments: The name of the file in which to store dribble information. Only one dribble file may be opened at a time.

Returns: A zero if an error occurred opening the file; otherwise a one.

int GetWatchItem(item);

char *item;

Purpose: Returns the current value of a watch item.

Arguments: The item to be activated or deactivated which should be one of the following strings: facts, rules, activations, focus, compilations, statistics, globals, instances, slots, messages, message handlers, generic functions,method, or deffunctions.

Returns: Returns 1 if the watch item is enabled, 0 if the watch item is disabled, and -1 if the watch item does not exist.

int Unwatch(item);

char *item;

Purpose: Allows the tracing facilities of CLIPS to be deactivated (the C equivalent of the CLIPS unwatch command).

Arguments: The item to be deactivated which should be one of the following strings: facts, rules, activations, focus, compilations, statistics, globals, deffunctions, instances, slots, messages, message handlers, generic functions, methods, or all. If all is se­lected, all possible watch items will not be traced.

Returns: A one if the watch item was successfully set; otherwise a zero.

int Watch(item);

char *item;

Purpose: Allows the tracing facilities of CLIPS to be activated (the C equivalent of the CLIPS watch command).

Arguments: The item to be activated which should be one of the following strings: facts, rules, activations, focus, compilations, statistics, globals, deffunctions, instances, slots, messages, message handlers, generic functions, methods, or all. If all is se­lected, all possible watch items will be traced.

Returns: A one if the watch item was successfully set; otherwise a zero.

The following function calls are used for manipulating deftemplates.

char *DeftemplateModule(deftemplatePtr);

void *deftemplatePtr;

Purpose: Returns the module in which a deftemplate is defined (the C equivalent of the CLIPS deftemplate-module command).

Arguments: A generic pointer to a deftemplate.

Returns: A string containing the name of the module in which the deftemplate is defined.

void *FindDeftemplate(deftemplateName);

char *deftemplateName;

Purpose: Returns a generic pointer to a named deftemplate.

Arguments: The name of the deftemplate to be found.

Returns: A generic pointer to the named deftemplate if it exists, otherwise NULL.

void GetDeftemplateList(&returnValue,theModule);

DATA_OBJECT returnValue;

void *theModule;

Purpose: Returns the list of deftemplates in the specified module as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-deftemplate-list function).

Arguments: 1) A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the deftemplate names from the list.

2) A generic pointer to the module from which the list will be extracted. A NULL pointer indicates that the list is to be extracted from al l modules.

Returns: No meaningful return value.

char *GetDeftemplateName(deftemplatePtr);

void *deftemplatePtr;

Purpose: Returns the name of a deftemplate.

Arguments: A generic pointer to a deftemplate data structure.

Returns: A string containing the name of the deftemplate.

char *GetDeftemplatePPForm(deftemplatePtr);

void *deftemplatePtr;

Purpose: Returns the pretty print representation of a deftemplate.

Arguments: A generic pointer to a deftemplate data structure.

Returns: A string containing the pretty print representation of the deftemplate (or the NULL pointer if no pretty print representation exists).

int GetDeftemplateWatch(deftemplatePtr);

void *deftemplatePtr;

Purpose: Indicates whether or not a particular deftemplate is being watched.

Arguments: A generic pointer to a deftemplate data structure.

Returns: An integer; one (1) if the deftemplate is being watched, otherwise a zero (0).

void *GetNextDeftemplate(deftemplatePtr);

void *deftemplatePtr;

Purpose: Provides access to the list of deftemplates.

Arguments: A generic pointer to a deftemplate data structure (or NULL to get the first deftemplate).

Returns: A generic pointer to the first deftemplate in the list of deftemplates if deftemplatePtr is NULL, otherwise a generic pointer to the deftemplate immediately following deftemplatePtr in the list of deftemplates. If deftemplatePtr is the last deftemplate in the list of deftemplates, then NULL is returned.

int IsDeftemplateDeletable(deftemplatePtr);
void *deftemplatePtr;

Purpose: Indicates whether or not a particular deftemplate can be deleted.

Arguments: A generic pointer to a deftemplate data structure.

Returns: An integer; zero (0) if the deftemplate cannot be deleted, otherwise a one (1).

void ListDeftemplates(logicalName,theModule);

char *logicalName;

void *theModule;

Purpose: Prints the list of deftemplates (the C equivalent of the CLIPS list deftemplates command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the deftemplates to be listed. A NULL pointer indicates that deftemplate in all modules should be listed.

Returns: No meaningful return value.

void SetDeftemplateWatch(newState,deftemplatePtr);

int newState;

void *deftemplatePtr;

Purpose: Sets the facts watch item for a specific deftemplate.

Arguments: The new facts watch state and a generic pointer to a deftemplate data structure.

int Undeftemplate(deftemplatePtr);

void *deftemplatePtr;

Purpose: Removes a deftemplate from CLIPS (the C equivalent of the CLIPS undeftemplate command).

Arguments: A generic pointer to a deftemplate data structure. If the NULL pointer is used, then all deftemplates will be deleted.

Returns: An integer; zero (0) if the deftemplate could not be deleted, otherwise a one (1).

The following function calls manipulate and display information about facts.

void *Assert(factPtr);

void *factPtr;

Purpose: Adds a fact created using the function CreateFact to the fact-list. If the fact was asserted successfully, Assert will return a pointer to the fact. Otherwise, it will return NULL (i.e., the fact was already in the fact list).

Arguments: A generic pointer to the fact created using CreateFact. The values of the fact should be initialized before calling Assert.

Returns: A generic pointer to a fact structure. If the fact was asserted successfully, Assert will return a generic pointer to the fact. Otherwise, it will return NULL (i.e., the fact was already in the fact list).

WARNING: If the return value from Assert is stored as part of a persistent data structure or in a static data area, then the function IncrementFactCount should be called to insure that the fact cannot be disposed while external references to the fact still exist.

void *AssertString(string);

char *string;

Purpose: Asserts a fact into the CLIPS fact list (the C equivalent of the CLIPS assert-string command).

Arguments: One argument; a pointer to a string containing a list of primitive data types (symbols, strings, integers, floats, and/or instance names).

Returns: A generic pointer to a fact structure.

Examples

If the following deftemplate has been processed by CLIPS,

(deftemplate example

(multislot v)

(slot w (default 9))

(slot x)

(slot y)

(multislot z))

then the following fact

(example (x 3) (y red) (z 1.5 b))

can be added to the fact-list using the function shown below.

void AddExampleFact1()

{

AssertString(“(example (x 3) (y red) (z 1.5 b))”);

}

To construct a string based on variable data, use the C library function sprintf as shown following.

void VariableFactAssert(

int number,

char *status)

{

char tempBuffer[50];

sprintf(tempBuffer,“(example (x %d) (y %s))”,number,status);

AssertString(tempBuffer);

}

int AssignFactSlotDefaults(theFact);

void *theFact;

Purpose: Assigns default values to a fact.

Arguments: A generic pointer to a fact data structure.

Returns: Boolean value. TRUE if the default values were successfully set, otherwise FALSE.

void *CreateFact(deftemplatePtr);

void *deftemplatePtr;

Purpose: Function CreateFact returns a pointer to a fact structure with factSize fields. Once this fact structure is obtained, the fields of the fact can be given values by using PutFactSlot and AssignFactSlotDefaults. Function AddFact should be called when the fact is ready to be asserted.

Arguments: A generic pointer to a deftemplate data structure (which indicates the type of fact being created).

Returns: A generic pointer to a fact data structure.

Other: Use the CreateFact function to create a new fact and then the PutFactSlot function to set one or more slot values. The AssignFactSlotDefaults function is then used to assign default values for slots not set with the PutFactSlot function. Finally, the Assert function is called with the new fact.

Since CreateFact requires a generic deftemplate pointer, it is not possible to use it to create ordered facts unless the associated implied deftemplate has already been created. In cases where the implied deftemplate has not been created, the function AssertString can be used to create ordered facts.

This function allows individual fields of a fact to be assigned under programmer control. This is useful, for example, if a fact asserted from an external function needs to contain an external address or an instance address (since the function AssertString does not permit these data types). For most situations in which a fact needs to be asserted, however, the AssertString function should be preferred (it is slighter slower than using the CreateFact and Assert functions, but it is much easier to use and less prone to being used incorrectly).

Examples

If the following deftemplate has been processed by CLIPS,

(deftemplate example

(multislot v)

(slot w (default 9))

(slot x)

(slot y)

(multislot z))

then the following fact

(example (x 3) (y red) (z 1.5 b))

can be added to the fact-list using the function shown below.

void AddExampleFact2()

{

void *newFact;

void *templatePtr;

void *theMultifield;

DATA_OBJECT theValue;

/*==================*/

/* Create the fact. */

/*==================*/

templatePtr = FindDeftemplate(“example”);

newFact = CreateFact(templatePtr);

if (newFact == NULL) return;

/*==============================*/

/* Set the value of the x slot. */

/*==============================*/

theValue.type = INTEGER;

theValue.value = AddLong(3);

PutFactSlot(newFact,“x”,&theValue);

/*==============================*/

/* Set the value of the y slot. */

/*==============================*/

theValue.type = SYMBOL;

theValue.value = AddSymbol(“red”);

PutFactSlot(newFact,“y”,&theValue);

/*==============================*/

/* Set the value of the z slot. */

/*==============================*/

theMultifield = CreateMultifield(2);

SetMFType(theMultifield,1,FLOAT);

SetMFValue(theMultifield,1,AddDouble(1.5));

SetMFType(theMultifield,2,SYMBOL);

SetMFValue(theMultifield,2,AddSymbol(“b”));

SetDOBegin(theValue,1);

SetDOEnd(theValue,2);

theValue.type = MULTIFIELD;

theValue.value = theMultifield;

PutFactSlot(newFact,“z”,&theValue);

/*=================================*/

/* Assign default values since all */

/* slots were not initialized. */

/*=================================*/

AssignFactSlotDefaults(newFact);

/*==================*/

/* Assert the fact. */

/*==================*/

Assert(newFact);

}

void DecrementFactCount(factPtr);
void *factPtr;

Purpose: This function should only be called to reverse the effects of a previous call to IncrementFactCount. As long as an fact's count is greater than zero, the memory allocated to it cannot be released for other use.

Arguments: A generic pointer to a fact.

Returns: No meaningful return value.

long int FactIndex(factPtr);

void *factPtr;

Purpose: Returns the fact index of a fact (the C equivalent of the CLIPS fact-index command).

Arguments: A generic pointer to a fact data structure.

Returns: A long integer (the fact-index of the fact).

void Facts(logicalName,theModule,start,end,max);

char *logicalName;

void *theModule;

long start, end, max;

Purpose: Prints the list of all facts currently in the fact list (the C equivalent of the CLIPS facts command). Output is sent to the logical name wdisplay.

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the facts to be listed (all facts visible to that module). A NULL pointer indicates that all facts in all modules should be listed.

3) The start index of the facts to be listed. Facts with indices less than this value are not listed. A value of -1 indicates that the argument is unspecified and should not restrict the facts printed.

4) The end index of the facts to be listed. Facts with indices greater than this value are not listed. A value of -1 indicates that the argument is unspecified and should not restrict the facts printed.

5) The maximum number of facts to be listed. Facts in excess of this limit are not listed. A value of -1 indicates that the argument is unspecified and should not restrict the facts printed.

Returns: No meaningful return value.

int GetFactDuplication();

Purpose: Returns the current value of the fact duplication behavior (the C equivalent of the CLIPS get-fact-duplication command).

Arguments: None.

Returns: An integer; FALSE (0) if the behavior is disabled and TRUE (1) if the behavior is enabled.

int GetFactListChanged();

Purpose: Determines if any changes to the fact list have occurred. If this function returns a non-zero integer, it is the user's responsibility to call SetFactListChanged(0) to reset the internal flag. Otherwise, this function will continue to return non-zero even when no changes have occurred. This function is primarily used to determine when to update a display tracking the fact list.

Arguments: None.

Returns: 0 if no changes to the fact list have occurred, non-zero otherwise.

void GetFactPPForm(buffer,bufferLength,factPtr);

char *buffer;

int bufferLength;

void *factPtr;

Purpose: Returns the pretty print representation of a fact in the caller's buffer.

Arguments: 1) A pointer to the caller's character buffer.

2) The maximum number of characters which could be stored in the caller's buffer (not including space for the terminating null character).

3) A generic pointer to a fact data structure.

Returns: No meaningful return value. The fact pretty print form is stored in the caller's buffer.

int GetFactSlot(factPtr,slotName,&theValue);

void *factPtr;

char *slotName;

DATA_OBJECT theValue;

Purpose: Retrieves a slot value from a fact.

Arguments: 1) A generic pointer to a fact data structure.

2) The name of the slot to be retrieved (NULL should be used for the implied multifield slot of an implied deftemplate).

3) A pointer to a DATA_OBJECT in which to place the slot’s value. See sections 3.2.3 and 3.2.4 for information on getting the value stored in a DATA_OBJECT.

Returns: Boolean value. TRUE if the slot value was successfully retrieved, otherwise FALSE.

void *GetNextFact(factPtr);

void *factPtr;

Purpose: Provides access to the fact-list.

Arguments: A generic pointer to a fact data structure (or NULL to get the first fact in the fact-list).

Returns: A generic pointer to the first fact in the fact-list if factPtr is NULL, otherwise a generic pointer to the fact immediately following factPtr in the fact-list. If factPtr is the last fact in the fact-list, then NULL is returned.

Other: Once this generic pointer to the fact structure is obtained, the fields of the fact can be examined by using the macros GetMFType and GetMFValue. The values of a fact obtained using this function should never be changed. See CreateFact for details on accessing deftemplate facts.

WARNING: Do not call this function with a pointer to a fact that has been retracted. If the return value from GetNextFact is stored as part of a persistent data structure or in a static data area, then the function IncrementFactCount should be called to insure that the fact cannot be disposed while external references to the fact still exist.

void IncrementFactCount(factPtr);
void *factPtr;

Purpose: This function should be called for each external copy of pointer to a fact to let CLIPS know that such an outstanding external reference exists. As long as an fact's count is greater than zero, CLIPS will not release its memory because there may be outstanding pointers to the fact. However, the fact can still be functionally retracted, i.e. the fact will appear to no longer be in the fact-list. The fact address always can be safely examined using the fact access functions as long as the count for the fact is greater than zero. Retracting an already retracted fact will have no effect, however, the function AddFact should not be called twice for the same pointer created using CreateFact. Note that this function only needs to be called if you are storing pointers to facts that may later be referenced by external code after the fact has been retracted.

Arguments: A generic pointer to a fact.

Returns: No meaningful return value.

int LoadFacts(fileName);
char *fileName;

Purpose: Loads a set of facts into the CLIPS data base (the C equivalent of the CLIPS load-facts command).

Arguments: A string representing the name of the file.

Returns: Returns an integer; if zero, an error occurred while opening the file. If non zero no errors were detected while performing the load.

int PutFactSlot(factPtr,slotName,&theValue);

void *factPtr;

char *slotName;

DATA_OBJECT theValue;

Purpose: Sets the slot value of a fact.

Arguments: 1) A generic pointer to a fact data structure.

2) The name of the slot to be set (NULL should be used for the implied multifield slot of an implied deftemplate).

3) A pointer to a DATA_OBJECT that contains the slot’s new value. A multifield or implied multifield slot should only be passed a multifield value. A single field slot should only be passed a single field value. See sections 3.3.3 and 3.3.4 for information on setting the value stored in a DATA_OBJECT.

Returns: Boolean value. TRUE if the slot value was successfully set, otherwise FALSE.

Warning: Do not use this function to change the slot value of a fact that has already been asserted. This function should only be used on facts created using CreateFact.

int Retract(factPtr);
void *factPtr;

Purpose: Retracts a fact from the CLIPS fact list (the C equivalent of the CLIPS retract command).

Arguments: A generic pointer to a fact structure (usually captured as the return value from a call to AssertString or Assert). If the NULL pointer is used, then all facts will be retracted.

Returns: An integer; zero (0) if fact already has been retracted, other­wise a one (1).

Other: The caller of RetractFact is responsible for insuring that the fact passed as an argument is still valid. The functions IncrementFactCount and DecrementFactCount can be used to inform CLIPS whether a fact is still in use.

int SaveFacts(fileName,saveScope,NULL);
char *fileName;

int saveScope;

Purpose: Saves the facts in the fact list to the specified file (the C equivalent of the CLIPS save-facts command).

Arguments: A string representing the name of the file and an integer constant representing the scope for the facts being saved which should be either LOCAL_SAVE or VISIBLE_SAVE. The third argument is used internally by the CLIPS save facts command and should be set to NULL when called from user code.

Returns: Returns an integer; if zero, an error occurred while opening the file. If non zero no errors were detected while performing the save.

int SetFactDuplication(value);

int value;

Purpose: Sets the fact duplication behavior (the C equivalent of the CLIPS set fact duplication command). When this behavior is disabled (by default), asserting a duplicate of a fact already in the fact list produces no effect. When enabled, the duplicate fact is asserted with a new fact index.

Arguments: The new value for the behavior: TRUE (1) to enable the behavior and FALSE (0) to disable it.

Returns: Returns the old value for the behavior.

void SetFactListChanged(changedFlag);

int changedFlag;

Purpose: Sets the internal boolean flag which indicates when changes to the fact list have occurred. This function is normally used to reset the flag to zero after GetFactListChanged() returns non-zero.

Arguments: An integer indicating whether changes in the fact list have occurred (non-zero) or not (0).

Returns: Nothing useful.

long FactExistp(factPtr);

void *factPtr;

Purpose: Indicates whether a fact is still in the fact-list or has been retracted (the C equivalent of the CLIPS fact-existp function).

Arguments: 1) A generic pointer to a fact data structure.

Returns: An integer; zero (0) if the fact is not in the fact-list, other­wise a one (1).

void FactSlotNames(factPtr,&theValue);

DATA_OBJECT slotNames;

Purpose: Retrieves the list of slot names associated with a fact (the C equivalent of the CLIPS fact-slot-names function).

Arguments: 1) A generic pointer to a fact data structure.

2) A pointer to a DATA_OBJECT in which to place a multifield value containing the fact’s slot name symbols. For ordered facts, a multifield value containing the single symbol implied is returned. See sections 3.2.3 and 3.2.4 for information on getting the value stored in a DATA_OBJECT.

Returns: No meaningful value.

void GetFactList(&returnValue,theModule);

DATA_OBJECT returnValue;

void *theModule;

Purpose: Returns the list of facts visible to the specified module as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-fact-list function).

Arguments: 1) A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the deffacts names from the list.

2) A generic pointer to the module from which the list will be extracted. A NULL pointer indicates that the list is to be extracted from al l modules.

Returns: No meaningful return value.

int LoadFactsFromString(inputString,maximumPosition);
char *inputString;

int maximumPosition;

Purpose: Loads a set of facts into the CLIPS data base using a string as the input source (in a manner similar to the CLIPS load-facts command).

Arguments: 1) A string containing the fact definitions to be loaded.

2) The maximum number of characters to be read from the string. A value of -1 indicates the entire string.

Returns: Returns an integer; if zero, an error occurred while processing the string.

The following function calls are used for manipulating deffacts.

char *DeffactsModule(theDeffacts);

void *theDeffacts;

Purpose: Returns the module in which a deffacts is defined (the C equivalent of the CLIPS deffacts-module command).

Arguments: A generic pointer to a deffacts.

Returns: A string containing the name of the module in which the deffacts is defined.

void *FindDeffacts(deffactsName);

char *deffactsName;

Purpose: Returns a generic pointer to a named deffacts.

Arguments: The name of the deffacts to be found.

Returns: A generic pointer to the named deffacts if it exists, otherwise NULL.

void GetDeffactsList(&returnValue,theModule);

DATA_OBJECT returnValue;

void *theModule;

Purpose: Returns the list of deffacts in the specified module as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-deffacts-list function).

Arguments: 1) A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the deffacts names from the list.

2) A generic pointer to the module from which the list will be extracted. A NULL pointer indicates that the list is to be extracted from al l modules.

Returns: No meaningful return value.

char *GetDeffactsName(deffactsPtr);

void *deffactsPtr;

Purpose: Returns the name of a deffacts.

Arguments: A generic pointer to a deffacts data structure.

Returns: A string containing the name of the deffacts.

char *GetDeffactsPPForm(deffactsPtr);

void *deffactsPtr;

Purpose: Returns the pretty print representation of a deffacts.

Arguments: A generic pointer to a deffacts data structure.

Returns: A string containing the pretty print representation of the deffacts (or the NULL pointer if no pretty print representation exists).

void *GetNextDeffacts(deffactsPtr);

void *deffactsPtr;

Purpose: Provides access to the list of deffacts.

Arguments: A generic pointer to a deffacts data structure (or NULL to get the first deffacts).

Returns: A generic pointer to the first deffacts in the list of deffacts if deffactsPtr is NULL, otherwise a generic pointer to the deffacts immediately following deffactsPtr in the list of deffacts. If deffactsPtr is the last deffacts in the list of deffacts, then NULL is returned.

int IsDeffactsDeletable(deffactsPtr);
void *deffactsPtr;

Purpose: Indicates whether or not a particular deffacts can be deleted.

Arguments: A generic pointer to a deffacts data structure.

Returns: An integer; zero (0) if the deffacts cannot be deleted, otherwise a one (1).

void ListDeffacts(logicalName,theModule);

char *logicalName;

void *theModule;

Purpose: Prints the list of deffacts (the C equivalent of the CLIPS list deffacts command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the deffacts to be listed. A NULL pointer indicates that deffacts in all modules should be listed.

Returns: No meaningful return value.

int Undeffacts(deffactsPtr);

void *deffactsPtr;

Purpose: Removes a deffacts construct from CLIPS (the C equivalent of the CLIPS undeffacts command).

Arguments: A generic pointer to a deffacts data structure. If the NULL pointer is used, then all deffacts will be deleted.

Returns: An integer; zero (0) if the deffacts could not be deleted, otherwise a one (1).

The following function calls are used for manipulating defrules.

int DefruleHasBreakpoint(defrulePtr);

void *defrulePtr;

Purpose: Indicates whether or not a particular defrule has a breakpoint set.

Arguments: A generic pointer to a defrule data structure.

Returns: An integer; one (1) if a breakpoint exists for the rule, otherwise a zero (0).

char *DefruleModule(theDefrule);

void *theDefrule;

Purpose: Returns the module in which a defrule is defined (the C equivalent of the CLIPS defrule-module command).

Arguments: A generic pointer to a defrule.

Returns: A string containing the name of the module in which the defrule is defined.

void *FindDefrule(defruleName);

char *defruleName;

Purpose: Returns a generic pointer to a named defrule.

Arguments: The name of the defrule to be found.

Returns: A generic pointer to the named defrule if it exists, otherwise NULL.

void GetDefruleList(&returnValue,theModule);

DATA_OBJECT returnValue;

void *theModule;

Purpose: Returns the list of defrules in the specified module as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-defrule-list function)..

Arguments: 1) A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the defrule names from the list.

2) A generic pointer to the module from which the list will be extracted. A NULL pointer indicates that the list is to be extracted from al l modules.

Returns: No meaningful return value.

char *GetDefruleName(defrulePtr);

void *defrulePtr;

Purpose: Returns the name of a defrule.

Arguments: A generic pointer to a defrule data structure.

Returns: A string containing the name of the defrule.

char *GetDefrulePPForm(defrulePtr);

void *defrulePtr;

Purpose: Returns the pretty print representation of a defrule.

Arguments: A generic pointer to a defrule data structure.

Returns: A string containing the pretty print representation of the defrule (or the NULL pointer if no pretty print representation exists).

int GetDefruleWatchActivations(defrulePtr);

void *defrulePtr;

Purpose: Indicates whether or not a particular defrule is being watched for activations.

Arguments: A generic pointer to a defrule data structure.

Returns: An integer; one (1) if the defrule is being watched for activations, otherwise a zero (0).

int GetDefruleWatchFirings(defrulePtr);

void *defrulePtr;

Purpose: Indicates whether or not a particular defrule is being watched for rule firings.

Arguments: A generic pointer to a defrule data structure.

Returns: An integer; one (1) if the defrule is being watched for rule firings, otherwise a zero (0).

int GetIncrementalReset();

Purpose: Returns the current value of the incremental reset behavior (the C equivalent of the CLIPS get-incremental-reset command).

Arguments: None.

Returns: An integer; FALSE (0) if the behavior is disabled and TRUE (1) if the behavior is enabled.

void *GetNextDefrule(defrulePtr);

void *defrulePtr;

Purpose: Provides access to the list of defrules.

Arguments: A generic pointer to a defrule data structure (or NULL to get the first defrule).

Returns: A generic pointer to the first defrule in the list of defrules if defrulePtr is NULL, otherwise a generic pointer to the defrule immediately following defrulePtr in the list of defrules. If defrulePtr is the last defrule in the list of defrules, then NULL is returned.

int IsDefruleDeletable(defrulePtr);
void *defrulePtr;

Purpose: Indicates whether or not a particular defrule can be deleted.

Arguments: A generic pointer to a defrule data structure.

Returns: An integer; zero (0) if the defrule cannot be deleted, otherwise a one (1).

void ListDefrules(logicalName,theModule);

char *logicalName;

void *theModule;

Purpose: Prints the list of defrules (the C equivalent of the CLIPS list defrules command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the defrules to be listed. A NULL pointer indicates that defrules in all modules should be listed.

Returns: No meaningful return value.

int Matches(defrulePtr);

void *defrulePtr;

Purpose: Prints the partial matches and activations of a defrule (the C equivalent of the CLIPS matches command).

Arguments: A generic pointer to a defrule data structure.

Returns: An integer; zero (0) if the rule was not found, otherwise a one (1).

int Refresh(defrulePtr);
void *defrulePtr;

Purpose: Refreshes a rule (the C equivalent of the CLIPS refresh command).

Arguments: A generic pointer to a defrule data structure.

Returns: An integer; zero (0) if the rule was not found, otherwise a one (1).

int RemoveBreak(defrulePtr);

void *defrulePtr;

Purpose: Removes a breakpoint for the specified defrule (the C equivalent of the CLIPS remove-break command).

Arguments: A generic pointer to a defrule data structure.

Returns: An integer; zero (0) if a breakpoint did not exist for the rule, otherwise a one (1).

void SetBreak(defrulePtr);

void *defrulePtr;

Purpose: Adds a breakpoint for the specified defrule (the C equivalent of the CLIPS set-break command).

Arguments: A generic pointer to a defrule data structure.

Returns: No meaningful return value.

void SetDefruleWatchActivations(newState,defrulePtr);

int newState;

void *defrulePtr;

Purpose: Sets the activations watch item for a specific defrule.

Arguments: The new activations watch state and a generic pointer to a defrule data structure.

void SetDefruleWatchFirings(newState,defrulePtr);

int newState;

void *defrulePtr;

Purpose: Sets the rule firing watch item for a specific defrule.

Arguments: The new rule firing watch state and a generic pointer to a defrule data structure.

int SetIncrementalReset(value);

int value;

Purpose: Sets the incremental reset behavior. When this behavior is enabled (by default), newly defined rules are update based upon the current state of the fact list. When disabled, newly defined rules are only updated by facts added after the rule is defined (the C equivalent of the CLIPS set-incremental-reset command).

Arguments: The new value for the behavior: TRUE (1) to enable the behavior and FALSE (0) to disable it.

Returns: Returns the old value for the behavior.

void ShowBreaks(logicalName,theModule);

char *logicalName;

void *theModule;

Purpose: Prints the list of all rule breakpoints (the C equivalent of the CLIPS show-breaks command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module for which the breakpoints are to be listed. A NULL pointer indicates that the the breakpoints in all modules should be listed.

Returns: No meaningful return value.

int Undefrule(defrulePtr);
void *defrulePtr;

Purpose: Removes a defrule from CLIPS (the C equivalent of the CLIPS undefrule command).

Arguments: A generic pointer to a defrule data structure. If the NULL pointer is used, then all defrules will be deleted.

Returns: An integer; zero (0) if the defrule could not be deleted, otherwise a one (1).

The following function calls are used for manipulating the agenda.

int AddRunFunction(runItemName,runFunction,priority);
char *runItemName;

void (*runFunction)();

int priority;

void runFunction();

Purpose: Allows a user-defined function to be called after each rule firing. Such a feature is useful, for example, when bringing data in from some type of external device which does not operate in a synchronous manner. A user may define an external function which will be called by CLIPS after every rule is fired to check for the existence of new data.

Arguments: 1) The name associated with the user defined run function. This name is used by the function RemoveRunFunction.

2) A pointer to the user-defined function which is to be called after every rule firing.

3) The priority of the run item which determines the order in which run items are called (higher priority items are called first). The values -2000 to 2000 are reserved for CLIPS system defined run items and should not be used for user defined run items.

Returns: Returns a zero value if the run item could not be added, otherwise a non-zero value is returned.

Example

This following function checks to see if a key on the keyboard has been hit. If a key has been hit, then the fact (stop-processing) is asserted into the fact-list.

void CheckKB()

{

if (CheckKeyboardStatus() == KB_HIT)

{ AssertString(“stop processing”); }

}

This function can now be added to the list of functions called after every rule firing by making the following function call.

AddRunFunction(“check kb”,checkKB,3000);

void Agenda(logicalName,theModule)

char *logicalName;

void *theModule;

Purpose: Prints the list of rules currently on the agenda (the C equivalent of the CLIPS agenda command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the agenda to be listed. A NULL pointer indicates that the agendas of all modules should be listed.

Returns: No meaningful return value.

void ClearFocusStack();

Purpose: Removes all modules from the focus stack (the C equivalent of the CLIPS clear-focus-stack command).

Arguments: None.

Returns: No meaningful return value.

int DeleteActivation(activationPtr);
void *activationPtr;

Purpose: Removes an activation from the agenda.

Arguments: A generic pointer to an activation data structure. If the NULL pointer is used, then all activations will be deleted.

Returns: An integer; zero (0) if the activation could not be deleted, otherwise a one (1).

void Focus(defmodulePtr);

void *defmodulePtr;

Purpose: Sets the current focus (the C equivalent of the CLIPS focus command).

Arguments: A generic pointer to a defmodule data structure.

Returns: No meaningful value.

char *GetActivationName(activationPtr);

void *activationPtr;

Purpose: Returns the name of the defrule from which the activation was generated.

Arguments: A generic pointer to an activation data structure.

Returns: A string containing a defrule name.

void GetActivationPPForm(buffer,bufferLength,activationPtr);

char *buffer;

int bufferLength;

void *activationPtr;

Purpose: Returns the pretty print representation of an agenda activation in the caller's buffer.

Arguments: 1) A pointer to the caller's character buffer.

2) The maximum number of characters which could be stored in the caller's buffer (not including space for the terminating null character).

3) A generic pointer to an activation data structure.

int GetActivationSalience(activationPtr);

void *activationPtr;

Purpose: Returns the salience value associated with an activation. This salience value may be different from the the salience value of the defrule which generated the activation (due to dynamic salience).

Arguments: A generic pointer to an activation data structure.

Returns: The integer salience value of an activation.

int GetAgendaChanged();

Purpose: Determines if any changes to the agenda of rule activations have occurred. If this function returns a non-zero integer, it is the user's responsibility to call SetAgendaChanged(0) to reset the internal flag. Otherwise, this function will continue to return non-zero even when no changes have occurred. This function is primarily used to determine when to update a display tracking rule activations.

Arguments: None.

Returns: 0 if no changes to the agenda have occurred, non-zero otherwise.

void *GetFocus();

Purpose: Returns the module associated with the current focus (the C equivalent of the CLIPS get-focus function).

Arguments: None.

Returns: A generic pointer to a defmodule data structure (or NULL if the focus stack is empty).

void GetFocusStack(&returnValue);

DATA_OBJECT returnValue;

Purpose: Returns the module names in the focus stack as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-focus-stack function).

Arguments: A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the defrule names from the list.

void *GetNextActivation(activationPtr);

void *activationPtr;

Purpose: Provides access to the list of activations on the agenda.

Arguments: A generic pointer to an activation data structure (or NULL to get the first activation on the agenda).

Returns: A generic pointer to the first activation on the agenda if activationPtr is NULL, otherwise a generic pointer to the activation immediately following activationPtr on the agenda. If activationPtr is the last activation on the agenda, then NULL is returned.

int GetSalienceEvaluation();

Purpose: Returns the current salience evaluation behavior (the C equivalent of the CLIPS get-salience-evaluation command).

Arguments: None.

Returns: An integer (see SetSalienceEvaluation for the list of defined constants).

int GetStrategy();

Purpose: Returns the current conflict resolution strategy (the C equivalent of the CLIPS get-strategy command).

Arguments: None.

Returns: An integer (see SetStrategy for the list of defined strategy constants).

void ListFocusStack(logicalName);

char *logicalName;

Purpose: Prints the current focus stack (the C equivalent of the CLIPS list-focus-stack command).

Arguments: The logical name to which the listing output is sent.

Returns: No meaningful return value.

void *PopFocus();

Purpose: Removes the current focus from the focus stack and returns the module associated with that focus (the C equivalent of the CLIPS pop-focus function).

Arguments: None.

Returns: A generic pointer to a defmodule data structure.

void RefreshAgenda(theModule);

void *theModule;

Purpose: Recomputes the salience values for all activations on the agenda and then reorders the agenda (the C equivalent of the CLIPS refresh-agenda command).

Arguments: A generic pointer to the module containing the agenda to be refreshed. A NULL pointer indicates that the agendas of all modules should be refreshed.

Returns: No meaningful return value.run

int RemoveRunFunction(runItemName);

char *runItemName;

Purpose: Removes a named function from the list of functions to be called after every rule firing.

Arguments: The name associated with the user defined run function. This is the same name that was used when the run function was added with the function AddRunFunction.

Returns: Returns the integer value 1 if the named function was found and removed, otherwise 0 is returned.

void ReorderAgenda(theModule);

void *theModule;

Purpose: Reorders the agenda based on the current conflict resolution strategy and current activation saliences.

Arguments: A generic pointer to the module containing the agenda to be reordered. A NULL pointer indicates that the agendas of all modules should be reordered.

Returns: No meaningful return value.

long int Run(runLimit);
long int runLimit;

Purpose: Allows rules to execute (the C equivalent of the CLIPS run command).

Arguments: An integer which defines how many rules should fire before returning. If runLimit is a negative integer, rules will fire until the agenda is empty.

Returns: Returns an integer value; the number of rules that were fired.

int SetActivationSalience(activationPtr,newSalience);

void *activationPtr;

int newSalience;

Purpose: Sets the salience value of an activation. The salience value of the defrule which generated the activation is unchanged.

Arguments: 1) A generic pointer to an activation data structure.

2) The new salience value (which is not restricted to the  10000 to +10000 range).

Returns: The old salience value of the activation.

Other: The function ReorderAgenda should be called after salience values have been changed to update the agenda.

void SetAgendaChanged(changedFlag);

int changedFlag;

Purpose: Sets the internal boolean flag which indicates when changes to the agenda of rule activations have occurred. This function is normally used to reset the flag to zero after GetAgendaChanged() returns non-zero.

Arguments: An integer indicating whether changes in the agenda have occurred (non-zero) or not (0).

Returns: Nothing useful.

int SetSalienceEvaluation(value);

int value;

Purpose: Sets the salience evaluation behavior (the C equivalent of the CLIPS set-salience-evaluation command).

Arguments: The new value for the behavior – one of the following defined integer constants:

WHEN_DEFINED
WHEN_ACTIVATED
EVERY_CYCLE

Returns: Returns the old value for the behavior.

int SetStrategy(value);

int value;

Purpose: Sets the conflict resolution strategy (the C equivalent of the CLIPS set-strategy command).

Arguments: The new value for the behavior – one of the following defined integer constants:

DEPTH_STRATEGY
BREADTH_STRATEGY
LEX_STRATEGY
MEA_STRATEGY
COMPLEXITY_STRATEGY
SIMPLICITY_STRATEGY
RANDOM_STRATEGY

Returns: Returns the old value for the strategy.

The following function calls are used for manipulating defglobals.

char *DefglobalModule(theDefglobal);

void *theDefglobal;

Purpose: Returns the module in which a defglobal is defined (the C equivalent of the CLIPS defglobal-module command).

Arguments: A generic pointer to a defglobal.

Returns: A string containing the name of the module in which the defglobal is defined.

void *FindDefglobal(globalName);

char *globalName;

Purpose: Returns a generic pointer to a named defglobal.

Arguments: The name of the defglobal to be found (e.g. x for ?*x*).

Returns: A generic pointer to the named defglobal if it exists, otherwise NULL.

void GetDefglobalList(&returnValue,theModule);

DATA_OBJECT returnValue;

void *theModule;

Purpose: Returns the list of defglobals in the specified module as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-defglobal-list function).

Arguments: 1) A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the defglobal names from the list.

2) A generic pointer to the module from which the list will be extracted. A NULL pointer indicates that the list is to be extracted from al l modules.

Returns: No meaningful return value.

char *GetDefglobalName(defglobalPtr);

void *defglobalPtr;

Purpose: Returns the name of a defglobal.

Arguments: A generic pointer to a defglobal data structure.

Returns: A string containing the name of the defglobal (e.g. x for ?*x*).

char *GetDefglobalPPForm(defglobalPtr);

void *defglobalPtr;

Purpose: Returns the pretty print representation of a defglobal.

Arguments: A generic pointer to a defglobal data structure.

Returns: A string containing the pretty print representation of the defglobal (or the NULL pointer if no pretty print representation exists).

int GetDefglobalValue(globalName,&vPtr);

char *globalName;

DATA_OBJECT vPtr;

Purpose: Returns the value of a defglobal.

Arguments: 1) The name of the global variable to be retrieved (e.g. y for ?*y*).

2) A pointer to a DATA_OBJECT in which the value is stored (see sections 3.2.3 and 3.3.4 for details on this data structure).

Returns: An integer; zero (0) if the defglobal was not found, other­wise a one (1). The DATA_OBJECT vPtr is assigned the current value of the defglobal.

void GetDefglobalValueForm(buffer,bufferLength,defglobalPtr);

char *buffer;

int bufferLength;

void *defglobalPtr;

Purpose: Returns a printed representation of a defglobal and its current value in the caller's buffer. For example,

?*x* = 5

Arguments: 1) A pointer to the caller’s character buffer.

2) The maximum number of characters which could be stored in the caller's buffer (not including space for the terminating null character).

3) A generic pointer to a defglobal data structure.

int GetDefglobalWatch(defglobalPtr);

void *defglobalPtr;

Purpose: Indicates whether or not a particular defglobal is being watched.

Arguments: A generic pointer to a defglobal data structure.

Returns: An integer; one (1) if the defglobal is being watched, otherwise a zero (0).

int GetGlobalsChanged();

Purpose: Determines if any changes to global variables have occurred. If this function returns a non-zero integer, it is the user's responsibility to call SetGlobalsChanged(0) to reset the internal flag. Otherwise, this function will continue to return non-zero even when no changes have occurred. This function is primarily used to determine when to update a display tracking global variables.

Arguments: None.

Returns: 0 if no changes to global variables have occurred, non-zero otherwise.

void *GetNextDefglobal(defglobalPtr);

void *defglobalPtr;

Purpose: Provides access to the list of defglobals.

Arguments: A generic pointer to a defglobal data structure (or NULL to get the first defglobal).

Returns: A generic pointer to the first defglobal in the list of defglobals if defglobalPtr is NULL, otherwise a generic pointer to the defglobal immediately following defglobalPtr in the list of defglobals. If defglobalPtr is the last defglobal in the list of defglobals, then NULL is returned.

int GetResetGlobals();

Purpose: Returns the current value of the reset global variables behavior (the C equivalent of the CLIPS get reset globals command).

Arguments: None.

Returns: An integer; FALSE (0) if globals are not reset and TRUE (1) if globals are reset.

int IsDefglobalDeletable(defglobalPtr);
void *defglobalPtr;

Purpose: Indicates whether or not a particular defglobal can be deleted.

Arguments: A generic pointer to a defglobal data structure.

Returns: An integer; zero (0) if the defglobal cannot be deleted, otherwise a one (1).

void ListDefglobals(logicalName,theModule);

char *logicalName;

void *theModule;

Purpose: Prints the list of defglobals (the C equivalent of the CLIPS list defglobals command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the defglobals to be listed. A NULL pointer indicates that defglobals in all modules should be listed.

Returns: No meaningful return value.

int SetDefglobalValue(globalName,&vPtr);

char *globalName;

DATA_OBJECT vPtr;

Purpose: Sets the value of a defglobal.

Arguments: 1) The name of the global variable to be set (e.g. y for ?*y*).

2) A pointer to a DATA_OBJECT in which the new value is contained (see sections 3.2.3 and 3.3.4 for details on this data structure).

Returns: An integer; zero (0) if the defglobal was not found, other­wise a one (1).

void SetDefglobalWatch(newState,defglobalPtr);

int newState;

void *defglobalPtr;

Purpose: Sets the globals watch item for a specific defglobal.

Arguments: The new globals watch state and a generic pointer to a defglobal data structure.

void SetGlobalsChanged(changedFlag);

int changedFlag;

Purpose: Sets the internal boolean flag which indicates when changes to global variables have occurred. This function is normally used to reset the flag to zero after GetGlobalsChanged() returns non-zero.

Arguments: An integer indicating whether changes in global variables have occurred (non-zero) or not (0).

Returns: Nothing useful.

int SetResetGlobals(value);

int value;

Purpose: Sets the reset-globals behavior (the C equivalent of the CLIPS set reset globals command). When this behavior is enabled (by default) global variables are reset to their original values when the reset command is performed.

Arguments: The new value for the behavior: TRUE (1) to enable the behavior and FALSE (0) to disable it.

Returns: Returns the old value for the behavior.

void ShowDefglobals(logicalName,theModule);

char *logicalName;

void *theModule;

Purpose: Prints the list of defglobals and their current values (the C equivalent of the CLIPS show defglobals command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the defglobals to be displayed. A NULL pointer indicates that defglobals in all modules should be displayed.

Returns: No meaningful return value.

int Undefglobal(defglobalPtr);

void *defglobalPtr;

Purpose: Removes a defglobal from CLIPS (the C equivalent of the CLIPS undefglobal command).

Arguments: A generic pointer to a defglobal data structure. If the NULL pointer is used, then all defglobals will be deleted.

Returns: An integer; zero (0) if the defglobal could not be deleted, otherwise a one (1).

The following function calls are used for manipulating deffunctions.

char *DeffunctionModule(theDeffunction);

void *theDeffunction;

Purpose: Returns the module in which a deffunction is defined (the C equivalent of the CLIPS deffunction-module command).

Arguments: A generic pointer to a deffunction.

Returns: A string containing the name of the module in which the deffunction is defined.

void *FindDeffunction(deffunctionName);

char *deffunctionName;

Purpose: Returns a generic pointer to a named deffunction.

Arguments: The name of the deffunction to be found.

Returns: A generic pointer to the named deffunction if it exists, otherwise NULL.

void GetDeffunctionList(&returnValue,theModule);

DATA_OBJECT returnValue;

void *theModule;

Purpose: Returns the list of deffunctions in the specified module as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-deffunction-list function).

Arguments: 1) A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the deffunction names from the list.

2) A generic pointer to the module from which the list will be extracted. A NULL pointer indicates that the list is to be extracted from al l modules.

Returns: No meaningful return value.

char *GetDeffunctionName(deffunctionPtr);

void *deffunctionPtr;

Purpose: Returns the name of a deffunction.

Arguments: A generic pointer to a deffunction data structure.

Returns: A string containing the name of the deffunction.

char *GetDeffunctionPPForm(deffunctionPtr);

void *deffunctionPtr;

Purpose: Returns the pretty print representation of a deffunction.

Arguments: A generic pointer to a deffunction data structure.

Returns: A string containing the pretty print representation of the deffunction (or the NULL pointer if no pretty print representation exists).

int GetDeffunctionWatch(deffunctionPtr);

void *deffunctionPtr;

Purpose: Indicates whether or not a particular deffunction is being watched.

Arguments: A generic pointer to a deffunction data structure.

Returns: An integer; one (1) if the deffunction is being watched, otherwise a zero (0).

void *GetNextDeffunction(deffunctionPtr);

void *deffunctionPtr;

Purpose: Provides access to the list of deffunctions.

Arguments: A generic pointer to a deffunction data structure (or NULL to get the first deffunction).

Returns: A generic pointer to the first deffunction in the list of deffunctions if deffunctionPtr is NULL, otherwise a generic pointer to the deffunction immediately following deffunctionPtr in the list of deffunctions. If deffunctionPtr is the last deffunction in the list of deffunctions, then NULL is returned.

int IsDeffunctionDeletable(deffunctionPtr);
void *deffunctionPtr;

Purpose: Indicates whether or not a particular deffunction can be deleted.

Arguments: A generic pointer to a deffunction data structure.

Returns: An integer; zero (0) if the deffunction cannot be deleted, otherwise a one (1).

void ListDeffunctions(logicalName,theModule);

char *logicalName;

void *theModule;

Purpose: Prints the list of deffunction (the C equivalent of the CLIPS list deffunctions command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the deffunctions to be listed. A NULL pointer indicates that deffunctions in all modules should be listed.

Returns: No meaningful return value.

void SetDeffunctionWatch(newState,deffunctionPtr);

int newState;

void *deffunctionPtr;

Purpose: Sets the deffunctions watch item for a specific deffunction.

Arguments: The new deffunctions watch state and a generic pointer to a deffunction data structure.

int Undeffunction(deffunctionPtr);
void *deffunctionPtr;

Purpose: Removes a deffunction from CLIPS (the C equivalent of the CLIPS undeffunction command).

Arguments: A generic pointer to the deffunction (NULL means to delete all deffunctions).

Returns: An integer; zero (0) if the deffunction could not be deleted, otherwise a one (1).

The following function calls are used for manipulating generic functions.

char *DefgenericModule(theDefgeneric);

void *theDefgeneric;

Purpose: Returns the module in which a defgeneric is defined (the C equivalent of the CLIPS defgeneric-module command).

Arguments: A generic pointer to a defgeneric.

Returns: A string containing the name of the module in which the defgeneric is defined.

void *FindDefgeneric(defgenericName);

char *defgenericName;

Purpose: Returns a generic pointer to a named generic function.

Arguments: The name of the generic to be found.

Returns: A generic pointer to the named generic function if it exists, otherwise NULL.

void GetDefgenericList(&returnValue,theModule);

DATA_OBJECT returnValue;

void *theModule;

Purpose: Returns the list of defgenerics in the specified module as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-defgeneric-list function).

Arguments: 1) A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the defgeneric names from the list.

2) A generic pointer to the module from which the list will be extracted. A NULL pointer indicates that the list is to be extracted from al l modules.

Returns: No meaningful return value.

char *GetDefgenericName(defgenericPtr);

void *defgenericPtr;

Purpose: Returns the name of a generic function.

Arguments: A generic pointer to a defgeneric data structure.

Returns: A string containing the name of the generic function.

char *GetDefgenericPPForm(defgenericPtr);

void *defgenericPtr;

Purpose: Returns the pretty print representation of a generic function.

Arguments: A generic pointer to a defgeneric data structure.

Returns: A string containing the pretty print representation of the generic function (or the NULL pointer if no pretty print representation exists).

int GetDefgenericWatch(defgenericPtr);

void *defgenericPtr;

Purpose: Indicates whether or not a particular defgeneric is being watched.

Arguments: A generic pointer to a defgeneric data structure.

Returns: An integer; one (1) if the defgeneric is being watched, otherwise a zero (0).

void *GetNextDefgeneric(defgenericPtr);

void *defgenericPtr;

Purpose: Provides access to the list of generic functions.

Arguments: A generic pointer to a defgeneric data structure (or NULL to get the first generic function).

Returns: A generic pointer to the first generic function in the list of generic functions if defgenericPtr is NULL, otherwise a generic pointer to the generic function immediately following defgenericPtr in the list of generic functions. If defgenericPtr is the last generic function in the list of generic functions, then NULL is returned.

int IsDefgenericDeletable(defgenericPtr);
void *defgenericPtr;

Purpose: Indicates whether or not a particular generic function and all its methods can be deleted.

Arguments: A generic pointer to a defgeneric data structure.

Returns: An integer: zero (0) if the generic function and all its methods cannot be deleted, otherwise a one (1).

void ListDefgenerics(logicalName,theModule);

char *logicalName;

void *theModule;

Purpose: Prints the list of defgenerics (the C equivalent of the CLIPS list defgenerics command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the defgenerics to be listed. A NULL pointer indicates that defgenerics in all modules should be listed.

Returns: No meaningful return value.

void SetDefgenericWatch(newState,defgenericPtr);

int newState;

void *defgenericPtr;

Purpose: Sets the defgenerics watch item for a specific defgeneric.

Arguments: The new generic-functions watch state and a generic pointer to a defgeneric data structure.

int Undefgeneric(defgenericPtr);
void *defgenericPtr;

Purpose: Removes a generic function and all its methods from CLIPS (the C equivalent of the CLIPS undefgeneric command).

Arguments: A generic pointer to the generic function (NULL means to delete all generic functions).

Returns: An integer: zero (0) if the generic function and all its methods could not be deleted, otherwise a one (1).

The following function calls are used for manipulating generic function methods.

void GetDefmethodDescription(buffer,bufferLength,

defgenericPtr,methodIndex);

char *buf;

int bufLength;

void *defgenericPtr;

unsigned methodIndex;

Purpose: Stores a synopsis of the method parameter restrictions in the caller's buffer.

Arguments: 1) A pointer to the caller's buffer.

2) The maximum number of characters which could be stored in the caller's buffer (not including space for the terminating null character).

3) A generic pointer to a defgeneric data structure.

4) The index of the generic function method.

Returns: No meaningful return value.

void GetDefmethodList(defgenericPtr,&returnValue);

void *defgenericPtr;

DATA_OBJECT returnValue;

Purpose: Returns the list of currently defined defmethods for the specified defgeneric. This function is the C equivalent of the CLIPS get defmethod-list command).

Arguments: 1) A generic pointer to the defgeneric (NULL for all defgenerics).

2) A pointer to the DATA_OBJECT in which the list of defmethod constructs is to be stored.

Returns: A multifield value containing the list of defmethods constructs for the specified defgeneric. The multifield functions described in section 3.2.4 can be used to retrieve the defmethod names and indices from the list. Note that the name and index for each defmethod are stored as pairs in the return multifield value.

char *GetDefmethodPPForm(defgenericPtr,methodIndex);

void *defgenericPtr;

unsigned methodIndex;

Purpose: Returns the pretty print representation of a generic function method.

Arguments: 1) A generic pointer to a defgeneric data structure.

2) The index of the generic function method.

Returns: A string containing the pretty print representation of the generic function method (or the NULL pointer if no pretty print representation exists).

int GetDefmethodWatch(defgenericPtr,methodIndex);

void *defgenericPtr;

unsigned methodIndex

Purpose: Indicates whether or not a particular defmethod is being watched.

Arguments: A generic pointer to a defgeneric data structure and the index of the generic function method.

Returns: An integer; one (1) if the defmethod is being watched, otherwise a zero (0).

void GetMethodRestrictions(defgenericPtr,methodIndex,

&returnValue);

void *defgenericPtr;

unsigned methodIndex;

DATA_OBJECT returnValue;

Purpose: Returns the restrictions for the specified method. This function is the C equivalent of the CLIPS get method-restrictions function.

Arguments: 1) A generic pointer to the defgeneric (NULL for all defgenerics).

2) The index of the generic function method.

3) A pointer to the DATA_OBJECT in which the method restrictions are stored.

Returns: A multifield value containing the restrictions for the specified method (the description of the get method-restrictions function in the Basic Programming Guide explains the meaning of the fields in the multifield value). The multifield functions described in section 3.2.4 can be used to retrieve the method restrictions from the list.

unsigned GetNextDefmethod(defgenericPtr,methodIndex);

void *defgenericPtr;

unsigned methodIndex;

Purpose: Provides access to the list of methods for a particular generic function.

Arguments: 1) A generic pointer to a defgeneric data structure.

2) The index of a generic function method (0 to get the first method of the generic function).

Returns: The index of the first method in the list of methods for the generic function if methodIndex is 0, otherwise the index of the method immediately following methodIndex in the list of methods for the generic function. If methodIndex is the last method in the list of methods for the generic function, then 0 is returned.

int IsDefmethodDeletable(defgenericPtr,methodIndex);
void *defgenericPtr;

unsigned methodIndex;

Purpose: Indicates whether or not a particular generic function method can be deleted.

Arguments: 1) A generic pointer to a defgeneric data structure.

2) The index of the generic function method.

Returns: An integer: zero (0) if the method cannot be deleted, otherwise a one (1).

void ListDefmethods(logicalName,defgenericPtr);

char *logicalName;

void *defgenericPtr;

Purpose: Prints the list of methods for a particular generic function (the C equivalent of the CLIPS list defmethods command).

Arguments: 1) The logical name of the output destination to which tosend the method listing

2) A generic pointer to the generic function (NULL to list methods for all generic functions).

Returns: No meaningful return value.

void SetDefmethodWatch(newState,defgenericPtr,methodIndex);

int newState;

void *defgenericPtr;

unsigned methodIndex

Purpose: Sets the methods watch item for a specific defmethod.

Arguments: The new methods watch state, a generic pointer to a defgeneric data structure, and the index of the generic function method.

int Undefmethod(defgenericPtr,methodIndex);
void *defgenericPtr;

unsigned methodIndex;

Purpose: Removes a generic function method from CLIPS (the C equivalent of the CLIPS undefmethod command).

Arguments: 1) A generic pointer to a defgeneric data structure (NULL to delete all methods for all generic functions).

2) The index of the generic function method (0 to delete all methods of the generic function - must be 0 if defgenericPtr is NULL).

Returns: An integer: zero (0) if the method could not be deleted, otherwise a one (1).

The following function calls are used for manipulating defclasses.

void BrowseClasses(logicalName,defclassPtr);

char *logicalName;

void *defclassPtr;

Purpose: Prints a “graph” of all classes which inherit from the specified class. This function is the C equivalent of the CLIPS browse classes command.

Arguments: 1) The logical name of the output destination to which to send the browse display.

2) A generic pointer to the class which is to be browsed.

Returns: No meaningful return value.

int ClassAbstractP(defclassPtr);

void *defclassPtr;

Purpose: Determines if a class is concrete or abstract, i.e. if a class can have direct instances or not. This function is the C equivalent of the CLIPS class-abstractp command.

Arguments: A generic pointer to the class.

Returns: The integer 1 if the class is abstract, or 0 if the class is concrete.

int ClassReactiveP(defclassPtr);

void *defclassPtr;

Purpose: Determines if a class is reactive or non-reactive, i.e. if objects of the class can match object patterns. This function is the C equivalent of the CLIPS class-reactivep command.

Arguments: A generic pointer to the class.

Returns: The integer 1 if the class is reactive, or 0 if the class is non reactive.

void ClassSlots(defclassPtr,&result,inheritFlag);

void *defclassPtr;

DATA_OBJECT result;

int inheritFlag;

Purpose: Groups the names of slots of a class into a multifield data object. This function is the C equivalent of the CLIPS class-slots command.

Arguments: 1) A generic pointer to the class.

2) Pointer to the data object in which to store the multifield. See sections 3.3.3 and 3.3.4 for information on getting the value stored in a DATA_OBJECT.

3) The integer 1 to include inherited slots or 0 to only include explicitly defined slots.

Returns: No meaningful return value.

void ClassSubclasses(defclassPtr,&result,inheritFlag);

void *defclassPtr;

DATA_OBJECT result;

int inheritFlag;

Purpose: Groups the names of subclasses of a class into a multifield data object. This function is the C equivalent of the CLIPS class-subclasses command.

Arguments: 1) A generic pointer to the class.

2) Pointer to the data object in which to store the multifield. See sections 3.3.3 and 3.3.4 for information on setting the value stored in a DATA_OBJECT.

3) The integer 1 to include inherited subclasses or 0 to only include direct subclasses.

Returns: No meaningful return value.

void ClassSuperclasses(defclassPtr,&result,inheritFlag);

void *defclassPtr;

DATA_OBJECT result;

int inheritFlag;

Purpose: Groups the names of superclasses of a class into a multifield data object. This function is the C equivalent of the CLIPS class-superclasses command.

Arguments: 1) A generic pointer to the class.

2) Pointer to the data object in which to store the multifield.

3) The integer 1 to include inherited superclasses or 0 to only include direct superclasses.

Returns: No meaningful return value.

char *DefclassModule(theDefclass);

void *theDefclass;

Purpose: Returns the module in which a defclass is defined (the C equivalent of the CLIPS defclass-module command).

Arguments: A generic pointer to a defclass.

Returns: A string containing the name of the module in which the defclass is defined.

void DescribeClass(logicalName,defclassPtr);

char *logicalName;

void *defclassPtr;

Purpose: Prints a summary of the specified class including: abstract/concrete behavior, slots and facets (direct and inherited) and recognized message-handlers (direct and inherited). This function is the C equivalent of the CLIPS describe class command.

Arguments: 1) The logical name of the output destination to which to send the description.

2) A generic pointer to the class which is to be described.

Returns: No meaningful return value.

void *FindDefclass(defclassName);

char *defclassName;

Purpose: Returns a generic pointer to a named class.

Arguments: The name of the class to be found.

Returns: A generic pointer to the named class if it exists, otherwise NULL.

unsigned short GetClassDefaultsMode();

Purpose: Returns the current class defaults mode (the C equivalent of the CLIPS get-class-defaults-mode command).

Arguments: None.

Returns: An integer (see SetClassDefaultsMode for the list of mode constants).

void GetDefclassList(&returnValue,theModule);

DATA_OBJECT returnValue;

void *theModule;

Purpose: Returns the list of defclasses in the specified module as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-defclass-list function).

Arguments: 1) A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the defclass names from the list.

2) A generic pointer to the module from which the list will be extracted. A NULL pointer indicates that the list is to be extracted from al l modules.

Returns: No meaningful return value.

char *GetDefclassName(defclassPtr);

void *defclassPtr;

Purpose: Returns the name of a class.

Arguments: A generic pointer to a defclass data structure.

Returns: A string containing the name of the class.

char *GetDefclassPPForm(defclassPtr);

void *defclassPtr;

Purpose: Returns the pretty print representation of a class.

Arguments: A generic pointer to a defclass data structure.

Returns: A string containing the pretty print representation of the class (or the NULL pointer if no pretty print representation exists).

int GetDefclassWatchInstances(defclassPtr);

void *defclassPtr;

Purpose: Indicates whether or not a particular defclass is being watched for instance creation and deletions.

Arguments: A generic pointer to a defclass data structure.

Returns: An integer; one (1) if the defclass is being watched, otherwise a zero (0).

int GetDefclassWatchSlots(defclassPtr);

void *defclassPtr;

Purpose: Indicates whether or not a particular defclass is being watched for slot changes.

Arguments: A generic pointer to a defclass data structure.

Returns: An integer; one (1) if the defclass is being watched for slot changes, otherwise a zero (0).

void *GetNextDefclass(defclassPtr);

void *defclassPtr;

Purpose: Provides access to the list of classes.

Arguments: A generic pointer to a defclass data structure (or NULL to get the first class).

Returns: A generic pointer to the first class in the list of classes if defclassPtr is NULL, otherwise a generic pointer to the class immediately following defclassPtr in the list of classes. If defclassPtr is the last class in the list of classes, then NULL is returned.

int IsDefclassDeletable(defclassPtr);
void *defclassPtr;

Purpose: Indicates whether or not a particular class and all its subclasses can be deleted.

Arguments: A generic pointer to a defclass data structure.

Returns: An integer; zero (0) if the class cannot be deleted, otherwise a one (1).

void ListDefclasses(logicalName,theModule);

char *logicalName;

void *theModule;

Purpose: Prints the list of defclasses (the C equivalent of the CLIPS list defclasses command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the defclasses to be listed. A NULL pointer indicates that defclasses in all modules should be listed.

Returns: No meaningful return value.

unsigned short SetClassDefaultsMode(value);

unsigned short value;

Purpose: Sets the current class defaults mode (the C equivalent of the CLIPS set-class-defaults-mode command).

Arguments: The new value for the mode – one of the following defined integer constants:

CONVENIENCE_MODE
CONSERVATION_MODE

Returns: Returns the old value for the mode.

void SetDefclassWatchInstances(newState,defclassPtr);

int newState;

void *defclassPtr;

Purpose: Sets the instances watch item for a specific defclass.

Arguments: The new instances watch state and a generic pointer to a defclass data structure.

void SetDefclassWatchSlots(newState,defclassPtr);

int newState;

void *defclassPtr;

Purpose: Sets the slots watch item for a specific defclass.

Arguments: The new slots watch state and a generic pointer to a defclass data structure.

void SlotAllowedValues(defclassPtr,slotName,&result);

void *defclassPtr;

char *slotName;

DATA_OBJECT result;

Purpose: Groups the allowed-values for a slot into a multifield data object. This function is the C equivalent of the CLIPS slot allowed-values function.

Arguments: 1) A generic pointer to the class.

2) Name of the slot.

3) Pointer to the data object in which to store the multifield. The multifield functions described in section 3.2.4 can be used to retrieve the allowed values from the list.

Returns: No meaningful return value.

void SlotCardinality(defclassPtr,slotName,result);

void *defclassPtr;

char *slotName;

DATA_OBJECT *result;

Purpose: Groups the cardinality information for a slot into a multifield data object. This function is the C equivalent of the CLIPS slot-cardinality function.

Arguments: 1) A generic pointer to the class.

2) Name of the slot.

3) Pointer to the data object in which to store the multifield.

Returns: No meaningful return value.

int SlotDirectAccessP(defclassPtr,slotName);
void *defclassPtr,

char *slotName;

Purpose: Determines if the specified slot is directly accessible.

Arguments: 1) A generic pointer to a defclass data structure.

2) The name of the slot.

Returns: An integer: 1 if the slot is directly accessible, otherwise 0.

int SlotExistP(defclassPtr,slotName,inheritFlag);
void *defclassPtr,

char *slotName;

int inheritFlag;

Purpose: Determines if the specified slot exists.

Arguments: 1) A generic pointer to a defclass data structure.

2) The name of the slot.

Returns: An integer: If inheritFlag is 0 and the slot is directly defined in the specified class, then 1 is returned, otherwise 0 is returned. If inheritFlag is 1 and the slot is defined either in the specified class or an inherited class, then 1 is returned, otherwise 0 is returned.

void SlotFacets(defclassPtr,slotName,result);

void *defclassPtr;

char *slotName;

DATA_OBJECT *result;

Purpose: Groups the facet values of a class slot into a multifield data object. This function is the C equivalent of the CLIPS slot-facets command. See section 10.8.1.11 in the Basic Programming Guide for more detail.

Arguments: 1) A generic pointer to the class.

2) Name of the slot.

3) Pointer to the data object in which to store the multifield.

Returns: No meaningful return value.

int SlotInitableP(defclassPtr,slotName);
void *defclassPtr,

char *slotName;

Purpose: Determines if the specified slot is initable.

Arguments: 1) A generic pointer to a defclass data structure.

2) The name of the slot.

Returns: An integer: 1 if the slot is initable, otherwise 0.

int SlotPublicP(defclassPtr,slotName);
void *defclassPtr,

char *slotName;

Purpose: Determines if the specified slot is public.

Arguments: 1) A generic pointer to a defclass data structure.

2) The name of the slot.

Returns: An integer: 1 if the slot is public, otherwise 0.

void SlotRange(defclassPtr,slotName,result);

void *defclassPtr;

char *slotName;

DATA_OBJECT *result;

Purpose: Groups the numeric range information for a slot into a multifield data object. This function is the C equivalent of the CLIPS slot range function.

Arguments: 1) A generic pointer to the class.

2) Name of the slot.

3) Pointer to the data object in which to store the multifield.

Returns: No meaningful return value.

void SlotSources(defclassPtr,slotName,result);

void *defclassPtr;

char *slotName;

DATA_OBJECT *result;

Purpose: Groups the names of the class sources of a slot into a multifield data object. This function is the C equivalent of the CLIPS slot-sources command. See section 10.8.1.12 in the Basic Programming Guide for more detail.

Arguments: 1) A generic pointer to the class.

2) Name of the slot.

3) Pointer to the data object in which to store the multifield.

Returns: No meaningful return value.

void SlotTypes(defclassPtr,slotName,result);

void *defclassPtr;

char *slotName;

DATA_OBJECT *result;

Purpose: Groups the names of the primitive data types allowed for a slot into a multifield data object. This function is the C equivalent of the CLIPS slot-types function.

Arguments: 1) A generic pointer to the class.

2) Name of the slot.

3) Pointer to the data object in which to store the multifield.

Returns: No meaningful return value.

int SlotWritableP(defclassPtr,slotName);
void *defclassPtr,

char *slotName;

Purpose: Determines if the specified slot is writable.

Arguments: 1) A generic pointer to a defclass data structure.

2) The name of the slot.

Returns: An integer: 1 if the slot is writable, otherwise 0.

int SubclassP(defclassPtr1,defclassPtr2);

void *defclassPtr1, *defclassPtr2;

Purpose: Determines if a class is a subclass of another class.

Arguments: 1) A generic pointer to a defclass data structure.

2) A generic pointer to a defclass data structure.

Returns: An integer: 1 if the first class is a subclass of the second class.

int SuperclassP(defclassPtr1,defclassPtr2);

void *defclassPtr1, *defclassPtr2;

Purpose: Determines if a class is a superclass of another class.

Arguments: 1) A generic pointer to a defclass data structure.

2) A generic pointer to a defclass data structure.

Returns: An integer: 1 if the first class is a superclass of the second class.

int Undefclass(defclassPtr);
void *defclassPtr;

Purpose: Removes a class and all its subclasses from CLIPS (the C equivalent of the CLIPS undefclass command).

Arguments: A generic pointer to a defclass data structure.

Returns: An integer; zero (0) if the class could not be deleted, otherwise a one (1).

The following function calls are used for manipulating instances.

long BinaryLoadInstances(fileName);
char *fileName;

Purpose: Loads a set of instances from a binary file into the CLIPS data base (the C equivalent of the CLIPS bload instances command).

Arguments: A string representing the name of the binary file.

Returns: Returns the number of instances restored or -1 if the file could not be accessed.

long BinarySaveInstances(fileName,saveCode,NULL,TRUE);
char *fileName;

int saveCode;

Purpose: Saves the instances in the system to the specified binary file (the C equivalent of the CLIPS bsave-instances command).

Arguments: 1) A string representing the name of the binary file.

2) An integer flag indicating whether to save local (current module only) or visible instances. Use either the constant LOCAL_SAVE or VISIBLE_SAVE.

3) Should always be NULL.

4) Should always be TRUE.

Returns: Returns the number of instances saved.

void *CreateRawInstance(defclassPtr,instanceName);
void *defclassPtr;

char *instanceName;

Purpose: Creates an empty instance with the specified name of the specified class. No slot overrides or class default initializations are performed for the instance.

Arguments: 1) A generic pointer to the class of the new instance.

2) The name of the new instance.

Returns: A generic pointer to the new instance, NULL on errors.

WARNING: This function bypasses message passing.

void DecrementInstanceCount(instancePtr);
void *instancePtr;

Purpose: This function should only be called to reverse the effects of a previous call to IncrementInstanceCount(). As long as an instance's count is greater than zero, the memory allocated to it cannot be released for other use.

Arguments: A generic pointer to the instance.

Returns: No meaningful return value.

int DeleteInstance(instancePtr);
void *instancePtr;

Purpose: Deletes the specified instance(s).

Arguments: A generic pointer to the instance to be deleted. If the pointer is NULL, all instances in the system are deleted.

Returns: Non-zero if successful, 0 otherwise.

WARNING: This function bypasses message passing.

void DirectGetSlot(instancePtr,slotName,result);
void *instancePtr;

char *slotName;

DATA_OBJECT *result;

Purpose: Stores the value of the specified slot of the specified instance in the caller's buffer (the C equivalent of the CLIPS dynamic get function).

Arguments: 1) A generic pointer to the instance.

2) The name of the slot.

3) The caller's buffer for the slot value. See sections 3.2.3 and 3.2.4 for information on getting the value stored in a DATA_OBJECT.

Returns: No meaningful return value.

WARNING: This function bypasses message passing.

int DirectPutSlot(instancePtr,slotName,newValue);
void *instancePtr;

char *slotName;

DATA_OBJECT *newValue;

Purpose: Stores a value in the specified slot of the specified instance (the C equivalent of the CLIPS dynamic put function).

Arguments: 1) A generic pointer to the instance.

2) The name of the slot.

3) The caller's buffer containing the new value (an error is generated if this value is NULL). See sections 3.3.3 and 3.3.4 for information on setting the value stored in a DATA_OBJECT.

Returns: Returns an integer; if zero, an error occurred while setting the slot. If non zero, no errors occurred.

WARNING: This function bypasses message passing.

void *FindInstance(theModule,instanceName,searchImports);

void *theModule;
char *instanceName;

int searchImports;

Purpose: Returns the address of the specified instance.

Arguments: 1) A generic pointer to the module to be searched (NULL to search the current module).

2) The name of the instance (should not include a module specifier).

3) A boolean flag indicating whether imported modules should also be searched: TRUE to search imported modules, otherwise FALSE.

Returns: A generic pointer to the instance, NULL if the instance does not exist.

void *GetInstanceClass(instancePtr);
void *instancePtr;

Purpose: Determines the class of an instance.

Arguments: A generic pointer to an instance.

Returns: A generic pointer to the class of the instance.

char *GetInstanceName(instancePtr);
void *instancePtr;

Purpose: Determines the name of an instance.

Arguments: A generic pointer to an instance.

Returns: The name of the instance.

void GetInstancePPForm(buffer,bufferLength,instancePtr);

char *buffer;

int bufferLength;

void *instancePtr;

Purpose: Returns the pretty print representation of an instance in the caller's buffer.

Arguments: 1) A pointer to the caller's character buffer.

2) The maximum number of characters which could be stored in the caller's buffer (not including space for the terminating null character).

3) A generic pointer to an instance.

Returns: No meaningful return value. The instance pretty print form is stored in the caller's buffer.

int GetInstancesChanged();

Purpose: Determines if any changes to instances of user defined instances have occurred, e.g. instance creations/deletions or slot value changes. If this function returns a non-zero integer, it is the user's responsibility to call SetInstancesChanged(0) to reset the internal flag. Otherwise, this function will continue to return non-zero even when no changes have occurred. This function is primarily used to determine when to update a display tracking instances.

Arguments: None.

Returns: 0 if no changes to instances of user defined classes have occurred, non-zero otherwise.

void *GetNextInstance(instancePtr);
void *instancePtr;

Purpose: Provides access to the list of instances.

Arguments: A generic pointer to an instance (or NULL to get the first instance in the list).

Returns: A generic pointer to the first instance in the list of instances if instancePtr is NULL, otherwise a pointer to the instance immediately following instancePtr in the list. If instancePtr is the last instance in the list, then NULL is returned.

void *GetNextInstanceInClass(defclassPtr,instancePtr);
void *defclassPtr,*instancePtr;

Purpose: Provides access to the list of instances for a particular class.

Arguments: 1) A generic pointer to a class.

2) A generic pointer to an instance (or NULL to get the first instance in the specified class).

Returns: A generic pointer to the first instance in the list of instances for the specified class if instancePtr is NULL, otherwise a pointer to the instance immediately following instancePtr in the list. If instancePtr is the last instance in the class, then NULL is returned.

void *GetNextInstanceInClassAndSubclasses(defclassPtr,instancePtr,

iterationData);
void **defclassPtr,*instancePtr;

DATA_OBJECT *iterationData;

Purpose: Provides access to the list of instances for a particular class and its subclasses.

Arguments: 1) A generic pointer to a generic pointer to a class.

1. A generic pointer to an instance (or NULL to get the first instance in the specified class).
2. A pointer to a DATA_OBJECT in which instance iteration is stored. No initialization of this argument is required and the values stored in this argument are not intended for examination by the calling function.

Returns: A generic pointer to the first instance in the list of instances for the specified class and its subclasses if instancePtr is NULL, otherwise a pointer to the instance immediately following instancePtr in the list or the next instance in a subclass of the class. If instancePtr is the last instance in the class and all its subclasses, then NULL is returned.

As the subclasses of the specified class are iterated through to find instances, the value stored in defclassPtr is updated to indicate the class of the instance returned by this function.

Example

DATA_OBJECT iterate;

void *theInstance;

void *theClass;

theClass = FindDefclass(“USER”);

for (theInstance = GetNextInstanceInClassAndSubclasses(&theClass,

NULL,&iterate);

theInstance != NULL;

theInstance = GetNextInstanceInClassAndSubclasses(&theClass,

theInstance,&iterate))

{

PrintRouter(WDISPLAY,GetInstanceName(theInstance));

PrintRouter(WDISPLAY,“\n”);

}

void IncrementInstanceCount(instancePtr);
void *instancePtr;

Purpose: This function should be called for each external copy of an instance address to let CLIPS know that such an outstanding external reference exists. As long as an instance's count is greater than zero, CLIPS will not release its memory because there may be outstanding pointers to the instance. However, the instance can still be functionally deleted, i.e. the instance will appear to no longer be in the system. The instance address always can be safely passed to instance access functions as long as the count for the instance is greater than zero. These functions will recognize when an instance has been functionally deleted.

Arguments: A generic pointer to the instance.

Returns: No meaningful return value.

Example

/*===========*/

/* Incorrect */

/*===========*/

void InstanceReferenceExample()

{

void *myInstancePtr;

myInstancePtr = FindInstance(NULL,“my-instance”,TRUE);

/*===========================================*/

/* Instance my-instance could be potentially */

/* deleted during the run. */

/*===========================================*/

Run(-1L);

/*===========================================*/

/* This next function call could dereference */

/* a dangling pointer and cause a crash. */

/*===========================================*/

DeleteInstance(myInstancePtr);

}

/*=========*/

/* Correct */

/*=========*/

void InstanceReferenceExample()

{

void *myInstancePtr;

myInstancePtr = FindInstance(NULL,“my-instance”,TRUE);

/*=====================================================*/

/* The instance is correctly marked so that a dangling */

/* pointer cannot be created during the run. */

/*=====================================================*/

IncrementInstanceCount(myInstancePtr);

Run(-1L);

DecrementInstanceCount(myInstancePtr);

/*===========================================================*/

/* The instance can now be safely deleted using the pointer. */

/*===========================================================*/

DeleteInstance(myInstancePtr);

}

void Instances(logicalName,modulePtr,className,subclassFlag);

char *logicalName;

void *defmodulePtr;

char *className;

int subclassFlag;

Purpose: Prints the list of all direct instances of a specified class currently in the system (the C equivalent of the CLIPS instances command).

Arguments: 1) The logical name to which output is sent.

2) A generic pointer to a defmodule data structure (NULL indicates to list all instances of all classes in all modules—the third and fourth arguments are ignored).

3) The name of the class for which to list instances (NULL indicates to list all instances of all classes in the specified module—the fourth argument is ignored).

4) A flag indicating whether or not to list recursively direct instances of subclasses of the named class in the specified module. 0 indicates no, and any other value indicates yes.

Returns: No meaningful return value.

long LoadInstances(fileName);
char *fileName;

Purpose: Loads a set of instances into the CLIPS data base (the C equivalent of the CLIPS load-instances command).

Arguments: A string representing the name of the file.

Returns: Returns the number of instances loaded or -1 if the file could not be accessed.

void *MakeInstance(makeCommand);
char *makeCommand;

Purpose: Creates and initializes an instance of a user defined class (the C equivalent of the CLIPS make instance function).

Arguments: A string containing a make instance command in the format below:

(<instance-name> of <class-name> <slot-override>*)

<slot-override> :== (<slot-name> <constant>*)

Returns: A generic pointer to the new instance, NULL on errors.

Example

MakeInstance(“(henry of boy (age 8))”);

long RestoreInstances(fileName);
char *fileName;

Purpose: Loads a set of instances into the CLIPS data base (the C equivalent of the CLIPS restore-instances command).

Arguments: A string representing the name of the file.

Returns: Returns the number of instances restored or -1 if the file could not be accessed.

long SaveInstances(fileName,saveCode,NULL,TRUE);
char *fileName;

int saveCode;

Purpose: Saves the instances in the system to the specified file (the C equivalent of the CLIPS save-instances command).

Arguments: 1) A string representing the name of the file.

2) An integer flag indicating whether to save local (current module only) or visible instances. Use either the constant LOCAL_SAVE or VISIBLE_SAVE.

3) Should always be NULL.

4) Should always be TRUE.

Returns: Returns the number of instances saved.

void Send(instanceBuffer,msg,msgArgs,result);
DATA_OBJECT *instanceBuffer, *result;

char *msg,*msgArgs;

Purpose: Message-passing from C Sends a message with the specified arguments to the specified object and stores the result in the caller's buffer (the C equivalent of the CLIPS send function).

Arguments: 1) A data value holding the object (instance, symbol, float, etc.) which will receive the message.

2) The message.

3) A string containing any constant arguments separated by blanks (this argument can be NULL).

4) Caller's buffer for storing the result of the message. See sections 3.2.3 and 3.2.4 for information on getting the value stored in a DATA_OBJECT.

Returns: No meaningful return value.

Example

void SendMessageExample()

{

DATA_OBJECT insdata, rtn;

void *myInstancePtr;

myInstancePtr = MakeInstance(“(my-instance of MY-CLASS”);

SetType(insdata,INSTANCE_ADDRESS);

SetValue(insdata,myInstancePtr);

Send(&insdata,“my-msg”,“1 abc 3”,&rtn);

}

void SetInstancesChanged(changedFlag);

int changedFlag;

Purpose: Sets the internal boolean flag which indicates when changes to instances of user-defined classes have occurred. This function is normally used to reset the flag to zero after GetInstancesChanged() returns non-zero.

Arguments: An integer indicating whether changes in instances of user defined classes have occurred (non-zero) or not (0).

Returns: Nothing useful.

int UnmakeInstance(instancePtr);
void *instancePtr;

Purpose: This function is equivalent to DeleteInstance except that it uses message passing instead of directly deleting the instance(s).

Arguments: A generic pointer to the instance to be deleted. If the pointer is NULL, all instances in the system are deleted.

Returns: Non-zero if successful, 0 otherwise.

int ValidInstanceAddress(instancePtr);
void *instancePtr;

Purpose: Determines if an instance referenced by an address still exists. See the description of IncrementInstanceCount.

Arguments: The address of the instance.

Returns: The integer 1 if the instance still exists, 0 otherwise.

int LoadInstancesFromString(inputString,maximumPosition);
char *inputString;

int maximumPosition;

Purpose: Loads a set of instances into the CLIPS data base using a string as the input source (in a manner similar to the CLIPS load-instances command).

Arguments: 1) A string containing the instance definitions.

2) The maximum number of characters to be read from the string. A value of -1 indicates the entire string.

Returns: Returns the number of instances loaded or -1 if there were problems using the string as an input source.

int RestoreInstancesFromString(inputString,maximumPosition);
char *inputString;

int maximumPosition;

Purpose: Loads a set of instances into the CLIPS data base using a string as the input source (in a manner similar to the CLIPS restore-instances command).

Arguments: 1) A string containing the instance definitions.

2) The maximum number of characters to be read from the string. A value of -1 indicates the entire string.

Returns: Returns the number of instances loaded or -1 if there were problems using the string as an input source.

The following function calls are used for manipulating defmessage handlers.

unsigned FindDefmessageHandler(defclassPtr,

handlerName,handlerType);

void *defclassPtr,

char *handlerName,*handlerType;

Purpose: Returns an index to the specified message handler within the list of handlers for a particular class.

Arguments: 1) A generic pointer to the class to which the handler is attached.

2) The name of the handler.

3) The type of the handler: around, before, primary or after.

Returns: An index to the specified handler if it exists, otherwise 0.

void GetDefmessageHandlerList(defclassPtr,&returnValue,

includeInheritedp);

void *defclassPtr;

DATA_OBJECT returnValue;

int includeInheritedp

Purpose: Returns the list of currently defined defmessage handlers for the specified class. This function is the C equivalent of the CLIPS get defmessage handler-list command).

Arguments: 1) A generic pointer to the class (NULL for all classes).

2) A pointer to the DATA_OBJECT in which the list of defmessage-handler constructs is to be stored.

3) An integer flag indicating whether to list inherited handlers (TRUE to list them or FALSE to not list them).

Returns: No meaningful value. The second argument to this function is set to a multifield value containing the list of defmessage-handler constructs for the specified class. The multifield functions described in section 3.2.4 can be used to retrieve the defmessage-handler class, name, and type from the list. Note that the class, name, and type for each defmessage-handler are stored as triplets in the return multifield value.

char *GetDefmessageHandlerName(defclassPtr,handlerIndex);

void *defclassPtr;

unsigned handlerIndex;

Purpose: Returns the name of a message handler.

Arguments: 1) A generic pointer to a defclass data structure.

2) The index of a message handler.

Returns: A string containing the name of the message handler.

char *GetDefmessageHandlerPPForm(defclassPtr,handlerIndex);

void *defclassPtr;

unsigned handlerIndex;

Purpose: Returns the pretty print representation of a message handler.

Arguments: 1) A generic pointer to a defclass data structure.

2) The index of a message handler.

Returns: A string containing the pretty print representation of the message handler (or the NULL pointer if no pretty print representation exists).

char *GetDefmessageHandlerType(defclassPtr,handlerIndex);

void *defclassPtr;

unsigned handlerIndex;

Purpose: Returns the type (around, before, primary or after) of a message handler.

Arguments: 1) A generic pointer to a defclass data structure.

2) The index of a message handler.

Returns: A string containing the type of the message handler.

int GetDefmessageHandlerWatch(defclassPtr,handlerIndex);

void *defclassPtr;

unsigned handlerIndex

Purpose: Indicates whether or not a particular defmessage-handler is being watched.

Arguments: A generic pointer to a defclass data structure and the index of the message-handler.

Returns: An integer; one (1) if the defmessage-handler is being watched, otherwise a zero (0).

unsigned GetNextDefmessageHandler(defclassPtr,handlerIndex);

void *defclassPtr;

unsigned handlerIndex;

Purpose: Provides access to the list of message handlers.

Arguments: 1) A generic pointer to a defclass data structure.

2) An index to a particular message handler for the class (or 0 to get the first message handler).

Returns: An index to the first handler in the list of handlers if handlerIndex is 0, otherwise an index to the handler immediately following handlerIndex in the list of handlers for the class. If handlerIndex is the last handler in the list of handlers for the class, then 0 is returned.

int IsDefmessageHandlerDeletable(defclassPtr,handlerIndex);
void *defclassPtr;

unsigned handlerIndex;

Purpose: Indicates whether or not a particular message handler can be deleted.

Arguments: 1) A generic pointer to a defclass data structure.

2) The index of a message handler.

Returns: An integer; zero (0) if the message handler cannot be deleted, otherwise a one (1).

void ListDefmessageHandlers(logicalName,defclassPtr,

includeInheritedp);

char *logicalName;

void *defclassPtr;

int includeInheritedp

Purpose: Prints the list of message handlers for the specified class. This function is the C equivalent of the CLIPS list defmessage handlers command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the class (NULL for all classes).

3) An integer flag indicating whether to list inherited handlers (TRUE to list them or FALSE to not list them).

Returns: No meaningful return value.

void PreviewSend(logicalName,defclassPtr,messageName);

char *logicalName;

void *defclassPtr;

char *messageName;

Purpose: Prints a list of all applicable message handlers for a message sent to an instance of a particular class (the C equivalent of the CLIPS preview send command). Output is sent to the logical name wdisplay.

Arguments: 1) The logical name to which output is sent.

2) A generic pointer to the class.

3) The message name.

Returns: No meaningful return value.

void SetDefmessageHandlerWatch(newState,defclassPtr,

handlerIndex);

int newState;

void *defclassPtr;

unsigned handlerIndex

Purpose: Sets the message-handlers watch item for a specific defmessage-handler.

Arguments: The new message-handlers watch state, a generic pointer to a defclass data structure, and the index of the message handler.

int UndefmessageHandler(defclassPtr,handlerIndex);
void *defclassPtr;

unsigned handlerIndex;

Purpose: Removes a message handler from CLIPS (similar but not equivalent to the CLIPS undefmessage handler command - see WildDeleteHandler).

Arguments: 1) A generic pointer to a defclass data structure (NULL to delete all message handlers in all classes).

2) The index of the message handler (0 to delete all message handlers in the class - must be 0 if defclassPtr is NULL).

Returns: An integer; zero (0) if the message handler could not be deleted, otherwise a one (1).

The following function calls are used for manipulating definstances.

char *DefinstancesModule(theDefinstances);

void *theDefinstances;

Purpose: Returns the module in which a definstances is defined (the C equivalent of the CLIPS definstances-module command).

Arguments: A generic pointer to a definstances.

Returns: A string containing the name of the module in which the definstances is defined.

void *FindDefinstances(definstancesName);

char *definstancesName;

Purpose: Returns a generic pointer to a named definstances.

Arguments: The name of the definstances to be found.

Returns: A generic pointer to the named definstances if it exists, otherwise NULL.

void GetDefinstancesList(&returnValue,theModule);

DATA_OBJECT returnValue;

void *theModule;

Purpose: Returns the list of definstances in the specified module as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-definstances-list function).

Arguments: 1) A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the definstances names from the list.

2) A generic pointer to the module from which the list will be extracted. A NULL pointer indicates that the list is to be extracted from al l modules.

Returns: No meaningful return value.

char *GetDefinstancesName(definstancesPtr);

void *definstancesPtr;

Purpose: Returns the name of a definstances.

Arguments: A generic pointer to a definstances data structure.

Returns: A string containing the name of the definstances.

char *GetDefinstancesPPForm(definstancesPtr);

void *definstancesPtr;

Purpose: Returns the pretty print representation of a definstances.

Arguments: A generic pointer to a definstances data structure.

Returns: A string containing the pretty print representation of the definstances (or the NULL pointer if no pretty print representation exists).

void *GetNextDefinstances(definstancesPtr);

void *definstancesPtr;

Purpose: Provides access to the list of definstances.

Arguments: A generic pointer to a definstances data structure (or NULL to get the first definstances).

Returns: A generic pointer to the first definstances in the list of definstances if definstancesPtr is NULL, otherwise a generic pointer to the definstances immediately following definstancesPtr in the list of definstances. If definstancesPtr is the last definstances in the list of definstances, then NULL is returned.

int IsDefinstancesDeletable(definstancesPtr);
void *definstancesPtr;

Purpose: Indicates whether or not a particular class definstances can be deleted.

Arguments: A generic pointer to a definstances data structure.

Returns: An integer; zero (0) if the definstances cannot be deleted, otherwise a one (1).

void ListDefinstances(logicalName,theModule);

char *logicalName;

void *theModule;

Purpose: Prints the list of definstances (the C equivalent of the CLIPS list definstances command).

Arguments: 1) The logical name to which the listing output is sent.

2) A generic pointer to the module containing the definstances to be listed. A NULL pointer indicates that definstances in all modules should be listed.

Returns: No meaningful return value.

int Undefinstances(definstancesPtr);
void *definstancesPtr;

Purpose: Removes a definstances from CLIPS (the C equivalent of the CLIPS undefinstances command).

Arguments: A generic pointer to a definstances data structure.

Returns: An integer; zero (0) if the definstances could not be deleted, otherwise a one (1).

The following function calls are used for manipulating defmodules.

void *FindDefmodule(defmoduleName);

char *defmoduleName;

Purpose: Returns a generic pointer to a named defmodule.

Arguments: The name of the defmodule to be found.

Returns: A generic pointer to the named defmodule if it exists, otherwise NULL.

void *GetCurrentModule();

Purpose: Returns the current module (the C equivalent of the CLIPS get-current-module function).

Arguments: None.

Returns: A generic pointer to the generic defmodule data structure that is the current module.

void GetDefmoduleList(&returnValue);

DATA_OBJECT returnValue;

Purpose: Returns the list of defmodules as a multifield value in the returnValue DATA_OBJECT (the C equivalent of the CLIPS get-defmodule-list function).

Arguments: A pointer to the caller’s DATA_OBJECT in which the return value will be stored. The multifield functions described in section 3.2.4 can be used to retrieve the defmodule names from the list.

Returns: No meaningful return value.

char *GetDefmoduleName(defmodulePtr);

void *defmodulePtr;

Purpose: Returns the name of a defmodule.

Arguments: A generic pointer to a defmodule data structure.

Returns: A string containing the name of the defmodule.

char *GetDefmodulePPForm(defmodulePtr);

void *defmodulePtr;

Purpose: Returns the pretty print representation of a defmodule.

Arguments: A generic pointer to a defmodule data structure.

Returns: A string containing the pretty print representation of the defmodule (or the NULL pointer if no pretty print representation exists).

void *GetNextDefmodule(defmodulePtr);

void *defmodulePtr;

Purpose: Provides access to the list of defmodules.

Arguments: A generic pointer to a defmodule data structure (or NULL to get the first defmodule).

Returns: A generic pointer to the first defmodule in the list of defmodules if defmodulePtr is NULL, otherwise a generic pointer to the defmodule immediately following defmodulePtr in the list of defmodules. If defmodulePtr is the last defmodule in the list of defmodules, then NULL is returned.

void ListDefmodules(logicalName);

char *logicalName;

Purpose: Prints the list of defmodules (the C equivalent of the CLIPS list defmodules command).

Arguments: 1) The logical name to which the listing output is sent.

Returns: No meaningful return value.

void *SetCurrentModule(defmodulePtr);

void *defmodulePtr;

Purpose: Sets the current module to the specified module (the C equivalent of the CLIPS set-current-module function).

Arguments: A generic pointer to a defmodule data structure.

Returns: A generic pointer to the previous current defmodule data structure.

This section lists the steps needed to define and use an embedded CLIPS application. The example given is the same system used in section 3.4, now set up to run as an embedded application.

1) Copy all of the CLIPS source code file to the user directory.

2) Define the user function (TripleNumber), a new main routine, and UserFunctions in a new file. These could go in separate files if desired. For this example, they will all be in­cluded in a single file.

#include “clips.h”

main()
{
InitializeEnvironment();
Load(“constructs.clp”);
Reset();
Run( 1L)
}

void TripleNumber(

DATA_OBJECT_PTR returnValuePtr)
{
void *value;
long longValue;
double doubleValue;

/*===============================================*/

/* If illegal arguments are passed, return zero. */

/*===============================================*/

if (ArgCountCheck(“triple”,EXACTLY,1) == -1)

{

SetpType(returnValuePtr,INTEGER);

SetpValue(returnValuePtr,AddLong(0L));

return;

}

if (! ArgTypeCheck(“triple”,1,INTEGER_OR_FLOAT,returnValuePtr))

{

SetpType(returnValuePtr,INTEGER);

SetpValue(returnValuePtr,AddLong(0L));

return;

}

/*====================*/

/* Triple the number. */

/*====================*/

if (GetpType(returnValuePtr) == INTEGER)

{

value = GetpValue(returnValuePtr);

longValue = 3 * ValueToLong(value);

SetpValue(returnValuePtr,AddLong(longValue));

}

else /* the type must be FLOAT */

{

value = GetpValue(returnValuePtr);

doubleValue = 3.0 * ValueToDouble(value);

SetpValue(returnValuePtr,AddDouble(doubleValue));

}

return;
}

UserFunctions()

{
extern void TripleNumber();

DefineFunction2(“triple”,'u',PTIF TripleNumber, “TripleNumber”,

“11n”);
}

3) Define constructs which use the new function in a file called constructs.clp (or any file; just be sure the call to Load loads all necessary constructs prior to execution).

(deffacts init data
(data 34)
(data 13.2))

(defrule get data
(data ?num)
⇒
(printout t “Tripling ” ?num crlf)
(assert (new-value (triple ?num))))

(defrule get new value
(new value ?num)
⇒
(printout t crlf “Now equal to ” ?num crlf))

4) Compile all CLIPS files, except main.c, along with all user files.

5) Link all object code files.

6) Execute new CLIPS executable.

This section lists the steps needed to define and use an embedded CLIPS application. The example illustrates how to call deffunctions and generic functions as well as manipulate objects from C.

1) Copy all of the CLIPS source code file to the user directory.

2) Define a new main routine in a new file.

#include <stdio.h>
#include “clips.h”

main()
{

void *c1,*c2,*c3;

DATA_OBJECT insdata,result;

char numbuf[20];

InitializeEnvironment();

/*=======================================================*/

/* Load the classes, message handlers, generic functions */

/* and generic functions necessary for handling complex */

/* numbers. */

/*=======================================================*/

Load(“complex.clp”);

/*=========================================================*/

/* Create two complex numbers. Message-passing is used to */

/* create the first instance c1, but c2 is created and has */

/* its slots set directly. */

/*=========================================================*/

c1 = MakeInstance(“(c1 of COMPLEX (real 1) (imag 10))”);

c2 = CreateRawInstance(FindDefclass(“COMPLEX”),“c2”);

result.type = INTEGER;

result.value = AddLong(3L);

DirectPutSlot(c2,“real”,&result);

result.type = INTEGER;

result.value = AddLong(-7L);

DirectPutSlot(c2,“imag”,&result);

/*===========================================================*/

/* Call the function '+' which has been overloaded to handle */

/* complex numbers. The result of the complex addition is */

/* stored in a new instance of the COMPLEX class. */

/*===========================================================*/

FunctionCall(“+”,“[c1] [c2]”,&result);

c3 = FindInstance(NULL,DOToString(result),TRUE);

/*=======================================================*/

/* Print out a summary of the complex addition using the */

/* “print” and “magnitude” messages to get information */

/* about the three complex numbers. */

/*=======================================================*/

PrintRouter(“stdout”,“The addition of\n\n”);

SetType(insdata,INSTANCE_ADDRESS);

SetValue(insdata,c1);

Send(&insdata,“print”,NULL,&result);

PrintRouter(“stdout”,“\nand\n\n”);

SetType(insdata,INSTANCE_ADDRESS);

SetValue(insdata,c2);

Send(&insdata,“print”,NULL,&result);

PrintRouter(“stdout”,“\nis\n\n”);

SetType(insdata,INSTANCE_ADDRESS);

SetValue(insdata,c3);

Send(&insdata,“print”,NULL,&result);

PrintRouter(“stdout”,“\nand the resulting magnitude is\n\n”);

SetType(insdata,INSTANCE_ADDRESS);

SetValue(insdata,c3);

Send(&insdata,“magnitude”,NULL,&result);

sprintf(numbuf,“%lf\n”,DOToDouble(result));

PrintRouter(“stdout”,numbuf);
}

UserFunctions()

{}

3) Define constructs which use the new function in a file called complex.clp (or any file; just be sure the call to Load loads all necessary constructs prior to execution).

(defclass COMPLEX (is-a USER)

(role concrete)

(slot real (create-accessor read-write))

(slot imag (create-accessor read-write)))

(defmethod + ((?a COMPLEX) (?b COMPLEX))

(make-instance of COMPLEX

(real (+ (send ?a get-real) (send ?b get-real)))

(imag (+ (send ?a get-imag) (send ?b get-imag)))))

(defmessage-handler COMPLEX magnitude ()

(sqrt (+ (** ?self:real 2) (** ?self:imag 2))))

4) Compile all CLIPS files, except main.c, along with all user files.

5) Link all object code files.

6) Execute new CLIPS executable.