Designing and Managing Behavior Models - Alarm Actions - Perl Subroutine - Defining a Perl Subroutine -
Perl Subroutine      Perl Subroutine Example

Defining a Perl Subroutine

Before you can add a Perl subroutine to a transition, you must write it (obviously) and store a compiled version of it in the NerveCenter database.

---

   Perl subroutines that you define inside NerveCenter use the Perl engine embedded in NerveCenter and not any Perl interpreters installed outside of NerveCenter. Any Perl programs run outside of NerveCenter will not have access to any NerveCenter variables or data structures.

---

---

   NerveCenter's Perl interpreter is single threaded. This means that only one poll, trap mask function, Perl subroutine, or action router rule can run at one time. Perl scripts that take a long time to run, such as logging to a file, performing database queries, or issuing external system calls, can slow down NerveCenter's performance. If you have need of such Perl scripts in your environment, use the scripts sparingly.

---

 
  To define a Perl subroutine within NerveCenter:

1. From the Admin menu in the main client window, choose Perl Subroutine List.

   The Perl Subroutine List window appears.

   

   This window contains a list with an entry for each Perl subroutine defined in your NerveCenter database. The Compiled Status column indicates whether the subroutine has been successfully compiled. From this window, you can add a new subroutine, modify an existing subroutine, or view the notes for a subroutine.

2. To add a new subroutine to NerveCenter, select the New button.

   The Perl Subroutine Definition window appears.

   

   This window enables you to name and define a new Perl subroutine.

3. Type the name of your new Perl subroutine in the Name field.

   ---

      The maximum length for Perl subroutine names is 255 characters.

   ---

4. To document your Perl subroutine, select the Notes button, enter a description in the Perl Subroutine Notes window, and select the OK button in that window.
5. Type your Perl subroutine in the Subroutine text entry box.

   Use Perl version 5 to write your subroutine. You can also make use of the NerveCenter functions and variables discussed in the sections Functions for Use in Perl Subroutines and NerveCenter Variables

   If you right-click in the Perl-subroutine editing area, you'll see a pop-up menu that lists all the functions and variables available for writing Perl subroutines. For more information about this pop-up menu, see the section Using the Pop-Up Menu for Perl on page 160.

   ---

      The maximum length for identifiers in Perl subroutines is 251 characters (252 including the variable type identifier character $, %, and so on).

   ---

6. Select the Save button in the Perl Subroutine Definition window.

   NerveCenter automatically attempts to compile the subroutine. If your Perl subroutine does not compile correctly, NerveCenter displays an error message from the Perl compiler. It also saves the subroutine and places it in the Perl Subroutine List, with the Compiled Status listed as Not Compiled.

   If your Perl subroutine compiles successfully, the saved subroutine is available for use in a Perl Subroutine alarm action. It won't be executed unless it's made the object of a Perl Subroutine action and the associated alarm transition occurs.

   ---

      Do not call the exec or exit function from within your Perl subroutine. These statements may cause the NerveCenter server to terminate.

   ---

Functions for Use in Perl Subroutines

NerveCenter provides a number of functions that you can use in your Perl subroutines. The list below indicates what types of functions are available and where you can find detailed information about each function:

• Variable-binding functions. These functions enable you to determine the number of variable bindings in a trigger's variable-binding list and to obtain information about each variable binding. For instance, you can retrieve the subobject and attribute associated with a variable-binding and the value of a variable-binding.

  For reference information about these functions, see the section Variable-Binding Functions on page 182.

• String-matching functions. These functions enable you to determine whether a string contains another string or a particular word. The functions are useful in conditions that test the value of a variable binding for a substring.

  For reference information about these functions, see the section String-Matching Functions on page 159.

• DefineTrigger(). This function enables you to create triggers which you can assign to variables and fire using FireTrigger() in NerveCenter Perl expressions.

  For reference information about this function, see the section DefineTrigger() Function on page 155.

• FireTrigger(). This function enables you to fire a trigger from your Perl subroutine. You can specify the name, subobject, and node attributes of the trigger.

  For reference information about this function, see the section FireTrigger() Function on page 156.

• AssignPropertyGroup(). This function enables you to assign a property group to the node associated with a trigger.

  For reference information about this function, see the section AssignPropertyGroup() Function on page 158.

• in(). This function determines whether one scalar value is in a set of scalar values.

  For reference information about this function, see the section in( ) Function on page 159.

• Counter(). This function returns the current value of an alarm counter. For reference information about this function, see the section Counter() Function.
• Node relationship functions. These functions enable you to import, export, and delete node parenting relationships from the NerveCenter database. You can use these functions in Perl subroutines that are called from alarms that you transition on demand. Node Relationship Functions.

Counter() Function

You use the Counter() function to get the value of an alarm counter for a particular alarm instance. The function can only be called from a Perl Subroutine alarm action or an Action Router rule.

The syntax of the Counter() function is shown below:

Counter()

Syntax: Counter("counterName")

Arguments:

counterName - The name of an existing alarm counter.

Description: The function returns the value of the specified counter.

Node Relationship Functions

The following functions import, export, and delete node parenting relationships from the NerveCenter database. You can use these functions in Perl subroutines that are called from alarms that you transition on-demand. One use for these functions is with the downstream alarm suppression behavior model that is shipped with NerveCenter. For more information, refer to the Open white paper, Open NerveCenter: Downstream Alarm Suppression.

LoadParentsFromFile()

Syntax: LoadParentsFromFile(filename)

Arguments:

filename - The name of the OVPA or manually created file containing the child parent relationships. This file should list each child node followed by the parent nodes in space-delimited fashion.

Description: Imports an OVPA or manually created file containing node parenting relationship information into the NerveCenter database.

Example: This statement loads the node relationship file data from the file nodeparents.dat into the NerveCenter database:

DumpParentsToFile()

Syntax: DumpParentsToFile(filename)

Arguments:

filename - The name of the file NerveCenter will output containing the child parent relationships exported from NerveCenter database.

Description: Exports node parenting relationship information from the NerveCenter database to the specified file on the local machine.

Example: This statement exports node relationship information from the NerveCenter database to the file nodeparents.dat:

RemoveAllParents()

Syntax: RemoveAllParents()

Description: Deletes node parenting relationship information from the NerveCenter database.

Example: This statement deletes node relationship information from the NerveCenter database.

NerveCenter Variables

NerveCenter defines a number of variables for use in Perl subroutines, Command Alarm actions, and logging actions. These variables contain information about the alarm transition that just occurred and about the trigger that caused the transition.

The variables (and functions) available to you for use in poll conditions, trigger functions, Action Router rule conditions, and Perl Subroutine alarm actions are summarized in a pop-up menu for Perl accessible via a right mouse click in the respective editing area. (See the section, Using the Pop-Up Menu for Perl on page 160, for more information.)

The variables available to you for use in Command Alarm actions and the logging actions are available to you via the Special Symbol drop-down listbox.

The complete list of NerveCenter variables that you can use are shown in NerveCenter Variables: