RuleWorks

Application Programming Interface

This chapter contains reference information about each routine in the RuleWorks run-time library.

The table below explains the constants defined in the RuleWorks API:

RuleWorks Defined Constants

Name Description Value

RUL_C_INVALID_ATOM The atomic value used to signal NULL
an error

RUL_C_INVALID_LENGTH An integer value used to signal -1
an error

RUL_C_MAX_SYMBOL_SIZE Maximum numbers of characters 256
in an atom of type SYMBOL

RUL_C_RESET_WM_ATOM An object identifier defined to NULL
be the first (lowest) in working
memory.

 

  1. rul_atom_is_compound

    2. Indicates whether a value is a RuleWorks COMPOUND value.

      1. Syntax

        2. truth_value = rul_atom_is_compound (atom_value)

        Argument Data Type Access

        truth_value boolean write

        atom_value opaque atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_atom_is_compound (rul_atom atom_value);

      3. Argument

        4. atom_value

        The value to be tested.

      4. Return Values

        5. TRUE if its argument is a RuleWorks COMPOUND value; otherwise, FALSE.

      5. See Also

    rul_atom_is_fatom

    rul_atom_is_iatom

    rul_atom_is_symbol

    rul_atom_is_instance_id

  2. rul_atom_is_fatom

    3. Indicates whether a value is a RuleWorks FLOAT atom.

      1. Syntax

        2. truth_value = rul_atom_is_fatom (atom_value)

        Argument Data Type Access

        truth_value boolean write

        atom_value opaque atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_atom_is_fatom (rul_atom atom_value);

      3. Argument

        4. atom_value

        The value to be tested.

      4. Return Values

        5. TRUE if its argument is a RuleWorks FLOAT atom; otherwise, FALSE.

      5. See Also

    rul_atom_is_compound

    rul_atom_is_iatom

    rul_atom_is_symbol

    rul_atom_is_instance_id

  3. rul_atom_is_iatom

    4. Indicates whether a value is a RuleWorks INTEGER atom.

      1. Syntax

        2. truth_value = rul_atom_is_iatom (atom_value)

        Argument Data Type Access

        truth_value boolean write

        atom_value opaque atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_atom_is_iatom (rul_atom atom_value);

      3. Arguments

        4. atom_value

        The value to be tested.

      4. Return Values

        5. TRUE if the argument is a RuleWorks INTEGER atom; otherwise, FALSE.

      5. See Also

    rul_atom_is_compound

    rul_atom_is_fatom

    rul_atom_is_symbol

    rul_atom_is_instance_id

  4. rul_atom_is_instance_id

    5. Indicates whether a value is a RuleWorks INSTANCE-ID atom.

    Note that rul_atom_is_instance_id does not indicate that the object associated with the INSTANCE-ID still exists. Use rul_is_instance to check that.

      1. Syntax

        2. truth_value = rul_atom_is_instance_id (atom_value)

        Argument Data Type Access

        truth_value boolean write

        atom_value opaque atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_atom_is_instance_id (rul_atom atom_value);

      3. Argument

        4. atom_value

        The value to be tested.

      4. Return Values

        5. TRUE if the argument is a RuleWorks INSTANCE-ID atom; otherwise, FALSE.

      5. See Also

    rul_atom_is_compound

    rul_atom_is_fatom

    rul_atom_is_iatom

    rul_atom_is_symbol

    rul_is_instance

  5. rul_atom_is_symbol

    6. Indicates whether a value is a RuleWorks SYMBOL atom.

      1. Syntax

        2. truth_value = rul_atom_is_symbol (atom_value)

        Argument Data Type Access

        truth_value boolean write

        atom_value opaque atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_atom_is_symbol (rul_atom atom_value);

      3. Argument

        4. atom_value

        The value to be tested.

      4. Return Values

        5. TRUE if the argument is a RuleWorks SYMBOL atom; otherwise, FALSE.

      5. See Also

    rul_atom_is_fatom

    rul_atom_is_iatom

    rul_atom_is_instance_id

  6. rul_atom_to_string

    7. Converts a RuleWorks atom to a string, regardless of the atom's type.

      1. Syntax

        2. num_chars = rul_atom_to_string (char_string, string_size, atom_value)

        Argument Data Type Access

        num_chars integer write

        char_string string write

        string_size integer read

        atom_value opaque atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        long rul_atom_to_string (
        char char_string
        long string_size
        rul_atom atom_value);

      3. Arguments

        4. char_string

        The read form of the specified atom, set by the function (see Chapter 2 for information on read forms).

        string_size

        The maximum number of characters to copy into char_string.

        atom_value

        The RuleWorks atom to be converted.

        Return Values

        The number of characters in the string that represents the read form of the specified atom; or RUL_C_INVALID_LENGTH if an error occurs (for example, the buffer specified by char_string is too small for the read form).

        Since the print form of a RuleWorks atom is at most RUL_C_MAX_SYMBOL_SIZE characters, allocating a buffer 3 + (2 <math_char>(times) RUL_C_MAX_SYMBOL_SIZE) characters long is guaranteed to be adequate for any read form.

      4. Examples

        5. The following example is in the C programming language.

        char result[RUL_C_MAX_SYMBOL_SIZE + 1];

        char_count = rul_atom_to_string (result, RUL_C_MAX_SYMBOL_SIZE + 1, my_atom);

      5. See Also

    rul_atom_to_string_length

    rul_string_to_atom

  7. rul_atom_to_string_length

    8. Finds the number of characters in the read form of a specified atom.

      1. Syntax

        2. num_chars = rul_atom_to_string_length (atom_value)

        Argument Data Type Access

        num_chars integer write

        atom_value opaque atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        long rul_atom_to_string_length (rul_atom atom_value);

      3. Arguments

        4. atom_value

        The RuleWorks atom to be converted.

      4. Return Values

        5. The number of characters in the string that represents the read form of the specified atom.

      5. See Also

    rul_atom_to_string

    rul_string_to_atom

  8. rul_attr_is_compound

    9. Indicates whether an attribute is compound or scalar.

      1. Syntax

        2. truth_value = rul_attr_is_compound (class_name, attr_name, block_name)

        Argument Data Type Access

        truth_value boolean write

        class_name string read

        attr_name string read

        block_name string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_attr_is_compound (
        char *class_name,
        char *attr_name,
        char *block_name);

      3. Arguments

        4. class_name

        A string that names the object class of the attribute.

        attr_name

        A string that names the attribute to be tested.

        block_name

        A string that names the block in which the object class was declared.

      4. Return Values

        5. TRUE if attr_name is the name of an attribute declared to be compound in the object class specified by class_name; otherwise, FALSE.

      5. See Also

    rul_get_comp_attr_length

    rul_get_comp_attr_string

    rul_get_comp_elem_atom

  9. rul_copy_instance

    10. Creates a new object identical to the one specified.

      1. Syntax

        2. new_object_id = rul_copy_instance (old_object_id)

        Argument Data Type Access

        new_object_id opaque INSTANCE-ID atom write

        old_object_id opaque INSTANCE-ID atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom rul_copy_instance (rul_atom old_object_id)

      3. Argument

        4. old_object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be copied.

      4. Return Values

        5. The RuleWorks INSTANCE-ID atom associated with the newly-created object; or RUL_C_INVALID_ATOM if for any reason the function was unable to create the new object.

      5. See Also

    rul_get_instance

    rul_make_instance

    rul_specialize_instance

  10. rul_debug

    11. Causes the RuleWorks> prompt to appear at the beginning of the next recognize-act cycle, if the active entry block was compiled with the Debug qualifier set to YES or MAYBE.

      1. Syntax

        2. rul_debug ( )

      2. C Binding

        3. #include <rul_rtl.h>

        void rul_debug (void);

      3. Arguments

    None.

  11. rul_double_to_fatom

    12. Converts a double-precision floating-point number into a RuleWorks FLOAT atom.

      1. Syntax

        2. atom_value = rul_double_to_fatom (double_value)

        Argument Data Type Access

        atom_value opaque float atom write

        double_value double float read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_double_to_fatom (double double_value);

      3. Argument

        4. double_value

        The double-precision floating-point number to be converted.

        (On OpenVMS VAX systems, this is a D_float value; on OpenVMS AXP systems, a G_float.)

      4. Return Values

        5. A RuleWorks atom made from the floating-point number; or RUL_C_INVALID_ATOM if the function was unable to create the new atom for any reason.

      5. See Also

    rul_atom_is_fatom

    rul_fatom_to_float

  12. rul_end_id_translation

    13. Signals the termination of an INSTANCE-ID translation table. See the description of rul_start_id_translation for details.

      1. Syntax

        2. rul_end_id_translation ( )

      2. C Binding

        3. #include <rul_rtl.h>

        void rul_end_id_translation (void);

      3. Arguments

        4. None.

      4. See Also

    rul_make_instance

    rul_start_id_translation

  13. rul_fatom_to_double

    14. Converts a RuleWorks FLOAT atom into a double-precision floating-point number.

    (On OpenVMS VAX systems, this is an F_float value; on OpenVMS AXP systems, a G_float.)

      1. Syntax

        2. double_value = rul_fatom_to_double (atom_value)

        Argument Data Type Access

        double_value double float write

        atom_value opaque float atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        double rul_fatom_to_double (rul_atom atom_value);

      3. Argument

        4. atom_value

        The RuleWorks FLOAT atom to be converted.

      4. Return Values

        5. A double-precision floating-point number made from the RuleWorks atom. If the argument is not a float atom, the function returns 0.0 and issues a warning.

      5. See Also

    rul_atom_is_fatom

    rul_fatom_to_float

  14. rul_fatom_to_float

    15. Converts a RuleWorks FLOAT atom into a single-precision floating-point number.

    (On VMS systems, this is an F_float value.)

      1. Syntax

        2. float_value = rul_fatom_to_float (atom_value)

        Argument Data Type Access

        float_value single float write

        atom_value opaque float atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        float rul_fatom_to_float (rul_atom atom_value);

      3. Argument

        4. atom_value

        The RuleWorks FLOAT atom to be converted.

      4. Return Values

        5. A single-precision floating-point number made from the RuleWorks atom. If the argument is not a float atom, the function returns 0.0 and issues a warning.

      5. See Also

    rul_float_to_fatom

  15. rul_float_to_fatom

    16. Converts a single-precision floating-point number into a RuleWorks FLOAT atom.

      1. Syntax

        2. atom_value = rul_float_to_fatom (float_value)

        Argument Data Type Access

        atom_value opaque float atom write

        float_value single float read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_float_to_fatom (float float_value);

      3. Argument

        4. float_value

        The floating-point number to be converted.

        (On VMS systems, this is an F_float value.)

      4. Return Values

        5. A RuleWorks atom made from the floating-point number; or RUL_C_INVALID_ATOM if the function was unable to create the new atom for any reason.

      5. See Also

    rul_atom_is_fatom

    rul_fatom_to_float

  16. rul_genint

    17. Returns a RuleWorks INTEGER atom that is guaranteed to be unique throughout the run.

    The RuleWorks atom generator is used by the RuleWorks GENATOM and GENINT functions, and by the rul_genint, rul_gensym and rul_gensymp API routines. Every atom generated for any of these routines is unique while the program is running.

    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:

    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.

      1. Syntax

        2. value = rul_genint ( )

        Argument Data Type Access

        value opaque symbol atom write

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom rul_genint (void);

      3. Arguments

        4. None.

      4. Return Values

        5. A RuleWorks-generated INTEGER atom.

      5. See Also

    rul_gensym

    rul_gensymp

  17. rul_gensym

    18. Generates a new symbol. See rul_genintfor an explanation of the RuleWorks atom generator.

      1. Syntax

        2. value = rul_gensym ( )

        Argument Data Type Access

        value opaque symbol atom write

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom rul_gensym (void);

      3. Arguments

        4. None.

      4. Return Values

        5. A RuleWorks SYMBOL atom guaranteed to be unique throughout the run.

      5. See Also

    rul_genint

    rul_gensymp

  18. rul_gensymp

    19. Generates a new symbol, as does the rul_gensymroutine, but with a prefix that you specify instead of G:. See rul_genintfor an explanation of the RuleWorks atom generator.

      1. Syntax

        2. value = rul_gensymp ( prefix )

        Argument Data Type Access

        value opaque symbol atom write

        prefix string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom rul_gensymp (char *prefix);

      3. Argument

        4. prefix

        A string to be placed in front of an integer by the RuleWorks atom generator. See rul_genintfor details.

      4. Return Values

        5. A RuleWorks SYMBOL atom guaranteed to be unique throughout the run.

      5. See Also

    rul_genint

    rul_gensym

  19. rul_get_attr_atom

    20. Accesses the value of a scalar attribute in an object.

      1. Syntax

        2. value = rul_get_attr_atom (object_id, attr_name)

        Argument Data Type Access

        value opaque atom write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom rul_get_attr_atom (
        rul_atom object_id,
        char *attr_name);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be accessed.

        attr_name

        A string that names the attribute whose value is returned.

      4. Return Values

        5. The RuleWorks atom value in the specified attribute of the specified object; or RUL_C_INVALID_ATOM if the function is unable to retrieve the value for any reason.

      5. See Also

    rul_get_instance

  20. rul_get_class_string

    21. Accesses the class name of an object.

      1. Syntax

        2. num_chars = rul_get_class_string (char_string, string_size, object_id)

        Argument Data Type Access

        num_chars integer write

        char_string string write

        string_size integer read

        object_id opaque INSTANCE-ID atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        long rul_get_class_string (
        char *char_string
        long string_size
        rul_atom object_id);

      3. Arguments

        4. char_string

        The class name of the specified object, set by the function.

        string_size

        The number of characters in the class name.

        object_id

        The RuleWorks INSTANCE-ID atom associated with the object whose class name is returned.

      4. Return Values

        5. The number of characters in the string that contains the name of the class of the specified object; or RUL_C_INVALID_LENGTH if an error occurs (for example, the buffer specified by char_string is too small for the print form).

        Since the class name can be no more than RUL_C_MAX_SYMBOL_SIZE characters, allocating a buffer RUL_C_MAX_SYMBOL_SIZE + 1 characters long is guaranteed to be adequate.

      5. See Also

    rul_get_class_string_length

    rul_get_instance

    rul_is_instance

  21. rul_get_class_string_length

    22. Returns the number of characters in the class name of an object.

      1. Syntax

        2. num_chars = rul_get_class_string_length (object_id)

        Argument Data Type Access

        num_chars integer write

        object_id opaque INSTANCE-ID atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        long rul_get_class_string_length (rul_atom object_id);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object whose class name is measured.

      4. Return Values

        5. The number of characters in the name of the class of the specified object.

      5. See Also

    rul_get_class_string

  22. rul_get_comp_attr_length

    23. Accesses the length of a compound attribute.

      1. Syntax

        2. length = rul_get_comp_attr_length (object_id, attr_name)

        Argument Data Type Access

        length integer write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        long rul_get_comp_attr_length (
        rul_atom object_id,
        char attr_name);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be accessed.

        attr_name

        A string that names a compound attribute in the object to be accessed.

      4. Return Values

        5. An integer that specifies the number of elements in the compound attribute's value; or RUL_C_INVALID_LENGTH if the function is unable to retrieve the specified attribute length for any reason.

      5. See Also

    rul_attr_is_compound

    rul_get_comp_elem_atom

    rul_get_comp_attr_string

    rul_get_comp_attr_string_len

  23. rul_get_comp_attr_string

    24. Accesses the read form of all the values in a compound attribute.

      1. Syntax

        2. num_chars = rul_get_comp_attr (values_string, string_size, object_id, attr_name)

        Argument Data Type Access

        num_chars integer write

        values_string string write

        string_size integer read

        object_id opaque INSTANCE-ID atom read

        attr_name string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        long rul_get_comp_attr_string (
        char *values_string
        long string_size
        rul_atom object_id
        char *attr_name);

      3. Arguments

        4. values_string

        A string that contains the read form of each element in the specified compound attribute, set by the function. Values are separated by spaces. This string does not include the name COMPOUND and is not enclosed in parentheses. (See Chapter 2 for more information on read forms.)

        string_size

        The number of characters in the read form.

        object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be accessed.

        attr_name

        A string that names a compound attribute in the object to be accessed.

      4. Return Values

        5. The number of characters actually found in the string that contains the read forms of all the values in the compound attribute; or RUL_C_INVALID_LENGTH if an error occurs (for example, the buffer specified by values_string is too small for the read forms).

      5. See Also

    rul_get_comp_attr_length

    rul_get_comp_elem_atom

    rul_get_comp_attr_string_len

    rul_set_comp_attr_string

  24. rul_get_comp_attr_string_len

    25. Returns the number of characters in the read form of all the values in a compound attribute.

      1. Syntax

        2. num_chars = rul_get_comp_attr_string_len (object_id, attr_name)

        Argument Data Type Access

        num_chars integer write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        long rul_get_comp_attr_string_len (
        rul_atom object_id
        char *attr_name);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be accessed.

        attr_name

        A string that names a compound attribute in the object to be accessed.

      4. Return Values

        5. The number of characters in the string that contains the read forms of all the values in the compound attribute.

      5. See Also

    rul_get_comp_attr_length

    rul_get_comp_attr_string

  25. rul_get_comp_elem_atom

    26. Accesses the value of a single element of a compound attribute in an object.

      1. Syntax

        2. value = rul_get_comp_elem_atom (object_id, attr_name, element_index)

        Argument Data Type Access

        value opaque atom write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        element_index integer read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom rul_get_comp_elem_atom (
        rul_atom object_id,
        char *attr_name,
        long element_index);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be accessed.

        attr_name

        A string that names a compound attribute in the object to be accessed.

        element_index

        An integer that specifies the position of the element to be accessed.

        Return Values

        The RuleWorks atom value of the specified compound attribute element; or RUL_C_INVALID_ATOM if the function is unable to retrieve the value for any reason.

        See Also

        rul_attr_is_compound

        rul_get_comp_attr_length

        rul_get_comp_attr_string

        rul_get_firing_rule

        Identifies the rule that the RuleWorks run-time system is currently executing.

      4. Syntax

        5. value = rul_get_firing_rule ( )

        Argument Data Type Access

        value opaque symbol atom write

         

      5. C Binding

        6. #include <rul_rtl.h>

        rul_atom rul_get_firing_rule ( void );

      6. Arguments

        7. None.

        Return Values

        The SYMBOL atom that identifies the name of the rule that is currently executing, or the symbol NIL if no rule is executing.

        rul_get_instance

        Accesses the read form of a working-memory object.

      7. Syntax

        8. num_chars = rul_get_instance (print_string, string_size, object_id)

        Argument Data Type Access

        num_chars integer write

        print_string string write

        string_size integer read

        object_id opaque INSTANCE-ID atom read

         

      8. C Binding

        9. #include <rul_rtl.h>

        long rul_get_instance (
        char *print_string
        long string_size
        rul_atom object_id);

      9. Arguments

        10. print_string

        The read form of the specified object, set by the function. The string returned is in a form similar to that printed by the PPWM debugger command. It is enclosed in parentheses and includes the ^$ID value, so that it can be used with rul_start_id_translation and rul_end_id_translation

        string_size

        The number of characters allocated for the read form.

        object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be accessed.

      10. Return Values

        11. The number of characters actually found in the string that contains the read form of the specified object; or RUL_C_INVALID_LENGTH if an error occurs (for example, the buffer specified by string_size is too small for the read form).

      11. Example

        12. See rul_make_instance and rul_get_instance_length.

      12. See Also

    rul_end_id_translation

    rul_get_attr_atom

    rul_get_comp_attr_length

    rul_get_comp_attr_string

    rul_get_instance_length

    rul_make_instance

    rul_start_id_translation

  26. rul_get_instance_length

    27. Returns the number of characters in the read form of a working-memory object.

      1. Syntax

        2. num_chars = rul_get_instance_length (object_id)

        Argument Data Type Access

        num_chars integer write

        object_id opaque INSTANCE-ID atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        long rul_get_instance_length (rul_atom object_id);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be accessed.

      4. Return Values

        5. The number of characters in the read form of the specified object.

      5. Example

        6. The C routine below uses rul_get_instance_length to find the correct string_size argument for rul_get_instance:

        #include <rul_rtl.h>

        #include <stdlib.h>__/* For malloc() */

        #include <stdio.h>__/* For printf() */

        /*

        * Print the readform of the WME whose instance ID is passed.

        */

        void

        print_wme(rul_atom wme_id)

        {

        char *buffer;

        unsigned int buffer_size;

        buffer_size = rul_get_instance_length(wme_id) + 1;

        ____/* Add 1 for null terminator */

        buffer = (char *) malloc(buffer_size);

        if (buffer == NULL) {

        _fprintf(stderr, "Unable to allocate memory");

        _exit(EXIT_FAILURE);

        }

        rul_get_instance(buffer, buffer_size, wme_id);

        printf("%s\n", buffer);

        free(buffer);

      6. See Also

    rul_get_instance

  27. rul_get_next_instance

    28. Allows iteration over the entire set of objects in working memory.

    To do this, start by passing the defined constant, RUL_C_RESET_WM_ATOM, to rul_get_next_instance. The function then returns the INSTANCE-ID of the first object in working memory. Pass this return value on the second call to rul_get_next_instance to get the INSTANCE-ID of the second object. Continue this cycle until the function returns RUL_C_INVALID_ATOM, which means the identifiers of all existing objects have been returned.

    Note: that this function returns INSTANCE-IDs in no particular order. If any objects are made, modified, or removed during iteration over the set of objects, undesired results will occur. For example, the function may return the same INSTANCE-ID more than once, or may never return a particular INSTANCE-ID.

      1. Syntax

        2. object_id = rul_get_next_instance (previous_instance_id)

        Argument Data Type Access

        object_id opaque INSTANCE-ID atom write

        previous_instance_id opaque INSTANCE-ID atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom rul_get_next_instance (rul_atom previous_instance_id);

      3. Arguments

        4. previous_instance_id

        The RuleWorks INSTANCE-ID atom associated with the object previously accessed.

      4. Return Values

        5. The RuleWorks INSTANCE-ID atom that identifies the next object in the set.

      5. See Also

    rul_get_instance

  28. rul_iatom_to_integer

    29. Converts a RuleWorks INTEGER atom into an integer.

      1. Syntax

        2. integer_value = rul_iatom_to_integer (atom_value)

        Argument Data Type Access

        integer_value integer write

        atom_value opaque integer atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        long rul_iatom_to_integer (rul_atom atom_value);

      3. Argument

        4. atom_value

        The RuleWorks INTEGER atom to be converted.

      4. Return Values

        5. An integer made from the RuleWorks atom. If the input argument is not an INTEGER atom, the function returns 0 and issues a warning.

      5. See Also

        6. rul_fatom_to_float

        rul_integer_to_iatom

        rul_integer_to_iatom

        Converts an integer number into a RuleWorks INTEGER atom.

      6. Syntax

        7. atom_value = rul_integer_to_iatom (integer_value)

        Argument Data Type Access

        atom_value opaque integer atom write

        integer_value integer read

         

      7. C Binding

        8. #include <rul_rtl.h>

        rul_atom rul_integer_to_atom (long integer_value);

      8. Argument

        9. integer_value

        The integer to be converted.

      9. Return Values

        10. The RuleWorks INTEGER atom made from the integer; or RUL_C_INVALID_ATOM if the function was unable to create the atom for any reason.

      10. See Also

    rul_float_to_fatom

    rul_iatom_to_integer

  29. rul_is_attribute

    30. Indicates whether an attribute is declared in the specified object class.

      1. Syntax

        2. truth_value = rul_is_attribute (class_name, attr_name, block_name)

        Argument Data Type Access

        truth_value boolean write

        class_name string read

        attr_name string read

        block_name string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_is_attribute (
        char *class_name,
        char *attr_name,
        char *block_name);

      3. Arguments

        4. class_name

        A string that names the desired object class.

        attr_name

        A string that names the desired attribute.

        block_name

        A string that names the block in which the object class was declared.

      4. Return Values

        5. TRUE if the attribute is declared in the specified class; FALSE if it is not declared.

      5. See Also

    rul_get_attr_atom

  30. rul_is_class

    31. Indicates whether an object class with the specified name has been declared in an OBJECT-CLASS declaration.

      1. Syntax

        2. truth_value = rul_is_class (class_name, block_name)

        Argument Data Type Access

        truth_value boolean write

        class_name string read

        block_name string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_is_class (
        char *class_name,
        char *block_name);

      3. Arguments

        4. class_name

        A string that names the desired object class.

        block_name

        A string that names the block in which the object class was declared.

      4. Return Values

        5. TRUE if the specified object class name has been declared; FALSE if it has not been declared.

      5. See Also

    rul_get_class_string

  31. rul_is_instance

    32. Indicates whether the object that corresponds to the specified INSTANCE-ID exists.

      1. Syntax

        2. truth_value = rul_is_instance (object_id)

        Argument Data Type Access

        truth_value boolean write

        object_id opaque INSTANCE-ID atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_is_instance (rul_atom object_id);

      3. Argument

        4. object_id

        The RuleWorks INSTANCE-ID associated with the object to be tested.

      4. Return Values

        5. TRUE if the argument is a RuleWorks INSTANCE-ID atom and the object associated with that INSTANCE-ID exists in working memory; otherwise, FALSE.

      5. See Also

    rul_atom_is_instance_id

    rul_get_instance

    rul_make_instance

  32. rul_is_subclass

    33. Indicates whether one object class is a subclass of another.

      1. Syntax

        2. truth_value = rul_is_subclass (child_name, parent_name, block_name)

        Argument Data Type Access

        truth_value boolean write

        child_name string read

        parent_name string read

        block_name string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_is_subclass (
        char *child_name,
        char *parent_name,
        char *block_name);

      3. Arguments

        4. child_name

        A string that names the object class to be tested for subclass status.

        parent_name

        A string that names the object class to be tested for ancestor status.

        block_name

        A string that names the block in which the object classes are declared.

      4. Return Values

        5. TRUE if both arguments are the names of declared object classes and the first argument is the name of a subclass of the second argument; otherwise, FALSE.

      5. See Also

    rul_is_class

  33. rul_make_instance

    34. Creates a new object from a string.

      1. Syntax

        2. object_id = rul_make_instance (char_string, block_name)

        Argument Data Type Access

        object_id opaque INSTANCE-ID atom write

        char_string string read

        block_name string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom rul_make_instance (
        char *string,
        char *block_name);

      3. Arguments

        4. char_string

        The string to be made into an object. This string must be in the same format as would be passed to a MAKE action in the RuleWorks language. The class name of the object to be created is required; attribute names and values are optional. The object class must be declared in the block named by

        block_name.

        The string may be enclosed in parentheses but they are not required. If the string includes the ^$ID value, it is ignored unless ID translation is on (see rul_start_id_translation.

        block_name

        A string that names the block in which the object class was declared.

        Return Values

        The RuleWorks INSTANCE-ID atom associated with the newly-created object; or RUL_C_INVALID_ATOM if the function is unable to create an object from the specified string for any reason.

        Example

        The following example, in the C programming language, makes an object of class animal with attributes color and species set.

        object_id = rul_make_instance ("(ANIMAL ^COLOR BLACK ^SPECIES PANTHER)",

        "my-block")

      4. See Also

    rul_copy_instance

    rul_end_id_translation

    rul_get_instance

    rul_remove_instance

    rul_specialize_instance

    rul_start_id_translation

  34. rul_remove_instance

    35. Removes an object from working memory.

      1. Syntax

        2. status = rul_remove_instance (object_id)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_remove_instance (rul_atom object_id);

      3. Argument

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be removed.

      4. Return Values

        5. TRUE if the object is successfully removed; FALSE if the function is unable to remove the object for any reason.

      5. See Also

    rul_copy_instance

    rul_make_instance

  35. rul_set_attr_atom

    36. Changes the value of a scalar attribute.

      1. Syntax

        2. status = rul_set_attr_atom (object_id, attr_name, value)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        value opaque atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_set_attr_atom (
        rul_atom object_id,
        char *attr_name,
        rul_atom value);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the attribute to be modified.

        value

        The RuleWorks atom that specifies the new value of the attribute. This atom may be any RuleWorks data type, even INSTANCE-ID.

      4. Return Values

        5. TRUE if the attribute is successfully modified; FALSE if the function is unable to change the specified attribute value for any reason.

      5. See Also

    rul_set_attr_double

    rul_set_attr_float

    rul_set_attr_integer

    rul_set_attr_string

  36. rul_set_attr_double

    37. Changes the value of a scalar attribute to a double-precision floating-point number.

      1. Syntax

        2. status = rul_set_attr_double (object_id, attr_name, value)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        value double float read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_set_attr_double (
        rul_atom object_id,
        char *attr_name,
        double value);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the attribute to be modified.

        value

        The double-precision floating-point number that specifies the new value of the attribute. This argument is converted into a RuleWorks FLOAT atom before it is placed into the specified attribute.

      4. Return Values

        5. TRUE if the attribute is successfully modified; FALSE if the function is unable to change the specified attribute value for any reason.

        See Also

        rul_set_attr_atom

        rul_set_attr_float

        rul_set_attr_integer

        rul_set_attr_string

        rul_set_attr_float

        Changes the value of a scalar attribute to a single-precision floating-point number.

      5. Syntax

        6. status = rul_set_attr_float (object_id, attr_name, value)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        value float read

         

      6. C Binding

        7. #include <rul_rtl.h>

        rul_boolean rul_set_attr_float (
        rul_atom object_id,
        char *attr_name,
        float value);

      7. Arguments

        8. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the attribute to be modified.

        value

        The single-precision floating-point number that specifies the new value of the attribute. This argument is converted into a RuleWorks FLOAT atom before it is placed into the specified attribute.

        Return Values

        TRUE if the attribute is successfully modified; FALSE if the function is unable to change the specified attribute value for any reason.

        See Also

        rul_set_attr_atom

        rul_set_attr_double

        rul_set_attr_integer

        rul_set_attr_string

        rul_set_attr_integer

        Changes the value of a scalar attribute to an integer.

      8. Syntax

        9. status = rul_set_attr_integer (object_id, attr_name, value)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        value integer read

         

      9. C Binding

        10. #include <rul_rtl.h>

        rul_boolean rul_set_attr_integer (
        rul_atom object_id,
        char *attr_name,
        long value);

      10. Arguments

        11. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the attribute to be modified.

        value

        The integer that specifies the new value of the attribute. This argument is converted into a RuleWorks INTEGER atom before it is placed into the specified attribute.

      11. Return Values

        12. TRUE if the object is successfully modified; FALSE if the function is unable to change the attribute value for any reason.

      12. See Also

    rul_set_attr_atom

    rul_set_attr_double

    rul_set_attr_float

    rul_set_attr_string

  37. rul_set_attr_string

    38. Changes the value of an attribute to a symbol.

      1. Syntax

        2. status = rul_set_attr_string (object_id, attr_name, value)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        value string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_set_attr_string (
        rul_atom object_id,
        char *attr_name,
        char *value);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the attribute to be modified.

        value

        A string that specifies the new value of the attribute. This argument is converted to a SYMBOL atom before it is placed into the specified attribute (see Chapter 2 for more information on symbolic atoms).

        Return Values

        TRUE if the object is successfully modified; FALSE if the function is unable to change the attribute value for any reason.

      4. See Also

    rul_set_attr_atom

    rul_set_attr_double

    rul_set_attr_float

    rul_set_attr_integer

  38. rul_set_comp_attr_string

    39. Changes the value of an entire compound attribute to the values extracted from a single string.

      1. Syntax

        2. status = rul_set_comp_attr_string (object_id, attr_name, values)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        values string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_set_comp_attr_string (
        rul_atom object_id,
        char *attr_name,
        char *values);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the compound attribute to be modified.

        values

        A single string that contains the new value for each element in the compound attribute. The items in this string must be read forms that follow the RuleWorks rules for quoted atoms (see Chapter 2) and are separated by white space.

        Return Values

        TRUE if the object is successfully modified; FALSE if the function is unable to change the compound attribute for any reason.

      4. Example

        5. The following example, in the C programming language, changes the value of the compound attribute colors with a single string containing four values.

        status = rul_set_comp_attr ( object_id_1, "COLORS", "BLACK GREEN WHITE RED" );

      5. See Also

    rul_get_comp_attr_string

    rul_set_comp_elem_atom

    rul_set_comp_elem_float

    rul_set_comp_elem_integer

    rul_set_comp_elem_string

  39. rul_set_comp_elem_atom

    40. Changes the value of a single element of a compound attribute to an atom value.

      1. Syntax

        2. status = rul_set_comp_elem_atom (object_id, attr_name, element_index, value)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        element_index integer read

        value opaque atom read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_boolean rul_set_comp_elem_atom (
        rul_atom object_id,
        char *attr_name,
        long element_index,
        rul_atom value);

      3. Arguments

        4. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the compound attribute to be modified.

        element_index

        An integer that specifies the position within the compound attribute of the element to be modified.

        value

        The RuleWorks atom that specifies the new value of the compound attribute element. This atom may be any RuleWorks data type, even INSTANCE-ID.

        Return Values

        TRUE if the compound element attribute is successfully modified; FALSE if the function is unable to change the element value for any reason.

        See Also

        rul_get_comp_elem_atom

        rul_set_comp_elem_float

        rul_set_comp_elem_double

        rul_set_comp_elem_integer

        rul_set_comp_elem_string

        rul_set_comp_elem_double

        Changes the value of a single element of a compound attribute to a double-precision floating-point number.

      4. Syntax

        5. status = rul_set_comp_elem_double (object_id, attr_name, element_index, value)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        element_index integer read

        value float read

         

      5. C Binding

        6. #include <rul_rtl.h>

        rul_boolean rul_set_comp_elem_double (
        rul_atom object_id,
        char *attr_name,
        long element_index,
        double value);

      6. Arguments

        7. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the compound attribute to be modified.

        element_index

        An integer that specifies the position within the compound attribute of the element to be modified.

        value

        A double-precision floating-point number that specifies the new value of the compound attribute element. This number is converted to a RuleWorks FLOAT atom before the value is set.

        Return Values

        TRUE if the compound attribute element is successfully modified; FALSE if the function is unable to change the element value for any reason.

        See Also

        rul_get_comp_elem_atom

        rul_set_comp_elem_atom

        rul_set_comp_elem_float

        rul_set_comp_elem_integer

        rul_set_comp_elem_string

        rul_set_comp_elem_float

        Changes the value of a single element of a compound attribute to a single-precision floating-point number.

      7. Syntax

        8. status = rul_set_comp_elem_float (object_id, attr_name, element_index, value)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        element_index integer read

        value float read

         

      8. C Binding

        9. #include <rul_rtl.h>

        rul_boolean rul_set_comp_elem_float (
        rul_atom object_id,
        char *attr_name,
        long element_index,
        float value);

      9. Arguments

        10. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the compound attribute to be modified.

        element_index

        An integer that specifies the position within the compound attribute of the element to be modified.

        value

        A single-precision floating-point number that specifies the new value of the compound attribute element. This number is converted to a RuleWorks FLOAT atom before the value is set.

        Return Values

        TRUE if the compound attribute element is successfully modified; FALSE if the function is unable to change the element value for any reason.

      10. See Also

        11. rul_get_comp_elem_atom

        rul_set_comp_elem_atom

        rul_set_comp_elem_double

        rul_set_comp_elem_integer

        rul_set_comp_elem_string

        rul_set_comp_elem_integer

        Changes the value of a single element of a compound attribute to an integer.

      11. Syntax

        12. status = rul_set_comp_elem_integer (object_id, attr_name, element_index, value)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        element_index integer read

        value integer read

         

      12. C Binding

        13. #include <rul_rtl.h>

        rul_boolean rul_set_comp_elem_integer (
        rul_atom object_id,
        char *attr_name,
        long element_index,
        long value);

      13. Arguments

        14. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the compound attribute to be modified.

        element_index

        An integer that specifies the position within the compound attribute of the element to be modified.

        value

        An integer that specifies the new value of the compound attribute element. The integer is converted to a RuleWorks INTEGER atom before the value is set.

        Return Values

        TRUE if the compound attribute element was successfully modified; FALSE if the function is unable to change the element value for any reason.

        See Also

        rul_get_comp_elem_atom

        rul_set_comp_elem_atom

        rul_set_comp_elem_float

        rul_set_comp_elem_string

        rul_set_comp_elem_string

        Changes the value of a single element of a compound attribute to a string.

      14. Syntax

        15. status = rul_set_comp_elem_string (object_id, attr_name, element_index, value)

        Argument Data Type Access

        status boolean write

        object_id opaque INSTANCE-ID atom read

        attr_name string read

        element_index integer read

        value string read

         

      15. C Binding

        16. #include <rul_rtl.h>

        rul_boolean rul_set_comp_elem_string (
        rul_atom object_id,
        char *attr_name,
        long element_index,
        char *value);

      16. Arguments

        17. object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be modified.

        attr_name

        A string that names the compound attribute to be modified.

        element_index

        An integer that specifies the position within the compound attribute of the element to be modified.

        value

        A character string that specifies the new value of the compound attribute element. The string is converted to a RuleWorks SYMBOL atom before the value is set.

        Return Values

        TRUE if the compound attribute element is successfully modified; FALSE if the function is unable to change the element value for any reason.

        See Also

        rul_get_comp_elem_atom

        rul_set_comp_elem_atom

        rul_set_comp_elem_float

        rul_set_comp_elem_integer

        rul_specialize_instance

        Changes an instance of a parent class to an instance of a subclass.

      17. Syntax

        18. same_object_id = rul_specialize_instance (old_object_id, subclass)

        Argument Data Type Access

        same_object_id opaque INSTANCE-ID atom write

        old_object_id opaque INSTANCE-ID atom read

        subclass string read

         

      18. C Binding

        19. #include <rul_rtl.h>

        rul_atom rul_specialize_instance (
        rul_atom old_object_id,
        char *subclass);

      19. Arguments

        20. old_object_id

        The RuleWorks INSTANCE-ID atom associated with the object to be specialized.

        subclass

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

        Return Values

        The RuleWorks INSTANCE-ID atom associated with the newly-modified object; or RUL_C_INVALID_ATOM if for any reason the function was unable to change the class. Note that the return value should be the same as the old_object_id.

        See Also

        rul_copy_instance

        rul_get_instance

        rul_make_instance

        rul_start_id_translation

        Signals the creation of an INSTANCE-ID translation table.

        A translation table allows a set of objects saved by an application as a set of text strings to be recreated via rul_make_instance. Interobject references in the strings are correctly integrated with the current RuleWorks program. A translation table is built incrementally from the strings passed to the rul_make_instance function. The table stores the mapping between INSTANCE-IDs contained in the strings and INSTANCE-IDs actually allocated by the current program for the new objects created by the rul_make_instance function.

        When rul_end_id_translation is called, all INSTANCE-ID attribute values in the newly-made objects are updated, and the table is deleted. INSTANCE-ID values within the strings passed to rul_make_instance that correspond to objects created while ID translation was in effect are set to the actual INSTANCE-IDs of the new objects. INSTANCE-ID values within the strings whose corresponding objects were not created within the scope of the translation are set to INSTANCE-ID values for which no objects exist.

      20. Syntax

        21. rul_start_id_translation ( )

        C Binding

        #include <rul_rtl.h>

        void rul_start_id_translation (void);

      21. Arguments

        22. None.

      22. Example

    This example, in the C programming language, illustrates the effect of INSTANCE-ID translation on objects created by rul_make_instance.

    rul_start_id_translation();

    rul_make_instance ("SEAL ^$ID #293 ^NAME CHUBBY", NULL);

    rul_make_instance ("SEAL ^$ID #232 ^NAME NOISY ^FATHER #293 ^MOTHER #288", 0);

    rul_make_instance ("SEAL ^$ID #239 ^NAME SKINNY ^FATHER #298 ^MOTHER #288", 0);

    rul_make_instance ("KILLER-WHALE ^$ID #103 ^NAME SHAMMY", 0);

    rul_make_instance ("KILLER-WHALE ^$ID #137 ^NAME TAMMY ^FATHER #103", 0);

    rul_make_instance ("KILLER-WHALE ^$ID #143 ^NAME WHAMMY ^MOTHER #137", 0);

    rul_end_id_translation(); The translation table for this example would contain the following INSTANCE-ID values:

    INSTANCE-ID WMO Created? (^name) New INSTANCE-ID
    from String

    #293 Yes (Chubby) #2112

    #232 Yes (Noisy) #2113

    #288 No #2114

    #239 Yes (Skinny) #2115

    #298 No #2116

    #103 Yes (Shammy) #2117

    #137 Yes (Tammy) #2118

    #143 Yes (Whammy) #2119

    (The middle column is shown for clarity.) Note that a new INSTANCE-ID is generated to correspond to #288 even though no object with that INSTANCE-ID is made.

    RuleWorks>ppwm killer-whale ^name whammy

    #2119 7116 [NIL] (KILLER-WHALE ^NAME WHAMMY ^MOTHER #2118)

    This PPWM command shows that the ^MOTHER attribute in the object created for Whammy correctly points to the object created for Tammy.

    RuleWorks>ppwm seal

    #2112 7111 [NIL] (SEAL ^NAME CHUBBY)

    #2113 7112 [NIL] (SEAL ^NAME NOISY ^FATHER #2112 ^MOTHER #2114)

    #2115 7113 [NIL] (SEAL ^NAME SKINNY ^FATHER #2116 ^MOTHER #2114)

    This PPWM command shows that the ^MOTHER attribute in the objects created for Noisy and Skinny both point to the same nonexistent object. Conversely, the ^FATHER and ^MOTHER attributes of Skinny point to different nonexistent objects.

    See Also

    rul_end_id_translation

    rul_make_instance

  40. rul_string_to_atom

    41. Converts the first token of a string into a RuleWorks atom.

      1. Syntax

        2. atom_value = rul_string_to_atom (char_string)

        Argument Data Type Access

        atom_value opaque atom write

        char_string string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom rul_string_to_atom (char *char_string);

      3. Argument

        4. char_string

        The read form of the atom to be made (see Chapter 2 for details on read forms).

      4. Return Values

    The RuleWorks atom that corresponds to the first token in the character string. Tokens are groups of characters separated by white space: parentheses and other nonalphanumerics count as characters, not separators. If possible, the returned atom is an INTEGER, FLOAT, or INSTANCE-ID; if not, a SYMBOL. See Chapter 2 for an explanation of atom types.

    See Also

    rul_atom_to_string

    rul_string_to_compound

    rul_string_to_symbol

  41. rul_string_to_compound

    42. Converts a string into a RuleWorks COMPOUND value.

      1. Syntax

        2. atom_value = rul_string_to_compound (char_string)

        Argument Data Type Access

        atom_value opaque atom write

        char_string string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom atom_value rul_string_to_compound (char *char_string);

      3. Argument

        4. char_string

        The read form of the COMPOUND value to be made (see Chapter 2 for details on read forms).

        Return Values

        The RuleWorks COMPOUND value that corresponds to the character string.

      4. See Also

    rul_string_to_atom

    rul_string_to_symbol

  42. rul_string_to_symbol

    43. Converts a character string into a RuleWorks SYMBOL atom.

      1. Syntax

        2. atom_value = rul_string_to_symbol (char_string)

        Argument Data Type Access

        atom_value opaque symbol atom write

        char_string string read

         

      2. C Binding

        3. #include <rul_rtl.h>

        rul_atom rul_string_to_symbol (char *string);

      3. Argument

        4. char_string

        The character string to be converted to a RuleWorks atom.

        Return Values

        The RuleWorks SYMBOL atom made from the string; or RUL_C_INVALID_ATOM if the function was unable to create the atom for any reason.

        See Also

        rul_string_to_atom

        rul_string_to_compound

        rul_symbol_to_string

        rul_symbol_to_string

        Converts a RuleWorks SYMBOL atom into a character string.

      4. Syntax

        5. num_chars = rul_symbol_to_string (char_string, string_size, atom_value)

        Argument Data Type Access

        num_chars integer write

        char_string string write

        string_size integer read

        atom_value opaque symbol atom read

         

      5. C Binding

        6. #include <rul_rtl.h>

        long rul_symbol_to_string (
        char *char_string
        long string_size
        rul_atom atom_value);

      6. Arguments

char_string

The print form of the specified symbol, set by the function.

string_size

The maximum number of characters to return in char_string.

atom_value

The RuleWorks atom to be converted.

Return Values

The number of characters in the string made from the RuleWorks atom; or RUL_C_INVALID_LENGTH if an error occurs (for example, the buffer specified by char_string is too small for the print form).

Note: that since RuleWorks atoms are at most RUL_C_MAX_SYMBOL_SIZE characters long, a buffer that is RUL_C_MAX_SYMBOL_SIZE + 1 characters long is always adequate.

See Also

rul_string_to_symbol