Return character values

The routine manager handles all character return values from a C UDR as mi_lvarchar values. Therefore, a C UDR must declare its return value as a pointer to an mi_lvarchar when it returns data for any of the following SQL character data types:

CHAR
IDSSECURITYLABEL
LVARCHAR
NCHAR
NVARCHAR
VARCHAR

Use of the SQL TEXT data type in a C UDR is not supported.

For more information about the NCHAR and NVARCHAR data types, see the HCL Informix® GLS User's Guide.

Important: SQL data types are not represented as null-terminated strings, so do not code a C UDR to return a null-terminated string. For more information about how to access an mi_lvarchar structure, see Varying-length data type structures.

For example, the initial_cap() function in Figure 1 can ensure that names are entered with an initial uppercase letter followed by lowercase letters. This UDR would be useful in the following query to ensure consistent capitalization of the customer last name:

INSERT INTO customer(customer_num, lname, fname)
VALUES (0, initial_cap("ANDERSON"), initial_cap("TASHI"));

The calls to initial_cap() in this INSERT statement convert the last and first names of this customer as Anderson and Tashi, respectively.

Figure 1 shows the following declaration for initial_cap():

/* Valid C UDR declaration for string return value */
mi_lvarchar *initial_cap(str)
   mi_lvarchar *str;

This declaration correctly specifies an mi_lvarchar pointer as the return type so that the function can return the VARCHAR value. The following declaration of initial_cap() is invalid because it specifies an mi_string pointer as the return type:

/* INVALID declaration for string return value */
mi_string *initial_cap(string)
   mi_lvarchar *string;

The initial_cap() function in the preceding declaration would not return the expected value because the routine manager interprets the mi_string that the UDR returns as an mi_lvarchar.

Tip: A C UDR that accepts data for one of these SQL character data types must also declare its parameters as mi_lvarchar pointers. For more information, see Handling character arguments.