INFORMIX
Informix Guide to GLS Functionality
Chapter 8: INFORMIX-ESQL/C Features
Home Contents Index Master Index New Book

Handling Code-Set Conversion

 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, make sure that the application correctly handles the following situations:

Writing TEXT Values

Important: The following information pertains to INFORMIX-OnLine Dynamic Server only. For information on how to write TEXT values in INFORMIX-Universal Server, refer to the "INFORMIX-ESQL/C Programmer's Manual."
ESQL/C uses the loc_t locator structure to read blobs from and write blobs to the database server. The loc_type field of this structure indicates the data type of the blob value 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 blob 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 this blob in order to determine whether to perform code-set conversion on the blob data. Before your ESQL/C client application inserts a blob into the database, it must explicitly set the loc_type field of the blob as follows:

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

    The client does not perform code-set conversion on BYTE blob 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. You must include this header file in your ESQL/C source file to use these constants. For more information on the sqltypes.h header file, see Chapter 2 of the "INFORMIX-ESQL/C Programmer's Manual."
Your ESQL/C source code does not need to set loc_type before it reads blob data from a database. The database server obtains the data type of the blob 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 blob value. 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 blobs 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 blob. 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.

Using the DESCRIBE Statement

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. (For more information about how to determine select-list columns, see "Using an sqlda Structure" in Chapter 10 of the INFORMIX-ESQL/C Programmer's Manual.)

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 (when it 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.

The sqldata Field

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:

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 shown in the following code fragment:

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

The sqlname Field

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.



Informix Guide to GLS Functionality, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.