The ifx_gl_convert_date() function

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: A pointer to the variable that holds the internal date representation that ifx_gl_convert_date() creates from the datestr date string.
datestr: A pointer to the first character of the date string that the function converts to its internal date representation.
format: 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.

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

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:

If the DBDATE environment variable is set, the function scans datestr according to the order of the format elements in DBDATE.
If the GL_DATE environment variable is set, the function scans datestr according to the specification of GL_DATE.
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 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 `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 characters 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


Argument	See
`modifiers`	Modified formatting directives
`flags`	Field width
`minimum_width`	Field width
`maximum_width`	Field width
`type_specifier`	Valid type specifiers

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

Valid type specifiers

The type specifier is a letter (or letters) within a formatting directive that 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 formats 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.

%a: Matches the day of the week. You can specify the abbreviated weekday name, which the abday subcategory of the LC_TIME defines or specify the full weekday name, which the day subcategory of LC_TIME defines.
%A: Same as %a.
%b: Matches the month. You can specify the abbreviated month name, which the abmon subcategory of LC_TIME defines or specify the full month name, which the mon subcategory of LC_TIME defines.
%B: Same as %b.
%C: Matches the century number in the range 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 in the range 1 - 31. Leading zeros are permitted but not required.
%e: Same as %d.
%h: Same as %b.
%j: Matches the day of the year as a decimal number in the range 1 - 366. Leading zeros are permitted but not required.
%m: Matches the month as a decimal number in the range 1 - 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 in the range 1 -7, with 0 representing Sunday. Leading zeros are permitted but not required.
%w: Matches the weekday as a decimal number in the range 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 in the range 0 - 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 in the range 0 - 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 the directives that are 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 modifier.

O: Use alternative locale-specific digits in dates.
LC_TIME Subcategory: alt_digits

The alternative format replaces one that an unmodified formatting directive normally uses. If the alternative format does not exist for the current locale, the behavior is the same as if unmodified formatting directives were used. The ifx_gl_convert_date() function supports the following modified formatting directives with the O modifier.

%Eg: Same as %EC.
%Ex: Indicates use of the format that the era_d_fmt subcategory of LC_TIME category defines.
%Ey: Matches the offset from %EC (year only) in the alternative representation, which the era subcategory of LC_TIME defines.
%EY: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to match the full alternative year representation, which the era subcategory of LC_TIME defines.
%Od: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to match the day of the month. Leading zeros are permitted but not required.
%Oe: Same as %Od.
%Om: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to match the month.
%Ow: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to match the weekday as a number (Sunday=0).

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

%iy: Indicates use of the Informix® DBDATE format Y2. Both 98 and 1998 are interpreted as 1998 (or the century that DBCENTURY indicates).
%iY: Indicates use of the Informix® DBDATE format Y4. Both 98 and 1998 are interpreted as 1998 (or the century that DBCENTURY indicates).

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-aligned. 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 0. If the specification begins with 0, the function assumes that the field is right-aligned. Any padding to the left must use zeros. Otherwise, the function assumes that the datestr string is right-aligned.
maximum_width: 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 occurs, 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: Yearday 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_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_BADFMTMOD: Format modifier is invalid.
IFX_GL_BADFMTWP: Width is invalid.
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.