find_match/5—find an entry in a match table and retrieve calculated values from it
The find_match/5 primitive finds an entry in a match table and retrieves calculated values from it. The syntax for this primitive is as follows:
$RESULTS=find_match($TBLNAME,$TAG,$VALUES,$OBJECTS)
find_match/5 arguments
Argument | Mode | Type | Description |
|---|---|---|---|
$TBLNAME | Input | STRING | Specifies the class name of the match table |
$TAG | Input | STRING | Specifies the tag to identify the requested part of the match table |
$VALUES | Input | LIST_OF STRING | Specifies the values to be matched as inputs |
$OBJECTS | Input | LIST_OF OBJECT | Specifies the objects to be used for evaluation of the output expressions |
$RESULTS | Output | LIST_OF STRING | Results of the output expression evaluation |
Use the find_match/5 primitive to find a matching entry in the match table of class $TBLNAME, filtered by $TAG. The input for the match is the list of values specified in $VALUES. The objects $OBJECTS are to be used in the evaluation of the output expressions. The results of this evaluation of output expressions for the matching entry are returned in $RESULTS.
Match tables are collections of instances of the data classes BEM_MATCH_TABLE, BMC_SIM_MATCH_TABLE or any subclass of these data classes. The $TBLNAME argument, indicating the required data class, and the $TAG argument work together to determine which instances must be considered to find a match. Only instances of the required data class, or any of its subclasses, that have the value of $TAG in their tag slot are considered.
An entry of the match table will match if all of the elements specified in $VALUES match the corresponding elements of the input_match slot of the entry.
There can be multiple match table entries that match. Only the match with the highest precedence is selected by using the following precedence rules:
- A match for the n th element has precedence over a match for the (n+1)th element.
- If there are matches on the same element, the match operators are ordered, in decreasing precedence, as equals, has_prefix, has_suffix, contains, any.
- If there are multiple has_prefix matches on the same element, the longest prefix takes precedence.
- If there are multiple has_suffix matches on the same element, the longest suffix takes precedence.
- If there are multiple contains matches on the same element, the longest string takes precedence.
- If there are multiple contains matches with same string length on the same element, the match closest to the beginning of the string takes precedence.
When a matching entry is found, output expressions, as defined in the output_expressions slot of the matching entry, are evaluated. The results of these evaluations are returned in $RESULTS. The resulting list must contain as many elements as there are output expressions in the entry.
During evaluation of the output expressions, instances from $OBJECTS can be referenced. These references are indicated as $1, $2,... in the output expression to refer to the first, second,... element of $OBJECTS. Each object passed in $OBJECTS must be an instance of the class specified at the same position in the slot ref_instances_classes of the matching entry.
find_match/5 example
In the following example, there are several instances of BEM_MATCH_TABLE:
tag=t1;
input_match=['<SERVICE>','<svc_>*'];
ref_instances_classes=[EVENT,DATA];
output_expressions=['sprintf("Service %s (%s) changed to %s",
[$1.mc_object,$2.description,$1.mc_parameter_value])',MINOR];
END
In this example, the KB contains data objects that provide a description of registered services. A rule that handles service-related events can look up the data object for the service, returned in $D in the following piece of code, while the event is referenced through $E.
[$E,$D],[$MSG,$SEV]);
$E.msg = $MSG;
$E.severity = $SEV;
If the mc_object_class of the event has the value SERVICE, and its mc_object starts with svc_, the call of find_match/5 will match the previously mentioned BEM_MATCH_TABLE entry.
The event and data object references are passed through the fourth argument. They are referred to in the output expressions as $1 and $2, respectively.
Evaluation of the two output expressions returns a message into $MSG and a severity in $SEV. The severity is a constant value. The message is produced by filling in some slots from the event (mc_object and mc_parameter_value) and the description slot of the data object in a message format.