Using the Archive Utility


Overview

Tasks

Included with

Tivoli Problem Management

Overview

Help topic contents

After you complete the installation process described in Configuring the Archive Utility, you are ready to use the Archive Utility. This help topic explains the following aspects of using the Archive Utility:
  • Configuring archiving options
  • Running the Archive Utility
  • Managing archiving processes
  • Ensuring compatibility with Tivoli Problem Management modifications

Configuration options

Before you can archive data, you must configure the Archive Utility with the appropriate information. The following information must be specified:

Tivoli Problem Management configuration

To properly archive data, the Archive Utility must access the correct Tivoli Problem Management database tables.

You should verify that the Tivoli Problem Management version and database information displayed in the Tivoli Problem Management Archive Utility window are correct.

If the Tivoli data source that is listed is not the Tivoli Problem Management production data source, then:

Where data is to be archived

Before you can archive data, you must specify a destination for the archived items. You can choose from the following three options:
  • Flat file
  • Database
  • Delete data

If you choose to archive data to a flat file, each line in the file represents one record from a table. To archive to a flat file, you must specify the file in which to archive data. Refer to APIs Used With the Archive Utility for more information about flat files.

If you choose to archive to a database, archived data is stored in archive tables in the default database. The default database is identified as the Tivoli Data Source in the Tivoli Problem Management Archive Utility window. To archive to a database, the destination database tables must already exist. Refer to Creating destination database tables for more information on creating archive tables.

If you choose to delete data, all archived items are deleted. They are not copied to a flat file or to an archive database table.

Caution: If you choose this option, you cannot retrieve the deleted data for any purpose!

Dates of data to be archived

An archived item can be any problem or information call with a "closed" status. The closed status of these problems and calls is assigned on a particular date. To indicate which data items are to be archived, you specify the range of dates during which the items to be archived were designated as closed.

Note that the dates you specify are inclusive. That is, the problems that are archived include those that were designated as closed on the starting and ending dates.

Items to be archived

In order to perform an archiving procedure, you must specify the number of items to be archived.

Items can consist of multiple records in multiple tables. For example, an information call consists of one CALL and one or more SESION records.

If you first specify the archiving dates, you can use the Estimate function to determine how many items exist to be archived within the given range. Estimate calculates the number of items to be archived, and displays the result in the Total Items to Archive box.

This is a useful function when you are unsure of the number of data items to be archived, or when you need to limit the number of items to be archived. If the number calculated by Estimate is too high, you can narrow the range of dates or specify a lower number of items.

If you are running the Archive Utility for the first time, it may be useful to use different number values to determine the amount of time required to archive data at your site. You can use different values in both the Commit Size and Total Number of Items text boxes to test performance at your site.

Commit size

You must specify the commit size for the archiving procedure.

Commit size refers to the number of items to be archived before a database "commit" is executed. This number should be considerably less than the value of the rollback segment because an item consists of multiple CALL, SESION, WORK_HISTORY, PROBLEM_HISTORY, and PROBLEM records. By default, the commit size is 50 items.

Commit size and rollback segments should be configured for high volume data transfer. Refer to the database documentation for your site to confirm the commit size and rollback segments that your database uses. This value should only be modified if authorized by a database administrator.

Compatibility with Tivoli Problem Management

Because the Archive Utility works with Tivoli Problem Management data, modifications or customizations to Tivoli Problem Management may affect the Archive Utility. When you modify Tivoli Problem Management, you must ensure that the Archive Utility is compatible with those modifications.

The following Tivoli Problem Management modifications require you to alter the Archive Utility for use with Tivoli Problem Management data:

  • Installation of Tivoli Problem Management after installing the Archive Utility
  • Customizations to the Tivoli Problem Management PROBLEMS, SESION, CALL, PROBLEM_HISTORY or WORK_HISTORY tables

The following sections describe the steps to take to maintain Tivoli Problem Management compatibility after each of these modifications.

Tivoli Problem Management customizations

If you archive to a database and you have customized any of the following tables in the Tivoli Problem Management database, you must customize the Archive Utility to reflect those changes:
  • PROBLEMS
  • SESION
  • CALL
  • PROBLEM_HISTORY
  • WORK_HISTORY

Customizing the archive tables involves two separate steps:

  • Modifying the build scripts that create the archive tables, or modifying the tables themselves
  • Editing the eaacust.kb file to reflect the changes in the archive tables

Before installation, the simplest way to customize the archive database tables is to modify the scripts that build the tables. After installation, however, re-running build scripts destroys all data in the tables. Instead, you should make the necessary customizations directly to the archive database tables themselves. Refer to the documentation for your DBMS for more information on customizing database tables.

When to modify eaacust.kb

Each of the Tivoli Problem Management tables used by the Archive Utility corresponds to a procedure in the eaacust.kb file. The procedure names are listed below. The name of each procedure includes the name of the table to which it corresponds.
  • EAProblems
  • EASesion
  • EACall
  • EAProblem_History
  • EAWork_History

If you have customized any of these tables in Tivoli Problem Management, you must modify the corresponding procedure entry in the eaacust.kb file.

String or integer data

Depending on the type of data you added to the Tivoli Problem Management table, you need to use a different procedure to define the new field in the eaacust.kb procedure.
  • For strings, such as char and vchar fields, use AddStr
  • For non-strings, such as integer and date fields, use AddNonStr

The AddStr and AddNonStr procedures take the same parameters:

( VAL Wrap : STRING, VAL Delmtr : STRING, 
REF str : STRING, VAL newstr : STRING)

Descriptions of the parameters follow:

Parameter Description
Wrap Character placed around strings or non-strings in output text files
Delmtr Character used to separate columns in output text files
str Reference parameter whose value is defined at run time. Always use "str" as the argument for this parameter.
newstr The name of the new field

Refer to APIs Used With the Archive Utility for a description of each of the file export characters to use as arguments for these parameters.

For example, if you added a column to an Tivoli Problem Management table, you must add a new line to the procedure in eaacust.kb which corresponds to the additional column.

Suppose you added a Problem_Code field to the PROBLEM_HISTORY table in Tivoli Problem Management in order to track the changes to problem codes. You must then add a new line to the EAProblem_History procedure in eaacust.kb which corresponds to the Problem_Code field.

Because problem codes are strings, the line you add to define the new Problem_Code field in the EAProblem_History procedure looks like this:

AddStr( STD, DELM, str, ph.problem_code);

Tasks

Configuring and running the Archive Utility

The following steps provide a guideline for using the Archive Utility.
  1. Start the Archive Utility as described in Starting the program.
    The Tivoli Problem Management Archive Utility window appears.
  2. Under Tivoli Problem Management Configuration, verify the version and data source information.
  3. Under Data Destination, select the location where archived files are sent.
    If you select Flat File, go to the next step.
    Otherwise, go to step 11.
  4. Do one of the following:
    • In the File Name box, type the full PATH and file name in which to archive data, and go to step 11.
    • Choose the File Name Browse button.
  5. In the Select Flat File dialog box, point to an existing file as the archive destination, or go to step 8.
  6. Choose Open.
  7. When a File Exists message appears which asks if you want to append archived data to the file, choose Yes.
    Go to step 10.
  8. Point to the folder where the archive file is to reside, and specify a file name.
  9. Choose Open.
  10. The Tivoli Problem Management Archive Utility window reappears with the File Name box filled in.
  11. Do one of the following:
    • In the Close Date From box, type the starting date for the items to be archived.
    • Choose the Calendar button, and use the Calendar to specify a date.
  12. Do one of the following:
    • In the To Date box, type the ending date for the items to be archived
    • Choose the Calendar button, and use the Calendar to specify a date.
  13. Do one of the following:
    • In the Total Items to Archive box, type the number of items to be archived.
    • Choose Estimate.
  14. In the Commit Size box, type the number of items to be archived before a commit is executed, or leave the default.
  15. Choose Execute.
  16. In the Execute dialog box, choose OK.
    The Archive Processing dialog box appears.
    When the archive process is complete, the Complete dialog box appears.
  17. Choose OK.
  18. When the Tivoli Problem Management Archive Utility window reappears, choose Exit.
    The Archive Utility closes.

Running the Archive Utility on multiple machines

It may be advisable to run the Archive Utility on more than one machine at various times. Choosing to use more than one machine may be a function of:
  • The amount of data to be archived
  • Limited time in which to perform an archive
    Caution: Do not run more than one Archive utility process at a time on an MS-SQL Server or Sybase database. These databases support page-level locking rather than row-level locking; simultaneous archiving decreases performance.

To run the Archive Utility on multiple machines simultaneously, you need to:

  1. Start the Archive Utility on each machine.
  2. Make sure the same data source is referenced by each machine.
  3. Enter non-overlapping date ranges for each machine.
    Note: For example, if you use a date range from 1/1/1997 to 4/15/1997 on one machine, you can use the date range from 4/16/1997 to 6/30/1997 on the other machine.
  4. Choose Execute.
    The data contained within each date range is archived.
    Note: Running simultaneous archives on the same database may cause slow performance of Tivoli Problem Management.

Dropping tables after the Archive Utility runs

You may want to consider dropping the tables used for the Archive Utility after the utility runs. Dropping tables saves considerable space on the data source.

Caution: If the data in dropped tables is required for future use, back up the archive tables before you drop them.

To drop the tables created for use with the Archive Utility, choose the script that corresponds to your database server and run it with TSD Build.

If your DBMS is... then run this drop script file...
Oracle 7.x eaaor7.drp
DB2 eaadb2.drp
MS-SQL Server eaamss.drp
Sybase 10.x eaassyb.drp
Informix eaainf.drp

Refer to the Tivoli Service Desk Installation Guide for more information on using TSD Build.

Modifying archive tables for use with DDM

If you archive to a database, and you install DDM for use with Tivoli Problem Management, you must ensure that the archive tables are compatible with DDM.

If you install DDM after the Archive Utility is installed and the archive tables are created, you can alter the tables for use with DDM by running an .alt script file which corresponds to your DBMS. You must not run any build scripts (.tab scripts) for this purpose. Doing so destroys any data currently present in the archive tables.

Follow these steps to modify the archive tables for use with DDM:

  1. Complete the procedure for running the .alt script, as described in Modifying archive tables for use with Tivoli Problem Management.
  2. Parse the Archive Utility, as described in Parsing the Archive Utility files.

Editing eaacust.kb

The following procedure describes how to edit eaacust.kb:
  1. Open the text editor for your system.
  2. From the File menu, choose Open.
  3. From the Open File dialog box, select the directory where eaacust.kb is stored.
  4. Select eaacust.kb.
  5. Choose OK.
    Result: The file, eaacust.kb, appears in the text window of the editor.
  6. Scroll down to the procedure which corresponds to the Tivoli Problem Management table you customized.
  7. Add a line to represent each new field in the table.
    Note: Use AddStr or AddNonStr, as appropriate, to define the field.
  8. From the File menu, choose Save.
  9. Exit the text editor.
  10. In the Tivoli Archive Utility program group, choose the Parse Archive Utility icon.
    Result: The Archive Utility parses.