Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Date and Time API

Applies to: v10

v10 adds DNTAPI2.H ("modernized Gregorian date/time API": dnt2_*, prndat2, prnday2, prntim2) next to the DNTAPI.H described here. It is present on the v10 branch add-dntapi2-header and not in main; GCOMM.H includes it only in the working tree (#include "dntapi2.h"). This chapter's DNTAPI.H text is otherwise unchanged. ncdate()/nctime() return const 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", BC5 for BC50, 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 the ncdate()/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:

NameTypeStatus
dcdateFunctionChanged
LDATSIZDefineAdded
ncdatelFunctionAdded
ncedatlFunctionAdded
v2sdatlFunctionAdded

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.

...

NameTypeStatus
addDaysToDateFunctionAdded
dateDecodeFunctionAdded
dayFromDateFunctionAdded
difDateFunctionAdded
difYearFunctionAdded
lastDayOfMonthFunctionAdded
prnDateFunctionAdded
prnTimeFunctionAdded
timeDecodeFunctionAdded
validDateFunctionAdded
validTimeFunctionAdded

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.

...

NameTypeStatus
sDateDecodeFunctionAdded
sDateDecodeDOSFunctionAdded
sDateEncodeFunctionAdded
sDateEncodeDOSFunctionAdded
sDecodeDTFunctionAdded
sDecodeDTDOSFunctionAdded
sTimeDecodeFunctionAdded
sTimeDecodeDOSFunctionAdded
sTimeEncodeFunctionAdded
sTimeEncodeDOSFunctionAdded

Miscellaneous

A number of identifiers have been changed or added for other reasons. These are as follows:

NameTypeStatus
DATSIZDefineAdded
isLeapYearDefineAdded
PRND_*DefineAdded
PRNT_*DefineAdded
strDaysVariableAdded
strMonthsVariableAdded
validDateDOSFunctionAdded
validTimeDOSFunctionAdded

Defines

DATSIZ

#define DATSIZ 9 /* size of a date in MM/DD/YY format */

...

Applies to: WG3.x

Header check: DATSIZ is defined as 9 in DNTAPI.H:137 and again, with the identical value, in UStructs.h:16; USRACC.H no longer defines it. LDATSIZ is 11 (DNTAPI.H:138) and isLeapYear(yr) is DNTAPI.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] and strDays[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                    */

...