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

The esqlmf Filter

 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.

However, the capabilities of your C compiler 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:

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 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:

    A component of a multibyte character might be indistinguishable from certain single-byte characters such as percent (%), comma, backslash (\), and double quote ("). If such characters exist in a quoted string, the C compiler might interpret them as C-language tokens, which can cause compilation errors or even lost characters.

    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 A1A2A3 has an octal representation of \160\042\244, and appears in the stcopy() call.

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

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

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 A3 byte. If the compiler ignores the eighth bit, it incorrectly interprets A3 (octal \244) as octal \044.

Invoking the ESQL/C Filter

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

Figure 8-1
Creating an ESQL/C Executable Program from a Non-ASCII Source Program

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:

    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 Value 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 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:

    1. Converts the embedded-language statements (source.ec) to C-language source code (source.c) with the ESQL/C preprocessor

    2. 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_).

    3. Compiles the filtered C source file (source.c) with the C compiler to create an object file (source.o)

    4. 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, 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. For more information on CC8BITLEVEL, see page 2-5.



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