The dttofmtasc() function

Syntax

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

dtvalue

A pointer to the initialized datetime variable to convert.

outbuf

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

buflen

The length of the outbuf buffer.

fmtstring

A pointer to the 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).

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 HCL OneDB 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 HCL OneDB GLS User's Guide.

Return codes

0

The conversion was successful.

<0

The conversion failed. Check the text of the error message.

Example

/* *dttofmtasc.ec*
    The following program illustrates the conversion of a datetime
    value into strings of different formats.
*/

#include <stdio.h>

EXEC SQL include datetime;

main()
{
   char out_str1[25];
   char out_str2[25];
   char out_str3[30];
   mint x;

   EXEC SQL BEGIN DECLARE SECTION;
       datetime month to minute birthday;
   EXEC SQL END DECLARE SECTION;

   printf("DTTOFMTASC Sample ESQL Program running.\n\n");

   /* Initialize birthday to "09-06 13:30" */
   printf("Birthday datetime (month to minute) value = ");
   printf("September 6 at 01:30 pm\n");
   x = dtcvfmtasc("September 6 at 01:30 pm","%B %d at %I:%M %p",
       &birthday);

   /* Convert the internal format to ascii for 3 given display formats.
    * Note that the second format does not include the minutes field and 
    * that the last format includes a year field even though birthday was 
    * not initialized as year to minute.
    */

   x = dttofmtasc(&birthday, out_str1, sizeof(out_str1), 
      "%d %B at %H:%M");
   x = dttofmtasc(&birthday, out_str2, sizeof(out_str2), 
      "%d %B at %H");
   x = dttofmtasc(&birthday, out_str3, sizeof(out_str3), 
      "%d %B, %Y at%H:%M");   /* Print out the three forms of the same date */
   printf("\tFormatted value (%%d %%B at %%H:%%M) = %s\n", out_str1);
   printf("\tFormatted value (%%d %%B at %%H) = %s\n", out_str2);
   printf("\tFormatted value (%%d %%B, %%Y at %%H:%%M) = %s\n", out_str3);

   printf("\nDTTOFMTASC Sample Program over.\n\n");
}

Output

DTTOFMTASC Sample ESQL Program running.

Birthday datetime (month to minute) value = September 6 at 01:30 pm
   Formatted value (%d %B at %H:%M)  = 06 September at 13:30
   Formatted value (%d %B at %H)) = 06 September at 13
   Formatted value (%d %B, %Y at %H:%M)) = 06 September, 2007 at 13:30

DTTOFMTASC Sample Program over.