RuleWorks Online Help

Contents

RuleWorks Reference Dictionary

This help system corresponds to Part III of your Guide to RuleWorks book. It contains complete descriptions of all the constructs in the RuleWorks language. The descriptions include usage details, format, arguments, and examples.

Many constructs take arguments. When you specify argument values, separate them with any combination of spaces, tabs, and carriage returns.

Note

You cannot use expressions that contain variables or function calls (except the COMPOUND function) as values for arguments to commands at the interpreter prompt. You can use them for values in source code only.

Declarations

Executable Program Statements

Predicates and Operators

RHS Actions

SQL Actions

Functions

Commands

The RuleWorks API routines are described in Appendix A of your Guide to RuleWorks book.

Top

RuleWorks Construct Index

+ A B C D E F G I L M N O P Q R S T W

+

+ (Addition) Operator

- (Negation and Subtraction) Operator

* (Multiplication) Operator

/ (Division) Operator

\ (Modulus) Operator

^ (Attribute) Operator

== (Identity) Predicate and Operator

<> (Nonidentity) Predicate and Operator

= (Equality) Predicate and Operator

-= (Inequality) Predicate and Operator

~= (Similarity) Predicate and Operator

-~= (Dissimilarity) Predicate and Operator

> (Greater-than) Predicate and Operator

>= (Greater-than-or-equal) Predicate and Operator

< (Less-than) Predicate and Operator

<= (Less-than-or-equal) Predicate and Operator

<=> (Same-type) Predicate and Operator

<-> (Different-type) Predicate and Operator

[+] (Containment) Predicate and Operator

[-] (Non-containment) Predicate and Operator

[=] (Length-equal) Predicate and Operator

[<>] (Length-not-equal) Predicate and Operator

[>] (Length-greater-than) Predicate and Operator

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

[<] (Length-less-than) Predicate and Operator

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

{} (Conjunction) Operator

<< >> (Disjunction) Operator

@(At) Command

A

ACCEPT-ATOM Function

ACCEPTLINE-COMPOUND Function

ADDSTATE Action and Command

AFTER Action and Command

AND Operator

B

>BIND Action

C

CALL-INHERITED Action

CATCH Statement

CLOSEFILE Action and Command

COMPOUND Function

CONCAT Function

COPY Action and Command

CRLF Function

CS Command

D

DEBUG Action

DECLARATION-BLOCK Declaration

DEFAULT Action and Command

DISABLE Command

E

EBREAK Command

ENABLE Command

END-BLOCK Declaration

END-GROUP Declaration

ENTRY-BLOCK Declaration

EVERY Function

EXIT Command

EXTERNAL-ROUTINE Declaration

F

FLOAT Function

FOR-EACH Action

G

GENATOM Function

GENINT Function

GET Function

I

IF...THEN...ELSE... Action

INTEGER Function

IS-OPEN Function

L

LENGTH Function

M

MAKE Action and Command

MATCHES Command

MAX Function

MIN Function

MODIFY Action and Command

N

NEXT Command

NOT Operator

NTH Function

O

OBJECT-CLASS Declaration

ON-EMPTY Statement

ON-ENTRY Statement

ON-EVERY Statement

ON-EXIT Statement

OPENFILE Action and Command

OR Operator

P

POSITION Function

PPCLASS Command

PPWM Command

Q

QUIT Action and Command

R

RBREAK Command

REMOVE Action and Command

REMOVE-EVERY Action and Command

RESTORESTATE Action and Command

RETURN Action and Command

RJUST Function

RULE Statement

RULE-BLOCK Declaration

RULE-GROUP Declaration

RUN Command

S

SAVESTATE Action and Command

Similarity Predicates and Operators

SPECIALIZE Action and Command

SQL Actions

SUBCOMPOUND Function

SUBSYMBOL Function

SYMBOL Function

SYMBOL-LENGTH Function

T

TABTO Function

TRACE Action and Command

W

WBREAK Command

WHILE...DO... Action

WM Command

WMHISTORY Command

WRITE Action

Top

Declarations

Declarations must precede any executable program statements contained in the same block.  Similarly, declaration blocks (if any) must be compiled before entry blocks and rule blocks (if any).

• DECLARATION-BLOCK Declaration
• END-BLOCK Declaration
• END-GROUP Declaration
• ENTRY-BLOCK Declaration
• EXTERNAL-ROUTINE Declaration
• OBJECT-CLASS Declaration
• RULE-BLOCK Declaration
• RULE-GROUP Declaration

