About Time Formats




The Report Generation facility in PERCY allows you to create time formats specially tailored to your specific application. To create a custom format you need to make a ``picture'' of it. A format picture is simply a string of letters that lets PERCY know where various components of a time representation should be placed during creation of the time string. Here's an example of such a picture: 

   MON DD,YYYY  HR:MN:SC.#### (TDB) ::TDB
Here is a sample of the times that would be created by using this format. 

   JAN 12,1992  12:28:18.2772 (TDB)
   FEB 13,1994  23:18:25.2882 (TDB)
   AUG 21,1995  00:02:00.1881 (TDB)
As you can see from the samples above, the format picture specifies that every time string created should begin with a three-letter abbreviation for the month, followed by a space and the day of the month. The day of month is followed immediately by a comma and the year. The year component is followed by two spaces. Following these two spaces are: hours represented as a two digit integer, a colon, minutes as a two digit integer, another colon, and seconds truncated to 4 decimal places and having a two digit integer part. This is followed by a space and the string (TDB). The special marker `::TDB' in the time picture is an ``invisible'' marker. It is used to specify the time system that should be used in creating the time string --- in this case Barycentric Dynamical Time.



Rules used by the time formatter



The time formatter does not recognize all of the parts of the time format picture in the example above. The list of recognized parts and unrecognized parts are listed in the table below. 

   Recognized       Unrecognized
   ----------       ------------
   'MON'            ' '
   'DD'             ','
   'YYYY'           '  '
   'HR'             ':'
   'MN'             '(TDB)'
   'SC'
   '.####'
   '::TDB'
When creating a time string, the recognized parts of the picture are replaced by a component of time or, as in the case of `::TDB' are used as instructions about the overall properties of the time string. Unrecognized portions of the time picture are simply copied into the output time string in the same location as they appeared in the format picture.

The full list of recognized markers, their classification and meaning are given below. 

   MARKER      CLASS      MEANING
   ------      ---------- ----------------------------------------------
   .##...      modifier   report preceding numeric component in decimal
                          form
   ::RND       meta       round output to places specified by least
                          significant component
   ::TDB       meta       all components should be TDB
   ::TDT       meta       all components should be TDT
   ::TRNC      meta       truncate all output components (default)
   ::UTC       meta       all components should be UTC (default)
   DD          numeric    day of month component
   DOY         numeric    day of year component of time
   HR          numeric    hour component of time
   JD          numeric    julian date component of time
   MM          numeric    numeric representation of month component
   MN          numeric    minute component of time
   MON         string     character representation of month component
   SC          numeric    second component of time
   SP1950      numeric    seconds past 1950 component of time
   SP2000      numeric    seconds past 2000 component of time
   WKD         string     character representation of day of week component
   YYYY        numeric    year component of time
Any combination of these components may be used in your format picture. As an example you could create the following format picture: 

   MON DD falls on WKD in YYYY and has Julian date JD.# ::RND
Some sample output time strings corresponding to this picture are: 

   JUL 28 falls on TUE in 1992 and has Julian date 2451617.5
   JUL 29 falls on WED in 1992 and has Julian date 2451618.5
   JUL 30 falls on THU in 1992 and has Julian date 2451619.5


Meta Markers



Meta markers (denoted by the class value ``meta'' in the table above) are used to indicate `global' properties of your time string. You may specify time scale and how rounding should be performed on the components of time in your output string. Meta markers may be placed anywhere in your format picture. They do not contribute to placement of characters in output time strings. Also there are no restrictions on how many meta markers you may place in the format picture. However, if you supply conflicting `meta' markers (for example ::TDT and ::TDB) in your picture the first marker listed (in left to right order) overrules the conflicting marker that appears later in the picture.



Modifier Markers



The numeric markers listed in the table above stand for integers unless they are modified through use of a modifier marker. The strings 

   .#
   .##
   .###
   .####
and so on, are used to this end. When a numeric marker is followed immediately by one of these modifiers, the corresponding time component will be written with the number of decimal places indicated by number of successive occurrences of the character `\#'. Any numeric token may be modified. For example if you need to represent time as year and day of year to six decimal places, you could use the following format picture. 

   YYYY DOY.######
To produce a time string with year, month, day of month, hour, and minutes to 1 decimal place you could use the following picture. 

   YYYY-MM-DD HR:MN.#
There are no restrictions on the number of modified numeric markers you may use in a format picture. For example, although the picture below produces somewhat confusing output, it is an acceptable format picture. 

   YYYY DOY.### HR.#:MN.#:SC.###
This will produce strings such as those shown below: 

   1992 100.500 12.0:00.0:00.000
   1992 100.010 00.0:14.4:24.000
For obvious reasons, we do not recommend producing this kind of output.

Modifier markers do not modify string markers. They are recognized only if they immediately follow one of the numeric markers. If they appear separated from a numeric marker they are simply copied as written into the output time string. 

   YYYY MON.### DD HR:MN:SC .###
will produce time strings such as those listed below. 

   1992 JAN.### 04 12:15:18 .###
   1993 FEB.### 05 12:18:38 .###


Rounding vs. Truncation



The meta markers ::TRNC and ::RND allow you to control how the output time picture is rounded. If you specify ::TRNC all components of time are simply truncated to the precision specified by the marker and any modifier. If you specify ::RND the output time is rounded to the least significant component of the format picture. The default action is truncation.

Whether an output time string should be rounded or truncated depends upon what you plan to do with the string. For example suppose you simply want to get the calendar date associated with a time and not the time of day. Then you probably do not want to round your output. Rounding 1992 Dec 31, 13:12:00 to the the nearest day produces 1993 Jan 1. Thus in this case rounding is probably not appropriate.

However, if you are producing output for plotting using Julian Date, seconds past an 1950 or or seconds past 2000, you will probably want your output rounded so as to produce a smoother plot.



Saving Format Pictures



If there is format pictures that you use frequently, we suggest that you create symbols for them and that you place these symbol definitions in your PERCY start-up file. That way you won't need to remember the details of creating format pictures but can simply use your symbol. On those occasions when you need to create a new format you can refer to this section of the command reference either in its printed form or through PERCY's HELP command.



Related Topics



  1. The Percy Help System