Informix Guide to GLS Functionality Informix ESQL/C Features

When the client and database code sets differ, the ESQL/C client application performs code-set conversion on character data. For more information, see Performing Code-Set Conversion. If your ESQL/C application executes in an environment in which code-set conversion might occur, check that the application correctly handles the following situations:

• When the application writes simple large objects (TEXT or BYTE data) to the database, it must set the loc_type field in the locator structure loc_t to indicate the type of simple large object that it needs to write.
• When the application writes smart large objects (CLOB or BLOB data) to the database in Dynamic Server, it uses various large-object file descriptors.
• When the application uses the sqlda structure to describe dynamic SQL statements, it must account for possible size differences in character data.
• When the application has character data that might undergo code-set conversion, you must declare character buffers that can hold the data.

For more information, see Avoiding Partial Characters.

ESQL/C uses the loc_t locator structure to read simple large objects from and write simple large objects to the database server. The loc_type field of this structure indicates the data type of the simple large object that the structure describes. When the client and database code sets are the same (no code-set conversion), the client application does not need to set the loc_type field explicitly because the database server can determine the simple large object data type implicitly. The database server assumes that character data has the TEXT data type and noncharacter data has the BYTE data type.

However, if the client and database code sets are different and convertible, the client application must know the data type of the simple large object in order to determine whether to perform code-set conversion on the data. Before an ESQL/C client application inserts a simple large object in the database, it must explicitly set the loc_type field of the simple large object as follows:

• For a TEXT value, the ESQL/C client application must set the loc_type field to SQLTEXT before the INSERT statement.

The client performs code-set conversion on TEXT data before it sends this data to the database for insertion.

• For a BYTE value, the ESQL/C client application must set the loc_type field to SQLBYTES before the INSERT statement.

The client does not perform code-set conversion on BYTE data before it sends this data to the database for insertion.

Important: The sqltypes.h header file defines the data type constants SQLTEXT and SQLBYTES. To use these constants, you must include this header file in your ESQL/C source file.

Your ESQL/C source code does not need to set loc_type before it reads simple-large-object data from a database. The database server obtains the data type of the simple large object from the database and sends this data type to the client with the data.

If you set loc_bufsize to -1, ESQL/C allocates memory to hold a single simple large object. It stores the address of this memory buffer in the loc_buffer field of the loc_t structure. If the client application performs code-set conversion on TEXT data that the database server retrieves, ESQL/C handles any possible data expansion as follows:

1. Frees the existing memory that the loc_buffer field references
2. Reallocates a memory buffer that is large enough to store the expanded TEXT data
3. Assigns the address of this new memory buffer to the loc_buffer field
4. Assigns the size of the new memory buffer to the loc_bufsize field

If this reallocation occurs, ESQL/C changes the memory address at which it stores the TEXT data. If your ESQL/C program references this address, the program must account for the address change.

ESQL/C does not need to reallocate memory for the TEXT data if code-set conversion does not expand the TEXT data or if it condenses the data. In either of these cases, the loc_buffer field remains unchanged, and the loc_bufsize field contains the size of the buffer that the loc_buffer field references.

The sqlda structure is a dynamic-management structure that contains information about columns in dynamic SQL statements. The DESCRIBE...INTO statement uses the sqlda structure to return information about the select-list columns of a SELECT statement. It sets the sqlvar field of an sqlda structure to point to a sequence of partially filled sqlvar_struct structures. Each structure describes a single select-list column.

Each sqlvar_struct structure contains character data for the column name and the column data. When the ESQL/C client application fills this structure, the column name and the column data are in the client code set. When the database server fills this structure and executes a DESCRIBE...INTO statement, this character data is in the database code set.

When the client application performs code-set conversion between the client and database code sets, the number of bytes that is required to store the column name and column data in the client code set might not equal the number that is required to store this same information in the database code set. Therefore, the size of the character data in sqlvar_struct might increase or decrease during code-set conversion. To handle this possible difference in size, the client application must ensure that it correctly handles the character data in the sqlvar_struct structure.

To hold the column data, the client application must allocate a buffer and set sqldata to point to this buffer. If your client application might perform code-set conversion, it must allocate sufficient storage to handle the increase in the size of the column data that might occur.

When the DESCRIBE...INTO statement sets the sqllen field, the sqllen value indicates the length of the column data in the database code set. Therefore, if you use the value of sqllen that the DESCRIBE...INTO statement retrieves, you might not allocate a buffer that is sufficiently large for the data when it is in the client code set. For example, the following code fragment allocates an sqldata buffer with the malloc() system call:

EXEC SQL include sqlda;
...
struct sqlda *q_desc;
...
EXEC SQL describe sqlstmt_id into q_desc;

...
q_desc->sqlvar[0].sqldata = 
	(char *)malloc(q_desc->sqlvar[0].sqllen);

In the preceding code fragment, the client application might truncate characters that it converts because the client application uses the sqllen value to determine the buffer size. Instead, increase the buffer to four times its original size when you allocate a buffer, as the following code fragment shows:

EXEC SQL include sqlda;

EXEC SQL define BUFSIZE_FACT 4;
...


struct sqlda *q_desc;
...


q_desc->sqlvar[0].sqllen = 
	q_desc->sqlvar[0].sqllen * BUFSIZE_FACT + 1;

q_desc->sqlvar[0].sqldata = 
	(char *)malloc(q_desc->sqlvar[0].sqllen);

Informix suggests a buffer-size factor (BUFSIZE_FACT) of 4 because a multibyte character has a maximum size of 4 bytes.

The sqlname field contains the name of the column. When the client application performs code-set conversion, this column name might also undergo expansion when the application converts it from the database code set to the client code set. Because the ESQL/C application stores the buffer for sqlname data in its internal work area, your ESQL/C source code does not have to handle possible buffer-size increases. Your code processes the contents of sqlname in the client code set.