/*------------------------------------------------------------------------------*
 * File Name: time.h															*
 * Creation: AW 10/21/2003														*
 * Purpose: Origin C header	for basic io functions								*
 * Copyright (c) OriginLab Corp.	2003										*
 * All Rights Reserved															*
 * 																				*
 * Modification Log:															*
 *------------------------------------------------------------------------------*/

#ifndef _TIME_H
#define _TIME_H   


typedef long time_t; 
typedef struct {
        int tm_sec;     /* seconds after the minute - [0,59] */
        int tm_min;     /* minutes after the hour - [0,59] */
        int tm_hour;    /* hours since midnight - [0,23] */
        int tm_mday;    /* day of the month - [1,31] */
        int tm_mon;     /* months since January - [0,11] */
        int tm_year;    /* years since 1900 */
        int tm_wday;    /* days since Sunday - [0,6] */
        int tm_yday;    /* days since January 1 - [0,365] */
        int tm_isdst;   /* daylight savings time flag */
        }tm, TM;

extern int _daylight;

extern long _timezone;

extern char *_tzname[2];



// basic time functions

/** >Date Time
Return: 
	a pointer to a structure of type tm. The fields of the returned structure hold the evaluated value of the timer argument in UTC rather than in local time. Each of the structure fields is of type int, as follows:
		tm_sec: Seconds after minute (0 - 59)
		tm_min:	Minutes after hour (0 - 59)
		tm_hour:Hours since midnight (0 - 23)
		tm_mday:Day of month (1 - 31)
		tm_mon:	Month (0 - 11; January = 0)
		tm_year:Year (current year minus 1900)
		tm_wday:Day of week (0 - 6; Sunday = 0)
		tm_yday:Day of year (0 - 365; January 1 = 0)
		tm_isdst:Always 0 for gmtime

	The gmtime, mktime, and localtime functions use the same single, statically allocated structure to hold their results. Each call to one of these functions destroys the result of any previous call. 
	If timer represents a date before midnight, January 1, 1970, gmtime returns NULL. There is no error return.
Parameter:
	timer = Pointer to stored time. The time is represented as seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC).
Remarks:
	The gmtime function breaks down the timer value and stores it in a statically allocated structure of type tm, defined in TIME.H. The value of timer is usually obtained from a call to the time function.
Examples:
	see example codes of time_t time( time_t *timer ).
SeeAlso:
	mktime, localtime and time.
*/
TM* gmtime( const time_t *timer );

/** >Date Time
Return:
	localtime returns a pointer to the structure result. If the value in timer represents a date before midnight, January 1, 1970, localtime returns NULL. The fields of the structure type tm store the following values, each of which is an int:
	tm_sec:	Seconds after minute (0 - 59)
	tm_min:	Minutes after hour (0 - 59)
	tm_hour:Hours after midnight (0 - 23)
	tm_mday:Day of month (1 - 31)
	tm_mon:	Month (0 - 11; January = 0)
	tm_year:Year (current year minus 1900)
	tm_wday:Day of week (0 - 6; Sunday = 0)
	tm_yday:Day of year (0 - 365; January 1 = 0)
	tm_isdst:Positive value if daylight saving time is in effect; 0 if daylight saving time is not in effect; negative value if status of daylight saving time is unknown. The C run-time library assumes t
	he United States’s rules for implementing the calculation of Daylight Saving Time (DST). 
Parameter:
	timer = Pointer to stored time
Remarks
	The localtime function converts a time stored as a time_t value and stores the result in a structure of type tm. The long value timer represents the seconds elapsed since midnight (00:00:00), January 1, 1970, 
	coordinated universal time (UTC). This value is usually obtained from the time function.
	gmtime, mktime, and localtime all use a single statically allocated tm structure for the conversion. Each call to one of these routines destroys the result of the previous call.
	localtime corrects for the local time zone if the user first sets the global environment variable TZ. When TZ is set, three other environment variables (_timezone, _daylight, and _tzname) 
	are automatically set as well. See _tzset for a description of these variables. TZ is a Microsoft extension and not part of the ANSI standard definition of localtime.
	Note   The target environment should try to determine whether daylight saving time is in effect.
Examples:
	see example codes of time_t time( time_t *timer ).
SeeAlso:
	gmtime, mktime, and time

*/
TM* localtime( const time_t *timer );


