Determine the passing mechanism for an opaque type

The way that the DataBlade API passes the internal representation of an opaque type in an MI_DATUM structure depends on the kind of opaque type, as follows:

For fixed-length opaque types, the contents of the MI_DATUM structure depends on the size of the internal representation for the opaque type:
- Most fixed-length opaque types have an internal representation that cannot fit into an MI_DATUM structure. These fixed-length opaque types must be passed by reference. The MI_DATUM structure contains a pointer to the internal C structure of the opaque type.
- If your fixed-length opaque type is always smaller than the size of the MI_DATUM data type, the opaque type can be passed by value. The MI_DATUM structure contains the actual internal representing of the opaque type.
  For such fixed-length opaque types, you must include the PASSEDBYVALUE modifier in the CREATE OPAQUE TYPE statement when you register the opaque type. The database server stores the value of the PASSEDBYVALUE modifier in the byvalue column of the sysxtdtypes system catalog table.
For varying-length opaque types, the MI_DATUM structure always contains a pointer to an mi_lvarchar structure.
Varying-length opaque types must be passed by reference. The actual varying-length data is in the data portion of this mi_lvarchar structure.

If the internal representation of a fixed-length opaque type can fit into an MI_DATUM structure, the routine manager can pass the internal representation by value. Suppose you have the declaration in following code fragment for a fixed-length opaque type named two_bytes.

Figure 1. Internal representation for the two_bytes opaque data type

typedef two_bytes_t mi_smallint;

The following CREATE OPAQUE TYPE statement specifies that the two_bytes fixed-length opaque type can be passed by value:

CREATE OPAQUE TYPE two_bytes (INTERNALLENGTH=2, 
   ALIGNMENT=2, PASSEDBYVALUE);

Figure 2 declares the output support function for the two_bytes fixed-length opaque type. The intrnl_format parameter in this declaration is passed by value. In contrast, the circle fixed-length opaque type (which Figure 1 declares) cannot fit into an MI_DATUM structure. Therefore, its output support function must declare its intrnl_format parameter as passed by reference, as Figure 1 shows.

When the routine manager receives data from a varying-length opaque type, it passes the data to the C UDR in an mi_lvarchar varying-length structure that the UDR allocates. The routine manager also passes a pointer to this mi_lvarchar structure as the MI_DATUM structure for the UDR argument. Therefore, a C UDR must have its parameter declared as a pointer to an mi_lvarchar structure when the parameter accepts data from varying-length opaque types. Figure 3 shows the declaration of the output support function for the image varying-length opaque type.