INFORMIX-GLS Programmer's Guide

INFORMIX-GLS Programmer's Guide
Chapter 4: INFORMIX-GLS Function Descriptions

Home Contents Index Master Index New Book

ifx_gl_case_conv_outbuflen()

The ifx_gl_case_conv_outbuflen() function calculates an approximation of the number of bytes required to store a case-converted multibyte character.

Syntax

#include <ifxgls.h>

...
int ifx_gl_case_conv_outbuflen(src_mbs_bytes)

		int src_mbs_bytes; 


src_mbs_bytes
is the integer number of bytes in the buffer of multibyte characters to be case converted.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_case_conv_outbuflen() function returns one of the following values:

Exactly the number of bytes that a buffer of case-equivalent multibyte characters will require
A close over-approximation of this number of bytes

This buffer can contain one or more multibyte characters. This function applies to both uppercase and lowercase conversions.

Use this function to determine whether or not case conversion of multibyte characters can be performed in place. If the value returned by this function is not equal to src_mbs_bytes, case conversion of multibyte characters cannot be performed in place. You must allocate a separate multibyte destination buffer. However, if the value returned by this function is exactly equal to src_mbs_bytes, multibyte case conversion can be performed in place.

Tip: This function does not apply to wide-character case conversions.

Return Values

>0
The number of bytes required to store multibyte characters of length src_mbs_bytes after they have been converted to either lowercase or uppercase characters.

0
The function was not successful.

Errors

None

ifx_gl_conv_needed()

The ifx_gl_conv_needed() function determines whether code-set conversion between two code sets is required.

Syntax

#include <ifxgls.h>

...
int ifx_gl_conv_needed(dst_codeset, src_codeset)

		char *dst_codeset;

		char *src_codeset; 


dst_codeset
is a pointer to the name of the destination (target) code set.

src_codeset
is a pointer to the name of the source code set.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_conv_needed() function determines whether characters encoded in src_codeset require conversion to dst_codeset. It is not enough to simply compare the names of the code sets because several names can identify the same code set. For example, 8859-1, 819, and Latin-1 refer to the same code set.

The code sets, src_codeset and dst_codeset, can be any of the following:

Locale names
Code-set names
The IFX_GL_PROC_CS macro

For more information, see "Specifying Code-Set Names".

Return Values

0
Code-set conversion is not needed between the code sets that dst_codeset and src_codeset specify.

1
Code-set conversion is needed between the code sets that dst_codeset and src_codeset specify.