/** >Date Time
	By now, we do not support _daylight,_timezone directly, and _tzname, you need call this function to get them.
	and, in the OC file you need call this function need declare them as "extern".
	_daylight: Nonzero if daylight-saving-time zone (DST) is specified in TZ; otherwise, 0. Default value is 1. 
	_timezone: Difference in seconds between coordinated universal time and local time. Default value is 28,800. 
	_tzname[0]: Time-zone name derived from TZ environment variable. 
	_tzname[1]: DST zone name derived from TZ environment variable. Default value is PDT (Pacific daylight time). If DST zone is omitted from TZ, _tzname[1] is empty string. 
Examples:
    _tzset();
    gettimeSetting(); // must call this function to get _daylight, _timezone and _tzname(global varaibles).
    printf( "_daylight = %d\n", _daylight );
    printf( "_timezone = %ld\n", _timezone );
    printf( "_tzname[0] = %s\n", _tzname[0] );
*/
void gettimeSetting();  


#pragma dll(msvcrt, system)


/** >Date Time
Return: 
	time returns the time in elapsed seconds. There is no error return.
Parameter:
	timer = Storage location for time
Remarks:
	The time function returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time, according to the system clock. The return 
	value is stored in the location given by timer. This parameter may be NULL, in which case the return value is not stored.
Examples:
	time_t ltime;
	tm *today, *gmt, xmas = { 0, 0, 12, 25, 11, 93 };
	char ampm[] = "AM";

    // Set time zone from TZ environment variable. If TZ is not set,
    // the operating system is queried to obtain the default value 
    // for the variable. 
    _tzset();
    gettimeSetting(); // must call this function to get _daylight, _timezone and _tzname(global varaibles).
    printf( "_daylight = %d\n", _daylight );
    printf( "_timezone = %ld\n", _timezone );
    printf( "_tzname[0] = %s\n", _tzname[0] );
    
	// Get UNIX-style time and display as number and string. 
    time( &ltime );
    printf( "Time in seconds since UTC 1/1/70:\t%ld\n", ltime );

    // Display UTC. 
    gmt = gmtime( &ltime );
    printf( "Coordinated universal time:\t\t%s", asctime( gmt ) );
    
    // Convert to time structure and adjust for PM if necessary. 
    today = localtime( &ltime );
    if( today->tm_hour > 12 )
    {
	   strcpy( ampm, "PM" );
	   today->tm_hour -= 12;
    }
    if( today->tm_hour == 0 )  // Adjust if midnight hour. 
   		today->tm_hour = 12;
	
    // Make time for noon on Christmas, 1993. 
    if( mktime( &xmas ) != (time_t)-1 )
   		printf( "Christmas\t\t\t\t%s\n", asctime( &xmas ) );

    // Use time structure to build a customized time string. 
    today = localtime( &ltime );
	
*/
time_t time( time_t *timer );


/** >Date Time
Return:
	the elapsed time in seconds, from timer0 to timer1. The value returned is a double-precision floating-point number.
Parameters:
	timer1 = Ending time;
	timer0 = Beginning time
Remarks:
	The difftime function computes the difference between the two supplied time values timer0 and timer1.
Examples:
	time_t   start, finish;
   	long loop;
   	double   result, elapsed_time;

	printf( "Multiplying 2 floating point numbers 10 million times...\n" );
	   
	time( &start );
	for( loop = 0; loop < 10000000; loop++ )
	   result = 3.63 * 5.27; 
	time( &finish );
	elapsed_time = difftime( finish, start );
	printf( "\nProgram takes %6.0f seconds.\n", elapsed_time );
*/
double difftime( time_t timer1, time_t timer0 ); 


