Event filter syntax

Event filters uses event IDs or source user names to filter out JP1 events. Event filters are specified in the following places:

Forwarding settings file (forward)
Additional extended attribute settings files (recv_add_extattr and send_add_extattr)
Local action execution definition file (jbslcact.conf)
jevexport command
JP1 event acquisition function (JevGetOpen)^#
Extended attribute mapping settings file^#

#: For details, see J.4 Converting JP1/SES events into JP1 events.

Organization of this page

Event filter format
Condition statement format
Examples of event filter settings

Event filter format

An event filter is a set of one or more condition groups. A condition group is a set of one or more condition statements. A condition statement is a line of conditions, and a number of such lines together constitute a condition group. The only statement you can write between condition groups is the single word OR. The maximum length of one line is 1,024 bytes. An event filter can be no more than 64 KB total.

A condition group is satisfied only if all the condition statements in the group are satisfied. The event filter conditions are satisfied if one or more of the condition groups are satisfied.

The following figure shows the concept of an event filter.

Figure 16‒1: Concept of an event filter

In JP1/Base 09-00 or later versions, you can write exclusion condition for event filters.

Define an exclusion condition when you want to exclude a specific JP1 event from the JP1 events that satisfy the extraction conditions.

Only the statement EXCLUDE can be written between the extraction conditions and the exclusion conditions. EXCLUDE can only be written once for each filter. The condition groups stated before EXCLUDE are extraction conditions; the condition groups stated after EXCLUDE are exclusion conditions. The format for exclusion conditions is the same as the format for extraction conditions.

Because exclusion conditions are not required, filters that were created in an earlier version of JP1/Base can still be used in version 09-00 or later, without having to modify the filters.

If the condition group is not defined, then conditions are satisfied unconditionally. However, if the exclusion conditions after EXCLUDE are not defined, EXCLUDE is ignored.

For the forwarding settings file, undefined extraction conditions are not permitted, and an error occurs if extraction conditions are not defined.

Be aware that if only OR is defined for the exclusion conditions or for the extraction conditions of forwarding settings file, or if either of the condition groups before or after OR is not defined, it is not considered a formatting mistake and conditions are satisfied unconditionally.

To Page Top

Condition statement format

Write condition statements in the following format:

attribute-namecomparison-keywordoperand-1operand-2...

[Figure] is a separator representing one or more continuous spaces or tab characters. When multiple operands are specified, the condition statement is satisfied even if only one of them is true. Spaces, tab characters, CR, LF, and percent signs cannot be written as ordinary characters in the operands, but can be represented as two-digit hexadecimal codes, as follows:

Space: %20
Tab: %09
CR: %0d
LF: %0a
%: %25

Characters other than space, tab character, CR, LF, and % symbols can also be represented using hexadecimal codes.

Notes

An event registered in JP1/SES format that contains Japanese characters will not match the condition if its encoding differs from that of the condition statement.
If a condition statement contains a machine dependent character, the statement cannot be correctly applied.

Attribute name

Table 16‒8: Attribute names in filter condition statements
Attribute name	Contents	Type and format
`B.SEQNO`	Serial number in the event database	Number (0 to 2,147,483,647)
`B.ID`	Event ID	Event ID^#1
`B.PROCESSID`	Source process ID	Number (0 to 2,147,483,647)
`B.TIME`	Registered time	Number (0 to 2,147,483,647 = cumulative seconds since UTC 1970-01-01 00:00:00)
`B.ARRIVEDTIME`	Arrived time	Number (0 to 2,147,483,647 = cumulative seconds since UTC 1970-01-01 00:00:00)
`B.REASON`	Reason to register the event into the event database	Number (1 to 4)
`B.USERID`	Source user ID	Number (-1 to 2,147,483,647)
`B.GROUPID`	Source group ID	Number (-1 to 2,147,483,647)
`B.USERNAME`	Source user name	Character string^#3
`B.GROUPNAME`	Source group name	Character string^#3
`B.SOURCESERVER`	Source event server name	Character string^#3
`B.DESTSERVER`	Destination event server name	Character string^#3
`B.SOURCESEQNO`	Source serial number	Number (0 to 2,147,483,647)
`B.CODESET`	Code set	Character string^#3
`B.MESSAGE`	Message	Character string^#3
`E.extended-attribute-name`^#2	Extended attribute	Character string^#3

#1: Event IDs are different from character strings and numbers. For details, see the paragraph beginning with When the attribute value is an event ID... in the Conditions column of Table 16-9.

#2: For the format of extended attribute names, see 17.1.2 Extended attributes.

