itmcmd history

Purpose:  manages the rolloff of history data into delimited text files.

Syntax notes:  [ optional ]  mutually|exclusive

Rolloff:
  itmcmd history [ -h CANDLEHOME ] -C [ -L nnn[Kb|Mb] ] [ -t masks*,etc ] [ -D delim ] [ -H|+H ] [ -N n ] 
  [ -i instance|-p tems_name ] prod_code

Rolloff Scheduling:
  itmcmd history -A?
  itmcmd history [ -h CANDLEHOME ] -A perday|0 [ -W days ] [ -L nnn[Kb|Mb] ] [ -t masks*,etc ] [ -D delim ] 
  [ -H|+H ] [ -N n ] [ -i instance|-p tems_name ] prod_code

Options can be combined and spaced per standard UNIX convention.
These three have identical meanings:

  -t "table list"  -ttable:list  -ttable,list

General options:

  -h  CANDLEHOME directory.  If -h appears as the only option without a value, 
      it is a help call.

  -i instance  process history data collected by a specific instance of prod_code.  

  -p tems_name  process history data collected by TEMS tems_name.  Optional.  Note
               that a prod_code of "ms" must be used with this option.  The default
               action is to process data collected by prod_code agent.

  prod_code  2-character product code (e.g. mq) of the product you want to 
             rolloff.

  -t  List of tables or ksh patterns thereof, delimited by comma, colon, slash 
      or blank (quote if blank-delimited or pattern may match a file).  Table 
      names are always uppercase, but -t ignores case.

Rolloff notes:

  Rolloff converts history files for selected tables of a product to delimited 
  files for use in a spreadsheet or similar product.   Rolloff can be run at any 
  time; the agent does not have to be active.

  There is no check to ensure that entries in the table list are meaningful or 
  actually used.  Each table will be rolled off only once per itmcmd history -C 
  execution even if multiple table masks match it.

Rolloff parms:

  -C  Identifies this as a history rolloff call.  Required.

  -L  Only process history files whose size is over a specified number of Kb or Mb.
      Suffix can be any of none, K, Kb, M, Mb, and none implies Kb.

  -H  Exclude column headers.  Default is "attribute".

  +H  Include group (long table) names in column headers.  Format is
      "Group_desc.Attribute."  Default is attribute only.

  -N  Keep generations 0-n of output (Default is 9.).

  -D  Output delimiter to use (Default is tab character.).  Quote or escape 
      blank (i.e.  -D ' ').

Rolloff scheduling notes:

  You may configure history rolloff to run via crontab (the UNIX scheduling 
  facility) provided you are authorized to use crontab.  See "man crontab" for details.  
  Crontab entries are unique to the UNIX ID that created them.

  -A  Identifies this as a history rolloff scheduling call.  Required.  Automatically 
      runs rolloff the specified number of times per day via crontab.  Values must be:

      -A n  n is 1-24.  Number of runs per day, rounded up to nearest divisor of 
       24 (e.g. -A 7 means run every three hours).

      -A 0  Cancels all automatic rolloff for the table(s) specified.

      -A ?  Lists rolloff crontab entries for all tables.

      The itmcmd history compares the table-pattern lists of the current and earlier runs.  
      For each item in the table-pattern list of THIS itmcmd history -A call, the pattern 
      is compared to the characters that defined each older pattern but NOT to each 
      possible expansion of the older pattern.  Example:

        Old call:  itmcmd history -A 2 -t quack*,moo*
        New call:  itmcmd history -A 1 -t   qua*,moo1*

        The intent is to change from 2 runs per day to one run per day.  Since qua* 
        matches quack*, it works, though it could match tables that quack* did not.  
        But moo1* does not match the literal characters moo* and does not stop the 
        twice-daily rolloff of moo* tables, even though both masks would match the 
        table MOO123.  If in doubt, this always works:

          itmcmd history -A0  # Cancel everything
          itmcmd history -A1 -t "tables I really want..."

        The itmcmd history preserves existing date, month and (if you omit -W) day-of-week 
        settings if any table in the current call matches an existing crontab entry.  
        If this is not the desired behavior, delete and re-create the entry.

        Other options, such as -D, -L and -H are NOT preserved.  They must be re-
        specified or defaulted with each itmcmd history -A call.

  -W  Day of week in crontab format (0=Sun, 1=Mon... 6=Sat).  The arguments to this 
      option can be a comma delimited list of numbers or ranges thereof.  Example:  
      -W 1,3-5 means Mon, Wed, Thu, Fri.  Default is 1-6 (Mon-Sat).

   Note on manual crontab updates:  The itmcmd history -A is the easiest way of managing 
   automatic itmcmd history rolloff execution.  However crontab allows scheduling 
   flexibility that itmcmd history -A does not.  You may manually create itmcmd history 
   commands in crontab.  However, if you ever want to use itmcmd history -A to list or 
   modify these entries, the first blank-delimited word after the command in the 
   crontab entry must be "-Ct".  The itmcmd history -A command preserves these scheduling 
   options on succeeding updates.
