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

This function creates a string from the the mi_datetime structure pointed to by datetime using the format specified by format. The resulting string is stored in the buffer pointed to by datetimestr and datetimebytes is the size of the output buffer.

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

Each conversion specification is replaced by appropriate characters as desribed in the following list. The appropriate characters are determined by the current locale passed to this function and datetime.
%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

Some conversion 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 conversion specifier. 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.
%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

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

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