8. The Jess Function List

In this chapter, every Jess language function shipped with Jess version 6.0 is described. Some of these functions are intrinsic functions while others are optional and may not be available to all Jess code. All of these functions are installed into the command-line version of Jess; to use a function marked (optional) in your own programs, you need to either add the appropriate Userpackage or load the script library (see the chapters on Jess/Java programming and extending Jess with Java). The package for each function is listed below.

Note: many functions documented as requiring a specific minimum number of arguments will actually return sensible results with fewer; for example, the + function will return the value of a single argument as its result. This behavior is to be regarded as undocumented and unsupported. In addition, all functions documented as requiring a specific number of arguments will not report an error if invoked with more than that number; extra arguments are simply ignored.

8.1. (* <numeric-expression> <numeric-expression>+)

Package:
Intrinsics
Arguments:
Two or more numeric expressions
Returns:
Number
Description:
Returns the products of its arguments. The return value is an INTEGER unless any of the arguments are FLOAT, in which case it is a FLOAT.

8.2. (** <numeric-expression> <numeric-expression>)

Package:
MathFunctions
Arguments:
Two numeric expressions
Returns:
Number
Description:
Raises its first argument to the power of its second argument (using Java's Math.pow() function). Note: the return value is NaN (not a number) if both arguments are negative.

8.3. (+ <numeric-expression> <numeric-expression>+)

Package:
Intrinsics
Arguments:
Two or more numeric expressions
Returns:
Number
Description:
Returns the sum of its arguments. The return value is an INTEGER unless any of the arguments are FLOAT, in which case it is a FLOAT.

8.4. (- <numeric-expression> <numeric-expression>+)

Package:
Intrinsics
Arguments:
Two or more numeric expressions
Returns:
Number
Description:
Returns the first argument minus all subsequent arguments. The return value is an INTEGER unless any of the arguments are FLOAT, in which case it is a FLOAT.

8.5. (/ <numeric-expression> <numeric-expression>+)

Package:
Intrinsics
Arguments:
Two or more numeric expressions
Returns:
Number
Description:
Returns the first argument divided by all subsequent arguments. The return value is a FLOAT.

8.6. (< <numeric-expression> <numeric-expression>+)

Package:
Intrinsics
Arguments:
Two or more numeric expressions
Returns:
Boolean
Description:
Returns TRUE if each argument is less in value than the argument following it; otherwise, returns FALSE.

8.7. (<= <numeric-expression> <numeric-expression>+)

Package:
Intrinsics
Arguments:
Two or more numeric expressions
Returns:
Boolean
Description:
Returns TRUE if the value of each argument is less than or equal to the value of the argument following it; otherwise, returns FALSE.

8.8. (<> <numeric-expression> <numeric-expression>+)

Package:
Intrinsics
Arguments:
Two or more numeric expressions
Returns:
Boolean
Description:
Returns TRUE if the value of the first argument is not equal in value to all subsequent arguments; otherwise returns FALSE.

8.9. (= <numeric-expression> <numeric-expression>+)

Package:
Intrinsics
Arguments:
Two or more numeric expressions
Returns:
Boolean
Description:
Returns TRUE if the value of the first argument is equal in value to all subsequent arguments; otherwise, returns FALSE. The integer 2 and the float 2.0 are =, but not eq.

8.10. (> <numeric-expression> <numeric-expression>+)

Package:
Intrinsics
Arguments:
Two or more numeric expressions
Returns:
Boolean
Description:
Returns TRUE if the value of each argument is less than that of the argument following it; otherwise, returns FALSE.

8.11. (>= <numeric-expression> <numeric-expression>+)

Package:
Intrinsics
Arguments:
Two or more numeric expressions
Returns:
Boolean
Description:
Returns TRUE if the value of each argument is greater than or equal to that of the argument following it; otherwise, returns FALSE.

8.12. (abs <numeric-expression>)

Package:
MathFunctions
Arguments:
One numeric expression
Returns:
Number
Description:
Returns the absolute value of its only argument.

8.13. (agenda)

Package:
MiscFunctions
Arguments:
None
Returns:
NIL
Description:
Displays a list of rule activations to the WSTDOUT router.

8.14. (and <expression>+)

Package:
Intrinsics
Arguments:
One or more expressions
Returns:
Boolean
Description:
Returns TRUE if all arguments evaluate to a non-FALSE value; otherwise, returns FALSE.

8.15. (apply <expression>+)

Package:
LispFunctions
Arguments:
One or more expressions
Returns:
An expression
Description:
Returns the result of calling the first argument, as a Jess function, on all the remaining arguments. The strength of this method lies in the fact that you can call a function whose name, for instance, is in a Jess variable.

8.16. (assert <fact>+)

Package:
Intrinsics
Arguments:
One or more facts (not fact-IDs)
Returns:
Fact-ID or FALSE
Description:
Adds a fact to the fact list. Asserts all facts onto the fact list; returns the fact-ID of last fact asserted or FALSE if no facts were successfully asserted (for example, if all facts given are duplicates of existing facts.)

8.17. (assert-string <string-expression>)

Package:
Intrinsics
Arguments:
One string representing a fact
Returns:
Fact-ID or FALSE
Description:
Converts a string into a fact and asserts it. Attempts to parse string as a fact, and if successful, returns the value returned by assert with the same fact. Note that the string must contain the fact's enclosing parentheses.

8.18. (bag <bag-command> <bag-arguments>+)

Package:
BagFunctions
Arguments:
An atom (a sub-command) and one or more additional arguments
Returns:
(Varies)
Description:
The bag command lets you manipulate Java hashtables from Jess. The net result is that you can create any number of associative arrays or property lists. Each such array or list has a name by which it can be looked up. The lists can contain other lists as properties, or any other Jess data type.

The bag command does different things based on its first argument. It's really seven commands in one:

8.19. (batch <filename>)

Package:
Miscfunctions
Arguments:
One string or atom representing the name of a file
Returns:
(Varies)
Description:
Attempts to parse and evaluate the given file as Jess code. If successful, returns the return value of the last expression in the file.

Note: the argument must follow Jess' rules for valid atoms or strings. On UNIX systems, this presents no particular problems, but Win32 filenames may need special treatment. In particular: pathnames should use either '\\' (double backslash) or '/' (forward slash) instead of '\' (single backslash) as directory separators; and pathnames which include a colon (':') or a space character (' ') must be enclosed in double quotes.

In an applet, batch will try to find the file relative to the applet's document base. In any program, if the file is not found, the name is then passed to ClassLoader.getSystemResourceAsStream(). This allows files along the class path, including files in JARs, to be batched.

8.20. (bind <variable> <expression>*)

Package:
Intrinsics
Arguments:
A variable name and any value
Returns:
(Varies)
Description:
Binds a variable to a new value. Assigns the given value to the given variable, creating the variable if necessary. Returns the given value.

8.21. (bit-and <integer-expression>+)

Package:
MiscFunctions
Arguments:
One or more integer expressions
Returns:
int
Description:
Performs the bitwise AND of the arguments. (bit-and 7 4) is 4, and is equivalent to the Java 7 & 4.

8.22. (bit-not <integer-expression>)

Package:
MiscFunctions
Arguments:
One integer expression
Returns:
int
Description:
Performs the bitwise NOT of the argument. (bit-not 0) is -1, and is equivalent to the Java ~0.

8.23. (bit-or <integer-expression>+)

Package:
MiscFunctions
Arguments:
One or more integer expressions
Returns:
int
Description:
Performs the bitwise OR of the arguments. (bit-or 2 4) is 6, and is equivalent to the Java 2 | 4.

8.24. (bload <filename>)

Package:
DumpFunctions
Arguments:
One string or atom representing the name of a file
Returns:
TRUE
Description:
The argument is the name of a file previously produced by the bsave command. The file is decompressed and deserialized to restore the state of the current Rete object. I/O routers are not restored from the file; they retain their previous state. Furthermore, JessListeners are not restored from the file; again, they are retained from their state prior to the bload.

8.25. (bsave <filename>)

Package:
DumpFunctions
Arguments:
One string or atom representing the name of a file
Returns:
TRUE
Description:
Dumps the engine in which it is called to the given filename argument in a format that can be read using bload. Any input/output streams and event listeners are not saved during the serialization process.

8.26. (build <string-expression>)

Package:
Miscfunctions
Arguments:
One string representing some Jess code
Returns:
(Varies)
Description:
Evaluates a string as though it were entered at the command prompt. Only allows constructs to be evaluated. Attempts to parse and evaluate the given string as Jess code. If successful, returns the return value of the last expression in the string. This is typically used to define rules from Jess code. For instance:

(build "(defrule foo (foo) => (bar))")

Note: The string must consist of one single construct; multiple constructs can be built using multiple calls to build.

8.27. (call (<external-address> | <string-expression>) <string-expression> <call-arguments>+)

Package:
ReflectFunctions
Arguments:
an external address or String, a String, and any number of additional arguments
Returns:
(Varies)
Description:
Calls a Java method on the given object, or a static method of the class named by the first argument. The second argument is the name of the method, and subsequent arguments are passed to the method. Arguments are promoted and overloaded methods selected precisely as for new. The return value is converted to a suitable Jess value before being returned. Array return values are converted to multifields.

The functor call may be omitted if the method being called is non-static and the object is represented by a simple variable. The following two method calls are equivalent: 

        
        ;; These are legal and equivalent
        (call ?vector addElement (new java.lang.String "Foo"))
        (?vector addElement (new java.lang.String "Foo"))
call may not be omitted if the object comes from the return value of another function call: 
        ;; This is illegal
        ((new java.lang.Vector 10) addElement (new java.lang.String "Foo"))

8.28. (call-on-engine <external-address> <jess-code>)

Package:
MiscFunctions
Arguments:
an external address (must be a jess.Rete object), and an executable snippet of Jess code
Returns:
(Varies)
Description:
Executes some Jess code in the context of the given Rete object. This is a nice way to send messages between multiple Rete engines in one process. Note that the current variable context is used to evaluate the code, so (for instance) all defglobal values will be from the calling engine, not the target.

8.29. (clear)

Package:
Intrinsics
Arguments:
None
Returns:
TRUE
Description:
Clears Jess. Deletes all rules, deffacts, defglobals, deftemplates, facts, activations, and so forth. Java Userfunctions are not deleted.

8.30. (clear-storage)

Package:
Intrinsics
Arguments:
None
Returns:
TRUE
Description:
Clears the hashtable used by (store) and (fetch).

8.31. (close [<router-identifier>])

Package:
Intrinsics
Arguments:
One or more router identifiers (atoms)
Returns:
TRUE
Description:
Closes any I/O routers associated with the given name by calling close() on the underlying stream, then removes the routers. Any subsequent attempt to use a closed router will report bad router. See open.

8.32. (complement$ <multifield-expression> <multifield-expression>)

Package:
MultiFunctions
Arguments:
Two multifields
Returns:
Multifield
Description:
Returns a new multifield consisting of all elements of the second multifield not appearing in the first multifield.

8.33. (context)

Package:
ReflectFunctions
Arguments:
None
Returns:
External address
Description:
Returns the execution context (a jess.Context object) it is called in. This provides a way for deffunctions to get a handle to this useful class.

8.34. (count-query-results <query-name> <expression>+)

Package:
MiscFunctions
Arguments:
An atom, and zero or more additional expressions
Returns:
INTEGER
Description:
Runs a defquery and returns a count of the matches. See the documentation for defquery for more details. Also see run-query for caveats concerning calling count-query-results on a rule RHS.

8.35. (create$ <expression>*)

Package:
MultiFunctions
Arguments:
Zero or more expressions
Returns:
Multifield
Description:
Appends its arguments together to create a multifield value. Returns a new multifield containing all the given arguments, in order. For each argument that is a multifield, the individual elements of the multifield are added to the new multifield; this function will not create nested multifields (which are not meaningful in the Jess language.) Note: multifields must be created explicitly using this function or others that return them. Multifields cannot be directly parsed from Jess input.

8.36. (defadvice (before | after) (<function-name> | <multifield> ) <function-call>+)

Package:
Intrinsics
Arguments:
The atom before or the atom after, followed by either one function name or a multifield of function names or the atom ALL, followed by one or more function calls.
Returns:
(varies)
Description:
Lets you supply extra code to run before or after the named function(s) or all functions. If before is specified, the code will execute before the named function(s); the variable $?argv will hold the arguments to the function on entry to and exit from the code block. If after is specified, the function will be called before the code block is entered. When the block is entered, the variable ?retval will refer to the original function's return value.

Whether before or after is specified, if the code block explicitly calls return with a value, the returned value will appear to the caller to be the return value of the original function. For before advice, this means the original function will not be called in this case.

8.37. (defclass <tag> <Java class name> [extends <tag>])

Package:
ReflectFunctions
Arguments:
Two or four atoms, as noted above
Returns:
The second argument
Description:
Defines a deftemplate with the given tag, with slots based on the Java Beans properties found in the named class. If the optional extends clause is included, the second tag will become the parent template of the new template. The common slots in the two templates will be in the same order, at the beginning of the new template. Rules defined to match instances of the parent template will also match instances of the new child template.

8.38. (definstance <tag> <Java object> [static | dynamic] )

Package:
ReflectFunctions
Arguments:
An atom, a Java object, and (optionally) one of the atoms static or dynamic.
Returns:
The fact-id of the new shadow fact.
Description:
Creates a "shadow fact" representing the given Java object, according to the named deftemplate (which should have come from defclass.) If the atom static is not supplied as the optional third argument, a PropertyChangeListener is installed in the given object, so that Jess can keep the shadow fact updated if the object's properties change.

Note that it is an error for a given Java object to be installed in more than one definstance at a time. The second and subsequent definstance calls for a given object will return a fact-id with value -1.

8.39. (delete$ <multifield-expression> <begin-integer-expression> <end-integer-expression>)

Package:
MultiFunctions
Arguments:
A multifield and two integer expressions
Returns:
Multifield
Description:
Deletes the specified range from a multifield value. The first numeric expression is the 1-based index of the first element to remove; the second is the 1-based index of the last element to remove.

8.40. (div <numeric-expression> <numeric-expression>+)

Package:
MathFunctions
Arguments:
Two or more numeric expressions
Returns:
Numbers
Description:
Returns the first argument divided by all subsequent arguments using integer division. Quotient of the values of the two numeric expressions rounded to the nearest integer.

8.41. (do-backward-chaining <deftemplate-tag>)

Package:
Intrinsics
Arguments:
Name of a deftemplate (ordered or unordered)
Returns:
TRUE
Description:
Marks a deftemplate as being eligible for backwards chaining, as described in the text.

8.42. (e)

Package:
MathFunctions
Arguments:
None
Returns:
Number
Description:
Returns the transcendental number e.

8.43. (engine)

Package:
MiscFunctions
Arguments:
None
Returns:
External address
Description:
Returns an external-address object containing the Rete engine in which the function in called.

8.44. (eq <expression> <expression>+)

Package:
Intrinsics
Arguments:
Two or more arbitrary arguments
Returns:
Boolean
Description:
Returns TRUE if the first argument is equal in type and value to all subsequent arguments. For strings, this means identical contents. Uses the Java Object.equals() function, so can be redefined for external types. Note that the integer 2 and the floating-point number 2.0 are not eq, but they are eq* and =.

8.45. (eq* <expression> <expression>+)

Package:
Intrinsics
Arguments:
Two or more arbitrary arguments
Returns:
Boolean
Description:
Returns TRUE if the first argument is equivalent to all the others. Uses numeric equality for numeric types, unlike eq. Note that the integer 2 and the floating-point number 2.0 are not eq, but they are eq* and =.

8.46. (eval <lexeme-expression>)

Package:
Intrinsics
Arguments:
One string containing a valid Jess expression
Returns:
(Varies)
Description:
Evaluates a string as though it were entered at a command prompt. Only allows functions to be evaluated. Evaluates the string as if entered at the command line and returns the result.

Note: The string must consist of one single function call; multiple calls can be evaluated using multiple calls to eval.

8.47. (evenp <expression>)

Package:
PredFunctions
Arguments:
One numeric expression
Returns:
Boolean
Description:
Returns TRUE for even numbers; otherwise, returns FALSE. Results with non-integers may be unpredictable.

8.48. (exit)

Package:
Intrinsics
Arguments:
None
Returns:
Nothing
Description:
Exits Jess and halts Java.

8.49. (exp <numeric-expression>)

Package:
MathFunctions
Arguments:
One numeric expression
Returns:
Number
Description:
Raises the value e to the power of its only argument.

8.50. (explode$ <string-expression>)

Package:
MultiFunctions
Arguments:
One string
Returns:
Multifield
Description:
Creates a multifield value from a string. Parses the string as if by a succession of read calls, then returns these individual values as the elements of a multifield.

8.51. (external-addressp <expression>)

Package:
PredFunctions
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE or FALSE as the given expression is an external-address.

8.52. (fact-id <integer>)

Package:
Miscfunctions
Arguments:
One number, a fact-id
Returns:
The given number as an RU.FACT
Description:
If the argument is the fact-id of an existing fact, returns the number as a value of type RU.FACT; otherwise throws an exception.

8.53. (fact-slot-value <fact-id> <slot-name>)

Package:
Scriptlib
Arguments:
A fact-id and a slot name
Returns:
(varies)
Description:
Returns the value in the named slot of the fact with the given fact-id.

8.54. (facts)

Package:
Scriptlib
Arguments:
None
Returns:
TRUE
Description:
Prints a list of all facts on the fact list.

8.55. (fetch <string or atom>)

Package:
Intrinsics
Arguments:
One string or atom
Returns:
(varies)
Description:
Retrieves and returns any value previously stored by the store function under the given name, or nil if there is none. Analogous to the fetch() member function of the Rete class. See the section on using store and fetch for details.

8.56. (first$ <multifield-expression>)

Package:
MultiFunctions
Arguments:
One multifield
Returns:
Multifield
Description:
Returns the first field of a multifield as a new 1-element multifield.

8.57. (float <numeric-expression>)

Package:
MathFunctions
Arguments:
One numeric expression
Returns:
Floating-point number
Description:
Converts its only argument to a float.

8.58. (floatp <expression>)

Package:
PredFunctions
Arguments:
One numeric expression
Returns:
Boolean
Description:
Returns TRUE for floats; otherwise, returns FALSE.

8.59. (foreach <variable> <multifield-expression> <action>*)

Package:
Intrinsics
Arguments:
A variable, a multifield expression, and zero or more arguments
Returns:
Varies
Description:
The named variable is set to each of the values in the multifield in turn; for each value, all of the other arguments are evaluated in order. The return function can be used to break the iteration.

Example:

(foreach ?x (create$ a b c d) (printout t ?x crlf))

8.60. (format <router-identifier> <string-expression> <expression>*)

Package:
MiscFunctions
Arguments:
A router identifier, a format string, and zero or more arguments
Returns:
A string
Description:
Sends formatted output to the specified logical name. Formats the arguments into a string according to the format string, which is identical to that used by printf in the C language (find a C book for more information). Returns the string, and optionally prints the string to the named router. If you pass nil for the router name, no printing is done.

8.61. (gensym*)

Package:
Intrinsics
Arguments:
None
Returns:
Atom
Description:
Returns a special unique sequenced value. Returns a unique atom which consists of the letters gen plus an integer. Use setgen to set the value of the integer to be used by the next gensym call.

8.62. (get <external-address> <string-expression>)

Package:
ReflectFunctions
Arguments:
An external address and a string.
Returns:
(Varies)
Description:
Retrieves the value of a Java Bean's property. The first argument is the object and the second argument is the name of the property. The return value is converted to a suitable Jess value exactly as for call.

8.63. (get-member (<external-address> | <string-expression>) <string-expression>)

Package:
reflect,ReflectFunctions
Arguments:
An external address or a string, and a string.
Returns:
(Varies)
Description:
Retrieves the value of a Java object's data member. The first argument is the object (or the name of a class, for a static member) and the second argument is the name of the field. The return value is converted to a suitable Jess value exactly as for call.

8.64. (get-multithreaded-io)

Package:
Intrinsics
Arguments:
None
Returns:
Boolean
Description:
Returns TRUE is Jess is currently using a separate thread to flush I/O streams. Turning this on can lead to a modest performance enhancement, at the expense of possible loss of output on program termination.

8.65. (get-reset-globals)

Package:
MiscFunctions
Arguments:
None
Returns:
Boolean
Description:
Indicates the current setting of global variable reset behavior. See set-reset-globals for an explanation of this property.

8.66. get-salience-evaluation

Package:
MiscFunctions
Arguments:
None
Returns:
Atom
Description:
Indicates the current setting of salience evaluation behavior. See set-salience-evaluation for an explanation of this property.

8.67. (halt)

Package:
Intrinsics
Arguments:
None
Returns:
TRUE
Description:
Halts rule execution. No effect unless called from the RHS of a rule.

8.68. (if <expression> then <action>* [else <action>*])

Package:
Intrinsics
Arguments:
A Boolean variable or function call returning Boolean, the atom then, and any number of additional expressions; optionally followed by the atom else another list of expression.
Returns:
(Varies)
Description:
Allows conditional execution of a group of actions. The boolean expression is evaluated. If it does not evaluate to FALSE, the first list of expressions is evaluated, and the return value is that returned by the last expression of that list. If it does evaluate to FALSE, and the optional second list of expressions is supplied, those expressions are evaluated and the value of the last is returned.

Example: 

    (if (> ?x 100)
        then
          (printout t "X is big" crlf)
        else
          (printout t "X is small" crlf))

8.69. (implode$ <multifield-expression>)

Package:
MultiFunctions
Arguments:
One multifield
Returns:
String
Description:
Creates a string from a multifield value. Converts each element of the multifield to a string, and returns these strings concatenated with single intervening spaces.

8.70. (import <atom>)

Package:
ReflectFunctions
Arguments:
One atom
Returns:
TRUE
Description:
Works like the Java import statement. You can import either a whole package using 
     (import java.io.*)
or a single class using 
     (import java.awt.Button)
After that, all functions that can accept a Java class name (new, defclass, call, etc) will refer to the import list to try to find the class that goes with a specific name. Note that java.lang.* is now implicitly imported.

8.71. (insert$ <multifield-expression> <integer-expression> <single-or-multifield-expression>+)

Package:
MultiFunctions
Arguments:
A multifield, an integer, and one or more multifields
Returns:
A multifield
Description:
Inserts one or more values in a multifield. Inserts the elements of the second and later multifields so that they appear starting at the given 1-based index of the first multifield.

8.72. (integer <numeric-expression>)

Package:
MathFunctions
Arguments:
One numeric expression
Returns:
Integer
Description:
Converts its only argument to an integer. Truncates any fractional component of the value of the given numeric expression and returns the integral part.

8.73. (integerp <expression>)

Package:
PredFunctions
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE for integers; otherwise, returns FALSE.

8.74. (intersection$ <multifield-expression> <multifield-expression>)

Package:
MultiFunctions
Arguments:
Two multifields
Returns:
Multifield
Description:
Returns the intersection of two multifields. Returns a multifield consisting of the elements the two argument multifields have in common.

8.75. (jess-version-number)

Package:
Intrinsics
Arguments:
None
Returns:
Float
Description:
Returns a version number for Jess; currently 6.0 .

8.76. (jess-version-string)

Package:
Intrinsics
Arguments:
None
Returns:
String
Description:
Returns a human-readable string descriptive of this version of Jess.

8.77. (length$ <multifield-expression>)

Package:
MultiFunctions
Arguments:
Multifield
Returns:
Integer
Description:
Returns the number of fields in a multifield value.

8.78. (lexemep <expression>)

Package:
PredFunctions
Arguments:
Any expression
Returns:
Boolean
Description:
Returns TRUE for symbols and strings; otherwise, returns FALSE.

8.79. (list-function$)

Package:
Intrinsics
Arguments:
None
Returns:
Multifield
Description:
Returns a multifield list of all the functions currently callable, including intrinsics, deffunctions, and Userfunctions. Each function name is an atom. The names are sorted in alphabetical order.

8.80. (load-facts <file-name>)

Package:
Intrinsics
Arguments:
A string or atom representing the name of a file of facts
Returns:
Boolean
Description:
Asserts facts loaded from a file. The argument should name a file containing a list of facts (not deffacts constructs, and no other commands or constructs). Jess will parse the file and assert each fact. The return value is the return value of assert when asserting the last fact. In an applet, load-facts will use getDocumentBase() to find the named file.

Note: See the batch command for a discussion about specifying filenames in Jess.

8.81. (load-function <class-name>)

Package:
MiscFunctions
Arguments:
One string or atom representing the name of a Java class
Returns:
Boolean
Description:
The argument must be the fully-qualified name of a Java class that implements the Userfunction interface. The class is loaded in to Jess and added to the engine, thus making the corresponding command available. See Extending Jess with Java for more information.

8.82. (load-package <class-name>)

Package:
MiscFunctions
Arguments:
One string or atom, the name of a Java class
Returns:
Boolean
Description:
The argument must be the fully-qualified name of a Java class that implements the Userpackage interface. The class is loaded in to Jess and added to the engine, thus making the corresponding package of commands available. See Extending Jess with Java for more information.

8.83. (log <numeric-expression>)

Package:
MathFunctions
Arguments:
One numeric expression
Returns:
Number
Description:
Returns the logarithm base e of its only argument.

8.84. (log10 <numeric-expression>)

Package:
MathFunctions
Arguments:
One numeric expression
Returns:
Number
Description:
Returns the logarithm base-10 of its only argument.

8.85. (long <expression>)

Package:
MiscFunctions
Arguments:
One expression, either numeric or String
Returns:
RU.LONG
Description:
Interprets the expression as a Java long (if possible) and returns a long value. Use strings or atoms for precise values that can't be expressed as an int. Longs in Jess are "second class citizens" in the sense that you can't directly do math on them. You can assign them to variables, pass them to function calls, and convert them to Strings or floating-point numbers.

8.86. (longp <expression>)

Package:
MiscFunctions
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE if the expression is of type RU.LONG; FALSE otherwise.

8.87. (lowcase <lexeme-expression>)

Package:
StringFunctions
Arguments:
One atom or string.
Returns:
String
Description:
Converts uppercase characters in a string or symbol to lowercase. Returns the argument as an all-lowercase string.

8.88. (matches <lexeme-expression>)

Package:
ViewFunctions
Arguments:
One atom, a rule or query name
Returns:
TRUE
Description:
Produces an ugly printout, useful for debugging, of the contents of the left and right Rete memories of each two-input node on the given rule or query's LHS.

8.89. (max <numeric-expression>+)

Package:
MathFunctions
Arguments:
One or more numerical expressions
Returns:
Number
Description:
Returns the value of its largest numeric argument

8.90. (member$ <single-field-expression> <multifield-expression>)

Package:
MultiFunctions
Arguments:
A value and a multifield
Returns:
Integer or FALSE
Description:
Returns the position (1-based index) of a single-field value within a multifield value; otherwise, returns FALSE.

8.91. (min <numeric-expression>+)

Package:
MathFunctions
Arguments:
One or more numeric expressions
Returns:
Number
Description:
Returns the value of its smallest numeric argument.

8.92. (mod <numeric-expression> <numeric-expression>)

Package:
Intrinsics
Arguments:
Two integer expressions
Returns:
Integer
Description:
Returns the remainder of the result of dividing the first argument by its second (assuming that the result of the division must be an integer).

8.93. (modify <fact-specified> <RHS-slot>*)

Package:
Intrinsics
Arguments:
A fact-ID and zero or more two-element lists
Returns:
Fact-ID
Description:
Modifies the deftemplate fact in the fact list. The fact-ID must belong to an unordered fact. Each list is taken as the name of a slot in this fact and a new value to assign to the slot. A new fact is asserted which is similar to the given fact but which has the specified slots replaced with new values. The original fact is retracted. The fact-ID of the new fact is returned. Modifying a definstance fact will cause the appropriate object properties to be set as well.

8.94. (multifieldp <expression>)

Package:
PredFunctions
Arguments:
Any value
Returns:
Boolean
Description:
Returns TRUE for multifield values; otherwise, returns FALSE.

8.95. (neq <expression> <expression>+)

Package:
Intrinsics
Arguments:
Two or more values
Returns:
Boolean
Description:
Returns TRUE if the first argument is not equal in type and value to all subsequent arguments (see eq).

8.96. (new <string-expression> <new-arguments>+)

Package:
ReflectFunctions
Arguments:
A string and one or more arguments
Returns:
Boolean
Description:
Creates a new Java object and returns an EXTERNAL_ADDRESS value containing it. The first argument is the fully-qualified class name: java.util.Vector, for example. The second and later arguments are constructor arguments. The constructor will be chosen from among all constuctors for the named class based on a first-best fit algorithm. Built-in Jess types are converted as necessary to match available constructors. See the text for more details.

8.97. (not <expression>)

Package:
Intrinsics
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE if its only arguments evaluates to FALSE; otherwise, returns FALSE.

8.98. (nth$ <integer-expression> <multifield-expression>)

Package:
MultiFunctions
Arguments:
A number and a multifield
Returns:
(Varies)
Description:
Returns the value of the specified (1-based index) field of a multifield value.

8.99. (numberp <expression>)

Package:
PredFunctions
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE for numbers; otherwise, returns FALSE.

8.100. (oddp <integer-expression>)

Package:
PredFunctions
Arguments:
One integer expression
Returns:
Boolean
Description:
Returns TRUE for odd numbers; otherwise, returns FALSE; see evenp.

8.101. (open <file-name> <router-identifier> [r|w|a])

Package:
Intrinsics
Arguments:
A file name, an identifier for the file (an atom), and optionally a mode string, one of r, w, a.
Returns:
The file identifier, a router name.
Description:
Opens a file. Subsequently, the given router identifier can be passed to printout, read, readline, or any other functions that accept I/O routers as arguments. By default, the file is opened for reading; if a mode string is given, it may be opened for reading only (r), writing only (w), or appending (a).

Note: See the batch command for a discussion about specifying filenames in Jess.

8.102. (or <expression>+)

Package:
Intrinsics
Arguments:
One or more expressions
Returns:
Boolean
Description:
Returns TRUE if any of the arguments evaluates to a non-FALSE value; otherwise, returns FALSE.

8.103. (pi)

Package:
MathFunctions
Arguments:
None
Returns:
Number
Description:
Returns the number pi.

8.104. (ppdeffunction <atom>)

Package:
Scriptlib
Arguments:
An atom, the name of a deffunction
Returns:
nil
Description:
Pretty-prints a deffunction to the 't' standard output router.

8.105. (ppdefglobal <atom>)

Package:
Scriptlib
Arguments:
An atom, the name of a defglobal
Returns:
nil
Description:
Pretty-prints a defglobal to the 't' standard output router.

8.106. (ppdefrule <atom>)

Package:
Scriptlib
Arguments:
An atom, the name of a defrule or defquery
Returns:
nil
Description:
Pretty-prints a defrule or defquery to the 't' standard output router.

8.107. (ppdeftemplate <atom>)

Package:
Scriptlib
Arguments:
An atom, the name of a deftemplate
Returns:
nil
Description:
Pretty-prints a deftemplate to the 't' standard output router.

8.108. (printout <router-identifier> <expression>*)

Package:
Intrinsics
Arguments:
A router identifier followed by zero or more expressions
Returns:
nil
Description:
Sends unformatted output to the specified logical name. Prints its arguments to the named router, which must be open for output. No spaces are added between arguments. The special atom crlf prints as a newline. The special router name t can be used to signify standard output.

8.109. (progn <expression>+)

Package:
LispFunctions
Arguments:
One or more expressions
Returns:
The result of evaluating the last expression.
Description:
A simple control structure that allows you to group multiple function calls where syntactically only one is allowed - for instance, on the LHS of a rule.

8.110. (random)

Package:
MathFunctions
Arguments:
None
Returns:
Number
Description:
Returns a pseudo-random integer between 0 and 65536.

8.111. (read [<router-identifier>])

Package:
Intrinsics
Arguments:
An optional input router identifier (when omitted t is the default)
Returns:
(Varies)
Description:
Reads a single-field value from a specified logical name. Read a single atom, string, or number from the named router, returns this value. The router t means standard input. Newlines are treated as ordinary whitespace; this behaviour is different than in CLIPS, which returns newlines as tokens. If you need to parse text line-by-line, use readline and explode$.

8.112. (readline [<router-identifier>])

Package:
Intrinsics
Arguments:
An optional input router identifier (when omitted t is the default)
Returns:
String
Description:
Reads an entire line as a string from the specified logical name (router). The router t means standard input.

8.113. (replace$ <multifield-expression> <begin-integer-expression> <end-integer-expression> <multifield-expression>+)

Package:
MultiFunctions
Arguments:
A multifield, two numeric expressions, and one or more additional single or multifield values
Returns:
Multifield
Description:
Replaces the specified range of a multifield value with a set of values. The variable number of final arguments are inserted into the first multifield, replacing elements between the 1-based indices given by the two numeric arguments, inclusive. Example: 
Jess> (replace$ (create$ a b c) 2 2 (create$ x y z))
(a x y z c)

8.114. (reset)

Package:
Intrinsics
Arguments:
None
Returns:
TRUE
Description:
Removes all facts from the fact list, removes all activations, then asserts the fact (initial-fact), then asserts all facts found in deffacts, asserts a fact representing each registered definstance, and (if the set-reset-globals property is TRUE) initializes all defglobals.

8.115. (rest$ <multifield-expression>)

Package:
MultiFunctions
Arguments:
One multifield
Returns:
Multifield
Description:
Returns all but the first field of a multifield as a new multifield.

8.116. (retract <integer-expression>+)

Package:
Intrinsics
Arguments:
One or more fact-IDs (not integers)
Returns:
TRUE
Description:
Retracts the facts whose IDs are given. Retracting a definstance fact will result in an implict call to undefinstance for the corresponding object (the object will no longer be pattern-matched).

8.117. (retract-string <string>)

Package:
Intrinsics
Arguments:
A string, a representation of a Fact
Returns:
TRUE
Description:
Parses the string as a Fact; if such a fact exists on the knowledge base, calls retract on it.

8.118. (return [<expression>])

Package:
Intrinsics
Arguments:
An optional expression
Returns:
(Varies)
Description:
Returns the given value from a deffunction. Exits the deffunction immediately.

8.119. (round <numeric-expression>)

Package:
MathFunctions
Arguments:
One numeric expression
Returns:
Integer
Description:
Rounds its argument toward the closest integer or negative infinity if exactly between two integers.

8.120. (rules)

Package:
Scriptlib
Arguments:
None
Returns:
nil
Description:
Prints a list of all defrules to the 't' router.

8.121. (run [<integer>])

Package:
Intrinsics
Arguments:
Optionally, a single integer
Returns:
TRUE
Description:
Starts the inference engine. If no argument is supplied, Jess will keep running until no more activations remain or halt is called. If an argument is supplied, it gives the maximum number of rules to fire before stopping.

8.122. (run-query <query-name> <expression>+)

Package:
MiscFunctions
Arguments:
An atom, and zero or more additional expressions
Returns:
java.util.Iterator, as an EXTERNAL_ADDRESS
Description:
Runs a defquery and returns a java.util.Iterator of the matches. See the documentation for defquery for more details. Note that run-query can lead to backwards chaining, which can cause rules to fire; thus if run-query is called on a rule RHS, other rules' RHSs may run to completion before the instigating rule completes. Putting run-query on a rule RHS can also cause the count of executed rules returned by run to be low.

8.123. (run-until-halt)

Package:
Scriptlib
Arguments:
None.
Returns:
int
Description:
Runs the engine until halt is called. Returns the number of rules fired. When there are no active rules, the calling thread will be blocked waiting on the activation semaphore.

8.124. (save-facts <file-name> [<deftemplate-name>])

Package:
Intrinsics
Arguments:
A filename, and optionally an atom
Returns:
Boolean
Description:
Saves facts to a file. Attempts to open the named file for writing, and then writes a list of all facts on the fact list to the file. This file is suitable for reading with load-facts. If the optional second argument is given, only facts whose head matches this atom will be saved. Does not work in applets.

Note: See the batch command for a discussion about specifying filenames in Jess.

8.125. (set <external-address> <string-expression> <expression>)

Package:
ReflectFunctions
Arguments:
An external address, a string, and an expression
Returns:
The last argument
Description:
Sets a Java Bean's property to the given value. The first argument is the Bean object; the second argument is the name of the property. The third value is the new value for the property; the same conversions are applied as for new and call.

8.126. (set-factory [factory object] )

Package:
MiscFunctions
Arguments:
External address, an object that implements the interface jess.factory.Factory
Returns:
External address, an object that implements the interface jess.factory.Factory; the previous value of this property.
Description:
Set the "thing factory" for the active Rete object. Providing an alternate "thing factory" is a very advanced, and currently undocumented, way to extend Jess's functionality.

8.127. (set-member (<external-address> | <string-expression>) <string> <expression>+)

Package:
ReflectFunctions
Arguments:
An external address or a string, a string, and one or more expressions
Returns:
The last argument
Description:
Sets a Java object's member variable to the given value. The first argument is the object (or the name of the class, in the case of a static member variable). The second argument is the name of the variable. The third value is the new value for the variable; the same conversions are applied as for new and call.

8.128. (set-multithreaded-io (TRUE | FALSE))

Package:
Intrinsics
Arguments:
Boolean
Returns:
Boolean
Description:
Specify whether Jess should use a separate thread to flush I/O streams. Turning this on can lead to a modest performance enhancement, at the expense of possible loss of output on program termination. Returns the previous value of this property.

8.129. (set-node-index-hash <integer>)

Package:
MiscFunctions
Arguments:
One integral value
Returns:
TRUE
Description:
Sets the default hashing key used in all Rete network join node memories defined after the function is called; this function will not affect parts of the network already in existence at the time of the call. A small value will give rise to memory-efficient nodes; a larger value will use more memory. If the created nodes will generally have to remember many partial matches, large numbers will lead to faster performance; the opposite may be true for nodes which will rarely hold more than one or two partial matches. This function sets the default; explicit declare statements can override this for specific rules.

8.130. (set-reset-globals (TRUE | FALSE | nil))

Package:
MiscFunctions
Arguments:
One boolean value (TRUE or FALSE or nil)
Returns:
Boolean
Description:
Changes the current setting of the global variable reset behavior. If this property is set to TRUE (the default), then the (reset) command reinitializes the values of global variables to their initial values (if the initial value was a function call, the function call is reexecuted.) If the property is set to FALSE or nil, then (reset) will not affect global variables. Note that in previous versions of Jess, defglobals were always reset; but if the initial value was set with a function call, the function was not reevaluated. Now it is.

8.131. (set-salience-evaluation (when-defined | when-activated | every-cycle))

Package:
MiscFunctions
Arguments:
One of the atoms when-defined, when-activated, or every-cycle
Returns:
One of the potential arguments (the previous value of this property)
Description:
Changes the current setting of the salience evaluation behavior. By default, a rule's salience will be determined once, when the rule is defined (when-defined.) If this property is set to when-activated, then the salience of each rule will be redetermined immediately before each time it is placed on the agenda. If the property is set to every-cycle, then the salience of every rule is redetermined immediately after each time any rule fires.

8.132. (set-strategy (depth | breadth))

Package:
MiscFunctions
Arguments:
An atom or string representing the name of a strategy (can be a fully-qualifed Java class name). You can use depth and breadth to represent the two built-in strategies.
Returns:
The previous strategy as an atom.
Description:
Lets you specify the conflict resolution strategy Jess uses to order the firing of rules of equal salience. Currently, there are two strategies available: depth (LIFO) and breadth (FIFO). When the depth strategy is in effect (the default), more recently activated rules are fired before less recently activated rules of the same salience. When the breadth strategy is active, rules of the same salience fire in the order in which they are activated. Note that in either case, if several rules are activated simultaneously (i.e., by the same fact-assertion event) the order in which these several rules fire is unspecified, implementation-dependent and subject to change. More built-in strategies may be added in the future. You can (perhaps) implement your own strategies in Java by creating a class that implements the jess.Strategy interface and then specifying its fully-qualified classname as the argument to set-strategy. Details can be gleaned from the source. At this time, though, I think some of the methods you'd need to call are package-protected.

8.133. (setgen <numeric-expression>)

Package:
MiscFunctions
Arguments:
A numeric expression
Returns:
TRUE
Description:
Sets the starting number used by gensym*. Note that if this number has already been used, gensym* uses the next larger number that has not been used.

8.134. (show-deffacts)

Package:
Scriptlib
Arguments:
None
Returns:
nil
Description:
Displays all defined deffacts to the 't' router.

8.135. (show-deftemplates)

Package:
Scriptlib
Arguments:
None
Returns:
nil
Description:
Displays all defined deftemplatess to the 't' router.

8.136. (show-jess-listeners)

Package:
Scriptlib
Arguments:
None
Returns:
nil
Description:
Displays all JessListeners registered with the engine to the 't' router.

8.137. (socket <Internet-hostname> <TCP-port-number> <router-identifier>)

Package:
MiscFunctions
Arguments:
An Internet hostname, a TCP port number, and a router identifier
Returns:
The router identifier
Description:
Somewhat equivalent to open, except that instead of opening a file, opens an unbuffered TCP network connection to the named host at the named port, and installs it as a pair of read and write routers under the given name.

8.138. (sqrt <numeric-expression>)

Package:
MathFunctions
Arguments:
A numeric expression
Returns:
Number
Description:
Returns the square root of its only argument.

8.139. (store <string or atom> <expression>)

Package:
Intrinsics
Arguments:
A string or atom and any other value
Returns:
(varies)
Description:
Associates the expression with the name given by the first argument, such that later calls to the fetch will retrieve it. Storing the atom nil will clear any value associated with name. Analagous to the store() member function of the jess.Rete class. See section on using store and fetch for more details.

8.140. (str-cat <expression>*)

Package:
StringFunctions
Arguments:
Zero or more expressions
Returns:
String
Description:
Concatenates its arguments as strings to form a single string.

8.141. (str-compare <string-expression> <string-expression>)

Package:
StringFunctions
Arguments:
Two strings
Returns:
Integer
Description:
Lexicographically compares two strings. Returns 0 if the strings are identical, a negative integer if the first is lexicographically less than the second, a positive integer if lexicographically greater.

8.142. (str-index <lexeme-expression> <lexeme-expression>)

Package:
StringFunctions
Arguments:
Two atoms
Returns:
Integer or FALSE
Description:
Returns the position of the first argument within the second argument. This is the 1-based index at which the first string first appears in the second; otherwise, returns FALSE.

8.143. (str-length <lexeme-expression>)

Package:
StringFunctions
Arguments:
An atom
Returns:
Integer
Description:
Returns the length of an atom in characters.

8.144. (stringp <expression>)

Package:
PredFunctions
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE for strings; otherwise, returns FALSE.

8.145. (sub-string <begin-integer-expression> <end-integer-expression> <string-expression>)

Package:
StringFunctions
Arguments:
Two numbers and a string
Returns:
String
Description:
Retrieves a subportion from a string. Returns the string consisting of the characters between the two 1-based indices of the given string, inclusive.

8.146. (subseq$ <multifield-expression> <begin-integer-expression> <end-integer-expression>)

Package:
MultiFunctions
Arguments:
A multifield and two numeric expressions
Returns:
Multifield
Description:
Extracts the specified range from a multifield value consisting of the elements between the two 1-based indices of the given multifield, inclusive.

8.147. (subsetp <multifield-expression> <multifield-expression>)

Package:
MultiFunctions
Arguments:
Two multifields
Returns:
Boolean
Description:
Returns TRUE if the first argument is a subset of the second (i.e., all the elements of the first multifield appear in the second multifield); otherwise, returns FALSE.

8.148. (sym-cat <expression>*)

Package:
Intrinsics
Arguments:
Zero or more expressions
Returns:
Atom
Description:
Concatenates its arguments as strings to form a single symbol.

8.149. (symbolp <expression>)

Package:
PredFunctions
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE for symbols; otherwise, returns FALSE.

8.150. (system <lexeme-expression>+ [&])

Package:
MiscFunctions
Arguments:
One or more atoms or strings
Returns:
a java.lang.Process object, or FALSE
Description:
Sends a command to the operating system. Each atom or string becomes one element of the argument array in a call to the Java java.lang.Runtime.exec(String[] cmdaray) method; therefore to execute the command edit myfile.txt, you should call (system edit myfile.txt), not (system "edit myfile.txt").

Normally blocks (i.e., Jess stops until the applet returns), but if the last argument is an ampersand (&), the program will run in the background. The standard output and standard error streams of the process are connected to the 't' router, but the input of the process is not connected to the terminal.

Returns the Java Process object. You can call waitFor and then exitValue to get the exit status of the process.

8.151. (throw <java-object>)

Package:
Intrinsics
Arguments:
A Java object that must inherit from java.lang.Throwable
Returns:
Does not return
Description:
Throws the given exception object. If the object is a JessException, throws it directly. If the object is some other type of exception, it is wrapped in a JessException before throwing. The object's stack trace is filled in such that the exception will appear to have been created by the throw function.

8.152. (time)

Package:
MiscFunctions
Arguments:
None
Returns:
Number
Description:
Returns the number of seconds since 12:00 AM, Jan 1, 1970.

8.153. (try <expression>* [catch <expression>*] [finally <expression>*])

Package:
Intrinsics
Arguments:
One or more expressions, followed optionally by the atom catch followed by zero or more expressions, followed optionally by the atom finally followed by zero or more expressions. Either the catch, or the finally, or both must be included.
Returns:
(Varies)
Description:
This command works something like Java try with a few simplifications. The biggest difference is that the catch clause can specify neither a type of exception nor a variable to receive the exception object. All exceptions occurring in a try block are routed to the single catch block. The variable ?ERROR is made to point to the exception object as an EXTERNAL_ADDRESS. For example: 
    (try
      (open NoSuchFile.txt r)
     catch
      (printout t (call ?ERROR toString) crlf))
prints 
   Rete Exception in routine _open::call.
     Message: I/O Exception java.io.FileNotFoundException: NoSuchFile.txt.

An empty catch block is fine. It just signifies ignoring possible errors.

The code in the finally block, if present, is executed after all try and/or catch code has executed, immediately before the try function returns.

8.154. (undefadvice (<function-name> | ALL | <multifield>))

Package:
Intrinsics
Arguments:
A function name, or ALL, or a multifield of function names
Returns:
TRUE
Description:
Removes all advice from the named function(s).

8.155. (undefinstance (<java-object> | * ))

Package:
ReflectFunctions
Arguments:
A Javaobject, or the atom *
Returns:
TRUE
Description:
If the object currently has a shadow fact, it is removed from the knowledge base. Furthermore, if the object has a PropertyChangeListener installed, this is removed as well. If the argument is "*" this is done for all definstances.

8.156. (undefrule <rule-name>)

Package:
Intrinsics
Arguments:
An atom representing the name of a rule
Returns:
Boolean
Description:
Deletes a defrule. Removes the named rule from the Rete network and returns TRUE if the rule existed. This rule will never fire again.

8.157. (union$ [<multifield-expression>]+)

Package:
MultiFunctions
Arguments:
One or more multifields
Returns:
Multifield
Description:
Returns a new multifield consisting of the union of all of its multifield arguments (i.e., of all the elements that appear in any of the arguments with duplicates removed).

8.158. (unwatch <watch-item>)

Package:
Intrinsics
Arguments:
One of the atoms all, rules, compilations, activations, facts
Returns:
Description:
Causes trace output to not be printed for the given indicator. See watch.

8.159. (upcase <lexeme-expression>)

Package:
StringFunctions
Arguments:
A string or atom
Returns:
A string
Description:
Converts lowercase characters in a string or symbol to uppercase. Returns the argument as an all-uppercase string.

8.160. (view)

Package:
ViewFunctions
Arguments:
None
Returns:
TRUE
Description:
This Userfunction is included in the Jess distribution but is not normally installed. You must load it using load-package (the class name is jess.ViewFunctions). When invoked, it displays a live snapshot of the Rete network in a graphical window. See How Jess Works for details.

8.161. (watch (all | rules | compilations | activations | facts))

Package:
Intrinsics
Arguments:
One of the atoms all, rules, compilations, activations, facts activations
Returns:
TRUE
Description:
Produces additional debug output when specific events happen in Jess, depending on the argument. Any number of different watches can be active simultaneously:

8.162. (while <expression> [do] <action>*)

Package:
Intrinsics
Arguments:
A Boolean value or a function call returning Boolean, the atom do, and zero or more expressions
Returns:
(Varies)
Description:
Allows conditional looping. Evaluates the boolean expression repeatedly. As long as it does not equal FALSE, the list of other expressions are evaluated. The value of the last expression evaluated is the return value.