Extending Informix Dynamic Server 2000 Creating an Opaque Data Type

The image data type is an example of a varying-length opaque data type written in C. The image data type encapsulates an image such as a JPEG, GIF, or PPM file. If the image is less than 2 kilobytes, the data structure for the data type stores the image directly. However, if the image is greater than 2 kilobytes, the data structure stores a reference (an LO-pointer structure) to a smart large object that contains the image data. An image stored in the smart large object can be referenced by multiple rows, but the database server only needs to store a single copy of it in an sbspace.

This section briefly outlines how to create the image data type.

The following statements shows the internal structure for the image data type in the database:

typedef struct 

	{

	int		img_len; 

	int		img_thresh;

	int		img_flags;

	union

		{

		ifx_lop_t    img_lobhandle;

		char  	  	img_data[4];

		}

	} image_t;

The following table shows possible function signatures for the basic support functions of the image data type.

The image data type has an embedded smart large object. Therefore, it has the following additional support functions.

The assign() function decides whether to store the image directly in the row or in a separate smart large object. This simple varying-length opaque data type does not require a destroy() function.

The following example shows the SQL statements that register the image data type and its basic support functions in the database:

CREATE OPAQUE TYPE image (INTERNALLENGTH = VARIABLE);

CREATE FUNCTION image_in(txt LVARCHAR) RETURNS image

	EXTERNAL NAME '/usr/lib/image.so(image_input)'

	LANGUAGE C NOT VARIANT;
CREATE IMPLICIT CAST (LVARCHAR AS image WITH image_in);

CREATE FUNCTION image_out(im image) RETURNS LVARCHAR

	EXTERNAL NAME '/usr/lib/image.so(image_output)'

	LANGUAGE C NOT VARIANT;
CREATE EXPLICIT CAST (image AS LVARCHAR WITH image_out);

CREATE FUNCTION image_rcv(cl_im SENDRECV) RETURNS image

	EXTERNAL NAME '/usr/lib/image.so(image_receive)'

	LANGUAGE C NOT VARIANT;
CREATE IMPLICIT CAST (SENDRECV AS image) WITH image_rcv);

CREATE FUNCTION image_snd(srv_im image) RETURNS SENDRECV

	EXTERNAL NAME '/usr/lib/image.so(image_send)'

	LANGUAGE C NOT VARIANT;
CREATE EXPLICIT CAST (image AS SENDRECV WITH image_snd);

The CREATE OPAQUE TYPE statement registers the image data type, which has the following characteristics:

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

The CREATE FUNCTION statements register the following basic support functions:

• The input support function is registered in the database as image_in(). Its source code is the image_input() function in the /usr/lib/image.so shared-object file.
• The output support function is registered in the database as image_out(). Its source code is the image_output() function in the /usr/lib/image.so shared-object file.
• The receive support function is registered in the database as image_rcv(). Its source code is the image_receive() function in the /usr/lib/image.so shared-object file.
• The send support function is registered in the database as image_snd(). Its source code is the image_send() function in the /usr/lib/image.so shared-object file.

For information about shared-object files, refer to Creating a Shared-Object File.

This example also shows the CREATE CAST statements to create the appropriate cast definitions for the input, output, receive, and send support functions. For more information on casts, see Creating Casts for Opaque Data Types.

The following example shows the SQL statements that register the other support functions for the image data type in the database:

CREATE FUNCTION image_imp(imp_im IMPEXP) RETURNS image

	EXTERNAL NAME '/usr/lib/image.so(image_import)'

	LANGUAGE C NOT VARIANT;
CREATE IMPLICIT CAST (IMPEXP AS image WITH image_imp);

CREATE FUNCTION image_exp(exp_im image) RETURNS IMPEXP

	EXTERNAL NAME '/usr/lib/image.so(image_export)'

	LANGUAGE C NOT VARIANT;
CREATE EXPLICIT CAST (image AS IMPEXP WITH image_exp);

CREATE FUNCTION image_impbin(impbin_im IMPEXPBIN) 

	RETURNS image

	EXTERNAL NAME '/usr/lib/image.so(image_importbin)'

	LANGUAGE C NOT VARIANT;
CREATE IMPLICIT CAST 

	(IMPEXPBIN AS image WITH image_impbin);

CREATE FUNCTION image_expbin(expbin_im image) 

	RETURNS IMPEXPBIN

	EXTERNAL NAME '/usr/lib/image.so(image_exportbin)'

	LANGUAGE C NOT VARIANT;
CREATE EXPLICIT CAST 

	(image AS IMPEXPBIN WITH image_expbin);

CREATE FUNCTION lohandles(im image) RETURNS POINTER

	EXTERNAL NAME '/usr/lib/image.so(image_lohandles)'

	LANGUAGE C NOT VARIANT;

CREATE FUNCTION assign(im image) RETURNS image

	EXTERNAL NAME '/usr/lib/image.so(image_assign)'

	LANGUAGE C NOT VARIANT;

The CREATE FUNCTION statements register the following support functions:

• The import support function is registered in the database as image_imp(). Its source code is the image_import() function in the /usr/lib/image.so shared-object file.
• The export support function is registered in the database as image_exp(). Its source code is the image_export() function in the /usr/lib/image.so shared-object file.
• The importbinary support function is registered in the database as image_impbin(). Its source code is the image_importbin() function in the /usr/lib/image.so shared-object file.
• The exportbinary support function is registered in the database as image_expbin(). Its source code is the image_exportbin() function in the /usr/lib/image.so shared-object file.
• The lohandles support function is registered in the database as lohandles(), its required name. Its source code is the image_lohandles() function in the /usr/lib/image.so shared-object file.
• The assign support function is registered in the database as assign(), its required name. Its source code is the image_assign() function in the /usr/lib/image.so shared-object file.

For information about shared-object files, refer to Creating a Shared-Object File.

This example also shows the CREATE CAST statements to create the cast definitions for the import, export, importbinary, and exportbinary support functions. For more information on these casts, see Creating Casts for Opaque Data Types.

The CREATE OPAQUE TYPE statement in the example in Registering the image Opaque Data Typecreates the image 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 image data type in SQL statements:

GRANT USAGE ON TYPE image TO PUBLIC

The CREATE FUNCTION statements in the two previous examples register the support functions for the image 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:

GRANT EXECUTE ON FUNCTION image_out TO PUBLIC;

GRANT EXECUTE ON FUNCTION image_snd TO PUBLIC;

GRANT EXECUTE ON FUNCTION image_imp TO PUBLIC;

GRANT EXECUTE ON FUNCTION image_impbin TO PUBLIC;

The image data type has the following end-user functions:

• The getsize() function returns the size of the image data.
• The image_zoom() function zooms the given image to a parametric factor in both x and y dimensions and returns a new image.

The actual code for the end-user functions would be written in the C language and put in the image.so shared-object file. The following SQL statements register the end-user functions for the image opaque data type with the database:

CREATE FUNCTION getsize(im image) RETURNS INTEGER

	EXTERNAL NAME '/usr/lib/image.so(image_size)'

	LANGUAGE C NOT VARIANT;

CREATE FUNCTION image_zoom(im image, i integer) 

	RETURNS image

	EXTERNAL NAME '/usr/lib/image.so(image_zoom)'

	LANGUAGE C NOT VARIANT;

Suppose you decide that the default secondary access method, a generic B-tree index, does not adequately handle data in columns of type image. Because the image data type holds spatial data, it is a good candidate for an R-tree index. To use an R-tree index, you must first install a spatial DataBlade module that implements the R-tree index. For more information about R-trees, refer to the user guide for the DataBlade module and to the Informix R-Tree Index User's Guide.