The ifx_gl_format_date() function

The ifx_gl_format_date() function formats an internal date value to a date string.

Syntax

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

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


Valid in client application	Valid in DataBlade® UDR
Yes	Yes

Usage

The ifx_gl_format_date() function uses the format that the format string specifies to format the internal date representation in date as a date string. It stores the resulting date string in a buffer that datestr references.

The date argument is a pointer to a date (4-byte int) value.

The date argument is a pointer to an mi_date value.

Format string

If format is NULL, the ifx_gl_format_date() function determines the format for the datestr date string that it creates from the environment, as follows:

If the DBDATE environment variable is set, the function scans datestr according to the order of the format elements in DBDATE.
If the GL_DATE environment variable is set, the function scans datestr according to the specification of GL_DATE.
Otherwise, the function obtains the format from the d_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 datestr date string, ifx_gl_format_date() 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 `date` argument. It replaces the formatting directive with a string representation of a date element for the `datestr` date string.
Ordinary characters	The function copies the ordinary character unchanged to the `datestr` date 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_date() function to use when it creates a date element of a datestr string. These date formats are formats that the LC_TIME locale-file category of the current locale might define. The ifx_gl_format_date() function supports the following formatting directives to represent a date element.

%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: Replaced by the century number (the year divided by 100 and truncated to an integer as a decimal number in the range 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.
%h: Same as %b.
%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.
%n: Replaced by a newline character.
%t: Replaced by a tab character.
%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.
%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 in the range 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_date() function supports the following format modifier.

O: Use alternative locale-specific digits in dates.
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_date() function supports the following modified formatting directives with the O modifier.

%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.
%Om: Replaced by the month, using the alternative digits that the alt_digits subcategory of LC_TIME defines.
%Ou: Replaced by the weekday as a number, using the alternative digits that the alt_digits subcategory of LC_TIME defines (Monday=1).

The ifx_gl_format_date() 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.

%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 datestr 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 directive. 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, %iy, %iY, %j, %m, %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, %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.
%a, %A, %b, %B, %h	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.
%n, %t, %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 date 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_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_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.