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 the 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 the 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. 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 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 US English) and do not set the DBTIME or GL_DATETIME environment variables, dtcvfmtasc() uses the default DATETIME 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 codes

0

The conversion was successful.

<0

The conversion failed.

Example

/* *dtcvfmtasc.ec*
 The following program illustrates the conversion of several ascii strings
 into datetime values.
*/

#include <stdio.h>

EXEC SQL include datetime;

main()
{
   char out_str[17],  out_str2[17],  out_str3[17]; mint x;

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

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

   /* Initialize birthday to "09-06 13:30" */
   printf("Birthday #1 = 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 in ANSI format, for displaying. */
   x = dttoasc(&birthday, out_str);
   printf("Datetime (month to minute) value = %s\n\n", out_str);
 /* Initialize birthday2 to "07-14-88 09:15" */
   printf("Birthday #2 = July 14, 1988. Time: 9:15 am\n");
   x = dtcvfmtasc("July 14, 1988. Time: 9:15am", 
      "%B %d, %Y. Time: %I:38p",  &birthday2);

   /*Convert the internal format to ascii in ANSI format, for displaying. */
x = dttoasc(&birthday2, out_str2);
   printf("Datetime (year to minute) value = %s\n\n", out_str2);
 /* Initialize birthday3 to "07-14-XX 09:15" where XX is current year.
   * Note that birthday3 is year to minute but this initialization only
   * provides month to minute. dtcvfmtasc provides current information
   * for the missing year.
 */
   printf("Birthday #3 = July 14. Time: 9:15 am\n");
   x = dtcvfmtasc("July 14. Time: 9:15am", "%B %d. Time: %I:%M %p",
      &birthday3);

 /* Convert the internal format to ascii in ANSI format, for displaying. */
   x = dttoasc(&birthday3, out_str3);
   printf("Datetime (year to minute) value with current year = %s\n", 
      out_str3);

    printf("\nDTCVFMTASC Sample Program over.\n\n");

}

Output

DTCVFMTASC Sample ESQL Program running.

Birthday #1 = September 6 at 01:30 pm
Datetime (month to minute) value = 09-06 13:30

Birthday #2 = July 14, 1988 Time: 9:15 am
Datetime (year to minute) value =  2007-07-14 09:15

Birthday #3 = July 14. Time: 9:15 am
Datetime  (year to minute) value with current year = 2007-07-14 09:15

DTCVFMTASC Sample Program over.