Top

DECLARATION-BLOCK Declaration

Names a group of object class, method, or external routine declarations so that they can be shared among multiple entry blocks 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

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

Top

END-BLOCK Declaration

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

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

(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

Top

END-GROUP Declaration

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

Example

This example shows ???:

(RULE-GROUP  ???)
      (rule ???)
      (rule ???)
      (rule ???)
(END-GROUP ???)      ; the group name is optional here,
                     ; but is checked if supplied

Top

ENTRY-BLOCK Declaration

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, method, and external routine declarations, and executable program statements (that is, ON- constructs, 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

Argument

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.

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.

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.

ACTIVATES

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

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 invokes them.

USES

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

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.

Example

This example shows a simple counting program:

(ENTRY-BLOCK |main|
       (accepts <argc> long
                <argv> [<argc>] 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>  ^value <lim>)
      (iterator  ^$id <It>  ^count <lim>)
  -->
      (write <lim> (crlf))
      (remove <It>)
      (remove <Limit>))


(END-BLOCK |main|)

This example produces the following output, when compiled on a VMS system with DEBUG YES:

$count 5
argC is 2 argV is $1$dua0:[williams.ruleworks]count.exe;2 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
$

Top

Relational Operators

The RuleWorks operators that return either TRUE or FALSE are listed below:

• AND
• NOT
• OR

A relational expression uses these operators to combine one or more value expressions.  You must use relational expressions in IF...THEN...ELSE... and WHILE...DO... actions.

Top

EXTERNAL-ROUTINE Declaration

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

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.

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.

RETURNS

Also an optional clause, this describes the external routine's return 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 last 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))

Top

C Language Requirements

C function names:

• cannot contain the characters " < > [ ] % ^ -
• must be less than 32 characters long
• must be different from all C keywords

If your C compiler is case-sensitive, you must quote (put vertical bars around) your block names.

Main functions must have either zero or two parameters. If two, the first must be a SHORT and the second an array of strings. The example in the ENTRY-BLOCK description shows how to use these two arguments.

Top

Passing Mechanisms

The valid passing mechanisms are listed below:

• BY REFERENCE READ-ONLY
• BY REFERENCE READ-WRITE
• BY VALUE

The passing mechanism is optional. RuleWorks provides a default for each external data type.

Top

External Data Types

The valid external data types are listed below with their default passing mechanism: 

Arrays of any type must be passed BY-REFERENCE. The default is BY-REFERENCE READ-ONLY but BY-REFERENCE READ-WRITE is also supported.

Top

RuleWorks Data Types

The valid data types and their system-defined default values are shown below:

Notes:

•        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

Top

OBJECT-CLASS Declaration

Declares an object class and the attributes associated with it.

All OBJECT-CLASS declarations must appear before any executable program statements. 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 ) ]

                       [ (FILL 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

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.

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

COMPOUND

Declares the attribute to be compound rather than scalar. See Section 2.3.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.

Example

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

Top

RULE-BLOCK Declaration

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

Argument

Clauses

USES

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

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.

Example

This example shows ???:

(RULE-BLOCK  ???)
      (rule ???)
      (rule ???)
      (rule ???)
(END-BLOCK ???)      ; the block name is optional here,
                     ; but is checked if supplied

Top

RULE-GROUP Declaration

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

Example

This example shows ???:

(RULE-GROUP  ???)
      (rule ???)
      (rule ???)
      (rule ???)
(END-GROUP ???)    ; the group name is optional here,
                   ; but is checked if supplied

Top

Executable Program Statements

The executable program statements are listed below:

CATCH Statement

ON- Constructs

RULE Statement

Top

ON- Constructs

ON- constructs allow you to specify RHS actions that are executed at specified times in the execution of an entry block, without matching any WMOs. There are four ON- constructs in RuleWorks:

• ON-EMPTY
• ON-ENTRY
• ON-EVERY
• ON-EXIT

Top

CATCH Statement

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

Example

The following CATCH statement creates a catcher named TOOMANY-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))

Top

ON-EMPTY Statement

Defines a set of RHS actions that are executed by RuleWorks when it reaches the select 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

Example

This example shows ???:

(ENTRY-BLOCK ???)
      (ON-EMPTY
            (???))
(END-BLOCK ???)

Top

ON-ENTRY Statement

