PDS Rings 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. Or click here to browse all the files directly.


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 Rings 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.

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.

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. 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. 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: In addition, these files contain generic RingLib routines.

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 Rings 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: 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 To build the library and binaries on a system by DEC or Silicon Graphics, type To build the library and binaries on a Macintosh under OS X, type To build the library and binaries under LINUX using the g77 compiler, type 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 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 | Rings Node Home