Sections

The MAP file can be divided into the following sections:

• INPUT_VARIABLES
   In this section, input variables from the adapter are defined. Input variables statements belong in this section. See INPUT_VARIABLES section.
• INIT
   In this section, common initialization of the slots is performed. Init statements belong in this section. See INIT section.
• DEFAULT
   Default classes are defined. See DEFAULT section.
• CLASS
   The mapping between BMC ProactiveNet cell classes and internal adapter classes is defined in the CLASS section. Class statements belong in this section. See CLASS section.

 INPUT_VARIABLES section

Input variables take their value from the parsing of data received by the adapter. Parsers do this by parsing a log file from a Syslog or LogFile Adapter, decoding a packet from an SNMP Adapter, or using a dedicated API from a user-defined adapter. Variables are stored internally by the adapter in the form a Perl hash table. Variables must be declared inside the INPUT_VARIABLES structure in order to be recognized and used by the MAP file. The input variables are not chosen arbitrarily. They must correspond to the internal Perl structure of the event.

Single variables

The INPUT_VARIABLES section begins with a line that contains only the keyword INPUT_VARIABLES and ends with a line that contains only the keyword END. Within the section, each variable is declared in a single line. The name of a variable must begin with the $ character.

Variables contain scalar values such as $avariable. These values are scalar in the context of the Perl language. They can represent a string or a number, depending on the variable definition. Therefore, these variables must be assigned only to relevant BMC ProactiveNet cell slots.

The variables can also be references in Perl context to any type of object. Such reference variables cannot be used for slot assignment, except as references to a list as discussed below, but can be used as arguments of customized functions. If the variable is a reference to a Perl list, it can be an assignment value for a slot which is of the LIST_OF type.

Series of variables

The MAP file supports declaration of a series of variables. The syntax is the same as that used for scalar variables except that the variable name must be followed by an interval of values. Three forms of acceptable declaration of sets are:

$setA 0-43

$setB 43

$setC 0-i

The first line declares 44 scalar variables, $setA1,$setA2,...,$setA43. The second line is equivalent to the first declaration. The third line declares a set of undefined size. In this case, variables $setC0, $setC1, $setC2, ..., $setC99 can be used in the MAP file. If the set has a size larger than 100, its size must be specified in the declaration. There is no size limit to sets other than your computer's memory resources. In other words,

$set N

is equivalent to

$set0

$set1

...

$setN

Order

Except in the variables declaration, the input variables section can contain comments. This section must be the first, as illustrated in the example of the input variables section of the SNMP Trap Adapter as shown in the following figure.

Comments code example

The MAP file is case-sensitive. $Source and $SOURCE are different variables.

For backward compatibility, the $LOGFILE INPUT_VARIABLES contains the value of the LogLOGFILE parameter in the configuration file or "logfile" as default. A new INPUT_VARIABLE, $logname, is available and contains the name of the log file. In addition, the syntax of the parameters is changed to be consistent with all adapters. Specific parameters to the LogFile Adapter begin with Log with an upper case L.

Slot assignments

Most MAP file entries are either a slot assignment or a condition. A slot assignment is used to enter an input value into a BMC ProactiveNet cell slot.

Unlike variables, the BMC ProactiveNet cell slots are not declared in the MAP file. They are syntactically reproduced when they are sent to the cell. The following figure illustrates acceptable slot assignment formats:

Slot assignment formats

The first five lines are simple assignments either from constants (lines 1 - 3) or from a variable (lines 4 and 5). When slot_name is assigned to a constant, this constant is recognized from the first non-space character after the equal ( = ) sign, to the last non-space character on the same line. 

Strings must be delimited by double quotation marks ( "" ). Because of the construction of a MAP file, a string cannot contain new lines. For new lines to be included in a string, a user-defined Perl function must be defined. For more information, see the last assignment for slot_name containing <perl_func>. Strings can contain quotation marks because the last quotation mark in the line is considered to be the end of the string.

Line 5 involves a substring of a variable, $variable. This corresponds to the matching substring of $variable, evaluated in a condition statement involving a regular expression matching $variable.

Slots can also be assigned to the return value of one of the seven functions as listed in the following table. Functions are used to insert in a slot a value held by an entity in the network, such as the IP address of a computer.

Slot functions

The most general method of assignment is represented by the following assignment form: slot_name can be assigned to the return value of built-in Perl functions, or any user defined Perl function, that is defined in an external file and loaded with the REQUIRE directive. 

slot_name = <perl_func>( <args>, ...)

<perl_func> can be either a built-in Perl function, such as length or time, or a function defined in files loaded with the REQUIRE directive. The arguments <args> of <perl_func> can be any of the following:

• Constants such as "a string", 1234
• Input variables such as $avariable, $anothervar[eventadapter90trial:1]
• Variables known in the global context such as @INC, $ENV{'PATH'}
• Simple expressions involving function calls such as length($avariable)

Constants and input variables are used as in other assignments. In addition, <perl_func> can accept other arguments that are valid Perl expressions in the global context. Local variables of the MAP module MA::Map and other modules are not known, except for variables with a global scope not declared with a ' my ' statement, when their name is preceded by the module name and ::). These expressions cannot contain comma characters ( , ) except in strings that have single or double quotation marks. For example, an argument such as badarg($farg1, $farg2) is not valid, while goodarg("string, string") is a valid argument.

Conditions

A condition is a Boolean expression associated with a CLASS statement that must be satisfied so the current event matches the class. A condition has the following format:

<var> <operator> <comp_value>

<var> is either an input variable or a substring of an input variable set in a previous condition, such as

$avariable

$anothervar[eventadapter90trial:1]

<operator> is one of the operators listed in the following table:

Operators

