Date and Time Manipulation

Reference Section

_add_time
_asc_date
_asc_time
_asc_to_date
_asc_to_time
_date_to_asc
_date_to_asce
_date_to_days
_days_to_date
_diff_time
dtc_addr
_dtc_init
_get_clock
_get_date
_get_day
_get_time
_hund_to_time
_init_msec
_merge_date
_merge_time
_set_clock
_set_date
_set_time
_sleep_msec
_sleep_sec
_split_date
_split_time
_ticks_to_time
_time_to_asc
_time_to_asce
_time_to_hund
_time_to_ticks
_tmr_read
_tmr_reset

_add_time


Descrip
Adds two times.

Syntax
#include <datetime.h>
std_time *_add_time(std_time *time1, const std_time *time2);

Returns
A pointer to time1.
time1 sum of time1 and time2

Notes
This function returns a pointer to time1, which contains the result of adding time1 to time2. The time value in time1 will never be greater than 255:59:59.99. If the sum of time1 and time2 is greater than 255:59:59.99, the result is not accurate.

The std_time structure is defined as follows:

typedef struct {
unsigned char hseconds;
unsigned char seconds;
unsigned char minutes;
unsigned char hours;
} std_time;

By using add_time with inline assembly, an unsigned long value may be obtained which allows time values to be compared directly.

C/C++ Example
	{
	   std_time time1, time2;
	   time1.hours = 10;/* time1 = 10:30:00.00 */
	   time1.minutes = 30;
	   time1.seconds = 0;
	   time1.hseconds = 0;
	   time2.hours = 10;/* time2 = 10:10:00.00 */
	   time2.minutes = 10;
	   time2.seconds = 0;
	   time2.hseconds = 0;
	   _add_time(&time1, &time2);
	   	  	 /* time1 = 20:40:00.00 */
	}

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned long sumtime;
	   ...
	   mov ch,10	/* CL = hours */
	   mov cl,30	/* CH = minutes */
	   mov bh,0	/* BH = seconds */
	   mov bl,0	/* BL = hseconds */
	   	  	 	/* (time1 = 10:30:00.00) */
	   mov dh,10	/* DH = hours */
	   mov dl,10	/* DL = minutes */
	   mov ah,0	/* AH = seconds */
	   mov al,0	/* AL = hseconds */
	   	  	 	/* (time2 = 10:10:00.00) */
	   sumtime = add_time();/* sumtime = 20:40:00.00 */
	   ...
	}

Source file _DTADTME.ASM ASM equiv ADD_TIME
See also
_diff_time, _get_time, _merge_time

_asc_date


Descrip
Creates an ASCIIZ date string in MM/DD/YY format.

Syntax
#include <datetime.h>
char *_asc_date(char *string, const std_date *adate)

Returns
A pointer to string.
string the ASCIIZ date string generated from adate ("MM/DD/YY")

Notes
This function uses the contents of the date structure adate to construct an ASCIIZ date string in string. The date string has the form MM/DD/YY, where MM represents the month number, DD represents the day number, and YY represents the last two digits of the year. Month, day, and year numbers are always zero padded.

C/C++ Example
	{
	   char datestr[20];
	   std_date adate;
	   ...
	   adate.year= 1992;
	   adate.day= 4;
	   adate.month= 7;
	   _put_str(_asc_date(datestr, &adate)); /* "07/04/92" */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char datestr[20];
	   ...
	   mov dx,1992	    /* DX = year */
	   mov ah,7	/* AH = month */
	   mov al,4	/* AL = day */
	   pushds
	   pop es	 	/* ES=SS(segment of datestr) */
	   lea si,datestr/* SI = offset of datestr */
	   asc_date();
	   put_str();	/* "07/04/92" */
	   ...
	}

Source file _DTASCDT.ASM ASM equiv ASC_DATE
See also
_asc_to_date, _date_to_asc, _get_date

_asc_time


Descrip
Creates an ASCIIZ time string in HH:MM Xm format.

Syntax
#include <datetime.h>
char *_asc_time(char *string, const std_time *atime);

Returns
A pointer to string.
string the ASCIIZ time string generated from atime ("HH:MM am/pm")

Notes
This function uses the contents of the time structure atime to construct an ASCIIZ time string in string. The time string has the form HH:MM Xm, where HH represents hours, MM represents minutes, and Xm represents "am" or "pm". Hours and minutes are always padded with zeros.

The std_time structure is defined as follows:

typedef struct {
unsigned char hseconds;
unsigned char seconds;
unsigned char minutes;
unsigned char hours;
} std_time;

C/C++ Example
	{
	   char timestr[20];
	   std_time atime;
	   atime.hours = 13;
	   atime.minutes = 30;
	   _put_str(_asc_time(timestr, &atime)); /* "01:30 pm" */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char timestr[20];
	   mov dh,13	/* DH = hours */
	   mov dl,30	/* DL = minutes */
	   xor ax,ax	/* AX = seconds, 100ths */
	   lea si,timestr /* SI = offset timestr */
	   pushds
	   pop es	 	/* ES=DS (small data models) */
	   asc_time();	/* DX;AX = time (long format) */
	   put_str();	/*  "01:30 pm" */
	   ...
	}

Source file _DTASCTM.ASM ASM equiv ASC_TIME
See also
_asc_to_time, _get_time, _time_to_asc

_asc_to_date


Descrip
Converts a formatted ASCII date string to date structure format.

Syntax
#include <datetime.h>
int _asc_to_date(char *instr, unsigned char flags, unsigned char width, const std_date *adate);
Returns
1 if numeric overflow occurred.
adate undefined

0 if the conversion was successful.
adate date in std_date structure format converted from instr

-1 if underflow occurred or an invalid format was encountered.
adate undefined

Notes
This function reads a formatted ASCII date from instr and converts it to a date in std_date structure format. The expected format of instr is specified in flags as well as the current date/time conversion options structure. If the format is not the same as specified, the date fields may be interpreted incorrectly. If the conversion is successful, 0 is returned and the adate structure contains the date. 1 is returned if numeric overflow occurs while reading any required field (DAY, MONTH, YEAR). -1 is returned if underflow occurs (instr is a NULL string) or an invalid format is detected (a required field is missing, zero, empty, or contains invalid characters). For example, if three fields were expected, then "//92", "2/A/92", and "11/12" would all generate an invalid format errors.

Conversion options specified in flags consist of date field order flags and date field suppress flags. The following symbolic constants (defined in DATETIME.H) may be bitwise ORed together to specify the expected date format:

Date field order flags:

DATE_CDATE(0x00) Use format from dtcopts structure
DATE_DMY (0x01) Use DAY/MONTH/YEAR format
DATE_YMD (0x02) Use YEAR/MONTH/DAY format
DATE_MDY (0x03) Use MONTH/DAY/YEAR format

Date field suppress flags:

DATE_NOYR (0x04) Suppress year field
DATE_NOMON(0x08) Suppress month field
DATE_NODAY(0x10) Suppress day field

Only those subfields specified in flags are actually read and stored; the remaining fields are neither read nor stored. If instr contains more fields than are required for the read, leading fields must match the specified format and trailing fields are ignored. The year field is read correctly whether the year is specified in 2-digit or 4-digit format; the years "80" to "99" represent 1980 to 1999 and the years "00" to "79" represent 2000 to 2079.

The current date/time conversion options structure specifies global formatting options such as the country-default date format and the date delimiter character. These options may be accessed or modified through the dtc_addr variable. (See dtc_addr for further information.)

Leading white space characters are not automatically skipped. To skip leading white space characters, call _str_skipw or _str_skips before calling this function.

