![]() |
|
The circle data type is an example of a fixed-length opaque data type written in C. This data type includes an (x,y) coordinate, to represent the center of the circle, and a radius value. This section briefly shows how to create the circle data type.
Figure 10-1 shows the internal data structures for the circle data type.
The internal representation for circle requires three double values: two double values for the center (x and y in the point_t structure) and one for the radius. Because each double is 8 bytes, the total internal length for the circle_t structure is 24 bytes.
The following table shows possible function signatures for the support functions of the circle data type.
The actual code for the circle data type would be written in the C language, compiled, and put in the circle.so shared-object file. For information about shared-object files, refer to Creating a Shared-Object File.
Suppose the input and output functions of the circle data type define the external format that Figure 10-2 shows.
The input support function, circle_input(), would accept a string of the form in Figure 10-2, parse the string, and store each value in the circle_t structure. The output support function, circle_output(), would perform the inverse operation: it would take the values from the circle_t structure and build a string of the form in Figure 10-2.
The following example shows the SQL statements that register the circle opaque data type and its input, output, send, and receive support functions in the database:
The CREATE OPAQUE TYPE statement registers the circle data type, which has the following characteristics:
The CREATE FUNCTION statements register the following support functions:
The CREATE CAST statements create the appropriate casts for the support functions. For more information on these casts, see Creating Casts for Opaque Data Types.
The CREATE OPAQUE TYPE statement in the previous example creates the circle data type with the Usage privilege granted to the owner (the person who ran the CREATE OPAQUE TYPE statement). The following GRANT statement allows all users of the database to use the circle data type in SQL statements:
The CREATE FUNCTION statements register the support functions for the circle data type with the Execute privilege granted to the owner (the person who ran the CREATE FUNCTION statements). The following GRANT statements grant the Execute privilege to all users of the database on the support statements that are defined as explicit casts:
The circle data type has two end-user functions:
The following SQL statements register the end-user functions for the circle data type with the database:
To generate a lexicographical sequence, the B-tree index compares the area of two circle values to determines the order of the values. Because the operator-class functions of the B-tree index do not include information about the circle data type, you must write the following functions so that the B-tree index can order the values correctly:
You must first write the B-tree strategy functions in C. The following table shows the meaning and possible function signatures for the strategy functions that handle the circle data type.
These functions might already have been defined when you provided support for the relational operators on your opaque data type. (For more information, see Comparing Data.) In this case, the lessthan(), lessthanorequal(), equal(), greaterthan(), and greaterthanorequal() functions have already been written, compiled, stored in a shared-object file, and registered in the database. Therefore, the generic B-tree index can already use them as its strategy functions.
However, if you had not yet defined the relational operators for the circle data type, you would need to do so to provide support for B-tree indexes on circle columns and on user-defined functions that return the circle data type. Once you have generated the code for these functions and stored their compiled versions in a shared-object file, you must register them in the database using the CREATE FUNCTION statement.
The compare() function is the support function for the generic B-tree index. You might have already defined this function to provide support for the comparison operations in a SELECT statement (such as the ORDER BY clause or the BETWEEN operator) on your opaque data type. (For more information, see Comparing Data.) In this case, the compare() function has already been written, compiled, stored in a shared-object file, and registered in the database. Therefore, the generic B-tree index can use it as its support function for the circle data type.
However, if you had not yet defined the compare() function for the circle data type, you must do so to provide support for B-tree indexes on circle columns and user-defined functions that return the circle data type. Once you have generated the code for this function and stored its compiled version in a shared-object file, you must register it in the database with the CREATE FUNCTION statement.
With the strategy and support functions registered, you are ready to define generic B-tree indexes on the circle data type. The code fragment in the next section creates a generic B-tree index called circle_ix on the circle_col column.
Tip: To index the values of the area of the circle data type, you could also create a functional index on the area() function.
Using the circle Opaque Data Type
The following example shows the SQL statements that create a table called circle_tab that has a column of data type circle and insert several rows into this table:
For information about the CREATE INDEX statement in this example, see Providing Indexes for the circle Data Type.
In the Informix ESQL/C Programmer's Manual, the chapter on opaque types provides examples of how to access the circle opaque data type with a fixed binary host variable.