Using Non-ASCII Characters in ESQL/C Source Files

Home | Previous Page | Next Page IBM Informix ESQL/C Features (ESQL/C) > Handling Non-ASCII Characters >

Using Non-ASCII Characters in ESQL/C Source Files

The ESQL/C processor, esql, accepts C source programs that are written in the client code set (the code set of the client locale). The ESQL/C preprocessor, esqlc, can accept non-ASCII characters (8-bit and multibyte) in the ESQL/C source code as long as the client code set defines them.

The capabilities of your C compiler, however, might limit your ability to use non-ASCII characters within an ESQL/C source file. If the C compiler does not fully support non-ASCII characters, it might not successfully compile an ESQL/C program that contains these characters. To provide support for common non-ASCII limitations of C compilers, ESQL/C provides an ESQL/C filter that is called esqlmf.

This section provides the following information about the ESQL/C filter:

How the ESQL/C filter processes non-ASCII characters
How you invoke the ESQL/C filter

Filtering Non-ASCII Characters

As part of the compilation process of an ESQL/C source program, the ESQL/C processor calls the C compiler. When you develop ESQL/C source code that contains non-ASCII characters, the way that the C compiler handles such characters can affect the success of the compilation process. In particular, the following situations might affect compilation of your ESQL/C program:

Multibyte characters might contain C-language tokens.
A component of a multibyte character might be indistinguishable from some single-byte characters such as percent ( % ), comma ( , ), backslash ( \ ), and double quote ( " ) characters. If such characters are included in a quoted string, the C compiler might interpret them as C-language tokens, which can cause compilation errors or even lost characters.
The C compiler might not be 8-bit clean.
If a code set contains non-ASCII characters (with code values that are greater than 127), the C compiler must be 8-bit clean to interpret the characters. To be 8-bit clean, a compiler must read the eighth bit as part of the code value; it must not ignore or put its own interpretation on the meaning of this eighth bit.

To filter a non-ASCII character, the ESQL/C filter converts each byte of the character to its octal equivalent. For example, suppose the multibyte character A¹A²A³ has an octal representation of \160\042\244 and appears in the stcopy() call.

stcopy("A¹A²A³", dest);

After esqlmf filters the ESQL/C source file, the C compiler sees this line as follows:

stcopy("\160\042\244", dest); /* correct interpretation */

To handle the C-language-token situation, the filter prevents the C compiler from interpreting the A² byte (octal \042) as an ASCII double quote and incorrectly parsing the line as follows:

stcopy("A¹"A³, dest); /* incorrect interpretation of A² */

The C compiler would generate an error for the preceding line because the line has terminated the string argument incorrectly. The esqlmf utility also handles the 8-bit-clean situation because it prevents the C compiler from ignoring the eighth bit of the A³ byte. If the compiler ignores the eighth bit, it incorrectly interprets A³ (octal \244) as octal \044.

Invoking the ESQL/C Filter

Figure 5 shows how an ESQL/C program that contains non-ASCII characters becomes an executable program.

Figure 5. Creating an ESQL/C Executable Program from a Non-ASCII Source Program

begin figure description - This figure is described in the surrounding text. - end figure description

The esql command can automatically call the ESQL/C filter, esqlmf, to process non-ASCII characters. When you set the following environment variables, you tell esql how to invoke esqlmf:

The ESQLMF environment variable indicates whether esql automatically calls the ESQL/C filter.
When you set ESQLMF to 1, esql automatically calls esqlmf after the ESQL/C preprocessor and before the C compiler.
The CC8BITLEVEL environment variable indicates the non-ASCII characters in the ESQL/C source file that esqlmf filters.
Set CC8BITLEVEL to indicate the ability of your C compiler to process non-ASCII characters.

How esqlmf filters an ESQL/C source file depends on the value of the CC8BITLEVEL environment variable. For each value of CC8BITLEVEL, the following table shows the esqlmf command that the ESQL/C processor invokes on a ESQL/C source file.

CC8BITLEVEL	esqlmf Action
0	Converts all non-ASCII characters, in literal strings and comments, to octal constants.
1	Converts non-ASCII characters in literal strings, but not in comments, to octal constants.
2	Converts non-ASCII characters in literal strings to octal constants to ensure that all the bytes in the non-ASCII characters have the eighth bit set.
3	Does not invoke esqlmf.

Important:

To invoke the esqlmf commands that CC8BITLEVEL can specify, you must set the ESQLMF environment variable to 1.

When you set CC8BITLEVEL to 0, 1, or 2, the ESQL/C processor performs the following steps:

Converts the embedded-language statements (source.ec ) to C-language source code (source.c ) with the ESQL/C preprocessor
Filters non-ASCII characters in the preprocessed file (source.c) with the ESQL/C filter, esqlmf (if the ESQLMF environment variable is 1)
Before esqlmf begins filtering, it creates a copy of the C source file (source.c) that has the .c_ file extension (source.c_).
Compiles the filtered C source file (source.c) with the C compiler to create an object file (source.o )
Links the object file with the ESQL/C libraries and your own libraries to create an executable program

When you set CC8BITLEVEL to 3, the ESQL/C processor omits step 2 in the preceding list.

If you do not set CC8BITLEVEL, then esql converts non-ASCII characters in literal strings and comments. You can modify the value of CC8BITLEVEL to reflect the capabilities of your C compiler.