The dttofmtasc() function

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

Syntax

mint dttofmtasc(dtvalue, outbuf, buflen, fmtstring)
   dtime_t *dtvalue;
   char *outbuf;
   mint buflen;
   char *fmtstring;
dtvalue
A pointer to an initialized datetime variable.
outbuf
A pointer to a buffer to contain the string for the value in dtvalue.
buflen
The length of the outbuf buffer.
fmtstring
is a pointer to a buffer that contains the formatting mask to use for the outbuf 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.)

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 dtextend() function).

If the formatting mask is an empty string, the function sets character string in 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:
  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

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() uses 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, dttofmtasc() uses the default DATETIME format that the client locale defines. For more information, see the HCL OneDB GLS User's Guide.

Return values

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