RuleWorks

www.RuleWorks.co.uk

RuleWorks Reference Dictionary

This chapter contains complete descriptions of all constructs in the RuleWorks language, including tables and complete descriptions. The following tables, presented at the beginning of this chapter, summarize the RuleWorks language constructs by category:

  • Operators
  • Predicates and Relational Operators
  • Statements
  • Actions
  • Functions
  • Commands
  • Declarations
  • SQL Interface routines

Many of the constructs described in this Reference Dictionary can be specified with arguments. When you specify argument values, separate the categories with any combination of spaces, tabs, and carriage returns.

The descriptions of all constructs are presented after the tables, alphabetically by name, with the non-alphabetic operators and predicates at the beginning. The descriptions include:

  • usage details
  • syntax
  • format
  • arguments
  • examples

Note: you cannot use expressions that contain variables or function calls (except the COMPOUND function) as argument values for commands.

The RuleWorks run-time library routines are described in Appendix A.

Summary of Operators

Table 1 Summary of Operators - Arithmetic Operators

OperatorDescription
+Performs addition on numeric values
-Performs subtraction on numeric values
*Performs multiplication on numeric values
/Performs division on numeric values
\Performs the modulus operation on integer values

 

Table 2 Summary of Operators - Match Operators

OperatorDescription
^Specifies an attribute of an object
{ }Specifies a conjunction (logical AND) of values
<< >>Specifies a disjunction (logical OR) between values

 

Table 3 Summary of Operators - Logical Operators*

OperatorDescription
ANDPerforms a conjunction on two relational expressions
NOTNegates a relational expression
ORPerforms an inclusive disjunction on two relational expressions

Note: Logical operators can be used only within the context of IF ... THEN ... ELSE ... and WHILE ... DO ... actions.

Summary of Predicates and Relational Operators