C/C++ Example
	{
	   dtcopts dtc = {0,'-',0,':','.'," am", " pm"};
	   std_date adate;
	   unsigned long date;
	   dtc_addr = &dtc; /* use dtc structure (conversion info) */
	   _asc_to_date("12-25-1992", DATE_MDY+DATE_4DIGYR, 80, &adate);
	   	  	 /* adate contains date */
	}

Inline Assembly Example
	#include <inline.h>
	{
	   dtcopts dtc = {0,'-',0,':','.'," am", " pm"};
	   char instr[] = "10-16-1992";
	   ... 
	   dtc_addr = &dtc;/* use dtc struct (conv. info) */
	   lea si,instr/* SI -> instr */
	   mov ch,DATE_MDY+DATE_4DIGYR /* set conv. flags */
	   mov cl,80	/* CL = width */
	   asc_to_date();	/* DX;AX = dword date */
	}

Source file _DTATODT.ASM ASM equiv ASC_TO_DATE
See also
_asc_date, _date_to_asc, _get_date

_asc_to_time


Descrip
Converts a formatted ASCII time string to time structure format.

Syntax
#include <datetime.h>
int _asc_to_time(char *instr, unsigned char flags, unsigned char width, const std_time *atime);

Returns
-1 if underflow occurred or an invalid format was detected.
atime undefined

0 if the conversion was successful.
atime the resulting time in std_time structure format

1 if numeric overflow occurred.
atime undefined

Notes
This function reads a formatted ASCII time from instr and converts it to a time in std_time structure format. The expected format of instr is specified in flags as well as the current date/time conversion options structure. If the format is not the same as specified, the time fields may be interpreted incorrectly. If the conversion is successful, 0 is returned and the atime structure contains the time. -1 is returned if no useable characters are found in instr. 1 is returned if numeric overflow occurs while reading any required field (HR, MIN, SEC, HSEC).

Conversion flags specified in flags consist of format flags, field flags, and leading zero flags. The following symbolic constants (defined in DATETIME.H) may be used by bitwise Oring them together to specify the expected time format:

Time format flags:

TIME_CTIME (0x03) Use time format from dtcopts structure (country)
TIME_12HR (0x01) Use 12-hour format
TIME_24HR (0x02) Use 24-hour format
TIME_FLEXHR (0x00) Writes TIME_CTIME, reads both 12-hour and 24-hour formats

If instr is read in 12-hour format, space characters in the dtc_amstr and dtc_pmstr fields are considered optional; the AM/PM match is also case insensitive. For example, dtc_amstr = "AM" will match the AM string portion of the input string "12:24:56 am". Trailing AM/PM strings are ignored if instr is read in 24-hour format.

Time field flags:

TIME_HR (0x00) Use hour field
TIME_NOHR (0x04) Suppress hour field
TIME_MIN (0x00) Use minute field
TIME_NOMIN(0x08) Suppress minute field
TIME_SEC (0x00) Use second field
TIME_NOSEC(0x10) Suppress second field
TIME_100THS(0x00) Use 100ths field
TIME_NO100THS(0x20) Suppress 100ths field

The time field flags specify which fields are to be read from instr. Most significant fields are read first (from left to right). Suppressed fields are not read and are not modified in atime (e.g., if TIME_NOSEC+TIME_NO100THS is the specified flag combination, the expected input format is "HH:MM" and only hours and minutes are modified in atime). If any expected trailing fields are missing, the corresponding portions of atime are set to zero (e.g., atime.hseconds = 0 if the 100ths field is expected but missing).

The current date/time conversion options structure specifies global formatting options such as the country-default time format, the time delimiter character, and the 100ths separator character. These options may be accessed or modified through the dtc_addr variable. (See dtc_addr for further information.)

The std_time structure is defined in DATETIME.H as follows:

typedef struct {
unsigned char hseconds;
unsigned char seconds;
unsigned char minutes;
unsigned char hours;
} std_time;

Leading white space characters are not automatically skipped. If white space characters must be skipped, call _str_skipw or _str_skips before calling this function.

C/C++ Example
	{
	   dtcopts dtc = {0,'-',0,':','.'," morning", " evening"};
	   std_time atime;
	   dtc_addr = &dtc; /* use DTC structure (conversion info) */
	   _asc_to_time("12:59:59:00 morning", TIME_12HR, 80, &atime);
	   	  	 /* atime contains converted time */
	}

Inline Assembly Example
	#include <inline.h>
	{
	   dtcopts dtc = {0,'-',0,':','.'," morning", " evening"};
	   char instr[] = "11:59:59:00 morning";
	   long time;
	   ... 
	   dtc_addr = &dtc;/* use DTC struct (conv. info) */
	   lea si,instr/* SI -> instr */
	   mov ch,TIME_12HR/* CH = conversion flags */
	   mov cl,80	/* CL = width */
	   time = asc_to_time();/* DX;AX = dword time */
	   ...
	}

Source file _DTATOTM.ASM ASM equiv ASC_TO_TIME
See also
_asc_time, _get_time, _time_to_asc

_date_to_asc


Descrip
Converts a date in structure format to a formatted ASCIIZ string.

Syntax
#include <datetime.h>
char *_date_to_asc(const std_date *adate, unsigned char flags, unsigned char width, char *outstr);

Returns
A pointer to outstr.
outstr resulting ASCIIZ representation of adate in the specified format

NULL if the length of the resulting string would have exceeded width.
outstr undefined

Notes
This function converts adate to a formatted ASCIIZ date string in outstr. The date string has the format specified in flags and in the current date/time conversion options structure. If the conversion is successful, a pointer is returned to the resulting date string. NULL is returned and outstr is left in an undefined state if the result would have exceeded width characters in length.

adate must be a structure of type std_date (defined in DATETIME.H) as follows:

typedef struct {
unsigned char day;
unsigned char month;
unsigned int year;
unsigned char day-of-week; /* not used by this function */
} std_date;

Conversion options specified in flags consist of field order flags, field suppress flags, leading zero flags, and year digits flags. The following symbolic constants (defined in DATETIME.H) may be bitwise ORed together to specify the date string format:

Date field order flags:

DATE_CDATE (0x00) Use format from dtcopts structure
DATE_DMY (0x01) Use DAY/MONTH/YEAR format
DATE_YMD (0x02) Use YEAR/MONTH/DAY format
DATE_MDY (0x03) Use MONTH/DAY/YEAR format

Date field suppress flags:

DATE_NOYR (0x04) Suppress year field
DATE_NOMON (0x08) Suppress month field
DATE_NODAY (0x10) Suppress day field

Date leading zero flags:

DATE_PADMON (0x00) Leading zero in month field
DATE_NOPADMON (0x20) No leading zero in month field
DATE_PADDAY (0x00) Leading zero in day field
DATE_NOPADDAY (0x40) No leading zero in day field

Year digits flags:

DATE_2DIGYR (0x00) Use 2 digits in year field ("93")
DATE_4DIGYR (0x80) Use 4 digits in year field ("1993")

Two-digit format assumes the years "80" to "99" represent 1980 to 1999 and the years "00" to "79" represent 2000 to 2079.

The current date/time conversion options structure specifies global formatting options such as the country-default date format and the date delimiter character. These options may be accessed or modified through the dtc_addr variable. (See dtc_addr for further information.)

WARNING! outstr must be large enough to hold the converted string plus a terminating NULL (width+1 bytes in size) or data following the buffer will be overwritten.

