Defining automated recovery actions

You can customize recovery actions in one of two ways. You can create or change recovery actions from the PATROL console, or you can customize recovery action response through automatic recovery actions (ARAs). Using ARAs provides the following benefits:

• You can maintain custom recovery actions outside PATROL for DB2 UDB, which means that upgrades are easier.
• You do not need a PATROL Console to create or change recovery actions.
• You can create different recovery script file versions for each computer, which means that computer-specific recovery is easier.
• You can integrate and write your own batch files without having to learn PSL.

To define recovery actions for parameters, use one of the following methods:

• From a PATROL Developer Console, you can access parameter definition dialog boxes and specify PSL and operating system recovery actions. (See the PATROL User Guide for your operating system for more information about how to add recovery actions from a PATROL Developer console.)
   If a user-customized recovery action is added to a parameter, ARA can be used to control the output. See Adding ARA to user-customized recovery actions for details.
• Without a PATROL Console, you can edit an external recovery script file that executes recovery actions for certain parameters of a monitored instance. This method is part of the PATROL for DB2 UDB ARA script function and is described in more detail in About the ARA script.
   You can also apply certain automated recovery actions to many parameters of a monitored instance that go into a warning or an alarm state (see the following table for a listing of these parameters). These recovery actions are set from the PATROL for DB2 UDB Configure Recovery Actions menu. See About the configure recovery actions menu for details.

Processing the ARA script

When a parameter goes into a warning or an alarm state, PATROL runs PSL and operating system recovery actions specified as part of the parameter definition. For parameters that support ARA, PATROL calls the external ARA script unless you have deactivated it. (You can deactivate execution of the script from the Configure Recovery Actions menu.) If PATROL for DB2 UDB calls the script and you have customized recovery actions through the script, those actions are executed.

In addition to calling the external ARA script, PATROL for DB2 UDB can generate certain automated recovery actions that you define through the Configure Recovery Actions menu. See About the configure recovery actions menu for details.

See the following figure for an illustration of this process.

Parameter recovery process

 Automated recovery action parameters

The following table lists the parameters for which you can set up automated recovery actions.

 About the ARA script

The file ara.sh (UNIX) or ara.cmd (Windows) is found in the $PATROL_ROOT/db2/ara (UNIX) or %PATROL_HOME%\db2\ara (Windows) directory on each monitored DB2 Universal Database computer.

PATROL for DB2 UDB is set up to automatically execute the ara.sh or ara.cmd script; however, you can deactivate the script at any time through the Configure Recovery Actions menu.

The ara.sh or ara.cmd script file can perform operating system commands as well as SQL commands using the DB2 Command Line Processor. When this script file is called, PATROL automatically passes the batch file information such as the name of the instance that is in an alarm state (for example, database, user, or DB2 Universal Database name), the parameter name, the alarm state, and the value of the parameter causing the alert.

The parameter name determines the action steps to be taken. Note that the actual command to be executed is located in the ara.sh or ara.cmd file. The ara.sh or ara.cmd file can be different for each DB2 Universal Database computer that PATROL is monitoring.

 About the configure recovery actions menu

In addition to activating or deactivating execution of the ara.sh or ara.cmd script, you can configure the following additional recovery actions through the Configure Recovery Actions menu as specified below. (For a list of parameters for which you can specify recovery actions, see Automated recovery action parameters.)

• execute net send to specified Windows desktops
• execute an SNMP trap (snmptrap command)
• create an output file in the PATROL_TEMP directory
• annotate a parameter warning or alarm
• trigger an event in PATROL Event Manager (PEM)

PATROL for DB2 UDB is set up to automatically execute the ara.sh or ara.cmd script, to annotate a parameter warning or alarm, and to trigger an event in the PEM; however, you can change these default settings at any time.

Command net send (Windows agents only)

If you activate the net send command, the ARA function builds a small message describing the issue and sends this message to each name listed in the ARA_SENDTO PATROL Agent configuration variable. The receiving Windows computers display a message on the desktop from the Windows Messaging Client.

