INFORMIX-ESQL/C Programmer's Manual ESQL/C Function Library

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

mint dttofmtasc(dtvalue, outbuf, buflen, fmtstring)

	dtime_t  *dtvalue;

	char  *outbuf;

	mint buflen;

	char *fmtstring;

 



dtvalue

is a pointer to the initialized datetime variable to convert. 


outbuf

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


buflen

is the length of the outbuf buffer.


fmtstring  

is 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, ../sqlr/intro.htmler to the description of DBTIME in the Informix Guide to SQL: Reference). 

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, 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 on DBTIME, ../sqlr/intro.htmler to the Informix Guide to SQL: Reference.
2. The format that the GL_DATETIME environment variable specifies (if GL_DATETIME is set). For more information on GL_DATETIME, refer to the Informix Guide to GLS Functionality.
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() assumes the present century for two-digit years. For information on how to set DBCENTURY, see the Informix 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 Informix Guide to GLS Functionality.

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

/* *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");
}

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, 1994 at 13:30

DTTOFMTASC Sample Program over.