C/C++ Example
	{
	   dtcopts dtc = {0,'-',0,':','.'," am", " pm"};
	   char outstr[80];
	   std_date adate;
	   ...
	   dtc_addr = &dtc;/* use dtc structure (conversion info) */
	   adate.year = 1992;
	   adate.day = 25;
	   adate.month = 12;/* adate contains date to convert */
	   _put_str(_date_to_asc(&adate, DATE_MDY, 80, outstr));
	   	  	 /* "12-26-1992" */
	}

Inline Assembly Example
	#include <inline.h>
	{
	   dtcopts dtc = {0,'-',0,':','.'," am", " pm"};
	   char outstr[80];
	   ... 
	   dtc_addr = &dtc;/* use dtc struct (conv. info) */
	   mov ch,DATE_MDY+DATE_4DIGYR /*CH = conv. flags */
	   mov cl,80	/* CL = width of buffer */
	   lea si,outstr/* SI -> outstr */
	   mov  dx,1992	/* DX = year */
	   mov ah,12	/* AH = month */
	   mov al,25	/* AL = day */
	   date_to_asc();	/* date -> "string" */
	   put_str();	/* "16-10-1992" */
	   ...
	}

Source file _DTDTASC.ASM ASM equiv DATE_TO_ASC
See also
_asc_date, _asc_to_date, _date_to_asc, dtc_addr

_date_to_asce


Descrip
Converts a date in structure format to a formatted ASCII string, returning a pointer to the end of the resulting string.

Syntax
#include <datetime.h>
char *_date_to_asce(const std_date *adate, unsigned char flags, unsigned char width, char *outstr);

Returns
A pointer to the character after the last converted character in outstr.
outstr resulting ASCII representation of adate in the specified format

NULL if the length of the resulting string would have exceeded width.
outstr undefined

Notes
This function converts adate to a formatted ASCII date string in outstr. The date string is not NULL terminated and has the format specified in flags and in the current date/time conversion options structure. The returned pointer identifies the next available position in outstr (past the result). A subsequent call to _str_cpy or _str_cpye will append data to the result more rapidly than is possible with _date_to_asc. NULL is returned if the result would have exceeded width characters in length.

adate must be a structure of type std_date (defined in DATETIME.H) as follows:

typedef struct {
unsigned char day;
unsigned char month;
unsigned int year;
unsigned char day-of-week; /* not used by this function */
} std_date;

Conversion options specified in flags consist of field order flags, field suppress flags, leading zero flags, and year digits flags. The following symbolic constants (defined in DATETIME.H) may be bitwise ORed together to specify the date string format:

Date field order flags:

DATE_CDATE(0x00) Use format from dtcopts structure
DATE_DMY (0x01) Use DAY/MONTH/YEAR format
DATE_YMD (0x02) Use YEAR/MONTH/DAY format
DATE_MDY (0x03) Use MONTH/DAY/YEAR format

Date field suppress flags:

DATE_NOYR (0x04) Suppress year field
DATE_NOMON(0x08) Suppress month field
DATE_NODAY(0x10) Suppress day field

Date leading zero flags:

DATE_PADMON(0x00) Leading zero in month field
DATE_NOPADMON(0x20) No leading zero in month field
DATE_PADDAY(0x00) Leading zero in day field
DATE_NOPADDAY(0x40) No leading zero in day field

Year digits flags:

DATE_2DIGYR(0x00) Use 2 digits in year field ("93")
DATE_4DIGYR(0x80) Use 4 digits in year field ("1993")

Two-digit year format assumes the years "80" to "99" represent 1980 to 1999 and the years "00" to "79" represent 2000 to 2079.

The current date/time conversion options structure specifies global formatting options such as the country-default date format and the date delimiter character. These options may be accessed or modified through the dtc_addr variable. (See dtc_addr for further information.)

Current date/time conversion options may be accessed and modified through the dtc_addr variable.

WARNING! outstr must be at least width bytes in size or data following the buffer will be overwritten.

C/C++ Example
	{
	   dtcopts dtc = {0,'-',0,':','.'," am", " pm"};
	   char *outstr;
	   std_date adate;
	   ...
	   dtc_addr = &dtc;/* use dtc struct (conv. info) */
	   adate.year = 1992;
	   adate.month = 12;
	   adate.day = 25;/* adate contains date to convert */
	   outstr = "         is today's date.";
	   _date_to_asce(&adate, DATE_MDY, 80, outstr);
	   _put_str(outstr);/* "10-16-92 is today's date." */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   dtcopts dtc = {0,'-',0,':','.'," am", " pm"};
	   char outstr[] = "         is today's date.";
	   ... 
	   dtc_addr = &dtc;/* use dtc struct (conv. info) */
	   mov ch,DATE_MDY/* CH = conversion flags */
	   mov cl,80	/* CL = width of buffer */
	   lea si,outstr/* SI -> outstr */
	   mov  dx,1992	/* DX = year */
	   mov ah,12	/* AH = month */
	   mov al,25	/* AL = day */
	   date_to_asce();    /* date -> "string..." */
	   lea si,outstr/* reset SI -> outstr */
	   put_str();	/* "12-25-92 is today's date" */
	   ...
	}

Source file _DTDTACE.ASM ASM equiv DATE_TO_ASCE
See also
_asc_date, _asc_to_date, _date_to_asc, dtc_addr

_date_to_days


Descrip
Returns the number of days between January 1, 1980 and a given date.

Syntax
#include <datetime.h>
unsigned int _date_to_days(const std_date *ddate);

Returns
The number of days elapsed since January 1, 1980.

Notes
This function calculates the number of days between January 1, 1980 and ddate and returns the result as an unsigned int. A ddate of 01-01-1980 returns 0, a ddate of 01-02-1980 returns 1, and so forth. The result is accurate for dates from 01-01-1980 to 12-31-2099. The result is undefined if ddate is outside this range.

ddate must be a structure of type std_date (defined in DATETIME.H) as follows:

typedef struct {
unsigned char day;
unsigned char month;
unsigned int year;
unsigned char day-of-week; /* not used by this function */
} std_date;

C/C++ Example
	{
	   unsigned int numdays;
	   std_date ddate;
	   ...
	   ddate.year= 1980;/* ddate = 01-06-1980 */
	   ddate.month= 1;
	   ddate.day= 6;
	   numdays = _date_to_days(&ddate);/* numdays = 5 */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned int numdays;
	   ...
	   mov dx,1980	    	  /* DX = year */
	   mov ah,1	    /* AH = month */
	   mov al,6	    /* AL = day */
	   	  	 	    /* date = 01-06-1980 */
	   numdays = date_to_days();/* numdays = 5 */
	   ...
	}

Source file _DTDTDYS.ASM ASM equiv DATE_TO_DAYS
See also
_days_to_date, _time_to_hund

_days_to_date


Descrip
Fills a structure with the date which corresponds to a specified number of days since January 1, 1980.

Syntax
#include <datetime.h>
void _days_to_date(int numdays, std_date *ddate);

Returns
No return value.
ddate the date representation of numdays

Notes
This function calculates the date which is numdays from January 1, 1980. The calculated date is returned in ddate. If numdays is 0, ddate is set to 01-01-1980; if numdays is 1, ddate is set to 01-02-1980, and so forth. The result is accurate for numdays values in the range 0 to 43,829 (i.e., ddate values in the range 01-01-1980 to 12-31-2099). The result is undefined if numdays lies outside this range.

The std_date structure is defined in DATETIME.H as follows:

typedef struct {
unsigned char day;
unsigned char month;
unsigned int year;
unsigned char day-of-week;/* 0=Sunday, 1=Monday, ... */
} std_date;

