The ifx_gl_convert_money() function

The ifx_gl_convert_money() function converts a money string to its internal money representation.

Syntax

#include <ifxgls.h>
...
int ifx_gl_convert_money(money, monstr, format)
       mi_money *money;
       char *monstr;
       char *format;

money: A pointer to the variable that holds the internal money representation that ifx_gl_convert_money() creates from the monstr money string.
monstr: A pointer to the first character of the money string that the function converts to its internal money representation.
format: A pointer to the format string that determines how to interpret the monstr money string. For more information, see Format string


Valid in client application	Valid in DataBlade® UDR
Yes	Yes

Usage

The ifx_gl_convert_money() function converts the money string that monstr references to its internal money representation, which the function stores in the money argument. The function uses the format that the format string specifies to scan the monstr money string.

The money argument is a pointer to a decimal (dec_t) value.

The money argument is a pointer to an mi_money value.

Format string

If format is NULL, the ifx_gl_convert_money() function determines the format of the monstr money string that it scans from the environment, as follows:

If the DBMONEY environment variable is set, the function scans monstr, as DBMONEY specifies.
Otherwise, the function uses the formats in the LC_MONETARY category of the current GLS locale to scan the money value.

If format is not NULL, it must point to a string that follows the rules that this section describes. To convert the monstr money string, the function ifx_gl_convert_money() compares each character in monstr with the format string. It takes the following actions for each possible character that it finds in format.


Contents of format string	Conversion action taken
One or more white space characters	The function skips over the corresponding number of white space characters in the `monstr` money string (unless the formatting directive begins with the minus-sign modifier), up to the first character that is not white space or until no more characters can be scanned. White space characters are characters that the blank class of the LC_CTYPE category in the current locale defines.
A valid formatting directive	The function performs the specified conversion on the monetary element in the `monstr` money string. It replaces the formatting directive with an internal representation of the monetary element for conversion to the `money` value. Only one formatting directive is allowed in the `format` string.
Ordinary characters	The function must find the same ordinary character in the `monstr` money string. Any mismatch generates an error. The differing and subsequent characters in `monstr` remain unscanned. You cannot include white space characters as ordinary characters.

The formatting directive consists of the following sequence:

%[flags][maximum_width]type_specifier


Argument	See
`flags`	Field width
`maximum_width`	Field width
`type_specifier`	Valid type specifiers

Tip: In the preceding format sequence, the square brackets indicate that the enclosed portion of the format is optional.

Valid type specifiers

The type specifier is a letter or letters within a formatting directive that identify a format for the ifx_gl_convert_money() function to expect when it scans a monetary element of a monstr string. The LC_MONETARY locale-file category of the current locale might define these monetary formats. The ifx_gl_convert_money() function supports the following formatting directives to represent a monetary element.

%i: Matches the international monetary format (which uses the int_curr_symbol subcategory of the LC_MONETARY category in the current locale) for the monstr argument. For example, in the default locale, the international monetary format for 1,234.56 is the USD 1,234.56 string. Declare the corresponding money value as (double *).
%n: Matches the national currency format (which uses the currency_symbol of the LC_MONETARY category in the current locale) for the monstr argument. For example, in the default locale, the national monetary format for 1,234.56 is the $1,234.56 string. Declare the corresponding money value as (double *).
%%: Matches a % character. No corresponding argument is needed.

If a formatting directive does not correspond to any of the preceding directives, the behavior of the conversion is undefined.

Field width

You can specify an optional field width in a formatting directive. This information follows the initial percent symbol (%) of the formatting directive and has the following format:

['][-][maximum_width]

[']

Indicates grouping rules.

If the specification begins with a single quotation mark ('), the field is expected to follow the grouping rules in the LC_MONETARY category of the current locale.

[-]

Indicates field justification.

If the specification begins with a minus sign (-), the function expects the first character of the monstr money string to be the first character of the value to be converted. The function does not skip white space characters in monstr but reports them as an error.

If you omit the minus sign (-), the function assumes that the monstr string is right-aligned, and it skips any initial white space characters.

maximum_width

A decimal value that specifies the maximum number of characters to read from the monstr money string.

Locale information

The LC_MONETARY category of the current locale affects the behavior of this function because it provides the locale-specific information for the scan of the monstr money string. For more information, see The LC_MONETARY locale-file category.

Return values

0: The function was successful.
-1: The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to the following value.

IFX_GL_INVALIDFMT: The format string is invalid.