NAME

mrtim - convert tim values to timestamps and timestamps to tim values

SYNOPSIS

  $ mrtim [options] [(tim | timestamp | "now") ...]
  
  Options:
  --eula              print End User License Agreement and exit
  --help              print help text and exit
  --man               print manual page and exit
  --precision=n       round to n digits post-decimal precision
  --rc=file           use named rc file; --norc prevents rc file usage
  --touch or -t       print timestamp in "touch -t" format
  --tz=z              interpret argument using time zone z
  --unit=x or -ux     set unit to value of expression x
  --version           print version number and exit

DESCRIPTION

mrtim is useful for converting human-readable timestamps into Oracle tim values used in Oracle extended SQL trace files, and vice-versa. Using mrtim now is the equivalent of specifying mrtim "`date`" (using the quoted output of the Unix date command); it will return the tim value corresponding to the current time. The default unit of measure for interpreting and expressing tim values is 1 microsecond. You can change this unit with the -u or --unit option.

mrtim converts each numeric argument to an ISO 8601 timestamp (e.g., 2008-04-01T08:00:00.000000+0000) in your local time zone (see "TZ"), and it converts each non-numeric argument to a tim value. If no arguments are specified on the command line, then mrtim reads from the standard input device.

mrtim is able to interpret any string timestamp that the Perl str2time function can interpret (see the Perl Date::Parse module). Unlike str2time, it can also understand Oracle trace file timestamps in the "2008-04-01 08:00:00.000" format.

OPTIONS

--eula

Display the license information and exit.

--help

Display usage information and exit.

--man

Print the manual page and exit.

--precision=n

Round durations to n digits to the right of the decimal point. The default value is --precision=3.

--rc=file

Process command line options listed in file. Use --norc to prevent mrtim from opening the default rc files in your home directory or current working directory (see "ENVIRONMENT").

--touch or -t

When the input is a tim value, print the output timestamp in CCYYMMDDhhmm.SS format required by touch -t.

--tz=zone

When the input is a tim value, print the output timestamp in the time zone specified by zone.

When the input is a timestamp, interpret the timestamp as being in time zone zone. However, if the input timestamp contains a time zone specification, then that time zone specification is used, and --tz is ignored.

When the input is now, --tz is ignored.

Acceptable time zone specifications include strings like cst, CST, and -0600. If you specify a nonsensical time zone string like abc, then mrtim will use UTC. Default value --tz='' means to use the shell's default time zone.

--unit=x or -ux

Use x seconds as the unit for interpreting and expressing tim values. mrtim understands common subsecond unit names, so -u1us or --unit=1us means to use units of 1 microsecond (.000_001 seconds). Likewise, -u1024ns and -u1.024us mean the same thing. (See mrtimfix for details on why you might want to use a unit of 1024ns instead of 1000ns.) mrtim understands the following unit names:

  ns   .000_000_001 seconds (1 nanosecond)
  us   .000_001 seconds (1 microsecond)
  ms   .001 seconds (1 millisecond)
  cs   .01 seconds (1 centisecond)
  s    1 second

Default is --unit=1us.

--version

Display the program version number and exit.

RC FILES

With .rc files, you can conveniently change the default behavior of any mrtim option. For example:

  $ cat ~/.mrtim.rc
  --tz=CST6CDT

You can also construct .rc files that allow you to customize mrtim queries without having to type a complex command line each time:

  $ cat mrtim.rc
  # Show times in Oracle 1024-nanosecond microseconds.
  --unit=1024ns

A line beginning with the '#' character (in the first column of the line) is a comment. A comment must be on a line by itself; do not put a comment on a line after an option. There is no need to use a line continuation character to specify a multi-line option.

Such a .rc file would be called into use like this:

  $ mrtim --rc=mrtim.rc

This command would first execute the options listed in ~/.mrtim.rc (picking up the --reverse argument shown above), next execute the options listed in ./.mrtim.rc (if the file exists), and then finally execute the options listed on the command line. Upon encountering the --rc=filename option, mrtim will execute the options listed within the named file.

EXAMPLES