-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, the function sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_EINVAL`	The src_codeset string is not a valid locale specification or code-set name, or the code-set name could not be mapped to a code-set number.
`IFX_GL_EBADF`	Function cannot find the code-set registry.
`IFX_GL_BADFILEFORM`	Bad format found in the code-set registry.

ifx_gl_convert_date()

The ifx_gl_convert_date() function converts a date string to its internal date representation.

Syntax

#include <ifxgls.h>

...
int ifx_gl_convert_date(date, datestr, format)

		mi_date *date;

		char *datestr;

		char *format; 


date
is a pointer to the variable that holds the internal date representation that ifx_gl_convert_date() creates from the datestr date string.

datestr

is a pointer to the first character of the date string that the function converts to its internal date representation.

format
is a pointer to the format string that determines how to interpret the datestr date string. For more information, see "Format String". 







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_convert_date() function converts the date string that datestr references to its internal date representation, which the function stores in the date argument. The function uses the format that the format string specifies to scan the datestr date string.

E/C

The date argument is a pointer to a date (4-byte int) value.

DB API

The date argument is a pointer to an mi_date value.

Format String

If format is NULL, the ifx_gl_convert_date() function determines the format of the datestr date string that it scans from the environment, as follows:

1. If the DBDATE environment variable is set, the function scans datestr according to the order of the format elements in DBDATE.

2. If the GL_DATE environment variable is set, the function scans datestr according to the specification of GL_DATE.

3. Otherwise, the function obtains the format from the d_fmt subcategory of the LC_TIME category in the current GLS locale file.

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

(1 of 2)
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 datestr date 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 those that the blank class of the `LC_CTYPE` category in the current locale defines. To execute a series of formatting directives composed of %n, %t, white-space characters, or any combination, the function scans up to the first character that is not white space (which remains unscanned) or until no more characters can be scanned.
A valid formatting directive	The function performs the specified conversion on the date element in the datestr date string. It replaces the formatting directive with an internal representation of the date element for conversion to the date value. There must be white-space or other nonalphanumeric characters between any two formatting directives.
Ordinary characters	The function must find the same ordinary character in the datestr date string. Any mismatch generates an error. The differing and subsequent characters in datestr remain unscanned. You cannot include white-space characters as ordinary characters.

The formatting directive consists of the following sequence:

%[modifiers][flags][maximum_width][.minimum_width]type_specifier 


modifiers
For more information, see "Modified Formatting Directives".

flags
For more information, see "Field Width".

maximum_width
For more information, see "Field Width".

minimum_width
For more information, see "Field Width".

type_specifier
For more information, see "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 identifies a format for the ifx_gl_convert_date() function to expect when it scans a date element of a datestr string. These date formats are those that the LC_TIME locale-file category of the current locale might define. The ifx_gl_convert_date() function supports the following formatting directives to represent a date element.

(1 of 2)

Formatting Directive Description
%a
Matches the day of the week. You can specify either the abbreviated or full weekday names, which the abday and day subcategories of LC_TIME define, respectively.

%A
Is the same as %a.

%b
Matches the month. You can specify either the abbreviated or full month names, which the abmon and mon subcategories of LC_TIME define, respectively.

%B
Is the same as %b.

%C
Matches the century number [0,99]. Leading zeros are permitted but not required. If %C is used without %y, it is ignored.

%d
Matches the day of the month as a decimal number [01,31]. Leading zeros are permitted but not required.

%e
Is the same as %d.

%h
Is the same as %b.

%j
Matches the day of the year as a decimal number [001,366]. Leading zeros are permitted but not required.

%m
Matches the month as a decimal number [01,12]. Leading zeros are permitted but not required.

%n
Matches any horizontal white space that the blank class of the LC_CTYPE category defines.

%t
Matches any vertical white space that the space class of the LC_CTYPE category defines.

%u
Matches the weekday as a decimal number [1,7], with 0 representing Sunday. Leading zeros are permitted but not required.

%w
Matches the weekday as a decimal number [0,6], with 0 representing Sunday. Leading zeros are permitted but not required.

%x
Indicates use of the format that the d_fmt subcategory of LC_TIME
defines.

%y
Matches the year within century as a decimal number [00,99].
Leading zeros are permitted but not required. If %y is used without %C and the month and day of month are part of the datestr string, the function determines the century from the DBCENTURY environment variable.

%Y
Matches the year, including the century, as a decimal number [0000,9999].

%%
Matches the % symbol.

Tip: The ifx_gl_convert_date() function ignores case when it matches items such as month or weekday names.

If the format string contains redundant formatting directives, directives that are closer to the end of the format string take precedence over those closer to the beginning of the format string.

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

Modified Formatting Directives

You can modify some formatting directives with format modifiers, which follow the percent symbol (%), to indicate use of an alternative format that the LC_TIME locale-file category of the current locale might define. The ifx_gl_convert_date() function supports the following format modifiers.

Format Modifier Purpose LC_TIME Subcategory
E
Use formats that include the era-based dates.
era, era_d_fmt

O
Use alternative locale-specific digits in dates.
alt_digits

The ifx_gl_convert_date() function needs the era base, era offset, day, and month to determine the year from era information. The function uses a default era offset of 1 if you specify era base, day, and month but not era offset.

The ifx_gl_convert_date() function also supports the i modifier in the following formatting directives to support formats that are backward compatible with earlier Informix date and time formatting.

Formatting Directive Description
%iy
Indicates use of the Informix DBDATE format Y2. Both 98 and 1998 are interpreted as 1998 (or whichever century is appropriate according to DBCENTURY).

%iY
Indicates use of the Informix DBDATE format Y4. Both 98 and 1998 are interpreted as 1998 (or whichever century is appropriate according to DBCENTURY).

Field Width

You can modify some formatting directives with the following modifiers to indicate use of an alternative format that the LC_TIME locale-file category of the current locale might define:

[- | 0][maximum_width][.minimum_width] 


[ - | 0 ]
indicates field justification. 
If the specification begins with a minus sign (-), the function assumes that the field is left justified. In this case, the value that is being read must start with a digit and can be trailed with spaces. The field can be preceded with leading spaces unless the first character is a zero. If the specification begins with a zero (0), the function assumes that the field is right justified. Any padding to the left must use zeros. Otherwise, the function assumes that the datestr string is right justified. 

maximum-width
is a decimal number that indicates an optional maximum field width.

minimum-width
indicates an optional minimum field width. The minimum field width has the format of a period (.) followed by a decimal number. The minimum_width decimal number 
represents the minimum number of characters to read. If the function reads fewer than minimum_width characters, it generates an error (unless you specified left justification). When you specify left justification, the function skips any trailing white space to read the required number of characters.

Locale Information

The LC_TIME category of the current locale affects the behavior of this function because it provides the locale-specific information for the scan of the datestr date string. For more information, see "The LC_TIME 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 one of the following values.


`IFX_GL_E2BIG`	Operation would overflow buffer.
`IFX_GL_EBADF`	A formatting directive is invalid.
`IFX_GL_INVALIDFMT`	The format string is invalid.
`IFX_GL_EDAYRANGE`	Day number is out of bounds.
`IFX_GL_EWKDAYRANGE`	Weekday number is out of bounds.
`IFX_GL_EYDAYRANGE`	Year day number is out of bounds.
`IFX_GL_EMONTHRANGE`	Month number is out of bounds.
`IFX_GL_EYEARRANGE`	Year number is out of bounds.
`IFX_GL_EERAOFFRANGE`	Era offset is out of bounds.
`IFX_GL_BADDAY`	Month (as a number) could not be scanned.
`IFX_GL_BADWKDAY`	Weekday (as a number) could not be scanned.
`IFX_GL_BADYDAY`	Day of year (as a number) could not be scanned.
`IFX_GL_BADMONTH`	Month could not be scanned.
`IFX_GL_BADYEAR`	Year could not be scanned.
`IFX_GL_BADERANAME`	Invalid era name.
`IFX_GL_BADERAOFFSET`	Invalid era offset.
`IFX_GL_BADFMTMOD`	Invalid format modifier.
`IFX_GL_BADFMTWP`	Invalid width.
`IFX_GL_BADINPUT`	Input string does not match format string.
`IFX_GL_NOPOINT`	Missing decimal point in input string.
`IFX_GL_BADMONTHSTR`	Month string could not be scanned.
`IFX_GL_BADERASPEC`	Could not load era from locale.

ifx_gl_convert_datetime()

The ifx_gl_convert_datetime() function converts a date/time string to its internal date/time representation.

Syntax

#include <ifxgls.h>

...
int ifx_gl_convert_datetime(datetime, datetimestr, format)

		mi_datetime *datetime;

		char *datetimestr;

		char *format; 


datetime
is a pointer to the variable that holds the internal date/time representation that ifx_gl_convert_datetime() creates from the datetimestr date/time string.

datetimestr

is a pointer to the first character of the date/time string that the function converts to its internal date/time representation.

format
is a pointer to the format string that determines how to interpret the datetimestr date/time string. For more information, see "Format String". 







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_convert_datetime() function converts the date/time string that datetimestr references to its internal date/time representation, which the function stores in the datetime argument. The function uses the format that the format string specifies to scan the datetimestr date/time string.

E/C

The datetime argument is a pointer to a datetime (dtime_t) value.

DB API

The datetime argument is a pointer to an mi_datetime value.

Format String

If format is NULL, the ifx_gl_convert_datetime() function determines the format of the datetimestr date/time string that it scans from the environment, as follows:

1. If the DBTIME environment variable is set, the function scans datetimestr according to DBTIME.

2. If the GL_DATETIME environment variable is set, the function scans datetimestr according to the specification of GL_DATETIME.

3. Otherwise, the function obtains the format from the value of the d_t_fmt subcategory of the LC_TIME category in the current GLS locale.

If format is not NULL, it must point to a string that follows the rules that this section describes. To convert the datetimestr date/time string, ifx_gl_convert_datetime() compares each character in datetimestr with the format string. It takes the following actions for each possible kind of character that it finds in format.

(1 of 2)
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 datetimestr date/time 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 those that the blank class of the `LC_CTYPE` category in the current locale defines. To execute a series of formatting directives composed of %n, %t, white-space characters, or any combination, the function scans up to the first character that is not white space (which remains unscanned) or until no more characters can be scanned.
A valid formatting directive	The function performs the specified conversion on the date or time element in the datetimestr date/time string. It replaces the formatting directive with an internal representation of the date or time element for conversion to the datetime value. There must be white-space or other nonalphanumeric characters between any two formatting directives.
Ordinary characters	The function must find the same ordinary character in the datetimestr date/time string. Any mismatch generates an error. The differing and subsequent characters in datetimestr remain unscanned. You cannot include white-space characters as ordinary characters.

The formatting directive consists of the following sequence:

%[modifiers][flags][maximum_width][.minimum_width]type_specifier 


modifiers
For more information, see "Modified Formatting Directives".

flags
For more information, see "Field Width".

maximum_width
For more information, see "Field Width".

minimum_width
For more information, see "Field Width".

type_specifier
For more information, see "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

Tip: The ifx_gl_convert_datetime() function ignores case when it matches items such as month or weekday names.

If the format string contains redundant formatting directives, directives that are closer to the end of the format string take precedence over those closer to the beginning of the format string.

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

Modified Formatting Directives

You can modify some formatting directives with format modifiers, which follow the percent symbol (%), to indicate use of an alternative format that the LC_TIME locale-file category of the current locale might define. The ifx_gl_convert_datetime() function supports the following format modifiers.

Format Modifier Purpose LC_TIME Subcategory
E
Use formats that include the era-based dates and times.
era, era_d_fmt, era_t_fmt, era_d_t_fmt

O
Use alternative locale-specific digits in dates and times.
alt_digits

The ifx_gl_convert_datetime() function needs the era base, era offset, day, and month to determine the year from era information. The function uses a default era offset of 1 if you specify era base, day, and month but not era offset.

The ifx_gl_convert_datetime() function also supports the i modifier in the following formatting directives to support formats that are backward compatible with earlier Informix date and time formatting.

Formatting Directive Description
%iF[n]
Indicates use of the Informix DBTIME format %F. An optional precision specification, n, can follow F. This n value must be between 1 and 5.

%iy
Indicates use of the Informix DBDATE format Y2. Both 98 and 1998 are interpreted as 1998 (or whichever century is appropriate according to DBCENTURY).

%iY
Indicates use of the Informix DBDATE format Y4. Both 98 and 1998 are interpreted as 1998 (or whichever century is appropriate according to DBCENTURY).

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:

[- | 0][maximum_width][.minimum_width] 


[ - | 0 ]
indicates field justification.
If the specification begins with a minus sign (-), the function assumes that the field is left justified. In this case, the value being read must start with a digit and can have trailing spaces. The field can be preceded with leading spaces unless the first character in the field is a zero (0). 
If the first character is a zero (0), the field is assumed to be right justified. Any padding to the left must use zeros.
Otherwise, the function assumes that the datetimestr string is right justified. 

maximum_width
is a decimal value that specifies the maximum number of characters to read from the datetimestr date/time string.

minimum_width
indicates an optional minimum field width. The minimum field width has the format of a period (.) followed by a decimal number. The minimum_width decimal number represents the minimum number of characters to read. If the function reads fewer than minimum_width characters, it generates an error (unless you specified left justification). When you specify left justification, the function skips any trailing white space to read the required number of characters.

Tip: The ifx_gl_convert_datetime() function ignores any field-width specification for any nonnumeric or compound formats.

For the %Fn format, n overrides the minimum field width. If n is greater than the maximum field width, the maximum field width is increased to n. If n is not between 1 and 5, an error is returned.

Locale Information

The LC_TIME category of the current locale affects the behavior of this function because it provides the locale-specific information for the scan of the datetimestr date/time string. For more information, see "The LC_TIME 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 one of the following values.


`IFX_GL_EBADF`	A formatting directive is invalid.
`IFX_GL_EFRACRANGE`	Fraction of second is out of bounds.
`IFX_GL_ESECONDRANGE`	Second is out of bounds.
`IFX_GL_EMINUTERANGE`	Minute is out of bounds.
`IFX_GL_EHOURRANGE`	Hour is out of bounds.
`IFX_GL_EDAYRANGE`	Day number is out of bounds.
`IFX_GL_EWKDAYRANGE`	Weekday number is out of bounds.
`IFX_GL_EYDAYRANGE`	Year day number is out of bounds.
`IFX_GL_EMONTHRANGE`	Month number is out of bounds.
`IFX_GL_EYEARRANGE`	Year number is out of bounds.
`IFX_GL_EERAOFFRANGE`	Era offset is out of bounds.
`IFX_GL_BADFRAC`	Fraction could not be scanned.
`IFX_GL_BADSECOND`	Second could not be scanned.
`IFX_GL_BADMINUTE`	Minute could not be scanned.
`IFX_GL_BADHOUR`	Hour could not be scanned.
`IFX_GL_BADDAY`	Month (as a number) could not be scanned.
`IFX_GL_BADWKDAY`	Weekday (as a number) could not be scanned.
`IFX_GL_BADYDAY`	Day of year (as a number) could not be scanned.
`IFX_GL_BADMONTH`	Month could not be scanned.
`IFX_GL_BADYEAR`	Year could not be scanned.
`IFX_GL_BADERANAME`	Era name not found.
`IFX_GL_BADERAOFFSET`	Era offset could not be scanned.

ifx_gl_convert_money()

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
is a pointer to the variable that holds the internal money representation that ifx_gl_convert_money() creates from the monstr money string.

monstr

is a pointer to the first character of the money string that the function converts to its internal money representation.

format
is 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.

E/C

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

DB API

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:

1. If the DBMONEY environment variable is set, the function scans monstr according to DBMONEY.

2. 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, ifx_gl_convert_money() compares each character in monstr with the format string. It takes the following actions for each possible kind of 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 those 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 


flags
For more information, see "Field Width".

maximum_width
For more information, see "Field Width".

type_specifier
For more information, see "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 identifies a format for the ifx_gl_convert_money() function to expect when it scans a monetary element of a monstr string. These monetary formats are those that the LC_MONETARY locale-file category of the current locale might define. The ifx_gl_convert_money() function supports the following formatting directives to represent a monetary element.

Formatting Directive Description
%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 quote ('), 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 over 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 justified, and it skips any initial white-space characters.

maximum_width
is 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.

ifx_gl_convert_number()

The ifx_gl_convert_number() function converts a number string to its internal decimal representation.

Syntax

#include <ifxgls.h>

...
int ifx_gl_convert_number(number, numstr, format)

		mi_decimal *number;

		char *numstr;

		char *format; 


number
is a pointer to the variable that holds the internal decimal representation that ifx_gl_convert_number() creates from the numstr number string.

numstr

is a pointer to the first character of the number string that the function converts to its internal decimal representation.

format
is a pointer to the format string that determines how to interpret the numstr number string. For more information, see "Format String". 







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_convert_number() function converts the number string that numstr references to its internal decimal representation, which the function stores in the number argument. The function uses the format that the format string specifies to scan the numstr number string.

E/C

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

DB API

The number argument is a pointer to an mi_decimal value.

Format String

If format is NULL, the function uses the formats in the LC_NUMERIC category of the current GLS locale file to scan the numstr number string. If format is not NULL, it must point to a string that follows the rules that this section describes.

To convert the numstr number string, ifx_gl_convert_number() compares each character in numstr with the format string. It takes the following actions for each possible kind of 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 numstr number 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 those 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 numeric element in the numstr numeric string. It replaces the formatting directive with an internal representation of the numeric element for conversion to the number value. Only one formatting directive is allowed in the format string.

Ordinary characters
The function must find the same ordinary character in the numstr number string. Any mismatch generates an error. The differing and subsequent characters in numstr remain unscanned.

The formatting directive consists of the following sequence:

%[flags][maximum_width[.minimum_width]]type_specifier 


flags
For more information, see "Field Width".

maximum_width
For more information, see "Field Width".

minimum_width
For more information, see "Field Width".

type_specifier
For more information, see "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 identifies a format for the ifx_gl_convert_number() function to expect when it scans a numeric element of a numstr string. These numeric formats are those that the LC_NUMERIC locale-file category of the current locale might define. The ifx_gl_convert_number() function supports the following formatting directives to represent a numeric element.

(1 of 2)

Formatting Directive Description
%b
Matches a binary integer.

%d
Matches a decimal integer.

%e
Matches a floating-point number.

%E
Is the same as %e.

%f
Is the same as %e.

%g
Is the same as %e.

%G
Is the same as %e.

%i
Is the same as %d.

%o
Matches an octal integer.

%q
Matches a base-4 integer.

%u
Matches an unsigned decimal integer.

%x
Matches a hexadecimal integer.

%X
Is the same as %x.

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][.minimum_width] 


[-]
indicates field justification.
If the specification begins with a minus sign (-), the functions expects the first character of the numstr number string to be the first character of the value to be converted. The function does not skip over white-space characters in numstr but reports them as an error.
If you omit the minus sign (-), the function assumes that the numstr string is right justified, and it skips any initial white-space characters.

maximum_width
is a decimal value that specifies the maximum number of characters to read from the numstr number string.

minimum_width
indicates an optional minimum field width. The minimum field width has the format of a period (.) followed by a decimal number. The minimum_width decimal number represents the minimum number of characters to read. If the function reads fewer than minimum_width characters, it generates an error (unless you specified left justification). When you specify left justification, the function skips any trailing white space to read the required number of characters.

Locale Information

The LC_NUMERIC category of the current locale affects the behavior of this function because it provides locale-specific information for the scan of the numstr number string. For more information, see "The LC_NUMERIC 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 one of the following values.


`IFX_GL_INVALIDFMT`	The format string is invalid.
`IFX_GL_PARAMERR`	The type specifier in the formatting directive is invalid.

ifx_gl_cv_mconv()

The ifx_gl_cv_mconv() function converts characters from one code set to another.

Syntax

#include <ifxgls.h>

...
int ifx_gl_cv_mconv(state, dst, dst_bytesleft, dst_codeset, src, src_bytesleft,

	src_codeset)

		conv_state_t *state;

		gl_mchar_t **dst;

		int *dst_bytesleft;

		char *dst_codeset;

		gl_mchar_t **src;

		int *src_bytesleft;

		char *src_codeset; 


state
points to a conv_state_t structure. For more information, see "Converting Fragmented Strings".

dst

points to a pointer to the first character in the destination buffer. If dst is NULL, the function updates *src, *src_bytesleft, and *dst_bytesleft, but the converted data is not written to *dst.

dst_bytesleft
points to the maximum number of bytes to write into *dst.

dst_codeset
is a pointer to the name of the destination (target) code set.

src
points to a pointer to the first character in the source buffer.

src_bytesleft

points to the number of bytes in *src to convert. If src_bytesleft is NULL, the function converts data until it reaches a null character in the source buffer.

src_codeset
is a pointer to the name of the source code set.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_cv_mconv() function converts the string of multibyte characters in *src into the same characters, but encoded in another code set, and stores the result in the buffer that *dst references. The ifx_gl_cv_mconv() function updates the following arguments:

The function updates src to point to the byte that follows the last source character successfully converted.
The function updates the integer that src_bytesleft references to the number of bytes in *src that have not been converted. After a successful conversion, src_bytesleft points to zero.
The function updates the dst to point to the first character of the code-set-converted text.
The function updates the integer that dst_bytesleft references to the number of bytes still available in *dst. Specifying Code Sets

The code sets, src_codeset and dst_codeset, can be any of the following:

Locale names
Code-set names
The IFX_GL_PROC_CS macro

For more information, see "Specifying Code-Set Names".

Calculating the Size of the Destination Buffer

The number of bytes written to *dst might be more or less than the number of bytes read from *src. You can determine the number of bytes that will be written to *dst in one of the following ways:

The function ifx_gl_cv_outbuflen() calculates an estimate based on the *src_bytesleft value.
The following expression is the maximum number of bytes that will be written to *dst for any value of *src in any locale. (*srcbytesleft) * IFX_GL_MB_MAX

Of these options, the last method is the fastest. The ifx_gl_cv_outbuflen() function is the slowest, but it is the most precise.

Converting Fragmented Strings

The state argument is a pointer to a conv_state_t structure. You must allocate a conv_state_t structure and set the first_frag and last_frag fields of the conv_state_t structure to tell the ifx_gl_cv_mconv() function whether the string to be converted is a fragment.

The following table lists the different fragments of a string and the corresponding values that you must set these two conv_state_t fields.

String Fragment Value of first_frag Field Value of last_frag Field
String is the first of n fragments.
1
0

String is the one of the 2nd, ..., nth-1 fragments.
0
0

String is the last (nth) fragment.
0
1

String is not fragmented; it is a complete string.
1
1

Important: The conv_state_t structure contains other fields that are for internal use only. Informix does not guarantee that these other internal fields of conv_state_t will not change in future releases. Therefore, to create portable code, set only the first_frag and last_frag fields of the conv_state_t structure.

For more information on the use of the conv_state_t structure, see "Preserving State Information".

Return Values

0
The code-set conversion was successful, and the **src*, **src_bytesleft*, **dst*, and **dst_bytesleft* arguments have been updated. If the entire source buffer is converted, the **srcbytesleft* value is zero (`0`).

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section. If the source conversion is stopped due to an error, the **srcbytesleft* value is greater than zero (`0`).

Errors

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


`IFX_GL_FILEERR`	Retrieving the conversion information for the specified code sets failed. This failure might be due to invalid code-set names, a missing registry file, a missing code-set-conversion object file or one with an incorrect format, or a lack of memory for the code-set-conversion object.
`IFX_GL_EILSEQ`	The *src value contains an invalid character. Conversion stops after both the last successfully converted source and destination character.
`IFX_GL_EINVAL`	The function cannot determine whether the last character of *src is a valid character or the end of shift sequence because it would need to read more than *src_bytesleft bytes from *src. Conversion stops after the last successfully converted source and destination character. For more information about this error, see "Keeping Multibyte Strings Consistent".
`IFX_GL_E2BIG`	Not enough space is available in the destination buffer. Conversion stops after both the last successfully converted source and destination character.

ifx_gl_cv_outbuflen()

The ifx_gl_cv_outbuflen() function calculates an approximation of the number of bytes required to store a case-converted multibyte character.

Syntax

#include <ifxgls.h>

...
int ifx_gl_cv_outbuflen(dst_codeset, src_codeset, src_bytes)

		char *dst_codeset;

		char *src_codeset;

		int src_bytes; 


dst_codeset
is a pointer to the name of the destination (target) code set.

src_codeset
is a pointer to the name of the source code set.

src_bytes

is the number of bytes in the buffer of multibyte characters to be code-set converted.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_cv_outbuflen() function returns one of the following values:

Exactly the number of bytes that a buffer of code-set-converted multibyte characters will require
A close over-approximation of this number of bytes

Use this function to determine whether or not code-set conversion of multibyte characters can be performed in place. If the value that this function that returns is not equal to src_bytes, code-set conversion of multibyte characters cannot be performed in place. You must allocate a separate multibyte destination buffer. However, if the value returned by this function is exactly equal to src_bytes, you can perform multibyte code-set conversion in place.

The code sets, src_codeset and dst_codeset, can be any of the following:

Locale names
Code-set names
The IFX_GL_PROC_CS macro

For more information, see "Specifying Code-Set Names".

Return Values

>=0
The number of bytes required to store multibyte characters of length src_bytes after they have been code-set converted.

-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_FILEERR`	Retrieving the conversion information for the specified code sets failed. This failure might be due to invalid code-set names, a missing registry file, a missing code-set-conversion object file or one with an incorrect format, or a lack of memory for the code-set-conversion object.

