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

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

Note

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.dat, dir, 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>
Warning

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.

 Output

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.

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

Note

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 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 the 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 the parameter history database. 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>

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

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 dir, annotate.dat, and param.hist files to the new directory. (The files must be named dir, annotate.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 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.

Warning

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:
    • . ./patrolrc.sh (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:

 

 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

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