SNMP traps

If you activate the SNMP trap option when you issue the net send command, the ara( ) function sends the message to all registered SNMP managers. For information about registering SNMP managers to receive traps, see the PATROL Agent Reference Manual section about the configuration variable snmp/pIV1m_list.

Output file

If you activate the output file option, a file is created containing the recovery action text in the PATROL_TEMP directory on the monitored DB2 Universal Database computer. The following file naming convention is automatically used:

instance-parameter_name*.out*

Parameter annotation

If you activate the annotate parameter option, the recovery action text is sent to the parameter annotation window for that parameter warning or alarm. For information about accessing parameter annotations, see the PATROL User Guide for your operating system.

Event trigger

If you activate the event trigger option, the parameter warning or alarm generates an event in the PEM with the recovery action text. For information about accessing the PEM, see the PATROL User Guide for your operating system.

Working with automated recovery actions

You can perform the following ARA tasks by using a PATROL Operator or Developer Console:The [confluence_table-plus] macro is a standalone macro and it cannot be used inline.

To customize automated recovery actions

Use this task to customize the automated recovery actions that PATROL for DB2 UDB performs when certain parameters go into a warning or an alarm state.

1. From the SETUP menu, select Configuration > Configure Recovery Actions > Set Default Actions.
    If more than one instance exists, the Configure Recovery Actions window appears. If you have only one instance to configure, skip to step 3.
2. From the Configure Recovery Actions window, select a DB2 DBM instance and click OK.
    The Configure Recovery Actions: Set Default Actions window opens. The DB2 instance that you selected appears under the date in the window.

3.  In the Configure Recovery Actions: Set Default Actions window, select the check boxes corresponding to the corrective actions that you want PATROL to perform.
    For a description of these actions, see About the configure recovery actions menu.

   Warning

   Note

   You can only enable the net send feature if you are monitoring DB2 UDB with a PATROL Agent running on Windows NT.

4. Click Accept.

To specify Windows NT message recipients

(Windows NT agent only) Use this task to specify the users who receive net send messages when one of the designated parameters goes into an alarm state. For users to receive net send messages, you must have already activated the net send automated recovery action. For more information, see To customize automated recovery actions. Each user must also have started the Windows Messaging client.

1. From the SETUP menu, select Configuration > Configure Recovery Actions > Set Sent to Names from the KM commands on the DB2 Setup popup menu.
    If more than one instance exists, the Configure Recovery Actions window appears. If you have only one instance to configure, skip to step 3.
2. From the Configure Recovery Actions window, select a DB2 DBM instance and click OK.
3. In the Configure Recovery Actions: Set Send to Names window, type the name of each Windows NT computer, separated by commas, to which you want to send a message.
4. Click Accept.

To test automated recovery action settings

Use this task to test current ARA settings. This test causes the ARATest parameter to go into alarm state so that you can verify that the recovery actions you configured execute correctly. This test also automatically resets the ARATest parameter back to an OK state.

1. From the SETUP menu, select Configuration > Configure Recovery Actions > Test Configuration from the KM commands on the DB2 Setup popup menu.
    If more than one instance exists, the Configure Recovery Actions window appears. If you have only one instance to configure, skip to step 3.
2. From the Configure Recovery Actions window, select a DB2 DBM instance and click OK.
3. In the Configure Recovery Actions: Test Configuration window, click Accept.
    The ARATest parameter goes into an alarm state, and the output displays in a task window. Also, depending on which ARA settings you select in the Set Default Actions dialog box, other appropriate actions occur. For more information, see To customize automated recovery actions.

 Adding ARA to user-customized recovery actions

If a user-customized recovery action is added to a parameter, ARA can be used to control output. ARA allows you to perform the following actions:

• annotate a parameter
• send text to an output file
• trigger an event
• execute an ARA script

If you write the recovery action in PSL code, add a call to the DB2rec2araL PSL function. In the example that follows, output is the text that is included in the annotation, the output file, and the event trigger; dbg is a debug flag where 1 is on and 0 is off.