Scalar predicates are those that are valid only for scalar attributes. The exceptions are identity and nonidentity (== and <>, which are also valid for comparing a compound attribute to a compound value. Compound predicates are those that are valid for compound attributes.

Table 4. Summary of Scalar Predicates and Relational Operators

DomainPredicateValue DomainTest
ANY==ANYIdentity: Same type as and equal to
This predicate is optional in LHS attribute-value tests. It is required in RHS relational expressions.
ANY<>ANYNonidentity; converse of identity
ANY=ANYEquality: Identical or equivalent numbers; identical symbols except for case; identical values of all other data types
ANY-=ANYInequality; converse of equality
ANY~=ANYSimilarity: Equal or phonetically similar symbols; equal or approximately equal numbers; identical values of all other data types
ANY-~=ANYDissimilarity; converse of similarity
NUMBER>NUMBERGreater than
SYMBOL>SYMBOLLexicographically after
ANY>=ANYGreater than or equal numbers; lexicographically after or equal symbols; identical values for all other data types
NUMBER<NUMBERLess than
SYMBOL<SYMBOLLexicographically before
ANY<=ANYLess than or equal numbers; lexicographically before or equal symbols; identical values for all other data types
ANY<=>ANYSame type
ANY<->ANYDifferent type

 

Table 5. Summary of Compound Predicates and Relational Operators

DomainPredicateValue DomainTest
COMPOUND[+]ATOMContainment; compound contains atom;
COMPOUND[-]ATOMNon-containment; converse of containment
COMPOUND[=]INTEGERLength equal
COMPOUND[<>]INTEGERLength not equal
COMPOUND[>]INTEGERLength greater
COMPOUND[>=]INTEGERLength greater than or equal
COMPOUND[<]INTEGERLength less than
COMPOUND[<=]INTEGERLength less than or equal

 

Summary of Statements

Rules and catchers may be contained in either an entry block or a rule block, but ON- statements must be contained in an entry block.

Table 6. Summary of Statements

StatementDescription
CATCHContains actions that are executed after a specified number of recognize-act cycles (see also the AFTER action)
ON-EMPTYContains actions that are executed when the conflict set is empty
ON-ENTRYContains actions that are executed when the entry block is called, before the first recognize-act cycle
ON-EVERYContains actions that are executed after the act phase of each recognize-act cycle except the last
ON-EXITContains actions that are executed after the act phase of the last recognize-act cycle, except when a QUIT action is performed
RULEContains actions that are executed when left-hand-side conditions are met and the instantiation wins conflict resolution

 

Summary of Actions

Table 7. Summary of Actions

ActionDescription
ADDSTATEAdds the contents of a file produced by the SAVESTATE action or command to the current state of working memory and the conflict set
AFTERSpecifies the number of recognize-act cycles that must be executed before a specified catcher is executed
BINDBinds a variable to a value
CLOSEFILECloses the open files associated with specified file identifiers and dissociates the identifiers from the files
COPYCopies a new copy of an existing object
DEFAULTSets the terminal or a file as the default input source for the ACCEPT-ATOM and ACCEPTLINE-COMPOUND functions, or the default output destination for the WRITE action or for trace output
FOR-EACHIterates over a compound value, executing the specified actions
IF ...
THEN ...
ELSE...
Provides a branch in the flow of control, as in procedural languages
MAKECreates an object
MODIFYChanges one or more values in an existing object
OPENFILEOpens a file and associates it with a file identifier
QUITStops execution of the active entry block and passes control back to the operating system, optionally returning a value
REMOVEDeletes one or more objects
REMOVE-EVERYDeletes all the working memory objects that are instances of the specified class or its subclasses
RESTORESTATEClears and then restores working memory and the conflict set to the state recorded in a file produced by the SAVESTATE action or command
RETURNStops execution of the active entry block, executes the ON-EXIT actions (if any), and passes control back to the caller of the entry block. May also pass a return value.
SAVESTATECopies the state of working memory and the conflict set to a file
SPECIALIZEConverts an instance of one class to an instance of a descendent class
TRACEDisplays or sets the run-time system's trace setting
WHILE ...
DO ...
Provides a loop in the flow of control, as in procedural languages
WRITESends output from a program to the terminal or a file

 

Summary of Functions

Table 8. Summary of Functions

FunctionOK on LHS?Description
ACCEPT-ATOMNoReads an atom from the terminal or a file
ACCEPTLINE-COMPOUNDNoReads a line of input from the terminal or file into a compound value
COMPOUNDYesCreates a new compound value from any number of arguments, scalar or compound
CONCATYesConcatenates the print forms of its arguments
CRLFNoCauses the WRITE action to produce output on a new line
EVERYNoReturns a compound value that contains the IDs of all instances of the specified class
FLOATYesConverts a numeric value into a floating-point number
GENATOMNoReturns a system-generated atom
GETNoGiven a variable bound to an object identifier and an attribute name, returns the value of that object's attribute
INTEGERYesConverts a numeric value into an integer
IS-OPENNoTests whether a file is open
LENGTHYesReturns the number of elements in a compound value
MAXYesReturns the largest of its arguments
MINYesReturns the smallest of its arguments
NTHYesReturns the value of a specified element in a compound value
POSITIONYesFinds the first occurrence of an element in a compound value
RJUSTNoCauses the WRITE action to right justify output in a field of specified width
SUBCOMPOUNDYesReturns a subrange of a compound value
SUBSYMBOLYesReturns a fragment of a symbolic value
SYMBOLYesConverts any atom into a symbol
TABTONoCauses the WRITE action to put output in a specified column

 

Summary of Commands

Table 9. Summary of Commands

CommandDescription
@Opens a file containing RuleWorks commands and executes the commands.
ADDSTATE Adds the contents of a file produced by the SAVESTATE action or command to the current state of working memory.
AFTERSpecifies the number of recognize-act cycles that must be executed before a specified catcher is executed.
CLOSEFILECloses the open files associated with specified file identifiers and dissociates the identifiers from the files.
COPYMakes a new copy of an existing object.
CSDisplays the current contents of the conflict set.
DEFAULTSets the terminal or a file as the default input source for the ACCEPT-ATOM and ACCEPTLINE-COMPOUND functions, or the default output destination for the WRITE action or trace output.
DISABLE Disables the WMHISTORY command and the display of block names.
EBREAKDisplays entry blocks that have breakpoints set, sets breakpoints for entry blocks, or deletes breakpoints from entry blocks.
ENABLEEnables the WMHISTORY command and the display of block names.
EXITSynonym for QUIT command
MAKECreates a working-memory object.
MATCHESDisplays the identifiers and time-tags of objects that match condition elements in a specified rule.
MODIFYChanges one or more values in an existing working-memory object.
NEXTDisplays the instantiation the run-time system will select from the conflict set for the act phase of the next recognize-act cycle.
OPENFILEOpens a file and associates it with a file identifier.
PPCLASSDisplays the ancestors of an object class.
PPWMDisplays working-memory objects that match a specified pattern.
QUITStops execution and returns control to the operating system; optionally returns an integer value.
RBREAKDisplays rules that have breakpoints set, sets breakpoints for rules, or deletes breakpoints from rules.
REMOVEDeletes objects from working memory.
REMOVE-EVERYDeletes all working-memory objects that are instances of a specified class or subclass.
RESTORESTATE Clears working memory and the conflict set, then loads them from a file produced by the SAVESTATE action or command.
RETURNPasses control back to the caller of the entry block; optionally returns a value.
RUNExecutes recognize-act cycles.
SAVESTATECopies the state of working memory and the conflict set to a file.
SPECIALIZEChanges a working-memory object from an instance of one class to an instance of a parent class.
TRACEDisplays or sets the amount of debugging information displayed by the run-time system.
WBREAKDisplays objects that have breakpoints set, sets breakpoints for objects, or deletes breakpoints from objects.
WMDisplays working-memory objects.
WMHISTORYDisplays the revision history of an object.

 

Summary of Declarations

Table 10. Summary of Declarations

DeclarationDescription
DECLARATION-BLOCK Begins a set of shareable object class and external routine declarations
END-BLOCKEnds an entry, declaration, or rule block
END-GROUPEnds a rule group
ENTRY-BLOCKBegins a callable RuleWorks routine
EXTERNAL-ROUTINEDeclares a routine written in a language other than RuleWorks, or another RuleWorks entry block
OBJECT-CLASS Defines a class name and its list of attribute names
RULE-BLOCK Begins a set of shareable rules and catchers
RULE-GROUPBegins a named set of rules and catchers

 

Summary of SQL Actions

Table 11. Summary of SQL Actions

ActionDescription
SQL-ATTACH Specifies the database that is to be accessed by the other RuleWorks SQL actions.
SQL-COMMIT Completes the current SQL transaction and makes permanent any changes made during the transaction.
SQL-DELETE Deletes specified records from the database.
SQL-DETACH Commits any outstanding transaction and detaches from the database.
SQL-FETCH-EACH Binds field values to RuleWorks variables and executes RuleWorks actions that can use those variables.
SQL-FETCH-AS-OBJECT Makes objects from database records.
SQL-INSERT Stores new records in the database.
SQL-INSERT-FROM-OBJECT Stores the contents of an object in a new database record.
SQL-ROLLBACK Completes the current SQL transaction and undoes any changes made during the transaction.
SQL-START Starts an SQL transaction and sets transaction options.
SQL-UPDATE Modifies existing database records.
SQL-UPDATE-FROM-OBJECT Modifies existing database records, using the contents of an object.

 

Operator Descriptions

This section contains a description of the RuleWorks operators, in alphabetical order.

 

+ (Addition)

Performs arithmetic addition on numeric values.

  • Format
  • numeric-expression + numeric-expression

  • Operands
  • numeric-expression

    The numeric expressions to be added. These may be numeric constants, arithmetic expressions, variables bound to numeric values, or functions that return numeric values.

  • Example
  • The following action shows addition of a bound variable and a constant.

    (modify <the-counter> ^count ( <c> + 1 ) )

 

- (Negation and Subtraction)

As a Match Operator

Negates a condition element (see Chapter 3 for a discussion of negative CEs).

  • Format
  • - condition-element

  • Operand
  • condition-element

    The CE that is to be negated.

As an Arithmetic Operator

Performs arithmetic subtraction on numeric values.

  • Format
  • - numeric-expression

    numeric-expression - numeric-expression

  • Operands
  • numeric-expression

    The numeric expressions to be subtracted. These arguments may be numeric constants, arithmetic expressions, variables bound to numeric values, or functions that return numeric values.

  • 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 following action shows subtraction of a bound variable and a constant:

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

 

* (Multiplication)

Performs arithmetic multiplication on numeric values.

  • Format
  • numeric-expression * numeric-expression

  • Operands
  • numeric-expression

    The numeric expressions to be multiplied. These may be numeric constants, arithmetic expressions, variables bound to numeric values, or functions that return numeric values.

  • Example
  • If the KIWI.RUL program calculates sales tax, it can use the following action:

    (modify <the-total> ^cost (<cost> + (<cost> * <tax>)))

 

/ (Division)

Performs arithmetic division on numeric values.

  • Format
  • numeric-expression / numeric-expression

  • Operands
  • numeric-expression

    The numeric expressions to be divided. These may be numeric constants, arithmetic expressions, variables bound to numeric values, or functions that return numeric values.

    The second operand must not evaluate to zero, or a warning is generated and the result is zero. The result is an integer only when both operands are integers.

  • Example
  • The following action converts degrees Fahrenheit to degrees Celsius:

    (bind <degrees-c> ((<degrees-f> - 32) * 5 / 9))

    Note that the entire arithmetic expression must be enclosed in parentheses.

 

\ (Modulus)

Performs the arithmetic modulus operation on integer values.

  • Format
  • integer-expression \ integer-expression

  • Operands
  • integer-expression

    The dividend and divisor for the modulus operation. These may be integers, arithmetic expressions that evaluate to integers, variables bound to integers, or functions that return integers.

  • Example
  • The following rule uses both division and modules on integers:

    (rule find-dozens

    (start ^$ID <start>)

    -->

    (write (crlf) |Enter an integer: | )

    (bind <eggs> (accept-atom)

    (write (crlf) |There are| (<eggs> / 12) |dozen in|<eggs>); division

    (write (crlf) | and there are| (<eggs> 12) |left over|) ; modulus

    (modify <start>))

    This example produces the following output:

    Enter an integer: 13

    There are 1 dozen in 13

    and there are 1 left over

    Enter an integer: 39

    There are 3 dozen in 39

    and there are 3 left over

    Enter an integer:

 

^ (Attribute)

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

  • Format
  • ^attribute-name

  • Argument
  • attribute-name

    The name of a declared attribute.

    In condition elements on the LHS, this argument must be a symbolic atom. In actions on the RHS, this argument can be a symbol or a variable that is bound to a declared attribute name.

  • Example
  • The following OBJECT-CLASS declaration defines the attribute ^ITEM for the class INPUT-THING:

    (OBJECT-CLASS input-thing

    ^item)

    The following CE matches objects of class INPUT-THING whose ^ITEM attribute has the value HOME-KIWI. It also uses the built-in attribute ^$ID to bind an object variable:

    (input-thing ^item home-kiwi ^$ID <my-input-thing>)

     

 

== (Identity)

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.

As a Match Predicate

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.

  • Format
  • ^attribute= = value-expression

    ^attribute value-expression

     

As a Relational Operator

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

  • Format
  • 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 following CE uses the implied identity predicate:

    (active-context ^name verify-configuration)

    The relational expression below, of necessity, uses the explicit identity predicate:

    (if ((is-open infile) = = nil)

    then (openfile infile orders.dat in))

     

<> (Nonidentity)

Produces a match when the identity predicate (see previous fails to match; evaluates to true when the identity operator evaluates to false.

  • 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>)

 

= (Equality)

Produces a match, or evaluates to true, when its operands are identical or have equal values.

The equality predicate and operator performs automatic type conversion between INTEGER and FLOAT values. For example, 2 is equal to 2.0, but 2 is not identical to 2.0.

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.

You cannot use the equality predicate with the binding instance of a variable. You must use the identity predicate.

  • 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)

 

-= (Inequality)

Produces a match when the equality predicate (see previous page) fails to match; evaluates to true when the equality operator evaluates to false.

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

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

 

~= (Similarity)

Produces a match, or evaluates to true, when its arguments are either both numbers or the same type, and are similar to each other. Similarity is defined as follows:

  • 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 ValueSecond ValueSimilar?
    4.04Yes
    4.54No
    9.910Yes
    -9.9-10Yes

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

    Table 13. SOUNDEX Codes and Symbols

    SymbolSOUNDEX Code
    TracyT62
    LarryL6
    St. LaurentS34653
    StevenS315
    StephenS315
    StefanoS315

 

-~= (Dissimilarity)

Produces a match, or evaluates to true, when the similarity predicate (see previous fails to match, or evaluates to false.

  • Examples
  • The table below shows the results of several dissimilarity tests:

    Table 14. Dissimilarity Testing

    First ValueSecond ValueDissimilar?
    4.04No
    4.54Yes
    9.910No
    -9.9-10No

 

> (Greater-than)

Produces a match, or evaluates to true, when its first operand is greater than its second. The operands must be either both numbers or both symbols.

See appendix E for information on the collating sequences used by RuleWorks to compare symbolic values.

  • 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 that evaluates to a symbol or a number.

  • Example
  • The following table shows the results of several greater-than tests

    Table 15. Greater-than Testing

    First Value Second ValueMatch or True?
    4.0>3Yes
    4>5.0No
    aardwolf>aardvarkYes
    | greater-than |>greater-thanNo

 

>= (Greater-than-or-equal)

Produces a match, or evaluates to true, when its first operand is greater than or equal to its second. The operands must be either both numbers or both symbols.

See Appendix E for information on the collating sequences used by RuleWorks to compare symbolic values.

  • 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 that evaluates to a symbol or a number.

  • Example
  • The following table shows the results of several greater-than-or-equal tests:

    Table 16. Greater-than-or-Equal Testing

    First Value Second ValueMatch or True?
    5.0>=5Yes
    6>=7.0No
    aardvark>=AardvarkYes
    | greater-than |>=greater-thanYes

    The aardvarks match because they are equal, which is a case insensitive comparison, not because the first value is greater than the second.

< (Less-than)

Produces a match, or evaluates to true, when its first operand is less than its second. The operands must be either both numbers or both symbols.

See Appendix E for more information on the collating sequences used by RuleWorks to compare symbolic values.

  • 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 that evaluates to a symbol or a number.

  • Example
  • The following table shows the results of several less-than tests:

    Table 17. Less-than Testing

    First ValueSecond ValueMatch or True?
    2.0<3Yes
    5<6.0Yes
    zygosis<zygoteYes
    zoology<ZoologyNo

 

<= (Less-than-or-equal)

Produces a match or evaluates to true, when its first operand is less than or equal to its second. The operands must be either both numbers or both symbols.

See Appendix E for information on the collating sequences used by RuleWorks to compare symbolic values.

  • 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 that evaluates to a symbol or a number.

     

  • Examples
  • The following table shows the results of several less-than-or equal tests:

    Table 18 Less-than-or-equal Testing

    First ValueSecond ValueMatch or True?
    2.0<=3Yes
    5<=5.0Yes
    zygosis<=zygoteYes
    zoology<=ZoologyYes

    The symbols match because they are equal, which is a case insensitive comparison, not because the first value is less than the second.

 

<=> (Same Type)

Produces a match, or evaluates to true, when both its operands are the same type. The RuleWorks data types are INTEGER, FLOAT, SYMBOL, INSTANCE-ID, and OPAQUE.

For example, if you specify this predicate with a symbol or a variable bound to a symbol, a match is produced when the atom in the WMO is a symbol.

The same-type predicate can be applied to scalar values only.

  • Format
  • (^attribute <=> value-expression)

    (value-expression <=> value-expression)

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

  • Arguments(Operands)
  • value-expression

    Any RuleWorks expression, whose value is to be tested.

  • Example
  • The following CE matches an object of class INPUT-THING whose ^ITEM attribute has a symbolic value:

    (input-thing ^item <=> symbol )

     

<-> (Different-type)

Produces a match when the same-type predicate (see previous page) fails to match; evaluates to true when the same-type operator evaluates to false.

This predicate can be applied to scalar values only.

  • Example
  • This CE is the converse of the previous example:

    (input-thing ^item <-> symbol)

 

[+] (Containment)

Produces a match, or evaluates to true, when its scalar operand is an element of its compound operand. That is, you can test whether a compound contains a scalar value, or you can test whether a scalar value is contained in a compound.

By default, the containment predicate tests for identity; you can specify a different test with an optional scalar predicate. The scalar predicate must appear next to the scalar argument.

  • Format
  • ^compound-attr [+] [predicate] scalar-value

    ^scalar-attr [predicate] [+] compound-value

    compound-value [+] [predicate] scalar-value

    scalar-value [predicate] [+] compound-value

     

  • Operands
  • ^compound-attr

    The compound attribute whose value is to be searched for a scalar value.

    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 (see Table 4)

    scalar-value

    The scalar value for which a compound attribute is to be searched.

    ^scalar-attr

    The scalar attribute for whose value a compound is to be searched.

    compound-value

    The compound value which is to be searched for a scalar value

     

  • Examples
  • The following CE matches an object class BOX whose ^CARD-IN-SLOT attribute contains at least one MEMORY element:

     

    (box ^card-in-slot <cards> [+] memory)

    The condition shown below is true when MEMORY is contained by <CARDS>:

     

    (memory [+] <cards>)

    The following attribute-value test uses the similarity predicate in conjunction with the containment predicate:

    ^list [+] ~= color

    This test matches when the compound value of the ^LIST attribute contains an element similar to COLOR, such as COLOUR or COULEUR.

     

[-] (Non-containment)

Produces a match when the containment predicate (see previous page) fails to match; evaluates to true when the containment operator evaluates to false.

 

  • Example
  • The following two CEs match a WMO of class BOX whose ^CARD-IN-SLOT-OBJ-ID attribute does not contain the object whose ID is bound to <THE-MEM>:

    (memory ^$ID <the-mem>)

    (box ^card-in-slot-obj-id [-] <the mem>)

 

[=] (Length-equal)

Produces a match, or evaluates to true, when the number of elements in its compound operand is identical to its numeric operand.

As with identity predicate, the length-equal predicate can be used with the first appearance of a variable. This binds the variable to the actual number of elements in the compound attribute.

 

  • Format
  • ^compound-attr [=] integer-value

    compound-value [=] integer-value

     

  • Operands
  • ^compound-attr

    The compound attribute whose length is to be tested.

    Integer-value

    The integer value to which the length of a compound value is to be compared. This operand may be any expression that evaluates to an integer greater than or equal to zero.

    Compound-value

    The compound value whose length is to be tested. This operand may be any expression that evaluates to a compound value.

     

  • Examples
  • The CE below matches an object of class BOX whose ^CARD-IN-SLOT attribute is empty:

    (box ^card-in-slot [=] 0)

    This CE shows the syntax for testing the compound and binding a variable:

    (box ^card-in-slot {[=] 0 [=] <cards>})

     

 

[<>] (Length-not-equal)

Produces a match when the length-equal predicate (see previous page) fails to match; evaluates to true when the length-equal operator evaluates to false.

  • Example
  • The following CE matches an object of class BOX whose ^CARD-IN-SLOT attribute is not empty:

    (box ^card-in-slot [<>] 0)

 

[>] (Length-greater-than)

Produces a match, or evaluates to true, if the number of elements in its compound operand is greater than its integer operand.

  • Format
  • ^compound-attr [>] integer-value

    compound-value [>] integer-value

  • Operands
  • ^compound-attr

    The compound attribute whose length is to be tested.

    Integer-value

    The integer value to which the length of a compound value is to be compared. This operand may be any expression that evaluates to an integer greater than or equal to zero.

    Compound-value

    The compound value whose length is to be tested. This operand may be any expression that evaluates to compound value.

    Example

    The following CE matches an object of class BOX whose ^CARD-In-SLOT attribute has more than two elements:

    (box ^card-in-slot [>] 2)

     

 

[>=] (Length-greater-than-or-equal)

Produces a match, or evaluates to true, if the number of elements in its compound operand is greater than or equal to its integer operand.

  • Format
  • ^compound-attr [>=] integer-value

    compound-value [>=] integer-value

  • Operands
  • ^compound-attr

    The compound attribute whose length is to be tested.

    Integer-value

    The integer value to which the length is to be tested. This operand may be any expression that evaluates to an integer greater than or equal to zero.

    Compound-value

    The compound value whose length is to be tested. This operand may be any expression that evaluates to a compound value.

    Example

    The following CE matches an object of class BOX whose ^CARD-IN-SLOT attribute has two or more elements:

    (box ^card-in-slot [>=] 2)

 

[<] (Length-less-than)

Produces a match, or evaluates to true, if the number of elements in its compound operand is less than its integer operand.

  • Format
  • ^compound-attr [<] integer-value)

    compound-value [<] integer-value

  • Operands
  • ^compound-attr

    The compound attribute whose length is to be tested.

    integer-value

    The integer value to which the length of a compound value is to be compared. This operand may be any expression that evaluates to an integer greater than or equal to zero.

    compound-value

    The compound value whose length is to be tested. This operand may be any expression that evaluates to a compound value.

  • Example
  • The following CE matches an object of class BOX whose ^CARD-IN-SLOT attribute has fewer than two elements:

    (box ^card-in-slot [<] 2 )

 

[<=] (Length-less-than-or-equal)

Produces a match, or evaluates to true, if the number of elements in its compound operand is less than or equal to its integer operand.

  • Format
  • ^compound-attr [<=] integer-value

    compound-value [<=] integer-value

  • Operands
  • ^compound-attr

    The compound attribute whose length is to be tested.

    integer-value

    The integer value to which the length of a compound value is to be compared. This operand may be any expression that evaluates to an integer greater than or equal to zero.

    compound-value

    This operand may be any expression that evaluates to a compound value.

  • Example
  • The following CE matches an object of class BOX whose ^CARD-IN-SLOT attribute has two or fewer elements.

    (box ^card-in-slot [<=] 2 )

     

{ } (Conjunction)

Specifies a conjunction. A conjunction is similar to a logical AND. It is a left-hand-side pattern containing one or more conditional tests, all of which a single attribute in an object must satisfy.

For more information about conjunctions, see Chapter 3.

  • Format
  • { conditional-test ... }

  • Operands
  • conditional-test

    One or more conditional tests that the value of an attribute in an object is to satisfy.

  • Example
  • The following CE matches teenagers by testing for age greater than or equal to 13 AND less than 20:

    (person ^age { >= 13 < 20})

    The next CE contains a conjunction of two tests on the length of the compound attribute ^CARD-IN-SLOT. The first binds the length to the variable <LEN>. The second tests that the length is less than 6:

    (box ^$ID <the-box> ^card-in-slot <{> [=] <len> [<] 6})

    You can use a conjunction when you want to bind as well as test an attribute. For example:

    (hardware-option ^in-slot { <slot-num> <> NIL})

 

<<>> (Disjunction)

Specifies a disjunction of values, similar to a logical inclusive OR. An attribute that matches any one of the values satisfies the disjunction (see also Chapter 3).

  • Format
  • << value-expression.>>

  • Operands
  • Value-expression

    The value that an attribute value in an object is to match. This argument can be a constant, a bound variable, an arithmetic expression, or a function call. It must have the same structure as the attribute, either scalar or compound. You can specify one or more values.

    A disjunction of values is implicitly preceded by the identity predicate (= =). You cannot use any other predicate with a disjunction of values.

  • Examples
  • The following CE contains a disjunction of values:

    (input-thing ^item << NIL EOF END-OF-FILE >>)

    The next example shows the syntax for a compound attribute:

    (object ^$id <object-1>

    ^ integer-attr <I> ^symbol-attr <s> ^compound-attr <c>)

    (object ^$id {<object-2> <> <object-1>}

    ^compound-attr << <c>

    (compound a <s> c)

    (subcompound <c> 1 ((length <c>) - <I>)) >>)

 

@ (At)

Opens a file containing RuleWorks commands and executes the commands. The file must contain only RuleWorks commands. If the file cannot be opened, the run-time system displays the following message:

<FAC>-W-CANTOPEN, @ - Unable to open file filename for reading

  • Format
  • @ filespec

  • Argument
  • filespec

    The file specification for a file containing RuleWorks commands to be executed. The restrictions on file specifications vary according to operating system; see Section C.1 for details.

  • Example
  • The first command illustrates a simple file specification:

    RuleWorks> @ init-mem.wm

    The command below shows a file specification that includes a pathname, and must be quoted:

    RuleWorks> @ |C:%MEM.COM|

 

ACCEPT-ATOM

Reads an atom from the keyboard or a file. Ignores values after a semicolon (;) until the end of the line.

By default, the ACCEPT-ATOM function reads input from the keyboard. If you want the function to read input from a file, call the function with the file identifier of an open input file, or change the default for input.

  • Format
  • ACCEPT-ATOM [ file-id ]

  • Argument
  • file-id

    The file identifier of the file from which input is to be read. The file must have been opened and associated with the identifier in a previous OPENFILE action or command.

    This argument is optional. If you do not specify a file identifier, input is read from the current default for the ACCEPT-ATOM function (set with the DEFAULT action or command).

    Return Value

    If the argument you specify is not associated with an open file, the run-time system issues a warning and the function returns the symbol NIL.

    When the function reads past the end of a file, it returns the symbol END-OF-FILE.

  • Example
  • The following MAKE action uses the ACCEPT-ATOM function to create a Working Memory Object (WMO) that contains an atom read from the file associated with the file identifier INFIL.

    (make input-thing ^item (accept-atom infil))

     

ACCEPTLINE-COMPOUND

Reads a line of input from the keyboard or a file and returns a compound value that contains the values read. Ignores values after a semicolon (;) until the end of the line.

If some of the atoms in the current line have already been read, the input line is defined as all the remaining atoms on the current line. If all the atoms on the current line have been read, the input line is the next. If the input line contains no atoms, the function returns the specified default compound value.

By default, the ACCEPTLINE-COMPOUND function reads input from the keyboard. If you want the function to read input from a file, call the function with the file identifier of an open input file, or change the default for input.

  • Format
  • ACCEPTLINE-COMPOUND [file-id [default-compound-value]]

  • Arguments
  • File-id

    The file identifier of the file from which input is to be read. The file must have been opened and associated with the identifier in a previous OPENFILE action or command.

    This argument is optional. If you do not specify a file identifier, input is read from the current default for the ACCEPTLINE-COMPOUND function (set with the DEFAULT action or command).

    Default-compound-value

    The compound value to be returned when the function reads a blank line. This argument may be a bound compound variable or a function call that returns a compound value.

    If you want to specify a default compound value, you must also specify a file identifier. If you want to specify a default compound value when reading from the default input source, use the symbol NIL for the file identifier.

  • Return Value
  • A compound value that contains all the atoms on the current input line. If the input line contains no atoms, the function returns the specified default compound value.

    If the first argument you specify is not associated with an open file, the run-time system issues a warning and the function returns the empty compound value.

    When the function reads past the end of a file, it returns a compound value that contains the single element END-OF-FILE.

  • Example
  • The following actions read a line of input as a compound variable, and write it one element at a time:

    (bind <my-compound> (acceptline-compound))

    (for-each <x> in <my-compound>

    (write (crlf) <x>))

     

ADDSTATE

Adds the objects in a file produced by the SAVESTATE action or command to working memory.

The added objects have new INSTANCE-IDs and new time-tags. Any attributes in the added objects that have INSTANCE-ID values that point to other added objects are automatically updated so that the references remain consistent.

The ADDSTATE action and command is scoped to the entry block; it creates visible objects only. Trying to add objects whose class declarations are not visible to the entry block causes a run-time warning, and the WMOs are not made.

  • Format
  • (ADDSTATE filespec)

  • Argument
  • filespec

    A file specification for a file previously produced by the SAVESTATE action or command. See Section C.1 for restrictions on file names.

  • Example
  • Suppose you use the SAVESTATE action or command to create the file CONFIG.DAT. The following action adds the objects in the file to working memory.

    (addstate config.dat)

    The equivalent command is:

    RuleWorks> addstate config.dat

    On ULTRIX and Digital UNIX systems, the command could be:

    RuleWorks> addstate | config.dat |

 

AFTER

Specifies the number of recognize-act cycles that must be executed before a specified catcher is executed (see also Chapter 5).

Only one catcher can be active. Thus, the AFTER action and command disables the current catcher, if any, before it enables the new one.

The rule-firing counter is local to the current invocation of the active entry block. Recognize-act cycles executed by an entry block called from the entry block that contains the AFTER and CATCH actions are not counted.

  • Format
  • AFTER cycles catcher-name

  • Arguments
  • cycles

    A positive integer that specifies the number of recognize-act cycles that are to be executed before the specified catcher is executed. If this number of cycles is never reached, the catcher is not executed.

    catcher-name

    A symbol that names a catcher.

    If the catcher executes another AFTER, the counter restarts.

  • Example
  • The following command specifies that the catcher named TOO-MANY-CYCLES is to be executed after 100 recognize-act cycles have been executed:

    RuleWorks> AFTER 100 TOO-MANY-CYCLES

    The equivalent action is:

    (AFTER 100 TOO-MANY-CYCLES)

 

AND

Performs a logical conjunction on its two operands, that is, returns true only when both of its operands are true.

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

  • Format
  • rel-expr AND rel-expr

  • Operands
  • rel-expr

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

  • Example
  • The following code fragment shows the AND operator in a WHILE...DO...action:

    (while ((<cards-dealt> < 5) AND (<dealing> == true)) do

    (deal-a-card))

 

BIND

Binds a variable to a value.

The scope of the variable binding depends on the construct that contains the BIND action. Variables bound in rules, catchers, and methods are local. Variables bound to the input arguments of an entry block, and variables bound in any ON- statement, are visible to all subsequent ON- statements.

  • Format
  • BIND variable value-expression

  • Arguments
  • variable

    The variable to which a value is to be bound.

    value-expression

    An expression that can evaluate to either a scalar or compound value. The action binds the specified variable to the value that results from the evaluation.

    Note: MAKE, COPY, MODIFY, and SPECIALIZE actions return a value of type INSTANCE-ID. You can use them as the second argument to the BIND action, as well as anywhere else a value expression is permitted.

  • Example
  • The following action binds the variable <NEW-OBJECT> to the INSTANCE-ID returned by a MAKE action. (See Chapter 3-3 for an example of a complete program):

    (bind <new-object>

    (make example-object ^next <first-object> ^last <instance-id>^value (<val> + 1)))

 

CATCH

Creates a catcher, which is a list of actions that are executed after a specified number of recognize-act cycles have been executed. An AFTER action or command specifies the number of recognize-act cycles to be executed before the catcher is executed.

The AFTER and the CATCH must be contained in the same block. The recognize-act cycles count includes only rule firings in the entry block that contains or activates the AFTER and the CATCH.

  • Format
  • CATCH catcher-name action.

  • Arguments
  • catcher-name

    A symbol that names the catcher being created. The symbol cannot be the name of another catcher, a rule, a rule group that already exits in the entry block.

    action

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

  • Example
  • The following CATCH statement creates a catcher named TOO-MANY-CYCLES, which displays a message after the number of recognize-act cycles specified in an AFTER action or command have been executed, and stops execution:

    (catch too-many-cycles

    (write (crlf) |Program appears to be looping.|)

    (quit))

 

CLOSEFILE

Closes the open files associated with specified file identifiers and dissociates the identifiers from the files.

  • Format
  • CLOSEFILE file-id ...

  • Argument
  • file-id

    The file identifier of the file to be closed. The file must have been opened and associated with the identifier in a previous OPENFILE action or command.

    You can specify one or more file identifiers.

  • Example
  • The following command closes the open files associated with the file identifiers INFIL and OUTFIL:

    RuleWorks> CLOSEFILE INFIL OUTFIL

    The equivalent action is:

    (CLOSEFILE INFIL OUTFIL)

 

COMPOUND

Creates a new compound value from an arbitrary number of elements. If no elements are specified, the function returns the empty list.

COMPOUND is a stateless function and can be used on either the LHS or RHS.

  • Format
  • COMPOUND [ element ] ...

  • Argument
  • element

    Any valid scalar or compound value expression.

  • Return Value
  • A compound value that contains all the elements of the specified arguments.

  • Example
  • The following rule pushes a new value onto a stack by creating a new compound value from the new scalar value plus the current compound value.

    (rule push-stack

    (agenda ^$ID <Agenda-object> ^tasks <task-list>)

    -->

    (modify <Agenda-object> ^tasks (compound new-task <task-list>)))

    Note: RuleWorks does not support multilevel lists; the value returned above is a compound value whose elements are all scalar, not a compound value with one scalar element and a nested compound value.

    COMPOUND is the only function you can use in commands to the RuleWorks interpreter:

    RuleWorks> make box ^card-in-slot (compound memory keyboard)

 

CONCAT

Concatenates (splices) the print forms of its arguments.

  • Format
  • CONCAT [value-expr]...

  • Arguments
  • value-expr

    A RuleWorks expression that evaluates to a value to be concatenated. You can specify any number of values.

    If you specify a compound value, RuleWorks treats each element as a separate argument.

  • Return Value
  • A single scalar symbolic atom whose print name is the result of splicing together all of its arguments without inserting any spaces. If the result is too big to fit in a single atom, the function truncates it at the maximum symbol size (see chapter 2) and issues a warning.

  • Example
  • The following table shows three calls to the CONCAT function and their results:

    Table 18 CONCAT Function Calls and Results

    Function Call Print Form of Return Value

    (CONCAT a b c) ABC

    (CONCAT A | b | c) AbC

    (bind <x> | Fast | )
    (bind <y> | program! | )
    (CONCAT <x> || <y>) Fast program!

 

COPY

Makes a new object from an existing object. The existing object remains unchanged as a result of this operation. If you specify one or more attributes and values in the COPY, the new object is created with the new values you supply. In any case, the new object has a new $ID and a new time-tag. For more information about objects, see Section 2.2.

Note that the first argument to the COPY action must be a variable, while the first argument to the COPY command must be a constant.

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

  • Format (for action)
  • COPY ID-variable [{^attribute value-expression}...]

  • Format (for command)
  • COPY instance-id [ {^attribute value}...]

  • Arguments
  • ID-variable

    A variable bound to a value of type INSTANCE-ID, indicating the object to be duplicated. The object must be visible to the active entry block. This argument can be used only in source code.

    instance-id

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

    attribute

    An optional argument, this represents an attribute whose value is to be changed during the copy operation. You must specify a value with each attribute; you can specify any number of attribute-value pairs.

    value-expression

    Any scalar or compound value (if you specify a compound attribute) is a valid argument to the COPY 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 COPY command.

  • Return Value
  • The COPY action returns the INSTANCE-ID atom that identifies the new WMO.

  • Example
  • The following example shows a rule from the sample program, KIWI.OPS, rewritten to use a COPY action.

    (rule verify-configuration:kiwindows-needs-2-memory-cards-found-one

    (active-context ^name verify-configuration)

    (kiwindows)

    (memory ^$ID <mem-id>)

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

    -->

    (make error ^severity warning ^message |Insufficient memory|)

    (write (crlf) |Caution: KiWindows requires two memory cards,|

    (crlf) | but you have only one memory card.|

    (crlf) | Fixup: adding another memory card to your order.|

    (crlf) )

    (copy <mem-id>))

    The following example shows the equivalent COPY command and its results:

    RuleWorks> PPWM MEMORY

    #31 [CONVERT-SINGLE-ITEM-INPUT-THING-TO-PARTS:MEMORY] (MEMORY)

    RuleWorks> COPY #31

    RuleWorks> PPWM MEMORY

    #31 [CONVERT-SINGLE-ITEM-INPUT-THING-TO-PARTS:MEMORY] (MEMORY)

    #32 [| main |] (MEMORY)

 

CRLF

Causes the WRITE action to move to the next line. Valid inside a WRITE action only.

  • Format
  • CRLF

  • Arguments
  • None

  • Example
  • The following WRITE action:

    (write (crlf) |Caution: You need to buy the base CPU unit.|

    (crlf) | Fixup: adding a CPU BOX to your order.|

    (crlf) )

    produces the following output:

    Caution: You need to buy the base CPU unit.

    Fixup: adding a CPU BOX to your order.

 

CS

Displays the active contents of the conflict set, that is, instantiations of rules contained in or activated by the active entry block.

The command displays instantiations in the following format:

rule-name #instance-id-1 time-tag-1 #instance-id-2 time-tag-2 ...

where:

  • #instance-id-1 is the INSTANCE-ID of an object that matches the first CE on the left-hand side and time-tag-1 is its time-tag,
  • #instance-id-2 matches the second CE, and so on.
  • Format
  • CS

  • Example
  • The following command displays the contents of the conflict set:

    RuleWorks> cs

    POP-ACTIVE-CONTEXT #35 40

    VERIFY-CONFIGURATION:APPLICATION-NEEDS-KIWOS #35 40 #32 37

    VERIFY-CONFIGURATION:APPLICATION-NEEDS-KIWOS #35 40 #29 34

    VERIFY-CONFIGURATION:NEED-DISK #35 40

    VERIFY-CONFIGURATION:NEED-OUTPUT #35 40

    MAKE-CONTEXT-ACTIVE #6 6

    MAKE-CONTEXT-ACTIVE #5 5

    MAKE-CONTEXT-ACTIVE #4 4

    MAKE-CONTEXT-ACTIVE #3 3

 

DEBUG

Pauses execution after the current rule or ON- construct and invokes the RuleWorks command interpreter.

This action is effective only when contained in an entry or rule block that was compiled with the Debug qualifier set to YES or MAYBE (see Chapter 8 for more information on compiling RuleWorks programs). If the block was compiled with Debug NO, the DEBUG action is a no-op.

When you compile an entry block with Debug set to YES, the command interpreter automatically appears when the entry block begins executing and when it ends. To achieve this effect with Debug set to MAYBE, put a DEBUG action in your ON-ENTRY and ON-EXIT statements. Other good places to put DEBUG actions are in error-checking rules (rules that match when your program is not running correctly) and catchers.

  • Format
  • DEBUG

  • Arguments
  • None

  • Example
  • RuleWorks debugging commands are allowed after the DEBUG action, and will be executed by the command interpreter. For example:

    (on-entry

    (make agenda ^tasks (compound start work stoop)

    (debug)

    (watch rules)

    (make control ^name print-err-messages))

 

DECLARATION-BLOCK

Names a group of object class, method, or external routine declarations so that they can be shared among multiple entry block or rule blocks.

Declaration blocks are optional; both object classes and external routines can be declared inside entry blocks or rule blocks. However, if a declaration is inside an entry block or rule block, that declaration is private and cannot be shared. Instances of objects declared privately are not visible to any other block.

All object classes that are related by inheritance must be contained in the same block. A subclass cannot inherit from a parent class declared in a different block. Similarly, methods must be declared in the same block as the class to which they are attached.

A declaration block must not contain any executable program statements (that is, rules, catchers, or ON-constructs). It must be entirely contained in a single source file.

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

  • Format
  • (DECLARATION-BLOCK block-name)

  • Argument
  • block-name

    A symbol that names the block. This name must be distinct from all other block names in your program.

  • Example
  • This example shows a block of two OBJECT-CLASS declarations:

    (DECLARATION-BLOCK line-items)

    (OBJECT-class item

    ^item-code

    ^item-name

    ^quantity

    ^price-per

    ^item-total)

    (OBJECT-CLASS shippable-item

    (INHERITS-FROM item)

    ^part-number)

    (END-BLOCK line-items) ; the block name is optional here,

    ; but is checked if supplied

 

DEFAULT

Sets the default input source for the ACCEPT-ATOM and ACCEPT-LINE COMPOUND functions, or the default output destination for the WRITE action or trace output. If you do not use the DEFAULT command or action to specify otherwise, RuleWorks reads input from the keyboard and sends output to the screen (see chapter 2 for platform-specific details.)

  • Format
  • DEFAULT file-id io-type

  • Arguments
  • file-id

    The source from which input is to be read or the destination to which output is to be written. The value can be either a file identifier or the symbol NIL. If you specify a file identifier, DEFAULT sets the source or destination to the open file associated with that name. If you specify NIL, the input is read from the keyboard or output is sent to the screen.

    Use the OPENFILE action or command to open a file for access in a specified mode and create a file identifier.

    io-type

    A keyword that specifies whether the default is to be set for input, debugging output, or program output. The following table lists the keywords you can specify.

    Table 19. DEFAULT Keywords

    I/O TypeModeDescription
    ACCEPTINInput read by the ACCEPT-ATOM and ACCEPT-LINE-COMPOUND functions.
    TRACEOUT, APPENDOutput generated by the TRACE debugging command.
    WRITEOUT, APPENDOutput produced by the WRITE action.

     

  • Example
  • The following commands open a file for input, associate it with a file identifier INFIL, and set it to be the default source for the ACCEPT-ATOM and ACCEPTLINE-COMPOUND functions:

    RuleWorks> openfile infil order.dat in

    RuleWorks> default infil accept

    The equivalent actions are:

    (openfile infil order.dat in)

    (default infil accept)

 

DISABLE

Revokes a run-time feature that you had previously set with an ENABLE command. To disable a feature, specify the appropriate keyword.

 

    Table 20. DEFAULT Keywords

    KEYWORDFeature
    BLOCK-NAMESBlock names displayed with rule names
    WARNINGRun-time warning and error messages
    WMHISTORYWMHISTORY command

     

  • Format
  • DISABLE keyword

  • Argument
  • keyword

    A keyword that specifies the feature to be disabled. The keywords and the features they disable are listed in DISABLE Keywords table.

    Table 21. DISABLE Keywords

    KeywordFeature
    BACKBACK command
    TIMINGPME package
    BLOCK-NAMESBlock names displayed with rule names
    WARNINGRun-time warning and error messages
    WMHISTORYWMHISTORY command

     

  • Example
  • The following command disables the WMHISTORY command:

    RuleWorks> disable wmh

 

EBREAK

Controls breakpoints on entry blocks.

When used with no arguments, the command displays a numbered list of the entry blocks that have breakpoints set. When used with the ON and OFF keywords, respectively, EBREAK sets and clears breakpoints for entry blocks. Breakpoints are set or cleared on both the ON-ENTRY and ON-EXIT clauses by a single command.

When the run-time system encounters a breakpoint on an entry block, it finishes the ON-ENTRY or ON-EXIT construct (if-any), displays a message in the following format, and invokes the command interpreter:

%RUL-I-BREAKNOTED, Execution paused by break

EBREAK entering entry-block-name

Or

EBREAK exiting entry-block-name

Note that the block name is always displayed in EBREAK messages, whether BLOCK-NAMES is enabled or disabled.

 

  • Format
  • EBREAK
  • Arguments
  • entry-block-name

    The name of an entry block. You can specify one or more entry block names.

    number

    An integer displayed with the list of entry blocks when you give an EBREAK command with no argument. This argument is valid with the OFF keyword only.
    *
    All entry blocks.

 

ENABLE

Enables the run-time feature specified by a keyword argument (see ENABLE Keywords). The default state for all features is disabled.

Giving an ENABLE command with no argument results in a display of the features that are currently enabled. You can revoke a feature with the DISABLE command.

  • Format
  • ENABLE keyword

  • Argument
  • keyword

    A keyword that specifies the feature to be enabled.

    Table 22. ENABLE Keywords

    KeywordFeature
    BACK [n]BACK command. The optional argument, n, is an integer that specifies the number of cycles that may be backed over. The default is 64.
    TIMINGPME package.
    BLOCK-NAMESBlock names displayed with rule names
    WARNINGRun-time warning and error messages.
    WMHISTORYWMHISTORY command.

  • Example
  • The following command enables run-time messages.

    RuleWorks> enable war

 

END-BLOCK

Closes a block construct. Each DECLARATION-BLOCK, ENTRY-BLOCK, and RULE-BLOCK declaration must end with an END-BLOCK. If you want, you can repeat the name of the block in the END-BLOCK declaration.

  • Format
  • (END-BLOCK [block-name])

  • Argument
  • block-name

    The symbol that names the block being terminated. This argument is optional, but if you provide it the compiler checks it.

  • Example
  • This example shows a simple DECLARATION-BLOCK with a matching END-BLOCK:

    (DECLARATION-BLOCK line-items)

    (OBJECT-CLASS item

      ^item-code

      ^item-name

      ^quantity

      ^price-per

      ^item-total)

    (OBJECT-CLASS shippable-item

      (INHERITS-FROM item)

      ^part-number)

    (END-BLOCK line-items) ; the block name is optional here,

    ; but is checked if supplied

 

END-GROUP

Closes a rule group. Each RULE_GROUP declaration must end with an END-GROUP. If you want, you can repeat the name of the group in the END-GROUP declaration.

  • Format
  • (END-GROUP [group-name])

  • Argument
  • Group-name

    The symbol that names the group being terminated. This argument is optional, but if you provide it the compiler checks it.

 

ENTRY-BLOCK

Defines an entry point that is visible to the system linker and is callable by RuleWorks and other languages.

At least one ENTRY-BLOCK declaration is required for each RuleWorks routine. To make a RuleWorks program that you can run, at least one entry block must be named MAIN (or |main|).

RuleWorks entry blocks can accept arguments and return a value. You declare arguments with an ACCEPTS clause and the return value with a RETURNS clause.

An entry block can contain object class, and external routine declarations, and executable RuleWorks statements (that is, ON-statements, rules and catchers). It must be entirely contained in a single source file. However, an entry block can invoke rule blocks and declaration blocks that are contained in other files.

The entry block must close with an END-BLOCK declaration.

  • Format
  • (ENTRY-BLOCK block-name

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

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

      [(ACTIVATES rule-block-name.)}

      [(USES decl-block-name.)]

      [(STRATEGY|MEA|)])

      |LEX| )])

  • Argument
  • block-name

    A symbol that names the block. This name must be distinct from all routine names and other block names in your program and must conform to any restrictions imposed by your platform's linker. It 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

    Note: Naming an entry block MAIN (or |main|), with no ACCEPTS or RETURNS clause, generates a C-compliant "main function". RuleWorks automatically adds a return value of type LONG.

    The RuleWorks compiler generates a warning if an entry block named MAIN violates the C language restrictions on passing parameters to the main function: either zero or two parameters, one SHORT and one array of strings.

  • Clauses
  • Accepts

    Defines the input argument list of the entry block. Note that the name and data type are required for each argument; the size (of an array) and passing mechanism are optional.

    f-param-nameA RuleWorks variable name for the formal parameter.
    Variables bound to input arguments are visible to the entry block's ON-statements. They are not visible to rules unless you put them in working memory in your ON-ENTRY or ON-EVERY statement.
    [[size]]If a parameter is an array, you can indicate its expected size with either an integer or a variable bound to a previous parameter. The size is optional; the brackets are not.

    ext-type

    The external data type of input argument is passed. This argument is optional; the default mechanism is determined by the argument's external data type (see Table 6-1)

    passing-mech

    The mechanism by which the argument is passed. This arument is optional; the default mechanism is determined by the arguments external data type.

  • RETURNS
  • Specifies the external data type and passing mechanism information for the entry block's return value, if any. This clause is optional, but if you provide one RuleWorks checks that you also provide at least one RETURN action.

    f-param-name

    A variable name for the return value. This argument is optional; you can use a name to make your code easier to read.

    [size]

    If the return value is compound, you must indicate its expected size. You can use either an input parameter of an integer type (byte, short long, and so on; see Table 6-2), or an integer constant.

    Ext-type

    The external data type of the return value. See Table 6-1 for RuleWorks external data types.

    Passing-mech

    The passing mechanism by which the value is returned. This argument is optional; the default mechanism is determined by the value's external data type (see Table 6-1)

  • ACTIVATES
  • Indicates which rule blocks are eligible to fire. This clause is optional.

    Rule-block-name. A symbol that names a rule block. You specify one or more rule blocks.

    All rule blocks activated by an entry block are enabled automatically when the entry block is called. They must all use the same conflict-resolution strategy as the entry block that invoke them.

     

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

    Declaration

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

    The declaration block(s) used by an entry block must be compiled before the entry block itself can be compiled.

     

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

    LEX The lexicographic-sort strategy.

    MEA The means-end analysis strategy

    Example

    This example shows a simple counting program:

     

    (entry-block |main|

      (accepts <argc> long

        <argv> [2] asciz)

      (returns long))

     

    (object-class iterator ^count)

    (object-class limit ^value)

     

    (on-entry

      (write |argC is| <argc> |argV is| <argv> (crlf))

      (bind <num-arg> (integer (nth <argv> 2)))

      (make limit ^value <num-arg>)

      (make iterator ^count 1))

     

    (on-exit (return 0))

     

    (rule increment-rule

      (limit ^value <lim>)

      (iterator ^$id <it> ^count {<num> < <lim> })

      à

      (write <num> (crlf))

      (modify <it> ^count (<num> +1)))

     

    (rule now-done

      (limit ^$id <limit-id> ^value <lim>)

      (iterator ^$id <it> ^count <lim>)

      à

      (write <lim> (crlf))

      (remove <it>)

      (remove <limit-id))

       

    (end-block |main|)

     

This example produces the following output, when compiled with DEBUG yes:

System> count 5

ArgC is 2 argV is $1$dua0:[williams.ruleworks]count.exe;4 5

%RUL-I-EBREAK, EBREAK encountered on |main| &ON-ENTRY

RuleWorks> run

1

2

3

4

5

%RUL-I-EBREAK, EBREAK encountered on |main| &On-EXIT

RuleWorks> run

System>

 

EVERY

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.)

 

EXIT

An obsolescent synonym for the QUIT command.

  • Format
  • EXIT

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

    RuleWorks> EXIT

    System>

 

EXTERNAL-ROUTINE

Declares a function or subroutine written in a language other than RuleWorks. Defines the data types and passing mechanisms of the arguments needed to call the external routine. (See Chapter 6.1 for information on data types and passing mechanisms.)

Other RuleWorks entry blocks must also be declared as external routines. However, an entry block can call itself recursively with no external routine declaration.

  • 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

     

     

© RuleWorks.co.uk | | Sitemap