When the operator is smaller, greater, smaller_or_equals, or greater_or_equals, <var> must contain a number. 

The <comp_value> represents:

• A number, such as 12, -2, 0xFF, .314E+2
• A string, such as "A string" (<operator> must be equals or not_equals)
• A regular expression, such as / . matchthis./ (<operator> must be equals or not_equals)
• DEFINE representing one of the previous three values, such as #mydefine.

Pattern matching

<comp_value> regular expressions are evaluated with the Perl rules for pattern matching. For more information about pattern matching see Perl documentation. The regular expression can contain parentheses that match substrings of <var>. These substrings can be accessed by using the [] operator on <var>. Technically, if <var> represents $var, the Perl variables $1, $2, ..., $9 are stored in $var[eventadapter90trial:1], $var[eventadapter90trial:2], ..., $var[eventadapter90trial:9]. For example:

Suppose that $match contains "first second third and so on...." The first condition is satisfied because $match contains at least two words. After the first condition, $match[eventadapter90trial:1] contains "first" and $match[eventadapter90trial:2] contains "second". The second condition is satisfied and slot is set to "second". 

The following is a more complex example:

The second condition also involves pattern matching. The second condition is satisfied; $match[eventadapter90trial:1] contains "ir" and $match[eventadapter90trial:2] contains "st". slot is set to "st". Such substrings can be used in nested CLASS structures. The second example shows how a substring, can be used by itself as an expression for pattern matching. In this case, the new partial strings extracted from the subexpression are accessed by using the operator [] from the base string. To clarify, examine the following condition: $match[eventadapter90trial:1] equals {{/f(..)(.)/. After successful matching, the expressions corresponding to the two expressions (..) and (.) will be stored in $match[eventadapter90trial:1] and $match[eventadapter90trial:2], overriding the previous values of $match[eventadapter90trial:1] and $match[eventadapter90trial:2]. Expressions such as $match[eventadapter90trial:1][eventadapter90trial:1] and $match[eventadapter90trial:1][eventadapter90trial:2] are not allowed. This may seem counterintuitive, but it is very much in accordance with the Perl approach to pattern matching, where special variables $1, $2, and so on take new values at each match. 

The regular expressions:

• Cannot contain references to the variables declared in the INPUT_VARIABLES section
• Support the following modifiers: g i m o s x

For more information about  such modifiers, see the Perl documentation. For example.

$match equals /AnY_cAsE/i

matches the string "any_case" in lowercase and uppercase.

 INIT section

The INIT section contains assignments of BMC ProactiveNet cell slots that are common to all events. The following figure illustrates the structure of the INIT section.

INIT structure

<assignment> is an assignment. When an external event is mapped to a BMC ProactiveNet cell event, the assignments of the INIT section are evaluated for each event. A CLASS or DEFAULT assignment overrides a slot value previously set in the INIT section.

 DEFAULT section

The following figure illustrates the structure of the DEFAULT section.

DEFAULT structure

<class_name > is the name of the default class, such as EVENT and DEF_ADAPTER_EV. Ensure that the class name is recognized by the cell to which it is sent. If an event does not match any CLASS requirements, an event of class <class_name> can be generated. The slots of the event are set by evaluation of the assignments of the INIT and DEFAULT sections. DEFAULT assignments override INIT assignments of the same slot. The DEFAULT section can contain no assignments. The DEFAULT section is optional. At most, one DEFAULT section is authorized.

By default, the DEFAULT mechanism is disabled. That is, if an event does not match any class, it is dropped before being sent to the cell. To enable the DEFAULT class mechanism, either:

• Use the -e command-line option without argument, or
• Use the MapUseDefaultClass (MapUseDefaultClass=1) parameter in the configuration file (etc/.conf* ).

 CLASS section

The CLASS structures contain the main information about how to map adapter events into BMC ProactiveNet cell events. CLASS structures can be nested. The following figure illustrates the CLASS leaf section.

CLASS leaf structure

General structure

The following figure illustrates the general structure for nested class mapping.

Nested class mapping structure

<class_name>, <sub_class_name>, and <subsub_class_name> are names of the BAROC classes. An event matches a CLASS <class_name> when all conditions ( <condition> ) associated with that class and parent classes are satisfied. If all conditions ( <condition> ) are satisfied, assignments ( <assignment> ) associated with that CLASS and possible parent classes ( CLASS ) are evaluated in order to build a BAROC event. This BAROC event is then sent to a cell. Classes are evaluated sequentially. As soon as an incoming event satisfies all the conditions of a CLASS and does not match any subclass of that CLASS, an event of the corresponding BAROC class is created, and then sent.

Even if it is often the case, the CLASS structure of the MAP file is not required to reflect the BAROC classes as defined in a .baroc file. The nature of the hierarchical classes in the MAP file is purely syntactic. The BAROC class corresponding to a subclass need not be a subclass, in the BAROC sense, of the BAROC class corresponding to the parent CLASS in the MAP file sense. In addition, a MAP file can contain several classes having the same <class_name>.

Class name

Moreover, a MAP file can contain CLASS <class_name> statements of nonexistent corresponding BAROC class names ( <class_name> ). In this case, either the MAP writer has verified that no event will match that CLASS without matching any subclass or events of CLASS <class_name> will be dropped by the cell, as shown in the following figure.

Class name example

The preceding CLASS structure defines several possible matches for CLASS A or CLASS B. Even if CLASS B is nested in CLASS A in the first CLASS A structure, CLASS B is not necessarily a BAROC subclass of CLASS A. Note that the BAROC CLASS B must have a defined slot, slot1. CLASS dummy need not be a defined BAROC class since the condition under the nested CLASS B, $var2 equals /.*/, is always satisfied, which means that it is impossible to generate a dummy event from that MAP file sample.