Home | Previous Page | Next Page   Programming DataBlade Module Routines in C > Editing Opaque Type Support Routines in opaque.c >

Comparison Functions

The Informix database server calls DataBlade module comparison functions to compare two opaque type values. For example, database users can compare opaque values in SQL statements. If you want to support B-tree or R-tree indexes on an opaque type, you must provide an additional set of comparison functions.

Compare Function

The Compare() function compares two opaque types and returns an integer indicating the result of the comparison. The C name for each opaque data type is OpaqueCompare().

BladeSmith generates the complete C code for this function.

The Generated Code

The generated code compares the members of an opaque type C structure to the members in the other opaque type, in the order defined in the structure. This algorithm might not be the appropriate way to compare your data; if it is not, you must customize the code as described in the next section.

The Compare() function returns:

For example, the Circle DataBlade module defines a Pnt data type as follows:

typedef struct
{
   mi_double_precision            x;
   mi_double_precision            y;
}
Pnt;

The Compare() function generated for the Pnt type first compares the two values of x. If the two values of x are not equal, Compare() stops and returns the result of the comparison. If the two values of x are equal, Compare() proceeds to compare the two values of y.

For data types such as mi_boolean, which cannot be compared for relative magnitude, the Compare() function returns +1 if the values differ. If all structure members are equal, it returns 0.

Customizing the Code

The algorithm used to generate the Compare() function cannot evaluate the semantic content of an opaque type. Therefore, for many opaque types, replace the generated code with more appropriate code.

For example, the Circ.h file of the Circle DataBlade module defines the Circ data type as follows:

typedef struct
{
       Pnt                 center;
       mi_double_precision radius;
}
Circ;

The Pnt member has two mi_double_precision members: x and y. The generated code for Compare() compares the three mi_double_precision values individually: first x, then y, and then radius. However, if the size of your circles is more important than their origins, you could remove the code that compares the x and y members to base the comparison on the length of the radius only.

If you want to use B-tree indexing, the Compare() function is the B-tree support function. Therefore, you should analyze how you want to index your opaque data types when modifying Compare().

Smart Large Object Considerations

The generated Compare() function does not compare the values of the smart large objects; it compares the smart large object handles. If the smart large object handles are the same, then both handles refer to the same object. You can customize the code to compare the actual values of the smart large objects.

Examples

The following example DataBlade modules implement the Compare() function to compare opaque data types member by member:

The Shapes DataBlade module uses Compare() to perform a bitwise comparison on its Circle and Box data types.

B-Tree Comparison Functions

The Informix database server calls the following comparison operators when constructing B-tree indexes for opaque data types:

The C names of each of these functions are prefixed by the name of the opaque data type for which they are defined.

Important:
The Equal() function is required if you use Visual Basic to develop a DataBlade module.

BladeSmith generates the complete C code for these functions.

The Generated Code

For these functions, BladeSmith generates code that calls the Compare() function described in Compare Function. For example, the Matrix2dEqual() function generated for the Matrix2d type calls the Matrix2dCompare() function, as follows:

/* Call Compare to perform the comparison. */

return (mi_boolean)(0 != Matrix2dCompare(Gen_param1, Gen_param2, 
Gen_fparam));
Customizing the Code

You should not modify these functions. You can, however, modify the Compare() function that these functions call.

Smart Large Object Considerations

Because these functions call the Compare() function, they only evaluate the smart large object handles. You must customize the Compare() function to evaluate the actual contents of smart large objects.

Examples

The following example DataBlade modules contain some of the B-tree comparison functions:

R-Tree Comparison Functions

Version 4.0 of BladeSmith does not generate code for R-tree comparison functions.

Refer to the IBM Informix: R-Tree Index User's Guide or the IBM Informix Online Documentation site at http://www.ibm.com/software/data/informix/pubs/library/ for information about creating DataBlade modules that use the R-tree secondary access method.

Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]