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.