www.RuleWorks.co.uk

Performs the arithmetic modulus operation on integer values.

Specifies an attribute of an object. You must define all attributes in an OBJECT-CLASS declaration. For more information about attributes, see Chapter 2.

Produces a match, or evaluates to true, when both its operands have the same type and the same value.

Two compound values are identical if they contain the same values in the same order.

In an attribute-value test on the LHS, the identity predicate is optional.

If the value following the identity predicate is an unbound variable, that variable is bound to the value of the specified attribute. The identity and length-equal ([=]) predicates are the only predicates that can precede the first occurrence of a variable, because they are the only ones that can either bind a variable or compare its value.

In a relational expression on the RHS, the identity operator is required. There is no default or implied operator inside relational expressions.

• Example

The following two Ces test for the existence of one and only one object of class MEMORY:

(memory ^$ID <the-mem>)

-(memory ^$ID <> <the-mem>)

The equality predicate and operator ignores case when comparing SYMBOL values. For example, |cat | is equal to CAT, but |cat | is not identical to CAT.

• Format

^attribute = value-expression

• Operands

^attribute

An attribute of a WMO whose value is to be tested

value-expression

Any RuleWorks expression, whose value is to be tested

• Example

The following CE uses the less restrictive equality predicate:

(active-context ^name = verify-configuration)

• Example

This attribute-value test is the converse of the previous example:

(active-context ^name -= verify-configuration)

• Two numbers are considered to be similar when the difference between their values is less than or equal to 1 percent of the larger absolute value. Like the equality predicate, the similarity predicate automatically converts between the INTEGER and FLOAT data types.
• Two symbols are similar when one of the following is true:
• they are identical or equal (equality is independent of case)
• Both symbols are at least three characters long, and adding a single character to one symbol makes it equal to the other
• Both symbols are at least three characters long, and transposing two characters in one symbol makes it equal to the other
• they have identical SOUNDEX values

SOUNDEX values are calculated according to an algorithm similar to that published in The Art of Computer Programming, Volume 3, pages 391-392, by Donald Knuth. The English-language rules are as follows:

1. Find the first alphabetic character in the symbol, and convert it to uppercase.

2. Convert all non-alphabetic characters to a code of 0.

3. Ignoring case, replace each consonant (after the first alphabetic character), except H's and W's, with its corresponding consonant group code number:

B, F, P, V 1

C, G, J, K, Q, S, X, Z 2

D, T 3

L 4

M, N 5

R 6

4. If two or more adjacent characters contain the same code, remove all but the first.

5. Ignoring case and leaving the first alphabetic character, remove all the vowels (including Y), H's, and W's, and all remaining zeroes and spaces.

• For all other data types, similarity is the same as identity. For example, assuming <the-id> is already bound, the two attribute-value tests shown below match under the same circumstances:

^$ID == <the-id>

^$ID ~= <the-id>

The identity predicate is more efficient.

You cannot use the similarity predicate with the binding instance of a variable.

• Format

^attribute ~= value-expression

value-expression ~= value-expression

• Operands

^attribute

An attribute of a WMO whose value is to be tested.

value-expression

Any RuleWorks expression, whose value is to be tested.

• Examples

The first table shows the results of several similarity test on numbers:

Table 12. Similarity Testing

First Value	Second Value	Similar?
4.0	4	Yes
4.5	4	No
9.9	10	Yes
-9.9	-10	Yes

The next table shows the SOUNDEX codes of several symbols. Note that the last three codes match exactly:

Table 13. SOUNDEX Codes and Symbols

Symbol	SOUNDEX Code
Tracy	T62
Larry	L6
St. Laurent	S34653
Steven	S315
Stephen	S315
Stefano	S315

Finds all instances of a specific class, including descendents of that class.

• Format

EVERY class-name

Argument

Class-name

A symbolic atom that names an object class visible to the active entry block.

• Return Value

A compound value whose elements are the INSTANCE-Ids of all WMOs that belong to class-name. If class-name has children, instances of those children are included in the returned compound.

The INSTANCE-Ids are returned in no particular order.

If the specified class is not visible, returns the empty list ((COMPOUND)).

• Example

The following uses the value returned by the EVERY function in a FOR-EACH action:

(bind <dogs> (every dog))

(for-each <dog> in <dogs>

(wash-pet <dog>)

(pet-to-vet <dog>)

(pet-gets-treat <dog>))

(Wash –pet, pet-to-vet, and pet-gets-treat are hypothetical external routines. Their definitions are left as an exercise for the reader.)

• Format

EXIT

• Example

The following command exits from the command interpreter and returns control to the operating system:

RuleWorks> EXIT

System>

• Format

(EXTERNAL-ROUTINE) routine-name

[(ALIAS actual-routine-name)]

[(ACCEPTS { [<f-param-name> [ [ [size] ] ] ] ext-type [passing-mech] }…)]

[(RETURNS { [<f-param-name> [ [size] ] ] ext-type [passing-mech] }…)]

• Argument

routine-name

The name of the external routine. This must be a symbol that is different from all other routine names and all block names in the program. It must also be different from all RuleWorks actions, built-in functions, and relational operators (AND, NOT, and OR). These restrictions are enforced by the RuleWorks compiler.

The routine name must also satisfy the C language requirements for a function name:

cannot contain the characters "<>[]%^-

less than 32 characters long

different from all C keywords

• Clauses

ALIAS

Declares that the external routine's name is not the actual name against which it is to be linked. The most common use of this clause is to map a case-sensitive routine name to a RuleWorks symbol.

actual-routine-name The real name of the external routine.

ACCEPTS

Specifies the name, data type and passing mechanism of the arguments to be passed out to the external routine. The ACCEPTS clause is optional. If you declare any arguments you must also declare the data type of each argument; the name and passing mechanism are optional. Arguments for the ACCEPTS clause are as follows:

f-param-name	A formal parameter name for an argument to be passed out, for documentation purposes.
[ [size] ]	If included, this declares the argument to be an array. The size of the array is optional; the brackets are not. The size may be an integer or a variable previously bound to an integer in this ACCEPTS clause.
ext-type	The name of the external data type. Valid external types are: BYTE, SHORT, LONG, UNSIGNED-BYTE, UNSIGNED-SHORT, UNSIGNED-LONG, SINGLE-FLOAT, DOUBLE-FLOAT, ASCIZ, ASCID, and ATOM.
passing-mech	Valid passing mechanisms are: BY REFERENCE READ-ONLY, BY REFERENCE READ-WRITE, and BY VALUE.

RETURNS

Also an optional clause, this describes the external routine's return value. Arguments for the RETURNS clause are as follows:

f-param-name	A formal parameter name for the return value, for documentation purposes.
[size]	If the return value is an array, you must declare its size. You can use a constant or a variable.
ext-type	The name of the external data type. Valid external types are: BYTE, SHORT, LONG, UNSIGNED-BYTE, UNSIGNED-SHORT, UNSIGNED-LONG, SINGLE-FLOAT, DOUBLE-FLOAT, ASCIZ, ASCID, and ATOM.
passing-mech	Valid passing mechanisms are BY REFERENCE and BY VALUE.

• Examples

The following example declares a VMS routine that returns a random number:

