The mi_lvarchar Data Type

Home | Previous Page | Next Page DataBlade API Overview > Accessing SQL Data Types > Character Data Types >

The mi_lvarchar Data Type

The mi_lvarchar data type has the following uses:

Holds data of an LVARCHAR column
Holds character data that is passed to or received from an SQL statement when the query is in binary mode
Holds data for character arguments and return values of C UDRs
Holds the external format of an opaque data type

The following sections summarize each of these uses of an mi_lvarchar. For information about the structure of the mi_lvarchar data type, see Varying-Length Data Type Structures.

The SQL LVARCHAR Data Type

The LVARCHAR data type of SQL stores variable-length character strings whose length can be up to 32,739 bytes. LVARCHAR is a built-in opaque data type that is valid in distributed queries of tables, views, and synonyms of databases outside the local server. The DataBlade API supports the LVARCHAR data type with the mi_lvarchar data type, which is implemented in the DataBlade API as a varying-length structure.

Tip:

The SQL data type LVARCHAR and the DataBlade API data type mi_lvarchar are not the same. Although you use mi_lvarchar to hold LVARCHAR data, mi_lvarchar is also used for other purposes.

If you declare no maximum size for an LVARCHAR column, the default size is two kilobytes. The maximum valid size is 32,739 bytes, but the maximum row size in a database table is limited to 32 kilobytes. (In addition, no more than 195 columns in the same database table can be of varying-length data types, named or unnamed ROW data types, collection data types, or simple large object data types, regardless of the declared size of individual columns.)

If you attempt to insert more than the declared maximum size into an LVARCHAR column, the result depends on the data type of the data:

If the value comes from a built-in type (such as CHAR or VARCHAR), the database server truncates the data to the declared column size.
The database server does not truncate data strings that come from an mi_lvarchar structure, but the database server does return an error.

Tip:

If you need to store more than 32,739 bytes of text data in a database of the local database server, use the CLOB data type. The CLOB data type allows you to store the text data outside the database table, in an sbspace. For more information, see Using Smart Large Objects.

Character Data in Binary Mode of a Query

When the database server processes a query, it might handle character data in the following cases:

Character data that is passed as an input parameter to an SQL statement
Character data that an SQL statement returns (for example, as a column value)

When a query has a control mode of binary, the database server stores character data in an mi_lvarchar varying-length structure. For more information on the control modes of a query, see Control Modes for Query Data.

Character Data in C UDRs (Server)

You must use the mi_lvarchar data type if your UDR expects any of the SQL character data types as an argument or a return value. Within an MI_DATUM structure, the routine manager passes character data to and from a C UDR as a pointer to an mi_lvarchar varying-length structure. Therefore, a C UDR must handle text data as mi_lvarchar values when it receives arguments or returns data of an SQL character data type, as the following table describes.

Handling Character Data	More Information
If the C UDR receives an argument of an SQL character data type, it must declare its corresponding parameter as a pointer to an mi_lvarchar data type.	Handling Character Arguments
If a C UDR returns a value of an SQL character data type, it must return a pointer to an mi_lvarchar data type.	Returning Character Values

External Representation of an Opaque Data Type (Server)

The database server stores the external representation of an opaque data type in an mi_lvarchar varying-length structure. The external representation is a text representation of the opaque-type data. Therefore, the input and output support functions of an opaque type handle the external representation as an mi_lvarchar. For more information, see Input and Output Support Functions.