Extending Informix Dynamic Server 2000 Creating an Opaque Data Type

To create an opaque data type, follow these steps:

1. Create the internal structure for the opaque data type in C or Java.
2. Write the support functions as external functions.
3. Register the opaque data type in the database with the CREATE OPAQUE TYPE statement.
4. Register the support functions of the opaque data type with the CREATE FUNCTION statement.
5. Provide access to the opaque data type and its support functions with the GRANT statement.
6. Write any SQL-invoked functions that are needed to support the opaque data type.
7. Provide any customized secondary access methods that the opaque data type might need.

The following sections describe each of these steps.

The internal structure of an opaque data type is a C data structure. For the internal structure, use the C typedefs that the DataBlade API supplies for those fields whose size might vary by platform. Use of these typedefs, such as mi_integer and mi_float, improves the portability of the opaque data type. For more information on these data types, see the DataBlade API Programmer's Manual.

The internal structure uniquely names the opaque data type. Informix recommends that you develop a unique prefix (such as the mi_ prefix used in the previous paragraph) for the opaque data type. You can use this prefix with each member of the internal structure and the structure itself. For opaque data types, Informix appends the string _t to the structure name. For example, the circle_t data structure holds the values for the circle opaque data type.

When you create the internal structure, consider the following impacts of the size of this structure:

• The final structure size of the new opaque data type
• The alignment in memory of the opaque data type
• The method for passing the opaque data type to user-defined routines

You provide this information when you create the opaque data type with the CREATE OPAQUE TYPE statement.

To save space in the database, lay out internal structures as compactly as possible. The database server stores values in their internal representation, so any internal structure with padding between entries consumes unnecessary space.

The INTERNALLENGTH keyword of the CREATE OPAQUE TYPE statement supplies the final size of the internal structure. This keyword provides the following two ways to specify the size:

• Specify the actual size, in bytes, of the internal structure to define a fixed-length opaque data type.
• Specify the VARIABLE keyword to define a varying-length opaque data type.

When you specify the actual size for INTERNALLENGTH, you create a fixed-length opaque data type. The size of a fixed-length opaque data type must match the value that the C-language sizeof() directive returns for the internal structure.

On most compilers, the sizeof() directive rounds up to the nearest 4-byte size to ensure that pointer match on arrays of structures works correctly. However, you do not need to round up for the size of a fixed-length opaque data type. Instead you can specify alignment for the opaque data type with the ALIGNMENT modifier. For more information, see Memory Alignment.

For an example of a fixed-length opaque data type, see A Fixed-Length Opaque Data Type: circle.

When you specify the VARIABLE keyword for the INTERNALLENGTH modifier, you create a varying-length opaque data type. By default, the maximum size for a varying-length opaque data type is 2 kilobytes.

To specify a different maximum size for a varying-length opaque data type, use the MAXLEN modifier. You can specify a maximum length of up to 32 kilobytes. When you specify a MAXLEN value, the database server can optimize resource allocation for the opaque data type. If the size of the data for an opaque data type exceeds the MAXLEN value, the database server returns an error.

For example, the following CREATE OPAQUE TYPE statement defines a varying-length opaque data type called var_type whose maximum size is 4 kilobytes:

CREATE OPAQUE TYPE var_type (INTERNALLENGTH=VARIABLE,

	MAXLEN=4096);

Only the last member of the internal structure can be of varying size.

For an example of a varying-length opaque data type, see A Varying-Length Opaque Data Type: image.

When the database server passes the data type to a user-defined routine, it aligns opaque-type data on a specified byte boundary. Alignment requirements depend on the C definition of the opaque data type and on the system (hardware and compiler) on which the opaque data type is compiled.

You can specify the memory-alignment requirement for your opaque data type with the ALIGNMENT modifier of the CREATE OPAQUE TYPE statement. The following table summarizes valid alignment values.

Structures that begin with single-byte characters, char, can be aligned anywhere. Arrays of a data type should follow the same alignment restrictions as the data type itself.

For example, the following CREATE OPAQUE TYPE statement specifies a fixed-length opaque data type, called LongLong, of 18 bytes that must be aligned on a 1-byte boundary:

CREATE OPAQUE TYPE LongLong (INTERNALLENGTH=18, ALIGNMENT=1);

If you do not include the ALIGNMENT modifier in the CREATE OPAQUE TYPE statement, the default alignment is a 4-byte boundary.

The database server can pass opaque-type values to a user-defined routine in either of the following ways:

• Pass by value passes the actual value of the opaque data type to a user-defined routine.
• Pass by reference passes a pointer to the value of the opaque data type to a user-defined routine.

By default, the database server passes all opaque types by reference. For the database server to pass an opaque data type by value, specify the PASSEDBYVALUE modifier in the CREATE OPAQUE TYPE statement. Only an opaque data type whose size is 4 bytes or smaller can be passed by value. However, the DataBlade API data type mi_real, although only 4 bytes in length, is always passed by reference.

