Informix Guide to GLS Functionality Informix ESQL/C Features

The ESQL/C processors obtain the code set for use in ESQL/C source files from the client locale. Within an ESQL/C source file, you can use non-ASCII characters for the following objects:

• ESQL/C host variable and indicator variable names

For example, in an ESQL/C program, the following use of multibyte characters is valid:

char A¹A²[20], B¹B²[20];

...

EXEC SQL select col1, col2 into :A¹A² :B¹B²;

For more information on ESQL/C host variables, see Using Non-ASCII Characters in Host Variables.

• ESQL/C comments
• Names of SQL identifiers such as databases, tables, columns, views, constraints, prepared statements, and cursors

For more information, see Naming Database Objects.

• Literal strings

For example, in an ESQL/C program, the following use of multibyte characters is valid:

EXEC SQL insert into tbl1 (nchr1) values 'A¹A²B¹B²';

• Filenames and pathnames, if your operating system supports multibyte characters in filenames and pathnames

Tip: Some C-language compilers support multibyte characters in literals or comments only. For such compilers, you might need to set the ESQLMF and CC8BITLEVEL environment variables so that the ESQL/C processor calls a multibyte filter. For more information, see Generating Non-ASCII Filenames.

To use non-ASCII characters in your ESQL/C source file, the client locale must support them. For information about the use of non-ASCII characters, see Non-ASCII Characters in Identifiers.

ESQL/C allows the use of non-ASCII characters in host variables when the following conditions are true:

• The client locale supports a code set with the non-ASCII characters that the host-variable name contains.

You must set the client locale correctly before you preprocess and compile an ESQL/C program. For more information, see Setting a GLS Locale.

• Your C compiler supports compilation of the same non-ASCII characters as the source code.

You must ensure that the C compiler supports use of non-ASCII characters in C source code. For information about how to indicate the support that your C compiler provides for non-ASCII characters, see Invoking the ESQL/C Filter.

ESQL/C applications can also support non-ASCII characters in comments and SQL identifiers. For more information, see Non-ASCII Characters in Identifiers.

The following code fragment declares an integer host-variable that contains a non-ASCII character in the host-variable name and then selects a serial value into this variable:

/*

	This code fragment declares an integer host variable

	"hôte_ent", which contains a non-ASCII character in the

	name, and selects a serial value (code number in the

	"numéro" column of the "abonnés" table) into it.

*/



EXEC SQL BEGIN DECLARE SECTION;

	int hôte_ent;
...

	

	
EXEC SQL END DECLARE SECTION;
...




EXEC SQL select numéro into :hôte_ent from abonnés

	where nom = 'Ötker';

If the client locale supports the non-ASCII characters, you can use these characters to define indicator variables, as the following example shows:

EXEC SQL BEGIN DECLARE SECTION;

	char      hôtevar[30];

	short    ind_de_hôtevar;

EXEC SQL END DECLARE SECTION;

You can then access indicator variables with these non-ASCII names, as the following example shows:

:hôtevar INDICATOR :hôtevarind



:hôtevar	:hôtevar	ind



$hôtevar		$hôtevar	ind

When an ESQL/C source file is processed, the ESQL/C processor generates a corresponding intermediate file for the source file. If you use non-ASCII characters (8-bit and multibyte character) in these source filenames, the following restrictions affect the ability of the ESQL/C processor to generate filenames that contain non-ASCII characters:

• The ESQL/C processor must know whether the operating system is 8-bit clean.

For more information, see GLS8BITFSYS.

• The code set of the client locale (the client code set) must support the non-ASCII characters that are used in the ESQL/C source filename.
• Your C compiler supports the non-ASCII characters that the filename of the ESQL/C source file uses.

If your C compiler does not support non-ASCII characters, you can use the CC8BITLEVEL environment variable as a workaround when your source file contains multibyte characters. For more information, see Generating Non-ASCII Filenames.

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:

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

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

• 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("A1A2A3", 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("A1"A3, dest); /* incorrect interpretation of A2 */

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.

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

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

• 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.

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.