Numeric-Format Functions

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 IBM Informix: ESQL/C Programmer's Manual.

Support for Multibyte Characters

The ESQL/C numeric-format functions support multibyte characters in their format strings if your client locale supports a multibyte code set that defines these characters. These ESQL/C functions and routines, however, 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

Locale-Specific Numeric Formatting

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)

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

Currency-Symbol Formatting

The ESQL/C numeric-format functions support all formatting characters that the IBM 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 front currency symbol and sets the back 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 back currency symbol and sets the front currency symbol to a blank character.

The default locale defines the currency symbol as the front currency symbol, which appears as a dollar sign ($). In the default locale, the back currency symbol appears as a blank space. In the default, British, 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, € is the currency symbol for Euros, and £ is the British currency symbol for pounds Sterling.

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. The DBMONEY setting, if one is specified, takes precedence over the symbols that the MONETARY category of the locale defines.

DBMONEY Extensions

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 examples of output.

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