The following CREATE OPAQUE TYPE statement specifies that the two_bytes opaque data type be passed by value:

CREATE OPAQUE TYPE two_bytes (INTERNALLENGTH=2

      PASSEDBYVALUE);

Once you have created the internal structure and support functions for the opaque data type, use the following SQL statements to register them with the database:

• The CREATE OPAQUE TYPE statement registers the opaque data type as a data type.
• The CREATE FUNCTION statement registers a support function.
• The CREATE CAST statement registers the support functions as cast functions.

Important: These SQL statements register the opaque data type in the current database. For users of another database to have access to the opaque data type, you must run the CREATE OPAQUE TYPE, CREATE FUNCTION, and CREATE CAST statements when this second database is the current database.

The CREATE OPAQUE TYPE statement registers an opaque data type with the database. It provides the following information to the database:

• The name and owner of the opaque data type

The opaque-type name is the name of the data type that SQL statements use. It does not have to be the name of the internal structure for the opaque data type. You might find it useful to create a special prefix to identify the data type as an opaque data type. The opaque-type name must be unique within the name space.

• The size of the opaque data type

You specify this size information with the INTERNALLENGTH modifier. It indicates whether the data type is a fixed-length or varying-length opaque data type. For more information, see Creating the Internal Structure in C.

• The values of the different opaque-type modifiers

The CREATE OPAQUE TYPE statement can specify the following modifiers for an opaque data type: MAXLEN, PASSEDBYVALUE, CANNOTHASH, and ALIGNMENT. You determine this information when you create the internal structure for the opaque data type. For more information, see Creating the Internal Structure in C.

The CREATE OPAQUE TYPE statement stores this information in the sysxtdtypes system catalog table. When it stores a new opaque data type in sysxtdtypes, the CREATE OPAQUE TYPE statement causes a unique value, called an extended identifier, to be assigned to the opaque data type. Throughout the system catalog, an opaque data type is identified by its extended identifier, not by its name. (For more information on the columns of the sysxtdtypes system catalog, see the chapter on system catalog tables in the Informix Guide to SQL: Reference.)

To register a new opaque data type in a database, you must have the Resource privilege on that database. By default, a new opaque data type has Usage permission assigned to the owner. For information on how to change the permission of an opaque data type, see Granting Privileges for an Opaque Data Type.

Once you have registered the opaque data type, you can use the data type in SQL statements and in user-defined routines. For more information on the syntax of the CREATE OPAQUE TYPE statement, see the description in the Informix Guide to SQL: Syntax.

Use the CREATE FUNCTION statement to register a support function with the database. The following example shows the CREATE FUNCTION syntax for a support function written in C:

CREATE FUNCTION func_name(parameter_list) RETURNS ret_type

	EXTERNAL NAME 'pathname'

	LANGUAGE C NOT VARIANT

This SQL statement provides the following information to the database:

• The name, func_name, and owner of the support function
• An optional specific name for the support function (not shown)
• The data types of the parameters, parameter_list, and return value, ret_type, of the support function
• The location, pathname, of the source code for the support function
• The language of the support function: LANGUAGE C.
• The routine modifier to indicate that a support function does not return different results with different arguments: NOT VARIANT

When you register a support function with the CREATE FUNCTION syntax for external functions, use the appropriate SQL data types for parameter_list and ret_type, as follows.

In the preceding table, opaque data type is the name of the data type that you specify in the CREATE OPAQUE TYPE statement. For more information, see Registering the Opaque Data Type.

The CREATE FUNCTION statement stores this information in the sysprocedures system catalog table. When it stores a new support function in sysprocedures, the CREATE FUNCTION statement causes a unique value, called an routine identifier, to be assigned to the support function. Throughout the system catalog, a support function is identified by its routine identifier, not by its name.

By default, a new support function has Execute permission assigned to the owner. For information on how to change the permission of an support function, see Privileges on the Support Functions.

You cannot use the CREATE FUNCTION directly in an ESQL/C program. To register an opaque-type support function from within an ESQL/C application, you must put the CREATE FUNCTION statement in an operating-system file. Then use the CREATE FUNCTION FROM statement to identify the location of this file. The CREATE FUNCTION FROM statement sends the contents of the operating-system file to the database server for execution.

For more information on the syntax of the CREATE FUNCTION and CREATE FUNCTION FROM statements, see their descriptions in the Informix Guide to SQL: Syntax.

For each of the support functions in the following table, the database server uses a cast to convert the opaque data type to a particular internal data type.

For the database server to perform these casts, you must create the casts with the CREATE CAST statement. The database server can then call the appropriate support function when it needs to cast opaque-type data to or from the LVARCHAR, SENDRECV, IMPEXP, or IMPEXPBIN data types.

The CREATE CAST statement stores information about cast functions in the syscasts system catalog table. For more information on the CREATE CAST statement, see the description in the Informix Guide to SQL: Syntax. For a description of casting, see the Informix Guide to SQL: Tutorial.