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
The dump_hist utility extracts the following information by default:
- Application class
- Time and date
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:
|PATROL_HOME||Directory specified when the PATROL Agent is started|
|PATROL_HOME/log||Log directory for the PATROL Agent|
|PATROL_HOME/log/history||Top directory of parameter history databases contains top directories of each PATROL Agent|
|PATROL_HOME/log/history/<hostName>||A PATROL Agent's top directory of parameter history created by the PATROL Agent using the official host name on which it is running|
|PATROL_HOME/log/history/<hostName>/<port_num>||The directory where a single PATROL Agent stores files when multiple PATROL Agents are running on the same host created by the PATROL Agent using its port number|
History database file composition
The following table shows the files read by dump_hist:
Files read by dump_hist
|File description||File name and path for UNIX|
|File name and path for Windows|
|History text file||PATROL_HOME/log/history/<hostName>/<port_num>/param.hist|
|History data file||PATROL_HOME/log/history/<hostName>/<port_num>/annotate.dat|
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
|Environment variable||For UNIX, run...
For Windows 2000 or later, select...
|Start > Settings > Control Panel > System > Environment; and type the variable name (PATROL_HOME) and value (the path), and click Set.|
|Start > Settings > Control Panel > System > Advance, and click Environment Variables. Click New and type the variable name (PATROL_HOME) and value (the path). Then, click OK.|
Running dump_hist while the PATROL Agent is also running can cause unpredictable results.
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:
dump_hist utility options
This option specifies which PATROL Agent's history database is used. Combined with the -host option, -p specifies a unique PATROL Agent. The value of this option must be the port number to which the specified PATROL Agent is listening. The default value is 3181.
This option specifies which PATROL Agent's history database is used. By default, the name of the host on which dump_hist is started is used.
-class or -class_noreg
This option specifies which application classes to dump. You can use -class to filter out parameters whose application classes do not match the given regular expression. The _noreg extension indicates that the argument will be interpreted literally.
-inst or -inst_noreg
This option specifies which application instances to dump. You can use -inst to filter out parameters whose application instances do not match the given regular expression. The _noreg extension indicates that the argument will be interpreted literally.
See Format options.
-param or -param_noreg
This option specifies which parameters to dump. You can use -param to filter out parameters whose names do not match the given regular expression. The _noreg extension indicates that the argument will be interpreted literally.
These options specify the time span for which you want to view history. Only parameter points that occur after the start date and time (-s mmddhhmm[yyyy]) and before the end date and time (-e mmddhhmm[yyyy]) are provided.
This option prints time stamps as integers instead of converting them into a local time string.
This option prints annotation text for a data point that is annotated.
This option suppresses the display of summary statistics. Only the raw history data is printed, which simplifies parsing.
This option displays version information.
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.
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.)
Options for -format of dump_hist
Time in the Greenwich Mean Time (GMT) format
Parameter value stored in param.hist file
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:
dump_hist -format ",,%H,%A,%I,%P,%y-%m-%d %h:%M:%s,%v"
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:
dump_hist -host host1 -p 3181 -inst db_manager
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:
dump_hist -host host1 -p 3181 -inst db_manager -timestamp
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.
dump_hist -format "%H|%P|%v|%m/%d/%y|%h%M%s" >dump_hist.out
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.
dump_hist -s 10010800CCYY -e 10010900CCYY
CCYY represent the century and year. When using this format option, enter the actual year.