INFORMIX
INFORMIX-GLS Programmer's Guide
Chapter 3: Data Formatting
Home Contents Index Master Index New Book

Conversion and Formatting with INFORMIX-GLS

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

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

    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.

Type of Data SQL Data Type ESQL/C Data Type DataBlade API Data Type

Numeric

DECIMAL

* SMALLINT, INTEGER, INT8, FLOAT, SMALLFLOAT

decimal (dec_t)

mi_decimal

Monetary

MONEY

decimal (dec_t)

mi_decimal

Date

DATE

date (long int)

mi_date

Date and time

DATETIME

datetime (dtime_t)

mi_datetime

* Numeric data includes integer, floating-point, and fixed-point numbers. The INFORMIX-GLS conversion and formatting functions represent all these numeric data types with the decimal (or mi_decimal) data type. To convert the decimal (or mi_decimal) representation to an integer or floating-point value, use a library function such as dectoint(), dectolong(), or dectodbl(). For more information on these decimal-conversion functions, see the INFORMIX-ESQL/C Programmer's Manual.

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

Figure 3-1
INFORMIX-GLS Conversion and Formatting Functions

Locale-Specific Data Conversion Formatting

Numeric

ifx_gl_convert_number()

ifx_gl_format_number()

Monetary

ifx_gl_convert_money()

ifx_gl_format_money()

Date

ifx_gl_convert_date()

ifx_gl_format_date()

Date/time

ifx_gl_convert_datetime()

ifx_gl_format_datetime()

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:

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

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

Converting a Locale-Specific String

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

Conversion Function Unconverted Form Converted Form
ESQL/C Data Type DataBlade API Data Type

ifx_gl_convert_number()

Number string

decimal (dec_t)

mi_decimal

ifx_gl_convert_money()

Money string

decimal (dec_t)

mi_decimal

ifx_gl_convert_date()

Date string

date (long int)

mi_date

ifx_gl_convert_datetime()

Date/time string

datetime (dtime_t)

mi_datetime

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:

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:

Formatting a Locale-Specific String

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

Formatting Function Unformatted Form Formatted Form
ESQL/C Internal Representation DataBlade API Internal Representation

ifx_gl_format_number()

decimal (dec_t)

mi_decimal

Number string

ifx_gl_format_money()

decimal (dec_t)

mi_decimal

Money string

ifx_gl_format_date()

date (long int)

mi_date

Date string

ifx_gl_format_datetime()

datetime (dtime_t)

mi_datetime

Date/time string

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 145 to a number string:

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



INFORMIX-GLS Programmer's Guide, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.