INFORMIX-GLS Programmer's Manual Data Formatting

The INFORMIX-GLS library provides functions that allow you to perform the following tasks on locale-specific data:

• Conversion changes a string that contains locale-specific formats to the internal representation of its value.

You usually perform conversion on a locale-specific string to prepare it for storage in a program variable or a database column.

• Formatting changes the internal representation of a value to a locale-specific string.

You usually perform formatting of a locale-specific string to prepare the internal representation of a value for display or printing to the end user.

The internal representation of a value is one that can be stored directly in a database column. The following table lists the SQL data types for the internal representations along with the ESQL/C and DataBlade API data types that hold these internal representations.

Figure 3-1 lists the functions that the INFORMIX-GLS library provides for the conversion and formatting of locale-specific data.

The conversion and formatting functions in Figure 3-1 accept a format string to indicate how to handle a locale-specific string. A format string is composed of white spaces, ordinary characters, and one or more formatting directives. A formatting directive consists of the following characters:

• A percent symbol (%)
• Optional format modifiers
• A type-specifier character, which determines the type of conversion

For example, the ifx_gl_convert_number() function supports the following formatting directive:

%0x

In the preceding formatting directive, 0 is a format modifier that indicates padding, and x is a type specifier that indicates the hexadecimal format of a number.

The INFORMIX-GLS conversion functions scan the incoming locale-specific string to create a corresponding internal representation, as follows.

The formatting directives in the format string tell the conversion functions what conversions to perform on the locale-specific string. To process a formatting directive, a conversion function consults the appropriate category in the current locale to obtain any locale-specific formats and then converts the resulting value to an internal representation that can be stored in a database.

For example, if the current locale is the default locale, the following DataBlade API call to the ifx_gl_convert_number() function converts the number string "1,450" to its hexadecimal equivalent in an mi_decimal value:

mi_decimal num_val;

...
if ( ifx_gl_convert_number(&num_val, "1,450","%0x") != 0 )

	/* handle error */

In the current locale, the thousands separator is defined as the comma (,) symbol. Therefore, the ifx_gl_convert_number() function must correctly interpret the comma in the number string so that it can convert this string to the hexadecimal equivalent of the value 1450 and store the result in the mi_decimal value, num_val.

If the current locale is French (fr_fr), the thousands separator is a space. Therefore, the following call to ifx_gl_convert_number() must interpret a space as the thousands separator to convert the French number string ("1 450") successfully to its mi_decimal equivalent:

mi_decimal *num_val;

...
if ( ifx_gl_convert_number(num_val, "1 450","%0x") != 0 )

	/* handle error */

The INFORMIX-GLS formatting functions create a locale-specific string from an incoming internal representation of a value, as follows.

The formatting directives in the format string tell the formatting functions how to format the internal representation of a value into a locale-specific string. To process a formatting directive, a formatting function consults the appropriate category in the current locale to obtain any locale-specific formats and then formats the locale-specific string with this information.

For example, the following DataBlade API call to the function ifx_gl_format_number() converts the hexadecimal representation of the number 1450 to a number string:

mi_decimal num_val;
char num_str[BUFSIZE];
...
if ( ifx_gl_format_number(&num_str, BUFSIZE, num_val,"%0x") != 0 )
/* handle error */

If the current locale is the default locale, num_str contains the number string "1,450" upon successful completion of this call to ifx_gl_format_number(). The function correctly formats the comma (,) as the thousands separator in the number string. If the current locale is French (fr_fr), the thousands separator is a space. Therefore, the preceding call to the function ifx_gl_convert_number() would format the French number string as "1 450".