dump_hist utility

Use the dump_hist command line utility to extract parameter history data from databases maintained by PATROL Agents and save the data to ASCII text files. History data is printed to standard output in text form.

• • Output of dump_hist utility
  • File and directory structure used by dump_hist
    • History database directory structure
  • History database file composition
  • Before running the dump_hist utility
  • Running dump_hist
    •  Syntax of dump_hist command
    • Return values of dump_hist command
    •  Options for dump_hist utility
    •  Format options
  • Examples for dump_hist command
    • For current host
    • For application instance
    • To print time as an integer rather than a local time string
    • To write to a file
    •  For a specific time period

Output of dump_hist utility

The dump_hist utility extracts the following information by default:

• Hostname
• Application class
• Instance
• Parameter
• Time and date
• Value

The following example is a portion of a history dump output:

File and directory structure used by dump_hist

PATROL creates and maintains a standard file and directory structure in which it stores the history database. The dump_hist utility will not run if the proper file and directory structure do not exist.

History database directory structure

The following table lists the directories for dump_hist:
dump_hist directories

History database file composition

The following table shows the files read by dump_hist: 

Files read by dump_hist

Before running the dump_hist utility

The PATROL environment must be set up prior to running dump_hist. You must set the PATROL_HOME environment variable. 

The following table describes how to define this variable for UNIX and Windows:

PATROL_HOME environment variable

Running dump_hist

Type the following command at the command line prompt and press Enter:

 Syntax of dump_hist command

The dump_hist utility has the following formats:

Return values of dump_hist command

The utility exits with one of the following values:

• 0 — All matching parameters were dumped successfully
• 1 — dump_hist was aborted because of invalid options

 Options for dump_hist utility

The following table lists and defines the options recognized by the dump_hist utility:

If multiple options are specified, they are interpreted as "and" conditions. For example, if you specify both -class and -param, then for the parameter to be dumped, its application class must match the regular expression given by the -class option, and its application instance must match the regular expression given by the -inst option.

 Format options

The -format option controls the layout of ASCII texts files created by the dump_hist command. This option can be used to decide what information is in the file. It can also make these files easier to read or import into popular desktop applications such as spreadsheet and word processing programs. Using a PATROL KM for history loading, it can facilitate uploading these files into databases such as Oracle, Sybase, and Microsoft SQL Server. (See the PATROL Knowledge Module for History Loader User Guide for more information.)

The syntax of -format requires placing the options in the above table between quotes and using characters such as commas (,), pipes (|), and dashes (-) to separate these values. Consider the following example:

This command produces a .dat file in the PATROL_HOME/remote directory on UNIX and PATROL_HOME\remote directory on Windows, and each line of the file uses the same character separators. 

Following is a sample line from a file generated by this example:

Examples for dump_hist command

The following examples illustrate how to use the dump history utility to extract certain types of information:

For current host

The following command prints all parameters for the current host:

For application instance

The following command prints all parameters of the application instance, db_manager, on a host entitled host1:

To print time as an integer rather than a local time string

The following command disallows the conversion of time stamps to a local time string:

Following is a sample line of output generated by this command:

To write to a file

This command redirects the output of dump_hist to a file called dump_hist.out. Each line of this file uses a pipe symbol to separate the values and displays the host name, parameter name, parameter value, date, and time.

 For a specific time period

This command prints history data from October 1, CCYY 8:00AM through October 1, 9:00AM of the same year.