IP Adapter parsers

Unlike the Logfile Adapter, the SNMP Adapter, and the Perl EventLog for Windows Adapter, which have their own dedicated parsers, the IP Adapters can use any one of the following parsers that are included with the BMC Event Adapters.

Specifying a CSV parser

The CSV parser, MA::Parser::CSV, is a pluggable parser that parses a data stream into records (newline), in which each record is a comma-separated value list. The parser returns each value as a token to the mapper.

To specify the CSV parser

  1. Using a text editor, open the mcxa.conf file.
  2. In the section of the file that describes the adapter that you want to use with the CSV parser, add the following line:
    Parser = parsername

  3. In the parser section of the mcxa.conf file, define parser parsername. 

    The following table describes the parameters that you can modify in the parser definition: 

    CSV parser parameters

    Parameter

    Description

    FieldSeparator

    A set of characters that will be used as a delimiter 

    Optional

    Default: comma (, )

    KeepEmptyRecords

    Indicates whether empty records are formatted as tokens and passed to the mapping function 

    Required 

    Valid values:

    • 1 - Tokenize empty records
    • 0 - Discard empty records (Default)
    RecordNegFilter

    A regular expression that acts as a criterion to which each parsed record is compared 

    If the criterion is included in the record, the record is discarded. 

    Optional

    RecordPosFilter

    A regular expression that acts as a criterion to which each parsed record is compared 

    If the string is included in the record, the record is formatted as a token and passed to the mapping function. 

    Optional

    RecordSeparator

    Regular expression used to break a data stream into separate records 

    The resulting record is returned in the $data variable, which can then be used in the MAP file to refer to the entire record as one field. The $data variable is provided automatically. You cannot rename it. 

    Optional

    Default: \r?\n

     

    Note

    The input variable $data is set to the string between two consecutiveRecordSeparator entries. It performs the function that $complete performs in the LogFile, Perl EventLog for Windows, and SNMP Adapter mappings.

    VarPrefix

    Variable prefix used by the mapper Each token will be returned as prefix0... prefixn. 

    Optional

    Default: varlog

    Default variables sent to the mapper are named varlog0, varlog1.

     

    The following figure shows a sample parser definition for a parser named MyParser. 

    Sample CSV parser specification example

    [MyParser]
    Engine = MA::Parser::CSV
    FieldSeparator = ","  # Default
    KeepEmptyRecords= 0    # Discard Empty Records
    RecordNegFilter = "(test|dummy) event"
    RecordPosFilter = "(ERROR|WARNING)"
    VarPrefix = "token" # Return token<0>... token<n>
  4. Save and close the mcxa.conf file.

Specifying a Fixed-width (column) parser

The fixed-width parser, MA::Parser::FixedWidth, is a pluggable parser that parses a data stream into records. From each record, a field is extracted based on a fixed-width format.

To specify the fixed-width parser

  1. Using a text editor, open the mcxa.conf file.
  2. In the section of the file that describes the adapter that you want to use with the fixed-width parser, add the following line:
    Parser = parsername

  3. In the parser section of the mcxa.conf file, define parser parsername.
    The following table describes the parameters that you can modify in the parser definition. 

    Fixed-Width parser parameters

    Parameter

    Description

    FieldDefinitions

    A numerical pair that specifies which data is used in a field 

    The first number in the pair specifies from which character in the string to begin collecting data. The second number specifies how many consecutive characters are to be included in the field. 

    For more information, see Defining Fields. 

    Required

    KeepEmptyRecords

    Indicates whether empty records are formatted as tokens and passed to the mapping function required

    Valid values:

    • 1 - Tokenize empty records
    • 0 - Discard empty records (Default)
    RecordNegFilter

    A regular expression that acts as a criterion to which each parsed record is compared 

    If the criterion is included in the record, the record is discarded. 

    Optional

    RecordPosFilter

    A regular expression that acts as a criterion to which each parsed record is compared 

    If the string is included in the record, the record is formatted as a token and passed to the mapping function. 

    Optional

    RecordSeparator

    Regular expression used to break a data stream into separate records 

    The resulting record is returned in the $data variable, which can then be used in the MAP file to refer to the entire record as one field. The $data variable is provided automatically. You cannot rename it. 

    Optional 

    Default: \r?\n

     

    Note

    The input variable $data is set to the string between two consecutiveRecordSeparator entries. It performs the function that $complete performs in the LogFile, Perl EventLog for Windows, and SNMP Adapter mappings.

    TrimLeadingWS

    Removes leading white space, if any, from fields required

    Valid values:

    • 1 - Removes white space (Default)
    • 0 - Does not remove white space
    TrimTrailingWS

    Removes trailing white space, if any, from fields required

    Valid values:

    • 1 - Removes white space (Default)
    • 0 - Does not remove white space
    VarPrefix

    Variable prefix used by the mapper Each token will be returned as prefix0... prefixn. 

    Optional

    Default: varlog 

    Default variables sent to the mapper are named varlog0, varlog1, .

     

    The following figure shows a sample parser definition for a parser named MyParser. 

    Fixed-width parser specification example

    [MyParser]
    Engine = MA::Parser::FixedWidth
    RecordSeparator = "\r?\n"
    FieldDefinitions = "0:10,5:10,15:20"
    KeepEmptyRecords = 0
    TrimLeadingWS = 1
    TrimTrailingWS = 1
    VarPrefix = "token" # Return token<0>... token<n>
  4. Save and close the mcxa.conf file.

 Defining Fields