C/C++ Example
	{
	   std_date ddate;
	   _days_to_date(10, &ddate);/* ddate = 01-11-1980 */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned long date;
	...
	mov ax,10	 /* AX = days from 01-01-1980 */
	date = days_to_date();/* date = 1/11/1980 */
	...
	}

Source file _DTDYSDT.ASM ASM equiv DAYS_TO_DATE
See also
_date_to_days, _hund_to_time

_diff_time


Descrip
Calculates the difference between two times.

Syntax
#include <datetime.h>
std_time *_diff_time( std_time *time1, const std_time *time2);

Returns
A pointer to time1.
time1 the chronological difference between time1 and time2

Notes
This function calculates the chronological difference between time1 and time2, where time1 is assumed to be a time which was read prior to time2, and the system clock may have wrapped past midnight before time2 was read. For example, if time1 is 23:59:00.0 and time2 is 0:01:00.0, the chronological difference is 0:02:00.0 (i.e., only two minutes elapsed, even though the absolute difference between the two times is 23:58:00.0).

The std_time structure is defined as follows:

typedef struct {
unsigned char hseconds;
unsigned char seconds;
unsigned char minutes;
unsigned char hours;
} std_time;

C/C++ Example
	{
	   static std_time time1, time2;
	   time1.hours = 23;	/* time1 = 23:59:00.00 */
	   time1.minutes= 59;
	   time1.seconds= 0;
	   time1.hseconds= 0;
	   time2.hours = 0;	/* time2 = 00:01:00.00 */
	   time2.minutes= 1;
	   time2.seconds= 0;
	   time2.hseconds= 0;
	   _diff_time(&time1, &time2);/* time1 = 00:02:00.00 */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned long diftime;
	   ...
	   mov ch,23	/* time1 = 23:59:00.00 */
	   mov cl,59
	   mov bh,0
	   mov bl,0
	   mov dh,0	/* time2 = 00:01:00.00 */
	   mov dl,1
	   mov ah,0
	   mov al,0
	   diftime = diff_time();  /* diftime = 00:02:00.00 */
	   ...
	}

Source file _DTDIFTM.ASM ASM equiv DIFF_TIME
See also
_add_time

dtc_addr


Descrip
(Variable) Contains the address of the current date/time conversion options structure.

Syntax
#include <dataconv.h>
extern dtcopts *dtc_addr;

Notes
This near/far pointer maintains the address of the current date/time conversion options (dtcopts) structure. In small data models (TINY, SMALL, MEDIUM), this pointer is a near pointer which contains the offset of the structure within the default data segment (global or static non-far data). In large data models (COMPACT, LARGE, HUGE), this variable is a far pointer which contains the segment and offset of the structure.

The current dtcopts structure specifies global date/time conversion formatting options and is used by _asc_to_date, _asc_to_time, _date_to_asc, _time_to_asc, and the scripted I/O functions. The behavior of these functions may be changed by modifying this structure or by modifying dtc_addr to point to a different dtcopts structure.

dtc_addr is initialized with the address of the default dtcopts structure. The default dtcopts structure is defined in DATETIME.H as follows:

typedef struct {
char dtc_dtformat;/* date format MDY/DMY/YMD (country) */
char dtc_dtdelim; /* date delimiter (country) */
char dtc_tmformat/* time format 12/24-hour (country) */
char dtc_tmdelim;/* time delimiter (country) */
char dtc_hdelim;/* delimiter for 100ths (default is cntry decimal delim) */
char *dtc_amstr;/* address of AM string (default string is " AM") */
char *dtc_pmstr;/* address of PM string (default string is " PM") */
} dtcopts;

The DTC_DEFAULT symbolic constant (defined in DATETIME.H) may be specified for any field which accepts a pointer. This causes the date/time conversion functions to use the default string, shown above, for each field in which it is specified.

Source file DTCVARS.ASM ASM equivâ
See also
_dtc_init, _get_countryinfo

_dtc_init


Descrip
Initializes the date/time conversion options structure with DOS country information.

Syntax
#include <datetime.h>
int _dtc_init(int cntrycode);

Returns
The country code of the specified (or current) DOS country.

-1 if an error occurred (e.g., cntrycode is invalid).
e_code error code

Notes
This function updates the current date/time conversion options structure (dtcopts) with the DOS country information for the specified country. The current DOS country may be specified by setting cntrycode to 0. If the operation was successful, the country code of the specified (or current) DOS country is returned and the current date/time conversion options structure is updated. If the function is unsuccessful, -1 is returned and the structure is left unmodified.

Valid cntrycode values are found in DOS user manuals for DOS 4.x and above and in many programming reference manuals.

The current date/time conversion options structure specifies global date/time formatting options and is used by _asc_to_date, _asc_to_time, _date_to_asc, _time_to_asc, and the scripted I/O functions. The dtc_addr variable maintains the address of the current structure. (See dtc_addr for further information.)

The following dtcopts information is updated by this function: date format, date delimiter, time format, time delimiter, and 100ths delimiter.

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

C/C++ Example
	{
	   dtcopts dtc;
	   dtc_addr = &dtc;/* use dtc structure (country info) */
	   if (dtc_init(0) == 0)
	      _put_str("Unable to initialize DTC structure.");
	   else
	      /* ... continue with conversions ... */
	}

Inline Assembly Example
	#include <inline.h>
	{
	   dtcopts dtc;
	   char msg[] = "Unable to initialize DTC structure";
	   ... 
	   dtc_addr = &dtc;/* use dtc structure */
	   xor ax,ax/* get current country information */
	   dtc_init();/* initialize dtc w/DOS country info */
	    jnccntry_010
	   lea si,msg/* SI -> message string */
	   put_str();/* output message */
	cntry_010:
	   ...
	}

Source file _DTINIT.ASM ASM equiv DTC_INIT
See also
dtc_addr, _get_countryinfo

_get_clock


Descrip
Returns the system clock tick count.

Syntax
#include <datetime.h>
unsigned long _get_clock(void);

Returns
The number of clock ticks since midnight.

Notes
This function returns the current system clock tick count. There are approximately 18.2 clock ticks per second. The count represents the number of ticks since midnight. The clock tick count rolls over to zero after 23 hours, 59 minutes and 59 seconds (system time) or a count of 1,573,040 has been reached.

C/C++ Example
	{
	   unsigned long clock;
	   clock = _get_clock();
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned long clock;
	   clock = get_clock();  
	   ...
	}

Source file DTGETCLK.ASM ASM equiv GET_CLOCK
See also
_get_time, _set_clock, _tmr_read

_get_date


Descrip
Fills structure with the current system date and day of the week.

Syntax
#include <datetime.h>
void _get_date(const std_date *gdate);

Returns
No return value.
gdate the current system date and day-of-week

Notes
This function places the current system date and day of the week in the std_date structure gdate. The indicated day of the week code represents the number of days since Sunday (0 for Sunday, 1 for Monday, etc).

When using inline assembly, the date is returned in an unsigned long. This format allows the date to be compared directly with other dates, producing a "greater than", "equal to", or "less than" result.

The std_date structure is defined in DATETIME.H as follows:

typedef struct {
unsigned char day;
unsigned char month;
unsigned int year;
unsigned char day_of_week;
} std_date;

C/C++ Example
	{
	   std_date gdate;
	   _get_date(&gdate); /* gdate filled w/current date */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   unsigned cmpdate;
	   ... 
	   mov cx,word ptr cmpdate+2
	   mov bx,word ptr cmpdate/* CX:BX = target date */
	   get_date();	/* DX:AX = current date */
	   cmp_dd();	/* past target date yet? */
	    ja chk_date_100/*   y: display message */
	   str = "Not past target date yet.";
	   jmp short chk_date_200

	chk_date_100:	 	/* write "past" message */
	   str = "Past target date!";
	chk_date_200:
	   mov si,str	/* SI = offset of str */
	   put_str();	/* display message */
	   ...
	}

