Informix Guide to GLS Functionality General SQL API Features

Each Informix SQL API product contains a processor to process an ESQL source file that has embedded SQL and preprocessor statements. The ESQL/C processor, esql, processes C source files.

The processors for ESQL/C products use operating-system files in the following situations:

• They write language-specific source files (.c) when they process an ESQL/C source file.

The ESQL/C processors use the client code set (that the client locale specifies) to generate the filenames for these language-specific files.

• They read ESQL/C source files (.ec) that the user creates.

The ESQL/C processors use the client code set to interpret the contents of these ESQL/C source files.

Use the CLIENT_LOCALE environment variable to specify the client locale.

A GLS locale supports a particular code set, which can contain single-byte characters and multibyte characters. When your application processes only multibyte characters, if can perform string-processing tasks based on the assumption that the number of bytes in a buffer equals the number of characters that the buffer can hold. For single-byte code sets, you can rely on the built-in scaling for array allocation and access that the C compiler provides.

However, if your application processes multibyte characters, it can no longer make the same assumption as for single-byte characters. The number of bytes in a buffer no longer equals the number of characters in the buffer. Because of the potential of varying number of bytes for each character, you can no longer rely on the C compiler to perform character-processing tasks such as traversing a multibyte-character string and allocating space for a multibyte-character string.

You can use functions from the Informix GLS library to communicate to your application how to perform internationalization on character-processing tasks.

Character-processing tasks are as follows:

• String traversal
• String processing
• Character classification
• Case conversion
• Character comparison and sorting

For more information and the syntax of these functions, see the Informix GLS Programmer's Manual.

When you internationalize an application, consider how to handle the format of locale-specific data. The format in which numeric, monetary, and date and time data appears to the end user is locale specific. The GLS locale file defines locale-specific formats for each of these types of data, as the following table shows.

The Informix GLS library provides functions that allow you to perform the following tasks on locale-specific data:

• Conversion changes a string that contains locale-specific format to the internal representation of its value

You usually perform conversion on a locale-specific string to prepare it for storage in a program variable or a database column.

• Formatting changes the internal representation of a value to locale-specific string.

You usually perform formatting of a locale-specific string to prepare the internal representation of a value for display to the end user.

For more information and the syntax of these functions, see the Informix GLS Programmer's Manual.

When you use a locale that supports a multibyte code set, make sure that you define buffers large enough to avoid the generation of partial characters. Possible areas for consideration are as follows:

• When you copy data from one buffer to another
• When you have character data that might undergo code-set conversion

For more detailed examples of partial characters, see Partial Characters in Column Substrings.

When you copy data, you must ensure that the buffers are an adequate size to hold the data. If the destination buffer is not large enough for the multibyte data in the source buffer, the data might be truncated during the copy.

For example, the following ESQL/C code fragment copies the multibyte data A1A2A3B1B2B3 from buf1 to buf2:

char buf1[20], buf2[5];
...
stcopy("A1A2A3B1B2B3", buf1);
...
stcopy(buf1, buf2);

Because buf2 is not large enough to hold the multibyte string, the copy truncates the string to A1A2A3B1B2. To prevent this situation, ensure that the multibyte string fits into a buffer before the ESQL/C program performs the copy.

If you have a character buffer to hold character data from a database, you must ensure that this buffer is large enough to accommodate any expansion that might occur if the application uses code-set conversion. If the client and database locales are different and convertible, the application might need to expand this value. For more information, see Performing Code-Set Conversion.

For example, if the fname column is defined as CHAR(8), the following ESQL/C code fragment selects an 8-byte character value into the 10-byte buf1 host variable:

char buf1[10];
...
EXEC SQL select fname into :buf1 from tab1 
                  where cust_num = 29;

You might expect a 10-byte buffer to be adequate to hold an 8-byte character value from the database. However, if the client application expands this value to 12 bytes, the value no longer fits in the buf1 buffer. The fname value is truncated to fit in buf1, possibly creating partial characters if fname contains multibyte characters. For more information, see Partial Characters in Column Substrings.

To avoid this situation, define buffers to handle the maximum character-expansion possible, 4 bytes, in the conversion between your client and database code sets.