Designing and Managing Behavior Models
-
Using Polls - Writing a Poll Condition - Functions for Use in Poll Conditions -
NerveCenter includes a number of functions that you can use in constructing a poll condition. Several of these functions are designed specifically for use in poll conditions. For example, they enable you to determine the exact number of seconds between polls and to determine the change in the value of a MIB variable between one poll and the next. You can also use the functions DefineTrigger(), FireTrigger(), AssignPropertyGroup(), and in() and a set of string-matching functions. These functions can be used not only in defining poll conditions, but in defining other objects as well.
The functions and variables available to you for use in poll conditions are summarized in a pop-up menu for Perl accessible via a right mouse click from the poll condition editing area in the Poll Condition page of the Poll Definition window. (See the section, Using the Pop-Up Menu for Perl, for more information.)
For detailed information about all of these functions, see the following sections:
The functions discussed below are designed specifically for use in poll conditions.
Syntax: delta(baseObject.attribute)
baseObject.attribute - The name of a MIB variable qualified by the name of its parent object, for example, ifEntry.ifType.
Description: Returns the difference between the value of baseObject.attribute retrieved by the previous poll and that retrieved by the current poll.
Example: This statement fires a trigger if the number of SNMP messages sent to a node without an acceptable community name has increased:
if (delta(snmp.snmpInBadCommunityNames) >= 1) {
FireTrigger("authFail");
}
Description: Returns the number of seconds that elapsed between the previous poll and the current poll.
Example: This statement fires a trigger if the poll detects interface traffic levels exceeding 80 percent of capacity:
if (((delta(ifEntry.ifInOctets) + delta(ifEntry.ifOutOctets))
* 8) / (ifEntry.ifSpeed * elapsed) >= 0.801) {
FireTrigger("highLoad");
}
Description: Returns true if the poll is not able to read the value of the MIB attribute that precedes the function.
Example: This statement fires a trigger if the poll is unable to read the value of system.sysDescr from an agent's MIB:
if (system.sysDescr not_present) {
FireTrigger("noAgent");
}
Description: Returns true if the poll is able to read the value of the MIB attribute that precedes the function.
Example: This statement fires a trigger if the poll is able to read the value of ifInUcastPkts from an agent's MIB.
if (ifEntry.ifInUcastPkts present) {
FireTrigger("gotInUcastPkts");
}
The DefineTrigger() function enables you to create triggers which you can assign to variables and fire using FireTrigger() in NerveCenter Perl expressions. (In the scope of a subroutine, Perl requires you to define a variable before you can use it.)
You can use DefineTrigger() in NerveCenter anywhere that you write Perl expressions (except for Action Router rule conditions):
As with triggers created with FireTrigger(), the triggers you create with DefineTrigger() are available in the trigger lists NerveCenter displays when you are defining alarm transitions, Perl subroutines, and Action Router rule conditions.
The syntax for the DefineTrigger() function is shown below:
DefineTrigger()
name - "The" name of the trigger in quotation marks.
Description: DefineTrigger() creates a trigger which you can assign to a variable and fire using FireTrigger().
Example one: The expression creates a trigger named "hello" which is assigned to a Perl variable "$trig" and is then fired:
$Trig = DefineTrigger("hello")
FireTrigger($trig)
Example two: The following code excerpt is from a Perl subroutine (TestParentSetNode) associated with the downstream alarm suppression behavior models shipped with NerveCenter. $TriggerFlag stores the name of the trigger to be fired which depends on the status of the parent node:
DefineTrigger('UnReachable');
DefineTrigger('Down');
DefineTrigger('Testing');
...
if( ($ParentStatus eq "Down" || $ParentStatus eq "UnReachable") &&
$TriggerFlag eq "NotSet" )
{
$TriggerFlag = "UnReachable";
}
elsif( $ParentStatus eq "Up" )
{
$TriggerFlag = "Down";
}
elsif( $ParentStatus eq "Testing" && $TriggerFlag ne "Down" )
{
$TriggerFlag = "Testing";
}
...
FireTrigger( $TriggerFlag );
The FireTrigger() function enables you to fire a trigger from anywhere in NerveCenter that you write Perl expressions:
You specify the name of the trigger and optionally its subobject attribute and node attribute.
As with triggers created with DefineTrigger(), the triggers you create with FireTrigger() are available in the trigger lists NerveCenter displays when you are defining alarm transitions, Perl subroutines, and Action Router rule conditions.
The syntax for the FireTrigger() function is shown below:
FireTrigger()
Syntax: FireTrigger("name", [subobject, [node]])
name - The name of the trigger in quotation marks. Name can also be a Perl variable that is assigned a trigger using the DefineTrigger() function. For example:
$var=DefineTrigger("myTrigger");
FireTrigger($var);
subobject - You can pass a subobject to FireTrigger() in one of two ways.
You can use a string literal, for example, "ifEntry.2".
Second, if you called FireTrigger() from a trigger function or a Perl subroutine, you can use the function VbObject(n). This function returns the subobject associated with the nth variable binding in a trap or trigger.
node - You can pass a node to FireTrigger in one of three ways.
First, you can use the variable $NodeName, which is the default for this argument. How this variable obtains its value depends on the context in which it is used, as shown in the table below.
| If $NodeName is used in a ... | Its value is ... |
|---|---|
The name of the node associated with the agent address in an SNMP trap. | |
Second, include the name of the node in quotation marks, for example, "MyBestRouter" or "192.168.197.110". This string must match the name of the node as it's listed in the NerveCenter Node List window.
Finally, if the node name you want to pass to FireTrigger() is in a trap's or a trigger's variable bindings, you can use the function VbValue(n) to retrieve that name. This function returns the value of the nth variable binding.
Description: FireTrigger() creates a trigger with the name, subobject, and node values that you supply.
Example: The following call generates a trigger with the name "trigger" and the default subobject and node:
FireTrigger("trigger");
You use the AssignPropertyGroup() function to assign a property group to a node. The function can be called from a poll condition, a trap mask trigger function, or a Perl Subroutine alarm action. The node affected is the node being polled, the node from which a trap arrived, or the node associated with the trigger that caused an alarm transition (in the case of a Perl Subroutine action).
The syntax of the AssignPropertyGroup() function is shown below:
Syntax: AssignPropertyGroup("propertyGroup")
propertyGroup - The name of an existing property group.
Description: The function assigns a property group to a node.
Example: The example below shows the AssignPropertyGroup() function being used in a Perl Subroutine alarm action. If the variable $DestStateSev (which holds the name of the NerveCenter severity of the destination state) contains the string "Critical," the property group of the node associated with the trigger that caused the alarm transition is changed to CriticalGrp. The node will now be managed by a new set of behavior models.
if ($DestStateSev eq "Critical") {
AssignPropertyGroup("CriticalGrp")
}
The in() function is available for use in poll conditions, trap mask trigger functions, Perl subroutines, and Action Router rule conditions.
Syntax: in(scalar, scalar, ...)
scalar - An scalar value in a set of scalar values (often integers representing interface types).
Description: Returns true if the value of the attribute that precedes the function is found in the set of scalars in parentheses.
Example: This statement fires a trigger if a particular interface is part of a broadcast network:
if (ifEntry.ifType in (6,7,8,9,11,12,13,15,26,27)) {
FireTrigger("broadcast");
}
NerveCenter provides four string-matching functions (Perl subroutines), which can be used in poll conditions, trap mask trigger functions, OpC trigger functions, Perl subroutines, and Action Router rules. These functions enable you to determine whether a string contains a substring or a word.
Each of the string-matching functions is explained below:
Syntax: CaseContainsString(string, substring)
Description: Returns true if string contains substring. The match is case sensitive.
Syntax: CaseContainsWord(string, word)
Description: Returns true if string contains word, and word begins and ends on a word boundary. The match is case sensitive.
Syntax: ContainsString(string, substring)
Description: Returns true if string contains substring. The match is case insensitive.
Syntax: ContainsWord(string, word)
Description: Returns true if string contains word, and word begins and ends on a word boundary. The match is case insensitive.
| Previous: The Basic Procedure for Creating a Poll Condition | Next: Using the Pop-Up Menu for Perl |
| Please send comments or corrections to Information Development | This file was last updated on 10 October 2000 |