Informix Guide to GLS Functionality Informix ESQL/C Features

Informix SQL API products support locale-specific enhancements to the ESQL/C library functions. These ESQL/C library functions fall into the following categories:

• DATE-format functions
• DATETIME-format functions
• Numeric-format functions
• String functions

In addition, this section describes the GLS-related error messages that these ESQL functions might produce.

The ESQL DATE-format functions are as follows:

• rdatestr()
• rstrdate()
• rdefmtdate()
• rfmtdate()

These functions support the following extensions to format era-based DATE values:

• Support for the GL_DATE environment variable
• Support for era-based date formats of the DBDATE environment variable
• Extensions to the date-format strings for ESQL DATE-format functions
• Support for a precedence of date end-user formats

This section describes locale-specific behavior of the ESQL DATE-format functions. For information about the ESQL/C DATE-format functions, see the Informix ESQL/C Programmer's Manual.

The value of the GL_DATE environment variables can affect the results that these ESQL/C DATE-format functions generate. The end-user format that GL_DATE specifies overrides date end-user formats that the client locale defines. For more information, see Precedence for Date End-User Formats.

The ESQL/C DATE-format functions that support the extended era-based date syntax for the DBDATE environment variable are as follows:

• rdatestr()
• rstrdate()

When you set DBDATE to one of the era-based formats, these functions use era-based dates to convert between date strings and internal DATE values. The following ESQL/C example shows a call to the rdatestr() library function:

char str[100];

long jdate;
...
rdatestr(jdate, str);

printf("%s\n", str);

If you set DBDATE to GY2MD/ and CLIENT_LOCALE to the Japanese SJIS locale (ja_jp.sjis), the preceding code fragment prints the following value for the date 08/18/1990:

H02/08/18


Important: Informix products treat any undefined characters in the alphabetic era specification as an error.

If you set DBDATE to a era-based date format (which is specific to a Chinese or Japanese locale), make sure to set the CLIENT_LOCALE environment variable to a locale that supports era-based dates.

The ESQL/C DATE-format functions that support the extended-DATE format strings are as follows:

• rdefmtdate()
• rfmtdate()

The following table shows the extended-format strings that these ESQL/C functions support for use with GLS locales. These extended-format strings format eras with 2-digit year offsets.

The following table shows some sample extended-format strings for era-based dates. These examples assume that the client locale is Japanese SJIS (ja_jp.sjis).

The following ESQL/C code fragment contains a call to the rdefmtdate() library function:

char fmt_str[100];

char in_str[100];

long jdate;
...
rdatestr("10/05/95", &jdate);

stcopy("gyy/mm/dd", fmt_str);

rdefmtdate(&jdate, fmt_str, in_str);

printf("Abbreviated Era Year: %s\n", in_str);



stcopy("eyymmdd", fmt_str);

rdefmtdate(&jdate, fmt_str, in_str);

printf("Full Era Year: %s\n", in_str);

When the CLIENT_LOCALE specifies the Japanese SJIS (ja_jp.sjis) locale, the code fragment displays the following output:

Abbreviated Era Year: H07/10/05

Full Era Year: H021005

The ESQL/C DATE-format functions use the following precedence to determine the end-user format for values in DATE columns:

1. The end-user format that DBDATE specifies (if DBDATE is set)
2. The end-user format that GL_DATE specifies (if GL_DATE is set)
3. The date end-user format that the client locale specifies (if CLIENT_LOCALE is set)
4. The date end-user format from the default locale: %m %d %iY

For more information on the precedence of DBDATE, GL_DATE, and CLIENT_LOCALE, refer to Date and Time Precedence.

Tip: Informix products support DBDATE for compatibility with earlier products. Informix recommends that you use the GL_DATE environment variable for new client applications.

DATETIME-Format Functions

The ESQL DATETIME-format functions are as follows:

• dtcvfmtasc()
• dttofmtasc()

These functions support the following extensions to format era-based DATETIME values:

• Support for the GL_DATETIME environment variable
• Support for era-based date and times of the DBTIME environment variable
• Extensions to the date and time format strings for ESQL DATETIME-format functions
• Support for a precedence of DATETIME end-user formats

This section describes locale-specific behavior of the ESQL/C DATETIME-format functions. For general information about the ESQL/C DATETIME-format functions, see the Informix ESQL/C Programmer's Manual.

The value of the GL_DATETIME environment variables can affect the results that these ESQL DATETIME-format functions generate. The end-user format that GL_DATETIME specifies overrides date and time formats that the client locale defines. For more information, see Precedence for DATETIME End-User Formats.

The ESQL/C DATETIME-format functions support the extended era-based date and time format strings for the DBTIME environment variable. When you set DBTIME to one of the era-based formats, these functions can use era-based dates and times to convert between literal DATETIME strings and internal DATETIME values.

Tip: Informix products support DBTIME for compatibility with earlier products. Informix recommends that you use the GL_DATETIME environment variable for new applications.

If you set DBTIME to a era-based DATETIME format (which is specific to a Chinese or Japanese locale), make sure to set the CLIENT_LOCALE environment variable to a locale that supports era-based dates and times.

The following table shows the extended-format strings that the ESQL/C DATETIME-format functions support.

In addition to the formats in the preceding table, these ESQL/C DATETIME-format functions support the GLS date and time specifiers. For a list of these specifiers, see GL_DATE and GL_DATETIME.

The ESQL/C DATETIME-format functions use the following precedence to determine the end-user format of values in DATETIME columns:

