time : IndexToc

TEKlib / Time module reference manual

By Timm S. Müller and Frank Pagels - Copyright © 2005 TEK neoscientists. All rights reserved.

Time requests
TAllocTimeRequest Allocate a time request
TFreeTimeRequest Free a time request
Time queries
TQueryTime Query system time
TGetDate Query system date (and timezone)
Waiting
TDelay Wait an amount of time
TWaitTime Wait an amount of time, with signals
TWaitDate Wait for an explicit date, with signals
Utilities
TSubTime Subtract one time from another
TAddTime Add a time to another
TCmpTime Compare times
TIsLeapYear Check if year is a leap year
TIsValidDate Check if a day, month, year is a valid date
Regular date
TPackDate Pack a datebox structure to a date
TUnpackDate Unpack a date to a datebox structure
TMakeDate Initialize a date
TAddDate Add days and/or time to a date
TSubDate Substract days and/or a time from a date
TDiffDate Calculate days/time difference between dates
Date conversion
TYDayToDM Convert a year and yearday to a day and month
TDMYToYDay Convert day, month, year to a yearday
TGetWeekDay Get the weekday number of a day, month, year
TGetWeekNumber Get the week number of a day, month, year
Julian date
TDateToJulian Get a Julian day from a date
TJulianToDate Get a date from a Julian day
TMYToJulian Convert month, year to a Julian day
TJulianToDMY Convert a Julian day to day, month, year

time : TSubTimeToc

NAME
TSubTime - Subtract time

SYNOPSIS
TTimeSubTime(TTimeBase, a,     b)
             TAPTR      TTIME* TTIME*

TSubTime(a,     b)
         TTIME* TTIME*

FUNCTION
Subtract time b from time a, leaving the result in time a.

INPUTS
a Pointer to a time structure to subtract from
b Pointer to a time structure to be subtracted

SEE ALSO


time : TAddTimeToc

NAME
TAddTime - Add time

SYNOPSIS
TTimeAddTime(TTimeBase, a,     b)
             TAPTR      TTIME* TTIME*

TAddTime(a,     b)
         TTIME* TTIME*

FUNCTION
Add time b to time a, leaving the result in time a.

INPUTS
a Pointer to a time structure to add to
b Pointer to a time structure to be added

SEE ALSO


time : TCmpTimeToc

NAME
TCmpTime - Compare times

SYNOPSIS
res = TTimeCmpTime(TTimeBase, a,     b)
TINT               TAPTR      TTIME* TTIME*

res = TTimeCmp(a,     b)
TINT           TTIME* TTIME*

FUNCTION
Compare time a with time b. The result will be
1 if time a refers to a later point in time than time b
-1 if time a refers to a earlier point in time than time b
0 if time a is equal to time b.

INPUTS
a Pointer to a time structure, first operand
b Pointer to a time structure, second operand

RESULTS
res result of comparison, -1, 0 or 1

SEE ALSO


time : TAllocTimeRequestToc

NAME
TAllocTimeRequest - allocate a time request

SYNOPSIS
timereq = TTimeAllocTimeRequest(TTimeBase, tags)
TAPTR                           TAPTR      TTAGITEM*

timereq = TAllocTimeRequest(tags)
TAPTR                       TTAGITEM*

FUNCTION
This function opens the timer.device and returns a pointer to a time request, which is readily initialized to be used by functions such as TWaitTime and TQueryTime.
Each time request allocated by this function must be freed using TFreeTimeRequest.

INPUTS
tags Pointer to an array of tag items

TAGS
None defined yet

RESULTS
timereq Pointer to a time request, or TNULL if the device open failed

NOTES
  • A single time request cannot be used by multiple tasks at the same time. If required, allocate one request per task.

SEE ALSO


time : TFreeTimeRequestToc

NAME
TFreeTimeRequest - free a time request

SYNOPSIS
TTimeFreeTimeRequest(TTimeBase, timereq)
                     TAPTR      TAPTR

TFreeTimeRequest(timereq)
                 TAPTR

FUNCTION
This function frees a time request that was allocated with TAllocTimeRequest.

INPUTS
timereq Pointer to a time request

SEE ALSO


time : TQueryTimeToc

NAME
TQueryTime - Query relative system time

SYNOPSIS
TTimeQueryTime(TTimeBase, timereq, timep)
               TAPTR      TAPTR    TTIME*

TQueryTime(timereq, timep)
           TAPTR    TTIME*

FUNCTION
This function queries a (relative) system time and inserts it into the time structure being pointed to by timep. The time request is a timer.device instance and usually obtained with a call to TAllocTimeRequest.

