ifx_gl_convert_datetime - Convert a datetime string to an internal representation.

SYNOPSIS

#include <ifxgls.h>
int ifx_gl_convert_datetime(mi_datetime *datetime, 
                            char *datetimestr, char *format)

DESCRIPTION

This function converts the datetime string stored in datetimestr into an internal representation. The internal representation is stored in the mi_datetime structure pointed to by datetime in the format specified by format.

If format is NULL, then the format is determined from the environment as follows:

  1. If the DBTIME environment variable is set, then the datetime is scanned according to DBTIME.
  2. If the GL_DATETIME environment variable is set, then the format is scanned according to the specification of GL_DATETIME.
  3. Otherwise the d_t_fmt setting of the current GLS locale is used.

If format is not NULL, then it must point to a string which follows the rules described in the FORMAT section below.

FORMAT

The format is composed of zero or more directives. Each directive is composed of one of the following:
-
one or more white-space characters (as specified by the ifx_gl_ismspace() function)
-
an ordinary character (neither % or a white-space character)
-
a conversion specification. Each conversion specification is composed of a % character followed by a conversion character which specifies the replacement required. There must be white-space or other non-alphanumeric characters between any two conversion specifications.

The following conversion specifications are supported:

%a
is the day of the week, using the locale's weekday names; either the abbreviated or full name may be specified (see the 'abday' and 'day' sub-categories of the locale's LC_TIME category).
%A
is the same as %a.
%b
is the month, using the locale's month names; either the abbreviated or full name may be specified (see the 'abmon' and 'mon' sub-categories of the locale's LC_TIME category).
%B
is the same as %b.
%c
the value of the 'd_t_fmt' sub-category of the locale's LC_TIME category is temporarily used as the format string.
%C
is the century number [0,99]; leading zeros are permitted, but not required.
%d
is the day of the month as a decimal number [01,31]; leading zeros are permitted, but not required.
%D
is the same as %m/%d/%y.
%e
is the same as %d.
%F[n]
is micro-second as a decimal number [0,999999]. Leading zeros are permitted, but not required. An optional precision specification may follow the F. This value must be between 1 and 5.
%iF
Is an Informix backward compatibility modifier which scans like the Informix DBTIME format %F.
%h
same as %b.
%H
is the hour (24-hour clock) as a decimal number [00,23]. Leading zeros are permitted, but not required.
%I
is the hour (12-hour clock) as a decimal number [00,12]. Leading zeros are permitted, but not required.
%j
is the day of the year as a decimal number [001,366]. Leading zeros are permitted, but not required.
%m
is the month as a decimal number [01,12]. Leading zeros are permitted, but not required.
%M
is the minute as a decimal number [00,59]. Leading zeros are permitted, but not required.
%n
is any white space as defined by ifx_gl_ismspace().
%p
is the locale's equivalent of either a.m. or p.m. (see the 'am_pm' sub-category of the locale's LC_TIME category).
%r
the value of the 't_fmt_ampm' sub-category of the locale's LC_TIME category is temporarily used as the format string.
%R
is the time as %H:%M.
%S
is the second as a decimal number [0,61]. Leading zeros are permitted, but not required.
%t
is any white space as defined by ifx_gl_ismspace().
%T
is is the time as %H:%M:%S.
%u
is the weekday as a decimal number [1,7], with 0 representing Sunday. Leading zeros are permitted, but not required.
%w
is the weekday as a decimal number [0,6], with 0 representing Sunday. Leading zeros are permitted, but not required.
%x
the value of the 'd_fmt' sub-category of the locale's LC_TIME category is temporarily used as the format string.
%X
the value of the 't_fmt' sub-category of the locale's LC_TIME category is temporarily used as the format string.
%y
is year within century as a decimal number [00,99]. Leading zeros are permitted, but not required. The century associated with this year is determined from DBCENTURY.
%iy
Is an Informix backward compatibility modifier which scans like the Informix DBDATE format Y2. Both "96" and "1996" would be interpreted as 1996 (or whatever is appropriate according to DBCENTURY).
%Y
is year including the century as a decimal number [0000,9999].
%iY
Is an Informix backward compatibility modifier which scans like the Informix DBDATE format Y4. Both "96" and "1996" would be interpreted as 1996 (or whatever is appropriate according to DBCENTURY).
%%
is replaced by %.

If a conversion specification does not correspond to any of the above, the behaviour is undefined. Modified Directives Some directives specifiers can be modified by the E or O modifier characters to indicate that an alternative format or specification should be used rather than the one normally used by the unmodified directive. If the alternative format or specification does not exist for the current locale, the behavior will be as if unmodified conversion specifications were used.

