This documentation space contains information about PATROL Agents when deployed in a BMC Helix Operations Management environment. If you are a TrueSight Operations Management user, see PATROL Agent 21.3. Open link

Using fix_hist utility

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:

  • Run the fix_hist command-line utility
  • Set the /AgentSetup/fixHistFlag configuration variable to automatically run commands when the agent restarts

For more information, see the following topics:

Overview of the fix_hist utility

The fix_hist command tries to solve these problems by removing the errant pointers and packing the related files: dirannotate.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:

  • Shut down the PATROL Agent and run the fix_hist utility, and remove any history you no longer need by selecting Options > Clear History from the parameter list screen.
  • Shut down the PATROL Agent and move the annotate.datdir, and param.hist files.
    Be sure to move or delete all three files. When the agent is restarted, it creates new versions of these files.

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:

$ fix_hist -force_history_cleanup = <last number of days of parameter history to keep>


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.

Overview of the fixHistFlag configuration variable

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)

always — attempts repair, packing or both
dirtybit — attempts repair, packing or both if the history database indicates it may have been left in an unknown or incomplete state
no_repair_hist — Do not repair history
no_pack_hist_index — Do not pack history index files
nobackup — does not back up the history database before attempting repair, packing, or both
nopackann — does not pack annotations when processing the history database
repair_cycle — Specifies the maximum number of repair cycles
force_history_cleanup — Specifies the number of days you want to retain the parameter history

Default value


Minimum and maximum

Not applicable





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.

File and directory structure used by fix_hist

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.

Directory structure used by the fix history utility

The following table lists the directories for fix_hist:

 Directories for fix_hist

UNIX directoryDefinition
Windows directory

Directory specified when the PATROL Agent is started


Log directory for the PATROL Agent


Top directory of the parameter history databases contains top directories of each PATROL Agent


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


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


Files read by the fix history utility

The following table shows which files are read by the fix_hist utility: 

 Files read by fix_hist 

File descriptionFile name and path for UNIX
File name and path for Windows
Index filePATROL_HOME/log/history/<hostName>/<port_num>/dir
History text filePATROL_HOME/log/history/<hostName>/<port_num>/param.hist
History data filePATROL_HOME/log/history/<hostName>/<port_num>/annotate.dat

Relocating files

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:

  1. Create the directory PATROL_HOME/log/history/<hostName>/<new_port> on UNIX or PATROL_HOME\log\history\<hostName>\<new_port> on Windows.
  2. Move the files in the dirannotate.dat, and param.hist files to the new directory. (The files must be named dirannotate.dat, and param.hist.)
  3. To view the data, type the following command and press Enter

    dump_hist -p new_port

Before running the fix_hist utility

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 describes how to define this variable for UNIX and Windows.

Running the fix_hist utility

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

To run fix_hist

  1. Stop the PATROL Agent.
  2. For Windows, set the variable called %PATROL_HOME%. For UNIX, run one of the following scripts from the PATROL installation directory:
    • . ./ (for Korn and Bourne shell)
    • source.patrolrc (for C shell)
  3. At the command line,  run fix_hist and monitor the output.
  4.  Issue the following command to get the return code of the process: 

    $ echo $? 

    See Return values for fix_hist utility for more information about return values.
  5. Repeat step 3 and step 4 until no more errors are reported or until you determine that the history files cannot be fixed.

 Return values for fix_hist utility

The fix_hist utility exits with one of the following values:

  • 0 — fix_hist completed successfully
  • 1 — fix_hist was aborted because of an error

 Syntax for fix_hist utility

The fix_hist utility has the following format:


[-p port]
[-host hostname]
[-repair_cycle number]

 Options for fix_hist utility

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.

-force_history_cleanup <days>

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.

Examples of the fix_hist utility

The following examples illustrate how to use the fix history utility.

To repair history for an agent on a specific port

The following command fixes history and packs the data and index files at port 5000:

fix_hist -p 5000

To scan the history database a maximum of two times

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.

fix_hist -host host1 -p 3181 -repair_cycle 2

To repair history database without packing index files

The following command fixes history for host host1 at port 3181. The history index file is not packed.

fix_hist -host host1 -p 3181 -no_pack_hist_index

To pack index files without repairing history database

The following command packs the files for host host1 at port 3181. The history files are not scanned and fixed.

fix_hist -host host1 -p 3181 -no_repair_hist
Was this page helpful? Yes No Submitting... Thank you