How to Use Procedures for Event Processing › Parse a Single Varbind into Multiple Event Variables

Parse a Single Varbind into Multiple Event Variables

In this example, a device produces a trap that contains a single varbind. That varbind contains multiple components that are required for correct processing of the alarm. A procedure is required to extract the components and place them into event variables, where they can be used as event discriminators.

We have analyzed the trap and know that the varbind contains a string with a well-defined pattern: ERROR TEXT:SEVERITY. We also know that the ERROR TEXT could be any arbitrary string, but that the SEVERITY is limited to a set of values: Critical, Major, Minor, Clear, None, or Special.

Therefore, we must create a pattern of (.*):(Critical|Major|Minor|Clear) to match our varbind. We use the left-hand side as a discriminator, and the right side as the severity. We also want a unique alarm instance that is created for each ERROR TEXT. And we want the Clear trap to clear only matching ERROR TEXT alarms.

We want to create a single event that is capable of handling many different error code and severity combinations. Using a procedure, we instruct the event to create multiple event variables. But first, we must create an entry in the AlertMap file for the trap.

Follow these steps:

1. Log in to the SpectroSERVER as an administrator.
2. Locate the AlertMap file in the following directory:

   SS/CsVendor/vendor_directory
   

   Note: An AlertMap file maps an alert to a CA Spectrum event. AlertMap files are automatically created when you map a trap to an event using MIB Tools.

3. Open the file in a text editor.
4. Use the following syntax for the new entry:

   Alert Code Event Code OID Map
   

   where the OID Map includes the OID, the value variable ID, and the instance variable ID.

   For example, the following syntax provides a fictional example:

   1.3.6.1.4.1.17844.1.2.6.0 0x05a91900 1.3.6.1.4.1.17844.1.1.1(1,0)
   

5. Create a regexp pattern to extract the error code into one variable, and the severity into another variable.

   In this example, we create a procedure that parses any number of tokens so that we can reuse it for other, similar requirements:

   Pseudo Code:

   Given a text string and a pattern
   Set the starting index
   If the text string matches the pattern then for each () in the pattern,
   extract the text enclosed and put it into an event variable at the current index; increment the index
   else throw an error message
   When all the () are exhausted, create an event with the new event variable list
   

   Example from an EventDisp File:

   0x05a91000 P " \
   SetVariable({V pattern},{S \"(.*):(Critical|Major|Minor|Clear|None|Special)\"}, \ SetVariable({V counter},{U 500}, \
   If(Regexp(GetEventVariable({U 1}),{V pattern}), \
   CreateEventWithVariables({C CURRENT_MODEL},{H 0x05a91002}, \ ForEach(GetRegexpList(\
   GetEventVariable({U 1}),{V pattern}),{Variable X}, \
   {Variable retVal},GetEventVariableList(), \
   Prog2(Assign({V retVal},SetEventVariable({V retVal},{V counter},{Variable X})), \ Assign({V counter},Add({V counter},{U 1}))))), \
   CreateEventWithVariables({C CURRENT_MODEL},{H 0x05a91001}, GetEventVariableList()))))"
   

   Notes: Validation occurs during the processing. If the input string does not match the pattern (for example, the syntax ERROR TEXT:BadSeverity does not match), an alarm is created. The alarm details indicate that the processing did not complete because the input was not formatted correctly. Including validation is extremely helpful in troubleshooting.

   For a complete walkthrough of this code sample, see "Code Walkthrough," below.

6. Add the procedure to an event map using the syntax that is described in Add a Procedure to an Event Map.

   The server sets the correct environment for the procedure evaluation, with the current model and event preset.

Code Walkthrough

0x05a91000 P " \
SetVariable({V pattern},{S \"(.*):(Critical|Major|Minor|Clear|None|Special)\"}, \ SetVariable({V counter},{U 500}, \
If(Regexp(GetEventVariable({U 1}),{V pattern}), \
CreateEventWithVariables({C CURRENT_MODEL},{H 0x05a91002}, \ ForEach(GetRegexpList(\
GetEventVariable({U 1}),{V pattern}),{Variable X}, \
{Variable retVal},GetEventVariableList(), \
Prog2(Assign({V retVal},SetEventVariable({V retVal},{V counter},{Variable X})), \ Assign({V counter},Add({V counter},{U 1}))))), \
CreateEventWithVariables({C CURRENT_MODEL},{H 0x05a91001}, GetEventVariableList()))))"

{V pattern} is the extraction pattern. If you wanted 3 tokens you would only have to change this pattern. The following example shows an extraction pattern:

(.*):(.*):(Something|Else)
The (.*) brown (fox|duck) (jumped|slid) over the lazy (.*) => {S 501}=quick {S 502}=fox 
{S503}=jumped {S 504}=dog

{V counter} is the starting index. The GetRegexpList function determines that the entire string is contained at counter, while the first extracted token is at counter + 1.

GetEventVariable({U 1}) returns the value of varbind 1 (you might know it as {S 1} or {I 1} in event messages). This instruction effectively means, "Get the event variable at index 1." If your variable is in varbind 100, use U 100, for example.

ForEach says, "For each item in the list returned by GetRegexpList, do something."

GetRegexpList returns a list of extracted tokens, but they cannot solely be used as event variables. They must be written to the EventVariableList.

Prog2 is like a code block that lets two independent actions execute sequentially. In this case, the code instructs, "Assign the current token to the event variable list at the current index, then increment the index counter."