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
| Code Block |
|---|
#define DATSIZ 9 /* size of a date in MM/DD/YY format */ |
This define was originally declared in USRACC.H. It has been moved to DNTAPI.H.
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
| Code Block |
|---|
#define isLeapYear(yr) /* is yr a leap year? */ |
This is a function-style macro that examines a year and determines whether it is a leap year based on the rules defined for the Gregorian calendar.
...
A non-zero integer value if the year is a leap year, or zero if it is not a leap year.
LDATSIZ
| Code Block |
|---|
#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_*
| Code Block |
|---|
#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).
| Code Block |
|---|
CHAR strMonths[12][10]; /* long month names (0 = January) */ |
A zero-based array of month names in English. The array is defined as follows:
...
10 "November"
11 "December"
strDays
| Code Block |
|---|
CHAR strDays[7][10]; /* long day names (0 = Sunday) */ |
A zero-based array of names of the days of the week in English. The array is defined as follows:
...
4 "Thursday"
5 "Friday"
6 "Saturday"
Functions
addDaysToDate
| Code Block |
|---|
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) */ |
Adds days to or subtracts days from a date in discrete components. If the starting date is invalid or the number of days is out of range (approximately -152000 to 2922365 as of January 1998), the results are undefined.
...
Pointer to a buffer containing the day component of the date. This buffer is updated with the new day.
dateDecode
| Code Block |
|---|
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) */ |
Decodes a U.S. standard date string (MM/DD/YYYY) into discrete components. The year can be two digits, four digits, or not specified. If two digits are used, values less than 80 will be assumed to be in the 2000s and values greater-than or equal-to 80 will be assumed to be in the 1900s. If no year is specified, the current year will be assumed.
...
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
| Code Block |
|---|
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) */ |
Determines the day of the week represented by a date specified in discrete components.
...
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
| Code Block |
|---|
USHORT /* returns GCINVALIDDOT if invalid */
dcdate( /* decode DOS date from "MM/DD[/YY[YY]]"*/
const CHAR *datstr); /* date string to convert */ |
Decodes a U.S. standard date string (MM/DD/YYYY) into a DOS packed date. The year can be two digits, four digits, or not specified. If two digits are used, values less than 80 will be assumed to be in the 2000s and values greater-than or equal-to 80 will be assumed to be in the 1900s. If no year is specified, the current year will be assumed.
...
The date in DOS packed format. If the input date string is not valid, it returns GCINVALIDDOT (0xFFFF).
difDate
| Code Block |
|---|
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 */ |
Computes the number of days between two dates specified in discrete components. If the ending date comes before the beginning date, the result is negative. If either of the dates are not valid, the result is undefined.
...
The number of days between the beginning date and the ending date.
difYear
| Code Block |
|---|
LONG /* < 0 if end year before beg year */
difYear( /* get # days between 1JAN of two years */
INT begYear, /* beginning year */
INT endYear); /* ending year */ |
Computes the number of days between January 1st of two years. If the ending year comes before the beginning year, the result is negative. If either year is out of range (1582 to 9999), the result is undefined.
...
The number of days between January 1st of the beginning and ending years.
lastDayOfMonth
| Code Block |
|---|
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) */ |
Determine the last day of a month. For example, January is always 31 and September is always 30, while February may be 28 or 29, depending on whether or not it is a leap year.
...
The number of the last day of the month (which is also the number of days in the month).
ncdatel
| Code Block |
|---|
const CHAR * /* returns ASCII long date string */
ncdatel( /* encodes date into "MM/DD/YYYY" */
USHORT date); /* packed date */ |
Encodes a DOS packed date into a U.S. standard (MM/DD/YYYY) date string with a four-digit year. If the date specified is not valid, an empty string is returned.
...
A pointer to a single internal buffer containing the date string.
ncedatl
| Code Block |
|---|
const CHAR * /* date string in European long format*/
ncedatl( /* encodes date to DD-MMM-YYYY */
USHORT date); /* packed date */ |
Encodes a DOS packed date into a European (DD-MMM-YYYY) date string with a four-digit year. If the date specified is not valid, an empty string is returned.
...
A pointer to a single internal buffer containing the date string.
prnDate
| Code Block |
|---|
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 */ |
Encodes a date specified in discrete components into a string in a variety of formats. If the date specified is not valid, an empty string is generated.
...
A pointer to the buf argument.
prnTime
| Code Block |
|---|
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 */ |
Encodes a time specified in discrete components into a string in a variety of formats. If the time specified is not valid, an empty string is generated.
...
A pointer to the buf argument.
sDateDecode
| Code Block |
|---|
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) */ |
Decodes a sort format date string into discrete components.
...
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
| Code Block |
|---|
USHORT /* DOS date or GCINVALIDDOT */
sDateDecodeDOS( /* decode "YYYYMMDD" to DOS format */
const CHAR *src); /* encoded date string */ |
Decodes a sort format date string into a DOS packed date.
...
The date in DOS packed format. If the input date string is not valid, it returns GCINVALIDDOT (0xFFFF).
sDateEncode
| Code Block |
|---|
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 */ |
Encodes a date in discrete components to a sort format date string.
...
A pointer to the buf argument.
sDateEncodeDOS
| Code Block |
|---|
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 */ |
Encodes a date in DOS packed format to a sort format date string.
...
A pointer to the buf argument.
sDecodeDT
| Code Block |
|---|
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) */ |
Decodes a string containing a sort format date followed by a sort format time into a date and time in discrete components.
...
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
| Code Block |
|---|
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) */ |
Decodes a string containing a sort format date followed by a sort format time into a date and time in DOS packed format.
...
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
| Code Block |
|---|
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) */ |
Decodes a sort format time string into discrete components.
...
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
| Code Block |
|---|
USHORT /* DOS time or GCINVALIDDOT */
sTimeDecodeDOS( /* decode "HHMMSS" to DOS format */
const CHAR *src); /* encoded time string */ |
Decodes a sort format time string into a DOS packed time.
...
The date in DOS packed format. If the input date string is not valid, it returns GCINVALIDDOT (0xFFFF).
sTimeEncode
| Code Block |
|---|
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 */ |
Encodes a time in discrete components to a sort format time string.
...
A pointer to the buf argument.
sTimeEncodeDOS
| Code Block |
|---|
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 */ |
Encodes a time in DOS packed format to a sort format time string.
...
A pointer to the buf argument.
timeDecode
| Code Block |
|---|
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) */ |
Decodes a standard date string (HH:MM:SS) into discrete components. The seconds portion of the time string is optional. If no second is specified, 00 will be assumed.
...
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
| Code Block |
|---|
const CHAR * /* returns ptr to MM/DD/YYYY */
v2sdatl( /* convert VB date to stg "MM/DD/YYYY" */
DOUBLE vbdat); /* VB DOUBLE precision date/time */ |
Encodes a VB binary date into a U.S. standard (MM/DD/YYYY) date string with a four-digit year. If the date specified is not valid, an empty string is returned.
...
A pointer to a single internal buffer containing the date string.
validDate
| Code Block |
|---|
GBOOL
validDate( /* check for valid date */
INT year, /* year component (1-9999) */
INT month, /* month component (1-12) */
INT day); /* day component (1-31) */ |
Test a date in discrete components for validity.
...
A non-zero value if the date is valid, or zero if the date is not valid.
validDateDOS
| Code Block |
|---|
GBOOL
validDateDOS( /* check for valid DOS date */
USHORT dosDate); /* DOS packed date */ |
Test a date in DOS packed format for validity.
...
A non-zero value if the date is valid, or zero if the date is not valid.
validTime
| Code Block |
|---|
GBOOL
validTime( /* check for valid time */
INT hour, /* hour component (0-23) */
INT minute, /* minute component (0-59) */
INT second); /* second component (0-59) */ |
Test a time in discrete components for validity.
...
A non-zero value if the date is valid, or zero if the date is not valid.
validTimeDOS
| Code Block |
|---|
GBOOL
validTimeDOS( /* check for valid DOS time */
USHORT dosTime); /* DOS packed time */ |
Test a time in DOS packed format for validity.
...
A non-zero value if the date
...
Previous: Major BBS v10: 26 Audit Trail API | Contents | Next: Major BBS v10: 28 Porting WG1/WG2 Source to Worldgroup 3.x