Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

The mi_get_string() function copies an mi_string (CHAR(x)) value from a buffer.

mi_unsigned_char1 *mi_get_string(data_ptr, string_dptr, srcbytes)

mi_unsigned_char1 *data_ptr;

mi_string **string_dptr;

mi_integer srcbytes;

data_ptr	is a pointer to the buffer from which the mi_string value is to be copied.
string_dptr	is a pointer to the buffer to which the mi_string value is to be copied.
srcbytes	is the number of source bytes to be copied.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
No	Yes

The mi_get_string() function copies srcbytes bytes from the user-defined buffer that data_ptr references into the mi_string value that string_ptr references. Upon completion, mi_get_string() returns the address of the position within the buffer to which data can be copied. The function advances the returned address by srcbytes bytes, ready for a subsequent copy. In other words, if srcbytes is the length of the value in string_buf, the returned address is srcbytes bytes advanced from the original buffer address in data_dptr.

The mi_get_string() function is useful in a receive support function of an opaque data type that contains mi_string values. Use this function to receive an aligned string value from a client application, which possibly has unaligned data buffers.

If code-set conversion is required, the mi_get_string() function converts the mi_string value from the code set of the client locale to that of the serverprocessing locale. For more information, see the Informix Guide to GLS Functionality.

Tip: While other mi_get functions accept a preallocated buffer, mi_get_string() allocates memory for data to be copied. This allocation is why the function accepts a pointer to the address as the buffer argument.

Return Values

mi_unsigned_char1 *	is the new address in the data_ptr data buffer.
NULL	indicates that the function was not successful.

See the description of the following functions: mi_get_bytes(), mi_get_date(), mi_get_datetime(), mi_get_decimal(), mi_get_double_precision(), mi_get_int8(), mi_get_integer(), mi_get_interval(), mi_get_lo_handle(), mi_get_money(), mi_get_real(), mi_get_smallint(), and mi_put_string().

For more information on the use of mi_get_string() in a receive support function, see Converting Opaque-Type Data With Machine-Specific Data Types.