Problems with the history database sometimes develop through undesirable incidents such as an abrupt shut down of the PATROL Agent. In these cases, one or more pointers in the .dir file could lead to erroneous data in the other two files. Corrupted history can cause the agent to consume excessive amounts of CPU and memory.
The PATROL Agent provides two ways for you to correct problems with the history database:
Set the /AgentSetup/fixHistFlag configuration variable to automatically run commands when the agent restarts
For more information, see the following topics:
The fix_hist command tries to solve these problems by removing the errant pointers and packing the related files: dir, annotate.dat, and param.hist. Often you will find out that your history database has these problems when you see an error message similar to the following:
Found inconsistency in hist param database.
On Microsoft Windows operating systems, the history index file has a file size limit of 2 GB.
Once such a problem is discovered, you might want to perform one of the following actions:
The -force_history_cleanup<days> option is available in versions 3.5.30 and later of fix_hist (available for PATROL for UNIX 9.0.00 and later and PATROL for Microsoft Windows Servers 3.0.01 and later). The -force_history_cleanup option deletes anything older than the number of days specified. This option is used to trim the history files.
The syntax for the option is as follows:
BMC recommends archiving history files before you use this feature. The number of days that the parameter history is retained is relative to the time at which the fix_hist -force_history_cleanup command is issued. You cannot delete selective parts of the history file or manually add data to the history files.
While reading the annotation database, the fix_hist utility creates a file. When the utility encounters an error that it cannot repair, it saves the data that it has already read and discards the data that is unreachable due to a corrupted pointer or other error.
The fix history utility backs up the history database files that it attempts to repair by appending "~#~" to each file, for example param.hist.~3~. The utility then writes the recovered information to the history database files, for example param.hist.
The /AgentSetup/fixHistFlag variable automatically runs commands when the agent restarts to back up and repair history files.
Format and type of data
text string (comma-separated list)
Minimum and maximum
For more information about changing configuration variables, see Using wpconfig (Windows) to configure the BMC PATROL Agent and Overview of the xpconfig configuration utility.
With PATROL Agent version 3.5.30 or later, the /AgentSetup/fixHistFlag Agent configuration variable is used to fix the history files when the agent starts up.
The /AgentSetup/fixHistFlag variable can have one of the following values:
Values for the /AgentSetup/fixHistFlag variable
Attempts to repair, pack, or both; always run fix_hist
Attempts to repair, pack, or both when the history database indicates that the database may have been left in an unknown or incomplete state; run fix_hist only when the history was not closed properly during the previous agent was shut down
Do not repair history
Do not pack history index files
Do not pack annotation file
Do not back up history file
Specifies the maximum number of repair cycles
Specifies the number of days you want to retain the parameter history
If the /AgentSetup/fixHistFlag variable is not defined, the default of never is used.
PATROL creates and maintains a standard file and directory structure in which it stores the history database. The fix_hist utility will not run if the proper file and directory structure do not exist.
The following table lists the directories for fix_hist:
Directories for fix_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 the parameter history databases contains top directories of each PATROL Agent|
|PATROL_HOME/log/history/<hostName>||A PATROL Agent's top directory of the parameter history database. 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|
The following table shows which files are read by the fix_hist utility:
Files read by fix_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|
Moving these files will not prevent you from viewing them. The dump_hist utility can be used to view the old history data.
To reuse the old history data, perform the following steps:
The PATROL environment must be set up prior to running fix_hist. You must set the PATROL_HOME environment variable. Before running the dump_hist utility page describes how to define this variable for UNIX and Windows.
Running the fix_hist command could require shutting down the agent for a considerable amount of time. The length of the down time is directly related to the size of dir, annotate.dat, and param.hist. If these files are very large or any down time for the agent is undesirable, consider clearing unneeded history or moving the files instead of running the fix_hist utility. Some options for the fix_hist command may reduce its run time. See Options for fix_hist utility.
The fix_hist utility requires disk space while it is running. If you have limited disk space on your computer, it is possible to run out of space. Running out of disk space can cause all PATROL files to be inaccessible or it can cause other applications to crash.
%PATROL_HOME%. For UNIX, run one of the following scripts from the PATROL installation directory:
. ./patrolrc.sh(for Korn and Bourne shell)
source.patrolrc(for C shell)
$ echo $?
The fix_hist utility exits with one of the following values:
The fix_hist utility has the following format:
The following table lists and defines the options recognized by the fix_hist utility:
Options recognized by the fix_hist utility
This option tells fix_hist or the PATROL Agent process to ignore an invalid lock and start anyway. An invalid lock occurs when fix_hist or PATROL Agent incorrectly detects a conflicting process is running for the same host and port.
This option specifies the last number of days for which you want to keep the parameter history.
This option specifies which PATROL Agent's history database is used. By default, the name of the host on which fix_hist is started is used.
This option stops this command from repairing the history. This option is useful if you only want to pack the data and index files.
This option specifies that the history index file is to be left unpacked.
This option specifies that the annotation file is to be left unpacked.
This option prevents the history files from being backed up before the command starts.
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 the maximum number of times to scan the history data while repairing it.
This option displays version information.
The following examples illustrate how to use the fix history utility.
The following command fixes history and packs the data and index files at port 5000:
The following command fixes history and packs the data and index files for host host1 at port 3181. It will scan the history file a maximum of two times.
The following command fixes history for host host1 at port 3181. The history index file is not packed.
The following command packs the files for host host1 at port 3181. The history files are not scanned and fixed.