The ifx_gl_convert_datetime() function

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: 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: A pointer to the first character of the date/time string that the function converts to its internal date/time representation.
format: 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.

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

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:

If the DBTIME environment variable is set, the function scans according to DBTIME.
If the GL_DATETIME environment variable is set, the function scans datetimestr according to the specification of GL_DATETIME.
Otherwise, the function obtains the format from the d_t_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 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 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 `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 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/time element in the `datetimestr` date/time string. It replaces the formatting directive with an internal representation of the date/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


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_datetime() function to expect when it scans a date/time element of a datetimestr string. These date/time formats are formats that the LC_TIME locale-file category of the current locale might define. The ifx_gl_convert_datetime() function supports the following formatting directives to represent a date/time 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. The directive ignores case when it matches weekday names.
%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. The directive ignores case when it matches month names.
%B: Same as %b.
%c: Indicates use of the format that the d_t_fmt subcategory of the LC_TIME defines for the scan.
%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.
%D: Is the same as %m/%d/%y.
%e: Same as %d.
%F[n]: Matches the microsecond as a decimal number in the range 0 - 999999. Leading zeros are permitted but not required. An optional precision specification can follow the %F. This n value must be 1 - 5.
%h: Same as %b.
%H: Matches the hour (24-hour clock) as a decimal number in the range 0 - 23. Leading zeros are permitted but not required.
%I: Matches the hour (12-hour clock) as a decimal number in the range 0 - 12. Leading zeros are permitted but not required. If %I is used without %p, the function assumes a.m.
%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 minute as a decimal number in the range 0 - 59. Leading zeros are permitted but not required.
%n: Matches any white space that the blank class of the LC_CTYPE category defines.
%p: Matches the 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_ampm subcategory of LC_TIME defines.
%R: Matches the time as %H:%M.
%S: Matches the second as a decimal number in the range 0- 61. Leading zeros are permitted but not required.
%t: Matches any white space that the space class of the LC_CTYPE category defines.
%T: Matches the time as %H:%M:%S.
%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.
%X: Indicates use of the format that the t_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 datetimestr 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_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 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_datetime() function supports the following format modifier.

O: Use alternative locale-specific digits in dates and times.
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_datetime() function supports the following modified formatting directives with the O modifier.

%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.
%OH: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to match the hour (24-hour clock).
%OI: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to match the hour (12-hour clock).
%Om: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to match the month.
%OM: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to match the minutes.
%OS: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to match the seconds.
%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_datetime() function supports the i modifier in the following formatting directives to support formats that are compatible with earlier HCL Informix® date and time formatting.

%iF[n]: Indicates use of the Informix DBTIME format %F. An optional precision specification, n, can follow F. This n value must be 1 - 5.
%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 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-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 datetimestr string is right-aligned.
maximum_width: 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 1 - 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.

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_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_EHOURRANGE: Hour is out of bounds.
IFX_GL_EMINUTERANGE: Minute 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_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.