Defines a set of RHS actions that are executed immediately after an entry block is called and before any rules fire. After the ON-ENTRY actions are executed, the RuleWorks runtime 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

Example

This example shows ???:

(ENTRY-BLOCK ???)

      (ON-ENTRY
            (???))
(END-BLOCK ???)

Top

ON-EVERY Statement

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

Example

This example shows ???:

(ENTRY-BLOCK ???)
      (ON-EVERY
            (???))
(END-BLOCK ???)

Top

ON-EXIT Statement

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

Example

This example shows ???:

(ENTRY-BLOCK ???)
      (ON-EXIT
            (???))
(END-BLOCK ???)

Top

P (Production) Statement

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

Format

(P  production-name

    (condition-element)...

  >-->

    (action)... )

Top

RULE Statement

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

Example

The following rule, named CLOSE-INPUT-FILE:DO-IT, contains three CEs and three actions. The second CE binds an 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 ^$ID <my-input-thing> ^item END-OF-FILE)
      (input-count ^count <c>)
  -->
      (closefile infil)
      (remove <my-input-thing>)
      (write (crlf) |Read| (<c> - 1) |items from input.| (crlf)))

Top

Predicates and Operators

This branch of the RuleWorks Help System contains the predicates and operators that you can use in your source code. Note that you cannot type any arithmetic expressions as arguments to commands at the interpreter prompt.

+ (Addition) Operator

- (Negation and Subtraction) Operator

* (Multiplication) Operator

/ (Division) Operator

\ (Modulus) Operator

^ (Attribute) Operator

== (Identity) Predicate and Operator

<> (Nonidentity) Predicate and Operator

= (Equality) Predicate and Operator

-= (Inequality) Predicate and Operator

~= (Similarity) Predicate and Operator

-~= (Dissimilarity) Predicate and Operator

> (Greater-than) Predicate and Operator

>= (Greater-than-or-equal) Predicate and Operator

< (Less-than) Predicate and Operator

<= (Less-than-or-equal) Predicate and Operator

<=> (Same-type) Predicate and Operator

<-> (Different-type) Predicate and Operator

[+] (Containment) Predicate and Operator

[-] (Non-containment) Predicate and Operator

[=] (Length-equal) Predicate and Operator

[<>] (Length-not-equal) Predicate and Operator

[>] (Length-greater-than) Predicate and Operator

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

[<] (Length-less-than) Predicate and Operator

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

{} (Conjunction) Operator

<< >> (Disjunction) Operator

AND Operator

NOT Operator

OR Operator

Top

Scalar Predicates

Scalar predicates are those that are valid for scalar attributes. Some scalar predicates, specifically, those whose attribute domain is ANY, are also valid for compound attributes.

Compound predicates are those that are valid only for compound attributes.

Top

Compound Predicates

Compound predicates are those that are valid only for compound attributes.

Some scalar predicates, specifically, those whose attribute domain is ANY, are also valid for compound attributes.

Top

+ (Addition) Operator

Performs arithmetic addition on numeric values.

Format

numeric-expression + numeric-expression

Operands

Example

The following action shows addition of a bound variable and a constant:

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

Top

- (Negation and Subtraction) Operator

As a Match Operator

Negates a condition element (see Section 3.5 for a discussion of negative CEs).

Format

-  condition-element

Operand

As an Arithmetic Operator

Performs unary negation or arithmetic subtraction on numeric values.

Format

- numeric-expression

numeric-expression - numeric-expression

Operands

Examples

The following two CEs test for the existence of one andonly 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) )

Top

* (Multiplication) Operator

Performs arithmetic multiplication on numeric values.

Format

numeric-expression * numeric-expression

Operands

Example

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

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

Top

/ (Division) Operator

Performs arithmetic division on numeric values.

Format

numeric-expression / numeric-expression

Operands

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.

Top

\ (Modulus) Operator

Performs the arithmetic modulus operation on integer values.

Format

integer-expression \ integer-expression

Operands

Example

The following rule uses both division and modulus 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>)
       (write (crlf) |  and there are| (<eggs> \ 12) |left over|)
       (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:

Top

^ (Attribute) Operator

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

Format

^attribute-name

Argument

Examples

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

Top

== (Identity) Predicate and Operator

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

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

Top

<> (Nonidentity) Predicate and Operator

Produces a match when the identity predicate 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>)

Top

= (Equality) Predicate and Operator

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

value-expression = value-expression

Operands

Example

The following CE uses the less restrictive equality predicate:

(active-context ^name = verify-configuration)

Top

-= (Inequality) Predicate and Operator

Produces a match when the equality predicate 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)

Top

~= (Similarity) Predicate and Operator

Produces a match, or evaluates to true, when its arguments are either both numbers or are the same type, and are similar to each other.

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

Format

^attribute ~= value-expression

value-expression ~= value-expression

Operands

Examples

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

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

Top

Similarity

Similarity is defined according to these steps:

1. 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.
2. Two symbols are similar when one of the following is true:
   1. They are identical or equal (equality is independent of case)
   2. Both symbols are at least three characters long, and adding a single character to one symbol makes it equal to the other
   3. Both symbols are at least three characters long, and transposing two characters in one symbol makes it equal to the other
   4. 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:

      Code	Consonants
      1	B, F, P, V
      2	C, G, J, K, Q, S, X, Z
      3	D, T
      4	L
      5	M, N
      6	R

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

Top

-~= (Dissimilarity) Predicate and Operator

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

Examples

The table below shows the results of several dissimilarity tests:

Top

> (Greater-than) Predicate and Operator

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

Examples

The following table shows the results of several greaterthan tests:

Top

>= (Greater-than-or-equal) Predicate and Operator

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

Example

The following table shows the results of several greaterthan-or-equal tests:

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

Top

< (Less-than) Predicate and Operator

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 information on the collating sequences used by RuleWorks to compare symbolic values.

Format

^attribute < value-expression

value-expression < value-expression

Operands

Examples

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

Top

<= (Less-than-or-equal) Predicate and Operator

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

Examples

The following table shows the results of several less-thanor-equal tests:

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

Top

<=> (Same-type) Predicate and Operator

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

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

Operands

Example

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

(input-thing ^item <=> symbol )

Top

<-> (Different-type) Predicate and Operator

Produces a match when the same-type predicate 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)

Top

[+] (Containment) Predicate and Operator

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

Examples

The following CE matches an object of 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.

Top

[-] (Non-containment) Predicate and Operator

Produces a match when the containment predicate 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 ^CARDIN-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>)

Top

[=] (Length-equal) Predicate and Operator

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

As with the 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

Examples

The CE below matches an object of class BOX whose ^CARD-INSLOT 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>})

Note that the predicate must be repeated inside the conjunction.

Top

[<>] (Length-not-equal) Predicate and Operator

Produces a match when the length-equal predicate 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)

Top

[>] (Length-greater-than) Predicate and Operator

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

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)

Top

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

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

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 )

Top

[<] (Length-less-than) Predicate and Operator

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

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 )

Top

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

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

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 )

Top

{} (Conjunction) Operator

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 Section 3.3.

Format

{ conditional-test... }

Operands

Examples

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

Top

<< >> (Disjunction) Operator

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

Format

<< value-expression... >>

Operands

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

Top

AND Operator

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

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

Top

NOT Operator

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

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

Top

OR Operator

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

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

Top

RHS Actions

The RuleWorks RHS actions are listed below.  Note that some actions are also valid as commands at the interpreter prompt; this is indicated in the title of each topic:

ADDSTATE Action and Command

AFTER Action and Command

BIND Action

CALL-INHERITED Action

CLOSEFILE Action and Command

COPY Action and Command

DEBUG Action

DEFAULT Action and Command

FOR-EACH Action

IF...THEN...ELSE... Action

MAKE Action and Command

MODIFY Action and Command

OPENFILE Action and Command

QUIT Action and Command

REMOVE Action and Command

REMOVE-EVERY Action and Command

RESTORESTATE Action and Command

RETURN Action and Command

SAVESTATE Action and Command

SPECIALIZE Action and Command

TRACE Action and Command

WHILE...DO... Action

WRITE Action

Additonal actions are listed under the RuleWorks interface to SQL.

Top

ADDSTATE Action and Command

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

Examples

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 DEC OSF/1 systems, the command could be:

RuleWorks> addstate |config.dat|

Top

AFTER Action and Command

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

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

Examples

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)

Top

BIND Action

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

Format

(BIND  variable value-expression )

Arguments

Note:

The 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 Example 3-3 for the complete program.)

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

Top

CALL-INHERITED Action

Used within a METHOD definition only, to invoke a method defined for a parent class. If there is no such method, the action does nothing.

Format

(CALL-INHERITED  arg-list )

Argument

Example

This example shows ???:

(method ???

(call-inherited ???))

Top

CLOSEFILE Action and Command

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

Format

(CLOSEFILE file-id...)

Argument

Examples

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)

Top

COPY Action and Command

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

Return Value

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

Examples

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

Top

DEBUG Action

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

Note:

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 9 for more information on compiling RuleWorks programs).  If the block was compiled with DEBUG NO, the DEBUG action is a no-op.

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 stop))
    (debug)
    (watch rules)
    (make control ^name print-err-messages))

Top

DEFAULT Action and Command

Sets the default input source for the ACCEPT-ATOM and ACCEPTLINE-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 Section C.2 for platform-specific details.)

Format

(DEFAULT  file-id io-type )

Arguments

Examples

The following commands open a file for input, associate it with the file identifier INFIL, and set it to be the default source 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)

Top

I/O Types

The valid keywords for the DEFAULT action are shown below:

Top

FOR-EACH Action

Allows iteration over each element in a compound value. The index variable is bound and the specified RHS actions are executed once for each iteration.

Format

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

Arguments

Examples

This example 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))))

Top

IF...THEN...ELSE... Action

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

Clauses

Example

This example shows ???:

(IF (???)

THEN (???)

ELSE (???))

Top

MAKE Action and Command

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

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

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-INSLOT and ^CARD-IN-SLOT-OBJ-ID:

RuleWorks>(make box ^card-in-slot (compound memory)
RuleWorks>^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

Top

MODIFY Action and Command

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. (For more information about objects, see Section 2.2.)

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

Return Value

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

Examples

The following action changes one attribute of a SOFTWAREOPTION 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-EX PANDED 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 Section 4.3 for examples of modifying compound attributes.

Top

OPENFILE Action and Command

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

Format

(OPENFILE file-id filespec mode )

Arguments

Examples

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

Top

File I/O Modes

The following table shows the keywords for the OPENFILE action:

Top

QUIT Action and Command

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

Examples

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.

Top

REMOVE Action and Command

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)

Argument

Examples

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

Top

REMOVE-EVERY Action and Command

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

Examples

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

(ON-EMPTY
    (write |Sorry... Program error. No satified 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))

Top

RESTORESTATE Action and Command

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 Section C.1 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)

Top

RETURN Action and Command

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 and in METHOD definitions, but not in rule blocks. When you use a RETURN action in a METHOD definition, the action returns from the method function, not from the active entry block.

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

Example

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

Top

SAVESTATE Action and Command

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. See Section C.1 for restrictions on file names.

Examples

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

Top

SPECIALIZE Action and Command

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

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

Top

TRACE Action and Command

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

Note:

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 9 for more information on compiling RuleWorks programs). If the block was compiled with DEBUG NO, the TRACE action is a no-op.

Format

Arguments

Examples

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 rb rule
RuleWorks>trace
ENTRY-BLOCK WM

For examples of trace output, see Section 11.2.7.

Top

TRACE Settings

Valid settings for the TRACE command are shown below:

Top

WHILE...DO... Action

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

Clause

Example

(WHILE (<sun-shines> = true) DO
       (make_hay))

Top

WRITE Action

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

Example

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

(write (crlf) <num> (tabto 12) <pname>
                    (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

Top

SQL Actions

The RuleWorks interface to SQL consists of the following actions:

SQL-ATTACH Action

SQL-COMMIT Action

SQL-DELETE Action

SQL-DETACH Action

SQL-FETCH-EACH Action

SQL-FETCH-AS-OBJECT Action

SQL-INSERT Action

SQL-INSERT-FROM-OBJECT Action

SQL-ROLLBACK Action

SQL-START Action

SQL-UPDATE Action

SQL-UPDATE-FROM-OBJECT Action

Top

SQL-ATTACH Action

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

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 )

Top

SQL-COMMIT Action

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.

Top

SQL-DELETE Action

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

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.

Top

SQL-DETACH Action

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.

Top

SQL-FETCH-EACH Action

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

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 above 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-EACH <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 record are selected, because of the wildcard (*). However, only the first two fetched are used. Any extra field values are ignored.

Top

SQL-FETCH-AS-OBJECT Action

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. SQL-FETCH-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

Return Value

When used as an 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 WHERE 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.

The next example refines the first 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 fld1, fld2, fld3 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 DISTINCT fld1, fld2 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 fld1, fld2, DBKEY FROM W1 WHERE fld1 < fld2 )

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

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.

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

