PDS Ring-Moon Systems Node Software Library
Part 2: THE JULIAN LIBRARY
Version 1.3.3, February 2005
Mark R. Showalter
Index
1. INTRODUCTION
2. SUMMARY OF ROUTINES
3. EXAMPLES
4. USAGE
5. BUILDING INSTRUCTIONS
6. CHANGE HISTORY
Click here for a text-only version of this
file.
1. INTRODUCTION
The Julian Library comprises a set of C functions for manipulating dates
and times. It includes routines for conversions between Universal Time
(UTC), Atomic Time (TAI), and Ephemeris Time (ET). It also performs
conversions between calendar dates and Julian dates, and interprets or
formats dates and times in a variety of styles. Routines are written in
C and can be accessed by programs written in either C or FORTRAN.
2. SUMMARY OF ROUTINES
Each routine in the Julian Toolkit is documented extensively in the
source code. The source files should be consulted for a detailed
description of how to use each routine.
For C programmers, all the Julian Library routines have names beginning
with "Jul_". Some more basic components of the Ring-Moon Systems Node
Library have names beginning with "RL_". For FORTRAN
programmers, the routine names are the same except that they have an
"F" prepended.
2.1 Definitions
A variety of variable names and terms are used throughout the toolkit.
|
DUTC
|
the integer number of days elapsed since January 1, 2000.
Negative numbers refer to earlier dates.
|
|
secs
|
the floating-point (double precision) number of seconds since
the beginning of a particular UTC day. For most days, 0 <= secs
< 86400; however, some days have leap seconds, in which case
0 <= secs < 86401.
|
|
year
|
An integer calendar year (CE). Years are numbered sequentially
so, since there was no year 0, 1 BCE is indicated by year=0,
2 BCE by year=-1, N BCE by year=-(N-1).
|
|
month
|
A numeric month value, 1=January, 2=February, ... 12=December.
Within the toolkit, there is no restriction on the numeric range
of month values; hence month=0 refers to December of the
previous year and month=13 refers to January of the following
year.
|
|
day
|
A numeric day value within a given month or year, where 1 is the
first day. There is no restriction on the numeric range of day
values; hence January 32 is equivalent to February 1.
|
|
J2000
|
noon, January 1, 2000. This is the epoch reference time for TAI
and ET values, chosen for consistency with the SPICE Toolkit.
|
|
TAI
|
the number of seconds elapsed since J2000 Atomic Time (TAI). In
the TAI time system, every day has exactly 86400 seconds; hence,
times TAI and UTC differ by a whole number of seconds, where the
number changes each time a leap second occurs.
|
|
ET
|
the number of seconds elapsed since J2000 Ephemeris Time (ET).
This is the time frame on which planetary ephemerides are
calculated (including the SPICE Toolkit). It differs from TAI
times by a constant plus small periodic terms related to
relativistic variations in the ticks of an Earth-based clock.
|
|
JDN
|
a Julian day number, equal to the whole number of elapsed days
since since January 1, 4713 BCE.
|
|
JD
|
a Julian date. The integer part is the number Julian days
elapsed since noon January 1, 4713 BCE; the fractional part
gives the fraction of a day from one noon to the next. Julian
dates can be based on times UTC, TAI or ET.
|
|
MJD
|
a UTC Modified Julian Date, defined as JD - 2400000.5.
|
2.2 Calendar date conversions
The following routines are all defined in the file
dates.c.
They are exact for all positive Julian Dates, i.e. for all dates since
January 1, 4713 BCE.
2.3 Time conversion routines
The following routines are all defined in file
seconds.c.
|
(F)Jul_SecofDHMS
|
converts days, hours, minutes and seconds to total
seconds.
|
|
(F)Jul_DSofSec
|
converts a number of seconds to days and seconds-into-
day.
|
|
(F)Jul_DHMSofSec
|
converts a number of seconds to days, hours, minutes and
seconds (excluding possible leap seconds).
|
|
(F)Jul_HMSofSec
|
converts a number of seconds to hours, minutes and
seconds (including possible leap seconds).
|
2.4 UTC/TAI conversion routines
The following files are all defined in file
utc_tai.c.
The following routines are all defined in file
juldates.c.
|
(F)Jul_TAIofJD
|
converts floating-point (double precision) JD to TAI.
|
|
(F)Jul_JDofTAI
|
converts TAI to floating-point (double precision) JD.
|
|
(F)Jul_TAIofMJD
|
converts floating-point (double precision) MJD to TAI.
|
|
(F)Jul_MJDofTAI
|
converts TAI to floating-point (double precision) MJD.
|
These files depend on an additional set of routines to keep track of
when leap seconds occur, found in file
leapsecs.c.
2.5 TAI/ET conversion routines
The following pair of routines is found in the file
tai_et.c.
These are intended to match (almost) exactly the algorithms used by the
SPICE toolkit.
2.6 Julian Day number conversion routines
The following routines are all found in file
juldates.c.
The Julian Dates converted by these routines can be based on the UTC,
TAI or ET time systems.
2.7 Date/time formatting and interpretation routines
Routines are available to format dates and times according to various
styles, and also to interpret character strings containing various
representations for dates and times. The file
format.c contains
routines for formatting dates and times:
The file
parse.c
contains routines for parsing dates and times.
|
(F)Jul_ParseDT
|
interprets a character string as a date and time in
arbitrary format.
|
|
(F)Jul_ParseDate
|
interprets a character string as a date.
|
|
(F)Jul_ParseTime
|
interprets a character string as a time.
|
The file
parsing.txt
summarizes the rules for how these strings
are interpreted; see also the source code.
2.8 Other Source Files
The following files contain additional source code in the form of
routines that are generally not to be called directly by the user.
Only one additional source file is specific to the Julian Library:
|
fjulian.for
|
FORTRAN interfaces to Julian Library routines that
pass character strings as arguments.
|
In addition, these files contain generic RingLib routines.
|
rlmemory.c
|
RingLib routines to manage memory.
|
|
rlerrors.c
|
RingLib routines to handle errors.
|
|
ringlib.h
|
C header file for RingLib.
|
|
fortran.c
|
Ringlib routines to convert between FORTRAN integers
and C pointers.
|
|
fstrings.for
|
Ringlib routines to convert string representations
between FORTRAN and C.
|
|
fortran.h
|
C header file for fortran.c and fstrings.for.
|
3. EXAMPLES
Test program
"tconvert.for"
is a FORTRAN program provided to illustrate
the use of Julian Library routines. It performs a variety of useful
time conversions. You enter a UTC date and time in essentially
arbitrary format, and it prints out the time in a variety of
additional formats and time systems. The program source should serve
as a reasonable example of how various Julian Library routines are
used.
4. USAGE
To use Julian Library routines from within a C program, one should
include the file
"julian.h".
This file provides a declaration prototype
for each function. Because some popular C compilers, such as that
provided on Suns, are not ANSI-standard, the include file is designed to
eliminate the prototypes on these systems.
Within the Julian Toolkit and the remainder of the Ring-Moon Systems Node Software
Library, special data types are defined to "hide" some variations among
implementations of C from one platform to the next. These special data
types are as follows:
|
RL_INT4 | | a four-byte signed integer.
|
|
RL_BOOL | | an integer taking on only values TRUE=1 and FALSE=0.
|
|
RL_FLT4 | | a single-precision (four-byte) floating point number.
|
|
RL_FLT8 | | a double-precision (eight-byte) floating point number.
|
|
RL_CHAR | | a one-byte character.
|
|
RL_VOID | | used in the context of "void *" as a pointer to a
structure of arbitrary type.
|
|
|
These types are defined in the include file
"ringlib.h", which is included
automatically by "julian.h".
For FORTRAN programmers, the include file
"fjulian.inc" is provided; it
declares the type of every function within the toolkit and also defines
some useful parameters.
5. BUILDING INSTRUCTIONS
5.1 UNIX
This library has been tested on UNIX systems by DEC, Sun, Silicon
Graphics and LINUX. To build the library and test binaries on a Sun,
type
chmod +x makesun.com
./makesun.com
To build the library and binaries on a system by DEC or Silicon
Graphics, type
chmod +x makedec.com
./makedec.com
To build the library and binaries on a Macintosh under OS X, type
chmod +x makemac.com
./makemac.com
To build the library and binaries under LINUX using the g77 compiler,
type
chmod +x makeg77.com
./makeg77.com
In each case, the script file "make*.com" will compile each file and
build an archive file called "make*.com". (Note that any pre-existent
file called "julian.a" should be removed first). The sample program
binary is called "tconvert".
The commands "cc" and "f77" are used by these scripts (except makeg77,
where "g77" is called in place of "f77"). Be sure that your command
search path includes these before executing the script.
To use the library, include "julian.a" among the files that
appear on a cc or f77 command line. Note that for C
programs, you must also include the "-lm" option to load in the
C math libraries.
5.2 VMS
To build the library and executables on a Vax or Alpha using the VMS
operating system, type
@MAKEVMS.COM
This will compile each file and build an object library called
JULIAN.OLB. The sample program binary is called
TCONVERT.EXE.
To use the library, include JULIAN/LIBRARY among the files in a
LINK command. For programs written in FORTRAN, you must also
include SYS$LIBRARY:VAXCRTL/LIBRARY because the C libraries
are not linked in by default.
6. CHANGE HISTORY
Version 1.1 (11/96) contains no significant changes to the initial
source code. However, it includes the file
"parsing.txt" which
describes in detail the string parsing rules used by "parse.c".
It also updates some of the comments in the source code.
Version 1.2 (7/97) incorporates the leap second of June 30, 1997 into
"leapsecs.c" and "leapsecs.lis". It also fixes a
minor bug in Jul_FormatPDS().
Version 1.3 (6/98) contains extensive, mostly cosmetic changes, so
that naming conventions better conform to those of the rest of the
RingLib. It also incorporates HTML tags into the source code so that
code may be easily inspected online.
Version 1.3.1 (12/98) contains the new leap second of December 31, 1998.
Version 1.3.2 (2/04) includes support for Macintosh OS X. It also
provides a detached PDS label file "JULIAN.LBL" and a software catalog
file "SOFTWARE.CAT", making the library suitable for archiving on any
PDS volume.
Version 1.3.3 (2/05) includes support for LINUX and the g77 compiler.
Toolkits |
Ring-Moon Systems Node Home