Informix DataBlade API Programmer's Manual Accessing SQL Data Types

This section discusses DataBlade API support for the following SQL data types:

• The BOOLEAN data type
• The POINTER data type
• Simple large objects: TEXT and BYTE

Boolean data holds values to indicate two states: true and false. The DataBlade API provides support for boolean values in both their text and binary representations.

The DataBlade API supports a Boolean value in text representation as a single quoted character with the format that Figure 2-17 shows.

A Boolean value in its text representation is often called a Boolean string.

The SQL BOOLEAN data type holds the internal (binary) format of a Boolean value. This value is a single-byte representation of Boolean data, as the following table shows.

The BOOLEAN data type is a predefined opaque type (an opaque data type that Informix defines). Its external format is the Boolean text representation that Figure 2-17 on page 2-44 shows. Its internal format consists of the values shown in the preceding table. For a complete description of the SQL BOOLEAN data type, see the Informix Guide to SQL: Reference.

Tip: The internal format of the BOOLEAN data type is often referred to as its binary representation.

The DataBlade API supports the SQL BOOLEAN data type with the mi_boolean data type. Therefore, the mi_boolean data type also holds the binary representation of a Boolean value.

The mi_boolean data type is guaranteed to be 1 byte on all computer architectures. Therefore, it can fit into an MI_DATUM and can be passed by value in C user-defined routines.

All data types, including mi_boolean, must be passed by reference in client LIBMI applications.

Because the mi_boolean value is smaller than the size of an MI_DATUM, the DataBlade API cast promotes the value to the size of MI_DATUM when it copies it into an MI_DATUM. When you obtain the mi_boolean value from an MI_DATUM, you need to reverse the cast promotion to assure that your value is correct.

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

Alternatively, you can declare an mi_integer value to hold the Boolean value.

The SQL POINTER data type is the SQL equivalent of a generic pointer. This data type is used in the routine registration of a user-defined routine to indicate that some data type has no equivalent SQL data type. The DataBlade API represents the POINTER data type with the mi_pointer data type.

Use the mi_pointer data type only for communications between user-defined routines. The POINTER data type is a predefined opaque type (an opaque data type that Informix defines). However, Informix does not include any opaque-type support functions for this data type.

Important: Because the POINTER data type does not include opaque-type support functions, you cannot pass this type between the database server and a client application. Also, do not define columns to be of type POINTER.

The mi_pointer data type is guaranteed to be the size of the C type void * on all computer architectures. The C type void * is usually equivalent to a long type, which is usually 4 bytes in length.

On 64-bit platforms, void * is 8 bytes in length. Therefore, mi_pointer is also 8 bytes.

Therefore, an mi_pointer can fit into an MI_DATUM and can be passed by value to and from C user-defined routines. Keep in mind that because mi_pointer actually contains an address to a value, passing an mi_pointer by value is actually the same as passing the value to which mi_pointer points by reference.

Important: When you use mi_pointer, make sure that the value that the mi_pointer references is allocated with a memory duration appropriate to the use of the value. For more information, see Determining Memory Duration.

Simple Large Objects

The DataBlade API does not provide direct support for simple large objects. Therefore, it cannot directly access TEXT and BYTE columns. However, the database server provides the following cast functions between simple and smart large objects.

For more information on these SQL cast functions, see the description of the Expression segment in the Informix Guide to SQL: Syntax.

C UDRs can accept TEXT data as arguments because the database server passes all character data in the mi_lvarchar data type. For more information, see Character Data in C UDRs.

C UDRs can also accept BYTE data as long as they declare and handle this data as a smart large object. The database server converts the BYTE data to BLOB data when it passes this data to the UDR.