/** >Date Time
Return:
	mktime returns the specified calendar time encoded as a value of type time_t. If timeptr references a date before midnight, January 1, 1970, 
	or if the calendar time cannot be represented, the function returns -1 cast to type time_t.

Parameter:
	timeptr = Pointer to time structure

Remarks:

	The mktime function converts the supplied time structure (possibly incomplete) pointed to by timeptr into a fully defined structure with normalized 
	values and then converts it to a time_t calendar time value. For description of tm structure fields, see asctime. The converted time has the same encoding 
	as the values returned by the time function. The original values of the tm_wday and tm_yday components of the timeptr structure are ignored, and the original 
	values of the other components are not restricted to their normal ranges.
	
	mktime handles dates in any time zone from midnight, January 1, 1970, to January 18, 19:14:07, 2038. If successful, mktime sets the values of tm_wday 
	and tm_yday as appropriate and sets the other components to represent the specified calendar time, but with their values forced to the normal ranges; 
	the final value of tm_mday is not set until tm_mon and tm_year are determined. When specifying a tm structure time, set the tm_isdst field to 0 to indicate 
	that standard time is in effect, or to a value greater than 0 to indicate that daylight savings time is in effect, or to a value less than zero to have 
	the C run-time library code compute whether standard time or daylight savings time is in effect. (The C run-time library assumes the United States’s rules 
	for implementing the calculation of Daylight Saving Time). tm_isdst is a required field. If not set, its value is undefined and the return value from mktime 
	is unpredictable. If timeptr points to a tm structure returned by a previous call to asctime, gmtime, or localtime, the tm_isdst field contains the correct value.
	
	Note that gmtime and localtime use a single statically allocated buffer for the conversion. If you supply this buffer to mktime, the previous contents are destroyed.
SeeAlso:
	gmtime, localtime, and time
*/
time_t mktime( TM *timeptr );



/** >Date Time
Remarks:

	The _tzset function uses the current setting of the environment variable TZ to assign values to three global variables: _daylight, _timezone, and _tzname. These variables 
	are used by the _ftime and localtime functions to make corrections from coordinated universal time (UTC) to local time, and by the time function to compute UTC from system 
	time. Use the following syntax to set the TZ environment variable:
	
	set TZ=tzn[+ | -]hh[:mm[:ss] ][dzn]
	tzn
	Three-letter time-zone name, such as PST. You must specify the correct offset from local time to UTC.
	hh
	Difference in hours between UTC and local time. Optionally signed.
	mm
	Minutes. Separated from hh by a colon (:).
	ss
	Seconds. Separated from mm by a colon (:).
	dzn
	Three-letter daylight-saving-time zone such as PDT. If daylight saving time is never in effect in the locality, set TZ without a value for dzn. The C run-time library assumes the 
	United States’s rules for implementing the calculation of Daylight Saving Time (DST). 
	
	For example, to set the TZ environment variable to correspond to the current time zone in Germany, you can use one of the following statements:
	
	set TZ=GST-1GDT
	set TZ=GST+1GDT
	
	These strings use GST to indicate German standard time, assume that Germany is one hour ahead of UTC, and assume that daylight savings time is in effect.
	
	If the TZ value is not set, _tzset attempts to use the time zone information specified by the operating system. Under Windows NT and Windows 95, this information is specified in the Control Panel’s Date/Time application. If _tzset cannot obtain this information, it uses PST8PDT by default, which signifies the Pacific time zone. 
	
	Based on the TZ environment variable value, the following values are assigned to the global variables _daylight, _timezone, and _tzname when _tzset is called:
	
	Global Variable Description Default Value 
	_daylight Nonzero value if a daylight-saving-time zone is specified in TZ setting; otherwise, 0 1 
	_timezone Difference in seconds between UTC and local time. 28800 (28800 seconds equals 8 hours) 
	_tzname[0] String value of time-zone name from TZ environmental variable; empty if TZ has not been set PST 
	_tzname[1] String value of daylight-saving-time zone; empty if daylight-saving-time zone is omitted from TZ environmental variable PDT 
	
	The default values shown in the preceding table for _daylight and the _tzname array correspond to "PST8PDT". If the DST zone is omitted from the TZ environmental variable, the value of _daylight is 0 and the _ftime, gmtime, and localtime functions return 0 for their DST flags.
Examples:
    _tzset();
    gettimeSetting(); // must call this function to get _daylight, _timezone and _tzname(global varaibles).
    printf( "_daylight = %d\n", _daylight );
    printf( "_timezone = %ld\n", _timezone );
    printf( "_tzname[0] = %s\n", _tzname[0] );

*/
void _tzset( void );

