The intofmtasc() function

Syntax

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

invvalue

A pointer to the initialized interval variable to convert.

outbuf

A pointer to a buffer to contain the string for the value in invvalue.

buflen

The length of the outbuf buffer.

fmtstring

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 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. and 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 incvfmtasc() 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 values

0

The conversion was successful.

<0

The conversion failed.