The intofmtasc() function

The intofmtasc() function uses a formatting mask to convert an interval variable to a character string.

Syntax

mint intofmtasc(invvalue, outbuf, buflen, fmtstring)
   intrvl_t *invvalue;
   char *outbuf;
   mint buflen;
   char *fmtstring;

invvalue: A pointer to an initialized interval variable to convert.
outbuf: A pointer to the buffer that receives the string for the value in invvalue.
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 interval variable in invvalue with the qualifier that you want the character string to have. If you do not initialize the interval 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 an INTERVAL literal.

The formatting mask, fmtstring, does not need to imply the same qualifiers as the interval variable. When the implied formatting-mask qualifier is different from the interval qualifier, intofmtasc() converts the result to appropriate units, as necessary (as if it called the invextend() function). However, both qualifiers must belong to the same class: either the year to month class or the day to fraction class.

If fmtstring is an empty string, the intofmtasc() function sets outbuf to an empty string.

The formatting directives %B, %b, and %p, which the DBTIME environment variable accepts, are not applicable in fmtstring because month name and a.m./p.m. information is not relevant for intervals of time. Use the %Y directive if the interval is more than 99 years (%y can handle only two digits). For hours, use %H (not %I, because %I can represent only 12 hours). If fmtstring is an empty string, the function returns an error.

If the character string and the formatting mask are acceptable, the intofmtasc() function sets the interval value in invvalue and returns zero. Otherwise, the function returns an error code and the interval variable contains an unpredictable value.

Return codes

0: The conversion was successful.
<0: The conversion failed.

Example

The demo directory contains this sample program in the file intofmtasc.ec.

/*
 *intofmtasc.ec*
 The following program illustrates the conversion of interval values
 to ASCII strings with the specified formats.
*/

#include <stdio.h>

EXEC SQL include datetime;

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

     EXEC SQL BEGIN DECLARE SECTION;
       interval day to minute short_time;
       interval minute(5) to second moment;
     EXEC SQL END DECLARE SECTION;

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

 /* Initialize short_time (day to minute) interval value */
     printf("Interval string #1 = '20 days, 3 hours, 40 minutes'\n");
     x = incvfmtasc("20 days, 3 hours, 40 minutes",
       "%d days, %H hours, %M minutes", &short_time);
   /* Turn the interval into ascii string of a certain format. */
    x = intofmtasc(&short_time, out_str, sizeof(out_str),
      "%d days, %H hours, %M minutes to go!");
   printf("\tFormatted value: %s\n", out_str);

   /* Initialize moment (minute(5) to second interval value */
   printf("\nInterval string #2: '428 minutes, 30 seconds'\n");
   x = incvfmtasc("428 minutes, 30 seconds",
      "%M minutes, %S seconds", &moment);

   /* Turn each interval into ascii string of a certain format. Note
    * that the second and third calls to intofmtasc both use moment
    * as the input variable, but the output strings have different
    * formats.
    */
   x = intofmtasc(&moment, out_str2, sizeof(out_str2),
      "%M minutes and %S seconds left.");
   x = intofmtasc(&moment, out_str3, sizeof(out_str3),
      "%H hours, %M minutes, and %S seconds still left.");

   /* Print each resulting string */
   printf("\tFormatted value: %s\n", out_str2);
   printf("\tFormatted value: %s\n", out_str3);

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

Output

INTOFMTASC Sample ESQL Program running.

Interval string #1: '20 days, 3 hours, 40 minutes'
   Formatted value: 20 days, 03 hours, 40 minutes to go!

Interval string #2: '428 minutes, 30 seconds'
   Formatted value: 428 minutes and 30 seconds left.
   Formatted value: 07 hours, 08 minutes, and 30 seconds still left.

INTOFMTASC Sample Program over.