The ifx_gl_format_datetime() function

The ifx_gl_format_datetime() function formats an internal date/time value to a date/time string.

Syntax

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

datetimestr: A pointer to the first character in the date/time string that the function formats from its internal datetime representation.
datetimebytes: The size of the datetimestr buffer for the date/time string. This size is the maximum size that the formatted string can reach.
datetime: A pointer to the variable that holds the internal representation that ifx_gl_format_datetime() formats to create the datetimestr date/time string.
format: A pointer to the format string that determines how to interpret the datetimestr date/time string. For more information, see Format string.


Valid in client application	Valid in DataBlade® UDR
Yes	Yes

Usage

The ifx_gl_format_datetime() function uses the format that the format string specifies to format the internal date/time representation in datetime as a date/time string. It stores the resulting date/time string in a buffer that datetimestr references.

The datetime argument is a pointer to a datetime (dtime_t) value.

The datetime argument is a pointer to an mi_datetime value.

Format string

If format is NULL, the ifx_gl_format_datetime() function determines the format of the datetimestr date/time string that it creates from the environment, as follows:

If the DBTIME environment variable is set, the function formats datetimestr according toDBTIME.
If the GL_DATETIME environment variable is set, the function formats datetimestr according to the specification of GL_DATETIME.
Otherwise, the function obtains the format from the d_t_fmt subcategory of the LC_TIME category in the current GLS locale file.

If format is not NULL, it must point to a string that follows the rules that this section describes. To format the datetimestr date/time string, ifx_gl_format_datetime() takes the following actions for each possible character that it finds in format.


Contents of format string	Conversion action taken
Valid formatting directives	The function performs the specified formatting of the data in the `datetime` argument. It replaces the formatting directive with a string representation of a date or time element for the `datetimestr` date/time string.
Ordinary characters	The function copies the ordinary character unchanged to the `datetimestr` date/time string. Ordinary characters include the null terminator and white space characters.

The formatting directive consists of the following sequence:

%[modifiers][flag][width][.precision]type_specifier


Argument	See
`modifiers`	Modified formatting directives
`flag`	Field width and precision
`width`	Field width and precision
`precision`	Field width and precision
`type_specifier`	Valid type specifiers

Tip: In the preceding format sequence, the square brackets indicate that the enclosed portion of the format is optional.

Valid type specifiers

The type specifier is a letter or letters within a formatting directive that identify a format for the ifx_gl_format_datetime() function to use when it creates a date or time element of a datetimestr string. These date and time formats are formats that the LC_TIME locale-file category of the current locale might define. The ifx_gl_format_datetime() function supports the following formatting directives to represent a date or time element that the LC_TIME locale-file category of the current locale might define.

%a: Replaced by the abbreviated weekday name that the abday subcategory of LC_TIME defines.
%A: Replaced by the full weekday name that the day subcategory of LC_TIME defines.
%b: Replaced by the abbreviated month name that the abmon subcategory of LC_TIME defines.
%B: Replaced by the full month name that the mon subcategory of LC_TIME defines.
%c: Indicates use of the format that the d_t_fmt subcategory of LC_TIME defines.
%C: Replaced by the century number (the year divided by 100 and truncated to an integer as a decimal number [00-00]).
%d: Replaced by the day of the month as a decimal number in the range 1 - 31.
%D: Same as %m/%d/%y.
%e: Replaced by the day of the month as a decimal number in the range 1 - 31; a single digit is preceded by a space.
%F[n]: Replaced by the microsecond as a decimal number. An optional precision specification, n, can follow F. This n value must be 1 - 5.
%h: Same as %b.
%H: Replaced by the hour (24-hour clock) as a decimal number in the range 0 - 23.
%I: Replaced by the hour (12-hour clock) as a decimal number in the range 0 -12.
%j: Replaced by the day of the year as a decimal number in the range 1 - 366.
%m: Replaced by the month as a decimal number in the range 1 -12.
%M: Replaced by the minute as a decimal number in the range 0- 59.
%n: Replaced by a newline character.
%p: Replaced by the locale equivalent of either a.m. or p.m. that the am_pm subcategory of LC_TIME defines.
%r: Indicates use of the format that the t_fmt_amp subcategory of LC_TIME defines.
%R: Replaced by the time in 24-hour notation (%H:%M).
%S: Replaced by the second as a decimal number.
%t: Replaced by a tab character.
%T: Replaced by the time (%H:%M:%S).
%u: Replaced by the weekday as a decimal number in the range 1 - 7, with 1 representing Monday.
%w: Replaced by the weekday as a decimal number in the range 0 - 6, with 0 representing Sunday.
%x: Indicates use of the format that the d_fmt subcategory of LC_TIME defines.
%X: Indicates use of the format that the t_fmt subcategory of LC_TIME defines.
%y: Replaced by year without century as a decimal number in the range 0 - 99.
%Y: Replaced by year with century as a decimal number 0 - 99.
%%: Replaced by the % symbol.

