TIMEX

From ICE Enterprises
Jump to navigation Jump to search

perform various time transfer and conversion functions

<in>           Input time specification
<out1...outn>  Output time specifications

Keyword Only Parameters:
  [ROUND]  - See below for description
  [INFILE] - See below for description
  [INACQ]  - See below for description
  [INQUAD] - See below for description

This intrinsic performs a number of time transformations with support for
multiple output formats in a single call.

Input:
  The input time specifications are:
      NOW                   - the current system or CPU time (J1950)
      SSM                   - the seconds since midnight (this is similar to the
                              SECNDS() function in Fortran)
      DAY                   - the beginning of the current day
      <time>                - any valid time specifier:
                                o Time object
                                o "yyyy:mm:dd::hh:mm:ss"
                                o "<sec>"           (seconds since 01-JAN-1950)
                                o "(<sec>)"         (seconds since 01-JAN-1950)
                                o "(<wsec>,<fsec>)" (seconds since 01-JAN-1950)
                                o "<time string>"   (as specified by /INFMT=)
      ROUND=<seconds>       - round the output to the specified number of sec
      INFILE=<filename>     - the timecode field in a file
      INACQ=<filename>      - TBD (the ACQDATE/ACQTIME keywords in a file)
      INQUAD=<filename>     - the quadword epoch fields

Output:
  The output time specifications include (see nxm.sys.lib.Time for details):
      TERMINAL              - Displays time in the current terminal display
      <resname>             - Saves Time object in <resname>

      FILE=<filename>       - Stores time in the timecode field of a BLUE file
      ACQ=<filename>        - TBD (the ACQDATE/ACQTIME keywords in a file)
      QUAD=<filename>       - Stores time in the quadword epoch fields of a
                              Type 5000 BLUE file (for ECR reference frame GHA)

      YEAR=<resname>        - year (1950,...)
      MONTH=<resname>       - month of year (1..12)
      MONTHNAME=<resname>   - month of year (January,...)
      MONTHTRIGRAPH=<res>   - month of year (JAN,FEB,...)
      DAY=<resname>         - day of month (1..N)
      HOUR=<resname>        - hour of day (0..23)
      MINUTE=<resname>      - minute of hour (0..59)
      SECOND=<resname>      - second of minute (0..59)
      DAYOFWEEK=<resname>   - day of week (1=SUN,2=MON,...,7=SAT)
      DAYOFWEEKNAME=<res>   - day of week (Sunday,...)
      DAYOFWEEKTRIGRAPH=<r> - day of week (SUN,MON,...)
      JD=<resname>          - Julian day (or JUL=)
                              (NOTE: Julian Date Epoch is 12:00 1 Jan 4713BC)
      MJD=<resname>         - Midas Julian day (since J1950)
                              (NOTE: NOT the Modified Julian Day defined by SAO.
                               Modified Julian Day = Midas Julian Day + 33282.0)
      MJS=<resname>         - Midas Julian second (since J1950)
      SEC=<resname>         - seconds since 00:00 1 Jan 1950 (same as MJS)
      YIS=<resname>         - year in seconds
      DOY=<resname>         - day of year (0..364/365)
      SOY=<resname>         - seconds of year
      SOD=<resname>         - seconds of day
      FOD=<resname>         - fraction of day (0.0 to 1.0)
      GHA=<resname>         - Greenwich hour angle (in radians)
      WSEC=<resname>        - Whole Seconds since J1950
      FSEC=<resname>        - Fractional Seconds since J1950
      LEAPYEAR=<resname>    - Indicates if it is a leap year (true/false)

Rounding:
  The input time can be rounded to a desired precision before output processing
  via the ROUND=<precision> parameter. This parameter causes the input time to
  be rounded to the nearest <precision> seconds. For example: ROUND=1 rounds to
  nearest second, ROUND=1:00:00 to the nearest hour, and ROUND=1e-3 rounds to
  the nearest millisecond.  Restrictions: precision must be an integer number
  of seconds or divide evenly into 1 second.

Formatting:
  Since NeXtMidas 2.5.0 the TIMEX command supports a wide variety of time/date
  formats made available via the MFormat class. Acceptable in/out formats can
  be either a standard Midas format:
   Type       Format                       Example (1993-FEB-25 14:42:57.123456)
   -----------------------------------------------------------------------------
   "STD"      yyyy:MM:dd::HH:mm:ss[.SSS]   1993:02:25::14:42:57.123456
              T:yyyy:MM:dd::HH:mm:ss[.SSS] T:1993:03:25::14:42:57.123
   "ACQ"      [yy]yy.DDD:HH:mm:ss[.SSS]    93.056:14:42:57.123456
   "EPOCH"    yyyy:sec_in_year             1993:4804977.123456
   "FILENAME" yyyyMMdd_HHmmss[SSS]         19930225_144257123456
   "NORAD"    yyDDD.frac_of_day            93056.61316115
   "TCR"      D:HH:mm:ss.SSS               56:14:42:57.123456
   "VAX"      dd-MMM-yyyy:HH:mm:ss.SSS     25-FEB-1993:14:42:57.123456
   "HMS"      HH:mm:ss.SSS                 14:42:57.123456
   "YMD"      yyyy:MM:dd                   1993:02:25
   "ISO8601"  yyyy-MM-ddTHH:mm:ss.SSSZ     1993-02-25T14:42:57.123456Z
   "FULL_STD" yyyy:MM:dd::HH:mm:ss.SSS     1993:02:25::14:42:57.123456

  Or they can be any of the patterns accepted by the java.text.SimpleDateFormat.
  This gives maximum flexibility when converting between various time/date
  formats. Here is mini-guide to above format/SimpleDateFormat pattern letters:
    D=Day in year (1-366),  d=Day in month (1-31),   M=Month in year (1-12),
    H=Hour in day (0-23),   h=Hour in am/pm (1-12),  m=Minute in hour (0-59),
    s=whole seconds in minute (0-59), S=fractional seconds (up to femtosecond),
    (NOTE: above doc difference vs S for milliseconds in SimpleDateFormat).

  Note: When the time is one day or less, time formats STD, ACQ, EPOCH, and VAX
  do NOT output the year, month, and day, but only the hours, minutes, and
  seconds. ISO8601 time format in NeXtMidas 3.3.0 to 3.5.3 also had this
  behavior, but was change to always output full date and time in 3.5.4.

  For details, please see nxm.sys.lib.MFormat, nxm.sys.lib.Time.formatList and
  java.text.SimpleDateFormat.

