CODA Time

Functions
int	coda_datetime_to_double (int YEAR, int MONTH, int DAY, int HOUR, int MINUTE, int SECOND, int MUSEC, double *datetime)
int	coda_utcdatetime_to_double (int YEAR, int MONTH, int DAY, int HOUR, int MINUTE, int SECOND, int MUSEC, double *datetime)
int	coda_double_to_datetime (double datetime, int *YEAR, int *MONTH, int *DAY, int *HOUR, int *MINUTE, int *SECOND, int *MUSEC)
int	coda_double_to_utcdatetime (double datetime, int *YEAR, int *MONTH, int *DAY, int *HOUR, int *MINUTE, int *SECOND, int *MUSEC)
int	coda_time_to_string (double datetime, char *str)
int	coda_time_to_utcstring (double datetime, char *str)
int	coda_string_to_time (const char *str, double *datetime)
int	coda_utcstring_to_time (const char *str, double *datetime)

---

Detailed Description

The CODA Time module contains all functions and procedures related to time handling.

Most of the time functions assume that you stay within the same time system. In CODA a single time value can be represented in three different forms and CODA provides functions to convert between them:

• as a floating point value indicating the amount of seconds since 2000-01-01 00:00:00.00000 (this Jan 1st 2000 is an 'epoch' in the same time system as your time value is in)
• as a decomposition of individual year, month, day, hour, minute, second, and microsecond values.
• as a string (e.g. "2005-04-03 02:01:00.00000").

The problem is that most time values are provided using the UTC time system. However, because of leap seconds, the only valid representations for a UTC time value are the last two. The problem with the floating point representation is that there is no unique definition of the Jan 1st 2000 epoch. Whenever a leap second is introduced this also shifts the epoch by one second. For instance, you cannot calculate the difference in seconds between UTC 2006-01-02 00:00:00 and UTC 2005-12-30 00:00:00 by just subtracting the two floating point representations of those times because of the leap second at 2005-12-31 23:59:60. If you would just subtract the values you would get 172800 seconds, but the actual answer should be 172801 seconds. If you want to calculate leap-second-accurate time differences the only solution is to convert your UTC time values to a time system that is based on actual clock ticks such as TAI or GPS.

In CODA this problem is solved by introducing special UTC leap-second-aware functions for converting from a floating point value to a string or datetime decomposition (and vice versa). The floating point value is always in TAI whereas the string and datetime decomposition values represent the time value in UTC (be aware that the value for 'amount of seconds in a minute' can range from 0 to 60 inclusive for UTC!)

For each public time function there are thus two variants. One that treats all days as having 86400 seconds (and where both the input(s) and output(s) are of the same time system) and one that is able to deal with leap seconds. The functions that deal with leap seconds have 'utc' in the name and assume that the number of seconds since 2000-01-01 is a value in the TAI time system whereas the datetime decomposition (or string value) is using the UTC time system.

Below is an overview of time systems that are commonly used:

• TAI: International Atomic Time scale International Atomic Time (TAI) represents the mean of readings of several atomic clocks, and its fundamental unit is exactly one SI second at mean sea level and is, therefore, constant and continuous. d TAI = TAI - UTC is the increment to be applied to UTC to give TAI.
• UTC: Coordinated Universal Time The time system generally used is the Coordinated Universal Time (UTC), previously called Greenwich Mean Time. The UTC is piece wise uniform and continuous, i.e. the time difference between UTC and TAI is equal to an integer number of seconds and is constant except for occasional jumps from inserted integer leap seconds. The leap seconds are inserted to cause UTC to follow the rotation of the Earth, which is expressed by means of the non uniform time reference Universal Time UT1. If UT1 is predicted to lag behind UTC by more than 0.9 seconds, a leap second is inserted. CODA has a built-in table of leap seconds up to 2009-01-01. You can use a more recent table by downloading the recent list of leap seconds from ftp://maia.usno.navy.mil/ser7/tai-utc.dat and set the environment variable CODA_LEAP_SECOND_TABLE with a full path to this file.
• UT1: Universal Time Universal Time (UT1) is a time reference that conforms, within a close approximation, to the mean diurnal motion of the Earth. It is determined from observations of the diurnal motions of the stars, and then corrected for the shift in the longitude of the observing stations caused by the polar motion.
• GPS: GPS Time GPS Time is an atomic clock time similar to but not the same as UTC time. It is synchronised to UTC but the main difference relies in the fact that GPS time does not introduce any leap second. Thus, the introduc tion of UTC leap second causes the GPS time and UTC time to differ by a known integer number of cumulative leap seconds; i.e. the leap seconds that have been accumulated since GPS epoch in midnight January 5, 1980. d GPS = TAI - GPS is the increment to be applied to GPS to give TAI, being a constant value of 19 seconds.