/** >Date Time
Remarks:
	Converts a tm time structure to a character string.
examples:
	struct tm *newtime;
	time_t aclock;
	time( &aclock );                 // Get time in seconds 

	newtime = localtime( &aclock );  // Convert time to struct 
                                    // tm form 
	// Print local time as a string 
	printf( "The current date and time are: %s", asctime( newtime ) );

*/
char* asctime( TM *timeptr );


#pragma dll(@OUTL)

/** >Date Time
	Convert time from a TM structure to a SYSTEMTIME structure
		TM:
		{	int tm_sec;     // seconds after the minute - [0,59] 
			int tm_min;     // minutes after the hour - [0,59] 
			int tm_hour;    // hours since midnight - [0,23] 
			int tm_mday;    // day of the month - [1,31] 
			int tm_mon;     // months since January - [0,11] 
			int tm_year;    // years since 1900 
			int tm_wday;    // days since Sunday - [0,6] 
			int tm_yday;    // days since January 1 - [0,365] 
			int tm_isdst;   // daylight savings time flag 
		}
		SYSTEMTIME: 
		{  
			WORD wYear;     	// The current year.
			WORD wMonth; 		// The current month; January is 1.
			WORD wDayOfWeek;	// The current day of the week; Sunday is 0, Monday is 1, and so on.     
			WORD wDay;     		// The current day of the month.
			WORD wHour;     	// The current hour.
			WORD wMinute; 		// The current minute.
			WORD wSecond;     	// The current second.
			WORD wMilliseconds; // The current millisecond.
		}
Examples:
	see example of convert_time_to_local
SeeAlso:
	systemtime_to_tm, convert_time_to_local
*/
void tm_to_systemtime(TM* pTM, SYSTEMTIME * pSysTime);

/** >Date Time
	convert system time struct to tm struct.
SeeAlso:
	tm_to_systemtime
*/
void systemtime_to_tm(TM* pTM, SYSTEMTIME * pSysTime);

/** >Date Time
	Converts a time value to a structure.\
Examples:
	TM tm1;
	time_t ltime;
    _tzset();
    
	// Get UNIX-style time and display as number and string. 
    time( &ltime );
	convert_time_to_tm(&ltime, &tm1 );
    printf( "Coordinated universal time:\t\t%s", asctime( &tm1 ) );
SeeAlso:
	gmtime.
*/
void convert_time_to_tm(time_t* pTime, TM* pTM);

/** >Date Time
	Converts a time value and corrects for the local time zone..
Examples:
	SYSTEMTIME st;
	TM tmLocal;
	time_t aclock;
	
	time( &aclock );
	convert_time_to_local( &aclock , &tmLocal);
    tm_to_systemtime(&tmLocal, &st);
	double dDate;
	SystemTimeToJulianDate(&dDate, &st);
	out_str(get_date_str(dDate, LDF_SHORT_AND_HHMMSS_SEPARCOLON));
SeeAlso:
	localtime, SystemTimeToJulianDate, get_date_str, tm_to_systemtime
*/
void convert_time_to_local(time_t* pTime, TM* pLocalTM);

/** >Date Time
	Get time information
Examples:
    _tzset();
    get_time_setting(&_daylight, &_timezone, _tzname); // must call this function to get _daylight, _timezone and _tzname(global varaibles).
    printf( "_daylight = %d\n", _daylight );
    printf( "_timezone = %ld\n", _timezone );
    printf( "_tzname[0] = %s\n", _tzname[0] );
*/
void get_time_setting(int* pdaylight, long* ptimezone, char* tzname[2]);

#endif //_TIME_H
