ConvertBot: perform various time transfer and conversion functions

2020-04-27T22:05:14Z

perform various time transfer and conversion functions

New page

perform various time transfer and conversion functions
<pre>
<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

</pre>

[[Category:NXM_Explain]]

TIMEX - Revision history

ConvertBot: perform various time transfer and conversion functions