This chapter discusses the interfaces of the EPS routines that deal with EPS internal time representation form. The EPS internal representation for time is a two-integer-number format. The first integer is the true Julian Day Number (e.g. May 23,1968 = 2,440,000). This true Julian Day should not be confused with the year-day (e.g. Feb. 2 is year-day 33), which is frequently called Julian Day by oceanographers and meteorologists. Our true Julian Day Number will begin at midnight (the Julian Day Number used by astronomers begins at noon). The second integer is the number of milliseconds since midnight with 86,400,000 in a day. July 4, 1994 16:57:23.217 GMT is 2,449,538 and 61,043,217 in EPS internal time representation. All times are assumed to be GMT. Once a data file is loaded to the internal database, the time axis will be converted to EPS internal time representation. When write an EPS file, the time axis will be converted back its default time format or to the format specified by user. For classic EPIC data file, EPS routines only read and write classic EPIC default time format. Operations supported on time manipulation routines are:
The function ep_time_to_mdyhms (or eptimetomdyhms for Fortran) converts internal EPS time representation to numerical values of month, day, year, hour, minute and second.
ep_time_to_mdyhms: C Interface
void ep_time_to_mdyhms(long* time, int* mon, int* day, int* yr,
int* hour, int* min, float* sec)
time[2] I EPS internal time format; i.e. time[0]=True Julian Days,
time[1]=milliseconds since 0:00 GMT
mon O month, 1-12
day O day of month, 1-31
yr O year (e.g. 1984)
hour O hour of day, GMT
min O minute of hour
sec O seconds of minute, to nearest millisecond
eptimetomdyhms: FORTRAN Interface
subroutine eptimetomdyhms(integer time(2), integer mon, integer day,
integer yr, integer hour, integer min,
real sec)
time I EPS internal time format; i.e. time(1)=True Julian Days,
time(2)=milliseconds since 0:00 GMT
mon O month, 1-12
day O day of month, 1-31
yr O year (e.g. 1984)
hour O hour of day, GMT
min O minute of hour
sec O seconds of minute, to nearest millisecond
The function mdyhms_to_ep_time (or mdyhmstoeptime for Fortran) converts numerical values of month, day, year, hour, minute and second to the EPS internal time representation. If invalid input month, day, hour, minute or second is detected, the output EPS time (both True Julian Day and millisecond) will contain 0.
mdyhms_to_ep_time: C Interface
void mdyhms_to_ep_time(int mon, int day, int yr, int hour, int min,
float sec, long* time)
mon I month, 1-12
day I day of month, 1-31
yr I year (e.g. 1984)
hour I hour of day, GMT
min I minute of hour
sec I seconds of minute, to nearest millisecond
time[2] O EPS internal time format
mdyhmstoeptime: FORTRAN Interface
subroutine mdyhmstoeptime(integer mon, integer day, integer yr,
integer hour, integer min, real sec,
integer time(2))
mon I month, 1-12
day I day of month, 1-31
yr I year (e.g. 1984)
hour I hour of day, GMT
min I minute of hour
sec I seconds of minute, to nearest millisecond
time O EPS internal time format
The function ep_time_to_ydn (or eptimetoydn for Fortran) converts the EPS time to year and year-day number. The year-day number is defined as the number of days since beginning of the year (e.g. Feb. 2 is year-day 33). Note: Sometimes people incorrectly refer to year-day number as Julian day number.
ep_time_to_ydn: C Interface
void ep_time_to_ydn(long* time, int* year, int* ydn)
time[2] I EPS internal time format
year O year (e.g. 1984)
ydn O year-day number (e.g. 1 for January 1st)
eptimetoydn: FORTRAN Interface
subroutine eptimetoydn(integer time(2), integer year, integer ydn)
time I EPS internal time format
year O year (e.g. 1984)
ydn O year-day number (e.g. 1 for January 1st)
The function ydn_to_ep_time (or ydntoeptime for Fortran) converts numerical values of year and year-day-number to EPS time. The milliseconds portion of EPS time will be zero.
ydn_to_ep_time: C Interface
void ydn_to_ep_time(int year, int ydn, long* time)
year I year (e.g. 1984)
ydn I year-day number (e.g. 1 for January 1st)
time[2] O EPS internal time format
ydntoeptime: FORTRAN Interface
subroutine ydntoeptime(integer year, integer ydn, integer time(2))
year I year (e.g. 1984)
ydn I year-day number (e.g. 1 for January 1st)
time O EPS internal time format
The function ep_time_to_str (or eptimetostr for Fortran) converts the EPS internal time to a string based on the format string. The format string is a short hand notation for how the date and time are to be written. An example is ``D-MM-YYYY hh:mm'' which would yield the string ``7-02-1989 21:16''. The position and number of the key letters determine the string format. Another example: ``DD MMM YYYY'' will yield the string ``07 FEB 1989''. A table of the meanings follows.
| Format | Description |
|---|---|
| D | day formatted as 1-31 |
| DD | day formatted as 01-31 |
| DDD | day of week written as 3 character name |
| DDDD | day of week, full format |
| M | month formatted as 1-12 |
| MM | month formatted as 01-12 |
| MMM | month formatted as 3 character name |
| MMMM | month formatted as full name |
| YY | year written as last two digits. (Not available for strtoeptime().) |
| YYYY | year written as all four digits |
| h | hour written as 1-24 |
| hh | hour written as 01-24 |
| m | minute written as 1-59 |
| mm | minute written as 01-59 |
| s | second written as 1-59 |
| ss | second written as 01-59 |
| f | fraction of second written as 0-9 |
| ff | fraction of second written as 00-99 |
| fff | fraction of second written as 000-999 |
| N | year-day number as 1-365 |
| NN | year-day number 01-365 |
| NNN | year-day number 001-365 |
Any character not in the above table is copied to the output string in the proper relative position. A backslash preceding any of the above formats is also copied to the output string.
ep_time_to_str: C Interface
void ep_time_to_str(long* time, char* format, char** string)
time[2] I EPS internal time
format I string to determine time formatting
string O formatted output of time
eptimetostr: Fortran Interface
subroutine eptimetostr(integer time(2), character*(*) format,
character*(*) string, integer len)
time I EPS internal time
format I string to determine time formatting
string O formatted output of time
len O length of string
The function str_to_ep_time (or strtoeptime for Fortran) converts a string to EPS time representation given a format. The input format string must follow the forms provided in the Time String Format Description table in the previous section. (Note: ``YY'' is not available for this function call.) Any character in the input time string which can not be described by the string listed in the table should appear exactly the same in the format string as it is in the time string. For example, your input time string is ``1990 Jan 10 12:00:00'', then the input string format must be ``yyyy MMM dd hh:mm:ss''. If invalid input month, day, hour, minute or second is detected, the output EPS time (both True Julian Day and millisecond) will contain 0.
str_to_ep_time: C Interface
void str_to_ep_time(char* format, char* string, long* time)
format I format of input time string
string I input time string
time[2] O EPS internal time
strtoeptime: Fortran Interface
subroutine strtoeptime(character*(*) format, character*(*) string,
integer time(2))
format I format of input time string
string I input time string
time O EPS internal time
The function ep_time_sub (or eptimesub for Fortran) subtracts one EPS time from another and stores the difference in delta. delta = time2 - time1.
ep_time_sub: C Interface
void ep_time_sub(long* time1, long* time2, long* delta)
time1[2] I first EPS time
time2[2] I second EPS time
delta[2] O time2 - time1
eptimesub: Fortran Interface
subroutine eptimesub(integer time1(2), integer time2(2),
integer delta(2))
time1 I first EPS time
time2 I second EPS time
delta O time2 - time1
The function ep_time_add (or eptimeadd for Fortran) adds EPS delta time to EPS time1 and stores the sum in EPS time2. time2 = delta + time1.
ep_time_add: C Interface
void ep_time_add(long* time1, long* delta, long* time2)
time1[2] I EPS internal time format
delta[2] I EPS time format increment
time2[2] O EPS internal time format result
eptimeadd: Fortran Interface
subroutine eptimeadd(integer time1(2), integer delta(2),
integer time2(2))
time1 I EPS internal time format
delta I EPS time format increment
time2 O EPS internal time format result
The integer function ep_time_intervals (or eptimeintervals for Fortran) returns the number of delta time intervals between time1 and time2, i.e. (time2 - time1)/deltat. (Note: it returns the nearest integral value, except halfway cases are rounded to the integral value larger in magnitude.)
ep_time_intervals: C Interface
int ep_time_intervals(long* time1, long* time2, long* deltat)
time1[2] I first EPS time
time2[2] I second EPS time
deltat[2] I EPS time interval
eptimeintervals: Fortran Interface
integer function eptimeintervals(integer time1(2), integer time2(2),
integer deltat(2))
time1 I first EPS time
time2 I second EPS time
deltat I EPS time interval
The function t_array_to_eptime (or tarraytoeptime for Fortran) Converts an array of integer or real number to an array of EPS time representation given length, data type, units and time base of the input time array. Two data types, EPREAL for real input time array and EPINT for integer input time array, are acceptable. The time base must be in EPS time representation.
t_array_to_eptime: C Interface
void t_array_to_eptime(void* t, int len, int dtype, char* units,
long* tbase, long* eptime)
t I input time array
len I length of input time array
dtype I type of input time array, (i.e.EPREAL or EPINT)
units I units of input time array, (i.e. hour, minuts, or day
tbase[2] I input time base in EPS time format
eptime[2][] O output EPS time representation
eptimeintervals: Fortran Interface
subroutine tarraytoeptime(dtype t(*), integer len, integer dtype,
character*(*) units, integer tbase(2),
integer eptime(2,*))
t I input time array
len I length of input time array
dtype I type of input time array, (i.e.EPREAL or EPINT)
units I units of input time array, (i.e. hour, minuts, or day)
tbase I input time base in EPS time format
eptime O output EPS time representation
The function eptime_to_t_array (or eptimetotarray for Fortran) converts an array of EPS time representation to an array of integer or real number given length of input EPS time array and data type, units and time base of the output time array. Two data types are EPREAL for real output time array and EPINT for integer output time array are acceptable. The time base must be in EPS time representation.
eptime_to_t_array: C Interface
void eptime_to_t_array(long* eptime, int len, int dtype,
char* units, long* tbase, void* t)
eptime[2][] I input EPIC system time array
len I length of input EPS time array eptime[2]
dtype I type of output time array, (i.e. EPREAL or EPINT)
units I units of output time array, (i.e. hour, minuts, or day)
tbase[2] I output time base in EPS time format
t O output time array
eptimetotarray: Fortran Interface
subroutine eptimetotarray(integer eptime(2,*), integer len,
integer dtype, character*(*) units,
integer tbase(2), dtype t(*))
eptime I input EPIC system time array
len I length of input EPS time array
dtype I type of output time array, (i.e. EPREAL or EPINT)
units I units of output time array, (i.e. hour, minuts, or day)
tbase I output time base in EPS time format
t O output time array
The integer function ep_month_to_int (or epmonthtoint for Fortran) returns input month string in integer. The valid input month string can be any of following format: "1", "01", "Jan" or "January".
ep_month_to_int: C Interface
int ep_month_to_int(char *monstr)
monstr I month stringe
epmonthtoint: Fortran Interface
integer function epmonthtoint(character monstr)
monstr I month stringe