The following command will show the tim value, expressed in microseconds, associated with the given date (note that in this case the quotation marks are required because the argument--an Oracle-format datetime stamp--contains a space):

  mrtim "2008-04-01 08:00:00.000001"

These (functionally identical) commands will show the same tim value, expressed in 1024-nanosecond units:

  mrtim "2008-04-01 08:00:00.000001" -u1024ns
  mrtim "2008-04-01 08:00:00.000001" -u1.024us
  mrtim "2008-04-01 08:00:00.000001" -u.000001024

This command will show the date corresponding to the given tim value:

  mrtim 1207054800000001

This command will show the date corresponding to the given tim value, regarding the tim in seconds instead of microseconds:

  mrtim -u1s 1207054800

To print a timestamp representing the present time as an ISO 8601 string, use:

  mrtim now | mrtim

To print a timestamp representing the present time as an ISO 8601 string in UTC, use:

  mrtim now | mrtim --tz=utc

mrtim is valuable for finding what time a line of trace data represents. Consider a trace file with the following line:

  CLOSE #4:c=1,e=52,dep=0,type=3,tim=1238753862358018

To find what time the close call ended and began, you could use:

  mrtim 1238753862358018                   # call end time
  echo  1238753862358018-52 | bc | mrtim   # call begin time

LIMITATIONS

mrtim can convert only dates between 1970-01-01T00:00:00.000000Z and 2038-01-17T00:00:00.999999Z, and only tim values in the range 0 <= tim < (2147299200.999999 - offset) seconds, where offset is the time zone offset from Coordinated Universal Time (UTC) for your system, in seconds. See "TZ" for more details.

mrtim cannot convert tim values and timestamps for Oracle Database ports that use tim values that are not based on the Unix epoch (for example, Oracle Database trace files generated on Sun Solaris and Microsoft Windows operating systems).

DIAGNOSTICS

Exit status is 0 on successful completion, and >0 if an error or warning occurs.

ENVIRONMENT

.mrtim.rc

By default, mrtim will execute the options listed in the following files, in the following order, before the options you actually list on your command line:

  ~/.mrtim.rc
  ./.mrtim.rc

If you do not wish to execute the options in these files, then specify --norc on the command line.

MRTOOLS_RCPATH

The MRTOOLS_RCPATH environment variable contains a list of directories that each --rc=file option will search for file. Value syntax is identical to the PATH environment value syntax (e.g., ".:a:a/b" in Unix, ".;c:a;c:a\b" in DOS). If file begins with '/', '.', or '~', then --rc looks for the file in the location you have specified. Otherwise, --rc will search each directory named in the MRTOOLS_RCPATH list for file, using only the first readable file that it finds.

TZ

mrtim always regards tim values as time that has elapsed since the Unix epoch, 1970-01-01T00:00:00Z. The UTC time zone (denoted by 'Z') is thus built into the notion of what a tim value is.

When you specify a timestamp value to mrtim, you have the choice of naming a time zone; for example, "2008-04-01T08:00:00-06" specifies the Americas Central Standard Time timezone. If you specify a timestamp value to mrtim without naming a time zone (such as Oracle does when it emits a string like "2008-04-01 08:00:00" into a trace file), mrtim interprets the timestamp value in the context of your local time zone, as defined by the setting of your TZ environment variable. If TZ is unset, mrtim interprets a timestamp as a Coordinated Universal Time (UTC) value.

Likewise, when mrtim prints an ISO 8601 timestamp, the time zone of the timestamp it prints is determined by your TZ environment variable setting.

Here are a few examples of timezone settings:

  export TZ=CST6CDT
  export TZ=Europe/Copenhagen
  export TZ=UTC

AUTHORS

Cary Millsap

SUPPORT

mrtim version 3.1.0.4.

Contact <> at Method R Corporation for support, or visit method-r.com for more information.

COPYRIGHT AND LICENSE

Copyright (c) 2011, 2014 by Method R Corporation. All rights reserved.

This is commercially licensed software. You may not redistribute copies of it. Please confirm with your software license administrator that you are licensed to use this Method R software product. Write <> for information.

There is NO WARRANTY, to the extent permitted by law.