The dtcvfmtasc() function

The dtcvfmtasc() function uses a formatting mask to convert a character string to a datetime value.

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 HCL OneDB™ 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 dtcvfmtasc() function returns an error if the formatting mask, fmtstring, is an empty string. If fmtstring is a null pointer, the dtcvfmtasc() function must determine the format to use when it reads the character string in inbuf. When you use the default locale, the function uses the following precedence:
  1. The format that the DBTIME environment variable specifies (if DBTIME is set)

    For more information, see the HCL OneDB Guide to SQL: Reference.

  2. The format that the GL_DATETIME environment variable specifies (if GL_DATETIME is set)

    For more information, see the HCL OneDB GLS User's Guide.

  3. The default date format that conforms to the standard ANSI SQL format: 
    %iY-%m-%d %H:%M:%S

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 HCL OneDB 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 HCL OneDB 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.