www.RuleWorks.co.uk

Performs the arithmetic modulus operation on integer values.

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

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

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

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

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

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

• Example

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

(memory ^$ID <the-mem>)

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

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

• Format

^attribute = value-expression

• Operands

^attribute

An attribute of a WMO whose value is to be tested

value-expression

Any RuleWorks expression, whose value is to be tested

• Example

The following CE uses the less restrictive equality predicate:

(active-context ^name = verify-configuration)

• Example

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

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

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

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

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

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

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

B, F, P, V 1

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

D, T 3

L 4

M, N 5

R 6

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

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

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

^$ID == <the-id>

^$ID ~= <the-id>

The identity predicate is more efficient.

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

• Format

^attribute ~= value-expression

value-expression ~= value-expression

• Operands

^attribute

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

value-expression

Any RuleWorks expression, whose value is to be tested.

• Examples

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

Table 12. Similarity Testing

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

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

Table 13. SOUNDEX Codes and Symbols

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

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

• Format

EVERY class-name

Argument

Class-name

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

• Return Value

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

The INSTANCE-Ids are returned in no particular order.

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

• Example

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

(bind <dogs> (every dog))

(for-each <dog> in <dogs>

(wash-pet <dog>)

(pet-to-vet <dog>)

(pet-gets-treat <dog>))

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

• Format

EXIT

• Example

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

RuleWorks> EXIT

System>

• Format

(EXTERNAL-ROUTINE) routine-name

[(ALIAS actual-routine-name)]

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

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

• Argument

routine-name

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

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

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

less than 32 characters long

different from all C keywords

• Clauses

ALIAS

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

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

ACCEPTS

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

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

RETURNS

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

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

• Examples

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

(EXTERNAL-ROUTINE mth$random

(ACCEPTS <seed> LONG BY REFERENCE)

(RETURNS LONG BY VALUE)

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

(EXTERNAL-ROUTINE xt_parent

(ACCEPTS <param1> INTEGER)

(RETURNS <param2> INTEGER)

(ALIAS "XtParent"))

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

(EXTERNAL-ROUTINE getenv__; from the POSIX library

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

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

 

• FOR-EACH

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

• Format (for a compound)

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

• Arguments

<element>

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

compound-value

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

RHS-action

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

<data-value>

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

<key-name>

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

table-value

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

• Examples

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

(rule print-out-cage:do-it

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

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

-->

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

(bind <slot-counter> 1)

(for-each <card> in <cards>

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

|contains a| <card>)

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

 

• FLOAT

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

• Format

(FLOAT numeric-expr )

• Argument

numeric-expr

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

Table 23. FLOAT Calls and their Return Values

Function Call Return Value Warning Message?

(FLOAT 3) 3.0 No

(FLOAT 3.2) 3.2 No

(FLOAT |3.2|) 3.2 No

(FLOAT |76 trombones|) 76.0 No

(FLOAT 2+2) 0.0 Yes

(FLOAT #32) 0.0 Yes

 

• GENATOM

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

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

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

Table -24. Atom Generator and Returns

Routine Call or RHS Action Atom Generated

rul_genint 1

rul_gensymp(R:) R:2

(GENATOM) G:3

(GENINT) 4

rul_gensym G:5

 

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

• Format

(GENATOM [prefix])

• Argument

prefix

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

 

• Return Value

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

• Example

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

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

• GENINT

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

 

• Format

(GENINT)

 

• Return Value

An INTEGER value.

 

• Example

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

(bind <transaction-id> (genint))

• GET

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

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

 

• Format

(GET object-id ^attribute-name)

 

• Arguments

Object-id

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

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

attribute-name

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

Return Value

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

 

• Example

The following example shows one use of the GET function:

(OBJECT-CLASS fruit

^fruit-name

^color)

 

(rule make-a-similar-one

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

à

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

• IF.THEN.ELSE.

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

 

• Format

(IF (rel-expr)

THEN RHS-action.

[ELSE RHS-action..])

 

• Arguments

rel-expr

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

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

RHS-action

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

 

• Clauses

THEN

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

ELSE

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

• INTEGER

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

• Format

(INTEGER numeric-expr )

• Argument

numeric-expr

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

 

• Return Value

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

 

• Examples

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

Table 25. INTEGER Return Values

Function Call Return Value Warning Message?

(INTEGER 3) 3 No

(INTEGER 3.5) 4 No

(INTEGER 3.5e4) 35000 No

(INTEGER |3.2|) 3 No

(INTEGER |110 cornets|) 110 No

(INTEGER 2+2) 0 Yes

(INTEGER #12) 0 Yes

• IS-OPEN

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

 

• Format

(IS-OPEN file-id)

 

• Argument

File-id

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

 

• Return Value

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

 

• Example

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

 

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

then

(closefile infil))

• LENGTH

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

 

• Format

LENGTH compound-val

 

• Argument

Compound-val

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

 

• Return Value

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

 

• Examples

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

 

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

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

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

• MAKE

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

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

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

• Format (for action)

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

• Format (for command)

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

• Arguments(Arguments)

class-name

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

attribute

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

value-expression

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

value

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

• Return Value

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