(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:

(bind <x>

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

Top

SQL-INSERT Action

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

Examples

In this example a new record is created in database table tbl_1, 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  |(fld2, 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 <v1>, 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.

Top

SQL-INSERT-FROM-OBJECT Action

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 as the 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

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

Top

SQL-ROLLBACK Action

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.

Top

SQL-START Action

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

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.

Top

SQL-UPDATE Action

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

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 <val2>. These records have a1 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 a1 = <new-val> WHERE a1 = <val>, a2 = <val2> ))

Top

SQL-UPDATE-FROM-OBJECT Action

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-variable> [WHERE-clause]

Arguments

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 fld2 = '<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.

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

(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 a1 = <val> AND a2 = <val2> ) )

Top

Functions

The built-in functions of RuleWorks are listed below.  Note that some functions are valid on the LHS of a rule but some are not; this is indicated in the description of each function:

• ACCEPT-ATOM Function
• ACCEPTLINE-COMPOUND Function
• COMPOUND Function
• CONCAT Function
• CRLF Function
• EVERY Function
• FLOAT Function
• GENATOM Function
• GENINT Function
• GET Function
• INTEGER Function
• IS-OPEN Function
• LENGTH Function
• MAX Function
• MIN Function
• NTH Function
• POSITION Function
• RJUST Function
• SUBCOMPOUND Function
• SUBSYMBOL Function
• SYMBOL Function
• SYMBOL-LENGTH Function
• TABTO Function

Top

ACCEPT-ATOM Function

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

Return Value

The first atom read from the input source.

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 WMO that contains an atom read from the file associated with the file identifier INFIL:

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

Top

ACCEPTLINE-COMPOUND Function

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

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

Top

COMPOUND Function

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

Return Value

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

Examples

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:

Top

CONCAT Function

Concatenates (splices) the print forms of its arguments.

Format

(CONCAT  [ value-expr ]... )

Arguments

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 Section 2.4.1) and issues a warning.

Examples

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

Top

CRLF Function

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.

Top

EVERY Function

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

Format

(EVERY  class-name )

Argument

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 methods.  Their definitions are left as an exercise for the reader.)

Top

FLOAT Function

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

Return Value

The floating-point number that corresponds to the specified value.

Examples

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

Top

GENATOM Function

Returns a system-generated atom, with an optional prefix. The GENATOM counter is reset by the RESTORESTATE action and command. The GENATOM counter is global, so that all entry blocks called in a program generate unique atoms.

Format

(GENATOM  [ prefix ])

Argument

Return Value

A symbol that consists of the prefix you specify (if any) with an integer appended to it. Each time the run-time system starts executing a program, the first call to the GENATOM function generates the atom prefix1. The second atom the function generates is prefix2, the third atom is prefix3, and so on.

Example

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

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

Top

GENINT Function

Returns a system-generated integer.

The GENINT counter is reset by the RESTORESTATE action and command. The GENINT counter is global, so that all entry blocks called in a program generate monotonically increasing integers. This lets you sort according to creation time.

Format

(GENINT)

Return Value

Each time the run-time system starts executing a program, the first call to the GENINT function generates the integer 1. The second call returns 2, the third 3, and so on.

Example

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

(bind <transaction-id> (genint))

Top

GET Function

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

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

Top

INTEGER Function

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

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:

Top

IS-OPEN Function

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

Format

(IS-OPEN file-id)

Argument

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.

Example

The following IF...THEN...ELSE... action uses the IS-OPEN function in its relational expression:

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

Top

LENGTH Function

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

(See also the SYMBOL-LENGTH function, which returns the number of characters in a symbol.)

Format

(LENGTH compound-val)

Argument

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

Top

MAX Function

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

Return Value

The greatest of the arguments.

Examples

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

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

Top

MIN Function

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

Return Value

The smallest of the arguments.

Examples

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

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

Top

NTH Function

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

Return Value

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

Example

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

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

Top

POSITION Function

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

By default, POSITION tests 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

Return Value