#3: Character strings are case sensitive.

Comparison keywords

Table 16‒9: Comparison keywords in filter condition statements
Comparison keywords	Number of operands	Conditions
`IN`	1 or more	The attribute value must match one of the operands. When the attribute value is of the string literal type: The operand can be any character string. Example: `B.MESSAGE` `IN` `KAJP` `KAVA` When the attribute value is a number: The operand must be a character string that can be interpreted as a (signed) integer. Other operands are never matched. Example: `B.REASON` `IN` `1` When the attribute value is an event ID: The operand must be a string in the form `x:y` or `x` (where `x` and `y` are hexadecimals of 1-8 digits). `x` represents the base code and `y` represents the extended code of the event ID. Other operands are never matched. Example: `B.ID` `IN` `111:0`
`NOTIN`	1 or more	Negation of the `IN` comparison keyword Example: `B.USERNAME` `NOTIN` `hitachi` Example: `B.SEQNO` `NOTIN` `1004959` Example: `B.ID` `NOTIN` `00003A71`
`BEGIN`	1 or more	The attribute value is of the string literal type, and must begin with one of the character strings specified in the operands. A numeric attribute value, or an attribute value that is an event ID, fails the condition. Example: `B.MESSAGE` `BEGIN` `KAVA`
`RANGE`	2	The condition statement is satisfied when the attribute name is `B.TIME` or `B.ARRIVEDTIME`, and the following conditions are satisfied: The attribute value is a number, or a character string interpreted as a number (0 to 2,147,483,647) `operand-1` and `operand-2` are 14-digit numeric literals When the attribute value is interpreted as the cumulative seconds since UTC 1970-01-01 00:00:00, and converted to a numeric literal in `yyyymmddHHMMSS` format based on the time zone of the event server operating environment, and `operand-1` <= `attribute value` <= `operand-2.` Example: `B.TIME` `RANGE` `20140715000000` `20140716000000` When the attribute value is a number, specified in an attribute name other than `B.TIME` or `B.ARRIVEDTIME`: The condition is satisfied if `operand-1` and `operand-2` are interpreted as numbers, and `operand-1` <= `attribute value` <= `operand-2`. Example: `B.SEQNO` `RANGE` `1004000` `1005000` When the attribute value is of string literal type: The condition is satisfied if `operand-1` <= `attribute value` <= `operand-2` when the value is compared in order of its character codes. Example: `B.MESSAGE` `RANGE` `KAJP1001` `KAJP1070` When the attribute value is an event ID: If `operand-1` and `operand-2` are strings in the form `x:y` (where `x` and `y` are hexadecimals of 1 to 8 digits), the whole interpreted as a 16-digit hexadecimal with `y` representing the upper 8 digits (extended code) and `x` representing the lower 8 digits (basic code), the condition is satisfied if `operand-1` <= `attribute value` <= `operand-2`. Example: `B.ID` `RANGE` `4780` `4790` Attribute values of all other types fail the condition.
`TRANGE`	2	The condition is satisfied if: The attribute value is a number, or a character string interpreted as a number (0 to 2,147,483,647) `operand-1` and `operand-2` are 14-digit numeric literals When the attribute value is interpreted as the cumulative seconds since UTC 1970-01-01 00:00:00, and converted to a numeric literal in `yyyymmddHHMMSS` format based on the time zone of the event server operating environment, and `operand-1` <= `attribute value` <= `operand-2`. Example: `B.TIME` `TRANGE` `20140716010000` `20140716013000` Attribute values of all other types fail the condition.
`DEFINED`	0	The condition is satisfied if `attribute-name` represents an extended attribute, and the specified extended attribute is defined. If the extended attribute is undefined, the condition fails. This condition is necessarily true when `attribute-name` represents a basic attribute. Example: `E.PRODUCT_NAME` `DEFINED`
`NOTDEFINED`	0	Negation of the `DEFINED` comparison keyword Example: `E.PRODUCT_NAME` `NOTDEFINED`
`SUBSTR`	1 or more	The condition is satisfied if the attribute value is a string literal type, and includes one of the character strings specified in the operands.A numeric attribute value, or an attribute value that is an event ID, fails the condition. Example: `B.MESSAGE` `SUBSTR` `error`
`NOTSUBSTR`	1 or more	Negation of the `SUBSTR` comparison keyword Example: `B.MESSAGE` `SUBSTR` `warning`
`REGEX`	1 or more	Regular expression comparison keyword. The condition is satisfied if the attribute value is of the string literal type, and matches one of the regular expressions specified in the operands. Example: `B.MESSAGE` `REGEX` `KAV.[0-9][0-9][0-9][0-9]-E` For details on regular expressions, see F. Syntax of Regular Expressions.
`WITHIN`^#	2	The condition statement is satisfied when the attribute name is `B.TIME` or `B.ARRIVEDTIME`, and the following conditions are satisfied: The attribute value is a number, or a character string interpreted as a number (1 to 2,147,483,647) `operand-1` is `M` (minutes), `H` (hours), or `D` (day). `operand-2` is a character string that can be handled as a number (unsigned). When `operand-1` is `M` (minutes) or `H` (hours): When the attribute value is interpreted as the cumulative seconds since UTC 1970-01-01 00:00:00, and converted to a numeric literal in `yyyymmddHHMMSS` format based on the time zone of the event server operating environment, and (current time - `operand-2` <= `attribute value` <= current time). Example: `B.TIME` `WITHIN` `M` `30` Example: `B.TIME` `WITHIN` `H` `12` When `operand-1` is `D` (day): When the attribute value is interpreted as the cumulative seconds since UTC 1970-01-01 00:00:00, and converted to a numeric literal in `yyyymmddHHMMSS` format based on the time zone of the event server operating environment, and 00:00:00 on [today's date - (`operand-2` - 1)] <= `attribute value` <= 24:59:59 on today. Example: `B.TIME` `WITHIN` `D` `7`

