The ifx_dtcvfmtasc() function

Syntax

mint ifx_dtcvfmtasc(input, fmtstring, d, dbcentury)
   char *input;
   char *fmtstring;
   dtime_t *d;

   char dbcentury;

input

A pointer to the buffer that contains the string to convert.

fmtstring

A pointer to the buffer that contains the formatting mask to use for the input 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).

d

A pointer to the initialized datetime variable.

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 d with the qualifier that you want this variable to have. The datetime variable does not need to specify the same qualifier that the formatting mask implies. When the datetime qualifier is different from the implied formatting-mask qualifier, ifx_dtcvfmtasc() extends the datetime value (as if it had called the dtextend() function).

All qualifier fields in the character string in input must be contiguous. In other words, if the qualifier is hour to second, you must specify all values for hour, minute, and second somewhere in the string, or the ifx_dtcvfmtasc() function returns an error.

The input character string can have leading and trailing spaces. However, from the first significant digit to the last, input can contain only digits and delimiters that are appropriate for the qualifier fields that the formatting mask implies. For more information about acceptable digits and delimiters for a DATETIME value, see the ANSI SQL standards for DATETIME and INTERVAL values.

The ANSI SQL format specifies a qualifier of year to second for the output. You can express the year as four digits (2007) or as two digits (07). When you use a two-digit year (%y) in a formatting mask, the ifx_dtcvfmtasc() function uses the value of the dbcentury argument to determine which century to use. If you do not set the dbcentury argument, ifx_dtcvfmtasc() uses the DBCENTURY environment variable to determine which century to use. If you do not set DBCENTURY, ifx_dtcvfmtasc() assumes the current century for two-digit years. For information about the DBCENTURY environment variable, 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, ifx_dtcvfmtasc() uses the default DATETIME format that the locale defines. For more information, see the Informix® GLS User's Guide.

When the character string and the formatting mask are acceptable, the ifx_dtcvfmtasc() function sets the datetime variable in d and returns zero. Otherwise, it returns an error code and the datetime variable contains an unpredictable value.

Return codes

0

The conversion was successful.

<0

The conversion failed.