1. The end-user format that DBTIME specifies (if DBTIME is set)
2. The end-user format that GL_DATETIME specifies (if GL_DATETIME is set)
3. The date and time end-user formats that the client locale specifies (if CLIENT_LOCALE is set)
4. The date and time end-user format from the default locale: %iY-%m-%d %H:%M:%S

For more information on the precedence of DBDATE, GL_DATE, and CLIENT_LOCALE, refer to Date and Time Precedence.

The ESQL/C numeric-format functions are as follows:

• rfmtdec()
• rfmtdouble()
• rfmtlong()

These functions support the following extensions to format numeric values:

• Support for multibyte characters in format strings
• Locale-specific formats for numeric values
• Formatting characters for currency symbols
• Support for the DBMONEY environment variable

This section describes locale-specific behavior of the ESQL/C numeric-format functions. For general information about the ESQL/C numeric-format functions, see the Informix ESQL/C Programmer's Manual.

Tip: For a list of errors that these ESQL/C numeric-format functions might return, see GLS-Specific Error Messages.

Support for Multibyte Characters

The ESQL/C numeric-format functions support multibyte characters in their format strings as long as your client locale supports a multibyte code set that defines these characters. However, these ESQL/C functions and routines interpret multibyte characters as literal characters. You cannot use multibyte equivalents of the ASCII formatting characters.

For example, the following ESQL/C code fragment shows a call to the rfmtlong() function with the multibyte character A¹A² in the format string:

stcopy("A1A2***,***", fmtbuf);

rfmtlong(78941, fmtbuf, outbuf);

printf("Formatted value: %s\n", outbuf);

This code fragment generates the following output (if the client code set contains the A¹A² character):

Formatting value: A1A2*78,941

The ESQL/C numeric-format functions require a format string as an argument. This format string determines how the numeric-format function formats the numeric value. A format string consists of a series of formatting characters and the following currency notation.

Regardless of the client locale that you use, you must use the preceding ASCII symbols in the format string to identify where to place the currency symbol, decimal separator, and thousands separator. The numeric-format function uses the following precedence to translate these symbols to their locale-specific equivalents:

1. The symbols that DBMONEY indicates (if DBMONEY is set)

For information about the locale-specific behavior of DBMONEY, see DBMONEY Extensions.

2. The symbols that the appropriate locale category of the client locale (if CLIENT_LOCALE is set) specifies

If the format string contains either a $ or @ formatting character, a numeric-format function assumes that the value is a monetary value and refers to the MONETARY category of the client locale. If these two symbols are not in the format string, a numeric-format function refers to the NUMERIC category of the client locale.

For more information on the use of the $ and @ formatting characters, see Currency-Symbol Formatting. For more information on the MONETARY and NUMERIC locale categories, see Locale Categories.

3. The actual symbol that appears in the format string ($, comma, or period)

In other words, these numeric-format functions replace the dollar sign in the format string with the currency symbol that DBMONEY specifies (if it is set) or with the currency symbol that the client locale specifies (if DBMONEY is not set). The same is true for the decimal separator and thousands separator.

For example, the following ESQL/C code fragment shows a call to the rfmtlong() function:

stcopy("$***,***.&&", fmtbuf);

rfmtlong(78941, fmtbuf, outbuf);

printf("Formatted value: %s\n", outbuf);

In the default, German, and Spanish locales, this code fragment produces the following results for the logical MONEY value of 78941.00 (if DBMONEY is not set).

The ESQL/C numeric-format functions support all formatting characters that the Informix ESQL/C Programmer's Manual describes. In addition, you can use the following formatting characters to indicate the placement of a currency symbol in the formatted output.

For more information, see The MONETARY Category.

You can include both formatting characters in a format string. The locale defines whether the currency symbol appears before or after the monetary value, as follows:

• If the locale formats monetary values with a currency symbol before the value, the locale sets the currency symbol to the precede-currency symbol and sets the succeed-currency symbol to a blank character.
• If the locale formats monetary values with a currency symbol after the value, the locale sets the currency symbol to the succeed-currency symbol and sets the precede-currency symbol to a blank character.

The default locale defines the currency symbol as the precede-currency symbol, which appears as a dollar sign ($). In the default locale, the succeed-currency symbol appears as a blank. In the default, German, and French locales, the numeric-format functions produce the following results for the internal MONEY value of 1.00.

In the preceding table, the character s represents a blank or space, FF is the French currency symbol for French francs, and DM is the German currency symbol for deutsche marks.

The DBMONEY environment variable can also set the precede-currency symbol and the succeed-currency symbol. The syntax diagram in DBMONEY refers to these symbols as front and back, respectively. If set, DBMONEY takes precedence over the symbols that the locale defines.

You can specify the currency symbol and decimal-separator symbol with the DBMONEY environment variable. These settings override any currency notation that the client locale specifies.

You can use multibyte characters for these symbols if your client code set supports them. For example, the following table shows how multibyte characters appear in sample output.

In the preceding table, the character s represents a blank or space.

The following ESQL/C string functions support locale-specific shifted characters:

• rdownshift()
• rupshift()

These string functions use the information in the CTYPE category of the client locale to determine the shifted code points. If the client locale specifies a multibyte code set, these functions can operate on multibyte strings.

Important: With multibyte character strings, a shifted string might occupy more memory after a shift operation than before. You must ensure that the buffer you pass to these ESQL/C shift functions is large enough to accommodate this expansion.

GLS-Specific Error Messages

The following ESQL/C functions might generate GLS-specific error messages:

• DATE-format functions
• DATETIME-format functions
• Numeric-format functions

For more information on GLS-specific error messages, use the finderr utility on UNIX, the Find Error utility on Windows NT, or the Informix Error Messages in Answers OnLine.