#: You can specify this keyword in a filter file used for the jevexport command.

To Page Top

Examples of event filter settings

The following are description examples of the IN comparison keyword:

Select the JP1 event whose event ID consists of basic code 111 and extended code 0.

B.ID IN 111:0
or
B.ID IN 111
or
B.ID IN 00000111:00000000

Select JP1 events whose source user ID is 103.

B.USERID IN 103
or
B.USERID RANGE 103 103

Select JP1 events whose source event server names are reysol.

B.SOURCESERVER IN reysol

The following are description examples of the BEGIN comparison keyword:

Select JP1 events that issued messages beginning with KAJP or KAVA.

B.MESSAGE BEGIN KAJP KAVA

Select JP1 events whose issued messages begin with the words Hello, world. Use the code %20 to represent the space between the comma and "w".

B.MESSAGE BEGIN Hello,%20world

The following are description examples where extended attributes are involved:

Select JP1 events that have extended attributes with the attribute name TASK_NAME, and that have inventory_management set as the value of the attribute.

E.TASK_NAME IN inventory_management

Select JP1 events that have extended attributes with the attribute name TASK_NAME (the attribute value is irrelevant).

E.TASK_NAME DEFINED

The following is a description example of multiple conditions (AND condition):

Select JP1 events whose event IDs are other than 222:0, and whose source user names are ann.

B.ID NOTIN 222
B.USERNAME IN ann

The following is a description example of multiple groups of conditions (OR condition):

Select JP1 events that have:

Warning or Error set as the value of the extended attribute SEVERITY, and for which the extended attribute PRODUCT_NAME is defined
www.hitachi.co.jp set as the source event server, and /HITACHI/JP1/AJS set as the value of the extended attribute PRODUCT_NAME

E.SEVERITY IN Warning Error
E.PRODUCT_NAME DEFINED
OR
B.SOURCESERVER IN www.hitachi.co.jp
E.PRODUCT_NAME IN /HITACHI/JP1/AJS

The following is a description example of exclusion condition (EXCLUDE):

Select the JP1 event whose event ID is 101 or 102, or whose severity level has an error. However, JP1 events whose source event server names are host3 are not selected.

B.ID IN 101,102
OR
E.SEVERITY IN Error
EXCLUDE 
B.SOURCESERVER IN host3

The following is a description example of the TRANGE comparison keyword:

Select JP1 events that occurred on or after June 16, 2002^#.

B.TIME TRANGE 20020616000000 99999999999999

The following are description examples of the WITHIN comparison keyword:

Select JP1 events that occurred within 30 minutes before the current time (current time:01:30:00 on July 16, 2003)^#.

B.TIME WITHIN M 30 
(Same as B.TIME TRANGE 20030716010000 20030716013000)

Select JP1 events that occurred within 24 hours before the current time (current time:01:21:21 on July 16, 2003)^#.

B.TIME WITHIN M 24 
(Same as B.TIME TRANGE 20030715012121 20030716012121)

Select JP1 events that occurred in the last two days, including today (today: July 16, 2003)^#.

B.TIME WITHIN D 2 
(Same as B.TIME TRANGE 20030715000000 20030716235959)

#: Based on the time in the event server environment

To Page Top