INPUTS
timereq Pointer to a time request
timep Pointer to a time structure to be filled

NOTES
  • It is important to note that a TEKlib TTIME is a relative entity. It might appear as if the fields filled in by this function could in some way reflect an absolute time or date, but this would be entirely misleading as the base for a TTIME structure can differ among different hosts. For getting an absolute date and time use the more expensive function TGetDate.

SEE ALSO


time : TGetDateToc

NAME
TGetDate - Get absolute system time and date

SYNOPSIS
error = TTimeGetDate(TTimeBase, timereq, datep, tzsecp)
TINT                 TAPTR      TAPTR    TDATE* TINT*

error = TGetDate(timereq, datep, tzsecp)
TINT             TAPTR    TDATE* TINT*

FUNCTION
This function queries the system's absolute time and date and inserts it into the structure being pointed to by datep, and optionally the number of seconds West of GMT into the variable being pointed to by tzsecp. The time request argument is a pointer to a timer.device instance, which is usually obtained with a call to TAllocTimeRequest.
If tzsecp is TNULL then *datep will be set to the system's local time. If tzsecp points to a variable then *datep will be set to Universal Time (UT).

INPUTS
timereq Pointer to a time request
datep Pointer to a date structure receiving the date
tzsecp Pointer to an integer receiving the seconds west of GMT

RESULTS
error Error value, indicating
-1 for invalid arguments
0 for success
1 for no date resource available
2 for no timezone information available

NOTES
  • The inner layout of the date structure is private and may differ among different hosts. Use functions like TUnpackDate to access it, and functions like TAddDate to perform calculations on it.
  • For measuring a relative time it can be sufficient to use a TTIME structure, which is better accessible to applications and requires less complex internal calculations. See TQueryTime and TSubTime for details.

SEE ALSO


time : TWaitTimeToc

NAME
TWaitTime - Wait for signals with a relative timeout

SYNOPSIS
signals = TTimeWaitTime(TTimeBase, timereq, timeout, sigmask)
TUINT                   TAPTR      TAPTR    TTIME*   TUINT

signals = TWaitTime(timereq, timeout, sigmask)
TUINT               TAPTR    TTIME*   TUINT

FUNCTION
Suspend the current task to wait for a set of signals or for a timeout. Any signals causing this function to return will be returned to the caller and cleared from the task's signal state. If a timeout causes the return then the return value is 0. If timeout is TNULL then this function is equivalent to exec:TWait.

INPUTS
timereq Pointer to a time request
timeout Pointer to a TTIME structure
sigmask Set of signals to wait for

RESULTS
signals Signals that caused returning, or 0 if a timeout occured

SEE ALSO


time : TWaitDateToc

NAME
TWaitDate - Wait for signals, with an absolute timeout

SYNOPSIS
signals = TTimeWaitDate(TTimeBase, timereq, datep, sigmask)
TUINT                   TAPTR      TAPTR    TDATE* TUINT

signals = TWaitDate(timereq, datep, sigmask)
TUINT               TAPTR    TDATE* TUINT

FUNCTION
Suspend the current task to wait for a set of signals or for an absolute date. Any signals causing this function to return will be returned to the caller and cleared from the task's signal state. If an expiring date causes the return then this function returns 0. If datep is TNULL then this function is equivalent to exec:TWait.
timereq Pointer to a time request
absdate Pointer to a TDATE structure
sigmask Set of signals to wait for

RESULTS
signals Signals that caused returning, or 0 if a timeout occured

NOTES
  • The absdate timeout is expected to be a system local date.

SEE ALSO


time : TDateToJulianToc

NAME
TDateToJulian - Get a Julian day from a date

SYNOPSIS
jd = TTimeDateToJulian(TTimeBase, date)
TDOUBLE                TAPTR      TDATE*

jd = TDateToJulian(date)
TDOUBLE            TDATE*

FUNCTION
Calculate the Julian day from a date structure. The Julian date counts the days since January 1st 4713 B.C. A Julian day starts at 12h universal time (UT). A specific point in time is given as a day number and the time of the day as its fraction.
The Julian date is often used for astronomical calculations.

INPUTS
date ptr to a TDATE structure

RESULTS
jd Julian day

NOTES
  • The Julian date conversion involves expensive calculations. Preferrably use functions like TMakeDate, TAddDate, TDiffDate, etc. for working with the TDATE type.
  • The Julian date knows about the date reformations that took place in the Christian world in the year 1582. The 5th to 14th October 1582 never existed in this system, as they were eliminated in order to correct derivations from the astronomical year that accumulated over the previous centuries. Leap years were introduced to alleviate the problem.

