The dtcvfmtasc() function

Syntax

mint dtcvfmtasc(inbuf, fmtstring, dtvalue)
   char *inbuf;
   char *fmtstring;
   dtime_t *dtvalue;

inbuf

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

fmtstring

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

dtvalue

A pointer to an initialized datetime variable.

Usage

You must initialize the datetime variable in dtvalue 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, dtcvfmtasc() extends the datetime value (as if it had called the dtextend() function).

All qualifier fields in the character string in inbuf 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 dtcvfmtasc() function returns an error.

The inbuf character string can have leading and trailing spaces. However, from the first significant digit to the last, inbuf can contain only digits and delimiters that are appropriate for the qualifier fields that the formatting mask implies.

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 dtcvfmtasc() function uses the value of the DBCENTURY environment variable to determine which century to use. If you do not set DBCENTURY, dtcvfmtasc() 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 U.S. English) and do not set the DBTIME or GL_DATETIME environment variables, dtcvfmtasc() uses the default date and time 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 dtcvfmtasc() function sets the datetime variable in dtvalue and returns zero. Otherwise, it returns an error code and the datetime variable contains an unpredictable value.

Return values

0

The conversion was successful.

<0

The conversion failed.