If a formatting directive does not correspond to any of the preceding directives, the behavior of the conversion is undefined.

Modified formatting directives

You can modify some formatting directives with format modifiers, which follow the percent symbol (%), to indicate use of an alternative format that the LC_TIME locale-file category of the current locale might define. The ifx_gl_format_datetime() function supports the following format modifier.

O: Use alternative locale-specific digits in dates and times.
LC_TIME subcategory: alt_digits

The alternative format replaces one that an unmodified formatting directive normally uses. If the alternative format does not exist for the current locale, the behavior is the same as if unmodified formatting directives were used. The ifx_gl_format_datetime() function supports the following modified formatting directives with the O modifier.

%Ey: Replaced by the offset from %EC (year only) that the era subcategory of LC_TIME defines.
%Oe: Replaced by the day of the month, using the alternative digits that the alt_digits subcategory of LC_TIME defines. This formatting directive fills as needed with leading spaces.
%OH: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to format the hour (24-hour clock).
%OI: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to format the hour (12-hour clock).
%Om: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to format the month.
%OM: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to format the minutes.
%OS: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to format the seconds.
%Ou: Uses the alternative digits that the alt_digits subcategory of LC_TIME defines to format the weekday as a number (Monday=1).

The ifx_gl_format_datetime() function also supports the i modifier in the following formatting directives to support formats that are compatible with earlier HCL Informix® date and time formatting.

%iF[n]: Replaced by the Informix DBTIME format %F. An optional precision specification, n, can follow F. This n value must be 1 - 5.
%iy: Replaced by the Informix DBDATE format Y2. This format prints the two-digit year offset.
%iY: Replaced by the Informix DBDATE format Y4. This format prints the full four-digit year.

Field width and precision

You can also specify an optional field width and precision in a formatting directive. This information precedes the type specifier in the formatting directive and has the following format:

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

[- | 0]: Indicates field justification.
If the specification begins with a minus sign (-), the function left-aligns the field and pads it with spaces on the right. If the value begins with 0, the function right-aligns the field and pads it with zeros on the left. Otherwise, the function right-aligns the field and pads it with spaces on the left.
width: A decimal value that specifies a minimum field width for the formatted datetimestr value.
precision: The format has the format of a period (.) followed by a decimal value. The field width specifier can optionally be followed by a precision directive. For more information about the purpose of precision, see the following table.

The values of width and precision affect each element of the %D, %R, and %T directives. For example, %6.4D is interpreted as "%6.4m/%6.4d/%6.4y".

The precision value has the following effects on the different formatting directives.


Formatting directives	Effect of precision
%C, %d, %e, %F, %H, %iF, %iy, %iY, %I, %j, %m, %M, %S, %u, %w, %y, %Y	The value of `precision` specifies the minimum number of digits to appear. If a directive supplies fewer digits than `precision` specifies, the function pads the value with leading zeros. The %d, %H, %iF, %iy, %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.
%a, %A, %b, %B, %h, %p	The value of `precision` specifies the maximum number of characters to be used. If a value to be formatted has more characters than the `precision` specifies, the function truncates the result on the right.
%c, %n, %r, %t, %x, %X, %%	The values of `width` and `precision` do not affect these directives.
Directives modified with O (alternative digits)	The field `width` relates to display width rather than actual number of digits; `precision` is still the minimum number of digits printed.

Locale information

The LC_TIME category of the current locale affects the behavior of this function because it provides the locale-specific information for the formatting of the datetime value.

Return values

0: The function was successful.
-1: The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurs, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.

IFX_GL_E2BIG: Formatting stopped due to lack of space in the buffer.
IFX_GL_EBADF: A formatting directive is invalid.
IFX_GL_EFRACRANGE: Fraction of second is out of bounds.
IFX_GL_ESECONDRANGE: Second is out of bounds.
IFX_GL_EHOURRANGE: Hour is out of bounds.
IFX_GL_EMINUTERANGE: Minute is out of bounds.
IFX_GL_EDAYRANGE: Day number is out of bounds.
IFX_GL_EWKDAYRANGE: Weekday number is out of bounds.
IFX_GL_EYDAYRANGE: Year day number is out of bounds.
IFX_GL_EMONTHRANGE: Month number is out of bounds.
IFX_GL_EYEARRANGE: Year number is 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 (as a number) could not be scanned.
IFX_GL_BADWKDAY: Weekday (as a number) could not be scanned.
IFX_GL_BADYDAY: Day of year (as a number) could not be scanned.
IFX_GL_BADMONTH: Month could not be scanned.
IFX_GL_BADYEAR: Year could not be scanned.