SEE ALSO


time : TJulianToDateToc

NAME
TJulianToDate - Get a date from a Julian day

SYNOPSIS
TTimeJulianToDate(TTimeBase, julian, tdate)
                  TAPTR      TDOUBLE TDATE*

TJulianToDate(julian, tdate)
              TDOUBLE TDATE*

FUNCTION
Calculate a TDATE from a Julian day.

INPUTS
julian Julian day
tdate Ptr to a TDATE structure

SEE ALSO


time : TIsLeapYearToc

NAME
TIsLeapYear - Check if a year is a leap year

SYNOPSIS
isleapyear = TTimeIsLeapYear(TTimeBase, year)
TBOOL                        TAPTR      TINT

isleapyear = TIsLeapYear(year)
TBOOL                    TINT

FUNCTION
Check if year is a leap year.

INPUTS
year Year to check

RESULTS
isleapyear TTRUE if leap year, TFALSE otherweise

NOTES
  • Leap years were introduced in the Christian world in the year 1582. This is taken into account by this function. See also TDateToJulian for further details.

SEE ALSO


time : TIsValidDateToc

NAME
TIsValidDate - Check if a date is valid

SYNOPSIS
valid = TTimeIsValidDate(TTimeBase, day, month, year)
TBOOL                    TAPTR      TINT TINT   TINT

valid = TIsValidDate(day, month, year)
TBOOL                TINT TINT   TINT

FUNCTION
Check if the given combination from day, month, year is a valid date, e.g. 29, 2, 2003 would be an invalid date, and this function would return TFALSE.

INPUTS
day, month, year Date

RESULTS
valid Boolean

SEE ALSO


time : TMYToJulianToc

NAME
TMYToJulian - Get a Julian day from a month and year

SYNOPSIS
julian = TTimeMYToJulian(TTimeBase, month, year)
TDOUBLE                  TAPTR      TINT   TINT

julian = TMYToJulian(month, year)
TDOUBLE              TINT   TINT

FUNCTION
Calculate the Julian day from the given month and year.

INPUTS
month Month to convert
year Year to convert

RESULTS
julian Julian day

EXAMPLES
To convert a full date to a Julian date, add the month's day number to the result:
julian = TMYToJulian(month, year);
julian += day;
Or, to get from a year and year's day to a Julian day:
julian = TMYToJulian(1, year);
julian += yearday;

NOTES
  • The Julian date involves expensive calculations. Preferrably use the TDATE type and use functions like TMakeDate, TAddDate, TDiffDate, etc.

SEE ALSO


time : TJulianToDMYToc

NAME
TJulianToDMY - Convert a Julian to day, month, year

SYNOPSIS
dayfract = TTimeJulianToDMY(TTimeBase, julian, pday, pmonth, pyear)
TDOUBLE                     TAPTR      TDOUBLE TINT* TINT*   TINT*

dayfract = TJulianToDMY(julian, pday, pmonth, pyear)
TDOUBLE                 TDOUBLE TINT* TINT*   TINT*

FUNCTION
Convert a Julian day to a combination of day, month, year. The remaining fraction of the day will be returned to the caller.

INPUTS
julian Julian day
pday Pointer to an integer for day (may be TNULL)
pmonth Pointer to an integer for month (may be TNULL)
pyear Pointer to an integer for year (may be TNULL)

RESULTS
dayfract Remaining fraction of the day

NOTES
  • Multiply the resulting fraction of the day
    • by 24 to get the number of hours,
    • by 1440 to get the number of minutes,
    • by 86400 to get the number of seconds,
    etc.
  • A more convenient way to decompose a Julian day can be the use of a combination of TJulianToDate and TUnpackDate.

SEE ALSO


time : TYDayToDMToc

NAME
TYDayToDM - Convert a year and yearday to a day and month

SYNOPSIS
TTimeYDayToDM(TTimeBase, yearday, year, pday, pmonth)
              TAPTR      TINT     TINT  TINT* TINT*

TYDayToDM(yearday, year, pday, pmonth)
          TINT     TINT  TINT* TINT*

FUNCTION
Convert a year and yearday to a month's day and month of the given year.

INPUTS
yearday Daynumber in the respective year
year The year
pday Pointer to an integer receiving the day (may be TNULL)
pmonth Pointer to an integer receiving the month (may be TNULL)

SEE ALSO


time : TDMYToYDayToc

NAME
TDMYToYDay - Convert day, month, year to a yearday

SYNOPSIS
yday = TTimeDMYToYDay(TTimeBase, day, month, year)
TINT                  TAPTR      TINT TINT   TINT

