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

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:

Example

HOST_12/NT_CACHE.NT_CACHE/CACcachCopyReadHitsPercent Fri May 05 09:22:56 CCYY 98.5958 Fri May 05 09:23:56 CCYY 98.324 Fri May 05 09:24:56 CCYY 100 Fri May 05 09:25:57 CCYY 99.4318 Fri May 05 09:26:57 CCYY 100 Fri May 05 09:27:57 CCYY 100 Fri May 05 09:28:57 CCYY 90.1566 Fri May 05 09:29:57 CCYY 96.1365 Fri May 05 09:30:57 CCYY 92.2062

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

UNIX directory	Definition
Windows directory
PATROL_HOME	Directory specified when the PATROL Agent is started
PATROL_HOME
PATROL_HOME/log	Log directory for the PATROL Agent
PATROL_HOME\log
PATROL_HOME/log/history	Top directory of parameter history databases contains top directories of each PATROL Agent
PATROL_HOME\log\history
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>
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
PATROL_HOME\log\history\<hostName>\<port_num>

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
Index file	PATROL_HOME/log/history/<hostName>/<port_num>/dir
	PATROL_HOME\log\history\<hostName>\<port_num>\dir
History text file	PATROL_HOME/log/history/<hostName>/<port_num>/param.hist
	PATROL_HOME\log\history\<hostName>\<port_num>\param.hist
History data file	PATROL_HOME/log/history/<hostName>/<port_num>/annotate.dat
	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...
PATROL_HOME	`../patrolrc.sh` (for Korn and Bourne shell) `source.patrolrc` (for C shell)
	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

Note

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:

 dump_hist -options

Syntax of dump_hist command

The dump_hist utility has the following formats:

dump_hist

[-p port]
[-host hostname]
[-class regexp] or [-class_noreg literal string]
[-inst regexp] or [-inst_noreg literal string]
[-format OPTIONS format]
[-param regexp] or [-param_noreg literal string]
[-s mmddhhmm[yyyy]]
[-e mmddhhmm[yyyy]]
[-timestamp]
[-annotate]
[-nostat]
[-v]

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

Option	Definition
-p	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.
-host	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.
-format "options"	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.
-s -e	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. See the example For a specific time period.
-timestamp	This option prints time stamps as integers instead of converting them into a local time string. See the example To print time as an integer rather than a local time string.
-annotate	This option prints annotation text for a data point that is annotated.
-nostat	This option suppresses the display of summary statistics. Only the raw history data is printed, which simplifies parsing.
-v	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.

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.)

Options for -format of dump_hist

Option	Definition
%H	Host name
%A	Application name
%I	Instance name
%P	Parameter name
%y	Year (yyyy)
%m	Month (mm)
%d	Day (dd)
%g	Time in the Greenwich Mean Time (GMT) format
%h	Hour
%M	Minutes (MM)
%s	Seconds (ss)
%v	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:

,,smile,USERS,USERS,USRNoSession,CCYY-10-16 20:51:53,22

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:

dump_hist

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:

smile|USRNoSession|22|10/16/CCYY|202153

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