Job Management Partner 1/Base User's Guide
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)
- Local action execution definition file
- jevexport command
- JP1 event acquisition function (JevGetOpen)#
- Extended attribute mapping settings file#
#: For details, see J.4 Converting JP1/SES events into JP1 events.
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 14-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.
Condition statement format
Write condition statements in the following format:
attribute-namecomparison-keyword
operand-1
operand-2
...
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.
- Note
If a condition statement contains a machine dependent character, the statement cannot be correctly applied.
Attribute name
The following table contains the attribute names that can be used in filter condition statements.
Table 14-2 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 14-3.
#2: For the format of extended attribute names, see 15.1.2 Extended attributes.
#3: Character strings are case sensitive.
Comparison keywords
The following table shows how to specify comparison keywords in filter condition statements.
Table 14-3 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.
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.
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.NOTIN 1 or more Negation of the IN comparison keyword 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. 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.
- 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.
- 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.
Attribute values of all other types fail the condition.
- 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.
TRANGE 2 The condition is satisfied if:
Attribute values of all other types fail the condition.
- 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.
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. NOTDEFINED 0 Negation of the DEFINED comparison keyword 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.NOTSUBSTR 1 or more Negation of the SUBSTR comparison keyword REGEX#1 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.
For details on regular expressions, see F. Syntax of Regular Expressions.WITHIN#2 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).
- 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.
#1: REGEX is a comparison keyword introduced in version 06-71. If you use a file containing a REGEX definition in a version of JP1/Base other than version 06-71 or later, the REGEX part is ignored. Even when you specify machine-type-dependent characters as a regular expression, they are handled as an ordinary character string.
#2: WITHIN is a comparison keyword introduced in JP1/Base Version 07-00. You can specify this keyword in a filter file used for the jevexport command. If you define WITHIN with a command other than the jevexport command provided by JP1/Base 07-00 and later versions, the definition of WITHIN is handled as an error, resulting in the same operation as with versions 06-71 and earlier.
Examples of event filter settings
The following examples show how to set an event filter.
- Example 1: 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- Example 2: Select JP1 events whose source user ID is 103.
B.USERID IN 103 or B.USERID RANGE 103 103- Example 3: Select JP1 events whose source event server names are reysol.
B.SOURCESERVER IN reysol- Example 4: Select JP1 events that issued messages beginning with KAJP or KAVA.
B.MESSAGE BEGIN KAJP KAVA- Example 5: 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- Example 6: 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- Example 7: 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- Example 8: Select JP1 events that have extended attributes with the attribute name TASK_NAME (the attribute value is irrelevant).
E.TASK_NAME DEFINED- Example 9: Select JP1 events that occurred on or after June 16, 2002#.
B.TIME TRANGE 20020616000000 99999999999999- Example 10: 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- Example 11: 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 20030716013000 20030716010000)- Example 12: 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)- Example 13: 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)- Example 14: 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#: Based on the time in the event server environment
All Rights Reserved. Copyright (C) 2009, Hitachi, Ltd.