Source file _DTGTDTE.ASM ASM equiv GET_DATE
See also
_get_day, _getftime_h, _get_time, _set_date

_get_day


Descrip
Returns the day of the week for a given date.

Syntax
#include <datetime.h>
char _get_day(const std_date *gdate)

Returns
The day of the week value (0 to 6).

Notes
This function returns a value which indicates the day of the week which corresponds to the date specified in gdate. The returned value indicates the number of days since Sunday (0 for Sunday, 1 for Monday, etc.).

The returned value is undefined if gdate is outside the range 01-01-1980 to 12-31-2099.

The std_date structure is defined in DATETIME.H as follows:

typedef struct {
unsigned char day;
unsigned char month;
unsigned int year;
unsigned char day_of_week;/* not used by this function */
};

C/C++ Example
	{
	   char day;
	   std_date gday;
	   gday.year= 2000;	/* gday = Jan 1, 2000 */
	   gday.month= 1;
	   gday.day= 1;
	   day = _get_day(&gday); /* day = 6 (Saturday) */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char day;
	   ...
	   mov dx,2000	    /* DX = year */
	   mov ah,1	/* AH = month */
	   mov al,1	/* AL = day */
	   get_day();	/* CL = 6 (Saturday) */
	   mov day,cl	/* day = day of week */
	...
	}

Source file _DTGTDAY.ASM ASM equiv GET_DAY
See also
_get_date

_get_time


Descrip
Gets the current system time.

Syntax
#include <datetime.h>
void _get_time(std_time *gtime);

Returns
No return value.
gtime the current system time

Notes
This function places the current system time in the specified std_time structure.

When using inline assembly, this function returns the system time value in unsigned long format. This format allows the time to be compared directly with other times, producing a "greater than", "equal to", or "less than" result.

The std_time structure is defined as follows:

typedef struct {
unsigned char hseconds;
unsigned char seconds;
unsigned char minutes;
unsigned char hours;
} std_time;

C/C++ Example
	{
	   ...
	   std_time gtime;
	   _get_time(&gtime);/* gtime filled with current time */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned long gtime, target;
	   ...
	   gtime = get_time();
	   if (gtime == target)
	            _put_str("Currently at target time!");
	   else if (gtime > target)
	            _put_str("Past target time!");
	   else 
	            _put_str("Not yet at target time!");
	   ...
	}

Source file _DTGTTME.ASM ASM equiv GET_TIME
See also
_get_clock, _get_date, _getftime_h, _set_time

_hund_to_time


Descrip
Converts hundredths of seconds into a time structure format.

Syntax
#include <datetime.h>
void _hund_to_time(unsigned long hundredths, std_time *htime);

Returns
No return value.
htime the standard time format representation of hundredths

Notes
This function converts hundredths into a time in structure format. The result is undefined if hundredths is greater than 92,159,999 (which is equivalent to 255:59:59.99).

When using inline assembly, the time is returned as an unsigned long. This allows the time to be compared directly with other times, producing a "greater than", "equal to", or "less than" result.

The std_time structure is defined in DATETIME.H as follows:

typedef struct {
unsigned char hseconds;
unsigned char seconds;
unsigned char minutes;
unsigned char hours;
} std_time;

C/C++ Example
	   std_time htime;
	   _hund_to_time(92159998, &htime); /* htime = 255:59:59.98 */
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned long target;
	   char *str;
	   ...
	   target = get_time();
	   mov bx,0xF200
	   mov cx,0x0026/* CX;BX = 8:00:00.00 (100ths) */
	   if (target < hund_to_time())
	   {   str = "\n\r   Not at target time yet.";   }
	   else
	   {  str = "\n\r   Past target time!";  }
	   mov si,str
	   put_str();	/* display "str" */
	   ...
	}

Source file _DTHNTME.ASM ASM equiv HUND_TO_TIME
See also
_days_to_date, _ticks_to_time, _time_to_hund

_init_msec


Descrip
Calibrates the millisecond timer.

Syntax
#include <datetime.h>
void _init_msec(void);

Returns
None

Notes
This function calibrates the millisecond timer. It should be called before using _sleep_msec. This ensures the accuracy of the millisecond timer even if system timer zero has been reprogrammed to run in a non-system default mode.

C/C++ Example
	   ...
	   _init_msec();
	   _sleep_msec(100);/* delay for 0.1 second */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   init_msec();
	   mov ax,200/* AX = thousandths of seconds */
	   sleep_msec();/* delay for 0.2 seconds */
	   ...

Source file DTINITMS.ASM ASM equiv INIT_MSEC
See also
_sleep_msec

_merge_date


Descrip
Converts a date from structure format to integer format.

Syntax
#include <datetime.h>
unsigned int _merge_date(const std_date *mdate);

Returns
The equivalent of mdate in integer date format.

Notes
This function converts mdate from structure format to integer date format. The integer result is returned.

Integer date format is identical to the date format used in file date/time stamps maintained by DOS. This is the same format returned by _find_first, _find_next, and _getfdate_h:

Bits0x00-0x04day (1-31)
Bits0x05-0x08month (1-12)
Bits0x09-0x0Fyear (0-119, relative to 1980)

The result is undefined if mdate is out of range.

The std_date structure is defined in DATETIME.H as follows:

typedef struct {
unsigned char day;
unsigned char month;
unsigned int year;
unsigned char day-of-week;/* not used by this function */
} std_date;

C/C++ Example
	{
	   std_date mdate;
	   fbuf mbuf; /* contains file info from last _find_next */
	   ...
	   mdate.day= 5;
	   mdate.month= 11;
	   mdate.year= 1992;
	   if(mbuf.date != _merge_date(&mdate))
	      exit(0); /* exit if file date <> 11-05-1992 */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   fbuf mbuf;/* contains file info from last _find_next */
	   ...
	   mov al,5	    /* AL = day   */
	   mov ah,11	    /* AH = month */
	   mov dx,1992	    	  /* DX = year  */
	   merge_date();
	   cmp word ptr mbuf.date,dx
	    jnemain_100 /* exit if file date <> 11-05-1992 */
	   ...
	main_100:
	   ...
	}

Source file _DTMRGDT.ASM ASM equiv MERGE_DATE
See also
_get_date, _merge_time, _split_date

_merge_time


Descrip
Converts a time from structure format to integer format.

Syntax
#include <datetime.h>
unsigned int _merge_time(const std_time *mtime);

Returns
The equivalent of mtime in integer format.

Notes
This function converts mtime from structure format to integer time format. The integer result is returned.

Integer time format is identical to the time format used in file date/time stamps maintained by DOS. This is the same time format returned by _find_first, _find_next, and _getfdate_h:

Bits0x00-0x042-second increments (0-29)
Bits0x05-0x0Aminutes (0-59)
Bits0x0B-0x0Fhours (0-23)

The result is undefined if mtime is out of range.

C/C++ Example
	{
	   std_time mtime;
	   fbuf mbuf;/* info from last _find_next */
	   ...
	   mtime.hours = 13;
	   mtime.minutes= 1;
	   mtime.seconds= 30;
	   if(mbuf.time != _merge_time(&mtime))
	      exit(0);/* exit if file time <> 13:01:30 */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   fbuf mbuf;	 /* info from last _find_next */
	   ...   
	   mov dh,12	    /* DH = hours */
	   mov dl,1	    /* DL = minutes */
	   mov ah,30	    /* AH = seconds */
	   merge_time();	    /* AX = merged time */
	   cmp word ptr mbuf.time,ax/* time = 12:01:30? */
	    jnemain_100    /*   n: exit */
	   ... 	 	    /*   y: continue 	  */
	main_100:
	   ...
	}