yday = TDMYToYDay(day, month, year)
TINT              TINT TINT   TINT

FUNCTION
Convert a date in the format day, month, year to yearday of the given year.

INPUTS
day, month, year Date

RESULTS
yday Day of the year

SEE ALSO


time : TUnpackDateToc

NAME
TUnpackDate - Unpack a date to a datebox structure

SYNOPSIS
TTimeUnpackDate(TTimeBase, tdate, datebox,         fields)
                TAPTR      TDATE* struct TDateBox* TUINT16

TUnpackDate(tdate, datebox,         fields)
            TDATE* struct TDateBox* TUINT16

FUNCTION
Convert a date to a datebox structure. At least the fields flagged in the fields argument will be inserted to the resulting datebox structure.
Specific combinations of date fields may be sufficient for your purpose, like TDB_DAY|TDB_MONTH|TDB_YEAR or TDB_YDAY|TDB_YEAR|TDB_SEC. If you want to receive all fields, pass TDB_ALL in the fields argument. The fields actually being inserted by this function (which can be more than requested) will be flagged as correponding bits in datebox->tdb_Fields.

INPUTS
tdate pointer to a source date
datebox pointer to a TDateBox structure to be filled in
fields Fields to be inserted into the datebox structure
Valid field flags:
Flag Description corresponds to
TDB_YEAR year datebox->tdb_Year
TDB_YDAY day of year datebox->tdb_YDay
TDB_MONTH month of year datebox->tdb_Month
TDB_WEEK week of year datebox->tdb_Week
TDB_WDAY day of week datebox->tdb_WDay
TDB_DAY day of month datebox->tdb_Day
TDB_HOUR hour of day datebox->tdb_Hour
TDB_MINUTE minute of hour datebox->tdb_Minute
TDB_SEC second of minute datebox->tdb_Sec
TDB_USEC 1/1000000th sec datebox->tdb_USec
TDB_ALL all of the above all of the above

SEE ALSO


time : TPackDateToc

NAME
TPackDate - Pack fields in a datebox structure to a date

SYNOPSIS
success = TTimePackDate(TTimeBase, datebox,         tdate)
TBOOL                   TAPTR      struct TDateBox* TDATE*

success = TPackDate(datebox,         tdate)
TBOOL               struct TDateBox* TDATE*

FUNCTION
Convert a datebox structure to a date. All fields with a corresponding bit in datebox->tdb_Fields will be possibly taken into account. Fields required are TDB_YEAR and either TDB_MONTH, TDB_DAY or TDTB_YDAY. More fields like TDB_HOUR, TDB_MINUTE etc. will be incorporated to the resulting date as well, if they are present. If not enough relevant fields are provided then this function returns TFALSE.
See TUnpackDate for a description of the flags in datebox->tdb_Fields.

INPUTS
datebox Pointer to a source datebox structure
tdate Pointer to a destination TDATE

RESULTS
success TTRUE if conversion succeeded

NOTES
  • See TMakeDate for annotations regarding the precision of dates and times.

SEE ALSO


time : TGetWeekDayToc

NAME
TGetWeekDay - Get weekday number from day, month, year

SYNOPSIS
daynum = TTimeGetWeekDay(TTimeBase, day,  month, year)
TINT                     TAPTR      TINT  TINT   TINT

daynum = TGetWeekDay(day,  month, year)
TINT                 TINT  TINT   TINT

FUNCTION
Get a weekday number from date. The number is defined as 0 (TDT_SUNDAY) to 6 (TDT_SATURDAY). See the defines in tek/mod/time.h.

INPUTS
day, month, year Date

RESULTS
daynum Week's day number (0...6)

NOTES
  • An alternative way to get to a weekday number would be the use of TUnpackDate and the field TDB_WDAY.

SEE ALSO


time : TGetWeekNumberToc

NAME
TGetWeekNumber - Get week number in a year from a date

SYNOPSIS
weeknum = TTimeGetWeekNumber(TTimeBase, day, month, year)
TINT                         TAPTR      TINT TINT   TINT

weeknum = TGetWeekNumber(day, month, year)
TINT                     TINT TINT   TINT

FUNCTION
Calculate the week number from a date.

INPUTS
day, month, year Date

RESULTS
weeknum Year's week number

NOTES
  • It is possible that a day at the end of the year is in the first week of the following year. For example, the 29th December 2003 is in week 1 of the year 2004 already. Be prepared for this.
  • An alternative way to get a week number may be the use of TUnpackDate and the field TDB_WEEK.

SEE ALSO


time : TMakeDateToc

