Creating the Fixed-Length Internal Structures

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.

Writing the circle Support Functions

circle_t * circle_input(extrnl_format)

	mi_lvarchar *extrnl_format;

mi_lvarchar * circle_output(intrnl_format)

	circle_t *intrnl_format;

circle_t * circle_receive(client_intrnl_format)

	mi_sendrecv *client_intrnl_format;

mi_sendrecv * circle_send(srvr_intrnl_format)

	circle_t *srvr_intrnl_format;

The actual code for the circle data type would be written in the C language, compiled, and put in the circle.so shared library.

Suppose the input and output functions of the circle data type define the external format that Figure 5-3 shows.

Figure 5-3 External Format of the circle Opaque Data Type

The input support function, circle_input(), would accept a string of the form in Figure 5-3, 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 5-3.

Registering the circle Opaque Type

The CREATE OPAQUE TYPE statement in Figure 5-4 registers the circle data type, which has the following characteristics:

• It is a fixed-length opaque type whose size is 24 bytes.
• It is to be aligned on 4-byte boundaries (the default alignment).
• When passed as an argument to a user-defined function, the opaque type is passed by reference (the default parameter-passing mechanism).

• The input support function is registered in the database as circle_in(). Its source code is the circle_input() function in the /usr/lib/circle.so shared library.
• The output support function is registered in the database as circle_out(). Its source code is the circle_output() function in the /usr/lib/circle.so shared library.
• The receive support function is registered in the database as circle_rcv(). Its source code is the circle_receive() function in the /usr/lib/circle.so shared library.
• The send support function is registered in the database as circle_snd(). Its source code is the circle_send() function in the /usr/lib/circle.so shared library.

Granting Privileges on the circle Data Type

GRANT USAGE ON TYPE circle TO PUBLIC

GRANT EXECUTE ON FUNCTION circle_out TO PUBLIC;

GRANT EXECUTE ON FUNCTION circle_snd TO PUBLIC;

• The radius() function obtains the radius value from a circle_t structure.

• The area() function calculates the area of the circle that a circle_t structure describes.

The following SQL statements register the end-user functions for the circle data type with the database:

CREATE FUNCTION radius(circle) RETURNS FLOAT

	AS EXTERNAL NAME '/usr/lib/circle.so'

	LANGUAGE C NOT VARIANT;

CREATE FUNCTION area(crcl_val circle) RETURNING FLOAT

	DEFINE pi FLOAT;



	LET pi = 3.1415926;

	RETURN (pi * POW(RADIUS(circle), 2);

END FUNCTION;

• The strategy functions of the default operator class for the generic
  B-tree

For more information about these functions, see "The B-Tree Strategy Functions".

• The support function of the default operator class for the generic
  B-tree

For more information about these functions, see "The B-Tree Support Function".

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.

B-Tree Strategy Function	Meaning for circle Data Type	Function Signature
lessthan()	area(circle1) < area(circle2)	boolean circ le_lessthan(crc1, crc2) circle *crc1, *crc2;
lessthanorequal()	area(circle1) <= area(circle2)	boolean circle_lessthanorequal(crc1, crc2) circle *crc1, *crc2;
equal()	area(circle1) = area(circle2)	boolean circle_equal(crc1, crc2) circle *crc1, *crc2;
greaterthan()	area(circle1) > area(circle2)	boolean circle_greaterthan(crc1, crc2) circle *crc1, *crc2;
greaterthanorequal()	area(circle1) >= area(circle2)	boolean circle_greaterthanorequal(crc1, crc2) circle *crc1, *crc2;

These functions might already have been defined when you provided support for the relational operators on your opaque 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 library, 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 library, you must register them in the database.

Figure 5-5 shows the CREATE FUNCTION statements that register the B-tree strategy functions for the circle data type with the database.

Figure 5-5 Registering the B-Tree Strategy Functions for the circle Opaque Data Type

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 type. (For more information, see "Comparing Data".) In this case, the compare() function has already been written, compiled, stored in a shared library, 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 would need to 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 library, you must register it in the database with the following CREATE FUNCTION statement:

CREATE FUNCTION compare(cir1 circle, cir2 circle)

	RETURNS integer

	EXTERNAL NAME '/usr/lib/circle.so(circle_compare)'

	LANGUAGE C NOT VARIANT

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

For information about the CREATE INDEX statement in Figure 5-6, 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 type with a fixed binary host variable.