Source file _DTMRGTM.ASM ASM equiv MERGE_TIME
See also
_get_time, _merge_date, _split_time

_set_clock


Descrip
Sets the system clock tick count.

Syntax
#include <datetime.h>
void _set_clock(unsigned long count);

Returns
None

Notes
This function sets the current system clock tick count to count.

There are approximately 18.2 clock ticks per second. The count represents the number of ticks since midnight. The clock tick count rolls over to zero after 23 hours, 59 minutes and 59 seconds (system time) or a count of 1,573,040 has been reached.

C/C++ Example
	   ...
	   unsigned long count = 1573039;
	   _set_clock(count);
	   ...

Inline Assembly Example
	#include <inline.h>
	...
	   unsigned long count = 1573039;
	   ...
	   mov ax,word ptr count
	   mov dx,word ptr count+2/* DX;AX = count */
	   set_clock();
	   ...

Source file _DTSTCLK.ASM ASM equiv SET_CLOCK
See also
_get_clock, _set_time

_set_date


Descrip
Sets the system date.

Syntax
#include <datetime.h>
int _set_date(const std_date *sdate);

Returns
0 if the system date was set successfully.

-1 if sdate is invalid.

Notes
This function sets the system date to sdate. 0 is returned if the function was successful. If sdate is invalid, -1 is returned and the system date remains unchanged. The new system date remains in effect only until the system is rebooted.

The std_date structure is defined in DATETIME.H as follows:

typedef struct {
unsigned char day;
unsigned char month;
unsigned int year;
unsigned char day_of_week;/* not used by this function */
} std_date;

