NAME

mrcallrm - remove calls from a trace file

SYNOPSIS

$ mrcallrm [ options ] [ file...]

  --comment or -c          display original line as a comment
  --eula                   print End User License Agreement and exit
  --help or -?             print help text and exit
  --initrc                 use ~/.mrcallrm.rc and ./.mrcallrm.rc; --noinitrc to bypass
  --inplace=extension      edit files in place, back up using extension
  --listrc                 list rcfiles and exit
  --lines=list or -l list  eliminate calls on the specified lines
  --man                    print manual page and exit
  --rc=file                use options listed in file
  --thinktime=float        set threshold for 'SQL*Net message from client' removal
  --timunit=float          number of seconds represented by one tim unit
  --version                print version number and exit

DESCRIPTION

mrcallrm reads Oracle extended SQL trace data from the named filei(s) and sets the call duration to zero on each input line that qualifies for removal. A line qualifies for removal as defined by the following mutually exclusive rules:

  • The line represents a 'SQL*Net message from client' call with an elapsed duration greater than or equal to the threshold specified by the --thinktime option.

  • The line number matches one of the lines specified with the --lines option,

It also subtracts the proper duration from tim values on the call's line and subsequent lines, as well as on timestamp lines. mrcallrm converts datestamps from an Oracle format like "2008-04-01 08:09:10.123" to the ISO 8601 format "2008-04-01T08:09:10.123000+0000".

The tool can automatically uncompress files compressed properly with:

  Compression tool
  ----------------
  gzip
  bzip2
  zip

OPTIONS

--comment or -c

Display the original line with a comment prefix ("# ") on the line prior to each updated line in the output. Default is --nocomment.

--eula

Display the license information and exit.

--help

Display usage information and exit.

--inplace=extension or -iextension

Edit files specified on the command line in place, by renaming the input file and writing output to the file with the original name. The extension is used to modify the name of the old file to make a backup copy, as follows:

  • If an empty extension is supplied with -i'') and your system supports it, the original file is kept open without a name while the output is redirected to a new file with the original filename. When mrcallrm exits, cleanly or not, the original file is unlinked.

  • If the extension doesn't contain a *, then it is appended to the end of the current filename as a suffix. If the extension does contain one or more * characters, then each * is replaced with the current filename.

Note that it can be tricky to specify an empty extension value to --inplace or -i. If you specify --inplace with no extension followed by a file name, then mrcallm will interpret the file name as the extension and appear to hang, because now it is wating on STDIN for input. Thus, if you specify your option values before your file name, then you must explicitly specify the empty extension value with '' or "". To avoid this complication, just specify your option values after your file name. The following commands are equivalent:

  mrcallrm --inplace='' file.trc
  mrcallrm -i '' file.trc
  mrcallrm file.trc --inplace
  mrcallrm file.trc -i
--initrc

Use --noinitrc to prevent mrcallrm from opening the default rc files in your home directory or current working directory (see "ENVIRONMENT"). The default value is --initrc. Use --noinitrc if you don't want to run the default rc files.

--lines=range_list or -l range_list

Reset call durations to 0 on lines specified in range_list. The list must consist of non-negative integers (like "42"), closed ranges of non-negative integers (like "42..52"), or open ranges of non-negative integers (like "..42" or "42.."), separated by commas. For example, --lines=..5,8,10..12,1000.. is a valid line range specification. You may use either ".." or "-" interchangeably as a range operator. Ranges may be listed in any order. Specifying an invalid range_list (like --lines=a,1- 5) will cause mrcallrm to die.

The --lines and --thinktime options are mutually exclusive. Setting --lines causes any previous setting of --thinktime to be unset.

--listrc

List rc filenames and exit. The default value is --nolistrc.

--man

Print the mrcallrm manual page and exit.

--rc=file

Process command line options listed in file. See the mrskew manual page for details.

--thinktime=float or --z=float

Set the think-time threshold for 'SQL*Net message from client' call removal. For example, the default value --thinktime=1 means to regard any 'SQL*Net message from client' call whose duration is 1.0 seconds or more to be a think time call to be eliminated.

The --thinktime and --lines options are mutually exclusive. Setting --thinktime causes any previous setting of --lines to be unset.

--timunit=float

Regard and ela field values in the raw trace file as being expressed in time units of float seconds. The default value is --timunit=0.000_001. Consider using the following values:

  value           Oracle versions
  -------------   ------------------------------------------
  0.01            prior to 9
  0.000_001       9 and beyond
  0.000_001_024   9.0 through 11.2.0.1 for certain platforms

On some platforms, the Oracle kernel converts nanoseconds (obtained from the OS) to microseconds (displayed in the trace output) by using a 10-bit right-shift operator instead of dividing by 1,000. It takes a little bit of sophisticated testing to determine whether your platform does this. However, if it does, then using --timunit=0.000_001_024 will give you more accurate output.

--version

Display the program version number and exit.

.RC FILES

A .rc file allows you to change the default behavior of a Method R Tools program. For example:

  $ cat ~/.mrcallrm.rc
  --comment
  --inplace=.bak

See the mrskew manual page for details.

EXAMPLES

This command will remove all 'SQL*Net message from client' calls whose duration is 1.0 seconds or greater, and write the content to another file:

  mrcallrm ora_1492.trc > ora_1492-1.trc

This command will remove the call on line 7 of the input trace file and write the content to another file:

  mrcallrm --lines=7 ora_1492.trc > ora_1492-1.trc

This command will remove the calls on lines 1 through 42:

  mrcallrm --lines=..42 ora_1492.trc > ora_1492-2.trc

This command will remove the calls on lines 1 through 42, 1000, and 2000 through the end of the file:

  mrcallrm --lines=..42,1000,2000.. ora_1492.trc > ora_1492-3.trc

This command will remove all 'SQL*Net message from client' calls whose duration is .5 seconds or greater, and do the edit in place, creating a backup of the original trace file with a ".bak" extension:

  mrcallrm ora_1492.trc -z.5 -i.bak

DIAGNOSTICS

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

ENVIRONMENT

.mrcallrm.rc

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

  ~/.mrcallrm.rc
  ./.mrcallrm.rc

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

MRTOOLS_RCPATH

See the mrskew manual page for details.

AUTHORS

Cary Millsap, Jeff Holt

SUPPORT

mrcallrm version 4.0.0.59.

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

COPYRIGHT AND LICENSE

Copyright (c) 2011, 2015 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.