The ifx_dttofmtasc() function

The ifx_dttofmtasc() function uses a formatting mask to convert a datetime variable to a character string.

Syntax

mint dttofmtasc(dtvalue, output, str_len, fmtstring, dbcentury)
   dtime_t *dtvalue;
   char *outbuf;
   mint buflen;
   char *fmtstring;

d

A pointer to the initialized datetime variable to convert.

output

A pointer to the buffer that receives the string for the value in d.

str_len

The length of the output buffer.

fmtstring

A pointer to the buffer that contains the formatting mask to use for the output string. This time-formatting mask contains the same formatting directives that the DBTIME environment variable supports. (For a list of these directives, see the description of DBTIME in the Informix® Guide to SQL: Reference).

dbcentury

Can be one of the following characters, which determines which century to apply to the year portion of the date:

R: Present. The function uses the two high-order digits of the current year to expand the year value.
P: Past. The function uses the past and present centuries to expand the year value. It compares these two dates against the current date and uses the century that is before the current century. If both dates are before the current date, the function uses the century closest to the current date.
F: Future. The function uses the present and the next centuries to expand the year value. It compares these centuries against the current date and uses the century that is later than the current date. If both dates are later than the current date, the function uses the date closest to the current date.
C: Closest. The function uses the past, present, and next centuries to expand the year value. It chooses the century that is closest to the current date.

Usage

You must initialize the datetime variable in dtvalue with the qualifier that you want the character string to have. If you do not initialize the datetime variable, the function returns an unpredictable value. The character string in outbuf does not include the qualifier or the parentheses that SQL statements use to delimit a DATETIME literal.

The formatting mask, fmtstring, does not need to imply the same qualifiers as the datetime variable. When the implied formatting-mask qualifier is different from the datetime qualifier, dttofmtasc() extends the datetime value (as if it called the dttofmtasc() function).

If the formatting mask is an empty string, the function sets character string, outbuf, to an empty string. If fmtstring is a null pointer, the dttofmtasc() function must determine the format to use for the character string in outbuf. When you use the default locale, the function uses the following precedence:

The format that the DBTIME environment variable specifies (if DBTIME is set). For more information about DBTIME, see the Informix® Guide to SQL: Reference.
The format that the GL_DATETIME environment variable specifies (if GL_DATETIME is set). For more information about GL_DATETIME, see the Informix® GLS User's Guide.
The default date format that conforms to the standard ANSI SQL format:
```
%iY-%m-%d %H:%M:%S
```

When you use a two-digit year (%y) in a formatting mask, the dttofmtasc() function uses the value of the DBCENTURY environment variable to determine which century to use. If you do not set DBCENTURY, dttofmtasc() assumes the present century for two-digit years. For information about how to set DBCENTURY, see the Informix® Guide to SQL: Reference.

When you use a nondefault locale (one other than US English) and do not set the DBTIME or GL_DATETIME environment variables, dttofmtasc() uses the default DATETIME format that the client locale defines. For more information, see the Informix® GLS User's Guide.

Return codes

0: The conversion was successful.
<0: The conversion failed. Check the text of the error message.