Support functions are user-defined functions that the Informix database server uses to construct and maintain an R-tree index. They are never explicitly executed by end users.
The R-tree access method uses support functions to determine the leaf page on which an index key belongs and to create the special bounding-box-only keys used internally by the R-tree index. For more information on bounding boxes, refer to Bounding Boxes.
The R-tree access method requires that you create the following three support functions:
If you plan to support bounding-box-only R-tree indexes (described in Bounding-Box-Only R-Tree Indexes), which are the default R-tree indexes created by Version 9.21.UC1 or later of the database server, or you plan to support nearest-neighbor searches, you must also implement the RtreeInfo support function with the operation strat_func_substitutions.
You must list the Union, Size, and Inter support functions in the order shown when you execute the CREATE OPCLASS statement to register the operator class with the database server. In other words, you must list the Union, Size, and Inter support functions as the first, second, and third support functions, respectively, in the CREATE OPCLASS statement. This SQL statement is described in Syntax for Creating a New Operator Class.
In addition to the required support functions, the R-tree access method also recognizes the following four optional support functions that it uses to enhance the performance of the statement that creates the R-tree index:
You are not required to include these support functions in your operator class. However, since these functions are specifically designed to improve the performance of the creation of R-tree indexes, it is highly recommended that you include them in your operator class.
If you decide to include these optional support functions in your operator class, you must list them after the required support functions, in the order shown, when you execute the CREATE OPCLASS statement to register the operator class with the database server. In other words, you must list the SFCbits, ObjectLength, SFCvalue, and SetUnion support functions as the fourth, fifth, sixth, and seventh support functions, respectively, in the CREATE OPCLASS statement. This SQL statement is described in Syntax for Creating a New Operator Class.
You must list the RtreeInfo support function in the eighth position, after Union, Size, and Inter, and the four optional bulk-loading support functions. If you do not provide the four optional bulk-loading support functions in your DataBlade module, specify NULL in the fourth, fifth, sixth, and seventh positions in the CREATE OPCLASS statement.
The following sections describe how the R-tree access method uses the support functions and how you should write each function, and provide an example of an SQL statement used to create the Union function. Examples of the SQL statements to create the Size, Inter, SFCbits, ObjectLength, SFCvalue, and SetUnion functions are not provided because they are similar to the Union example.
The R-tree access method uses the required support functions in combination when it maintains the R-tree index. For example, when the access method is deciding into which subtree to place a new entry, it uses the Union and Size functions to determine how much each bounding box needs to expand if the new entry were added to that subtree. After a page splits, the access method uses the Union function to calculate a new bounding box for all entries on a page.
The RtreeInfo support function determines, for a given strategy function, which strategy function should actually be called when the R-tree access method is working on an internal nonleaf page. It also provides support for nearest-neighbor searches. You must define the RtreeInfo function if your DataBlade module is going to support bounding-box-only R-tree indexes or nearest-neighbor searches.
The R-tree access method uses the four optional support functions (SFCbits, ObjectLength, SFCvalue, and SetUnion) to increase the performance of initial R-tree index creation by performing fast bulk loading of data into the index from a populated table. First, the R-tree access method groups together the rows that belong to the same page. At the same time, the access method identifies the neighbors of each page. Once this process is completed, the R-tree access method stores all the rows in a singly linked list of leaf pages, filled as compactly as possible. As the leaf pages become full, the access method recursively builds the pages at the higher levels. The R-tree access method repeats this process until all the rows are written into the leaf pages.
The R-tree access method uses this method of building R-tree indexes only if you specify the optional support functions in the appropriate operator class. If you do not specify these support functions, then the R-tree access method uses a slower method to create the R-tree index.
The R-tree access method uses the Union function to find a new all-inclusive bounding box for the index entries on an index page when a new entry is added. The union of the old bounding box and the bounding box of the new entry is the new, possibly enlarged, bounding box for the entire index page.
The R-tree access method also uses the Union function when it calculates onto which index page it should put a new index entry. In conjunction with the Size function, the Union function shows how much the old bounding box must be enlarged to include the new index entry. In other words, the Union function tells the R-tree access method the data size of a bounding box.
The access method also uses the Union function after a page split to calculate the bounding box for the new page and to evaluate the new groupings between the old and new pages.
The SQL signature of the Union support function must be:
Union (UDT, UDT, UDT) RETURNS INTEGER
UDT refers to user-defined type, or the data type you want to index with the R-tree access method.
Write the Union function to calculate the overall bounding box of the bounding boxes of the objects in the first two parameters and to store the result in the third parameter.
The return value of the Union function is not used by the R-tree access method. The Union function should call the mi_db_error_raise() DataBlade API function to return errors.
For variable UDTs, the third parameter of the Union function is not initialized; it contains a valid mi_lvarchar data type with a conservatively large amount of memory allocated to it. Be sure you set the size in the function to the size, in bytes, of the largest possible result.
The result returned in the third parameter of the Union function must be a fixed size and not a large object. Set its size large enough for any return value.
The R-tree access method implementation assumes that the size returned from the first call to the Union function is the size of all internal index keys. Therefore, when you write the code for the Union function, pick a maximum size for any internal index keys of an R-tree index and set the size of the union to that value.
For sample C code of the Union function, see Union Support Function. C code uses the DataBlade API to interact with the database server.
The R-tree access method uses the Size function to evaluate different ways to group objects by comparing the sizes of bounding boxes around objects or groups of objects. It does this when it decides where to place a new data object and when it splits a page. Ideally, a disk page is divided into two pages whose overall bounding boxes are as compact and small as possible.
For sample C code of the Size function, see Size Support Function. C code uses the DataBlade API to interact with the database server.
The SQL signature of the Size support function must be:
Size (UDT, DOUBLE PRECISION) RETURNS INTEGER
UDT refers to user-defined type, or the data type you want to index with the R-tree access method.
Write the Size function to calculate the relative size of the bounding box of the object in the first parameter and to store the result in the second parameter as a double-precision value.
The return value of the Size function is not used by the R-tree access method. The Size function should call the mi_db_error_raise() DataBlade API function to return errors.
Write the Size function to always return a different value as a bounding box expands or shrinks by the addition or removal of objects inside it. This means that you should add a compensating factor when calculating the size to take care of degenerate bounding boxes. A degenerate bounding box is one that has one or more sides of 0 length.
Assume your data is in a two-dimensional space and you decide to use a simple length times width calculation to compute the size of a bounding box. If the width of the bounding box subsequently shrinks to 0, then the size of the bounding box is 0. However, if it was the length of the original bounding box that shrunk to 0, then the size would also be 0, breaking the rule that different bounding boxes return different sizes. Figure 5 describes this situation.
In this situation, a better formula for calculating the size of a bounding box would be:
(length times width) plus (length plus width)
This formula for the Size function always returns a larger value if the box changes by the inclusion of a new item and returns a smaller value if it shrinks because something inside was removed.
The SQL signature of the Inter support function must be:
Inter (UDT, UDT, UDT) RETURNS INTEGER
UDT refers to user-defined type, or the data type you want to index with the R-tree access method.
Write the Inter function to calculate the intersection of the bounding boxes of the objects in the first two parameters and to store the result in the third parameter. The R-tree access method uses the resulting bounding box in a subsequent call to the Size function to find out how much two bounding boxes overlap.
The return value of the Inter function is not used by the R-tree access method. The Inter function should call the mi_db_error_raise() DataBlade API function to return errors.
For variable length UDTs, the third argument of the Inter function is not initialized; it contains a valid mi_lvarchar data type. You must set the size in the function to the size, in bytes, of the largest possible result.
For sample C code of the Inter function, see Inter Support Function. C code uses the DataBlade API to interact with the database server.
The RtreeInfo support function defines the switching semantics for the strategy functions in your DataBlade module. The R-tree access method calls the RtreeInfo function, if it exists, to determine, for a given strategy function, which strategy function it should actually call when working on an internal nonleaf page.
Earlier versions of the R-tree access method required DataBlade module strategy functions to test whether a page stored a bounding box or not to determine if that page was a leaf page or an internal page (only internal pages used to store bounding boxes). In the current version of the R-tree access method, if your DataBlade module implements the RtreeInfo function with the strat_func_substitutions operation, by default, indexes are created as bounding-box-only R-tree indexes; leaf pages store only bounding boxes (and not data objects).
For this version of the R-tree access method, if you are supporting bounding-box-only indexes, you must use a different method to specify how strategy functions behave when called on an internal nonleaf page or on a leaf page. To better understand why you might want your strategy function to behave differently on an internal nonleaf page or on a leaf page, see the following example and Internal Uses of the Strategy Functions. This section describes why each of the four required strategy functions sometimes uses different strategy functions on internal nonleaf pages and which function is actually used on the internal nonleaf pages. If necessary, you must redesign your strategy functions if you want them to behave differently for leaf and nonleaf pages. This is because you cannot distinguish between leaf and nonleaf items in a bounding-box-only index.
For example, suppose you have a strategy function in slot 5 named MyEqual, which is a variation on the Equal function. When this function is called on a nonleaf page, you want it to behave like Contains; you cannot eliminate nonleaf items by testing their bounding boxes for equality, because the test is too stringent. But when MyEqual is called on a leaf page, you do want it to test for equality. If the leaf pages contain the complete objects (the index is not a bounding-box-only index), you can implement this behavior switch yourself in the MyEqual function by checking to see if one or both operands are bounding boxes. However, with a bounding-box-only index, the leaf pages hold only the objects' bounding boxes. In this case, an implementation of MyEqual, which performs a Contains check whenever it is called with bounding boxes, would be inefficient because it would force the R-tree access method to make the extra step of retrieving a complete object from the table. Instead, a candidate data object could be eliminated immediately by performing an equality check on its leaf page bounding box.
To detect whether the operands are leaf or nonleaf data, and switch behavior accordingly, use the RtreeInfo support function, as described in this section, or design your own strategy functions to make this determination.
The R-tree access method checks for the RtreeInfo function when it creates an R-tree index and updates the root page with the information. This means that if you create an RtreeInfo support function that defines the switching semantics of your strategy functions, you must update existing R-tree indexes so they know about it.
Use the oncheck utility to update any existing indexes, using the following syntax:
oncheck -ci -u "info_anchor_update"
{database[:[owner.]table[,fragdbs|#index]]}
Write the RtreeInfo support function to take four arguments.
| Argument | Signature | Description |
|---|---|---|
| First | mi_lvarchar *dummy_obj | Should be NULL. |
| Second | mi_lvarchar *operation_ptr | A pointer to an MI_LVARCHAR structure that contains a string that represents the information needed from the DataBlade module. When writing the RtreeInfo function to return the internal-page equivalents of strategy functions, the string is strat_func_substitutions. |
| Third | mi_lvarchar *opclass_ptr | This argument points to an MI_LVARCHAR structure that contains a string that represents the name of the operator class. |
| Fourth | mi_lvarchar *answer_ptr | This argument points to an MI_LVARCHAR structure that contains a pointer to the structure that returns information to the R-tree access method. If answer_ptr is NULL, then the R-tree access method calls the RtreeInfo function to determine if a particular operation is supported by your DataBlade module. If the operation is not supported, set the return value of the function to RLT_OP_UNSUPPORTED. If the operation is supported, set the return value of the function to MI_OK. If answer_ptr is not NULL, fill in the array of integers with the slot numbers of the internal-page equivalent strategy functions. (This array is allocated by the R-tree access method). Then set the return value of the function to MI_OK. |
Use the following CREATE FUNCTION SQL statement template to create the RtreeInfo support function after you write and compile the code:
CREATE FUNCTION rtreeInfo(UDT, pointer, pointer, pointer) RETURNS INT WITH (NOT VARIANT, PARALLELIZABLE) EXTERNAL NAME '$INFORMIXDIR/extend/bladedir/xxx.bld(funcname) LANGUAGE C;
In the statement template, the text UDT refers to user-defined type or the data type you want to index with the R-tree access method; bladedir refers to the name of your DataBlade module under the extend directory; xxx refers to the name of the shared object that contains the code for your DataBlade module; and funcname refers to the name of the function within the shared object that contains the code for the RtreeInfo function.
When you create the operator class with the CREATE OPCLASS statement, include the RtreeInfo support function in the eighth position, after the three required support functions Union, Size, and Inter, and the four optional bulk-loading support functions SFCbits, ObjectLength, SFCvalue, and SetUnion. If you do not provide the four optional bulk-loading support functions in your DataBlade module, specify NULL in the fourth, fifth, sixth, and seventh positions in the CREATE OPCLASS statement.
You can use the following sample C code to help write your own RtreeInfo function.
/**************************************************************************
* Description: Example of new support function used to return *
* requested Information to R-tree. *
* *
* Arguments: *
* *
* dummy_obj - (is NULL) *
* *
* operation_ptr - ptr to string that represents the operation. *
* *
* opclass_ptr - ptr to string that represents the opclass name. *
* *
* answer_ptr - pointer to the pointer to the structure used to *
* return information to R-tree. *
* answer_ptr is a "pointer to a pointer" to make *
* the interface generic to support later *
* operations to implement which the blade might *
* need to allocate memory and return its address *
* to R-tree. For the operation *
* "strat_func_substitutions", memory is allocated *
* by R-tree. *
* *
* *
* Support function slot no: 8 *
* *
* Return values: MI_OK - Success, operation supported. *
* MI_ERROR - Error. *
* RLT_OP_UNSUPPORTED - operation not supported. *
* *
***************************************************************************
*/
#define RLT_OP_UNSUPPORTED 1
mi_integer
rtreeInfo (mi_lvarchar *dummy_obj, mi_lvarchar *operation_ptr,
mi_lvarchar *opclass_ptr, mi_lvarchar *answer_ptr)
{
mi_integer status = MI_OK;
mi_string *operation = NULL, *opclassname = NULL;
/* opclassname may be used if required */
operation = mi_lvarchar_to_string(operation_ptr);
if (operation == NULL)
{
status = MI_ERROR;
goto bad;
}
opclassname = mi_lvarchar_to_string(opclass_ptr);
if (opclassname == NULL)
{
status = MI_ERROR;
goto bad;
}
if (!strcmp(operation,"strat_func_substitutions"))
{
mi_integer *answer = NULL;
if (answer_ptr == NULL)
{
status = MI_OK;
goto done;
}/* Option is supported */
/* For operation "strat_func_substitutions" memory
* for 64 slots is allocated by R-tree. For later
* operations, we might need to allocate the return
* structure and set its address.
*/
answer =(mi_integer*)
mi_get_vardata((mi_lvarchar*)
(mi_get_vardata(answer_ptr)));
if (answer == NULL)
{
status = MI_ERROR;
goto bad;
}
/* Provide mapping for strategy functions to be used at
* internal nodes.
* If the mapping changes for the opclasses I support,
* use the opclassname
*/
if (!strcmp(opclass,"my_opclass1"))
{
answer[0] = 0;
answer[1] = 2;
answer[2] = 2;
answer[3] = 0;
answer[4] = 4;
answer[5] = 4;
/* as many slots as strategy functions. max is 64 */
}
else if (!strcmp(opclass,"my_opclass2")) {
answer[0] = 0;
answer[1] = 2;
answer[2] = 2;
answer[3] = 0;
answer[4] = 4;
}
else /* for all other opclasses that I support */
{
answer[0] = 0;
answer[1] = 2;
answer[2] = 2;
answer[3] = 0;
}
status = MI_OK;
}
else
status = RLT_OP_UNSUPPORTED;
/* Only "strat_func_substitutions" is
* supported, as yet. */
done:
bad:
if (opclassname)
mi_free(opclassname);
if (operation)
mi_free(operation);
return status;
}
The R-tree secondary access method uses the SFCbits function to determine the number of bits required by the internal space-filling curve (SFC) algorithm to represent the spatial key. An example of a space-filling curve is the Hilbert function.
The SFCbits support function is optional. If you create it and specify it in the operator class with the other optional support functions, the R-tree secondary access method uses a fast bulk-loading algorithm to initially create an R-tree index. If you have not specified this function in the operator class, then the access method uses a slower method to create R-tree indexes.
The SQL signature of the SFCbits support function must be:
SFCbits (UDT, POINTER) RETURNS INTEGER
UDT refers to user-defined type, or the data type you want to index with the R-tree access method.
The sample C signature of the SFCbits function for a variable length UDT is:
mi_integer SFCbits(mi_lvarchar *object, mi_integer *bits)
Write the SFCbits function to return, in the second parameter, the number of bits required to build a spatial key on the data type you want to index. This value must be either 32 or 64.
The return value of the SFCbits function is not used by the R-tree access method. The SFCbits function should call the mi_db_error_raise() DataBlade API function to return errors.
For sample C code of the SFCbits function, see SFCbits Support Function in Appendix A. Shapes3 Sample DataBlade Module. C code uses the DataBlade API to interact with the database server.
The R-tree secondary access method uses the ObjectLength function to determine the maximum size, in bytes, of the objects stored in the column that is being indexed with an R-tree index.
The ObjectLength support function is optional. If you create it and specify it in the operator class with the other optional support functions, the R-tree secondary access method uses a fast bulk-loading algorithm to initially create an R-tree index. If you have not specified this function in the operator class, then the access method uses a slower method to create R-tree indexes.
The SQL signature of the ObjectLength support function must be:
ObjectLength (UDT, POINTER) RETURNS INTEGER
UDT refers to user-defined type, or the data type you want to index with the R-tree access method.
The sample C signature of the ObjectLength function is:
mi_integer ObjectLength(mi_lvarchar *object, mi_integer *obj_max_length)
The first parameter of the ObjectLength function contains the name of the data type to be indexed; it does not contain a row value. For example, if the data type to be indexed is MyPoint, the parameter contains the string MyPoint.
Write the ObjectLength function to return, in the second parameter, the maximum possible size, in bytes, of the objects in the column to be indexed.
The return value of the ObjectLength function is not used by the R-tree access method. The ObjectLength function should call the mi_db_error_raise() DataBlade API function to return errors.
For sample C code of the ObjectLength function, see ObjectLength Support Function in Appendix A. Shapes3 Sample DataBlade Module. C code uses the DataBlade API to interact with the database server.
The R-tree secondary access method uses the SFCvalue function to determine the sort values of an array of objects of the data type of the column that is being indexed with an R-tree index.
The SFCvalue support function is optional. If you create it and specify it in the operator class with the other optional support functions, the R-tree secondary access method uses a fast bulk-loading algorithm to initially create an R-tree index. If you have not specified this function in the operator class, then the access method uses a slower method to create R-tree indexes.
The SQL signature of the SFCvalue support function must be:
SFCvalue (UDT, INTEGER, POINTER) RETURNS INTEGER
UDT refers to user-defined type, or the data type you want to index with the R-tree access method.
The sample C signature of the SFCvalue function is:
mi_integer SFCvalue(mi_lvarchar *objects, mi_integer array_size,
void *spatialKey)
Write the SFCvalue function to store an array of mi_lvarchar pointers in the data portion of the first parameter. Each mi_lvarchar pointer points to a data object in the table for which the R-tree access method needs to compute a sort value.
The second parameter is the number of elements in the array.
The third output parameter is an array of either 32-bit or 64-bit values, depending on the number of bits specified in the corresponding SFCbits function. This array stores a spatial key for each data object. The number of elements in this array is always the same as the number of elements in the array of the first parameter. The R-tree secondary access method automatically allocates enough space for the array of the third parameter.
The return value of the SFCvalue function is not used by the R-tree access method. The SFCvalue function should call the mi_db_error_raise() DataBlade API function to return errors.
For sample C code of the SFCvalue function, see SFCValue Support Function. C code uses the DataBlade API to interact with the database server.
The R-tree secondary access method uses the SetUnion function to determine the union of all the elements in an array of objects of the data type of the column that is being indexed with an R-tree index.
The SetUnion support function is optional. If you create it and specify it in the operator class with the other optional support functions, the R-tree secondary access method uses a fast bulk-loading algorithm to initially create an R-tree index. If you have not specified this function in the operator class, then the access method uses a slower method to create R-tree indexes.
The SQL signature of the SetUnion support function must be:
SetUnion (UDT, INTEGER, POINTER) RETURNS INTEGER
UDT refers to user-defined type, or the data type you want to index with the R-tree access method.
The sample C signature of the SetUnion function is:
mi_integer SetUnion (mi_lvarchar *objects, mi_integer array_size,
void *UnionObject)
Write the SetUnion function to store an array of mi_lvarchar pointers in the data portion of the first parameter. Each mi_lvarchar pointer points to objects in the table for which the R-tree access method needs to compute the union. Each of the objects is either a data object or a bounding box.
The second parameter is the number of elements in the array.
The third output parameter is a single object that contains the union of all the objects in the input array of the first parameter. The R-tree secondary access method uses the Union support function to automatically allocate enough space for the output value.
The return value of the SetUnion function is not used by the R-tree access method. The SetUnion function should call the mi_db_error_raise() DataBlade API function to return errors.
For sample C code of the SetUnion function, see SetUnion Support Function. C code uses the DataBlade API to interact with the database server.
The database server automatically resolves internal function signatures for a subtype that inherits a function from a supertype in the following two cases:
You must first create a cast with the CREATE IMPLICIT CAST statement for it to be used implicitly during the execution of a query. The query optimizer tries to find implicit casts when it tries to make arguments fit support and strategy function signatures.
This example describes the SQL statement that registers the Union support function with the database server. The example is based on the objects of the sample DataBlade module, described in Appendix A. Shapes3 Sample DataBlade Module.
The SQL statements to register the Size, Inter, SFCbits, ObjectLength, SFCvalue, and SetUnion support functions with the database server are similar to the SQL statement to register the Union function.
The following SQL statement shows how to register the Union support function with the database server:
CREATE FUNCTION Union (MyShape, MyShape, MyShape)
RETURNS INTEGER
WITH
(
NOT VARIANT
)
EXTERNAL NAME "$INFORMIXDIR/extend/shapes.3.0/shapes.bld (MyShapeUnion)"
LANGUAGE C;
The three parameters of the function are all of data type MyShape. The C function MyShapeUnion, found in the shared object file $INFORMIXDIR/extend/Shapes.3.6/Shapes.bld, contains the actual C code that calculates the union of two objects of type MyShape.
For the sample C code of the MyShapeUnion function, see Union Support Function. C code uses the DataBlade API to interact with the database server. Sample C code to implement the Size and Inter functions is also provided in that appendix.
For more information on the DataBlade API, refer to the IBM Informix: DataBlade API Programmer's Guide.
For more information and examples on how to create user-defined functions, refer to IBM Informix: User-Defined Routines and Data Types Developer's Guide.
Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]