NAME
TMakeDate - Initialize a date structure with date and time

SYNOPSIS
valid = TTimeMakeDate(TTimeBase, tdate, day, month, year, time)
TBOOL                 TAPTR      TDATE* TINT TINT   TINT  TTIME*

valid = TMakeDate(tdate, day, month, year, time)
TBOOL             TDATE* TINT TINT   TINT  TTIME*

FUNCTION
Initialize a date structure from a day, month, year, and optionally from a time structure. If day, month, year form an invalid date, this function return TFALSE.

INPUTS
tdate Date structure to be filled
day, month, year Date
time Pointer to a TTIME structure. May be TNULL.

RESULTS
valid Boolean. TTRUE if the date is valid

NOTES
  • When a time specification is incorporated into the resulting date, then it is not guaranteed to be taken into account with a precision higher than 1/1000th of a second.

SEE ALSO


time : TAddDateToc

NAME
TAddDate - Add a number of days and a time to a date

SYNOPSIS
TTimeAddDate(TTimeBase, date,  ndays, time)
             TAPTR      TDATE* TINT   TTIME*

TAddDate(date,  ndays, time)
         TDATE* TINT   TTIME*

FUNCTION
Add a number of days and optionally a time to a date.

INPUTS
tdate Date structure
ndays Number of days to add. Can be 0.
time Pointer to a TTIME structure. Can be TNULL.

NOTES
  • See TMakeDate for annotations about the precision of dates and times.
  • Do not add negative values in the time structure, use the function TSubDate instead.

SEE ALSO


time : TSubDateToc

NAME
TSubDate - Substract a number of days and a time from a date

SYNOPSIS
TTimeSubDate(TTimeBase, date,  ndays, time)
             TAPTR      TDATE* TINT   TTIME*

TSubDate(date,  ndays, time)
         TDATE* TINT   TTIME*

FUNCTION
Subtract a number of days and optionally a time from a date.

INPUTS
tdate Date structure
ndays Number of days to subtract. Can be 0.
time Pointer to a TTIME structure. Can be TNULL.

NOTES
  • See TMakeDate for annotations about the precision of dates and times.
  • Do not subtract negative values in the time structure, use the function TAddDate instead.

SEE ALSO


time : TDiffDateToc

NAME
TDiffDate - Get the difference between dates

SYNOPSIS
days = TTimeDiffDate(TTimeBase, date1, date2, timep)
TINT                 TAPTR      TDATE* TDATE* TTIME*

days = TDiffDate(date1, date2, timep)
TINT             TDATE* TDATE* TTIME*

FUNCTION
This function returns the difference in number of days between tdate1 and tdate2. The difference in time will be inserted, optionally, into the time structure being pointed to by timep.
Note that if tdate1 is before tdate2 then the resulting number of days will be negative, but the time difference (in seconds and microseconds) will always be inserted as positive numbers.

INPUTS
tdate1, tdate2 Pointers to TDATE structures
timep Pointer to a TTIME structure receiving a time difference, or TNULL

RESULTS
days Number of days difference

NOTES
  • See TMakeDate for annotations about the precision of dates and times.

SEE ALSO


time : TDelayToc

NAME
TDelay - Suspend for some time

SYNOPSIS
TTimeDelay(TTimeBase, timereq, timeout)
           TAPTR      TAPTR    TTIME*

TDelay(timereq, timeout)
       TAPTR    TTIME*

FUNCTION
This function suspends the current task for the specified time. The time request is a timer.device instance and usually obtained with a call to TAllocTimeRequest.

INPUTS
timereq Pointer to a time request
timeout Pointer to a TTIME structure containing the time to wait

SEE ALSO


time : ABOUTToc

VERSION
$Id: time.html,v 1.7 2005/09/07 01:19:38 tmueller Exp $

REVISION HISTORY
$Log: time.html,v $ Revision 1.7 2005/09/07 01:19:38 tmueller added inline function equivalents to synopsis Revision 1.2 2005/06/29 21:41:02 tmueller minor fixes
Revision 1.1 2005/06/19 20:42:21 tmueller added
Revision 1.4 2004/01/21 14:31:59 tmueller Bugfixes and better wording
Revision 1.3 2003/12/19 18:15:01 tmueller Improved precision for notes on TAllocTimeRequest and TQueryTime
Revision 1.2 2003/12/14 01:40:48 tmueller Better wording, fixes, changes to TQueryTime, addition of TDelay
Revision 1.1.1.1 2003/12/11 07:17:27 tmueller Krypton import


time : Table of contents


Generated Wed Sep 7 02:18:02 2005 from time.doc