The contents of each field are determined by a pair of numbers. Each record from which the field is extracted is a string of data. The first field number indicates the starting position in the record at which the string field begins. The second number indicates the length of the string.

Defining a single field

The first character of the record is zero (0 ). A starting number of 5 indicates that the string begins with the sixth character in the record string.

Example

In this example, the string is as follows: ABCDEFGHIJKLMNOPQRSTUVWXYZ

If the field specification is <0,3>, then the string that composes the field is ABC. A is at position 0, and then starting from position 0, three characters are selected to constitute the field.

If the field specification is <11,2>, then the string that composes the field is LM. (Remember that the first character in the record is at position 0, not 1 ). L is at position 11, and then starting from position 11, two characters are selected to constitute the field.

Either number in the field specification can include a negative number. The field length position can include an asterisk wildcard (* ).

  • When the starting point (the first number) is negative, the starting position is determined from the end of the record.
Example

In this example, the string is as follows: ABCDEFGHIJKLMNOPQRSTUVWXYZ

If the field specification is <-8,3>, then the string that composes the field is STU. S is at position -8, and then starting from position -8, three characters are selected to constitute the field.

Alternatively, you can express the same string in positive numbers: <18,3>

  • When the field length (the second number) is negative, the end point of the string is calculated by counting back that number of characters from the end of the string and including everything between the starting  point and the end point.
Example

In this example, the string is as follows: ABCDEFGHIJKLMNOPQRSTUVWXYZ

If the field specification is <8,-3>, then the string that constitute the field is IJKLMNOPQRSTUVW. The string starts at I (position 8 ) and includes all but the last three characters in the record string.

  • Both the starting point and the length can be negative values.
Example

In this example, the string is:ABCDEFGHIJKLMNOPQRSTUVWXYZ

If the field specification is <-20,-4>, then the string that constitutes the field is GHIJKLMNOPQRSTUV. The string starts at G (position -20 ) and includes everything except the last four characters in the record string.

  • When the length is an asterisk (* ), all characters from the starting point to the end of the record string comprise the field string. Use the asterisk when you do not know the record field length but want to select all of it from the starting point that you specify.
Example

In this example, the string is as follows: ABCDEFGHIJKLMNOPQRSTUVWXYZABC

If the field specification is <15,*>, then the string that constitutes the field is PQRSTUVWXYZABC. The string starts at P (position 15 ) and includes all the remaining characters in the record string.

Defining Multiple Fields

Each record can contain multiple fields. Example for their order is as follows:

<START1>:<LENGTH1>[, <START2>:<LENGTH2>[, <STARTn>:<LENGTHn>[...]]]

Specifying record and field separated parser

The Record and Field Separated parser, MA::Parser::Separator, is a pluggable parser that parses a data stream into user-definable records. Each record is then converted into a token using a user-defineable field separator.

To specify the Record and field separated parser

  1. Using a text editor, open the mcxa.conf file.
  2. In the section of the file that describes the adapter that you want to use with the record and field separated parser, add the following line:
    Parser = parsername

  3. In the parser section of the file, define parser parsername.
    The parameters of the parser definition that you can modify are described in the following table: 

    Record and field separated parser parameters

    Parameter

    Description

    FieldSeparator

    Regular expression used to break a record into multiple fields 

    Required 

    Default: \s+ (separates on any instance of white space)

    KeepEmptyRecords

    Indicates whether empty records are formatted as tokens and passed to the mapping function 

    Required 

    Valid values:

    • 1 - Tokenize empty records
    • 0 - Discard empty records (Default)
    RecordNegFilter

    A regular expression that acts as a criterion against which each parsed record is evaluated

    If the criterion is included in the record, the record is discarded. 

    Optional

    RecordPosFilter

    A regular expression that acts as a criterion to which each parsed record is compared 

    If the string is included in the record, the record is formatted as a token and passed to the mapping function. 

    Optional

    RecordSeparator

    Regular expression used to break a data stream into separate records 

    The resulting record is returned in the $data variable, which can then be used in the MAP file to refer to the entire record as one field. The $data variable is provided automatically. You cannot rename it. 

    Optional

    Default: \r?\n

     

    Note

    The input variable $data is set to the string between two consecutiveRecordSeparator entries. It performs the function that $complete performs in the LogFile, Perl EventLog for Windows, and SNMP Adapter mappings.

    TrimLeadingWS

    Trims the leading white space from the record before applying RecordSeparator, which is achieved using the split function 

    In this parser, TrimLeadingWS does not trim the white space from each FIELD after the RecordSeparator has been applied.

    VarPrefix

    Variable prefix used by the mapper. Each token will be returned as prefix0... prefixn. 

    Optional

    Default: varlog 

    Default variables sent to the mapper are named varlog0, varlog1, .

     

    The following figure shows a sample parser definition for a parser named MyParser. 

    Record and Field Separated Parser Specification Example

    [MyParser]
    Engine = MA::Parser::Separator
    RecordSeparator = "\r?\n"
    FieldSeparator = "\s+"
    KeepEmptyRecords = 0    # Discard Empty Records
    RecordNegFilter = "(test|dummy) event"
    RecordPosFilter = "(ERROR|WARNING)"
     VarPrefix = "token" # Return token<0> ... token<n>
  4. Save and close the mcxa.conf file.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*