Varying-length opaque data type

If the C structure that holds your opaque type can vary in size depending on the data it holds, you must declare the opaque type as a varying-length opaque type.

The opaque type can contain character strings. Each instance of the opaque type can contain a character string with a different size. When you define the internal representation of a varying-length opaque, make sure that only the last member of the C structure is of varying size.

The following code fragment shows the internal representation for a varying-length opaque data type named image.

Figure 1. Internal representation for the image opaque data type

typedef struct 
   {
   mi_integer         img_id;
   mi_integer         img_thresh_trck;
   mi_integer         img_thresh;
   mi_date            img_date;
   mi_integer         img_flags;
   mi_lvarchar   img_data;
   } image_t;

You tell the database server that an opaque type is varying length when you register the opaque type. In the CREATE OPAQUE TYPE statement, you must include the INTERNALLENGTH modifier with the VARIABLE keyword.

The CREATE OPAQUE TYPE statement in the following code fragment registers the image opaque type (which Figure 1 defines) as a varying-length opaque type.

Figure 2. Registration of the image opaque data type

CREATE OPAQUE TYPE image 
   (INTERNALLENGTH = VARIABLE);

The database server stores the value of the INTERNALLENGTH modifier in the length column of the sysxtdtypes system catalog table. For varying-length opaque types, this column holds a value of zero.

You can obtain information about support functions for the image varying-length opaque type in Write opaque-type support functions. The following table lists the image support functions that this section declares.

Support function for image opaque type	Where to find declaration
Input	Figure 3
Output	Figure 3
Receive	Figure 3
Send	Figure 3
Import	Figure 3
Export	Figure 3
Importbin	Figure 3
Exportbin	Figure 3

The database server requires you to store the C data structure for a varying-length opaque type in an mi_lvarchar structure. To store varying-length data in the mi_lvarchar structure, you need to code support functions. The size limitations of a varying-length structure apply to a varying-length opaque type as follows:

By default, the maximum size for a varying-length opaque type is two kilobytes.
You specify a different maximum size for a varying-length opaque type when you register the opaque type.
In the CREATE OPAQUE TYPE statement, use the MAXLEN modifier. You can specify a maximum length of up to 32 kilobytes. The database server stores the value of the MAXLEN modifier in the maxlen column of the sysxtdtypes system catalog table.

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

CREATE OPAQUE TYPE var_type 
   (INTERNALLENGTH=VARIABLE, MAXLEN=4096);

Because the database server uses mi_lvarchar to transfer varying-length data, the passing mechanism for a varying-length opaque type is always by reference. For more information, see Determine the passing mechanism for an opaque type.