%Ec
the value of the 'era_d_t_fmt' sub-category of the locale's LC_TIME category is temporarily used as the format string. representation.
%EC
is the name of the base year (period) in the locale's alternative representation. Either the abbreviated or full name may be specified. (see the 'era' sub-category of the locale's LC_TIME category).
%Eg
is the same as %EC.
%Ex
the value of the 'era_d_fmt' sub-category of the locale's LC_TIME category is temporarily used as the format string.
%EX
the value of the 'era_t_fmt' sub-category of the locale's LC_TIME category is temporarily used as the format string.
%Ey
is the offset from %EC (year only) in the locale's alternative representation (see the 'era' sub-category of the locale's LC_TIME category).
%EY
is the full alternative year representation (see the 'era' sub-category of the locale's LC_TIME category).
%Od
is the day of the month using the locale's alternative numeric digits. Leading zeros are permitted, but not required.
%Oe
is the same as %Od.
%OH
is the hour (24-hour clock) using the locale's alternative numeric digits.
%OI
is the hour (12-hour clock) using the locale's alternative numeric digits.
%Om
is the month using the locale's alternative numeric digits
%OM
is the minutes using the locale's alternative numeric digits
%OS
is the seconds using the locale's alternative numeric digits
%Ow
is the weekday as a number using the locale's alternative numeric digits (Sunday=0).
%Oy
is the value of %Ey using the locale's alternative numeric digits.

A directive that is an ordinary character is executed by scanning the next character from the buffer. If the character scanned from the buffer differs from the one comprising the directive, the directive fails, and the differing and subsequent characters remain unscanned.

A series of directives composed of %n, %t, white-space characters or any combination is executed by scanning up to the first character that is not white space (which remains unscanned), or until no more characters can be scanned.

Any other conversion specification is executed by scanning characters until one or more characters matching the next directive is scanned, or until no more characters can be scanned. These characters, except the one matching the next directive, are then compared to the current locale values associated with the conversion specifier. If a match is found, datetime is updated appropriately. Case is ignored when matching items in s such as month or weekday names. If no match if found, no more characters are scanned and failure is returned.

Field Description Specification

An optional field description specification may immediately follow the initial % of a directive for any format specifications which read numeric values. This field description has the following format:

[-|0][<max-width>][.<min-width>]

If the first character of the field description is a minus (-), then the field is assumed to be left justified. In this case the value being read must start with a digit and may be trailed with spaces.

If the first character of the field description is not a minus, then the field is assumed to be right justified. The field may be preceeded with leading spaces unless the first character is a zero (0).

If the first character of field description is a zero, then the field is assumed to be right justifed. Any left had padding must use zeros.

After the optional justification and padding information, an optional maximum field width may be specified. This maximum field width is a decimal number.

Finally, an optional minimum field width may be specified. This minimum field width is defined by a decimal point followed by a decimal number.

Any field description specification will be ignored for non-numeric or compound formats.

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

DEFAULTS

In order to determine the year using era information, the era base, era offset, day and month are needed. A default era offset of 1 will be used if era base, day and month but not era offset are specified.

AMBIGUOUS FORMATS

This section describes how ambiguous formats are handled.

If format contains redundant format specifiers then specifiers that are closer to the the end of the format string will take precedence over ones closer the beginning of the format string.

If %y is used without %C and the month and day of month are part of the input string, then the century is determined from DBCENTURY.

If %C is used without %y then it is ignored.

In order to determine the year from era information, the day, month, and era name must be included in the format. If the era offset is not specified, then an offset of 1 is assumed.

If %I is used without %p, then AM is assumed.

RETURN VALUES

On success, this function returns 0.
On failure, this function returns -1.

ERRORS

If an error has occurred, this function returns -1 and ifx_gl_lc_errno() returns,
[IFX_GL_EBADF]
The format specifier is invalid.
[IFX_GL_EFRACRANGE]
Fraction of Second out of bounds.
[IFX_GL_ESECONDRANGE]
Second out of bounds.
[IFX_GL_EMINUTERANGE]
Minute out of bounds.
[IFX_GL_EHOURRANGE]
Hour out of bounds.
[IFX_GL_EDAYRANGE]
Day number out of bounds.
[IFX_GL_EWKDAYRANGE]
Week Day number out of bounds.
[IFX_GL_EYDAYRANGE]
Year Day number out of bounds.
[IFX_GL_EMONTHRANGE]
Month number out of bounds.
[IFX_GL_EYEARRANGE]
Year number out of bounds.
[IFX_GL_EERAOFFRANGE]
Era offset 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 Day could not be scanned.
[IFX_GL_BADWKDAY]
Week Day could not be scanned.
[IFX_GL_BADYDAY]
Year Day 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.

SEE ALSO

ifx_gl_format_datetime(),

ACKNOWLEDGEMENT

Portions of this description were derived from the X/Open CAE Specification: "System Interfaces and Headers, Issue 4"; X/Open Document Number: C202; ISBN: 1-872630-47-2; Published by X/Open Company Ltd., U.K.