---

Function Documentation

int coda_datetime_to_double	(	int	YEAR,
		int	MONTH,
		int	DAY,
		int	HOUR,
		int	MINUTE,
		int	SECOND,
		int	MUSEC,
		double *	datetime
	)

Retrieve the number of seconds since Jan 1st 2000 for a certain date and time.

Warning:

This function does _not_ perform any leap second correction. The returned value is just a straightforward conversion using 86400 seconds per day. UTC time

Parameters:

YEAR	The year.
MONTH	The month of the year (1 - 12).
DAY	The day of the month (1 - 31).
HOUR	The hour of the day (0 - 23).
MINUTE	The minute of the hour (0 - 59).
SECOND	The second of the minute (0 - 59).
MUSEC	The microseconds of the second (0 - 999999).
datetime	Pointer to the variable where the amount of seconds since Jan 1st 2000 will be stored.

Returns:

• 0, Success.
• -1, Error occurred (check coda_errno).

int coda_double_to_datetime	(	double	datetime,
		int *	YEAR,
		int *	MONTH,
		int *	DAY,
		int *	HOUR,
		int *	MINUTE,
		int *	SECOND,
		int *	MUSEC
	)

Retrieve the decomposed date corresponding with the given amount of seconds since Jan 1st 2000.

Warning:

This function does _not_ perform any leap second correction. The returned value is just a straightforward conversion using 86400 seconds per day.

Parameters:

datetime	The amount of seconds since Jan 1st 2000.
YEAR	Pointer to the variable where the year will be stored.
MONTH	Pointer to the variable where the month of the year (1 - 12) will be stored.
DAY	Pointer to the variable where the day of the month (1 - 31) will be stored.
HOUR	Pointer to the variable where the hour of the day (0 - 23) will be stored.
MINUTE	Pointer to the variable where the minute of the hour (0 - 59) will be stored.
SECOND	Pointer to the variable where the second of the minute (0 - 59) will be stored.
MUSEC	Pointer to the variable where the microseconds of the second (0 - 999999) will be stored.

Returns:

• 0, Success.
• -1, Error occurred (check coda_errno).

int coda_double_to_utcdatetime	(	double	datetime,
		int *	YEAR,
		int *	MONTH,
		int *	DAY,
		int *	HOUR,
		int *	MINUTE,
		int *	SECOND,
		int *	MUSEC
	)

Retrieve the decomposed UTC date corresponding with the given amount of TAI seconds since Jan 1st 2000. This function assumes the input to by the number of seconds since 2000-01-01 in the TAI system. The returned date/time components will be the corresponding UTC datetime (using proper leap second handling for the TAI to UTC conversion). For example: -88361290 will be 1972-01-01 00:00:00 UTC 0 will be 1999-31-12 23:59:28 UTC 284083232 will be 2008-12-31 23:59:59 UTC 284083233 will be 2008-12-31 23:59:60 UTC 284083234 will be 2009-01-01 00:00:00 UTC

Warning:

For dates before 1972-01-01 UTC a fixed leap second offset of 10 is used.

Note:

CODA has a built in table of leap seconds up to Jan 2009. To use a more recent leap second table, download the most recent file from ftp://maia.usno.navy.mil/ser7/tai-utc.dat and set the environment variable CODA_LEAP_SECOND_TABLE with a full path to this file.

Parameters:

datetime	The amount of seconds since Jan 1st 2000.
YEAR	Pointer to the variable where the year will be stored.
MONTH	Pointer to the variable where the month of the year (1 - 12) will be stored.
DAY	Pointer to the variable where the day of the month (1 - 31) will be stored.
HOUR	Pointer to the variable where the hour of the day (0 - 23) will be stored.
MINUTE	Pointer to the variable where the minute of the hour (0 - 59) will be stored.
SECOND	Pointer to the variable where the second of the minute (0 - 60) will be stored.
MUSEC	Pointer to the variable where the microseconds of the second (0 - 999999) will be stored.

Returns:

• 0, Success.
• -1, Error occurred (check coda_errno).

int coda_string_to_time	(	const char *	str,
		double *	datetime
	)

Convert a time string to a floating point time value. The time string needs to have one of the following formats:

• "YYYY-MM-DD hh:mm:ss.uuuuuu"
• "YYYY-MM-DD hh:mm:ss"
• "YYYY-MM-DD"
• "DD-MMM-YYYY hh:mm:ss.uuuuuu"
• "DD-MMM-YYYY hh:mm:ss"
• "DD-MMM-YYYY"

As an example, both the strings "2000-01-01 00:00:01.234567" and "01-JAN-2000 00:00:01.234567" will result in a time value of 1.234567.

Warning:

This function does not perform any leap second correction.

Parameters:

str	String containing the time in one of the supported formats.
datetime	Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000.

Returns:

• 0, Success.
• -1, Error occurred (check coda_errno).

int coda_time_to_string	(	double	datetime,
		char *	str
	)

Convert a floating point time value to a string. The string will be formatted as "YYYY-MM-DD HH:MM:SS.mmmmmm" and it will have a fixed length.
The time string will be stored in the str parameter. This parameter should be allocated by the user and should be 27 bytes long.

The str parameter will be 0 terminated.

Warning:

This function does not perform any leap second correction.

Parameters:

datetime	Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000.
str	String representation of the floating point time value.

Returns:

• 0, Success.
• -1, Error occurred (check coda_errno).

int coda_time_to_utcstring	(	double	datetime,
		char *	str
	)

Convert a floating point TAI time value to a UTC string. The string will be formatted as "YYYY-MM-DD HH:MM:SS.mmmmmm" and it will have a fixed length.
The time string will be stored in the str parameter. This parameter should be allocated by the user and should be 27 bytes long.

The str parameter will be 0 terminated.

This function performs proper leap second correction in the conversion from TAI to UTC (see also coda_double_to_utcdatetime()).

Warning:

This function does not perform any leap second correction.

Parameters:

datetime	Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000.
str	String representation of the floating point time value.

Returns:

• 0, Success.
• -1, Error occurred (check coda_errno).

int coda_utcdatetime_to_double	(	int	YEAR,
		int	MONTH,
		int	DAY,
		int	HOUR,
		int	MINUTE,
		int	SECOND,
		int	MUSEC,
		double *	datetime
	)

Retrieve the number of TAI seconds since Jan 1st 2000 for a certain UTC date and time using leap second correction. This function assumes the input to be an UTC datetime. The returned value will be the seconds since 2000-01-01 in the TAI time system (using proper leap second handling for the UTC to TAI conversion). For example: 1972-01-01 00:00:00 UTC will be -883612790 2000-01-01 00:00:00 UTC will be 32 2008-12-31 23:59:59 UTC will be 284083232 2008-12-31 23:59:60 UTC will be 284083233 2009-01-01 00:00:00 UTC will be 284083234

Warning:

For dates before 1972-01-01 UTC a fixed leap second offset of 10 is used.

Note:

CODA has a built in table of leap seconds up to Jan 2009. To use a more recent leap second table, download the most recent file from ftp://maia.usno.navy.mil/ser7/tai-utc.dat and set the environment variable CODA_LEAP_SECOND_TABLE with a full path to this file.

Parameters:

YEAR	The year.
MONTH	The month of the year (1 - 12).
DAY	The day of the month (1 - 31).
HOUR	The hour of the day (0 - 23).
MINUTE	The minute of the hour (0 - 59).
SECOND	The second of the minute (0 - 60).
MUSEC	The microseconds of the second (0 - 999999).
datetime	Pointer to the variable where the amount of seconds since Jan 1st 2000 will be stored.

Returns:

• 0, Success.
• -1, Error occurred (check coda_errno).

int coda_utcstring_to_time	(	const char *	str,
		double *	datetime
	)

Convert a UTC time string to a TAI floating point time value. The time string needs to have one of the following formats:

• "YYYY-MM-DD hh:mm:ss.uuuuuu"
• "YYYY-MM-DD hh:mm:ss"
• "YYYY-MM-DD"
• "DD-MMM-YYYY hh:mm:ss.uuuuuu"
• "DD-MMM-YYYY hh:mm:ss"
• "DD-MMM-YYYY"

This function performs proper leap second correction in the conversion from UTC to TAI (see also coda_utcdatetime_to_double()).

As an example, both the strings "2000-01-01 00:00:01.234567" and "01-JAN-2000 00:00:01.234567" will result in a time value of 33.234567.

Warning:

This function does not perform any leap second correction.

Parameters:

str	String containing the time in one of the supported formats.
datetime	Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000.

Returns:

• 0, Success.
• -1, Error occurred (check coda_errno).