Examples:
  1. Display the current time at the terminal.
       nM> TIMEX
       Time = 2004:05:09::16:04:53.416
     or
       nM> TIMEX NOW terminal
       Time = 2004:05:09::16:04:53.416

  2. Display the current time rounded to the nearest second.
       nM> TIMEX round=1 terminal
       Time = 2004:05:09::16:04:53.000

  3. Writes the current system time to the epoch timecode fields of MYFILE
     and also to the result LOCALTIME.
       nM> TIMEX NOW file=myfile localtime

  4. Copies the epoch timecode in MYFILE to the epoch timecode in YOURFILE
     and the YOUROTHERFILEs acquisition fields.
       nM> TIMEX infile=myfile file=yourfile acq=yourotherfile

  5. Breaks out the acquisition date/time keywords for MYFILE into its
     Julian day components for system modeling functions.
       nM> TIMEX acq=myfile jd=julianday soy=secofyear gha=greenwichHourAngle

  6. Uses the timecode field in MYFILE as the quadword epoch time for
     the ECI reference frame.  This affects the epoch_year, epoch_seconds,
     and epoch_hour_angle quadwords of the file, quadwords(10-12).
       nM> TIMEX file=myfile quad=myfile

     (There are no restrictions on the number of output parameters.)

  7. Converts a time string to a DOUBLE.
       nM> timex "2004:11:15::13:55:31.503" d:mytime
       nM> res mytime
         D: MYTIME          = 1.731678931503E9

     Could also use (note this only works when the time is not quoted):
       nM> res d:mytime 2004:11:15::13:55:31.503
       nM> res mytime
         D: MYTIME          = 1.731678931503E9


  8. Converts a time string to a long LONG.
       nM> timex "2004:11:15::13:55:31.503" L:mytime
       nM> res mytime
         L: MYTIME          = 1731678932

     Could also use (note this only works when the time is not quoted):
       nM> res d:mytime 2004:11:15::13:55:31.503
       nM> res mytime
         L: MYTIME          = 1731678931

     Note that TIMEX will round the time to the nearest second while RESULT
     will always do a type cast (i.e. round down).

  9. Use Java input and output formats (since NeXtMidas 2.5.0).
       nM> timex now /fmt="yyyy-MM-dd hh:mm:ss.SSS"
       Time = 2007-08-06 10:30:14.745

       nM> timex "2007-08-06 10:30:14.745" /infmt="yyyy-MM-dd hh:mm:ss.SSS"
       Time = 2007:08:06::10:30:14.745

       nM> timex "1994-01-01T00:00:00Z" /infmt="yyyy-MM-dd'T'hh:mm:ss'Z'"
       Time = 1994:01:01::00:00:00

       nM> timex "1994-01-01T00:00:00Z" /infmt="ISO8601"  !since NeXtMidas 3.3.0
       Time = 1994:01:01::00:00:00

  10. Get current time in Hour-Min-Sec time format into results TIMEHMS.
       nM> timex now timeHMS /fmt="HMS"
       nM> res timeHMS
       12S: TIMEHMS         = 17:44:27.293

  11. Comparison of time of day (since midnight) in STD versus FULL_STD
       nM> TIMEX SSM /fmt="STD"
       Time = 19:56:12.337
       nM> TIMEX SSM /fmt="FULL_STD"                     !since NeXtMidas 3.5.2
       Time = 1950:01:01::19:56:12.337

  12. Up to femtosecond precision is available           !since NeXtMidas 3.5.2
       nM> timex "2014:04:03  02:34:56.123456789012345" &
             /infmt="yyyy:MM:dd  hh:mm:ss.SSSSSSSSSSSSSSS" &
             /fmt="d MMM yyyy HH:mm:ss.SSSSSSSSSSSSSSSSSS"
       Time = 3 Apr 2014 02:34:56.123456789012345

  13. simpleDateFormat milliseconds used when 3 or less Ss are specified
        nM>  timex "2014:04:03::02:34:56.1234" /fmt="d MMM yyyy HH:mm:ss.S"
        Time = 3 Apr 2014 02:34:56.123

  14. T:<std_format> as STD Time
        nM> timex T:2015:03:14::09:26:53.589793238462 /PREC=12
        Time = 2015:03:14::09:26:53.589793238462

Switches:
  /FMT=<str>    Output format to use. If present, the output is a formatted
                time/data string, otherwise it will be a Time object. See the
                above section titled "Formatting" for details.
  /INFMT=<str>  Input format to use. If present, the input value is parsed from
                a time/data string, otherwise it will assume one of the time
                specifiers listed above. See the "Formatting" section for
                details.
  /PREC=<n>     Number of places after the decimal point to display when given
                one of the "standard" formats on the /FMT= switch.

See Also: nxm.sys.lib.Time, nxm.sys.lib.MFormat