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:
- If the DBTIME environment variable is set, then the datetime is scanned
according to DBTIME.
- If the GL_DATETIME environment variable is set, then the format is scanned according to the specification
of GL_DATETIME.
- 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.