Informix DataBlade API Programmer's Manual Accessing SQL Data Types

The DataBlade API handles a generic data value as an MI_DATUM value, also called a datum. A datum is a chunk of memory that can fit into a computer register.

In the C language, the void * type is a typeless way to point to any object and should hold any integer value. This type is usually equivalent to the long int type and is usually 4 bytes in length, depending on the computer architecture. An MI_DATUM is defined as a void * type. The MI_DATUM data type is guaranteed to be the size of the C type void * on all computer architectures.

On 64-bit platforms, void * is 8 bytes in length. Therefore, MI_DATUM is stored in 8 bytes. However, the 4-byte MI_DATUM is put into the appropriate 4 bytes of the 8-byte void *.

This section provides the following information about the MI_DATUM data type:

• What value does the MI_DATUM contain?
• How do you perform address calculations with MI_DATUM?
• Where are the uses of MI_DATUM?

A datum can describe any SQL data type; it is used to transport an SQL data type between the database server and the DataBlade API module.

In a C UDR, the content of an MI_DATUM depends on the data type of the value, as follows:

• For most data types, the MI_DATUM contains a pointer to the data type.

The actual value of most data types is too large to fit within an MI_DATUM. For such data types, the DataBlade API passes the value using the pass-by-reference mechanism. Use the contents on the MI_DATUM as a pointer to access the actual value.

• For a few small data types, the MI_DATUM contains the actual data value.

Figure 2-18 shows the few data types whose value can always fit in an MI_DATUM. For these data types, the DataBlade API passes the value using the pass-by-value mechanism. Use the contents of the MI_DATUM as the actual data value.

Figure 2-18
Data Types That Can Fit into MI_DATUM (Those Passed by Value)

Data Type of DataBlade API Value	Length	SQL Data Type
Data types that can hold 4-byte integers, including mi_integer and mi_unsigned_integer	4	The SQL INTEGER data type
mi_date	4	The SQL DATE data type
Data types that can hold 2-byte integers, including mi_smallint and mi_unsigned_smallint	2	The SQL SMALLINT data type
Data types that can hold a 1-byte character, including mi_char1 and mi_unsigned_char	1	The SQL CHAR(1) data type (Multicharacter values must be passed by reference.)
mi_boolean	1	The SQL BOOLEAN data type
mi_pointer	sizeof(void *)	The SQL POINTER data type
C data structure for the internal format of opaque data type (when structure size can fit into MI_DATUM)	Depends on the size of the C data structure	An opaque data type whose CREATE OPAQUE TYPE statement specifies the PASSEDBYVALUE modifier

For all data types listed in Figure 2-18, the DataBlade API passes the value in an MI_DATUM by value unless the variable is declared as pass by reference. For example, in the following sample function signature, the arg2 variable would be passed by reference to the my_func() UDR because it is declared as a pointer:

mi_integer my_func(arg1, arg2)
	mi_integer arg1; /* passed by value */
	mi_integer *arg2; /* passed by reference */

Data types with sizes smaller than or equal to the size of void* can be passed by value because they can fit into the MI_DATUM. However, passed-by-value data types that are smaller than the size of MI_DATUM are cast promoted to the MI_DATUM size with whatever byte position is appropriate for the computer architecture. When you obtain the smaller passed-by-value data type from an MI_DATUM, you need to reverse the cast promotion to assure that your value is correct.

For example, an mi_boolean value is a 1-byte value. To pass it by value, the DataBlade API performs something like the following example when it puts the mi_boolean into an MI_DATUM:

datum = (void*) ((char) bool))

In the preceding cast promotion, datum is an MI_DATUM and bool is an mi_boolean.

When you obtain the mi_boolean value from the MI_DATUM, reverse the cast-promotion process with something like the following example:

mi_boolean bool_val;
MI_DATUM datum;
...
bool_val = (char) datum;

To avoid the cast promotion situation, Informix recommends that you declare small by-value SQL types as an mi_integer.

For all data types not listed in Figure 2-18, the DataBlade API passes the value in an MI_DATUM by reference; that is, the MI_DATUM contains a pointer to the actual data type.

Warning: Do not assume that any data type of length 1, 2, or 4 is passed by value. Not all 1-, 2-, or 4-byte datums are passed by value. For example, the mi_real data type is passed by reference. Always check the data type or use the mi_type_byvalue() function to determine the passing mechanism.

User-defined routines store the data types of their arguments in the MI_FPARAM structure. You can check the type identifier of an argument to determine if it is passed by value or by reference, as the following code fragment shows:

my_type_id = mi_fp_argtype(my_fparam, 1);
my_type_desc = mi_type_typedesc(conn, my_type_id);
if ( mi_type_byvalue(my_type_desc) == MI_TRUE )
	{
	/* Argument is passed by value: extract 1-, 2-, or 
	** 4-byte item from argument */
	}
else
	{
	/* Argument is passed by reference: it contains a pointer
	** to the actual value */
	}

The preceding rules for passing values by reference and by value in MI_DATUM do not apply to client LIBMI applications. In client LIBMI applications, pass all data types in MI_DATUM by reference.

An MI_DATUM value holds a value that is transferred to or from the database server. DataBlade API functions handle an MI_DATUM consistently. The following table shows examples of the use of MI_DATUM values.