ifx_gl_cv_sb2sb_table()

The ifx_gl_cv_sb2sb_table() function returns the single-byte conversion table from the source code set to the destination code set.

Syntax

#include <ifxgls.h>

...
int ifx_gl_cv_sb2sb_table(dst_codeset, src_codeset, array)

		char *dst_codeset;

		char *src_codeset;

		unsigned char **array; 


dst_codeset
is a pointer to the name of the destination (target) code set.

src_codeset
is a pointer to the name of the source code set.

array

is the number of bytes in the buffer of multibyte characters to be code-set converted.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

If the code-set conversion from src_codeset to dst_codeset converts from one single-byte code set to another single-byte code set (where no substitution conversions occur), the ifx_gl_cv_sb2sb_table() function sets array to an array of 256 unsigned char values that represent the conversion. If the code-set conversion is not of this form, the function sets array to NULL.

The code sets, src_codeset and dst_codeset, can be any of the following:

Locale names
Code-set names
The IFX_GL_PROC_CS macro

For more information, see "Specifying Code-Set Names".

Return Values

0
The function was successful, and the array argument points to the conversion table.

-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_FILEERR`	Retrieving the conversion information for the specified code sets failed. This failure might be due to invalid code-set names, a missing registry file, a missing code-set-conversion object file or one with an incorrect format, or a lack of memory for the code-set-conversion object.

ifx_gl_format_date()

The ifx_gl_format_date() function formats an internal date value to a date string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_format_date(datestr, datebytes, date, format)

		char *datestr;

		int datebytes;

		mi_date *date;

		char *format; 


datestr

is a pointer to the first character in the date string that the function formats from its internal date representation.

datebytes

is the size of the datestr buffer for the date string. This size is the maximum size that the formatted string can reach.

date
is a pointer to the variable that holds the internal representation that ifx_gl_format_date() formats to create the datestr date string.

format
is a pointer to the format string that determines how to format the datestr date string. For more information, see "Format String". 







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_format_date() function uses the format that the format string specifies to format the internal date representation in date as a date string. It stores the resulting date string in a buffer that datestr references.

E/C

The date argument is a pointer to a date (4-byte int) value.

DB API

The date argument is a pointer to an mi_date value.

Format String

If format is NULL, the ifx_gl_format_date() function determines the format for the datestr date string that it creates from the environment, as follows:

1. If the DBDATE environment variable is set, the function formats datestr according to the order of the format elements in DBDATE.

2. If the GL_DATE environment variable is set, the function formats datestr according to the specification of GL_DATE.

3. Otherwise, the function obtains the formats from the d_fmt subcategory of the LC_TIME category in the current GLS locale.

If format is not NULL, it must point to a string that follows the rules that this section describes. To format the datestr date string, ifx_gl_format_date() takes the following actions for each possible kind of character that it finds in format.


Contents of Format String	Formatting Action Taken
Valid formatting directives	The function performs the specified formatting of the data in the date argument. It replaces the formatting directive with a string representation of a date element for the datestr date string.
Ordinary characters	The function copies the ordinary character unchanged to the datestr date string. Ordinary characters include the null terminator and white-space characters.

The formatting directive consists of the following sequence:

%[modifiers][flag][width][.precision]type_specifier 


modifiers
For more information, see "Modified Formatting Directives".

flag
For more information, see "Field Width and Precision".

width
For more information, see "Field Width and Precision".

precision
For more information, see "Field Width and Precision".

type_specifier
For more information, see "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 identifies a format for the ifx_gl_format_date() function to use when it creates a date element of a datestr string. These date formats are those that the LC_TIME locale-file category of the current locale might define. The ifx_gl_format_date() function supports the following formatting directives to represent a date element.

(1 of 2)

Formatting Directive Description
%a
Replaced by the abbreviated weekday name that the abday
subcategory of LC_TIME defines.

%A
Replaced by the full weekday name that the day subcategory of LC_TIME defines.

%b
Replaced by the abbreviated month name that the abmon
subcategory of LC_TIME defines.

%B
Replaced by the full month name that the mon subcategory of LC_TIME defines.

%C
Replaced by the century number (the year divided by 100 and
truncated to an integer as a decimal number [00-00]).

%d
Replaced by the day of the month as a decimal number [01,31].

%D
Is the same as %m/%d/%y.

%e
Replaced by the day of the month as a decimal number [1,31]; a
single digit is preceded by a space.

%h
Is the same as %b.

%j
Replaced by the day of the year as a decimal number [001,366].

%m
Replaced by the month as a decimal number [01,12].

%n
Replaced by a newline character.

%t
Replaced by a tab character.

%u
Replaced by the weekday as a decimal number [1,7], with 1
representing Monday.

%w
Replaced by the weekday as a decimal number [0,6], with 0
representing Sunday.

%x
Indicates use of the format that the d_fmt subcategory of LC_TIME
defines.

%y
Replaced by year without century as a decimal number [00,99].

%Y
Replaced by year with century as a decimal number [00,99].

%%
Replaced by the % symbol.

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

Modified Formatting Directives

You can modify some formatting directives with format modifiers, which follow the percent symbol (%), to indicate use of an alternative format that the LC_TIME locale-file category of the current locale might define. The ifx_gl_format_date() function supports the following format modifiers.

Format Modifier Purpose LC_TIME Subcategory
E
Use formats that include the era-based dates.
era, era_d_fmt

O
Use alternative locale-specific digits in dates.
alt_digits

The ifx_gl_format_date() function also supports the i modifier in the following formatting directives to support formats that are backward compatible with earlier Informix date and time formatting.

Formatting Directive Description
%iy
Replaced by the Informix DBDATE format Y2. This format prints the two-digit year offset.

%iY
Replaced by the Informix DBDATE format Y4. This format prints the full four-digit year.

Field Width and Precision

You can also specify an optional field width and precision in a formatting directive. This information precedes the type specifier in the formatting directive and has the following format:

[- | 0][width][.precision] 


[- | 0]
indicates field justification.
If the specification begins with a minus sign (-), the function left-justifies the field and pads it with spaces on the right. 
If the value begins with a zero (0), the function right-justifies the field and pads it with zeros on the left. 
Otherwise, the function right-justifies the field and pads it with spaces on the left. 

width
is a decimal value that specifies a minimum field width for the formatted datestr value.

precision
has the format of a period (.) followed by a decimal value. The field width specifier can optionally be followed by a precision directive. For more information on the purpose of precision, see the following table.

The values of width and precision affect each element of the directive. For example, %6.4D is interpreted as "%6.4m/%6.4d/%6.4y".

The precision value has the following effects on the different formatting directives.

Formatting Directives Effect of Precision
%C, %d, %e, %Ey, %iy, %iY, %j, %m, %u, %w, %y, %Y
The value of precision specifies the minimum number of digits to appear. If a directive supplies fewer digits than the precision specifies, the function pads the value with leading zeros.
The %d, %Ey, %iy, %m, %u, %w, and %y directives have a default precision of 2. The %j directive has a default precision of 3. The %Y and %iY directives have a default precision of 4.

%a, %A, %b, %B, %EC, %Eg, %h
The value of precision specifies the maximum number of characters to be used. If a value to be formatted has more characters than the precision specifies, the function truncates the result on the right.

%Ex, %EY, %n, %t, %x, %%
The values of width and precision do not affect these directives.

Directives modified with O
(alternative digits)
The field width relates to display width rather than actual number of digits. The precision is still the minimum number of digits printed.

Locale Information

The LC_TIME category of the current locale affects the behavior of this function because it provides the locale-specific information for the formatting of the date value. For more information, see "The LC_TIME 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 one of the following values.


IFX_GL_E2BIG	Formatting stopped due to lack of space in the buffer.
`IFX_GL_EBADF`	The formatting directive is invalid.
`IFX_GL_EDAYRANGE`	Day number is out of bounds.
`IFX_GL_EWKDAYRANGE`	Weekday number is out of bounds.
`IFX_GL_EYDAYRANGE`	Year day number is out of bounds.
`IFX_GL_EMONTHRANGE`	Month number is out of bounds.
`IFX_GL_EYEARRANGE`	Year number is out of bounds.
`IFX_GL_EERAOFFRANGE`	Era offset is out of bounds.
`IFX_GL_BADDAY`	Month (as a number) could not be scanned.
`IFX_GL_BADWKDAY`	Weekday (as a number) could not be scanned.
`IFX_GL_BADYDAY`	Day of year (as a number) could not be scanned.
`IFX_GL_BADMONTH`	Month could not be scanned.
`IFX_GL_BADYEAR`	Year could not be scanned.
`IFX_GL_BADERANAME`	Era name not found.
`IFX_GL_BADERAOFFSET`	Era offset could not be scanned.

ifx_gl_format_datetime()

The ifx_gl_format_datetime() function formats an internal date/time value to a date/time string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_format_datetime(datetimestr, datetimebytes, datetime, format)

		char *datetimestr;

		int datetimebytes;

		mi_datetime *datetime;

		char *format; 


datetimestr

is a pointer to the first character in the date/time string that the function formats from its internal datetime representation.

datetimebytes

is the size of the datetimestr buffer for the date/time string. This size is the maximum size that the formatted string can reach.

datetime
is a pointer to the variable that holds the internal representation that ifx_gl_format_datetime() formats to create the datetimestr date/time string.

format
is a pointer to the format string that determines how to format the datetimestr date/time string. For more information, see "Format String". 







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_format_datetime() function uses the format that the format string specifies to format the internal date/time representation in datetime as a date/time string. It stores the resulting date/time string in a buffer that datetimestr references.

E/C

The datetime argument is a pointer to a datetime (dtime_t) value.

DB API

The datetime argument is a pointer to an mi_datetime value.

Format String

If format is NULL, the ifx_gl_format_datetime() function determines the format for the datetimestr date/time string that it creates from the environment, as follows:

1. If the DBTIME environment variable is set, the function formats datetimestr according to DBTIME.

2. If the GL_DATETIME environment variable is set, the function formats datetimestr according to GL_DATETIME.

3. Otherwise, the function obtains the formats from the d_t_fmt subcategory of the LC_TIME category in the current GLS locale.

If format is not NULL, it must point to a string that follows the rules that this section describes. To format the datetimestr date/time string, ifx_gl_format_datetime() takes the following actions for each possible kind of character that it finds in format.


Contents of Format String	Formatting Action Taken
Valid formatting directives	The function performs the specified formatting of the data in the datetime argument. It replaces the formatting directive with a string representation of a date or time element for the datetimestr date/time string.
Ordinary characters	The function copies the ordinary character unchanged to the datetimestr date/time string. Ordinary characters include the null terminator and white-space characters.

The formatting directive consists of the following sequence:

%[modifiers][flag][width][.precision]type_specifier 


modifiers
For more information, see "Modified Formatting Directives".

flags
For more information, see "Field Width and Precision".

width
For more information, see "Field Width and Precision".

precision
For more information, see "Field Width and Precision".

type_specifier
For more information, see "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 identifies a format for the ifx_gl_format_datetime() function to use when it creates a date or time element of a datetimestr string. These date and time formats are those that the LC_TIME locale-file category of the current locale might define. The ifx_gl_format_datetime() function supports the following formatting directives to represent a date or time element that the LC_TIME locale-file category of the current locale might define.

(1 of 3)

Formatting Directive Description
%a
Replaced by the abbreviated weekday name that the abday
subcategory of LC_TIME defines.

%A
Replaced by the full weekday name that the day subcategory of LC_TIME defines.

%b
Replaced by the abbreviated month name that the abmon
subcategory of LC_TIME defines.

%B
Replaced by the full month name that the mon subcategory of LC_TIME defines.

%c
Indicates use of the format that the d_t_fmt subcategory of LC_TIME
defines.

%C
Replaced by the century number (the year divided by 100 and truncated to an integer as a decimal number [00-00]).

%d
Replaced by the day of the month as a decimal number [01,31].

%D
Is the same as %m/%d/%y.

%e
Replaced by the day of the month as a decimal number [1,31]; a single digit is preceded by a space.

%F[n]
Replaced by the microsecond as a decimal number. An optional precision specification, n, can follow F. This n value must be
between 1 and 5.

%h
Is the same as %b.

%H
Replaced by the hour (24-hour clock) as a decimal number [00,23].

%I
Replaced by the hour (12-hour clock) as a decimal number [00,12].

%j
Replaced by the day of the year as a decimal number [001,366].

%m
Replaced by the month as a decimal number [01,12].

%M
Replaced by the minute as a decimal number [00,59].

%n
Replaced by a newline character.

%p
Replaced by the locale equivalent of either A.M. or P.M. that the am_pm subcategory of LC_TIME defines.

%r
Indicates use of the format that the t_fmt_amp subcategory of LC_TIME defines.

%R
Replaced by the time in 24-hour notation (%H:%M).

%S
Replaced by the second as a decimal number.

%t
Replaced by a tab character.

%T
Replaced by the time (%H:%M:%S).

%u
Replaced by the weekday as a decimal number [1,7], with 1
representing Monday.

%w
Replaced by the weekday as a decimal number [0,6], with 0
representing Sunday.

%x
Indicates use of the format that the d_fmt subcategory of LC_TIME defines.

%X
Indicates use of the format that the t_fmt subcategory of LC_TIME defines.

%y
Replaced by year without century as a decimal number [00,99].

%Y
Replaced by year with century as a decimal number [00,99].

%%
Replaced by the % symbol.

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

Modified Formatting Directives

You can modify some formatting directives with format modifiers, which follow the percent symbol (%), to indicate use of an alternative format that the LC_TIME locale-file category of the current locale might define. The ifx_gl_format_datetime() function supports the following format modifiers.

Format Modifier Purpose LC_TIME Subcategory
E
Use formats that include the era-based dates and times.
era, era_d_fmt, era_t_fmt, era_d_t_fmt

O
Use alternative locale-specific digits in dates and times.
alt_digits

The ifx_gl_format_datetime() function also supports the i modifier in the following formatting directives to support formats that are backward compatible with earlier Informix date and time formatting.

Formatting Directive Description
%iF[n]
Replaced by the Informix DBTIME format %F. An optional precision specification, n, can follow the F. This n value must be between 1 and 5.

%iy
Replaced by the Informix DBDATE format Y2. This format prints the two-digit year offset.

%iY
Replaced by the Informix DBDATE format Y4. This format prints the full four-digit year.

Field Width and Precision

You can also specify an optional field width and precision in a formatting directive. This information precedes the type specifier in the formatting directive and has the following format:

[- | 0][width][.precision] 


[- | 0]
indicates field justification.
If the directive begins with a minus sign (-), the function left-justifies the field and pads it with spaces on the right. 
If the directive begins with a zero (0), the function right-justifies the field and pads it with zeros on the left. 
Otherwise, the function right-justifies the field and pads it with spaces on the left.

width
is a decimal value that specifies a minimum field width for the 
formatted datetimestr value.

precision
has the format of a period (.) followed by a decimal value. The field width specifier can optionally be followed by a precision directive. For more information on the purpose of precision, see the following table.

The values of width and precision affect each element of the %D, %R, and %T directives. For example, %6.4D is interpreted as "%6.4m/%6.4d/%6.4y".

The precision value has the following effects on the different formatting directives.

Formatting Directives Effect of Precision
%C, %d, %e, %Ey, %F, %H, %iF, %iy, %iY, %I, %j, %m, %M, %S, %u, %w, %y, %Y
The value of precision specifies the minimum number of digits to appear. If a directive supplies fewer digits than the precision specifies, the function pads the value with leading zeros.
The %d, %Ey, %H, %iF, %iy, %m, %M, %S, %u, %w, and %y directives have a default precision of 2. The %j directive has a default precision of 3. The %Y and %iY directives have a default precision of 4.
The %F and %iF directives can be followed by an optional precision specification. For example, %F3 means a precision of 3. The value of this precision must be between 1 and 5. If it is not between 1 and 5, an error is returned. The %F directive has a default precision of 6. This directive overrides the precision value between the % symbol and the directive if one is given.

%a, %A, %b, %B, %EC, %Eg, %h, %p
The value of precision specifies the maximum number of characters to be used. If a value to be formatted has more characters than the precision specifies, the function truncates the result on the right.

%c, %Ec, %Ex, %EX, %EY, %n, %r, %t, %x, %X, %%
The values of width and precision do not affect these directives.

Directives modified with O
(alternate digits)
The field width relates to display width rather than actual number of digits. The precision is still the minimum number of digits printed.

Locale Information

The LC_TIME category of the current locale affects the behavior of this function because it provides the locale-specific information for the formatting of the datetime value. For more information, see "The LC_TIME 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 one of the following values.


`IFX_GL_E2BIG`	Formatting stopped due to lack of space in the buffer.
`IFX_GL_EBADF`	The formatting directive is invalid.
`IFX_GL_EFRACRANGE`	Fraction of second out of bounds.
`IFX_GL_ESECONDRANGE`	Second is out of bounds.
`IFX_GL_EMINUTERANGE`	Minute is out of bounds.
`IFX_GL_EHOURRANGE`	Hour is out of bounds.
`IFX_GL_EDAYRANGE`	Day number is out of bounds.
`IFX_GL_EWKDAYRANGE`	Weekday number is out of bounds.
`IFX_GL_EYDAYRANGE`	Day-of-year number is out of bounds.
`IFX_GL_EMONTHRANGE`	Month number is out of bounds.
`IFX_GL_EYEARRANGE`	Year number is out of bounds.
`IFX_GL_EERAOFFRANGE`	Era offset is out of bounds.
`IFX_GL_BADFRAC`	Fraction could not be scanned.
`IFX_GL_BADSECOND`	Second could not be scanned.
`IFX_GL_BADMINUTE`	Minute could not be scanned.
`IFX_GL_BADHOUR`	Hour could not be scanned.
`IFX_GL_BADDAY`	Month (as a number) could not be scanned.
`IFX_GL_BADWKDAY`	Weekday (as a number) could not be scanned.
`IFX_GL_BADYDAY`	Day of year (as a number) could not be scanned.
`IFX_GL_BADMONTH`	Month could not be scanned.
`IFX_GL_BADYEAR`	Year could not be scanned.
`IFX_GL_BADERANAME`	Era name was not found.
`IFX_GL_BADERAOFFSET`	Era offset could not be scanned.

ifx_gl_format_money()

The ifx_gl_format_money() function formats an internal money value to a money string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_format_money(monstr, monstrbytes, money, format)

		char *monstr;

		int monstrbytes;

		mi_money *money;

		char *format; 


monstr

is a pointer to the first character in the money string that the function formats from its internal money representation.

monstrbytes

is the size of the monstr buffer for the money string. This size is the maximum size that the formatted string can reach.

money
is a pointer to the variable that holds the internal representation that ifx_gl_format_money() formats to create the monstr money string.

format
is a pointer to the format string that determines how to format the monstr money string. For more information, see "Format String". 







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_format_money() function uses the format that the format string specifies to format the internal money representation in money as a money string. It stores the resulting money string in a buffer that monstr references.

E/C

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

DB API

The money argument is a pointer to an mi_money value.

Format String

If format is NULL, the ifx_gl_format_money() function determines the format for the monstr money string that it creates from the environment, as follows:

1. If the DBMONEY environment variable is set, the function formats monstr according to DBMONEY.

2. Otherwise, the function uses the monetary formats in the LC_MONETARY category of the current GLS locale.

If format is not NULL, it must point to a string that follows the rules that this section describes. To format the monstr money string, ifx_gl_format_money() takes the following actions for each possible kind of character that it finds in format.


Contents of Format String	Formatting Action Taken
A valid formatting directive	The function performs the specified formatting of the data in the money argument. It replaces the formatting directive with a string representation of a money element for the monstr money string. Only one formatting directive is allowed in the format string.
Ordinary characters	The function copies the ordinary character unchanged to the monstr money string. Ordinary characters include the null terminator and white-space characters.

The formatting directive consists of the following sequence:

%[modifiers][flag][width[#left_precision][.right_precision]]type_specifier 


modifiers
For more information, see "Modified Formatting Directives".

flags
For more information, see "Field Width and Precision".

width
For more information, see "Field Width and Precision".

left_precision
For more information, see "Field Width and Precision".

right_precision
For more information, see "Field Width and Precision".

type_specifier
For more information, see "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 identifies a format for the ifx_gl_format_money() function to use when it creates a monetary element of a monstr string. These monetary formats are those that the LC_MONETARY locale-file category of the current locale might define. The ifx_gl_format_money() function supports the following formatting directives.

Formatting Directive Description
%i
Replaced by the international monetary format (which uses the int_curr_symbol subcategory of the LC_MONETARY category in the current locale) for the money argument. For example, in the default
locale, the international monetary format for 1,234.56 is as follows:
USD 1,234.56

%n
Replaced by the national currency format (which uses the currency_symbol of the LC_MONETARY category in the current
locale) for the money argument. For example, in the default locale, the national monetary format for 1,234.56 is as follows:
$1,234.56

%%
Replaced by the % symbol.

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

Modified Formatting Directives

You can modify some formatting directives with format modifiers, which follow the percent symbol (%), to indicate use of an alternative format. The ifx_gl_format_money() function supports the following format modifiers.

Format Modifier Description
=f
Use the single-byte character f as the numeric-fill character. The fill
character must be representable in a single byte to work with precision and width counts. The default numeric-fill character is the blank (space)
character. This flag does not affect field-width filling, which always uses the space character. Unless you specify a left_precision, this flag is ignored.

^
Do not format the monetary amount with thousands separators. The default action is to insert the thousands separators if the LC_MONETARY category of the current locale defines them.

+ or (
Specify how to represent positive and negative monetary amounts. Only one of + or ( can be specified. If you specify the plus sign (+) , the function uses the equivalent of + and - that the LC_MONETARY category of the
current locale defines. For example, in the default locale, a plus sign means an the empty string for positive values and a minus sign (-) for negative values. If you do not specify either flag, the function uses the locale equivalent of the minus sign (-) for negative values and no sign for positive values.

!
Suppress the currency symbol from the formatted result.

Field Width and Precision

You can also specify an optional field width and precision in a formatting directive. This information precedes the type specifier in the formatting directive and has the following format:

[-][width[#left_precision][.right_precision]] 


-
indicates field justification. If the specification begins with a minus sign (-), the function left-justifies the field and pads it with spaces on the right. Otherwise, the function right-justifies the field and pads it with spaces on the left.

width
is a decimal value that specifies a minimum field width, in 
characters, in which the resulting string is right-justified. The default field width is zero (0).

left_precision
is a string that specifies the maximum number of digits expected to the left of the decimal separator. This option causes an amount to be formatted as if it has the number of digits that n specifies. If more than n digit positions are required, the function ignores this precision specification. 

right_precision
is a decimal value that specifies the number of digits after the decimal separator. If the value of right_precision is zero, no decimal separator appears in the formatted string. If you do not include right_precision, the function uses a default, which the current locale specifies. The amount that is being formatted is rounded to the specified number of digits before formatting.








You can use this left_precision option to:

keep the formatted output from multiple calls to this function aligned in the same columns.
fill unused positions with a special character, as the asterisk character in the "$***123.45" string.

For left_precision, digit positions in excess of those actually required are filled with the numeric-fill character (see the description of the =f modifier in "Modified Formatting Directives"). If grouping has not been suppressed with the ^ modifier, and it is defined for the current locale, the function inserts thousands separators before the fill characters (if any) are added. Thousands separators are not applied to fill characters even if the fill character is a digit.

To ensure alignment, any characters appearing before or after the number in the formatted output such as currency or sign symbols are padded as necessary with space characters to make their positive and negative formats and equal length.

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 formatting of the money value. 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 one of the following values.


`IFX_GL_ENOSYS`	The formatting directive is not supported.
`IFX_GL_E2BIG`	Formatting stopped due to lack of space in the buffer.

ifx_gl_format_number()

The ifx_gl_format_number() function formats an internal decimal value to a number string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_format_number(numstr, numstrbytes, number, format)

		char *numstr;

		int numstrbytes;

		mi_decimal *number;

		char *format; 


numstr

is a pointer to the first character in the number string that the function formats from its internal number representation.

numstrbytes

is the size of the numstr buffer for the number string. This size is the maximum size that the formatted string can reach.

number
is a pointer to the variable that holds the internal representation that ifx_gl_format_number() formats to create the numstr number string.

format
is a pointer to the format string that determines how to format the numstr number string. For more information, see "Format String". 







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_format_number() function uses the format that the format string specifies to format the internal decimal representation in number as a number string. It stores the resulting number string in a buffer that numstr references.

E/C

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

DB API

The number argument is a pointer to an mi_decimal value.

Format String

If format is NULL, the ifx_gl_format_number() function uses the numeric formats in the LC_NUMERIC category of the current GLS locale to format the numstr number string that it creates.

If format is not NULL, it must point to a string that follows the rules that this section describes. To format the numstr number string, ifx_gl_format_number() takes the following actions for each possible kind of character that it finds in format.

Contents of Format String Formatting Action Taken
A valid formatting directive
The function performs the specified formatting of the data in the number argument. It replaces the formatting directive with a string representation of a numeric element for the numstr number string. Only one formatting directive is allowed in the format string.

Ordinary characters
The function copies the ordinary character unchanged to the numstr number string. Ordinary characters include the null terminator and white-space characters.

The formatting directive consists of the following sequence:

%[modifiers][flags][width[.precision]]type_specifier 


modifiers
For more information, see "Modified Formatting Directives".

flags
For more information, see "Field Width and Precision".

width
For more information, see "Field Width and Precision".

precision
For more information, see "Field Width and Precision".

type_specifier
For more information, see "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 identifies a format for the ifx_gl_format_number() function to use when it creates a numeric element of a numstr string. These numeric formats are those that the LC_NUMERIC locale-file category of the current locale might define. The ifx_gl_format_number() function supports the following formatting directives.

(1 of 2)

Formatting Directive Description
%b
Replaced by the binary representation of number.

%d
Replaced by the decimal representation of number.

%e
Replaced by the style [-]d.ddde[+|-]dd of number (where d is a digit).

%E
Replaced by the style [-]d.dddE[+|-]dd of number (where d is a digit).

%f
Replaced by the style [-]ddd.ddd of number (where d is a digit). The default precision is 6.

%g
Replaced by the style of %f or %e. The %e directive is used only if the converted exponent is less than -4 or greater than or equal to the precision. The precision specifies the number of significant digits. Trailing zeros are removed from the fractional portion of the result.

%G
Is the same as %g , except the replacement of %E for %e.

%i
Is the same as %d.

%o
Replaced by the octal representation of number.

%q
Replaced by the base-4 representation of number.

%u
Replaced by the unsigned decimal representation of number.

%x
Replaced by the hexadecimal representation of number, using the hexadecimal characters a-f.

%X
Is the same as %x, but use uppercase hexadecimal characters (A-F) instead of lowercase letters (a-f).

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

Modified Formatting Directives

You can modify some formatting directives with format modifiers, which follow the percent symbol (%), to indicate use of an alternative format. The ifx_gl_format_number() function supports the following format modifiers.

Format Modifier Description
'
Separate the significant digits of the converted number with the grouping character defined in the locale, according to the grouping format also defined in the locale.

+
Begin the result of a signed conversion with a positive or negative sign, which the locale defines.

-
Left-justify the result of the conversion within the field.

space.
If the beginning of a signed conversion is not a sign, prefix result with a space character (unless the + modifier exists).

#
Convert the value to an alternate form. For a %o directive, the first digit of the result is forced to be zero. For a %x (or %X) directive, a non-zero result will have a leading "0x" (or "0X"). Fora %e,%E,%f,%g,or %G directive, the result always has a decimal-separator character.

0
Pad the field width with leading zeros (unless the - modifier exists).

If the alternative format does not exist for the current locale, the function uses the unmodified formatting directive.

Field Width and Precision

You can also specify an optional field width and precision in a formatting directive. This information precedes the type specifier in the formatting directive and has the following format:

[- | 0][width[.precision]] 


[- | 0]
indicates field justification. 
If the specification begins with a minus sign (-), the function left-justifies the field and pads it with spaces on the right. 
If the value begin with a zero (0), the function right-justifies the field and pads it with zeros on the left. 
Otherwise, the function right-justifies the field and pads it with spaces on the left.

width
is a decimal value that specifies a minimum field width for the 
formatted string.

precision
has the format of a period (.) followed by a decimal value. The field width specifier can optionally be followed by a precision directive. 
For the %d, %o, %u, %x, and %X directives, the value of precision 
specifies the minimum number of digits to appear. If a directive supplies fewer digits than specified by the precision, it will be padded with leading zeros.
For the %e, %E, and %f directives, the value of precision specifies the number of digits to appear after the decimal separator.
For the %g, and %G directives, the value of precision specifies the 
maximum number of significant digits.

Locale Information

The LC_NUMERIC category of the current locale affects the behavior of this function because it provides the locale-specific information for the formatting of the number value. For more information, see "The LC_NUMERIC 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 one of the following values.


`IFX_GL_INVALIDFMT`	The format string is invalid.
`IFX_GL_PARAMERR`	The type specifier in the formatting directive is invalid.
`IFX_GL_E2BIG`	Formatting stopped due to lack of space in the buffer.

ifx_gl_getmb()

The ifx_gl_getmb() function obtains a single multibyte character from a user-specified location.

Syntax

#include <ifxgls.h>

...
int ifx_gl_fgetmb(mb, funcp, v, bytes_got)

		gl_mchar_t *mb;

		int (*funcp)(void *v);

		void *v;

		int *bytes_got; 


mb
is a pointer to the multibyte character whose bytes the funcp function reads from a specified location.

funcp
is the funcp argument is a pointer to a function that you define to specify the location from which to read the multibyte character.

v
is a pointer that the ifx_gl_getmb() function passes to the funcp function each time it is called.

bytes_got
is a pointer to an integer that ifx_gl_getmb() sets to indicate the number of bytes that the funcp function has successfully read.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_getmb() function calls a function that you define to obtain the bytes that form one multibyte character from a specified location. This multibyte character is then written to the mb buffer.

The funcp argument is a pointer to a function that you must define as follows:

       int funcp(void *v)

The pointer v is passed to funcp each time that it is called. On success, funcp must return a value between 0 and 255, inclusive, which is the next byte of the multibyte character. On failure, funcp must return -1.

This function calls funcp until one of the following occurs:

1. A complete multibyte character has been formed.

2. The funcp function returns a byte that forms an illegal character when appended to the bytes already read.

3. The funcp function fails.

All bytes obtained by calling funcp are guaranteed to be written to mb. This function assumes that mb is large enough to hold the result. You can determine what will be written to mb in either of the following ways:

The function ifx_gl_mb_loc_max() calculates the maximum number of bytes in any multibyte character for the current locale.
The macro IFX_GL_MB_MAX is the maximum number of bytes in any multibyte character in any locale. This value is always equal to or greater than the value that ifx_gl_mb_loc_max() returns.

Of these two options, the macro IFX_GL_MB_MAX is faster and the only one that can be used to initialize static buffers. The function ifx_gl_mb_loc_max() is slower but more precise.

The number of bytes that funcp successfully reads is returned in bytes_got (even when failure is returned).

Return Values

0 to 255
The value of the next byte for the multibyte character

-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 one of the following values.


`IFX_GL_EILSEQ`	The bytes read from funcp do not form a valid multibyte character.
`IFX_GL_EINVAL`	The funcp function returned `-1` in the middle of an otherwise valid multibyte character.
`IFX_GL_EOF`	The funcp function returned `-1` on the first call.

ifx_gl_init()

The ifx_gl_init() function initializes the current processing locale for the current program.

Syntax

#include <ifxgls.h>

...
int ifx_gl_init(void) 



Valid in Client Application

Valid in DataBlade UDR

Yes
Not needed

Usage

The ifx_gl_init() function initializes a global locale structure that identifies the current processing locale. Because this locale structure is global, the INFORMIX-GLS functions do not require the current locale as an argument. Any program that establishes its own connections must call the ifx_gl_init() function before it calls any other INFORMIX-GLS functions.

E/C

ESQL/C applications establish their own connections to a database server and therefore must call the ifx_gl_init() function before any INFORMIX-GLS functions to establish a current processing locale.

DB API

DataBlade client applications establish their own connections to a database server and therefore must call the ifx_gl_init() function before any
INFORMIX-GLS functions to establish a current processing locale.

However, a DataBlade UDR executes in the context of an established connection and therefore has an established current processing locale. DataBlade UDRs are not required to call the ifx_gl_init() function.

For both ESQL/C and DataBlade client applications, ifx_gl_init() initializes the current processing locale to the client locale.

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 one of the following values.


`IFX_GL_PARAMERR`	Either specifiers for locale or code-set conversion (such as `GLS` environment variables) are incorrect, or the code-set name registry file could not be found.
`IFX_GL_ENOMEM`	Not enough memory is available to allocate a new locale object or a new code-set-conversion object.
`IFX_GL_FILEERR`	The locale or code-set conversion file could not be found, is not readable, or has the wrong format.
`IFX_GL_INVALIDLOC`	An attempt to create a locale with incompatible code sets occurred.
`IFX_GL_ELOCTOOWIDE`	The locale contains characters that are wider than the library allows.
`IFX_GL_BADOBJVER`	The locale object version is not compatible with the current library.
`IFX_GL_BADFILEFORM`	Bad format was found in the code-set registry file.

INFORMIX-GLS Programmer's GuideChapter 4: INFORMIX-GLS Function Descriptions Home Contents Index Master Index New Book

ifx_gl_case_conv_outbuflen()

Usage

Return Values >0 The number of bytes required to store multibyte characters of length src_mbs_bytes after they have been converted to either lowercase or uppercase characters. 0 The function was not successful.

Errors

Usage

Errors

Usage

Locale Information

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

Usage

Usage

Locale Information

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

Usage

Locale Information

Usage

Errors

Usage

Return Values >=0 The number of bytes required to store multibyte characters of length src_bytes after they have been code-set converted. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values 0 The function was successful, and the array argument points to the conversion table. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

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

Usage

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

Usage

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

Usage

Locale Information

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

Usage

Return Values 0 to 255 The value of the next byte for the multibyte character -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

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

INFORMIX-GLS Programmer's Guide
Chapter 4: INFORMIX-GLS Function Descriptions

Home Contents Index Master Index New Book

Return Values

>0
The number of bytes required to store multibyte characters of length src_mbs_bytes after they have been converted to either lowercase or uppercase characters.

0
The function was not successful.

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.

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.

Return Values

>=0
The number of bytes required to store multibyte characters of length src_bytes after they have been code-set converted.

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

Return Values

0
The function was successful, and the array argument points to the conversion table.

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

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.

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.

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.

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.

Return Values

0 to 255
The value of the next byte for the multibyte character

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

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.