Date and Time API
Applies to: v10
v10 adds
DNTAPI2.H("modernized Gregorian date/time API":dnt2_*,prndat2,prnday2,prntim2) next to theDNTAPI.Hdescribed here. It is present on the v10 branchadd-dntapi2-headerand not inmain;GCOMM.Hincludes it only in the working tree (#include "dntapi2.h"). This chapter'sDNTAPI.Htext is otherwise unchanged.ncdate()/nctime()returnconst CHAR *: chapter 29, section 29.4.
Applies to: WG3.x
Editor's note: this chapter is new in the WG3 layer. It is from section 9 ("Date and Time API") of the Developer's Addendum for Worldgroup 3.12 (
wg312dev; the earlier 3.10 edition,devad3, is the same text apart from "3.10" for "3.12",BC5forBC50, InstallShield V5.0 for V5.1 and spelling). The addendum has no figures. Prose is unrewritten; "Header check" notes record where the printed text disagrees with the WG3.2 headers. It supersedes thencdate()/ncedat()/dcdate()descriptions of chapter 11 for WG3.x; the Visual Basic conversion routines (v2sdatl, ...) are client-side.
Overview
This document outlines changes and additions to the Date and Time API made for Worldgroup 3.12. This document also covers changes to the VB Date and Time API.
The most important changes were For Year 2000 compliance, and the addition of the discrete components format and sort format for dates and times. Many of the functions which take pointers as arguments or return pointers to internal buffers now specify that these are const pointers. A complete list of functions to which const was added will not be given in this document.
Year 2000 Compliance
The primary changes made for year 2000 compliance are improved support for four-digit years in string-format dates. The following defines and functions were changed or added for year 2000 compliance:
| Name | Type | Status |
|---|---|---|
dcdate | Function | Changed |
LDATSIZ | Define | Added |
ncdatel | Function | Added |
ncedatl | Function | Added |
v2sdatl | Function | Added |
Discrete Components Date and Time Format
The most basic binary representation of a date or time is to use separate integer variables to hold the year, month, and day components of a date, and the hour, minute, and second components of a time. This format has now been formalized and will be referred to as the "discrete components" format.
...
| Name | Type | Status |
|---|---|---|
addDaysToDate | Function | Added |
dateDecode | Function | Added |
dayFromDate | Function | Added |
difDate | Function | Added |
difYear | Function | Added |
lastDayOfMonth | Function | Added |
prnDate | Function | Added |
prnTime | Function | Added |
timeDecode | Function | Added |
validDate | Function | Added |
validTime | Function | Added |
Sort Date and Time String Format
In order to provide a date and time string format that is compact, provides a complete representation of the date, and can be used to sort dates easily, the sort date and time string format was defined.
...
| Name | Type | Status |
|---|---|---|
sDateDecode | Function | Added |
sDateDecodeDOS | Function | Added |
sDateEncode | Function | Added |
sDateEncodeDOS | Function | Added |
sDecodeDT | Function | Added |
sDecodeDTDOS | Function | Added |
sTimeDecode | Function | Added |
sTimeDecodeDOS | Function | Added |
sTimeEncode | Function | Added |
sTimeEncodeDOS | Function | Added |
Miscellaneous
A number of identifiers have been changed or added for other reasons. These are as follows:
| Name | Type | Status |
|---|---|---|
DATSIZ | Define | Added |
isLeapYear | Define | Added |
PRND_* | Define | Added |
PRNT_* | Define | Added |
strDays | Variable | Added |
strMonths | Variable | Added |
validDateDOS | Function | Added |
validTimeDOS | Function | Added |
Defines
DATSIZ
#define DATSIZ 9 /* size of a date in MM/DD/YY format */...
Applies to: WG3.x
Header check:
DATSIZis defined as9inDNTAPI.H:137and again, with the identical value, inUStructs.h:16;USRACC.Hno longer defines it.LDATSIZis11(DNTAPI.H:138) andisLeapYear(yr)isDNTAPI.H:192.
isLeapYear
#define isLeapYear(yr) /* is yr a leap year? */...
A non-zero integer value if the year is a leap year, or zero if it is not a leap year.
LDATSIZ
#define LDATSIZ 11 /* size of a date in MM/DD/YYYY format */The size of a character buffer required to hold a U.S. standard format date with a four-digit year (MM/DD/YYYY).
PRND_*, PRNT_*
#define PRND_* /* prnDate format identifiers */
#define PRNT_* /* prnTime format identifiers */These defines have been added to make it easier to use the prndat(), prntim(), prnDate(), and prnTime() functions. See the prnDate() and prnTime() functions for details.
Variables
strMonths
Applies to: WG3.x
Header check: declared
EXPWGSV(CHAR) strMonths[12][10]andstrDays[7][10](DNTAPI.H:196-197).
...
10 "November"
11 "December"
strDays
CHAR strDays[7][10]; /* long day names (0 = Sunday) */...
4 "Thursday"
5 "Friday"
6 "Saturday"
Functions
addDaysToDate
VOID
addDaysToDate( /* get date by adding # days to base */
LONG nDays, /* # days to add (can be negative) */
INT *pYear, /* base year (updated w/ new year) */
INT *pMonth, /* base month (updated w/ new month) */
INT *pDay); /* base day (updated w/ new day) */...
Pointer to a buffer containing the day component of the date. This buffer is updated with the new day.
dateDecode
VOID
dateDecode( /* decode date from "MM/DD[/YY[YY]]" */
const CHAR *src, /* date string */
INT *pYear, /* buffer for year (-1 if bad) */
INT *pMonth, /* buffer for month (-1 if bad) */
INT *pDay); /* buffer for day (-1 if bad) */...
Pointer to a buffer to receive the day component of the date. If the day component of the date string is invalid, this buffer will be filled with -1.
dayFromDate
INT /* day of week (0 = Sun, <0 = error) */
dayFromDate( /* get day of week given date */
INT year, /* year component (1-9999) */
INT month, /* month component (1-12) */
INT day); /* day component (1-31) */...
A zero-based index describing the day of the week (Sunday = 0, Saturday = 6). If the specified date is not valid, a negative value will be returned.
dcdate
USHORT /* returns GCINVALIDDOT if invalid */
dcdate( /* decode DOS date from "MM/DD[/YY[YY]]"*/
const CHAR *datstr); /* date string to convert */...
The date in DOS packed format. If the input date string is not valid, it returns GCINVALIDDOT (0xFFFF).
difDate
LONG /* < 0 if end date before beg date */
difDate( /* compute # days between dates */
INT begYear, /* year component of first date */
INT begMonth, /* month component of first date */
INT begDay, /* day component of first date */
INT endYear, /* year component of second date */
INT endMonth, /* month component of second date */
INT endDay); /* day component of second date */...
The number of days between the beginning date and the ending date.
difYear
LONG /* < 0 if end year before beg year */
difYear( /* get # days between 1JAN of two years */
INT begYear, /* beginning year */
INT endYear); /* ending year */...
The number of days between January 1st of the beginning and ending years.
lastDayOfMonth
INT /* number of last day (e.g. Jan = 31) */
lastDayOfMonth( /* get highest day in given month/year */
INT month, /* number of month (1-12) */
INT year); /* year in question (1-9999) */...
The number of the last day of the month (which is also the number of days in the month).
ncdatel
const CHAR * /* returns ASCII long date string */
ncdatel( /* encodes date into "MM/DD/YYYY" */
USHORT date); /* packed date */...
A pointer to a single internal buffer containing the date string.
ncedatl
const CHAR * /* date string in European long format*/
ncedatl( /* encodes date to DD-MMM-YYYY */
USHORT date); /* packed date */...
A pointer to a single internal buffer containing the date string.
prnDate
CHAR * /* returns pointer to buffer */
prnDate( /* form formatted date string */
INT year, /* year component (1-9999) */
INT month, /* month component (1-12) */
INT day, /* day component (1-31) */
CHAR *buf, /* buffer to receive formatted date */
size_t bufSiz, /* size of buffer */
INT mode, /* format mode */
CHAR sep); /* separator character */...
A pointer to the buf argument.
prnTime
CHAR * /* returns pointer to buffer */
prnTime( /* form formatted time string */
INT hour, /* hour component (0-23) */
INT minute, /* minute component (0-59) */
INT second, /* second component (0-59) */
CHAR *buf, /* buffer to receive formatted time */
size_t bufSiz, /* size of buffer */
INT mode); /* format mode */...
A pointer to the buf argument.
sDateDecode
VOID
sDateDecode( /* decode "YYYYMMDD" */
const CHAR *src, /* encoded date string */
INT *pYear, /* buffer for year (-1 if bad) */
INT *pMonth, /* buffer for month (-1 if bad) */
INT *pDay); /* buffer for day (-1 if bad) */...
Pointer to a buffer to receive the day component of the date. If the day component of the date string is invalid, this buffer will be filled with -1.
sDateDecodeDOS
USHORT /* DOS date or GCINVALIDDOT */
sDateDecodeDOS( /* decode "YYYYMMDD" to DOS format */
const CHAR *src); /* encoded date string */...
The date in DOS packed format. If the input date string is not valid, it returns GCINVALIDDOT (0xFFFF).
sDateEncode
CHAR * /* returns pointer to buffer */
sDateEncode( /* encode date to "YYYYMMDD" */
INT year, /* year component (1-9999) */
INT month, /* month component (1-12) */
INT day, /* day component (1-31) */
CHAR *buf, /* buffer to receive encoded date */
size_t bufSiz); /* size of buffer */...
A pointer to the buf argument.
sDateEncodeDOS
CHAR * /* returns pointer to buffer */
sDateEncodeDOS( /* encode DOS date to "YYYYMMDD" */
USHORT dosDate, /* DOS packed date */
CHAR *buf, /* buffer to receive encoded date */
size_t bufSiz); /* size of buffer */...
A pointer to the buf argument.
sDecodeDT
VOID
sDecodeDT( /* decode "YYYYMMDD[ ]HHMMSS" */
const CHAR *src, /* encoded date string */
INT *pYear, /* buffer for year (-1 if bad) */
INT *pMonth, /* buffer for month (-1 if bad) */
INT *pDay, /* buffer for day (-1 if bad) */
INT *pHour, /* buffer for hour (-1 if bad) */
INT *pMinute, /* buffer for minute (-1 if bad) */
INT *pSecond); /* buffer for second (-1 if bad) */...
Pointer to a buffer to receive the second component of the time. If the second component of the time string is invalid, this buffer will be filled with -1.
sDecodeDTDOS
VOID
sDecodeDTDOS( /* decode "YYYYMMDD[ ]HHMMSS" to DOS fmt*/
const CHAR *src, /* encoded date string */
USHORT *pDate, /* buf for date (GCINVALIDDOT if bad) */
USHORT *pTime); /* buf for time (GCINVALIDDOT if bad) */...
Pointer to a buffer to receive the time in DOS packed format. If the time is not valid, this buffer will be filled with GCINVALIDDOT (0xFFFF).
sTimeDecode
VOID
sTimeDecode( /* decode "HHMMSS" */
const CHAR *src, /* encoded date string */
INT *pHour, /* buffer for hour (-1 if bad) */
INT *pMinute, /* buffer for minute (-1 if bad) */
INT *pSecond); /* buffer for second (-1 if bad) */...
Pointer to a buffer to receive the second component of the time. If the second component of the time string is invalid, this buffer will be filled with -1.
sTimeDecodeDOS
USHORT /* DOS time or GCINVALIDDOT */
sTimeDecodeDOS( /* decode "HHMMSS" to DOS format */
const CHAR *src); /* encoded time string */...
The date in DOS packed format. If the input date string is not valid, it returns GCINVALIDDOT (0xFFFF).
sTimeEncode
CHAR * /* returns pointer to buffer */
sTimeEncode( /* encode time to "HHMMSS" */
INT hour, /* hour component (0-23) */
INT minute, /* minute component (0-59) */
INT second, /* second component (0-59) */
CHAR *buf, /* buffer to receive encoded time */
size_t bufSiz); /* size of buffer */...
A pointer to the buf argument.
sTimeEncodeDOS
CHAR * /* returns pointer to buffer */
sTimeEncodeDOS( /* encode DOS time to "HHMMSS" */
USHORT dosTime, /* DOS packed time */
CHAR *buf, /* buffer to receive encoded time */
size_t bufSiz); /* size of buffer */...
A pointer to the buf argument.
timeDecode
VOID
timeDecode( /* decode time from "HH:MM[:SS]" */
const CHAR *src, /* encoded date string */
INT *pHour, /* buffer for hour (-1 if bad) */
INT *pMinute, /* buffer for minute (-1 if bad) */
INT *pSecond); /* buffer for second (-1 if bad) */...
Pointer to a buffer to receive the second component of the time. If the second component of the time string is invalid, this buffer will be filled with -1.
v2sdatl
const CHAR * /* returns ptr to MM/DD/YYYY */
v2sdatl( /* convert VB date to stg "MM/DD/YYYY" */
DOUBLE vbdat); /* VB DOUBLE precision date/time */...
A pointer to a single internal buffer containing the date string.
validDate
GBOOL
validDate( /* check for valid date */
INT year, /* year component (1-9999) */
INT month, /* month component (1-12) */
INT day); /* day component (1-31) */...
A non-zero value if the date is valid, or zero if the date is not valid.
validDateDOS
GBOOL
validDateDOS( /* check for valid DOS date */
USHORT dosDate); /* DOS packed date */...
A non-zero value if the date is valid, or zero if the date is not valid.
validTime
GBOOL
validTime( /* check for valid time */
INT hour, /* hour component (0-23) */
INT minute, /* minute component (0-59) */
INT second); /* second component (0-59) */...
A non-zero value if the date is valid, or zero if the date is not valid.
validTimeDOS
GBOOL
validTimeDOS( /* check for valid DOS time */
USHORT dosTime); /* DOS packed time */...