DATE Library Functions
The following date-manipulation functions are in the ESQL/C library. They convert dates between a string format and the internal DATE format.
When you compile your ESQL/C program with the esql command, esql automatically links these functions into your program. The following pages describe each of these functions.
rdatestr()
The rdatestr() function converts an internal DATE to a character string.
Syntax
Usage
For the default locale, U.S. English, the rdatestr() function determines how to interpret the format of the character string with the following precedence:
1. The format that the DBDATE environment variable specifies (if DBDATE is set). For more information on DBDATE, refer to the Informix Guide to SQL: Reference.
2. The format that the GL_DATE environment variable specifies (if GL_DATE is set). For more information on GL_DATE, refer to the Informix Guide to GLS Functionality. 
3. The default date form: mm/dd/yyyy.
When you use a nondefault locale and do not set the DBDATE or GL_DATE environment variable, rdatestr() uses the date end-user format that the client locale defines. For more information, see the Informix Guide to GLS Functionality.
Return Codes
Example
The demo directory contains this sample program in the rtoday.ec file.
Example Output
rdayofweek()
The rdayofweek() function returns the day of the week as an integer value for an internal DATE.
Syntax
Return Codes
Example
The demo directory contains this sample program in the rdayofweek.ec file.
Example Output
rdefmtdate()
The rdefmtdate() function uses a formatting mask to convert a character string to an internal DATE format.
Syntax
Usage
The fmtstring argument of the rdefmtdate() function points to the date-formatting mask, which contains formats that describe how to interpret the date string. For more information on these date formats, see "Formatting Date Strings".
The input string and the fmtstring must be in the same sequential order in terms of month, day, and year. They need not, however, contain the same literals or the same representation for month, day, and year. The following combinations of fmtstring and input are valid.
When you use a two-digit year (yy) in a format, the rdefmtdate() function uses the value of the DBCENTURY environment variable to determine which century to use. If you do not set DBCENTURY, ESQL/C uses the 20th century. For information on how to set DBCENTURY, see the Informix Guide to SQL: Reference.
When you use a nondefault locale whose dates contain eras, you can use extended-format strings in the fmtstring argument of rdefmtdate(). For more information, see the Informix Guide to GLS Functionality.
Return Codes
Example
The demo directory contains this sample program in the rdefmtdate.ec file.
Example Output
rfmtdate()
The rfmtdate() function uses a formatting mask to convert an internal DATE format to a character string.
Syntax
Usage
The fmtstring argument of the rfmtdate() function points to the date-formatting mask, which contains formats that describe how to format the date string. For more information on these date formats, see "Formatting Date Strings".
The examples in the following table use the formatting mask in fmtstring to convert the integer jdate, whose value corresponds to December 25, 1995, to a formatted string outbuf.
When you use a nondefault locale whose dates contain eras, you can use extended-format strings in the fmtstring argument of rfmtdate(). For more information, see the Informix Guide to GLS Functionality.
Return Codes
Example
The demo directory contains this sample program in the rfmtdate.ec file.
/*
* rfmtdate.ec *
The following program converts a date from internal format to
a specified format using rfmtdate().
*/
#include <stdio.h>
main()
{
char the_date[15];
long i_date;
int x;
int errnum;
static short mdy_array[3] = { 12, 21, 1994 };
printf("RFMTDATE Sample ESQL Program running.\n\n");
if ((errnum = rmdyjul(mdy_array, &i_date)) == 0)
{
/*
* Convert date to "mm-dd-yyyy" format
*/
if (x = rfmtdate(i_date, "mm-dd-yyyy", the_date))
printf("First rfmtdate() call failed with error %d\n", x);
else
printf("\tConverted date (mm-dd-yyy): %s\n", the_date);
/*
* Convert date to "mm.dd.yy" format
*/
if (x = rfmtdate(i_date, "mm.dd.yy", the_date))
printf("Second rfmtdate() call failed with error %d\n",x);
else
printf("\tConverted date (mm.dd.yy): %s\n", the_date);
/*
* Convert date to "mmm ddth, yyyy" format
*/
if (x = rfmtdate(i_date, "mmm ddth, yyyy", the_date))
printf("Third rfmtdate() call failed with error %d\n", x);
else
printf("\tConverted date (mmm ddth, yyyy): %s\n", the_date);
}
printf("\nRFMTDATE Sample Program over.\n\n");
}
Example Output
rjulmdy()
The rjulmdy() function creates an array of three short integer values that represent the month, day, and year from an internal DATE value.
Syntax
Return Codes
Example
The demo directory contains this sample program in the rjulmdy.ec file.
/*
* rjulmdy.ec *
The following program converts today's date, represented as an
integer in internal format, to an array of three short integers that
contain the month, day and year.
*/
#include <stdio.h>
main()
{
long i_date;
short mdy_array[3];
int errnum;
char date[20];
int x;
static char fmtstr[9] = "mmddyyyy";
printf("RJULMDY Sample ESQL Program running.\n\n");
/* Allow user to enter a date */
printf("Enter a date as a single string, month.day.year\n");
gets(date);
printf("\nThe date string is %s.\n", date);
/* Put entered date in internal format */
if (x = rdefmtdate(&i_date, fmtstr, date))
printf("Error %d on rdefmtdate conversion\n", x);
else
{
/* Convert from internal format to MDY array */
if ((errnum = rjulmdy(i_date, mdy_array)) == 0)
{
printf("\tThe month component is: %d\n", mdy_array[0]);
printf("\tThe day component is: %d\n", mdy_array[1]);
printf("\tThe year component is: %d\n", mdy_array[2]);
}
else
printf("rjulmdy() call failed with error %d", errnum);
}
printf("\nRJULMDY Sample Program over.\n\n");
}
Example Output
rleapyear()
The rleapyear() function returns 1 (TRUE) when the argument that is passed to it is a leap year and 0 (FALSE) when it is not.
Syntax
Usage
The argument year must be the year component of a date and not the date itself. You must express the year in full form (1996) and not abbreviated form (96).
Return Codes
Example
The demo directory contains this sample program in the rleapyear.ec file.
/*
* rleapyear.ec *
The following program obtains the system date into a long integer,
which stores this date in the internal format.
It then converts the internal format into an array of three short integers
that contain the month, day, and year portions of the date.
It then tests the year value to see if the year is a leap year.
*/
#include <stdio.h>
main()
{
long i_date;
int errnum;
short mdy_array[3];
char date[20];
int x;
static char fmtstr[9] = "mmddyyyy";
printf("RLEAPYEAR Sample Program running.\n\n");
/* Allow user to enter a date */
printf("Enter a date as a single string, month.day.year\n");
gets(date);
printf("\nThe date string is %s.\n", date);
/* Put entered date in internal format */
if (x = rdefmtdate(&i_date, fmtstr, date))
printf("Error %d on rdefmtdate conversion\n", x);
else
{
/* Convert internal format into a MDY array */
if ((errnum = rjulmdy(i_date, mdy_array)) == 0)
{
/* Check if it is a leap year */
if (rleapyear(mdy_array[2]))
printf("%d is a leap year\n", mdy_array[2]);
else
printf("%d is not a leap year\n", mdy_array[2]);
}
else
printf("rjulmdy() call failed with error %d", errnum);
}
printf("\nRLEAPYEAR Sample Program over.\n\n");
}
Example Output
rmdyjul()
The rmdyjul() function creates an internal DATE from an array of three short integer values that represent month, day, and year.
Syntax
Usage
You can express the year in full form (1996) or abbreviated form (96).
Return Codes
Example
The demo directory contains this sample program in the rmdyjul.ec file.
Example Output
rstrdate()
The rstrdate() function converts a character string to an internal DATE.
Syntax
Usage
For the default locale, U.S. English, the rstrdate() function determines how to format the character string with the following precedence:
1. The format that the DBDATE environment variable specifies (if DBDATE is set). For more information on DBDATE, refer to the Informix Guide to SQL: Reference.
2. The format that the GL_DATE environment variable specifies (if GL_DATE is set). For more information on GL_DATE, refer to the Informix Guide to GLS Functionality.
3. The default date form: mm/dd/yyyy. You can use any nonnumeric character as a separator between the month, day, and year. You can express the year as four digits (1995) or as two digits (95).
When you use a nondefault locale and do not set the DBDATE or GL_DATE environment variable, rstrdate() uses the date end-user format that the client locale defines. For more information, see the Informix Guide to GLS Functionality.
When you use a two-digit year in the date string, the rstrdate() function uses the value of the DBCENTURY environment variable to determine which century to use. If you do not set DBCENTURY, rstrdate() assumes the 20th century for two-digit years. For information on how to set DBCENTURY, see the Informix Guide to SQL: Reference.
Return Codes
Example
The demo directory contains this sample program in the rstrdate.ec file.
Example Output
rtoday()
The rtoday() function returns the system date as an internal DATE value.
Syntax
Usage
The rtoday() function obtains the system date on the client computer, not the server computer.
Example
The demo directory contains this sample program in the rtoday.ec file.
Example Output
|
