ifx_gl_convert_date - Convert a date string to an internal representation.

SYNOPSIS

#include <ifxgls.h>
int ifx_gl_convert_date(mi_date *date, char *datestr, char *format)

DESCRIPTION

This function converts the date string stored in datestr into an internal representation. The internal representation is stored in the mi_date structure pointed to by date in the format specified by format.

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

  1. If the DBDATE environment variable is set, then the date is scanned according to the order of the format elements in DBDATE.
  2. If the GL_DATE environment variable is set then the format is scanned according to the specification of GL_DATE.
  3. Otherwise the d_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
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.
%e
is the same as %d.
%h
same as %b.
%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.
%n
is any white space as defined by ifx_gl_ismspace().
%t
is any white space as defined by ifx_gl_ismspace().
%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.
%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 the DBCENTURY setting.
%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
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.
%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.
%Om
is the month 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, then date 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.

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.

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_INVALIDFMT]
Invalid formatted argument string
[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_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]
Invalid Era name
[IFX_GL_BADERAOFFSET]
Invalid Era offset
[IFX_GL_BADFMTMOD]
Invalid Format modifer
[IFX_GL_BADFMTWP]
Invalid width/precision
[IFX_GL_BADINPUT]
Input string doesn't match format
[IFX_GL_NOPOINT]
Missing decimal point in input
[IFX_GL_BADMONTHSTR]
Month string could not be scanned
[IFX_GL_BADFMTMOD]
Invalid Format modifer
[IFX_GL_BADFMTWP]
Invalid width/precision
[IFX_GL_BADINPUT]
Input string doesn't match format
[IFX_GL_BADMONTHSTR]
Month string could not be scanned
[IFX_GL_BADERASPEC]
Couldn't load era from locale

SEE ALSO

ifx_gl_format_date(),

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.