ABLE keyword to define a varying-length opaque data type.
A Fixed-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. The maximum internal length for a fixed-length opaque type is 32760 bytes.

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.

A Varying-Length Opaque Data Type

When you specify the VARIABLE keyword for the INTERNALLENGTH modifier, you create a varying-length opaque data type. The default 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. The maximum internal length for a varying-length opaque type is 32740 bytes. 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. A varying-length opaque data type is also limited to 195 columns within the 32740 byte maximum length.

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.

The C data structure for a varying-length opaque type must be stored in an mi_lvarchar data structure. For information about mi_lvarchar, refer to the IBM Informix: DataBlade API Function Reference.

Memory Alignment

When the database server passes the data type to a UDR, 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.

ALIGNMENT
Value		 Meaning Purpose
1 Align structure on single-byte boundary. Structures that begin with 1-byte quantities
2 Align structure on 2-byte boundary. Structures that begin with 2-byte quantities such as mi_unsigned_smallint
4 Align structure on 4-byte boundary. Structures that begin with 4-byte quantities such as float or mi_unsigned_integer
8 Align structure on 8-byte boundary. Structures that contain members of the C double data type

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.

Parameter Passing

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

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, ALIGNMENT=2,
   PASSEDBYVALUE);
Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]