ifx_gl_format_date - Format a date value.

---

SYNOPSIS

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

DESCRIPTION

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

%a

is replaced by the locale's abbreviated weekday name (see the 'abday' sub-category of the locale's LC_TIME category).

%A

is replaced by the locale's full weekday name (see the 'day' sub-category of the locale's LC_TIME category).

%b

is replaced by the locale's abbreviated month name (see the 'abmon' sub-category of the locale's LC_TIME category).

%B

is replaced by the locale's full month name (see the 'mon' sub-category of the locale's LC_TIME category).

%C

is replaced by the century number (the year divided by 100 and truncated to an integer as a decimal number [00-00].

%d

is replaced by the day of the month as a decimal number [01,31].

%D

is the same as %m/%d/%y.

%e

is replaced by the day of the month as a decimal number [1,31]; a single digit is preceeded by a space.

%h

same as %b.

%j

is replaced by the day of the year as a decimal number [001,366].

%m

is replaced by the month as a decimal number [01,12].

%n

is replaced by a newline character.

%t

is replaced by a tab character.

%u

Is replaced by the weekday as a decimal number [1,7], with 1 representing Monday.

%w

is replaced by the weekday as a decimal number [0,6], with 0 representing Sunday.

%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 replaced by year without century as a decimal number [00,99].

%iy

Is an Informix backward compatibility modifier which formats like the Informix DBDATE format Y2. This will print the two digit year offset.

%Y

is replaced by year with century as a decimal number [00,99].

%iY

Is an Informix backward compatibility modifier which formats like the Informix DBDATE format Y4. This will print the full four digit year.

%%

is replaced by %.

If a conversion specification does not correspond to any of the above, the behavior is undefined.

Modified Conversion Specifiers

%EC

is replaced by the name of the base year (period) in the locale's alternative representation (see the 'era' sub-category of the locale's LC_TIME category).

%Eg

is replaced by the abbreviated name of the base year (period) in the locale's alternative representation (see the 'era' sub-category of the locale's LC_TIME category).

%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 replaced by 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 replaced by the full alternative year representation (see the 'era' sub-category of the locale's LC_TIME category).

%Oe

is replaced by the day of the month, using the locale's alternative numeric digits, filled as needed with leading spaces.

%Om

is replaced by the month using the locale's alternative numeric digits

%Ou

is replaced by the weekday as a number using the locale's alternative numeric digits (Monday=1).

%Oy

is replaced by the value of %Ey using the locale's alternative numeric digits.

Field Width and Precision

An optional justification, field width and precision specification can immediately follow the initial % of a directive according to the following:

[-|0][<width>][.<precision>]

justification

If the specification begins with a minus (-) then the field will be left justified and padded with spaces on the right. If the value begins with a zero (0) then the field will be right justified and padded with zeros on the left. Otherwise, the value will be right justified and padded with spaces on the left.

width

<width> is a decimal value which specifies a minimum field width for the conversion and <width> is specified in terms of display width. <width> is ignored when scanning strings.

precision

The field width specifier may be followed by a precision directive defined to be a period followed by a decimal value.

For the C, d, e, Ey, iy, iY, j, m, u, w, y and Y directives, the value of <precision> specifies the minimum number of digits to appear. If a directive supplies fewer digits than specified by the precision, it will be padded with leading zeros.

For the a, A, b, B, EC, Eg, and h, directives, the value of <precision> specifies the maximum number of characters to be used. If a value to be formatted has more characters than specified by the precision, the result will be truncated on the right.

The values of <width> and <precision> do not affect the Ex, EY, n, t, x or %.

The values of <width> and <precision> affect each element of the D directive. For example %6.4D would be printed as "%6.4m/%6.4d/%6.4y".

For the directives modified with O (Alternate Digits) the field width and relates to display width rather than actual number of digits. The precision is still the minimum number of digits printed.

The d, Ey, iy, m, u, w, and y directives have a default precision of .2.

The j directive has a default precision of 3.

The Y and iY directives have a default precision of 4.

RETURN VALUES

ERRORS

[IFX_GL_EBADF]

The format specifier is invalid.

[IFX_GL_E2BIG]

Operation would overflow buffer.

[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]

Era name not found.

[IFX_GL_BADERAOFFSET]

Era offset could not be scanned.

SEE ALSO

ACKNOWLEDGEMENT