ifx_gl_format_datetime - Format a datetime value.

---

SYNOPSIS

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

DESCRIPTION

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 formatted according to DBTIME.
2. If the GL_DATETIME environment variable is set, then the format is formatted 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

%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

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 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.

%F[n]

is replaced by the micro-second as a decimal number. An optional precision specification may follow the F. This value must be between 1 and 5.

%iF[n]

Is an Informix backward compatibility modifier which formats like the Informix DBTIME format %F. An optional precision specification may follow the F. This value must be between 1 and 5.

%h

same as %b.

%H

is replaced by the hour (24-hour clock) as a decimal number [00,23].

%I

is replaced by the hour (12-hour clock) as a decimal number [00,12].

%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].

%M

is replaced by the minute as a decimal number [00,59].

%n

is replaced by a newline character.

%p

is replaced by 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 replaced by the time in 24 hour notation (%H:%M).

%S

is replaced by the second as a decimal number.

%t

is replaced by a tab character.

%T

is replaced by is replaced by the time (%H:%M:%S).

%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.

%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 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 behaviour is undefined.

Modified Conversion Specifiers

%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.

%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.

%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 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.

%OH

is replaced by the hour (24-hour clock) using the locale's alternative numeric digits

%OI

is replaced by the hour (12-hour clock) using the locale's alternative numeric digits

%Om

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

%OM

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

%OS

is replaced by seconds 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>]

[-|0]

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 the <width> is 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, F, H, iF, iy, iY, I, j, m, M, S, 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, h, and p 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 c, Ec, Ex, EX, EY, r, n, t, x, X or %.

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

The F and iF directives may be followed by an optional precision specification. For example, "%F3" means precision of 3. The value of this precision must be between 1 and 5. If it is not between 1 and 5, then an error is returned. This specification overrides the precision value between the % and the directive if it is given.

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, H, iF, iy, I, m, M, S, 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.

The F directive has a default precision of 6.

RETURN VALUES

ERRORS

[IFX_GL_EBADF]

The format specifier is invalid.

[IFX_GL_E2BIG]

Operation would overflow buffer.

[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

ACKNOWLEDGEMENT