C/C++ Example
	{
	   std_date sdate;
	   sdate.year= 2000;
	   sdate.month= 1;
	   sdate.day= 1;
	   _set_date(&sdate); /* set sys date to 01-01-2000 */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	mov dx,2000	/* DX = year */
	mov ah,1	 /* AH = month */
	mov al,1	 /* AL = day */
	set_date();	 /* set sys date to 01-01-2000 */
	...

Source file _DTSTDTE.ASM ASM equiv SET_DATE
See also
_get_date, _set_time

_set_time


Descrip
Sets the system time.

Syntax
#include <datetime.h>
int _set_time(const std_time *stime);

Returns
0 if the system time was successfully set.

-1 if stime is invalid.

Notes
This function sets the system time to stime. 0 is returned if the function was successful. If stime is invalid, -1 is returned and the system time remains unchanged. The new system time remains in effect only until the system is rebooted.

The std_time structure is defined as follows:

typedef struct {
unsigned char hseconds;
unsigned char seconds;
unsigned char minutes;
unsigned char hours;
} std_time;

C/C++ Example
	   ...
	   std_time stime;
	   stime.hours= 12;
	   stime.minutes= 30;
	   stime.seconds= 30;
	   if(_set_time(&stime) == -1)
	      _put_str("Time is invalid.");
	   ...

Inline Assembly Example
	#include <inline.h>
	...
	   mov dx,12	/* DX = hours */
	   mov ah,30	/* AH = minutes */
	   mov al,30	/* AL = seconds */
	   set_time();	    
	    jnclabel_100/* if successful jump to label */
	   _put_str("Time is invalid.");
	label_100:
	   ...

Source file _DTSTTME.ASM ASM equiv_SET_TIME
See also
_get_time, _set_clock, _set_date

_sleep_msec


Descrip
Suspends program execution for a specified number of milliseconds.

Syntax
#include <datetime.h>
void _sleep_msec(unsigned int msecs);

Returns
None

Notes
This function suspends program execution for msecs milliseconds. The delay period is determined by monitoring system timer zero.

The _init_msec function should be called at some point prior to using this function in order to calibrate the millisecond timer. If _init_msec is not called, this function will assume that system timer zero is operating in thedefault mode (mode 3, reload count 0). If timer zero is operating in any other mode, the delay period will be incorrect. If system timer zero is reprogrammed, _init_msec should be called again.

If this function is called with interrupts off, they remain off for the entire duration of the function.

C/C++ Example
	   ...
	   _init_msec();/* initialize millisecond timer first */
	   _sleep_msec(1000);/* sleep for 1 second */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   init_msec();
	   mov ax,2000	/* AX = thousandths of seconds */
	   sleep_msec();/* sleep for 2 seconds */
	   ...

Source file _DTSLMSC.ASM ASM equiv SLEEP_MSEC
See also
_init_msec, _sleep_sec

_sleep_sec


Descrip
Suspends program execution for a specified number of hundredths of a second.

Syntax
#include <datetime.h>
void _sleep_sec(unsigned int hsecs)

Returns
None

Notes
This function suspends program execution for hsecs hundredths of a second. The delay period is approximated to the nearest 1/18th of a second. If a more accurate delay period is required, use _sleep_msec.

WARNING! This function will not operate properly when interrupts are off. If a delay is needed while interrupts are disabled, use _sleep_msec.

C/C++ Example
	   _sleep_sec(100);/* sleep for 1 second */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ax,200/* AX = hundredths of seconds */
	   sleep_sec();/* sleep for 2 seconds */
	   ...

Source file _DTSLPSC.ASM ASM equiv SLEEP_SEC
See also
_sleep_msec, _tmr_read

_split_date


Descrip
Converts a date from integer format to structure format.

Syntax
#include <datetime.h>
void _split_date(unsigned int idate, std_date *sdate);

Returns
No return value.
sdate the resulting date value in std_date format

Notes
This function converts idate from integer format to structure format. The std_date result is returned in sdate.

Integer date format is identical to the date format used in file date/time stamps maintained by DOS. This is the same format returned by _find_first, _find_next, and _getfdate_h:

bits 0x00-0x04day (1-31)
bits 0x05-0x08month (1-12)
Bits 0x09-0x0Fyear (0-119, relative to 1980)

The result is undefined if idate does not conform to the above format.

The std_date structure is defined in DATETIME.H as follows:

typedef struct {
unsigned char day;
unsigned char month;
unsigned int year;
unsigned char day-of-week;/* not updated by this function */
} std_date;

C/C++ Example
	   ...
	   fbuf filebuf; /* file info from last _find_next */
	   std_date sdate;
	   ...
	   _split_date(filebuf.date, &sdate);
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   unsigned long sdate;
	   fbuf filebuf;/* info from last _find_next */
	   ...
	   mov dx,word ptr filebuf.date/* DX=time (int format) */
	   sdate = split_date();
	   ...

Source file _DTSPLDT.ASM ASM equiv SPLIT_DATE
See also
_get_date, _merge_date

_split_time


Descrip
Converts a time from integer format to structure format.

Syntax
#include <datetime.h>
void _split_time(unsigned int itime, std_time *stime);

Returns
No return value.
stime the resulting time value in std_time format

Notes
This function converts itime from integer format to std_time structure format. The std_time result is placed in stime. Because integer time format only supports seconds in two-second intervals, the resulting number of seconds in stime is always an even number.

Integer time format is identical to the time format used in file date/time stamps maintained by DOS. This is the same format returned by _find_first, _find_next, and _getftime_h:

bits 0x00-0x042-second increments (0-29)
bits 0x05-0x0Aminutes (0-59)
bits 0x0B-0x0Fhours (0-23)

The result is undefined if itime does not conform to the above format.

The std_time structure is defined DATETIME.H as follows:

typedef struct {
unsigned char hseconds;
unsigned char seconds;
unsigned char minutes;
unsigned char hours;
} std_time;

C/C++ Example
	   ...
	   fbuf mbuf;/* info from last _find_next */
	   std_time stime;
	   _split_time(mbuf.time, &stime); /* stime struct = file time */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   unsigned long ltime;
	   fbuf mbuf;/* info from last _find_next */
	   mov ax,word ptr mbuf.time
	   	  	 /* AX = time in integer format */
	   ltime = split_time();
	   	  	 /* ltime is time in structure format */
	   ...

Source file _DTSPLTM.ASM ASM equiv SPLIT_time
See also
_get_time, _merge_time

_ticks_to_time


Descrip
Converts a time value from timer ticks format to structure format.

Syntax
#include <datetime.h>
std_time *_ticks_to_time(unsigned long tticks, std_time *stime);

Returns
A pointer to stime.
stime the std_time format result (equivalent to tticks)

Notes
This function converts a time in timer ticks format into a time in std_time structure format. A pointer to stime is returned.

stime must be a structure of type std_time (defined in DATETIME.H) as follows:

typedef struct {
unsigned char hseconds;/* 0-99 */
unsigned char seconds;/* 0-59 */
unsigned char minutes;/* 0-59 */
unsigned char hours; /* 0-255 */
} std_time;

The result in stime is undefined if tticks is greater than 16,779,092 (which is equivalent to 255:59:59.99).

This function, when used in conjunction with _get_clock, is much faster than the _get_time function. Use the _get_time function if code size is more important than speed.

C/C++ Example
	{
	   std_time stime;
	   unsigned long ttime;
	   ttime = _get_clock();
	   _ticks_to_time(ttime, &stime);
	   	  	 /* convert ticks to structure format */
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   get_clock();/* DX;AX = time in ticks */
	   ticks_to_time();
	   	  /* DX;AX = time in unsigned long format */
	   ...

Source file _DTTKTME.ASM ASM equiv TICKS_TO_TIME
See also
_hund_to_time, _time_to_ticks

_time_to_asc


Descrip
Converts a time in structure format to a formatted ASCIIZ string.

Syntax
#include <datetime.h>
char *_time_to_asc(const std_time *atime, unsigned char flags, unsigned char width, char *outstr);

Returns
A pointer to outstr.
outstr resulting ASCIIZ representation of atime in the specified format

NULL if the length of the resulting string would have exceeded width.
outstr undefined

Notes
This function converts atime to a formatted ASCIIZ time string in outstr. The resulting time string has the format specified in flags and in the current date/time conversion options structure. A pointer to outstr is returned if the conversion was successful. NULL is returned and outstr is left in an undefined state if the resulting time string would exceed width characters in length.

atime must be a structure of type std_time (defined in DATETIME.H) as follows:

typedef struct {
unsigned char hseconds;/* 0-99 */
unsigned char seconds;/* 0-59 */
unsigned char minutes;/* 0-59 */
unsigned char hours; /* 0-255 */
} std_time;

Conversion options specified in flags consist of time format flags, field suppress flags, and leading zero flags. The following symbolic constants (defined in DATETIME.H) may be bitwise ORed together to specify the time string format:
Time format flags:

TIME_CTIME (0x03) Use country format from dtcopts structure
TIME_12HR (0x01) Use 12-hour format
TIME_24HR (0x02) Use 24-hour format
TIME_FLEXHR (0x00) Writes TIME_CTIME, reads both 12-hour and 24-hour formats

Time field suppress flags:

TIME_HR (0x00) Use hour field
TIME_NOHR (0x04) Suppress hour field
TIME_MIN (0x00) Use minute field
TIME_NOMIN(0x08) Suppress minute field
TIME_SEC (0x00) Use second field
TIME_NOSEC(0x10) Suppress second field
TIME_100THS(0x00) Use 100ths field
TIME_NO100THS(0x20) Suppress 100ths field

Time leading zero flags:

TIME_PAD (0x00) Write leading zero in 1st field (e.g. "1:00" to "01:00")
TIME_NOPAD(0x40) No leading zero in 1st field

The time leading zero flags specify whether or not to pad the leading field with a "0" if it only has one digit. All other fields always contain two digits.

The current date/time conversion options structure specifies global formatting options such as the country-default time format, the time delimiter character, and the 100ths separator character. These options may be accessed or modified through the DTC_ADDR variable. (See DTC_ADDR for further information.)

WARNING! outstr must be at least width+1 bytes in size or data following the buffer will be overwritten.

C/C++ Example
	{
	   dtcopts dtc = {0,'-',0,':','.'," am", " pm"};
	   std_time atime;
	   char outstr[80];
	   dtc_addr = &dtc; /* use dtc structure for conversion info */
	   atime.hours = 12;
	   atime.minutes = 59;
	   atime.seconds = 59;
	   atime.hseconds = 99; /* atime contains time to convert */
	   _put_str(_time_to_asc(&atime, 0, 80, outstr));
	   	  	 /* "12:59:59.99 pm" */
	}

Inline Assembly Example
	#include <inline.h>
	{
	   dtcopts dtc = {0,'-',0,':','.'," am", " pm"};
	   char outstr[80];
	   ... 
	   dtc_addr = &dtc; /* use dtc structure (conv. info) */
	   xor ch,ch	/* CH = conversion flags */
	   mov cl,80	/* CL = width of buffer */
	   lea si,outstr/* SI -> outstr */
	   mov  dh,11	/* DH = hours */
	   mov dl,59	/* DL = minutes */
	   mov ah,59	/* AH = seconds */
	   mov al,99	/* AL = 100ths */
	   time_to_asc();	/* time -> "string" */
	   put_str();	/* "11:59:59.99 am" */
	   ...
	}

Source file _DTTMASC.ASM ASM equiv TIME_TO_ASC
See also
_asc_time, _asc_to_time, _time_to_asc

_time_to_asce


Descrip
Converts time in a structure to a formatted ASCII string, returning a pointer to the end of the resulting string.

Syntax
#include <datetime.h>
char *_time_to_asce(const std_time *atime, unsigned char flags, unsigned char width, char *outstr);

Returns
A pointer to the character after the last character written to outstr.
outstr resulting ASCII representation of atime in the specified format

NULL if the length of the resulting string would have exceeded width.
outstr undefined

Notes
This function converts atime to a formatted ASCII time string in outstr. The resulting time string is not NULL terminated and has the format specified in flags and in the current date/time conversion options structure. The returned pointer identifies the next available position in outstr (past the result). A subsequent call to _str_cpy or _str_cpye will append data to the result more rapidly than is possible with _time_to_asc. NULL is returned and outstr is left in an undefined state if the resulting time string would exceed width characters in length.

atime must be a structure of type std_time (defined in DATETIME.H) as follows:

typedef struct {
unsigned char hseconds;/* 0-99 */
unsigned char seconds;/* 0-59 */
unsigned char minutes;/* 0-59 */
unsigned char hours; /* 0-255 */
} std_time;

Conversion options specified in flags consist of time format flags, field suppress flags, and leading zero flags. The following symbolic constants (defined in DATETIME.H) may be bitwise ORed together to specify the time string format:

Time format flags:

TIME_CTIME (0x03) Use country format from dtcopts structure
TIME_12HR (0x01) Use 12-hour format
TIME_24HR (0x02) Use 24-hour format
TIME_FLEXHR (0x00) Writes TIME_CTIME, reads both 12-hour and 24-hour formats

Time field suppress flags:

TIME_HR (0x00) Use hour field
TIME_NOHR (0x04) Suppress hour field
TIME_MIN (0x00) Use minute field
TIME_NOMIN(0x08) Suppress minute field
TIME_SEC (0x00) Use second field
TIME_NOSEC(0x10) Suppress second field
TIME_100THS(0x00) Use 100ths field
TIME_NO100THS(0x20) Suppress 100ths field

Time leading zero flags:

TIME_PAD (0x00) Write leading zero in 1st field (e.g. "1:00" to "01:00")
TIME_NOPAD(0x40) No leading zero in 1st field

The time leading zero flags specify whether or not to pad the leading field with a "0" if it only has one digit. All other fields always contain two digits.

The current date/time conversion options structure specifies global formatting options such as the country-default time format, the time delimiter character, and the 100ths separator character. These options may be accessed or modified through the DTC_ADDR variable. (See DTC_ADDR for further information.)

WARNING! outstr must be at least width+1 bytes in size or data following the buffer will be overwritten.

C/C++ Example
	{
	   dtcopts dtc = {0,'-',0,':','.'," am", " pm"};
	   std_time atime;
	   char *outstr;
	   dtc_addr = &dtc; /* use dtc structure (conversion info) */
	   atime.hours = 12;
	   atime.minutes = 59;
	   atime.seconds = 59;
	   atime.hseconds = 99; /* atime contains time to convert */
	   outstr = "               is the current time";
	   _time_to_asce(&atime, 0, 80, outstr);
	   _put_str(outstr); /* "12:59:59.99 pm is the current time"*/
	}

Inline Assembly Example
	#include <inline.h>
	{
	   dtcopts dtc = {0,'-',0,':','.'," am", " pm"};
	   char outstr[] = "               is the current time";
	   ...   
	   dtc_addr = &dtc; /* use DTC structure (conv. info) */
	   xor ch,ch	/* CH = conversion flags */
	   mov cl,80	/* CL = width of buffer */
	   lea si,outstr/* SI -> outstr */
	   mov      dh,11	/* DH = hours */
	   mov dl,59	/* DL = minutes */
	   mov ah,59	/* AH = seconds */
	   mov al,99	/* AL = 100ths */
	   time_to_asce();    /* time -> "string" */
	   lea si,outstr/* reset SI -> outstr */
	   put_str();/* "11:59:59.99 am is the current time"*/
	   ...
	}

Source file _DTTMACE.ASM ASM equiv TIME_TO_ASCE
See also
_asc_time, _asc_to_time, _time_to_asc

_time_to_hund


Descrip
Converts a time from structure format to hundredths of seconds.

Syntax
#include <datetime.h>
unsigned long _time_to_hund(const std_time *stime);

Returns
The hundredths of seconds result.

Notes
This function converts stime from structure format to hundredths of seconds and returns the hundredths of seconds result.

stime must be a structure of type std_time (defined in DATETIME.H) as follows:

typedef struct {
unsigned char hseconds;/* 0-99 */
unsigned char seconds;/* 0-59 */
unsigned char minutes;/* 0-59 */
unsigned char hours; /* 0-255 */
} std_time;

The result is undefined if any of the fields in stime are invalid or out of range.

C/C++ Example
	{
	   unsigned long hundredths;
	   std_time htime;

	   htime.hours = 10;
	   htime.minutes= 30;
	   htime.seconds= 5;
	   htime.hseconds = 50;
	   hundredths = _time_to_hund(&htime);
	   	  /* = 3780550 hundredths of a sec */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned long hundredths;
	   ...
	   mov dh,10	/* DH = hours */
	   mov dl,30	/* DL = minutes */
	   mov ah,5	/* AH = seconds */
	   mov al,50	/* AL = hseconds */
	   hundredths = time_to_hund();
	   	  	 /* 3780550 100ths of a sec */
	   ...
	}

Source file _DTTMHUN.ASM ASM equiv TIME_TO_HUND
See also
_date_to_days, _hund_to_time, _time_to_ticks

_time_to_ticks


Descrip
Converts a time from structure format to timer tick format.

Syntax
#include <datetime.h>
unsigned long _time_to_ticks(const std_time *stime);

Returns
The time represented by stime in timer tick format.

Notes
This function converts a time from std_time structure format to timer ticks format. The return value indicates the number of system clock ticks between midnight (00:00:00.0) and the time specified in stime.

stime must be a structure of type std_time (defined in DATETIME.H) as follows:

typedef struct {
unsigned char hseconds;/* 0-99 */
unsigned char seconds;/* 0-59 */
unsigned char minutes;/* 0-59 */
unsigned char hours; /* 0-255 */
} std_time;

The result is undefined if any field in stime is invalid or out of range.

This function, when used in conjunction with _set_clock, is much faster than the _set_time function. Use the _set_time function if code size is more important than speed.

C/C++ Example
	{
	   std_time stime;
	   unsigned long ttime;
	   _get_time(&stime);
	   ttime = _time_to_ticks(&stime);
	/* convert structure time to timer ticks format */
	}

Inline Assembly Example
	#include <inline.h>
	{
	   ...
	   get_time();/* DX;AX = unsigned long format time */
	   time_to_ticks();/* DX;AX = time in ticks */
	   ...
	}

Source file _DTTMETK.ASM ASM equiv TIME_TO_TICKS
See also
_ticks_to_time, _time_to_hund

_tmr_read


Descrip
Returns the elapsed time since the last call to _tmr_reset.

Syntax
#include <datetime.h>
std_time *_tmr_read(std_time *tmrtime);

Returns
A pointer to tmrtime.
tmrtime the time since the last call to _tmr_reset

Notes
This function reads the elapsed time since the last call to _tmr_reset without interrupting the current timing sequence. The elapsed time is indicated in tmrtime. A pointer to tmrtime is returned.

tmrtime must be a structure of type std_time (defined in DATETIME.H) as follows:

typedef struct {
unsigned char hseconds;/* 0-99 */
unsigned char seconds;/* 0-59 */
unsigned char minutes;/* 0-59 */
unsigned char hours; /* 0-255 */
} std_time;

If this function is called prior to calling _tmr_reset, the current time of day is indicated in tmrtime.

C/C++ Example
	{
	   std_time tmrtime;
	   _tmr_reset();
	   ...
	   _tmr_read(&tmrtime);
	   	  /* tmrtime = elapsed time after 1st section */
	   ...
	   _tmr_read(&tmrtime); /* tmrtime = elapsed time at end */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned long tmrtime;
	... 
	_tmr_reset();	 /* start timer */
	...
	tmrtime = tmr_read();
		/* tmrtime = elapsed time after 1st section */
	...
	tmrtime = tmr_read();/* tmrtime=elapsed time at end */
	...
	}

Source file _DTTIMER.ASM ASM equiv TMR_READ
See also
_get_clock, _sleep_sec, _tmr_reset

_tmr_reset


Descrip
Begins a new timing sequence.

Syntax
#include <datetime.h>
void _tmr_reset(void);

Returns
None

Notes
This function begins a new timing sequence by resetting the timer used by _tmr_read. The elapsed time (since the last call to this function) is obtained by calling _tmr_read.

C/C++ Example
	{
	   std_time tmr;

	   _tmr_reset();
	   ...
	   _tmr_read(&tmr);/* tmr = elapsed time */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned long tmr;
	   ...
	   _tmr_reset():	/* start timer */
	   ...
	   tmr = _tmr_read();/* tmr = elapsed time */
	   ...
	}

Source file DTTIMER.ASM ASM equiv TMR_RESET
See also
_tmr_read