(EXTERNAL-ROUTINE mth$random

(ACCEPTS <seed> LONG BY REFERENCE)

(RETURNS LONG BY VALUE)

The next example maps the case-sensitive name XtParent to the RuleWorks symbol XT_PARENT:

(EXTERNAL-ROUTINE xt_parent

(ACCEPTS <param1> INTEGER)

(RETURNS <param2> INTEGER)

(ALIAS "XtParent"))

The following example declares the ULTRIX routine that returns an environment variable:

(EXTERNAL-ROUTINE getenv__; from the POSIX library

(ACCEPTS <env-name> ASCIZ BY REFERENCE READ-ONLY)

(RETURNS <env-value> ASCIZ BY REFERENCE))

 

• FOR-EACH

Allows iteration over each element in a compound <CONDITION>(TIN) or table value. The index variable is bound and the specified RHS actions are executed once for each iteration.

• Format (for a compound)

(FOR-EACH <element> IN compound-value
RHS-action ... )

• Arguments

<element>

The index variable that is bound to each element of the compound value.

compound-value

The compound value to be acted upon. This argument may be a bound compound variable or an expression that returns a compound value.

RHS-action

Any valid RHS action. You can specify any number of actions.

<data-value>

The index variable that is bound to each data value in the table value.

<key-name>

The index variable that is bound to each key value in the table value.

table-value

The table value to be acted upon. This argument may be a bound table variable or an expression that returns a table value.

• Examples

The following examples uses the FOR-EACH action to print out the names of all the cards in a Kiwi-9200 computer card cage. Note that this also shows how to bind an index variable.

(rule print-out-cage:do-it

(active-context ^name print-out-cage)

(box ^cards-in-slot <cards> )

-->

(write (crlf) |The card cage will contain: |)

(bind <slot-counter> 1)

(for-each <card> in <cards>

(write (crlf) (tabto 20) |Slot number| <slot-counter>

|contains a| <card>)

(bind <slot-counter> ( <slot-counter> + 1 ) ) ) )

 

• FLOAT

Converts a numeric value into a floating-point number. FLOAT is a stateless function and can be used on either the LHS or RHS.

• Format

(FLOAT numeric-expr )

• Argument

numeric-expr

An expression that evaluates to an INTEGER or FLOAT. If supplied with a SYMBOL, the FLOAT function converts the first white space delimited token, if possible. If not, or if the argument is an OPAQUE or INSTANCE-ID, the function issues a warning message and returns the floating-point number zero.

Table 23. FLOAT Calls and their Return Values

Function Call Return Value Warning Message?

(FLOAT 3) 3.0 No

(FLOAT 3.2) 3.2 No

(FLOAT |3.2|) 3.2 No

(FLOAT |76 trombones|) 76.0 No

(FLOAT 2+2) 0.0 Yes

(FLOAT #32) 0.0 Yes

 

• GENATOM

Returns a system-generated atom, with an optional prefix.

The RuleWorks atom generator is used by the GENATOM and GENINT actions, and by the rul_genint, rul_gensym, and rul_gensymp routines. Every atom generated for any of these routines is unique while the program is running. The atom generator is global, so that all entry blocks called in a program have unique generated atoms.

The generated atoms consist of an integer and an optional prefix. Within a program run, the first use of the atom generator returns 1, the second 2, and so on. The rul_genint routine and the GENINT action return an integer with no prefix. The rul_gensymp routine and the GENATOM action return an integer with a prefix that you can specify, or use the default prefix G:. The rul_gensym routine returns an integer prefixed by G:. The table below shows several uses of the atom generator and the atoms it returns:

Table -24. Atom Generator and Returns

Routine Call or RHS Action Atom Generated

rul_genint 1

rul_gensymp(R:) R:2

(GENATOM) G:3

(GENINT) 4

rul_gensym G:5

The atom generator is reset by the RESTORESTATE action and command.

• Format

(GENATOM [prefix])

• Argument

prefix

A RuleWorks expression, the print form of which will be the first part of the return value. The default prefix is G:

 

• Return Value

A symbol that consists of the prefix you specify (if any) with an integer appended to it.

• Example

The following BIND action binds the variable <TRANSACTION-ID> to the atom produced by the GENATOM function:

(bind <transaction-id> (genatom trans-))

• GENINT

Returns a system-generated INTEGER. See GENATOM for details on the RuleWorks atom generator.

 

• Format

(GENINT)

 

• Return Value

An INTEGER value.

 

• Example

The following BIND action binds the variable <TRANSACTION-ID> to the atom produced by the GENINT function:

(bind <transaction-id> (genint))

• GET

Given a variable bound to an object identifier and an attribute name, returns the value of that attribute of that object. The variable can be bound on either the LHS or the RHS, but GET is allowed on the RHS only.

The GET function lets you access attribute values on the RHS that you did not bind to variables on the LHS. You can bind the identifier of the object on the LHS, and then use the GET function to return the value of any attribute in that object. You do not need to bind each attribute value separately, only the INSTANCE-ID.

 

• Format

(GET object-id ^attribute-name)

 

• Arguments

Object-id

A variable bound to, or an expression that evaluates to, an INSTANCE_ID value. Variables can be bound on either the LHS or the RHS of the rule. The class of the object must be visible to the active entry block.

The RuleWorks compiler issues a warning if it is unable to verify that this argument is an INSTANCE-ID.

attribute-name

A symbolic expression that names an attribute in the specified object. It is a run-time warning to use an attribute that is not declared for the specified class.

Return Value

The value of the specified attribute in the specified instance; or NIL if the arguments are not correct.

 

• Example

The following example shows one use of the GET function:

(OBJECT-CLASS fruit

^fruit-name

^color)

 

(rule make-a-similar-one

(fruit ^$ID <The-fruit> ^fruit-name apple)

à

(MAKE fruit ^fruit-name apple ^color (GET <The-fruit> ^color)))

• IF…THEN…ELSE…

Executes one or more RHS actions when a relational expression is true, or executes one or more different RHS actions when the expression is false. In other words, provides a branch in the flow of control.

 

• Format

(IF (rel-expr)

THEN RHS-action…

[ELSE RHS-action..])

 

• Arguments

rel-expr

A relational expression that determines which RHS actions are to be executed. This argument must evaluate to either true or false. It may not contain any SQL functions.

Note: RuleWorks does not have Boolean values. Therefore, this argument must be a comparison of two expressions. It must not be a single value. For example, RuleWorks does not allow (IF (TRUE) THEN…).

RHS-action

Any RuleWorks action. You can specify any number of actions.

 

• Clauses

THEN

Specifies the actions that are to be executed when the relational expression is true. This clause is required.

ELSE

Specifies the actions that are to be executed when the relational expression is false. This clause is optional.

• INTEGER

Converts a numeric atom into an integer. INTEGER is a stateless function and can be used on either the LHS or RHS.

• Format

(INTEGER numeric-expr )

• Argument

numeric-expr

An expression that evaluates to an INTEGER or FLOAT. If supplied with a SYMBOL, the INTEGER function converts the firs-t white space delimited token, if possible. If not, or if the Argument is an OPAQUE or INSTANCE-ID, the function issues a warning message and returns the integer zero.

 

• Return Value

The nearest integer (by rounding) that corresponds to the specified value.

 

• Examples

The following table shows several calls to the INTEGER function and their results:

Table 25. INTEGER Return Values

Function Call Return Value Warning Message?

(INTEGER 3) 3 No

(INTEGER 3.5) 4 No

(INTEGER 3.5e4) 35000 No

(INTEGER |3.2|) 3 No

(INTEGER |110 cornets|) 110 No

(INTEGER 2+2) 0 Yes

(INTEGER #12) 0 Yes

• IS-OPEN

Tests whether a file has already been opened. IS-OPEN is valid on the RHS only.

 

• Format

(IS-OPEN file-id)

 

• Argument

File-id

A symbolic atom that was associated with a filespec in an OPENFILE action. (See Section 4.5 for more information on input and output.)

 

• Return Value

The mode (IN or OUT) if the file is open; NIL if it is not. If the file is open in mode APPEND, the function returns OUT. (See the OPENFILE action for more information on I/O mode.)

 

• Example

The following IF…THEN…ELSE… action uses the IS-OPEN function:

 

(if ((is-open infil) <> nil)

then

(closefile infil))

• LENGTH

Returns the number of elements in a compound value. LENGTH is a stateless function and can be used on either the LHS or RHS.

 

• Format

LENGTH compound-val

 

• Argument

Compound-val

The compound value to be counted. This argument can be a bound compound variable or a function that returns a compound value.

 

• Return Value

An integer that specifies the number of elements in the compound value.

 

• Examples

The following condition element shows the LENGTH function used on the LHS:

 

(box ^card-in-slot <cards> ^max-cards <= (length <cards>))

The following action shows the LENGTH function used on the RHS:

(write |The card cage contains| (length <cards> ) |cards.|)

• MAKE

Creates a working-memory object of the specified class, with the specified attribute values (if any). RuleWorks uses the default values for attributes you do not specify (see Chapter 2).

Note: When you create WMOs at the command interpreter prompt, the first Argument to the MAKE command must be a constant. In contrast, when you create WMOs in source code, the first Argument to the MAKE action can be a variable or a call to the GET function.

You can also use MAKE as a function with the BIND action.

• Format (for action)

(MAKE class-name [ { ^attribute value-expression }... ] )

• Format (for command)

MAKE class-name [ { ^attribute value }... ] )

• Arguments(Arguments)

class-name

A symbol or variable that names the class of the object to be created; it must be visible to the active entry block.

attribute

A symbol that names an attribute declared in the specified class. This Argument is optional, but if you specify any attributes, you must specify a value with each attribute.

value-expression

Any scalar or compound expression (if you specify a compound attribute) is a valid Argument to the MAKE action, including function calls and arithmetic expressions.

value

A scalar or compound value (if you specify a compound attribute). You cannot use expressions or call functions (except the COMPOUND function) in an Argument to the MAKE command.

• Return Value

The MAKE action returns the INSTANCE-ID atom that identifies the new WMO.

• Examples

The following rule uses the MAKE action to create an object of class ACTIVE-CONTEXT, with a bound variable as the value of the ^NAME attribute.

(rule make-context-active

(context ^name <context-name> ^$ID <context-id>)

-->

(make active-context ^name <context-name>)

(remove <context-id>))

The following MAKE command creates an object of class BOX with one element each in the compound attributes ^CARD-IN-SLOT and ^CARD-IN-SLOT-OBJ-ID:

RuleWorks> (MAKE BOX ^CARD-IN-SLOT (COMPOUND MEMORY)

_RuleWorks> <u>(^CARD-IN-SLOT-OBJ-ID (COMPOUND #32))

The MAKE command below uses the bracket notation to index a compound attribute:

RuleWorks> MAKE BOX ^CARD-IN-SLOT[3] KEYBOARD ^CARD-IN-SLOT-OBJ-ID[3] #49

• MATCHES

Displays the INSTANCE-IDs of the objects that match CEs in the specified rule(s). The command lists the objects that match the first CE, then the second CE, then the first two CEs, and so on. The class name of each CE is shown as part of its heading. The output is in the following format:

>>>RULE_NAME<<<

***matches for (class-name-1)***

#instance-id

…

***matches for (class-name-2)***

#instance-id

…

***matches for 1 2 ***

#instance-id ~instance-id

…

***complete instantiations***

#instance-id time-tag #instance-id time-tag

For more information about displaying match information, see Chapter 9.

• Format

MATCHES rule-name...

• Argument
• rule-name

The name of a rule for which match information is to be displayed. You can specify the name of one or more rules.

• Examples

The following command displays match information of a rule that is not eligible for the conflict set.

RuleWorks> matches foo

>>> foo <<<

to be specified

Note: that there is no instantiation displayed after the last heading. The next command displays the matches of a rule that is eligible for the conflict set:

RuleWorks> matches bar

>>> bar <<<

to be specified

(The third CE in this rule is negative, so no matches for 3, with a match for 1 and 2, means the rule can fire.)

• MAX

Given one or more arguments, returns the largest. The elements of compound values are added to the argument list as if they were separate scalar values.

 

• Format

(MAX value…)

 

• Arguments

value

Any RuleWorks expression. The first value determines the valid data type; using mixed types causes a warning message. You may specify any number of value, either compound or scalr.

 

• Return Value

The greatest of the arguments.

 

• Examples

The following table shows several calls to the MAX function and their results:

Function Call	Return Value	Warning Message?
(MAX 3 2.0 1) (MAX 3.2 10) (MAX –3.2 –10) (MAX boy (COMPOUND man woman) girl) (MAX 3.2 cat 10)	3 10 -3.2 WOMAN 10	No No No No Yes

Note: that ruleworks issues a warning when it finds a value of an invalid data type, but it does process the rest of the arguments list. (See Appendix E for the collating sequences for symbols.)

• MIN

Given one or more arguments, returns the smallest. The elements of compound values are added to the argument list as if they were separate scalar values.

 

• Format

(MIN value…)

 

• Arguments

value

Any RuleWorks expression. The first value determines the valid data type; using mixed types causes a warning message. You may specify any numbert of values, either compound or scalar.

Return Value

The smallest of the arguments.

 

• Examples

The following table shows several calls to the MIN function and their results:

Function Call	Return Value	Warning Message?
(MIN 3 2.0 2) (MIN 3.2 10) (MIN –3.2 –10) (MIN boy (COMPOUND man woman) girl) (MIN 3.2 cat 10)	1 3.2 -10 BOY 3.2	No No No No Yes

Note: that RuleWorks issues a warning when it find a value of an invalid data type, but it does process the rest of the arguments list.

• MODIFY

Changes one or more values in an existing working-memory object. The object must be visible to the active entry block. The object's time-tag is updated but its INSTANCE-ID remains the same.

Note: When you change WMOs at the command interpreter prompt, the first Argument to the MODIFY command must be a constant. In contrast, when you change WMOs in a rule, the first Argument to the MODIFY action can be a variable or a call to the GET function.

You can also use MODIFY as a function with the BIND action.

• Format (for action)

(MODIFY) ID-variable {^attribute value-expression}...

• Format (for command)

MODIFY instance-id {^attribute value}...)

• Arguments(Arguments)

ID-variable

An expression of type INSTANCE-ID, indicating the object to be modified. This Argument can be used in rules only.

instance-id

A constant of type INSTANCE-ID, indicating the object to be modified. This Argument can be used only at the command interpreter level.

attribute

An attribute name that specifies which value in the object is to be changed. You must specify a value with each attribute.

value-expression

Any scalar or compound value (if you specify a compound attribute) is a valid Argument to the MODIFY action, including function calls and arithmetic expressions.

value

A scalar atom or a compound value containing constants (if you specify a compound attribute). You cannot use expressions or call functions (except COMPOUND) in an Argument to any command.

• Return Value

The MODIFY action returns the INSTANCE-ID atom that identifies the changed WMO.

• Example

The following action changes on attribute of a SOFTWARE-OPTION object:

(modify <the-software> ^media-type FD-35)

The equivalent command is shown below:

RuleWorks> WM #29

#29 [EXPAND-PART-SKELETONS:KIWICALC] (KIWICALC ^NAME KIWICALC ^PART-NUM

BER S-CA-9200 ^PRINTNAME KiwiCalc Spreadsheet Software ^PRICE 29.95 ^IS-EXPANDED YES

RuleWorks> MODIFY #29 ^MEDIA-TYPE FD-35

RuleWorks> WM #29

#29 [ | | ] (KIWICALC ^MEDIA-TYPE FD-35 ^NAME KIWICALC ^PART-NUMBER S-CA

-9200 ^PRINTNAME KiwiCalc Spreadsheet Software ^PRICE 29.95 ^IS-EXPANDED YES)

See Chapter 4.4 for examples of modifying compound attributes.

• NOT

Performs a logical negation on its operand, that is, returns true when the operand is false and false when the operand is true.

Note: This is a relational operator, not a match predicate. NOT may be used only in relational expressions within IF…THEN…ELSE…or WHILE…DO…actions.

 

• Format

NOT relation

 

• Operand

relation

The relational expression to be negated. This must evaluate to either true or false.

 

• Example

The following code fragment shows the NOT operator in an IF…THEN…ELSE…action:

 

(if (not (<day> = work-day))

then (sleep-late)

else (go-to-work))

• NTH

Accesses the value at the specified index into a compound value. NTH is a stateless function and can be used on either the LHS or RHS.

 

• Format

(NTH compound-value index)

 

• Arguments

compound-value

The compound value that is to be searched. This argument may be bound compound variable or a function that returns a compound value.

Index

An integer expression (anything that evaluates to an integer) that specifies the location of the desired value. The index of the first element is 1, not 0.

 

• Return Value

The element value at the specified location in a compound value. If the location does not exist, the function returns NIL.

 

• Examples

The following action prints the first element of a bound compound variable:

 

(write (crlf) |Slot 1 contains | (NTH <cards> 1) )

• NEXT

Displays the instantiation that the run-time system will select from the conflict set for the act phase of the next recognize-act cycle. The NEXT command displays the instantiation in the same Format as the CS command, with the addition of the rule-firing counts:

n (m): rule-name #instance-id-1 time-tag-1 m)#instance-id-2 time-tag-2...

where n is the global count and m is the local (to the block invocation) count.

• Format

NEXT

• Arguments

NONE

• Example

The following command shows that the next instantiation the run-time system will select from the conflict set is the rule MODIFY-SOFTWARE-MEDIA:35-CHEAPEST acting on objects #38, #32, and #45:

RuleWorks> NEXT

MODIFY-SOFTWARE-MEDIA:35-CHEAPEST #38 71 #32 58 #45 70

• OBJECT-CLASS

Declares an object class and the attributes associated with it. All OBJECT-CLASS declarations must appear before any executable program elements. OBJECT-CLASS declarations can be contained in entry blocks, declaration blocks, or rule blocks.

• Format

(OBJECT-CLASS) class-name

[(INHERITS-FROM parent-class)]

{^attribute-name [data-type]

[(DEFAULT value)]

}

{^attribute-name COMPOUND

[data-type]

[(DEFAULT value)]

[(FIL value)]

}…)

Note: This Format shows one scalar and one compound attribute, for clarity only. RuleWorks does not require that you declare all scalar attributes first, nor that you have at least one scalar attribute. You can declare compound and scalar attributes in any order.

• Arguments

class-name

The only required Argument, this represents the name of the new object class. It must be a symbol that is different from all other classes in the block, and must not be a RuleWorks predicate.

If the OBJECT-CLASS declaration is contained in an entry block, and the entry block uses declaration blocks, the class name must also be different from all the classes in the used blocks.

A class name in an entry block may be the same as a class in a rule block, even if the entry block activates the rule block.

attribute-name

Specifies the name of an attribute for the new object class.

data-type

Specifies the data type of an attribute. This Argument is optional, but if you do specify a data type RuleWorks enforces that domain restriction. The valid data types and their system-defined default values are shown in the RuleWorks Data Types table.

Table 26. RuleWorks Data Types

Name Default Value

INTEGER 0

FLOAT 0.0

NUMBER 0

SYMBOL NIL

OPAQUE %x0

INSTANCE-ID #0

INSTANCE-ID OF #0

ANY NIL

An attribute typed NUMBER can be assigned either an INTEGER or a FLOAT value. ANY is the default when no data type is declared. INSTANCE-ID optionally restricts the value to a named object class when this Format is used:

INSTANCE-ID OF class-name

• Clauses

INHERITS-FROM

Specifies a parent object class from which the class being declared is to acquire attribute names and characteristics. If present, this clause must precede any attribute names.

parent-class

The name of the parent object class. The parent class must be previously declared in the same block. A subclass cannot inherit from a parent class declared in a different block.

See Table 2-1 in Section 2.1 for a table on restrictions on declaring attributes in a subclass of a parent class.

DEFAULT

Establishes the initial value for an attribute when an object of this object class is created. (The default value is ignored if another value is specified in the MAKE action.

value The default value must be the same attribute shape as the attribute. That is, scalar attributes must have a scalar default value; compound attributes must have a compound default value. Use the COMPOUND function to create the default value for a compound attribute.

COMPOUND

Declares the attribute to be compound rather than scalar. See Chapter 2 for details.

FILL

Defines an initial value for certain elements of a compound value. This filler value is used only when the length of the compound value is increased dynamically but no value is specified for those elements.

value

The scalar value to be used as a filler. See Chapter 2.3.5 for more information.

• Example

The following example declares class BOX that inherits from class PART and has two additional compound attributes.

(OBJECT-CLASS box

(inherits-from part)

^card-in-slot compound

^card-in-slot-obj-id compound))

• ON-EMPTY

Defines a set of RHS actions that are executed by RuleWorks when it reaches the selection phase of the recognize-act cycle and the conflict set is empty. After the ON-EMPTY actions are executed, the ON-EXIT actions fire (see Figure 5-1)

An ON-EMPTY statement must be contained in an ENTRY-BLOCK. You can use and change the input arguments of the entry block in the ON-EMPTY actions.

 

• Format

(ON-EMPTY

action…)

 

• Argument

action

Any RuleWorks RHS action. You can specify one or more actions.

 

• ON-ENTRY

Defines a set of RHS actions that are executed immediately after an entry block is calle and before any rules fire. After the ON-ENTRY actions are executed, the RuleWorks run-time proceeds to the match phase of the first recognize-act cycle.

An ON-ENTRY statement must be contained in an ENTRY-BLOCK. You can use and change the input arguments of the entry block in the ON-ENTRY actions.

• Format

(ON-ENTRY

action…)

 

• Argument

action

Any RuleWorks RHS action. You can specify one or more actions.

• ON-EVERY

Defines a set of RHS actions that are executed by RuleWorks after the act phase of one recognize-act cycle and before the match phase of the next cycle.

If the last rule fired executes a RETURN or QUIT action, the ON-EVERY actions are not executed. When the conflict set is empty, the ON-EMPTY actions are executed but the ON-EVERY actions are not. (See Figure 5-1 for an illustration.)

An ON-EVERY statement must be contained in an ENTRY-BLOCK. You can use and change the input arguments of the entry block in the ON-EVERY actions.

 

• Format

(ON-EVERY

action…)

 

• Argument

action

Any RuleWorks RHS action. You can specify one or more actions.

• ON-EXIT

Defines a set of RHS actions that are executed by RuleWorks just before control returns to the caller of the entry block.

The ON-EXIT actions are executed when the reason for control being returned is that the conflict set is empty or that a RETURN action was executed. The ON-EXIT actions are not executed after a QUIT action is executed. (See Figure 5-1 for an illustration.)

An ON-EXIT statement must be contained in an ENTRY-BLOCK. You can use and change the input arguments of the entry block in the ON-EXIT actions.

 

• Format

(ON-EXIT

action…)

 

• Argument

action

Any RuleWorks RHS action. You can specify one or more actions.

 

• OPENFILE

Opens a file for access in a specified mode, and associates it with a file identifier.

• Format

(OPENFILE file-id filespec mode)

• Arguments

file-id

A symbol that represents the file identifier with which the specified file is to be associated.

filespec

The file specification for the file to be opened. If you are opening a file for input, the file must already exist.

mode

A keyword that indicates whether the specified file is to be opened for input or output. The following table, OPENFILE Keywords, lists the keywords you can specify.

Table 27 OPENFILE Keywords

Mode Effect

OPENFILE KeywordsIN The action opens an existing file for reading only.

OUT The action creates a new file and opens it for writing only.

APPEND The action opens an existing file for writing and sets the file pointer to the end of the file.

 

• Example

The following action opens the file ORDER.DAT for input and associates it with the file identifier INFIL:

(OPENFILE INFIL ORDER.DAT IN)

The equivalent command is:

RuleWorks> OPENFILE INFIL ORDER.DAT IN

• OR

Performs a logical inclusive disjunction on its two operands, that is, returns true when either one or both of its operands is true.

Note: This is a relational operator, not a match predicate. OR may be used only in relational expressions within IF...THEN...ELSE... or WHILE...DO... actions.

• Format

relation OR relation

• Operands

relation

The relational expressions to be combined. These operands must evaluate to either true or false.

• Example

The following code fragment shows the OR operator in an IF ... THEN ... ELSE ... action:

(if ((<weather> = sunny) or (<weather> = warm))

then (do_outdoor_chores)

else (do_indoor_chores))

• P (Production)

Synonym for "rule", the Production statement is provided for compatibility with DEC OPS5 Version 4.0A and other OPS systems. See RULE for details.

 

• Format

(P production-name

(condition-element)…

à

(action)…)

• POSITION

Scans the specified compound variables for the specified scalar value. POSITION is a stateless function and can be used on either the LHS or RHS.

By default, POSITION test for identity; you can specify a different predicate. The function always stops at the first occurrence of the predicate evaluating to true.

 

• Format

(POSITION compound-var [predicate] scalar-value)

 

• Arguments

compound-var

A compound variable bound to the compound value that is to be scanned.

predicate

A predicate that specifies the comparison between elements of the compound value and the scalar value. This argument is optional; if you do not specify a predicate, RuleWorks uses the default identity predicate.

You can use any scalar predicate except containment and non-containment.

scalar-value

A scalar constant or a bound variable.

 

• Return Value

The integer index of the first element in compound-var that satifies the comparison specified by the predicate with the scalar-value; or zero if no element of compound-var satisfies the comparison.

 

• Examples

Given the following object:

 

#28 69 (BOX ^CARD-IN-SLOT (COMPOUND MEMORY MEMORY MEMORY KEYBOARD FD-35) ^CARD-IN-SLOT-OBJ-ID (COMPOUND #31 #39 #37 #45) ^NAME BOX ^PART-NUMBER KI-9200 ^PRINTNAME Kiwi-9200 CPU Base Unit ^PRICE 999.95 ^IS-EXPANDED YES)

And assuming <CARDS> is bound to ^CARD-IN-SLOT, the following function call returns the value 1:

 

(POSITION <CARDS> MEMORY)

The following attribute-value tests use the containment and similarity predicates in conjunction with the POSITION function to test two consequtive elements of a compound value:

 

^list {[+] ~= color <list>}

^list [(position <list> ~=color) + 1] <> blue

 

• PPCLASS

Displays the parents and attributes of the specified object class. The attributes are listed under the name of the object class that declared them, with their shape, domain restriction, and default and fill values (if any).

Alternatively, displays the hierarchy of classes defined in the active block.

• Format

PPCLASS [ object-class ]

• Argument

object-class

The name of an object class that is visible to the active entry block.

This Argument is optional. If you supply no Argument, PPCLASS displays the class structure of the active block.

• Example

The following example shows the PPCLASS output for the class BOX from the sample program, KIWI.

RuleWorks> PPCLASS BOX

PART
^PART-NUMBER
^NAME symbol
^PRICE float
^IS-EXPANDED symbol (default NO)

BOX
^CARD-IN-SLOT compound symbol
^CARD-IN-SLOT-OBJ-ID compound instance-id

• PPWM

Displays all objects, or all instances of a specified class, or only those instances that match a specified object pattern. Object patterns are similar to CEs and can include attributes specified with values, tests, disjunctions, and conjunctions. Object patterns cannot include variables or function calls.

The PPWM command displays the following information about an object:

• Its INSTANCE-ID
• The name of the construct that last modified the object (for example, a rule or ON- clause). If you last modified the object at the interpreter prompt, the construct name is the symbol RUL.
• Its class name, its attributes, and the attributes’ values

Scalar attributes whose value is NIL, and compound attributes whose value is (COMPOUND) are not displayed unless you have declared a DEFAULT value for the attribute.

The system displays this information in the following format:

#INSTANCE-ID [rule-name](class-name attribute-1 value-1 attribute-2 value-2 …)

If you do not specify a pattern, the command displays all the visible WMOs.

 

• Format

PPWm [class-name] ^attribute value

Predicate value

<<value…>>

{test…}

 

• Arguments

class-name

A symbol that names an object class that is visible to the active entry block. If you specify a class that has inherited subclasses, objects of those subclasses are also displayed.

attribute

An attribute that describes a characteristic of the objects to be displayed and contains the corresponding value. If you specify any attributes, you must also specify at least one value for each attribute.

If you specify a compound attribute, you can index it with a left bracket, an integer constant, and a right bracket ([index}).

predicate

Any of the valid match predicate.

value

This argument must be a scalar atom. Compound values, created with the COMPOUND function, are not allowed.

 

test

A value, a predicate followed by a value, or a disjunction of values:

• Examples

The following commands illustrate the syntax for compound attributes:

RuleWorks>ppwm box ^card-in-slot [3] keyboard

#28 [CHOOSE-SLOTS:PLACE-NONMEMORY] (BOX ^CARD-IN-SLOT (COMPOUND MEMORY MEMORY KEYBOARD ^CARD-IN-SLOT-OBJ-ID (COMPOUND #31 #39 #37 ^PART-NUMBER ki-9200 ^NAME Kiwi-9200 CPU Base Unit ^PRICE 999.95 ^IS-EXPANDED YES)

RuleWorks>ppwm box ^card-in-slot [+} memory

~28 {CHOOSE-SLOTS:PLACE-NONMEMORY] (BOX ^CARD-IN-SLOT (COMPOUND MEMORY MEMORY KEYBOARD) ^CARD-IN-SLOT-OBJ-ID (COMPOUND #31 #39 #37) ^part-NUMBER KI-9200 ^NAME Kiwi-9200 CPU Base Unit ^PRICE 999.95 ^IS-EXPANDED YES)

 

 

QUIT

Terminates execution of the current image and returns control to the operating system. If there are other actions in the rule, they are not executed. The ON-EXIT actions are not executed after a QUIT action. You can return a value with QUIT. Valid Arguments for QUIT include $FAILURE and $SUCCESS, as well as any integer. RuleWorks substitutes either 0 or 1, as appropriate for the operating system, for $FAILURE and $SUCCESS.

Entering QUIT at the command interpreter is equivalent to pressing Ctrl/Z on VMS systems, Ctrl/D on UNIX systems.

• Format (for action)

(QUIT [value-expr])

• Format (for command)

QUIT [return-value]

• Arguments

value-expr

The value returned by RuleWorks. This Argument is optional; it can be an expression that evaluates to a scalar value, $FAILURE, or $SUCCESS. This Argument can be used in rules only.

return-value

The value returned by RuleWorks. This Argument is optional; it can be a constant, $FAILURE, or $SUCCESS. You cannot use expressions or function calls (except to COMPOUND) as Arguments to any command.

• Example

The following command exits from the command interpreter and returns control to the operating system:

RuleWorks> QUIT

$

The following example uses the QUIT action to terminate execution with a return value indicating success.

(rule success

(context ^$ID <context> ^task complete)

-->

(remove <context>)

(quit $success))

When this rule fires, the QUIT action causes the run-time system to stop executing recognize-act cycles immediately. The compiler provides a warning when any actions follow RETURN or QUIT actions.

The entry block's ON-EVERY and ON-EXIT statements are not executed after a QUIT action.

• RBREAK

Controls breakpoints on rules and rule groups.

When used with no Arguments, the command displays a numbered list of the rules and groups that have breakpoints set. When used with the ON and OFF keywords, respectively, RBREAK sets and clears breakpoints for rules and groups. Breakpoints for rule groups are set or cleared for all rules in the group by a single command.

When the run-time system encounters a breakpoint on a rule, it finishes the current recognize-act cycle, displays a message in the following Format, and invokes the command interpreter:

%RUL-I-RBREAK, RBREAK encountered on rule[group] name
%RUL-I-BREAKNOTED, Execution paused by break.

• Format


ON
{
rule-name
rule-group-name
}...
OFF
{
rule-name
rule-group-name
number
}

The keywords and Arguments are optional. If you do not specify the name of a rule, the command displays the names of the rules and groups for which breakpoints are set.

• Arguments

rule-name

A symbol that names a rule. You can specify one or more.

rule-group-name

A symbol that names a rule group. You can specify one or more.

*

All rules and groups that have breaks set.

• Example

The following command displays the names of the rules of which breakpoints are set:

RuleWorks> rbreak

1 VERIFY-CONFIGURATION:MOUSE-PORT

2 POP-ACTIVE-CONTEXT

The next commands delete one breakpoint and sets another:

RuleWorks> rbreak off 2

RuleWorks> rbreak on choose-slots:place-nonmemory

The following command redisplays the names of the rules for which breakpoints are set:

RuleWorks> rbreak

1 VERIFY-CONFIGURATION:MOUSE-PORT

2 CHOOSE-SLOTS:PLACE-NONMEMORY

The following dialog shows what happens when the breakpoint is reached:

RuleWorks> run

%RUL-I-RBREAK, RBREAK encountered on rule CHOOSE-SLOTS:PLACE-NONMEMORY

%RUL-I-BREAKNOTED, Execution paused by break

 

RuleWorks> next

CHOOSE-SLOTS:PLACE-NONMEMORY #47 62 #28 65 #37 56

• REMOVE

Deletes one or more objects from working memory. The object must be visible to the active entry block. Once an object has been removed, it can no longer be accessed. However, variables bound to the values of attributes of that object can still be used.

Note: When you delete WMOs at the command interpreter prompt, the first Argument to the REMOVE command must be a constant. In contrast, when you delete WMOs in a rule, the first Argument to the REMOVE action can be a variable or a call to the GET function.

• Format (for action)

(REMOVE ID-expr... )

• Format (for command)

REMOVE {

Instance-id...

*
}

• Argument

ID-expr

A RuleWorks expression that evaluates to a value of type INSTANCE-ID, indicating the object to be deleted. You can specify one or more IDs. This Argument can be used in rules only.

instance-id

A constant of type INSTANCE-ID, indicating the object to be deleted. This Argument can be used only at the command interpreter level.

*

You can specify an asterisk (*) to delete all visible objects. Objects whose class declarations are neither contained in nor used by the active entry block remain in working memory.

• Example

The following command deletes all visible objects:

RuleWorks> REMOVE *

The following command deletes the objects whose identifiers are #3 and #4:

RuleWorks> REMOVE #3 #4

Consider the following rule:

(rule make-context-active

(context ^name <context-name> ^$ID <context-id>)

-->

(make active-context ^name <context-name>)

(remove <context-id>))

The REMOVE action deletes the object bound to the variable <CONTEXT-ID>.

• REMOVE-EVERY

Deletes all the working memory objects that are instances of the specified class or its subclasses. The class must be visible to the active entry block. Once an object has been removed, it can no longer be accessed. However, variables bound to values of attributes of that object can still be used.

• Format

(REMOVE-EVERY class-name... )

• Argument

class-name

An expression that evaluates to a symbol names an object class. The declaration of this class must be contained in or used by the active entry block.

You can also use the symbol $ROOT, to remove all visible objects.

• Example

The following example removes working-memory objects when the conflict set is empty:

(on-empty

(write |Sorry... Program error. No satisfied rules".| (crlf))

(remove-every control-context)

(remove-every local)

(remove-every input-thing)

(remove-every error)

(remove-every part)

(remove-every input-count)

(remove-every total-cost)

(quit 0))

• RESTORESTATE

Clears and then restores working memory, the conflict set, the GENATOM counter, and the INSTANCE-ID generator to the state recorded in a file produced by the SAVESTATE action or command.

The working memory objects contained in the SAVESTATE file must be visible to the active entry block. A run-time warning is generated if the files contains any objects whose class declarations are neither private to nor shared by the active entry block.

RESTORESTATE clears all working memory objects before loading the new state; therefore, variable bindings are lost.

After a RESTORESTATE action, the GENATOM and GENINT functions produce atoms that are different from any that were recorded in the saved file. They may repeat atoms that were generated before the RESTORESTATE action was executed.

• Format

(RESTORESTATE filespec )

• Argument

filespec

The file specification for a file previously produced by the SAVESTATE action or command. The action uses the contents of the file to restore the state of working memory and the conflict set. See Chapter 12 for restrictions on file names.

• Example

The following action clears and then restores the contents of working memory and the conflict set to the same state recorded in the file CONFIG.DAT.

(restorestate config.dat)

• RETURN

Stops the firing of rules in the current entry block, executes the ON-EXIT actions (if any), and passes control back to the caller of the entry block. The RETURN action is executed immediately, so any actions that follow it are not executed and a warning is generated.

This action has one optional Argument, the value to be returned. Your RETURN action(s) should match the RETURNS clause of your ENTRY-BLOCK declaration. For example, if your entry block has no RETURNS clause, a RETURN action with an Argument generates a compiler warning. Similarly, if your entry block declares a symbolic return value, a RETURN action with a numeric Argument generates a run-time warning.

RETURN actions are valid in entry blocks but not in rule blocks.

Executing more than one RETURN action generates a warning. If a value is being returned from the entry block, the value of the last RETURN action executed is used.

When you execute a RETURN command at the RuleWorks interpreter prompt, and the return is to a RuleWorks entry block, no action of the caller is executed before the prompt reappears. This allows you to see working memory in exactly the state the callee left it.

• Format (for action)

(RETURN) [value-expr] )

• Format (for command)

RETURN [value]

• Arguments

value-expr

The value returned by the entry block. This Argument is optional; it can be any expression that evaluates to the structure (scalar or compound) and domain (integer, symbol, and so on) specified in the ENTRY-BLOCK declaration.

value

The value returned by the entry block. This Argument is optional; it may be a constant or a call to the COMPOUND function. You cannot use any other functions or expressions at the command line.

• Example

The following example shows a simple rule that returns a value:

(rule when-done-return-number-filled

(task ^name last-step)

- (order ^status unfilled)

(totals ^filled-orders <count>)

-->

(return <count>))

• RJUST

Causes the WRITE action to right-justify output in a field of a specified width. This function is useful for writing a column of numbers with decimal positions aligned.

Note: The RJUST function is valid only inside the WRITE action.Calls to the RJUST function can follow calls to the CRLF and TABTO functions but must directly precede the value being written.

• Format

(RJUST width )

• Argument

width

An integer expression (anything that evaluates to an integer) that indicates the width of the field in which output is to be placed. If the output being written requires more character positions than you specify for the field, the WRITE action behaves as if the RJUST function had not been specified. That is, the action inserts one space and then writes the output.

• Example

The following WRITE action writes a vertical list of numbers right-justified in a column 10 characters wide:

(WRITE (CRLF) (RJUST 10) |10.06|

(CRLF) (RJUST 10) |2.45|

(CRLF) (RJUST 10) |56.00|

(CRLF) (RJUST 10) |250.00|)

The output is:

10.06

2.45

56.00

250.00

• RULE

Executes right-hand-side actions when left-hand-side conditions are met and the rule has been selected from the conflict set.

• Format

(RULE rule-name)

(condition-element)...

(action )... )

• Arguments

rule-name

A unique symbol that names the rule being created. The symbol cannot be the name of another rule, a rule-group, a method, or a catcher that already exists in the entry block.

condition-element

A specified pattern against which working memory objects can be matched. Condition elements can be negative, can contain conjunctions and disjunctions, and can bind variables that are used in other condition elements and in actions on the right-hand side.

You can specify one or more condition elements. You cannot put a negative CE first. See Chapter 3 for information on CEs.

action

Any RHS action. You can specify one or more actions. See Chapter 4 for information on actions.

• Example

The following rule, named CLOSE-INPUT-FILE:DO-IT, contains three CEs and three actions. The second CE binds a $ID variable., <MY-INPUT-THING>, which is deleted by the REMOVE action. The third CE binds an attribute variable, <C>, which is used in the WRITE action.

(rule close-input-file:do-it

(active-context ^name close-input-file)

(input-thing ^item END-OF-FILE ^$ID <my-input-thing> )

(input-count ^count <c>)

-->

(closefile infil)

(remove <my-input-thing>)

(write (crlf) |Read| (<c> - 1) |items from input.| (crlf)))

• RULE-BLOCK

Names a collection of rules so that they can be shared among multiple entry blocks. Rule blocks may contain rules, catchers, and declarations, but no RETURN actions and no ON- constructs.

A rule block must be activated by a RuleWorks entry block. Rule blocks can use declaration blocks but they cannot activate other rule blocks.

The rules in a rule block cannot match objects of classes declared inside the entry block; they can match only objects of classes declared inside the rule block or in a declaration block used by the rule block. Likewise, rules in the entry block cannot match objects of classes declared inside the rule block.

Each rule block can have its own STRATEGY clause. However, all rule blocks activated by an entry block must have the same strategy as that entry block. It is a run-time warning to activate rule blocks that have different strategies.

The block must be closed with an END-BLOCK declaration.

• Format

(RULE-BLOCK block-name )

[(USES decl-block-name…)]

[(STRATEGY

)])

• Argument

block-name

A symbol that names the block. This name must be distinct from all other block names in your program and must also be a valid C function name:

cannot contain the characters "<>[]%^-

less than 32 characters long

different from all C keywords

• Clauses

USES

Indicates which declaration blocks are shared by the entry block. This clause is optional.

decl-block-name... A symbol that names a declaration block. You can specify one or more declaration blocks.

STRATEGY

Specifies the conflict-resolution strategy (see Chapter 1). This clause is optional. If you do not declare a strategy, the default MEA is used.

LEX The lexicographic-sort strategy.

MEA The means-ends analysis strategy.

• RULE-GROUP

Names a collection of rules inside a single entry block or rule block. If you put each MEA group in a separate rule group, you can then enable TRACE for rule groups and see output for the MEA groups without seeing each individual rule.

Rule groups may contain rules and catchers, but no declarations, no methods, and no ON- constructs.

The rules in a rule group can match objects of classes declared in the containing block and objects of classes declared in a declaration block that is used by the containing block.

The group must be terminated with an END-GROUP declaration.

• Format

(RULE-GROUP group-name )

• Argument

group-name

A symbol that names the group. This name must be distinct from the names of all other groups, rules, and catchers in the containing block.

• RUN

Causes the run-time system to execute recognize-act cycles. You can optionally specify the number of recognize-act cycles the system executes.

RuleWorks entry blocks start running by default. Use the DEBUG action or the Debug compiler switch to pause execution and invoke the RuleWorks command interpreter.

• Format

RUN [integer]

• Argument

integer

The number of global recognize-act cycles the run-time system is to execute. This Argument is optional. If you do not specify an integer, the run-time system executes recognize-act cycles until no rules are satisfied or until a RETURN or QUIT action, or a breakpoint interrupts execution.

Note: If a breakpoint interrupts program execution, the run-time system does not execute the number of recognize-act cycles indicated by the integer.

• Example

The following command starts executing recognize-act cycles:

RuleWorks> RUN

The following command executes four recognize-act cycles:

RuleWorks> RUN 4

• SAVESTATE

Copies to a file the state of working memory, the conflict set, the GENATOM and GENINT counter, and the INSTANCE-ID generator. You can later use the ADDSTATE or RESTORESTATE action or command to add to or overwrite the current memory with the contents of the file.

Only objects that are visible to the active entry block are saved.

• Format

(SAVESTATE filespec )

• Argument

filespec

The file specification for the file to which the state of working memory and the conflict set is to be copied.

• Example

The following action copies the state of working memory and the conflict set to the file CONFIG.DAT.

(savestate config.dat)

The equivalent command is:

RuleWorks> savestate config.dat

• SHOW SPACE

Displays information about working memory and the RuleWorks symbol table. The information consists of the current number of objects and symbol-table entries, the amount of memory that these currently occupy, and the largest value that these have reached during this execution of the program.

• Format

SHOW SPACE

• Arguments(NONE)
• Example

The following example shows the SHOWSPACE command:

RuleWorks> SHOW SPACE

WORKING-MEMORY OBJECTS SYMBOL TABLE ENTRIES

Current number - 10 Current number - 97

Current space used - 0.6 Kbytes Current space used - 4.4 Kbytes

Maximum number - 12 Maximum number - 97

Maximum space used - 0.7 Kbytes Maximum space used - 4.4 Kbytes

• SHOW VERSION

Displays the current version of the RuleWorks compiler (and the copyright notice).

• Format

SHOW VERSION

• Arguments(NONE)
• Example

The following

RuleWorks> sho ver

RuleWorks ä - Version 2.0 EFT1 (11-18-94)

Copyright ã 1994-1995 Digital Equipment Corporation. All Rights Reserved.

• SPECIALIZE

Converts an instance of a parent class to an instance of a descendent class. The converted object's INSTANCE-ID does not change as a result of this action. You can also set or change any attributes belonging to the descendent class.

Note: When you convert WMOs at the command interpreter prompt, the first Argument to the SPECIALIZE command must be a constant. In contrast, when you convert WMOs in a rule, the first Argument to the SPECIALIZE action can be a variable or a call to the GET function.

• Format (for action)

(SPECIALIZE ID-variable new-class-name-expr

[ {attribute-name-expr value-expr}... ] )

• Format (for command)

SPECIALIZE instance-id new-class-name

[ {attribute-name value}... ]

• Arguments

ID-variable

An expression of type INSTANCE-ID, indicating the object to be specialized. This Argument can be used in rules only.

new-class-name-expr

An expression that evaluates to a symbol that names an object class that inherits from the current class of the object being specialized.

attribute-name-expr

A symbol or bound variable that evaluates to an attribute declared in or inherited by the new class. This Argument is optional; if you do specify an attribute, you must also specify a value for it.

You can specify any number of attribute-value pairs.

value-expr

Any valid RuleWorks expression that evaluates to the same structure as the attribute.

instance-id

A constant of type INSTANCE-ID, indicating the object to be specialized. The object must be visible to be active entry block. This Argument can be used only at the command interpreter level.

new-class-name

A symbol that names an object class that inherits from the current class of the object being specialized.

attribute-name

A symbol that names an attribute declared in or inherited by the new class. This Argument is optional; if you do specify an attribute, you must also specify a value for it.

You can specify any number of attribute-value pairs.

value

A value that has the same structure as the attribute.

• Return Value

The SPECIALIZE action returns the INSTANCE-ID atom that identifies the converted object.

• Example

The following rule shows one possible use of the SPECIALIZE action:

(RULE animal-now-identified-as-a-zebra

; if current class is the generic class ANIMAL

(animal ^$ID <My-animal> ^$object-class animal ^name <n>)

(identification ^name <n> ^is-a zebra)

-->

(SPECIALIZE <My-animal> zebra; new class is ZEBRA

^inter-breeds-with (compound horse donkey)))

• SQL-ATTACH

Specifies the database of interest by executing a DECLARE SCHEMA statement. You can specify the source of the schema either by providing the database filespec itself or by providing a pathname to the CDD schema definition.

Note: that the actual attachment to the database usually does not occur until the first executable SQL statement after this action is processed.

 

• Format

SQL-ATTACH database-spec ( DBKEY-scope ]

 

• Arguments

Database-spec

This argument must be either FILENAME db-filespec or PATHNAME db-pathname. The keyword FILENAME may be omitted; the keyword PATHNAME is required.

A logical name may be used for all or part of the database filespec or for the CDD pathname.

DBKEY-scope

A keyword that specifies the duration of validity of database key values, either TRANSACTION or ATTACH. ATTACH scoping means that a database key value is valid for the entire time your program is attached to a given database, rather than just for the duration of a single transaction. TRANSACTION scoping is the default.

 

• Examples

The following example uses the FILENAME method. MY_DB is a logical name pointing to the complete filespec for the database.

 

(SQL-ATTACH FILENAME MY_DB)

The next example shows the same attachment except that the scope or duration of DBKEY validity is the total time your program is attached to the database, rather than the duration of the transaction as in the previous example (by default).

 

(SQL-ATTACH FILENAME MY_DB ATTACH )

 

 

 

 

• SQL-COMMIT

Completes the current SQL transaction and makes permanent any changes made to the database during the transaction. This action executes a COMMIT statement.

 

• Format

SQL-COMMIT

 

• Arguments

None

 

• SQL-DELETE

Deletes all or selected records from a specified database table, by executing a DELETE FROM statement. This action does not remove any RuleWorks objects; it is up to you to use REMOVE actions to do that.

The SQL-DELETE action can be executed only within the context of a READ WRITE transaction, which you must explicitly start with an SQL-START action.

 

• Format

SQL-DELETE table-name [WHERE-clause]

 

• Arguments

table-name

Specifies the database table from which rows are to be deleted.

WHERE-clause

Optionally specifies which records are to be deleted within the target table. If the where-clause is omitted, the default is to delete all records in the table specified in the first argument.

 

• Examples

The first example deletes all records in table W1:

 

(SQL-DELETE W1)

The next example deletes only those records in table W1 that satisfy the WHERE clause:

 

(SQL-DELETE W1 | WHERE fld1 = 10 AND fld2 = 'some text' | )

The records deleted are those with field fld1 equal to the value 10, and field fld2 equal to the string 'some text'. All other records in W1 are unaffected.

• SQL-DETACH

Detaches your program from any database previously attached by an SQL-ATTACH action. This action executes a FINISH statement and a COMMIT statement on the current transaction, if any.

 

• Format

SQL-DETACH

 

• Arguments

None.

 

• SQL-FETCH-EACH

For each selected database record, binds field value(s) to specified RuleWorks variable(s) and then performs one or more RHS actions. This action executes a SELECT statement.

You can create or change instances of any OBJECT-CLASS in the RHS actions performed by the SQL-FETCH-EACH action. The OBJECT-CLASS does not have to match the database table name, nor do the attribute names have to match the database field names.

 

• Format

SQL-FETCH-EACH <var>... (select-expr)

(RHS-action)...

 

• Arguments

<var>

One or more RuleWorks variables to which database field values are to be bound. These variables must not be bound prior to the SQL-FETCH-EACH action. They can be used only in the RHS actions provided as the third argument.

select-expr

An SQL select expression that limits the fetch to specific database table(s) and record(s) and specifies which database fields are to be fetched. This expression can include variables bound prior to the SQ~FETCH-EACH action (either on the LHS or RHS), but cannot include variables specified in the first argument.

RHS-action

One or more RuleWorks RHS actions to be performed for each database record fetched. Note that these actions may not include any other SQL interface actions.

These actions can use both variables bound prior to the SQL-FETCH-EACH action and variables specified in the first argument. If these actions bind any variables, those bindings are maintained after the SQL-FETCH-EACH action is executed.

 

• Examples

The first example fetches records from database table tbl_1, and binds the values of fields fld1 and fld2 to the RuleWorks variables <v1> and <v2>. These variables are then used in two MAKE actions, creating new instances of classes W1 and W2. The actions are repeated for each database record that satisfies the FROM and WHERE clauses of the select expression.

 

(SQL-FETCH-EACH <v1> <v2> (SELECT fld1, fld2 FROM tbl_1 WHERE fld3 = 1)

(MAKE w1 ^a1 <v2> ^a2 tbl_1)

(MAKE w2 ^a3 <v1> ^a4 (<v1> + <v2>)))

The previous example uses symbols in the select expression. The following example uses RuleWorks variables that are (presumably) bound earlier in the rule that contains this SQL-FETCH-EACH action. The optional vertical bars ( | ) around the constant parts of the select expression allow the compiler to generate more efficient code.

 

(SQL-FETCH <v1> <v2> (|SELECT * FROM| <table-name> |WHERE fld3= |<val>)

(MAKE w1 ^a1 <v2> ^a2 tbl_1)

(MAKE w2 ^a3 <v1> ^a4 (<v1> + <v2>)))

In this example, all the fields in the database are selected, because of the wildcard (*). However, only the first two fetched are used. Any extra field values are ignored.0

 

 

• SQL-FETCH-AS-OBJECT

Makes WMOs from selected database records by executing a SELECT statement.

This action creates instances of a single OBJECT-CLASS only, even if it is retrieving data from multiple tables (for example, a join between source tables). The OBJECT-CLASS matches the (first) table name specified in the FROM clause of the select expression. SQLFETCH-AS-OBJECT creates one new object from each database record selected.

The database field names and the attribute names of the OBJECT-CLASS must match. Any selected fields that do not have a corresponding attribute are ignored. Any attributes that do not have a corresponding field are set to their DEFAULT values (if one was declared) or NIL. Attributes that correspond to fields whose value is "missing" are also set to NIL.

You can use the SQL-FETCH-AS-OBJECT action as the value argument to a BIND action. The variable argument of the BIND action is bound to a compound value that contains the INSTANCE-IDs of all the fetched WMOs.

 

• Format

SQL-FETCH-AS-OBJECT select~expr

 

• Argument

select-expr

An SQL select expression that restricts the fetch to specific database records and specifies which database fields are to be fetched. The database table specified in the select expression is used as the object class name for the objects created by the SQL-FETCH-AS-OBJECT operation.

 

• Return Value

When used as in the second argument to the BIND action, the SQL-FETCH-AS-OBJECT action returns a compound value that contains the INSTANCE-IDs of all the objects created.

 

• Examples

In the first example, selected records from table W1 are fetched and used to create objects. Only records with field fld1 having a value less than field fld2 are fetched. (This is a numeric comparison; the last two examples use character string fields.)

 

(SQL-FETCH-AS-OBJECT SELECT * FROM W1 WEERE fld1 < fld2 )

Any objects created by this action are instances of OBJECT-CLASS W1, as specified in the FROM clause. All record fields are used and mapped into object attributes, as requested by the use of an asterisk (*) in the select expression.

 

(SQL-FETCH-AS-OBJECT SELECT fld1, fld2, fld3 FROM W1 WHERE fld1 < fld2)

The example above refines the first example by fetching fields fld1, fld2, and fld3 only. Again, as in the previous example, only records with field fld1 value less than that of fld2 are fetched.

 

(SQL-FETCH-AS-OBJECT SELECT DISTINCT fld1, fld2 FROM W1 WHERE fld1 < fld2)

 

 

 

This example illustrates the DISTINCT qualifier, which restricts the new W1 objects to unique combinations of fld1 and fld2 values. Without the DISTINCT qualifier this action can yield multiple duplicate objects, depending on the database contents.

 

(SQL-FETCH-AS-OBJECT SELECT fld1, fld2, DBKEY From W1 WHERE fld1 < fld2 )

This example fetches the DBKEY for each database record, along with the fld1 and fld2 values. The OBJECT-CLASS declaration for W1 in this case must include a DBKEY attribute, so that the action has a place to put the DBKEY value.

 

(SQL-FETCH-AS-OBJECT SELECT W1. *, DBKEY FROM W1 WHERE fld1 < f1d2)

The action above shows how to select all fields and capture the DBKEY values. The required syntax is not the SELECT *, DBKEY that you might expect.

 

(SQL-FETCH-AS-OBJECT SELECT * FROM W1 WHERE fld1 = 'abc' AND fld2 = '<var>')

This example uses string field comparisons in the select expression. Only those records that have fld1 equal to the string 'ABC' and fld2 equal to the string bound to the RuleWorks variable <var> are selected and fetched. Note that RuleWorks automatically converts the symbol 'abc' to the string 'ABC'.

 

(bind <x> (SQL-FETCH-AS-OBJECT

SELECT * FROM W1 WHERE fld1 = 'abc' AND fld2 = '<var>'))

This example shows the previous SQL-FETCH-AS-OBJECT action used as an argument to the BIND action.

• SQL-INSERT

Stores new records in the specified database table by executing an INSERT statement. The fields to be set, and their new values, are provided in the second argument.

This action can be executed only within the context of a READ WRITE transaction, which you must explicitly start with an SQL-START action.

 

• Format

SQL-INSERT table-name SQL-expr

 

• Arguments

Table-name

Specifies the database table into which the new records are to be inserted.

SQL-expr

An SQL expression that specifies the target fields and their values.

 

• Examples

In this example a new record is created in database table tbl_l, with its field fld2 set to 123 and its field fld5 set to the string 'test'. The SQL expression is enclosed in vertical bars because it includes parentheses.

 

(SQL-INSERT tbl_1 | (f1d2, fld5) VALUES (123, 'test') |)

The next example is similar to the previous one, except that one of the field names is defined at run-time by the RuleWorks variable <v2> and the value for field fld5 is given by the RuleWorks variable <v2>.

 

(SQL-INSERT tbl_1 |(| <v1> |, fld5) VALUES (456,| '<v2>' |)| )

Since fld5 is a character (string) field, the value substituted for <v2> must be enclosed in single quotes.

Note: that both unquoted and quoted variables must be preceded and followed by whitespace, as in this example. Also, parentheses that are passed to SQL must be enclosed in vertical bars.

• SOL-INSERT-FROM-OBJECT

Stores the contents of a specified object in a new database record by executing an INSERT statement. The record is inserted into the database table that has the same name object's OBJECT~CLASS. The values of the object's ^$ID and ^$INSTANCE-OF attributes are not written to the database, even if the database explicitly provides fields with those names.

This action can be executed only within the context of a READ WRITE transaction, which you must explicitly start with a SQL-START action.

 

• Format

SQL-INSERT-FROM-OBJECT <^$ID-variable>

 

• Argument

<^$ID-variable>

A variable bound to the value of the ^$ID attribute of the object to be stored.

 

• Example

In this example the object identified by the <W> object identifier is inserted into the database, into the table having the same name as the <W> object's OBJECTCLASS- After the SQL-INSERT-FROM-OBJECT, you are free to remove the <W> object or leave it in working memory.

 

(SQL-INSERT-FROM-OBJECT <W>)

• SQL-ROLLBACK

Undoes any changes to the database made during the current transaction and completes the transaction. This action executes a ROLLBACK statement.

 

• Format

SQL-ROLLBACK

 

• Arguments

None.

• SQL-START

Executes a SET TRANSACTION statement to start a transaction with the specified options. These options can include a READ ONLY versus a READ WRITE transaction, and whether to retain any locks obtained on records during the course of the transaction.

You end the transaction started by this action with an SQL-COMMIT, SQL-DETACH, or SQL-ROLLBACK action.

 

• Format

SQL-START [txn-options]

 

• Argument

Txn-options

Optional list of desired SQL transaction options. If this argument is not provided, a READ ONLY transaction is the default.

 

• Examples

The first example starts a READ ONLY transaction by default, because it has no transaction options.

 

(SQL-START)

The following example shows an update transaction whose options request that any records accessed during the transaction have locks retained on them, so that the records may be updated again (in protected write mode).

 

(SQL-START |READ WRITE RESERVING W1 FOR PROTECTED WRITE| )

The vertical bars in this example are not required, but they do make the action more efficient.

• SQL-UPDATE

Modifies the contents of selected database records, where the fields to be modified and their new values are specified in the second argument.

This action can be executed only within the context of a READ WRITE transaction, which must be explicitly started by an SQL-START action.

 

• Format

SQL-UPDATE table-name SET-clause [WHERE-clause]

 

• Arguments

Table-name

Specifies database table to be modified.

SET-clause

An SQL expression to define which fields are to be updated within the target table, and the new values for these fields.

WHERE-clause

An optional select expression that specifies which database records are updated.

If it is omitted, the default action is to update all records in the specified table.

 

• Examples

The first example sets the numeric fld1 field value in all W1 table records, if any, to zero, and sets the char field fld2 to 'SOME TEXT')

 

(SQL-UPDATE W1 SET fld1 = 0, fld2 = 'some text' )

The second example modifies any and all records in the W1 table whose previous field a1 value was the old value <val> (bound in LHS of the rule) and field whose field a2 value was <va12>. These records have al set to <new-val> (bound on the RHS of the rule).

 

(rule sql-update-example

(W1 ^$ID <W1> ^a1{ < 10 <val> } ^a2 <val2>

à

(bind <new-val> (<val> + 10))

(modify <W1> ^a1 <new-val>)

(SQL-UPDATE W1 SET al = <new-val> WHERE al = <val>, a2 = <val2> ))

• SQL-UPDATE-FROM-OBJECT

Uses the attribute values of an object to modify corresponding data fields in one or more existing database records. The values of the object's ^$ID and ^$INSTANCE-OF attributes are not written to the database, even if the database explicitly provides fields with those names.

This action can only be executed within the context of a READ WRITE transaction, which you must explicitly start with an SQL~START action.

 

• Format

SQL-UPDATE-FROM-OBJECT <$ID-variabl> [where-clause ]

 

• Arguments

<$ID-variable>

A variable bound to the ^$ID attribute of the object to be used. The OBJECT-

CLASS name of the associated object specifies the database table that is modified.

WHERE-clause

Optionally identifies which database records are to be modified using the object attribute values. If it is omitted, the default action is to update all records.

 

• Examples

The first example uses the attribute values in the object whose INSTANCE-ID is bound to <W> to modify database records whose field fld1 is equal to the value bound to the RuleWorks variable <var1> and whose character field fld2 is equal to the value bound to <var2>. This WHERE clause may or may or not be sufficiently restrictive to make the SQL-UPDATE-FROM-OBJECT action modify only one database record.

 

(SQL-UPDATE-FROM-OBJECT <W> WHERE fld1 = <var1> AND f1d2 = '<var2>')

The database table containing the record(s) to be modified is the table with the same name as the OBJECT-CLASS of the object identified by the $ID variable <W1>. Note that the white space around the quoted variable ('<var2>' in this example) is required.

 

(rule sql-update-from-object-example

(W1 ^$ID <W1> ^a1 { < 10 <val> ) ^a2 <val2>)

à

(modify <w1> ^a1 (<val> + 10))

(SQL-UPDATE-FROM-OBJECT <w1> WHERE al = <val> AND a2 = <val2>))

The above example modifies any and all records in the W1 table whose previous field al value was the old value <val> (bound in LHS of the rule) and whose field a2 value was <val2>. These records have field al set to the newly-computed value of the ^A1 attribute (the object was modified just before the SQL-UPDATE-OBJECT action).

• SUBCOMPOUND

Creates a new compound value that is a subrange of an existing compound value. SUBCOMPOUND is a stateless function and can be used on the LHS or RHS.

• Format

(SUBCOMPOUND compound-val index-1 index-2 )

• Arguments

compound-val

The compound value from which a subrange is returned. This Argument can be a bound compound variable or a function that returns a compound value.

index-1 index-2

The positions of the first and last elements in the subrange, respectively. These Arguments can be either of the following:

• Anything that evaluates to an integer greater than zero
• The special symbol $LAST

The index-1 Argument must be less than or equal to the index-2 Argument.

Note: that $LAST may not be used as part of an expression; it must stand alone.

• Example

The following rule uses the SUBCOMPOUND function to remove the first element of a compound value:

(rule pop-stack

(agenda ^$ID <my-agenda> ^tasks <tasks> )

-->

(modify <my-agenda> ^tasks (SUBCOMPOUND <tasks> 2 $LAST)))

• SUBSYMBOL

Creates a new symbol value that is a fragment of an existing symbol value. SUBSYMBOL is a stateless function and can be used on either the LHS or RHS.

• Format

(SUBSYMBOL symbol-val index-1 index-2 )

• Arguments

symbol-val

The symbol value from which a fragment is returned. This Argument can be a bound symbol variable or a function that returns a symbol value.

index-1 index-2

The positions of the first and last characters in the return value, respectively. These Arguments can be either of the following:

• Anything that evaluates to an integer greater than or equal to one
• The special symbol $LAST

The index-1 Argument must be less than or equal to the index-2 Argument.

Note that $LAST may not be used as part of an expression; it must stand alone.

Return Value

A symbol that contains the specified fragment of the input symbol. If the fragment is specified incorrectly or does not exist, the function returns the empty symbol value, 11.

• SYMBOL

Converts any value into a symbol. SYMBOL is a stateless function and can be used on either the LHS or RHS.

• Format

(SYMBOL value-expr )

• Argument

value-expr

An expression that evaluates to the value to be converted.

 

• Return Value

The symbolic atom that corresponds to the specified value. In other words, the atom of type Symbol whose print form is identical to the print form of the argument.

The print form of a compound value includes a space between the elements, but does not include the function name COMPOUND or its parentheses. If the compound is too long to fit in a symbol, it is truncated.

 

• Example

NYI

• SYMBOL_LENGTH

Returns the number of characters in a symbol. SYMBOL-LENGTH is a stateless function and can be used on either the LHS or RHS.

(See also the LENGTH function, which returns the number of elements in a compound value.)

• Format

(SYMBOL-LENGTH symbol-val )

• Argument

symbol-val

The symbolic value to be measured. This Argument can be a bound symbolic variable or a function that returns a symbolic value.

 

• Return Value

An integer that specifies the number of characters in the symbol.

TABTO

Causes the WRITE action to start writing output in a specified column.

Note: The TABTO function is valid only inside the WRITE action.

• Format

(TABTO column )

• Argument

column

An integer expression that indicates the column in which the WRITE action is to start writing output. If you specify a column that is to the left of the last column in which output is written, the WRITE action writes the output on a new line, starting at the specified column.

• Example

The following WRITE action displays the headers of three columns:

(WRITE (CRLF) (TABTO 10) NUMBER

(TABTO 25) AMOUNT

(TABTO 40) DATE)

The output is:

NUMBER AMOUNT DATE

• TRACE

Displays or changes the run-time system's trace setting, which controls the amount of information the system displays while executing a program.

Note: The TRACE action in source code is effective only when the entry block that contains it was compiled with the DEBUG qualifier set to YES or MAYBE.

• Format

TRACE

[

ON trace-name...

OFF *

]

• Arguments

trace-name

The name of a trace setting, which are shown in the table, Trace Settings. You can supply one or more names.

*

All trace settings shown in the table, Trace Settings.

Table 28. Trace Settings

Name Information Displayed

{ENTRY-BLOCK} Entry blocks being entered or exited

{EB}

RULE Global and local rule firing counts and instantiation executed

{RULE-GROUP} Rule group name added to RULE trace information
{RG}

WM Objects being created, changed, or deleted from working memory

CS Instantiations into and out of the conflict set

PM Rules into and out of program memory

 

 

• Example

The following command displays the current trace level:

RuleWorks> TRACE

ENTRY-BLOCK RULE-GROUP RULE WM

The following commands change and redisplay the trace setting:

RuleWorks> TRACE OFF RG RULE

RuleWorks> TRACE

ENTRY-BLOCK WM

For examples of trace output, see Chapter 9.9.

• WBREAK

Controls breakpoints on WMOs that match a specified pattern.

When used with no Arguments, the command displays a numbered list of the object patterns that have breakpoints set. When used with the ON and OFF keywords, respectively, RBREAK sets and clears breakpoints for object patterns.

Any rule that makes, copies, modifies, specializes, or removes an object that matches a pattern triggers the breakpoint on that pattern. When the run-time system encounters a breakpoint on an object pattern, it completes the current recognize-act cycle and displays messages in the format below, and invokes the command interpreter:

%RUL-I-WBREAK, WBREAK encountered on class-name #instance-id
%RUL-I-BREAKNOTED, Execution paused by break

• Format

WBREAK

[

ON object pattern

OFF {

object-pattern

number

*

}

]

• Arguments(Keywords)

ON

Sets a new breakpoint on an object pattern.

OFF

Clears the existing breakpoint on an object pattern.

• Arguments

object-pattern

An expression, similar to a CE, that defines which objects cause a break. The object pattern must include the name of an object class that is visible to the active entry block, and may include any number of attribute-value tests.

If the class name in the object pattern has inheriting subclasses, objects of those subclasses also match the pattern.

number

An integer corresponding to an object pattern that currently has a breakpoint set. You get a list of integers and their patterns when you give the WBREAK command with no Arguments.

*

You can use an asterisk (star) with the OFF keyword to mean "clear all breakpoints on WMOs".

• Example

The following is an example of the WBREAK command:

RuleWorks> wbreak on control-context

RuleWorks> run

<FAC>-I-WBREAK, WBREAK encountered on ACTIVE-CONTEXT #2
=>WM: #2 [MAKE-CONTEXT-ACTIVE] (ACTIVE-CONTEXT ^NAME TASKS-TO-DO)
<=WM: #1 [ | main | ON-ENTRY] (CONTEXT ^NAME TASKS-TO-DO)

%RUL-I-BREAKNOTED, Execution paused by break

RuleWorks>

• WHILE…DO…

Repeatedly executes one or more RHS actions as long as a relational expression remains true. In other words, provides a loop in the flow of control.

 

• Format

(WHILE (rel-expr)

DO RHS-action…)

 

• Arguments

rel-expr

A relational expression that determines whether RHS actions are to be executed. This argument must evaluate to eithe rtrue or false. It may not contain any SQL functionc.

Note: RuleWorks does not have Boolean values. Therefore, this argument must be a comparison of two expressions. It must not be a single value. For example, RuleWorks does not allow (WHILE (TRUE) DO…).

RHS-action

Any RuleWorks action. You can specify any number of actions.

 

• Clause

DO

Specifies the actions that are to be executed as long as the relational expression remains true. This clause is required.

 

• Example

The example below illustrates a simple relational expression in a WHILE

 

(WHILE (<sun_shines> = true) DO

(make hay))

 

• WM

Displays the objects whose INSTANCE-IDs are specified. The output includes the following information about each object:

· Its INSTANCE-ID

· The name of the construct that last modified the object (for example, a rule or ON- clause). If you last modified the object at the interpreter prompt, the construct name is the symbol RUL.

· Its attributes' names and their values

Scalar attributes whose value is NIL, and compound attributes whose value is (COMPOUND), are not displayed unless you have declared a DEFAULT value for the attribute.

The system displays this information in the following format:

#instance-id [block-name~rule-name] (class-name attribute-1 value-1 attribute-2 value-2) ...

• Format

WM [ instance-id ]...

• Arguments

instance-id

An INSTANCE-ID atom that identifies an object that the command is to display. You can specify one or more INSTANCE-IDs.

The Argument is optional. If you do not specify any INSTANCE-IDs, the command displays all the visible WMOs.

• Example

The following command displays the objects whose identifiers are #3 and #4:

RuleWorks> WM #3 #4

???

???

• WMHISTORY

Displays the history of a specified object, that is, which rules set the attribute values. You must specify the INSTANCE-ID of the desired object; you may also specify a particular attribute.

When the WMHISTORY command displays an entire object, the output includes the following information:

· INSTANCE-ID

· Name of the rule that last modified the object

· Object class name

· Name of the rule that originally created the object

· Name and value of each attribute

· Name of the rule that set the current value of each attribute

Scalar attributes whose value is NIL, and compound attributes whose value is (COMPOUND), are not displayed unless you have declared a DEFAULT value for the attribute.

The system displays this information in the following format:

#instance-id [rule-name-0] (class-name [rule-name] { ^attr-1 value-1 [rule-name-1] } ...

When the WMHISTORY command displays a single attribute, the output includes the following information:

· INSTANCE-ID

· Name of the rule that last modified the object

· Name and value of the specified attribute

· Name of the rule that set the current value of the specified attribute

The system displays this information in the following format:

#INSTANCE-ID [rule-name-0] ^attribute value [rule-name-n]

Note: By default, WMHISTORY is disabled. You must turn it on with the ENABLE command before you can use it.

• Format

WMHISTORY instance-id [ ^attribute ]

• Arguments

instance-id

The INSTANCE-ID of the object to be displayed.

attribute

An attribute that describes a characteristic of the object to be displayed. This Argument is optional. You can use at most one attribute name in a WMHISTORY command.

• Example

The following example shows the history of an entire object:

RuleWorks> ENABLE WMHISTORY

RuleWorks> RUN

.
.
.

RuleWorks> WMH #28

#28 [CHOOSE-SLOTS:PLACE-NONMEMORY] (BOX [CONVERT-PACKAGES-TO-PARTS:HOME-KIWI] ^CARD-IN-SLOT (COMPOUND MEMORY MEMORY KEYBOARD FD-35) [CHOOSE-SLOTS:PLACE-NONMEMORY] ^CARD-IN-SLOT-OBJ-ID (COMPOUND #31 #39 #37 #45) [CHOOSE-SLOTS:PLACE-NONMEMORY] ^NAME BOX [EXPAND-PART-SKELETONS:BOX] ^PART-NUMBER KI-9200 [EXPAND-PART-SKELETONS:BOX] ^PRINTNAME Kiwi-9200 CPU Base Unit [EXPAND-PART-SKELETONS:BOX] ^PRICE 999.95 [EXPAND-PART-SKELETONS:BOX] ^IS-EXPANDED YES [EXPAND-PART-SKELETONS:BOX])

This example shows the history of an attribute:

RuleWorks> WMH #28 ^CARD-IN-SLOT

#28 [CHOOSE-SLOTS:PLACE-NONMEMORY] (BOX [CONVERT-PACKAGES-TO-PARTS:HOME-KIWI] ^CARD-IN-SLOT (COMPOUND MEMORY MEMORY KEYBOARD FD-35) [CHOOSE-SLOTS:PLACE-NONMEMORY])

• WRITE

Sends output from a program to the terminal or a file. By default, the WRITE action sends output to the terminal. To send output to a file, you can do one of the following:

· Specify the WRITE action with a file identifier

· Change the default destination for the WRITE action, using the DEFAULT action or command

• Format

(WRITE [file-id] RHS-expression )

• Arguments

file-id

The file identifier of the destination file for the WRITE action's output. This Argument is optional. If you do not specify the Argument or if the name you specify is not associated with an open output file, the output is sent to the current default for the WRITE action (set with the DEFAULT action or command).

RHS-expression

A right-hand-side expression that represents the output. The action evaluates the expression and sends the output to the terminal or a file. Use the following functions to format the output:

 

Table 29. WRITE Functions

Function Description

CRLF Carriage return/line feed

TABTO Tab

RJUST Right-justify

If you do not use these functions, the WRITE action displays its output on the current output line with one space between values. For information about using these functions, see Chapter 4.

• Example

The following WRITE action is from the rule OUTPUT-HARDWARE-OPTIONS:WITH-SLOT:

(write (crlf) <num> (tabto 12) RuleWorks

(tabto 50) |in Slot:| <slot-num> (tabto 65) (rjust 10) <price>) )

This action produces the following output:

FD-35 3.5" Floppy Disk Drive in Slot: 4 99.95

KB-9200 108-Key Keyboard with Mouse Port in Slot: 3 99.95

MS-9200 Kiwi-9200 Memory card in Slot: 2 129.95

MS-9200 Kiwi-9200 Memory card in Slot: 1 129.95