The integer index of the first element in compound-var that satisfies 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 (BOX ^CARD-IN-SLOT (COMPOUND 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

Top

RJUST Function

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

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

Top

SUBCOMPOUND Function

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

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

Return Value

A compound value that contains the specified subrange of the input compound value. If the subrange is specified incorrectly or does not exist, the function returns the "empty list", (COMPOUND).

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

Top

SUBSYMBOL Function

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

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

Example

The following rule uses the SUBSYMBOL function to do what???

(rule ???
      (???)
  -->
(modify ??? (SUBSYMBOL <???> ? $LAST)))

Top

SYMBOL Function

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

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

NYD

Top

SYMBOL-LENGTH Function

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

Return Value

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

Examples

The following shows ???:

TBD

Top

TABTO Function

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

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:

nbsp;        NUMBER         AMOUNT         DATE

Top

Commands

The RuleWorks commands that are valid only at the interpreter prompt are listed below:

• @ (At) Command
• CS Command
• DISABLE Command
• EBREAKCommand
• ENABLECommand
• EXITCommand
• MATCHESCommand
• NEXTCommand
• PPCLASSCommand
• PPWMCommand
• QUITAction and Command
• RBREAKCommand
• RUNCommand
• TRACEAction and Command
• WBREAKCommand
• WMCommand
• WMHISTORYCommand

For additional commands that are also valid in source code, see Actions.

Top

@ (At) Command

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:

%RUL-W-CANTOPEN, @ -- Unable to open file filespec for reading

Format

@ filespec

Argument

Examples

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:\SMITH\WORK\INIT%MEM.COM|

Top

CS Command

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 timetag-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

Arguments

None.

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

Top

DISABLE Command

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

Format

DISABLE  feature

Argument

Examples

The following command disables the WMHISTORY command:

RuleWorks> disable wmh

Top

Enable and Disable Keywords

The table below describes the features that you can enable and disable:

Top

EBREAK Command

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 messages 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

The block name is always displayed in EBREAK messages, whether BLOCK-NAMES are enabled or disabled.

Format

Keywords

Arguments

Examples

The first command displays the names of the entry blocks for which breakpoints are set:

RuleWorks>ebreak
  1  ???
  2  ???
  3  ???

The next command clears one of the breakpoints displayed above:

RuleWorks> ebreak off 2

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

RuleWorks>run
EBREAK entering |main|
%RUL-I-BREAKNOTED, Execution paused by break

Top

ENABLE Command

Enables the run-time feature specified by a keyword argument. 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 you have enabled by using the DISABLE command.

Format

ENABLE  feature

Argument

Example

The following command enables run-time messages:

RuleWorks> enable war

Top

EXIT Command

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>

Top

MATCHES Command

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 the 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 Section 11.2.8.

Format

MATCHES  rule-name ...

Argument

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

Top

NEXT Command

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  #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
   15 (15): MODIFY-SOFTWARE-MEDIA:35-CHEAPEST #38 71  #32 58  #45 70

Top

PPCLASS Command

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

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

Example

This 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

Top

PPWM Command

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. Unlike CEs, 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- construct). 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

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

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

Arguments

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)

Top

RBREAK Command

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

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.

Keywords

Arguments

Examples

This command displays the names of the rules for 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

Top

RUN Command

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 and compiler switch to pause execution and invoke the RuleWorks command interpreter.

Format

RUN  [integer]

Argument

This argument is optional. If you do not specify an integer, the run-time system executes recognizeact cycles until no rules are satisfied or until a RETURN or QUIT action, or a breakpoint interrupts execution.

Note:

If the program halts, the run-time system does not execute the number of recognize-act cycles indicated by the integer.

Examples

The following command starts executing recognize-act cycles:

RuleWorks> run

The following command executes four recognize-act cycles:

RuleWorks> run 4

Top

WBREAK Command

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, WBREAK 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, displays messages in the format below, and invokes the command interpreter:

%RUL-I-WBREAK, WBREAK encountered on class-name #instanceid

%RUL-I-BREAKNOTED, Execution paused by break

Format

Keywords

Arguments

Examples

RuleWorks> wbreak on control-context

RuleWorks> run

%RUL-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>

Top

WM Command

Displays the objects whose INSTANCE-IDs you specify. 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- construct). 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

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

Examples

The following command displays all visible objects:

RuleWorks> wm

???

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

RuleWorks> wm #3 #4

???

???

Top

WMHISTORY Command

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] {^attr1 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

Examples

This 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-KIW I]  ^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:PLAC E-NONMEMORY]   ^NAME BOX [EXPAND-PART-SKELETONS:BOX]  ^PART-NUMBER KI-9200 [EXPAND-PART-SKELETONS:BOX]  ^PRINTNAME Kiwi-9200 CPU Base Unit [EXPAND-PART-SKEL ETONS: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

Top