Contents of an MI_DATUM Structure

A datum in an MI_DATUM structure can describe a value of any SQL data type. You can use an MI_DATUM structure to transport a value of an SQL data type between the database server and the DataBlade API module.

MI_DATUM in a C UDR (Server)

In a C UDR, the contents of an MI_DATUM structure depend on the SQL data type of the value, as follows:

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

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

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

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

For all data types that Table 13 lists, the DataBlade API passes the value in an MI_DATUM structure 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 */

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

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

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

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

When you obtain the mi_boolean value from the MI_DATUM structure, 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, it is recommended that you declare small pass-by-value SQL types as mi_integer.

For all data types not listed in Table 13, the DataBlade API passes the value in an MI_DATUM structure by reference; that is, the MI_DATUM structure contains a pointer to the actual data type.

UDRs store the data types of their arguments in an 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 one-, two-, or 
    * four-byte item from argument
    */
   }
else
   {
   /* Argument is passed by reference: it contains a pointer
    * to the actual value
    */
   }

However, a UDR that hardcodes a type identifier in a switch or if statement to determine actions can handle only built-in data types. It cannot handle all possible user-defined types because not all of them have unique, type-specific identifiers.

MI_DATUM in a Client LIBMI Application

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