Beruflich Dokumente
Kultur Dokumente
Supporting
BMC Event and Impact Management 2.0 BMC ProactiveNet Performance Manager 8.0
November 2009
www.bmc.com
Copyright 2005-2009 BMC Software, Inc. BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. AIX and IBM are registered trademarks of International Business Machines Corporation in the United States, other countries, or both. ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office, and is used here by BMC Software, Inc., under license from and with the permission of OGC. Linux is the registered trademark of Linus Torvalds. Oracle is a registered trademark of Oracle Corporation. Sun, Java, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc., in the U.S. and several other countries. UNIX is the registered trademark of The Open Group in the US and other countries. The information included in this documentation is the proprietary and confidential information of BMC Software, Inc., its affiliates, or licensors. Your use of this information is subject to the terms and conditions of the applicable End User License agreement for the product and to the proprietary and restricted rights notices included in the product documentation.
Customer support
You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or e-mail. To expedite your inquiry, see Before contacting BMC.
Support website
You can obtain technical support from BMC 24 hours a day, 7 days a week at http://www.bmc.com/support. From this website, you can
I I I I I I I I
read overviews about support services and programs that BMC offers find the most current information about BMC products search a database for issues similar to yours and possible solutions order or download product documentation download products and maintenance report an issue or ask a question subscribe to receive proactive e-mail alerts when new product notices are released find worldwide BMC support center locations and contact information, including e-mail addresses, fax numbers, and telephone numbers
product information product name product version (release number) license number and password (trial or permanent)
operating system and environment information machine type operating system type, version, and service pack or other maintenance level such as PUT or PTF system hardware configuration serial numbers related software (database, application, and communication) including type, version, and service pack or maintenance level
I I I
sequence of events leading to the issue commands and options that you used messages received (and the time and date that you received them) product error messages messages from the operating system, such as file system full messages from related software
Contents
Chapter 1 Working with the Knowledge Base 19 20 20 20 21 24 24 25 25 25 26 26 27 27 30 30 32 33 33 33 33 34 34 41 43 43 45 46 46 46 47 48 49 50 50 51 52 55
5
What is a Knowledge Base? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How a KB is created. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components of a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Knowledge Base directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Knowledge Base index files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integrating a unified KB with pre-7.2 cell definitions . . . . . . . . . . . . . . . . . . . . . . . Creating a new production or test Knowledge Basemcrtcell . . . . . . . . . . . . . . . Importing Knowledge Base information into a cellmkb . . . . . . . . . . . . . . . . . . . Compiling a Knowledge Basemccomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading a Knowledge Base into a running cellmcontrol . . . . . . . . . . . . . . . . . . Implementing changes to a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Versioning a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event classification and formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How event classes are structured . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the Knowledge Base classifies incoming events . . . . . . . . . . . . . . . . . . . . . . . Event processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event management policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How an event management policy differs from a rule . . . . . . . . . . . . . . . . . . . . . . When to use an event management policy rather than a rule . . . . . . . . . . . . . . . . How events are processed using rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MetaCollectors (only available for BMC Impact Solutions) . . . . . . . . . . . . . . . . . . Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Defining classes to manage events
BAROC language syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BAROC language symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use of quotation marks in the BAROC language . . . . . . . . . . . . . . . . . . . . . . . . . . . Class definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Metaclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Slot data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Universal event and data identifier slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Slot facets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Internal enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class instance definition syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Class definition examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Global record definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Global record definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Loading and compiling BAROC modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Chapter 3 Event and data classes 59
Knowledge Base class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Event class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 CORE_EVENT base event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 EVENT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 MC_CELL_CONTROL event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 PPM_EV event class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Data class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 CORE_DATA base class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 MC_SM_DATA data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 MC_CALENDARING data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 BEM_MATCH_TABLE data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 POLICY data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 SELECTOR data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Cell information class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Deprecated slots and their replacements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Chapter 4 Master Rule Language (MRL) reference 81
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Integer data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Enumeration data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Condition operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Condition operators to test ordering conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Condition operators to test range conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Condition operators to test match conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Condition operators to test conditions on IP addresses . . . . . . . . . . . . . . . . . . . . . . 94 Condition operators to test class hierarchy conditions . . . . . . . . . . . . . . . . . . . . . . 97 Expression operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 MRL functions and primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Primitives and functions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Action-related primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Value type conversion primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Mathematical functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Enumeration operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 String manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Time stamp functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 List operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Match table lookup primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Object slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 Specific slot manipulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Object relation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6 BMC Knowledge Base Development Reference Guide
Operation environment inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service model inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . License key functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Time frame operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object creation and deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specific rule-based functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 5 Event rules
193 197 200 202 204 218 220 225 226 226 226 226 227 230 230 233 235 236 237 239 241 242 243 244 245 246 247 248 249 249 249 252 253 253 255 255 257 259 259 260 261 261 262 263 263 264
7
Rules and event management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rule structure and syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MRL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MRL conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MRL event selection clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using_policy clause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unless clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Body clause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic data in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global records in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Interfaces in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Interface instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Indexes in rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compiling rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tracing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring rule tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing rule trace message headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Undefined events, processing errors, and deprecated slots . . . . . . . . . . . . . . . . . . . . Undefined events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event processing errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using deprecated slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 6 Event rule types and syntax
Refine rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refine rule processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refine rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refine rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refine rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rule processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Filter rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Regulate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Regulate rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Forms of the Regulate rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Regulate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 Regulate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 Regulate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 New rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 New rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 New rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 New rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Abstract rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 Abstract rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 Abstract rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 Correlate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Correlate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Correlate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 Correlate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 Execute rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Execute rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Threshold rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Threshold rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Threshold rule examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Propagate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 Propagate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 Propagate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Propagate rules examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Timer rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Timer rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Timer rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Timer rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Timer rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Delete rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Delete rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Delete rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Delete rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Chapter 7 Working with collectors 297
Creating or modifying a collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 Collector syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 Best practices for defining collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 Collector security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 Defining static collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 Defining dynamic collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
8 BMC Knowledge Base Development Reference Guide
Default event management collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . self_collector.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . catchall_collector.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_bystatus_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_bylocation_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MCxP collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bii4p_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_evr_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default service impact management event collector . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 8 Policy and selector syntax
306 306 306 307 307 308 308 309 309 311 312 313 314 314 314 317 317 319 320 320 322 322 323 323 323 324 324 324 324 328 331 335 339 341
Event policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format of event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . How a rule for a policy type is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 9 Common Event Model
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Versioning support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Internationalization compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping quick reference: CEM to BAROC (CORE_EVENT). . . . . . . . . . . . . . . . Guidelines for applying CEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Associating events with configuration items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Root cause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding attributes vs. adding generic slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cross-launching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Free-format text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM property groupings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reporter component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Situation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Metric properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index
Contents
10
Figures
Knowledge Base directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Output from mgetinfo kbsources argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Event processing rule phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Enumeration definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Class hierarchy definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Superclass definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Subclass definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Data class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Interface class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 CORE_EVENT class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 CORE_DATA class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Permitted integer combinations in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Event selection criteria example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 when condition triggered by any change to a specified slot . . . . . . . . . . . . . . . . . . . 237 when condition triggered by a specific change to a specified slot . . . . . . . . . . . . . . . 238 when condition triggered by a specific change to a specified slot . . . . . . . . . . . . . . . 238 Rule containing a when clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 Sample data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 Execute rule using dynamic data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Interface instance example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Refine rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 Refine rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 Refine rule ECF syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 Refine rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 Filter rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Filter rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Event condition formula in a filter rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Filter rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Regulate rule syntax form 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 Regulate rule syntax Form 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 Regulate rule syntax to send a custom event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 Regulate rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 regulate rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Regulate rule example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Regulate rule example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 Abstract rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 Abstract rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Figures 11
Correlate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Correlate rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 Correlate rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 When clause in an Execute rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 Execute rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Execute rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Threshold rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Propagate rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Timer rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Timer rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Timer rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Delete rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Delete rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Collector definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 Collector tree definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Static collector example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 Static collector example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 Self collector definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 Catchall collector definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 MC_SMC_EVENTS collector definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 Policy class syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 Policy entry syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 Policy in a rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 Selector class syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 Selector entry syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
12
Tables
Knowledge Base subdirectories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Knowledge Base file extensions and directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cell rule phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BAROC syntax symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Core and metaclass event and data classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Slot facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_EVENT_CATEGORY event categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Knowledge Base class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CORE_EVENT base class slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CELL_CONTROL slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PPM_EV slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ABNORMALITY slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ALARM slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CORE_DATA slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BEM_MATCH_TABLE class attribute (slot) definitions . . . . . . . . . . . . . . . . . . . . . . . . POLICY slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SELECTOR slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CELL_INFO slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deprecated slot substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ==/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . !=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . </2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . <=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . >/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . >=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . between/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . within/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . outside/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . contains/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . contained_in/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . contains_one_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . has_prefix/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . has_suffix/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . matches/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ip_smaller_or_equals/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ip_greater_or_equals/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ip_matches/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ip_matched_by/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tables
22 23 35 46 49 51 53 60 63 69 70 70 71 73 74 77 77 78 79 82 83 85 86 86 87 87 88 88 89 89 90 91 91 92 92 93 94 95 96 97
13
superclass_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 subclass_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Alphabetical list of primitives and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 action_requestor/1 syntax argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 action_requestor/2 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 action_requestor/3 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 action_return/2 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 admin_execute/5 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 admin_execute/5 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 perform/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 perform/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 execute/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 confirm_external/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 get_external/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 inttostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 int_to_hex/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 int_to_hex/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 realtostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 pointertostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 string/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 stringtoint/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 stringtoreal/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 stringtopointer/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 int/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 trunc/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 round/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 real/2 or float/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 code/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 char/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 max/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 min/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 sign/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 abs/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 sqrt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 exp/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 pow/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 log/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 log10/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 sin/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 cos/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 tan/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 asin/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 acos/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 atan/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 atan2/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 gcd/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 random/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 incr/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 incr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
14
incr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . incr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . incr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . incr/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decr/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decr2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decr/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . concat/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strlen/2 and len/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tolowercase/2 and lower/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . touppercase/2 and upper/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strpart/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strnpart/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strextract/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . substring/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . substring/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strip/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strip/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Possible values for the $POS argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strip/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Possible values for the $POS argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strtolist/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strmatch/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . match_regex/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . match_regex/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . match_regex/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sprintf/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mapslots/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mapslots/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . has_substring/2 syntax argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . has_substring/3 syntax argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_stamp/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_stamp_to_cim/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_stamp_to_str/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_stamp_to_str/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_extract/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . str_to_time_stamp/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listlen/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listgetelt/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listmember/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listdelete/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listappend/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listdisjoint/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listintersect/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listunion/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listsubtract/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
137 137 138 138 139 140 140 141 142 142 143 143 144 145 146 146 147 148 148 149 149 150 150 151 152 152 154 155 157 158 158 159 160 161 162 162 163 164 164 166 167 167 168 169 169 170 170 171 172
Tables
15
listremdup/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 listwalk/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 add_to_list/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 rem_from_list/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 find_match/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 find_match_entry/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 apply_match_entry/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 get_list_slotvalues/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 set_list_slotvalues/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 class_path/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 reset_default/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 ntadd/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 ntcnt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 ntget/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 ntset/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 opadd/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 opadd/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 opcnt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 opget/7 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 opget/6 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 opget_time/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 opget_author/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 opget_action/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 opget_args/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 opset/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 opset/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 relate/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 unrelate/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 cellinfo/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 cellcontrol/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 kbversion/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 kbversion/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 get_env/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 send_to/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 send_to/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 send_to_ext/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 propagated_to/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 smcomps/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 key_version/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 key_verify/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 key_verify/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 tf_active/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 tf_active/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 tf_udid_active/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 tf_udid_active/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 tf_current_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 tf_current_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 tf_current_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 tf_current_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
16
tf_current_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_current_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_prev_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_prev_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_prev_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_prev_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_prev_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_prev_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_next_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_prev_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_next_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_next_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_next_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_next_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_duration/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_duration/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . generate_event/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . new_data/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remove_data/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_timer/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_timer_at/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_timer_at/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conditions for the using clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CELL_PARSE_ERROR slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CELL_UNDEFINED_CLASS slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CELL_PROCESS_ERROR slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rule syntax descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . f1 and f2 Filter rules event processing examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlate rule event examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Available environment variables in Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC Impact Manager standard roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . By Status collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . By Location collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Collectors included in the MCxP collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Property groupings: BMC_BaseEvent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM to BAROC: Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM to BAROC: source information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM to BAROC: reporter information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM to BAROC: situation information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM to BAROC: metric information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EventInformation::EventToCIAssociationType parameter values . . . . . . . . . . . . . . ReportTime (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EventModelVersion (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EventClass (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EventId (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Status (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timeout (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
209 209 210 211 211 212 212 213 214 214 215 215 216 216 217 217 218 219 220 222 223 223 228 234 254 254 255 264 265 282 284 301 307 307 308 319 319 320 320 321 321 321 323 324 325 325 325 325 326
Tables
17
Notes (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 EventToCIAssociationType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 PropagationHistory (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 RelationSource (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 Owner (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 Account (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 ResourceId (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 ReconciliationIdentity (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 Alias (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 ComponentHost (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 ComponentHostAddress (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 Location (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 ComponentURI (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 ComponentCaption (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 ComponentType (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 ComponentOwner (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 Slots for event monitoring information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 ResourceId (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 ComponentHostAddress (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 ComponentURI (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 ComponentCaption (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 ComponentType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 EventTime (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 EventType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 EventId (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 EventSeverity (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 EventSuggestion (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 SituationCategory (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Situation category (mc_event_category) values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 SituationTime (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 Priority (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 Severity (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 Message (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 Application (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 LongMessage (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 RepeatCount (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 MetricName (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 MetricValue (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 MetricValueUnit (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 MetricThreshold (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
18
Chapter
1
20 20 20 21 24 24 25 25 25 26 26 27 27 30 30 32 33 33 33 33 34 34 41 43 43
Chapter 1
19
How a KB is created
During installation, a KB that serves as a template for all cell KBs is created for the cell. This KB provides the cell with the data definitions, data instances, collector definitions, and rules for a fully functional environment in which to process events and service components. If you modify the template KB, any cell that you install or create will include those modifications. When you create or install a new cell using the mcrtcell command, you always create or install a KB in the newly-created cells KB directory path: MCELL_HOME/etc/CellName/kb. Modifications to the KB in the CellName/kb directory apply to the CellName cell only.
event classes define the types of events to accept and classify source event data for processing data classes define the classes and slots of dynamic data instances and service model component instances. dynamic data function as contextual variables that can provide data values to rules and policies during event processing.
20
global records are persistent structured global variables that maintain data values across all phases of event processing. event management rules are event processing statements that use the BAROC data associated with an event, data instances or records to determine if, when, and how to respond to new events or event modifications. event management policies are one of several generic rule types that perform actions against events that meet selection criteria specified in an associated event selector. An event management policy selects the events that you want to process, defines the processes needed to manage those events, and schedules when the events are processed.
event collectors are filters that query the event repository and display the results in an event list in an organized manner. action executables are executable programs or scripts that perform an automated task on a particular event.
The Knowledge Base used by the cell during runtime is located in %MCELL_HOME%\etc\CellName\kb on Windows platforms and in $MCELL_HOME/etc/CellName/kb on UNIX platforms. The template Knowledge Base resides in the %MCELL_HOME%\etc\default \standard or $MCELL_HOME/etc/default/standard directory.
Cells are created during installation of a cell or by using the mcrtcell command. For information about this command, see the Administration Guide.
NOTE
The environment variables created during installation that define paths to cell configuration files and executables are listed in the Installation Guide.
Chapter 1
21
In the Knowledge Base, each subdirectory is labeled to indicate the type of files or programs it stores, as listed in Table 1 on page 22. Table 1 Knowledge Base subdirectories (part 1 of 2)
Knowledge Base subdirectory Description bin stores the external scripts that can execute during rule processing and actions The bin directory organizes the scripts and programs in subdirectories specific to the appropriate operating system, as follows:
I I I I I I
The .load file in the bin directory specifies the order in which external scripts or programs are presented to clients. Actions are defined in .mrl files. There is one default file, .load, in the bin directory. classes stores event class, data class, and interface definitions Classes are stored in .baroc files. The .load file in the classes directory specifies the order in which classes are loaded. Parent classes must be loaded prior to child classes. Event and data classes are described in Chapter 3, Event and data classes.
22
Table 1
Knowledge Base subdirectory Description collectors stores collector rule definitions Collector definitions are used to organize the event lists that are viewed in the console. Collector rules are defined in .mrl files. Collectors and their syntax are described in Chapter 7, Working with collectors. data instances of dynamic data stored in files that are loaded when the cell is initialized Dynamic data instances are stored in .baroc files. The .load file indicates the order in which the files are loaded into the cell. After the values are loaded into the cell any changes are maintained in the mcell.db. Dynamic data objects and their syntax are described in Chapter 5, Event rules. lib stores primitives and functions used in the Knowledge Base For example, the Knowledge Base contains the following files that cannot be modified:
I I
sim.wiccontains the compiled implementation of primitives and functions that are loaded by the cell at startup sim_decl.wiccontains the compiled definitions for primitives and functions; it is loaded by the compiler to compile rules that reference SIM primitives
For more information about functions and primitives, see Chapter 4, Master Rule Language (MRL) reference. records stores global record definitions, which store dynamic information across all rule phases A global record stores persistent dynamic information in a .baroc file. Many rule processing phases use global records for retrieving dynamic information. The .load file indicates the order in which the files are loaded into the cell. The default copy of record definitions is stored in baroc files in the records directory. After the values are loaded they are maintained in the mcell.db. Dynamic data objects and their syntax are described in Chapter 5, Event rules. rules stores the rule definitions for the Knowledge Base The source for rule definitions are the files with an .mrl extension. The compiled versions of rules are contained in files with the .wic or .pkg extension. The .load file indicates the order in which the rules are loaded into the cell. Rules and their syntax are described in Chapter 5, Event rules.
Table 2 lists the file extensions and directory location for the each of the components contained in a KB. Table 2
Component event classes data classes data instances
Chapter 1
23
Table 2
Component
global records rules collectors action executables service model class definitions interface classes scripts and programs
manifest.kbserves as an index file for the listed directories that compose the Knowledge Base during compilation. This file is located in %MCELL_HOME%\etc\CellName\kb on Windows platforms and in $MCELL_HOME/etc/CellName/kb on UNIX platforms. .loadserves as an index file for the individual files contained in the
corresponding subdirectory of the Knowledge Base directory structure. Load files are included in each subdirectory to determine load order for that particular directory. Files types within the .load file do not have extensions.
I
.loadwicBefore the compilation of the Knowledge Base, rules and collectors are created in .mrl files and are included in the .load files. After compilation, rule and collector files are stored in .wic files and a .loadwic file is created for the KB to use. The .wic files are machine-readable only.
24
NOTE
To protect the format of the default Knowledge Base, back it up prior to making any modifications. An adequate backup includes all directories and files in the kb directory or the directory where the changes occur. You can also use source-control programs such as CVS or Subversion to keep track of changes to the KB. Source control allows you to revert to older versions of the KB and to examine changes.
1 Create a new cell using the mcrtcell CLI with either the -ae or -as option. 2 Copy the modifications or extensions youve made in old cells KB to the new cells
KB. To do so, you can manually edit the files or use your specific utilities.
Chapter 1
25
NOTE
To use the mkb command to manipulate an existing KB, you must use the -f parameter to define the path to the manifest.kb file and specify the action that the mkb command should execute.
NOTE
The TraceRuleLevel parameter in the mcell.conf file must be set to 2 for rules tracing to occur.
26
KB source files For each KB source file that you specify, information about the source file is provided and the version of the compiler that was used to compile it. Logical KB modulesVersion information is provided for each logical module that you identify in the KB.
A logical KB module is a collection of class definitions and rules that perform a specific task within the KB. For instance, all class definitions and rules that are related to Help Desk events could be called the HelpDesk KB module. A single KB can contain multiple such logical modules. The class definitions and rules that are not associated to a specific KB module are considered to be part of the global, unnamed KB module. If desired, you can make rules behave differently depending on the version of specific KB modules. This can be useful in patches, for example.
Enabling KB versioning
To enable versioning, you must create logical modules in the KB. To identify the files for a particular module, add the @kbversion annotation to the KB source files, using the following syntax:
@kbversion( [ ModuleName , ] VersionID )
Variable ModuleName
Description specifies the name of the module to which the current file belongs To indicate version information for the global module, either use the empty string as ModuleName or omit ModuleName.
VersionID
Chapter 1
27
WARNING
Multiple @kbversion annotations for the same module will result in a compilation error. This also applies to a global version; only one annotation without a module name is allowed in a KB.
The mccomp command compiles the @kbversion annotations into the KB object files and includes the following information about each source file in the KB:
I I I I I I
release number of the compiler used to compile the file build number of the compiler used to compile the file build date of the compiler used to compile the file source file name source file size in bytes source file checksum
KB versioning example
@kbversion( HelpDesk , '1.2.01' )
This example specifies that the KB contains a logical module called HelpDesk, and that its version is 1.2.01.
Returned results list of KB modules with version information list of KB source files with compiler version information
28
The information is displayed in raw format. You can use the -v switch to obtain the information in a more readable format. Figure 2 shows a portion of the information returned from the kbsources argument. Figure 2 Output from mgetinfo kbsources argument
Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 268 3028595382 collectors/self_collector.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 848 2351849679 collectors/pom_activeevents_collectors.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 1298 1572060265 collectors/pom_intelligentevents_collectors.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 2276 3736979305 collectors/catchall_collector.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 882 4217293348 collectors/pom_byuser_collectors.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 5411 3623989645 collectors/ibrsd_collectors.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 143 4015122127 rules/kbversem.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 145 3230031018 rules/kbverssim.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 455 3870777253 rules/mc_startup.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 1348 4183429197 rules/refine_multiple_server_events.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 35175 1041057786 rules/im_internal.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 3009 1294038250 rules/mc_intevt.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 2364 3554485946 rules/impact_admin_server.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 2595 287947525 rules/ips.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 1896 51731806 rules/mc_sm_start.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 3885 2912043582 rules/mc_sm_associate.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 11587 1724466729 rules/mc_ci_policies.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 2126 3683660578 rules/mc_sm_maintenance.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 957 4072896080 rules/mc_sm_elect.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 1865 2174473777 rules/mc_sm_attach.mrl Compiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 3885 3336615242 rules/mc_sm_shadow.mrl
the BMC Atrium CMDB (Configuration Management Database) Common Data Model (CDM) Service class definitions used in a cells service model the service model for the cell, published by a BMC Impact Publishing Server
Chapter 1
29
30
The following shows the same example with some of the slots defined for these classes:
Class: CORE_EVENT - Flags: p Slot: mc_client_address - Type: STRING - Flags: rkpdh - Def: Class: EVENT Class: MC_ADAPTER_BASE Class: WIN_EVENTLOG Slot: mc_tool_class - Type: STRING - Flags: rkPDh - Def: WINEventLog Class: WIN_EL_APPLICATION Slot: mc_tool - Type: STRING - Flags: rkPdh - Def: Application Class: WIN_EL_SECURITY Slot: mc_tool - Type: STRING - Flags: rkPdh - Def: Security Class: WIN_EL_SYSTEM Slot: mc_tool - Type: STRING - Flags: rkPdh - Def: System
In this example, a WIN_EL_APPLICATION event defines mc_tool as Application. Because WIN_EL_APPLICATION is a sub-class of WIN_EVENTLOG, it inherits the mc_tool_class slot definition of WINEventLog. WIN_EL_APPLICATION also inherits mc_client_address from the CORE_EVENT class. mc_client_address contains the network address of the host of the adapter that sent the event. By comparison, a WIN_EL_SECURITY event defines mc_tool as Security; however, it inherits the same values for mc_tool_class and mc_client_address as a WIN_EL_APPLICATION event. Event classes and their syntax are described in Chapter 3, Event and data classes.
Class inheritance
BAROC class definitions are organized in a hierarchical system where existing classes (superclasses) can be assigned subclasses so that the subclasses automatically inherit definitions from these superclasses. This behavior is called inheritance. While a subclass inherits all the slot definitions of the superclass, it can also contain additional new slot definitions of its own, and even slot definitions that override a superclass slot definition. However, when a subclass slot overrides a superclass slot definition, it cannot have a different data type from the inherited slot, only different facet values. Also, a rule defined for a class applies to all instances of its subclasses. For example, a rule defined for the base event class, EVENT, applies to all events because all event classes are subclasses of EVENT.
Chapter 1
31
In summary, subclasses
I I I I I
inherit slots from superclasses inherit rules from superclasses can have their own slots can override superclass slots (but must contain the same data type) can be a subclass of only one class
If the event does not match any of the predefined events in the KB at all, an internal event in the form of an error message is generated and the event is stored as an MC_CELL_UNDEFINED_CLASS event with a MINOR severity and a slot, class_name, containing the original, incorrect event class. If the event is of a class that matches one of the predefined event classes, but contains undefined event slot(s), the event is generated and continues to processing, but incorrect slot name(s) are stored in the mc_bad_slot_names slot and the corresponding value(s) are stored in the mc_bad_slot_values slot. If the event has slot(s) that contain value(s) that cannot be interpreted (for example, alphabetical string data in an integer slot), the default slot value(s) are used, the incorrect slot name(s) are stored in the mc_bad_slot_names slot, and the value(s) of the incorrect slot(s) are stored in the mc_bad_slot_values slot. If an event cannot be parsed, an internal MC_CELL_PARSE_ERROR event is created containing the text for that event stored in the event_text slot. The MC_CELL_PARSE_ERROR event also uses error_line, error_column and error_messages slots to indicate the position in text where the error occurs and the parsing error message. The MC_CELL_PARSE_ERROR event has a default severity of MINOR.
Interface classes
Interface classes are used to interface with external programs. They define the format of data that comes from the external source, allowing the external information to be used in a rule. The external program returns an INTERFACE instance that it writes to the rule that called the external program.
32 BMC Knowledge Base Development Reference Guide
Event processing
Event processing
Once events are collected and formatted, they are processed by the cell rules engine. You can control how incoming events are processed using either rules or event management policies.
Rules
Rules are processing statements that determine and control the behavior of cells. A rule determines if and how events are processed. Rules consist of a set of statements that evaluate whether or not an event is processed. If the event is to be processed the rule can include an event management function or action to perform, such as discarding the event, enriching the event data, automatically escalating an event, or automatically executing an action on the event. You write rules using the Master Rule Language (MRL). Rules are compiled and stored in the cells KB. Rules and rule syntax are described in Chapter 5, Event rules.
However, unlike rules, an event management policy is easily defined interactively through the console rather than being manually written in MRL uses an event selector by which you specify the criteria used to select events for processing by the policy. The event selector allows you to specify a number of events that meet selection criteria. This gives the event policy greater flexibility than a rule. does not require compilation because it is implemented using predefined data classes and precompiled rules.
34
Figure 3
An event can be discarded during any one of these phases before being added to the repository.
New
Abstract
The New, Abstract, Correlate, and Execute rule phases can trigger a Timer rule.
Correlate Execute
10
Timer
Repository
8
Threshold Propagate
to other cells
9 8
11
Delete
Table 3
1 Refine 2 Filter
2 Regulate
4 New
determines which events in the event repository should be updated with new information from new incoming events During this phase:
I I
actions are triggered that must be performed just before a new event comes in previously received events are updated, and the new event optionally may be dropped
Note: This is the last opportunity to prevent an event from entering the event repository.
Chapter 1
35
Table 3
6 Correlate 7 Execute
determines whether any events have a cause-and-effect relationship specifies actions to perform when a slot of a new event matches a condition, or a slot of an old event is modified to satisfy a condition
8 Threshold specifies the actions that must be performed when a certain number of duplicate events have been received over a certain time period 9 Propagate determines whether an event is forwarded to another cell or integration product 10 Timer specifies actions to be executed when a timer has expired. A timer can be set in the New, Abstract, Correlate, Execute, Threshold and Delete phases. 11 Delete triggers actions to ensure that data integrity is maintained when an event is deleted from the event repository during the cleanup process
a new incoming event a timer expiration (by timer rule unless it is part of a regulate rule) end of a process called by the get_external or confirm_external primitive cleanup modification of a slot by a client (such as the console, or the mposter or msetmsg CLIs) or the propagation of this modification from another cell
When each of these transactions occur, all applicable rules are executed in the order of the phases (as shown in Figure 3 on page 35), then in order of definition inside each phase. Starting at the New phase:
I
every slot modification to the current event or other existing events are logged in a first-in, first-out queue abstraction events created by the abstraction rules are stored in another queue internal events generated by the generate_event() primitive are put in another firstin, first-out queue
36
When all the rules have been evaluated the queue slot modifications are processed (triggering the when parts of the rules). During this processing, slot modifications and internal events continue to be added to the queues. When the slot modification queue is empty, the abstraction events are processed starting directly at the new phase. When all abstraction events have been processed, the internal event queue is processed. When all internal events have been processed, the processing continues with the next transaction in the main loop.
NOTE
The Refine phase and the Regulate phase are the only phases in which the evaluation process may be suspended. In all other phases, the event is processed sequentially through all the rules of all phases.
Chapter 1
37
Correlate rules can be used to build an effect-to-cause relationship between an event that occurs as a result of another event, such as relating certain APP_DOWN events to certain APP_MISSING_PROCESSES events. Execute rules can be used to perform specified actions when a slot value has changed in the repository. Threshold rules can be used to count the number of events that matches the criteria you specify; if the number of these events exceeds the amount allowed within a time frame the Threshold rule executes. Propagate rules forward events to other cells; such as, escalation of an event from a lower-level cell to a higher-level cell.
modify the contents of a slot in an event monitor the returning remote actions perform cleanup by removing old event data apply a time window for a Regulate rule
Maintaining rules
You can use dynamic data and global records to make it easier to maintain and manage rules.
38
Dynamic data
Dynamic data is similar to a small database within the cell. Dynamic data function as contextual variables that can provide data values to rules and policies during event processing. By using dynamic data, you can create generic event management rules and policies that apply broadly. This greatly simplifies the creation and maintenance of the event management rules. For example, without using dynamic data, if you want to change the severity of an event based on the host name of a device, you must create a rule for each host name. Using dynamic data, you can define the host names and corresponding severity as data instances and reference them from one generic rule, rather than writing one rule for each possible host name. To define a dynamic data instance, you must first define a new data class. You can use the Dynamic Data Editor to define data class instances for use in event management rules or service models. As new hosts are added to the environment, you can add new data instances dynamically through the using the CLI or an API, or through event management rules themselves. You do not need to recompile event management rules to use new data instances. Dynamic data is stored in the event repository and updated whenever the context changes while the cell is running. For more information about dynamic data, data classes, and the Dynamic Data Editor, see the Administration Guide.
Global records
Global records are persistent, structured global variables that maintain data values across all phases of event processing. Their scope is the entire Knowledge Base; any other type of variable has a scope limited to the current rule. Global records are addressed by name. You can use global records to share information between events during event processing.
Chapter 1
39
is used in a rule in im_internal.mrl to set a default value to the location slot of the following event:
... if ($EM_KB_OPTIONS.default_location != "") then { $EV.mc_location = $EM_KB_OPTIONS.default_location; } ...
For more information about global records, see Global record definition syntax on
page 58.
40
Event collectors
Event collectors
You can use event collectors to organize events in meaningful groups for display in an event list and to show event relationships. An event collector consists of a filter that queries the event repository and displays the results in an event list in the console. Each cell has default collectors for the console and collectors that you create. In the collector definition, you specify the user groups that can access a collector.
Chapter 1
41
Event collectors
For an event to be displayed in an event collector, you specify criteria that an event must match and specify which user groups can view a collector and the events within a collector. You define collectors using MRL and store them in the KB. Event collectors are dynamic or static. Nodes for dynamic event collectors are displayed in or removed from the navigation tree based on whether or not events are present that meet the criteria specified by the collectors. Nodes for static event collectors remain in the navigation tree whether events for that collector are present or not. The color of the node reflects the highest level of severity in the event list. Events can appear in multiple collector trees in the console, but not in multiple collectors within a single collector tree. Because collectors are defined in the cells Knowledge Base, they appear in any console that displays that cell. The cell provides default event collectorsPATROL, All Events, By Location, By Statusfor the console.
42
A MetaCollector is a grouping of collectors. You can create MetaCollectors to view events from several event lists. Each event list is shown as a tab in the event list pane. The MetaCollector node represents the state of the combined events. MetaCollectors are often used to view collectors from multiple cells in the network.
NOTE
An incoming event that changes slot conditions can move from one collector to another within a cell.
Actions
Actions are a series of commands executed on an event or data instance that are used to diagnose and remedy problems. Actions are implemented as a piece of MRL code similar to a rule or implemented in an external program. Actions can be defined in the Knowledge Base of a cell. These actions usually are launched by a user in the console but can also be triggered by rules. In both cases, the action runs in the cells environment. The action definition can prompt the user performing the action for arguments. Arguments can be passed to an action by rules or through user input in the console interface. An executable associated with an action can be a script or binary. The executable is run on the OS platform on which the cell is running. Actions can be made available to a specific user, group and with specific values assigned to event slots. Actions defined in a cell are remote actions. Remote actions are executed remotely by the cell from the console. A remote action that is implemented as an external program is called an external action. A remote action implemented as a piece of MRL code is called an internal action. For more information about defining remote actions, see the Administration Guide.
Chapter 1
43
Actions
44
Chapter
2
46 46 46 47 48 49 50 50 51 52 55 56 58 58 58
Chapter 2
45
The BAROC language is not sensitive to the number of space, tab, and line break characters except those inside quoted strings. In all class definitions, a trailing semicolon (;) is required after the last curly brace (}). This is unique to class definitions. The END keyword must be followed by new line. You can add comments to a BAROC file. A comment line begins with the pound symbol (# ).
Symbol name
NOTE
All other symbols are tokens of the language.
46
STRINGString values need to be quoted only when the value starts with a single quote ( ' ) or with a double quote ( " ). You do not need to quote a STRING value
LIST_OF_STRINGString list items need to be quoted only when the value starts
with a single quote ( ' ) or with a double quote ( " ). Quotation marks must be used if the list includes a comma ( , ) or a bracket ( ] ) because these characters determine the end of string item.
Example
For the value 'this is a test', enter '''this is a test'''. The first double quote indicates that a quoted value is being entered. The first quote should be a double quotation mark because it is a quote character inside a quoted string value.
Chapter 2
47
Metaclasses
NOTE
Event class definitions must be the same in all cells. If you add custom event classes, you must manually modify the KB of each cell, recompile the KB, and then restart each cell.
Metaclasses
A metaclass is a class that defines other classes. In the cell, you cannot create, modify, or delete metaclasses. Metaclasses define the name of a tag, or a placeholder, for the class definition. The following metaclasses are defined in the mc_root_internal.baroc file:
I I I I I
NOTE
For Tivoli users: the T/EC (Tivoli Enterprise Console) metaclass definitions are built in the cell but their definition is reflected in the mc_root_internal.baroc file.
48
The syntax for defining event and data classes is essentially the same; however, their core classes and metaclasses differ: Table 5
Class type metaclass base class
For information about the default event and data class definitions, see Chapter 3, Event and data classes on page 59. Every service model component class whose instances are published from BMC Atrium CMDB are instances of MC_PUBLISH_DATA_CLASS. In publish mode, instances of this class cannot be modified by external clients (mposter command). For further information about service model component classes and service model publishing, see BMC Impact Solutions Service Modeling and Publishing Guide.
INTEGER32-bit signed value REAL64-bit real value STRINGstring, maximum 64 KB EnumNamean enumeration whose definition must appear before the slot
definition in the BAROC declaration file For further information about enumerations, see Enumerations on page 51.
NOTE
Additional slot data types INT32 and POINTER are supported for compatibility with the Tivoli TEC product.
Chapter 2
49
mc_ueid slotthe universal event identifier mc_udid slotthe universal data class identifier
mc_ueid slot
The mc_ueid slot, the cell universal event ID, uniquely identifies an event to all cells of a network. The mc_ueid slot provides a convenient way to retrieve an event in a cell hierarchy. When a cell receives a syntactically valid event with a non-empty mc_ueid slot, it determines whether a prior event has been received with that same mc_ueid. If such an event has been received, the new event is ignored. When a cell receives a syntactically valid event with an empty mc_ueid, it generates an mc_ueid of the form:
mc.cellName.<extension>
mc_udid slot
The mc_udid slot, cell universal data ID, uniquely identifies the data in the cell. If not set, the cell automatically generates an mc_udid of the form:
mc.cellName.<extension>
This slot is used to associate an event to a component. To attach an event to a component, you set the mc_smc_id attribute value of the event to the mc_udid value of the component rather than to the logical_id value used in older releases. Use this slot when importing data from an external system, such as an asset management system. By carefully selecting the mc_udid, you can identify the data in the cell that corresponds to a particular component defined in the external system.
Slot facets
Slot definitions can also have slot facets that control aspects of a class instances processing or control the values that a slot can have. For example, the dup_detect facet indicates whether the slot participates in duplicate event detection. Table 6 on page 51 lists the facets available for slot definitions.
50
Enumerations
Table 6
Facet default
Slot facets
Description value assigned to the slot if no value is received from the incoming event If no default facet is specified, zero (0) is the default for an INTEGER and a REAL, the empty string for a STRING and the empty list for a LIST_OF.
dup_detect
flag indicating whether the slot participates in the determination of duplicate events For events to be considered duplicates, they must be of the same class and all their slots whose dup_detect facet is set to yes must have equal values.
hidden parse
flag indicating whether the slot is displayed in the console flag indicating whether the slot is protected against updates by incoming events If the slot value is set by the incoming event, the cell drops the value before processing the event. Slots managed by the system usually have their parse facet set to no.
read_only
flag indicating whether the slot is protected against modification by a command or a rule A slot whose read_only facet is set to yes cannot be modified by a command or a rule. However, the system can modify this slot.
key
allows data tables to be indexed by setting the key facet to yes for one or more slots of the data class definition. Keys must be unique, and if a key is set, the rule engine prevents creation of multiple instances with the same key. When the key facet is equal to yes, it implicitly means the slot is read-only.
representation
indicator specifying how the slot should be displayed by the console For example, a possible value is date.
Enumerations
Enumerations list acceptable values for a particular slot. Enumerations must be declared and labeled in BAROC before they can be used. Figure 4 Enumeration definition syntax
Chapter 2
51
Internal enumerations
Internal enumerations
The following internal enumerations are included in the Knowledge Base:
I I I I I I
WARNING
Modifying these internal enumerations is not recommended, except to add new values. Removing built-in values or modifying their order can render the cell unable to perform its tasks.
For information about the service model enumerations included in the KB, see BMC Impact Solutions Service Modeling and Publishing Guide.
STATUS enumeration
The STATUS enumeration lists the possible status values for an event, as follows:
I I I I I
SEVERITY enumeration
The SEVERITY enumeration lists the possible severity values for an event, as follows:
I I I I I I I
52
Internal enumerations
MC_PRIORITY enumeration
The MC_PRIORITY enumeration lists the possible priority values for an event, as follows. Also, the component attribute priority uses the MC_PRIORITY enumeration values.
I I I I I
MC_EVENT_CATEGORY enumeration
The MC_EVENT_CATEGORY enumeration lists the possible categories for an event, as follows: Table 7
Category
SLA_MANAGEMENT events relating to the Service Level Agreement Management process The process covers planning, coordinating, drafting, agreeing to, monitoring and reporting on SLAs, and the on-going review of service achievements to ensure that the required and cost-justifiable service quality is maintained and gradually improved. CAPACITY_ MANAGEMENT events relating to the Capacity Management process The process is responsible for ensuring that the capacity of the IT Infrastructure matches the evolving demands of the business in the most cost-effective and timely manner. All events that report on capacity (for example, diskFull) or performance (transactions/sec) are categorized as capacity events. SERVICE_ CONTINUITY_ MANAGEMENT events relating to the Service Continuity Management process The process supports the overall Business Continuity Management process by ensuring that the required IT technical and services facilities (including computer systems, networks, applications, telecommunications, technical support and Service Desk) can be recovered within the required, and agreed upon, business timescales. events relating to the Availability Management process The process supports optimizing the capability of the IT Infrastructure, services and supporting organization to deliver a cost effective and sustained level of availability that enables the business to satisfy its business objectives. All events which report if a component is available or unavailable should be categorized as availability events.
AVAILABILITY_ MANAGEMENT
Chapter 2
53
Internal enumerations
Table 7
Category
INCIDENT_ MANAGEMENT
CONFIGURATION_ MANAGEMENT
events relating to the Configuration Management process The process identifies and defines configuration items in a system, records and reports the status of configuration items and requests for change, and verifies the completeness and correctness of configuration items.
RELEASE_ MANAGEMENT
events relating to the Release Management process The process takes a holistic view of a change to an IT service and ensures that all aspects of release, both technical and non-technical, are considered together.
PROBLEM_ MANAGEMENT
events relating to the Problem Management process The goal of this process is to minimize the adverse impact on the business of incidents and problems that are caused by errors within the IT Infrastructure, and to prevent recurrence of incidents related to these errors. To achieve this goal, Problem Management seeks to get to the root cause of incidents and then initiates actions to improve or correct the situation.
CHANGE_ MANAGEMENT
events relating to the Change Management process This process controls changes to the infrastructure or any aspect of services in a controlled manner, enabling approved changes with minimum disruption.
OPERATIONS_ MANAGEMENT
events relating to the Operational Management process The process is not only concerned with the incidents reported by users, but also with events generated by or recorded by the infrastructure.
SECURITY_ MANAGEMENT
events relating to the Security Management process This process consists of activities that are carried out by Security Management itself or by activities that are controlled by Security Management. Events related to Identity Management as well as events reporting security breaches fall into this category.
FINANCIAL_ MANAGEMENT
events relating to the Financial Management process This process accounts for IT usage by planning, controlling and recovering costs expended by providing the IT services negotiated and agreed to in the SLA.
SERVICE_DESK_ MANAGEMENT
events relating to the Service Desk Management process This process manages the Service Desk.
54
MC_EVENT_SUBCATEGORY enumeration
The MC_EVENT_SUBCATEGORY enumeration defines the sub-category for an event, as follows:
I I I I I I
10 20 30 40 50 60
MC_YESNO enumeration
The MC_YESNO enumeration is used to set a YES or NO value for a slot.
Chapter 2
55
All slots with key set to yes make up the primary key to the data class. The primary keys of all data instances must be unique. Moreover, the key is used internally to index the data table, which increases the performance of the rule engine when it searches the table. In Figure 6, the SECURITY_EVENT class inherits all of the slots of the EVENT class. Figure 6 Class hierarchy definition example
In Figure 7, the LOGIN_EVENT class inherits all the slots of SECURITY_EVENT and adds two new slots, mc_host and user. These two new slots are declared with facet dup_detect=yes. This means that two event instances are considered identical if they have the same values for these slots. Figure 7 Superclass definition example
MC_EV_CLASS :p_ LOGIN_EVENT ISA SECURITY_EVENT DEFINES { mc_host: dup_detect = yes ; user: STRING, dup_detect = yes ;
56
Figure 7
}; END
In Figure 8, the LOGIN_FAILURE class is a subclass of LOGIN_EVENT. It inherits all the slots except the severity slot, which is inherited from the base EVENT class; the default value is set to MINOR for this class. Figure 8 Subclass definition example
In Figure 9, the AppByHost data class is a table that stores a list of applications present on each host. The host slot is defined as the unique key for this table. The system will prevent the creation of two AppByHost class instances, or a subclass of AppByHost, with the same host slot value. Figure 9 Data class definition example
MC_DATA_CLASS : AppByHost ISA DATA DEFINES { host: STRING, key=yes; applications: LIST_OF STRING; }; END
In Figure 10, the location class is an interface class with a single slot, site. Figure 10 Interface class definition example
You can also define data instances in the Administration console. For information, see the Administration Guide.
Chapter 2
57
In a rule, you can refer to one of the slots, as shown in the following example:
$UNDER_MAINTENANCE.hosts
This form can be used in an expression, an assignment, or a primitive. For information about using global records in rules, see Global records in rules on page 243.
NOTE
The cell executable contains default BAROC definitions. For reference purposes, those definitions are provided in the default KB in the mc_root_internal.baroc.mrl file. Do not reference this file in the .load file.
After you modify BAROC definitions, recompile the Knowledge Base. For information about compiling the Knowledge Base, see Managing a Knowledge Base on page 24.
58
Chapter
3
60 62 63 69 69 70 72 73 73 73 74 77 77 78 78
59
NOTE
Class files with the term deprecated in their file name are files that remain in the Knowledge Base for backward compatibility purposes. By default, they are not loaded into the Knowledge Base.
Table 8
File name
apache.baroc bem_match_table.baroc
BMC Impact Integration for PATROL 7 class definitions BMC Impact Integration for SmartDBA class definitions event log class definitions the data classes used internally for event management in the event processor of a cell. These data classes are related to policies. generates events for monitoring the BMC Impact Publishing Server To enable generation of Publishing Server monitoring events, see the BMC Impact Solutions Service Modeling and Publishing Guide.
FILTER_POLICY class definition deprecated data classes provided in the default KB and supported in the service model in prior releases deprecated notification policy classes for e-mail and paging deprecated event propagation classes BMC internal event and data class definitions Note: The mc_evtdata_internal.baroc file is distributed for information purposes only. Do not load this file into a Knowledge Base.
mc_root_internal.baroc
system core data and event classes Note: The mc_root_internal.baroc file is distributed for information purposes only. Do not load this file into a Knowledge Base.
mc_root_redef.baroc
redefinition of the EVENT class This file includes classes and attributes (slots) that have been deprecated in this release and prior releases of the product.
60
Table 8
File name
mc_sm_cost.baroc mc_sm_custom.baroc
SLOT_FORMULAS class definitions SM_MAINTENANCE class definitions client notification registry classes hierarchy with BMC_Base_Element and BMC_Impact subclasses This hierarchy reflects the CMDB CDM class hierarchy.
MC_SM_PROPAGATION_POLICY class definitions defines the service management internal classes for the integration to the Remedy Service Level Management product enumeration definitions for Tivoli Enterprise Console compatibility Note: By default, the mc_tec_severity.baroc file is not loaded into the Knowledge Base.
defines the events that are generated internally by the Impact Administration Server classes that define mposter and mc-client, the adapter system, and the BMC Impact Event Adapters BMC Impact Integration for PATROL event class definitions and extensions. Note: This class file is for backward compatibility with previous BMC Impact Integration for PATROL releases.
definitions for BMC ProactiveNet event classesPPM_EV, ALARM, and ABNORMALITY BMC II for PATROL EM integration PEM_EV event class definition BMC Performance Manager integration event class definitions contains the obsolete STATE_CHANGE_EVENT class definition. Note: This class file should be loaded only if the sce_compatibility.mrl rule set is used for backward compatibility with old rules.
61
MC_CELL_CONTROL MC_CELL_START MC_CELL_STOP MC_CELL_TICK MC_CELL_STATBLD_START MC_CELL_STATBLD_STOP MC_CELL_DB_CLEANUP MC_CELL_CONNECT MC_CELL_CLIENT MC_CELL_DESTINATION_UNREACHABLE MC_CELL_HEARTBEAT_EVT MC_CELL_RESOURCES MC_CELL_ACTION_RESULT MC_CELL_PUBLISH_RESULT
62
date_reception
INTEGER timestamp as set by the source of the event represenation = date If not set by the source, on its arrival at a cell, its value is set to the value of incident_time. If there is no incident_time value, its value is set to the mc_arrival_time value. INTEGER, parse = no INTEGER parse = no LIST_OF INTEGER parse = no LIST_OF INTEGER parse = no STRING LIST OF STRING parse = no INTEGER parse = no INTEGER representation = date LIST_OF STRING parse = no elapsed time, in seconds from event creation to the time the event was closed event identifier in the local cell system reserved system reserved identifies the account associated with the event. controls write and execute access to events when read access is provided by the collector number of actions performed on the event timestamp when the event arrived at the network at either an adapter or a cell Its value is never zero (0).
mc_associations
system reserved
63
Table 9
Slot
mc_bad_slot_names
LIST_OF STRING INTEGER parse = no STRING parse = no LIST_OF STRING INTEGER representation=date LIST_OF INTEGER parse = no MC_EVENT_CATEGORY
corresponding values of the bad slots system reserved network address of the host where the adapter that sent the event is running system reserved timestamp of last modification of certain slots The slots are those mentioned in mcell.modify.
mc_effects mc_event_category
system reserved high-level normalized category of the object the event represents based on an appropriate Information Technology Infrastructure Library (ITIL) core process denotes the version (<major_version>.<minor_version>.<service_versi on>) of the event model that instantiates the event. The event model version is required for compatibility purposes. For example, 1.0.00
mc_event_model_version STRING
mc_event_relations
LIST_OF STRING a list of tuples parse=no, hidden=yes I The first element of the tuple contains the relation type. I The second element is the mc_ueid of the related event. This slot links a source event to one or more related events.
mc_event_subcategory
MC_EVENT_SUBCATEGORY subcategory of the object the event represents based on an appropriate Information Technology Infrastructure Library (ITIL) core process. Possible values are USER_TRANSACTIONS, APPLICATION, DATABASE, SYSTEM, NETWORK, and OTHER. LIST_OF STRING STRING system reserved fully-qualified name of the host on which the problem occurred
mc_history mc_host
64
Table 9
Slot
mc_host_address
mc_host_class
STRING
type of host This field is important to implementing generic actions, such as rebooting a computer on which a problem has occurred. In the background, a generic action can be translated into a specific action based on this field.
mc_incident_report_time INTEGER
date and time when the event was reported (represented as a timestamp) If there is a chain of reporters, the timestamp indicates the time when the event was reported to the first reporter.
mc_incident_time
INTEGER representation=date
timestamp corresponding to the time at which the incident causing the event occurred Its value is zero (0) if the time unknown. This timestamp can be set by an adapter or a gateway.
timestamp when the event arrived in the local component It is never zero (0).
location at which the managed object resides expands the information in msg system reserved list of free text annotations added to the event The contents of this slot is implementationdependent. Rules or users should not rely on a particular value in this slot.
indicates the status of the event with respect to the notification system over time subcomponent of the host to which the event is related For example, it could be the name of the disk on which the event is reporting the problem.
65
Table 9
Slot
mc_object_class
identifies the owner of the source component address used to cross-launch directly to the component slot containing a list of operation history entries event management systems that is closest to the source of the event as possible For example, if an event originates from an agent, is forwarded to HP OpenView IT/Operations, and is then received by the cell, the name of the agent would be the mc_origin, and the name of the HP ITO instance would be the mc_tool. If this is only a two-layer implementation, mc_origin might have the same value as mc_tool.
mc_origin_class
STRING
identifies the event management system type This slot may have the same value as the mc_tool_class slot if this is only a two-layer implementation.
mc_origin_key
STRING
unique key that the originating tool used to enumerate the event If this is only a two-layer implementation, mc_origin_key might have the same value as the mc_tool_key.
mc_origin_sev
STRING
severity as given by the mc_origin slot If this is only a two-layer implementation, mc_origin_sev might have the same value as mc_tool_sev.
mc_original_priority
MC_PRIORITY
records the original priority of the event upon insertion to the cell, which is needed to determine if an event has been escalated or deescalated records the original severity of the event to determine if the events severity has been modified current user assigned to the event
mc_original_severity
SEVERITY
mc_owner
STRING
66
Table 9
Slot
mc_propagations mc_relation_source
system reserved the mc_ueid of the source event to which this event is related This slot links a related event to its source event.
service related to the event event is attached to the SIM component with the specified identifier set to 1 if event has an impact on a SIM component prioritizes events with respect to their impact on the SIM model For every event attached to a SIM component, the mc_smc_priority slot for the event is set to the raw_impact_status of the SIM component if all of the following conditions hold true:
I
the SIM component is the root cause of an important component the event severity corresponds to the self_status of the SIM component using the BMC_SEVERITY_TO_STATUS table the self_status of the SIM component is greater than or equal its status
mc_smc_typea
STRING
value is set to the class of the SIM component to which the event is attached
67
Table 9
Slot
mc_timeout mc_tool
mc_tool_address mc_tool_class
STRING STRING
the network address of the Reporter For BMC Event Management, mc_tool_class represents a user-defined categorization of the tool reporting the event. For example, the mc_tool_class value for an SNMP adapter could be SNMP. And the mc_tool_class value for an NT Event Log Adapter might be NT_EVLOG. For BMC ProactiveNet events, mc_tool_class contains the string PNET.
unique key used by the sending tool to enumerate the event name of the adapter or integration mapping rule that generated the event severity as given by mc_tool the Reporters suggested solution to the problem posed by the event. This is similar to expert advice information that other applications provide. date and time (as a timestamp) when the event report was created. The ReportTime value must be read as using the time scale Coordinated Universal Time (UTC) unless a particular time zone or the value Z (Zulu time for UTC) is otherwise specified. the address used to cross-launch directly to the Reporter
mc_tool_time
INTEGER
mc_tool_uri
STRING
68
EVENT class
Table 9
Slot mc_ueid
text description of the event number of copies received from this event severity value of the event status value of the event
These slots are not in use for the current version of BMC ProactiveNet.
EVENT class
The EVENT class is a subclass of the CORE_EVENT base class. By default, the EVENT subclass has no slots initially defined other than the inherited ones; however, slots can be added. The EVENT class can be extended in the mc_root_redef.baroc file. (Is this true?)
NOTE
No user or application should create internal cell events. These events only should be generated by the cell.
Table 10
Slot
cell_name cell_location
69
list of the names of the groups to which the mc_object slot of the event belongs duration (in minutes) that data points have to meet the trigger condition before the event is created name of the VM host machine. Value is empty if no VM host is being used. severity value of the event
70
true alarm currently has a Predictive severity false alarm does not currently have a Predictive severity
pn_predict_to_occur_time
INTEGER
time when the a predictive alarm is predicted to occur. The value is given in UNIX format. indicates whether or not this alarm is suppressing other alarms
I
pn_is_suppressing
BOOLEAN
true this alarm is suppressing other alarms false this alarm is not suppressing other alarms
pn_predicted_severity
PREDICTED_SEVERITY
indicates the predicted severity for predictive events Possible values are: I blank (the value is empty) I MINOR I MAJOR I CRITICAL
71
SELECTOR
72
NOTE
It is possible, but not recommended, to redefine the CORE_DATA class in a Knowledge Base. Redefining the base CORE_DATA class results in a merge between the default definition and the new definition of it in the Knowledge Base.
Table 14
Slot
data_handle
mc_udid mc_creation_time
mc_modification_time
modification time
73
you to specify an action that begins at the beginning or end of an active timeframe)
I
TIME_FRAMEthe periods of time that the event policy is active TIME_ZONEthe time zone to use as a basis for time display, represented by a coordinated universal time (UTC) offset
For complete information about event policies and local timeframes, see the Administration Guide.
ref_instances_classes
LIST_OF STRING
list of classes corresponding to the class instances (objects) that will be passed as the fourth argument to the find_match primitive For more information, see BEM_MATCH_TABLE output_expressions references on page 75 below.
output_expressions
LIST_OF STRING
list of expressions to be evaluated to compute the values to be returned These expressions can reference a reference object with $i notation and can reference input_values with $Vi notation. For more information, see BEM_MATCH_TABLE output_expressions references on page 75 and BEM_MATCH_TABLE output_expressions references on page 75.
74
BEM_MATCH_TABLE processing
All instances that share the same tag value must have the same number of elements in the list values of the other slots. For example, if the first instance created has the value A in the tag attribute and there is one element in ref_instances_classes, three elements in input_match, and two elements in output_expressions, all subsequent instances with the value A in the tag attribute must have one element in ref_instances_classes, three elements in input_match, and two elements in output_expressions. There cannot be two instances with the same value in the tag slot that also have the exact same value in the input_match slot. The creation and modification of instances of these classes (or subclasses) will trigger the creation and modification of indexes in the cell. The output expressions will also be compiled. If an instance is invalid because it violates one of the above constraints or because one of the output_expressions is invalid, the creation or modification of the instance will fail.
Each fixed pattern must be enclosed in brackets. This enables you to explicitly match an asterisk character. For example, <*** >* will match strings starting with three asterisks and a space.
75
In the above example, the string tolowercase($1.msg)represents the following MRL expression:
tolowercase($1)
Although a string is a simple valid expression, BAROC requires single quotation marks around a string that contains non-alphanumeric characters, such as in tolowercase($1.msg). It is mandatory to put single quotation marks around strings that contains periods or spaces. The following is a valid expression:
'quoted.string'
When the encoded expressions in output_expressions slot are literal and contain non-alphanumeric characters, you must use double quotation marks. In the following example, the first level of quotation marks delimits the string in BAROC; the second level of quotation marks indicates the MRL expression is a literal:
output_expressions=['"quoted.string"']
76
For more information about policies, see Event policies on page 312.
For more information about selectors, see Event selectors on page 313.
77
MC_YESNO indicates that the cell is a high availability cell MC_YESNO indicates that the cell is secondary server of a high availability cell MC_YESNO indicates that cell is in standby mode
I I I I I I
78
I I I I I I I
I I I I I I I
Table 19 lists the slots that can be substituted for a deprecated slot. Table 19 Deprecated slot substitution (part 1 of 2)
Slot substitution Description mc_host HomeCell Icon Name mc_host_address OwnerName PropagationModel State StatusModel ToolTipSlots mc_object mc_location component_scope The source and sub_source deprecated slots identify the adapter or software the event originates from. The following new slots allow a better identification of the adapter or software:
I I I I
Deprecated slot description hostname home_cell icon name origin owner_name propagation_model state status_model tool_tip_slots sub_origin site scope source sub_source
79
Table 19
80
Chapter
This chapter presents the following topics: Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Integer data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Enumeration data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Condition operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Expression operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 MRL functions and primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Primitives and functions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Action-related primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Value type conversion primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Enumeration operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 String manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Time stamp functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 List operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Match table lookup primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Object slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 Specific slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Object relation functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Operation environment inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Service model inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 License key functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Time frame operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Object creation and deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Specific rule-based functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
81
Data types
Data types
Table 20 lists the types of data that can be stored by the cell. Table 20
INTEGER REAL POINTER STRING ENUM
Data types
Default value 0 0 0 (empty string) The first ordinal value that corresponds to the lowest numeric value. a whole number that does not have a fractional part numeric data in form of a decimal fraction a 32-bit value sequence of characters, words, or phrases list of values used as the range of a particular attribute type
Integer data
The rules allow you to use arithmetic operators with integer data. The following figure lists the only combinations in which pointers are permitted. Figure 13
pointer pointer pointer integer pointer pointer = = = = = =
Enumeration data
An enumeration associates constant values with names. The general format is
ENUMERATION enum_name integer_value string_value integer_value string_value ... END
WARNING
Enumeration names must be unique throughout the class and the enumeration names of the application. The name of an enumeration must not be equal to a class name.
82
Operators
Operators
There are three kinds of operators:
I I I
combination operators, used to combine conditions condition operators, used to specify a condition for expressions expression operators, used in expressions
In the following sections, the description of each operator includes the allowed type(s) of each argument. The argument type is the expected type of the result of evaluating the actual expression passed as argument. The following argument types are used:
STRING INTEGER REAL ENUM ANY LIST_OF T an expression evaluating to a value of type STRING an expression evaluating to a value of type INTEGER an expression evaluating to a value of type REAL an expression evaluating to a value of an enumeration type any simple (non-list) value a list of elements of type T
Combination operators
Combination operators allow you to combine conditions in a logical expression. The result is a logical value. Combination operators can be used in where clauses. There are three logical combination operators, NOT, AND, and OR, listed in order of evaluation: Table 21
NOT c1 c1 AND c2 c1 OR c2
If no parentheses are used, the NOT operators are evaluated first, the AND operators are evaluated second, and the OR operators are evaluated last. You can use parentheses to change this order. The expression within parentheses is evaluated first.
83
Condition operators
Parentheses are needed around the OR combination; otherwise, the AND combination would be evaluated first.
Condition operators
Condition operators take two expressions as arguments. The operator specifies a condition. When evaluated, the result is a logical value (true or false). Condition operators can be used in:
I I I
where clauses, and can be combined with logical combination operators when clauses, to exert a condition on the changed slot timer_info clauses, to exert a condition on the timer_info tag
When a condition operator is used in a where clause, the argument on the left can either be an expression or a short-cut slot reference using the form:
SlotName:
NOTE
A short-cut slot reference is equivalent to $THIS.SlotName. However, the use of this shortcut syntax is discouraged because it is less readable.
When a condition operator is used in a when operator, the argument to the left of the operator must be a slot reference. When the referenced slot changes, the when clause evaluation is triggered. When a condition operator is used in a timer_info clause, the argument to the left of the clause is the timer_info tag.
84
Table 22
Argument $EXPR1 $EXPR2
==/2 arguments
Type
I I I I
Description expression to the left of the operator expression to the right of the operator
Use ==/2 to test for the equality of two expressions $EXPR1 and $EXPR2. When comparing lists, the corresponding list elements are compared one at a time. Therefore, the lists [a,b] and [b,a] are not equal.
85
Table 23
Argument $EXPR1 $EXPR2
!=/2 arguments
Type
I I I I
Description expression to the left of the operator expression to the right of the operator
Use !=/2 to test for inequality of two expressions $EXPR1 and $EXPR2. When comparing lists, the corresponding list elements are compared one at time. Therefore, the lists [a,b] and [b,a] are not equal.
</2 - smaller_than/2 - less_than/2 determine if one value is less than another value
$EXPR1 < $EXPR2 $EXPR1 smaller_than $EXPR2 $EXPR1 less_than $EXPR2
Table 24
Argument $EXPR1 $EXPR2
</2 arguments
Type ANY ANY Description expression to the left of the operator expression to the right of the operator
Use </2 to determine if the value of expression $EXPR1 is less than the value of $EXPR2.
86
<=/2 - smaller_or_equals/2 - less_or_equals/2 determine if one value is less than or equal to another value
$EXPR1 <= $EXPR2 $EXPR1 smaller_or_equals $EXPR2 $EXPR1 less_or_equals $EXPR2
Table 25
Argument $EXPR1 $EXPR2
<=/2 arguments
Type ANY ANY Description expression to the left of the operator expression to the right of the operator
Use <=/2 to determine if the value of expression $EXPR1 is less than or equal to the value of $EXPR2.
Table 26
Argument $EXPR1 $EXPR2
>/2 arguments
Type ANY ANY Description expression to the left of the operator expression to the right of the operator
Use >/2 to determine if the value of expression $EXPR1 is greater than the value of $EXPR2.
87
>=/2 - greater_or_equals/2 determine if one value is greater than or equal to another value
$EXPR1 >= $EXPR2 $EXPR1 greater_or_equals $EXPR2
Table 27
Argument $EXPR1 $EXPR2
>=/2 arguments
Type ANY ANY Description expression to the left of the operator expression to the right of the operator
Use >=/2 to determine if the value of expression $EXPR1 is greater than or equal to the value of $EXPR2.
Table 28
Argument $EXPR1 $EXPR2
between/2 arguments
Type ANY LIST_OF ANY Description expression to the left of the operator expression to the right of the operator
Use between/2 to determine if the value of expression $EXPR1 is between the two values of $EXPR2. The expression $EXPR2 must evaluate to a list of two values.
88
If $EXPR2 evaluates to [$VAL1,$VAL2], then the condition $EXPR1 between $EXPR2 is equivalent to: $VAL1 <= $EXPR1 AND $EXPR1 <= $VAL2.
between/2 example
$E.duration between [100,199]
Table 29
Argument $EXPR1 $EXPR2
within/2 arguments
Type ANY LIST_OF ANY Description expression to the left of the operator expression to the right of the operator
Use within/2 to determine if the value of expression $EXPR1 is equal to one of the values of $EXPR2. The expression $EXPR2 must evaluate to a list of values.
within/2 example
$E.mc_host within [host1,host2,host3]
Table 30
Argument $EXPR1 $EXPR2
outside/2 arguments
Type ANY LIST_OF ANY Description expression to the left of the operator expression to the right of the operator
Use outside/2 to determine if the value of expression $EXPR1 is not equal to any of the values of $EXPR2. The expression $EXPR2 must evaluate to a list of values.
89
outside/2 example
$E.mc_host outside [host1,host2,host3]
Table 31
Argument $EXPR1 $EXPR2
contains/2 arguments
Type
I I I I I
Description expression to the left of the operator expression to the right of the operator
Use contains/2 to determine if the value of expression $EXPR1 contains the value of $EXPR2. There are three possible uses of this operator:
I
Both $EXPR1 and $EXPR2 are strings: contains/2 tests to see if $EXPR2 is a substring of $EXPR1.
$EXPR1 is a string and $EXPR2 is a list of strings: contains/2 tests to see if each element of $EXPR2 is a substring of $EXPR1. $EXPR1 is a list and $EXPR2 is a simple value: contains/2 tests to see if $EXPR2 is equal to one of the elements of $EXPR1.
90
contains/2 example
$E.msg contains Disk full $E.msg contains [Not enough,disk,space] $E.mc_bad_slotnames contains myslot
Table 32
Argument $EXPR1 $EXPR2
contained_in/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator
Use contained_in/2 to determine if the value of expression $EXPR1 is a substring of the value of $EXPR2.
contained_in/2 example
Disk full contained_in $E.msg
Table 33
Argument $EXPR1 $EXPR2
contains_one_of/2 arguments
Type STRING LIST_OF STRING Description expression to the left of the operator expression to the right of the operator
Use contains_one_of/2 to determine if the value of expression $EXPR1 has at least one of the values in the list $EXPR2 as a substring.
91
contains_one_of/2 example
$E.msg contains_one_of [Disk,CPU,Memory]
Table 34
Argument $EXPR1 $EXPR2
has_prefix/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator
Use has_prefix/2 to determine if the value of expression $EXPR1 has the value of $EXPR2 as a prefix.
has_prefix/2 example
$E.mc_host has_prefix svc_
Table 35
Argument $EXPR1 $EXPR2
has_suffix/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator
Use has_suffix/2 to determine if the value of expression $EXPR1 has the value of $EXPR2 as a suffix.
92
has_suffix/2 example
$E.mc_host has_suffix _clt
matches/2 to determine if the pattern of one string matches the pattern of another string
$EXPR1 matches $EXPR2
Table 36
Argument $EXPR1 $EXPR2
matches/2 arguments
Type
I I I
Description expression to the left of the operator expression to the right of the operator
Use matches/2 to determine if the value of expression $EXPR1 matches the pattern $EXPR2. There are two possible uses of this operator:
I
$EXPR1 is a string: matches/2 tests if string $EXPR1 matches the pattern $EXPR2. $EXPR1 is a list of strings: matches/2 tests if at least one string element of $EXPR1 matches the pattern $EXPR2.
The pattern $EXPR2 consists of literal text and value substitutes. Literal text is matched literally. Space characters in the pattern are matched with any number of consecutive spaces. Non-printable or special characters can be specified in the text with escape sequences:
\\ \s \n \r \t \0ddd backslash space (single space) new line carriage return tab character code in octal
A substitute is preceded by a % sign, followed by a type indicator. Between the % and the type indicator, an optional * suppression modifier can be added.
93
Two substitutes cannot occur without literal text in between them. The portion of the input that matches the substitute of %s depends on the pattern following the substitute:
I I I
a literal: input up to the first literal a space and a literal: input up to the space followed by the literal a space and a substitute: input up to the first space
matches/2 example
$E.msg matches %s failure
Table 37
Argument $EXPR1 $EXPR2
ip_smaller_or_equals/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator
Use ip_smaller_or_equals/2 to determine if the value of expression $EXPR1 is an IP address that is less than or equal to the IP address value of $EXPR2.
94
If either of the expressions do not evaluate to an IP address in dotted decimal notation, the operator condition fails. The IP addresses are compared as numbers.
ip_smaller_or_equals/2 example
$E.mc_host_address ip_smaller_or_equals 10.1.1.100
Any IP address in the range 0.0.0.0 to 10.1.1.100 for mc_host_address will satisfy this condition. An address such as 10.1.2.1 will not satisfy the condition.
Table 38
Argument $EXPR1 $EXPR2
ip_greater_or_equals/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator
Use ip_greater_or_equals/2 to determine if the value of expression $EXPR1 is an IP address that is greater than or equal to the IP address value of $EXPR2. If either of the expressions do not evaluate to an IP address in dotted decimal notation, the operator condition fails. The IP addresses are compared as numbers.
ip_greater_or_equals/2 example
$E.mc_host_address ip_greater_or_equals 10.1.1.100
Any IP address within the range 10.1.1.100 to 255.255.255.255 for mc_host_address will satisfy this condition. An address like 9.1.1.101 will not satisfy this condition.
95
Table 39
Argument $EXPR1 $EXPR2
ip_matches/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator
Use ip_matches/2 to determine if the value of expression $EXPR1 is an IP address that matches the IP address pattern of $EXPR2. An IP address pattern is a sequence of four pattern components separated with dots that correspond to the four components of a dotted decimal IP address. Each component can be one of:
I I I I
* represents any possible value < followed by a number represents any value less than that number > followed by a number represents any value greater than that number
any number represents an exact match of that number
Each of the four components of the IP address is matched against the corresponding component of the pattern. The IP address matches the pattern if all four components match. If the first expression does not evaluate to an IP address dotted decimal notation, or the second expression does not evaluate to an IP address pattern, the operator condition fails.
ip_matches/2 example
$E.mc_host_address ip_matches 10.1.1.*
Any IP address in the range 10.1.1.0 to 10.1.1.255 for mc_host_address will satisfy this condition.
$E.mc_host_address ip_matches 10.>200.<100.*
Any IP address in the ranges 10.201.0.0 to 10.201.99.255, 10.202.0.0 to 10.202.99.255 up to 10.255.0.0 to 10.255.99.255 for mc_host_address will satisfy this condition.
96
Table 40
Argument $EXPR1 $EXPR2
ip_matched_by/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator
Use ip_matched_by/2 to determine if the value of expression $EXPR2 is an IP address that matches the IP address pattern of $EXPR1. This is the reverse of ip_matches/2: the condition $EXPR1 ip_matched_by $EXPR2 is equivalent to $EXPR2 ip_matches $EXPR1.
ip_matched_by/2 example
10.1.1.* ip_matched_by $E.mc_host_address
Table 41
Argument $EXPR1 $EXPR2
superclass_of/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator
Use superclass_of/2 to determine if the value of expression $EXPR1 is the name of a class that is a superclass of the class name that is the value of $EXPR2. For this operator each class is considered to be a superclass of itself.
97
Expression operators
superclass_of/2 example
PATROL_EV superclass_of $E.CLASS
Table 42
Argument $EXPR1 $EXPR2
subclass_of/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator
Use subclass_of/2 to determine if the value of expression $EXPR1 is the name of a class that is a subclass the class name that is the value of $EXPR2. For this operator each class is considered to be a subclass of itself.
subclass_of/2 example
$E.CLASS subclass_of PATROL_EV
Expression operators
Expression operators are mainly arithmetic operators that take numeric values as arguments. There is also one expression operator that takes textual arguments. Results of expression operators are numeric or textual values. They can be reused as arguments in an expression. Logical operators take integer arguments that are interpreted as bit sets. The operation is performed on the bits and the result is interpreted as an integer value. The operators are listed in groups. All operators within the same group are evaluated at the same time, when they appear in an expression without parentheses. Operators from earlier groups are evaluated before operators from later groups.
98
Expression operators
This expression is evaluated as ($E1+($E2*$E3)). The * is evaluated before the +, because the * is in the second group, while the + is in the third group.
Multiplicative operators
Multiplicative operators take two numeric arguments and produce a numeric result.
e1 * e2 e1 / e2 e1 // e2 e1 >> e2 e1 << e2 Value of e1 multiplied by e2 Value of e1 divided by e2 Integer division of e1 by e2 Bitwise right shift of e1 by e2 positions Bitwise left shift of e1 by e2 positions
Additive operators
Additive operators take two numeric arguments and produce a numeric result.
e1 + e2 e1 - e2 e1 /\ e2 e1 \/ e2 e1 xor e2 The sum of e1 and e2 Value of e1 subtracted by e2 Bitwise conjunction (AND) of e1 and e2 Bitwise inclusive disjunction (OR) of e1 and e2 Bitwise exclusive disjunction (XOR) of e1 and e2
99
Concatenation operator
The following operator takes two string arguments and produces a string result.
e1 || e2 Concatenation of string e1 with string e2
Table 43
abs/2 acos/2
action_requestor/1 action_requestor/2 action_requestor/3 action_return/2 add_to_list/2 apply_match_entry/4 admin_execute/5 admin_execute/7 asin/2 atan/2 atan2/3 cellcontrol/1 cellinfo/2 char/2 class_path/2
100
Table 43
code/2 concat/2
confirm_external/2 cos/2 decr/1 decr/2 decr/2 and prev/2 decr/3 decr/3 decr/4 drop_new/0 execute/4 exp/2 find_match/5 find_match_entry/4 gcd/3 generate_event/2 get_env/2 get_external/4
return an integer or enumeration slot value decremented by 139 1 retrieve the value of an integer or enumeration slot decremented by a specified value decrement an integer or enumeration slot by a specified value within a given limit 141 141
return an integer or enumeration slot value decremented by 142 a specified value within a given limit drop a new event object run a program as an external process raise e (2.718281828...) to a specified power 220 114 129
find an entry in a match table and retrieve calculated values 174 from it find an entry in a match table return the greatest common divisor of two numbers generate a new event retrieve the value of an environment variable run an external program and wait for its termination to continue to process the current event, using data retrieved through an interface object retrieve a list of slots from one or more objects verify the occurrence of a substring within a string or list of strings verify the occurrence of a substring within a string or list of strings using a comparison modifier increment an integer or enumeration slot by 1 increment an integer or enumeration slot by a specified value 176 134 218 196 117
get_list_slotvalues/3 has_substring/2 has_substring/3 incr/1 incr/2 incr/2 and next/2 incr/3 incr/3
return an integer or enumeration slot value incremented by 1 136 return an integer or enumeration slot value incremented by a 137 specified value increment an integer or enumeration slot by a specified value within a specified limit 138
Chapter 4
101
Table 43
incr/4 int/2
int_to_hex/2 int_to_hex/3 inttostring/2 kbversion/1 kbversion/2 key_verify/2 key_verify/3 key_version/2 listappend/3 listdelete/3 listdisjoint/2 listgetelt/3 listintersect/3 listlen/2 listmember/2 listremdup/2 listsubtract/3 listunion/3 listwalk/2 log/2 log10/2 mapslots/3 mapslots/4 match_regex/3 match_regex/4 match_regex/5 max/3 min/3 new_data/3 ntadd/2
retrieve a list element located at a specified position within a 167 list determine the common elements of two lists determine the length of a list verify that an element is included in a list remove duplicate elements from a list remove the elements that occur in one list from another list determine the union of two lists execute instructions against each element in a list return the natural logarithm of a specified number return the decimal logarithm of a specified number format a series of expressions that refer to objects into a string format a series of expressions that refer to event and data objects into a string match a string with a regular expression match a string with a regular expression and retrieve all fields from it 170 167 168 172 171 171 172 130 130 159 158 154 155
match a string with a regular expression and retrieve a given 157 number of fields from it determine the maximum of two values determine the minimum of two values create a new data object add a note to an event 126 127 219 182
102
Table 43
ntcnt/2 ntget/5 ntset/3 opadd/3 opadd/4 opcnt/2 opget/6 opget/7
opget_action/3 opget_args/3 opget_author/3 opget_time/3 opset/4 opset/5 perform/3 perform/5 pointertostring/2 pow/3 propagated_to/3 random/3 real/2 and float/2 realtostring/2 relate/1 rem_from_list/2 remove_data/1 reset_default/1 round/2 send_to/2 send_to/3 send_to_ext/4 set_list_slotvalues/3 set_timer/3 set_timer_at/3
convert a numeric value to an integer value by rounding the 124 number send an event to another cell or gateway send an event modification to another cell or gateway send an extended event to another cell or gateway assign values to a list of slots for one or more objects 197 197 198 180
set a timer on an event object that will expire after a specified 221 delay set a timer on an event object that will expire at a specified time Chapter 4 Master Rule Language (MRL) reference 222
103
Table 43
Primitive/function name Description set_timer_at/4 sign/2 sin/2 smcomps/5 sprintf/3 sqrt/2 str_to_time_stamp/3 strextract/4 string/2 stringtoint/2 stringtopointer/2 stringtoreal/2 strip/2 strip/3 strip/4 strlen/2 and len/2 strmatch/3 strnpart/4 strpart/3 strtolist/3 substring/3
match a string with a simple pattern and retrieve fields from 152 it determine the start position of a specified occurrence of a part of a string determine the starting position of a partial string within a larger string divide a string into parts at specified separators retrieve a string that begins at a specified position within a larger string and continues through the end of the larger string retrieve a substring of a specified length beginning at a specified offset return the tangent of an angle verify if one or more time frames are active verify if one or more time frames are active at a given time obtain the end time of the current active interval of a time frame 152 145 152 148
obtain the end time of the active interval of a time frame at a 208 specified time obtain the start and end time of the current active interval of 209 a time frame
104
Table 43
Primitive/function name Description tf_current_interval/3 tf_current_start/2 tf_current_start/3 tf_duration/3 tf_duration/4 tf_next_end/2 tf_next_end/3 tf_next_interval/2 tf_next_interval/3 tf_next_start/2 tf_next_start/3 tf_prev_end/2 tf_prev_end/3 tf_prev_interval/2 tf_prev_interval/3 tf_prev_start/2 tf_prev_start/3 tf_udid_active/1 tf_udid_active/2 time_extract/3 time_stamp/1 time_stamp_to_cim/2 time_stamp_to_str/2 time_stamp_to_str/3
obtain the start time of the active interval of a time frame at a 207 specified time calculate the duration of all active intervals of a time frame from a specified start time to the current time calculate the duration of all active intervals of a time frame during a specified time period 217 217
obtain the end time of the next active interval of a time frame 214 obtain the end time of the next active interval of a time frame 215 at a specified time obtain the start and end time of the next active interval of a time frame obtain the start and end time of the next active interval of a time frame at a specified time obtain the start time of the next active interval of a time frame obtain the start time of the next active interval of a time frame at a given time obtain the end time of the previous active interval of a time frame obtain the end time of the previous active interval of a time frame at a given time obtain the start and end time of the previous active interval of a time frame obtain the start and end time of the previous active interval of a time frame at a specified time 215 216 213 214 211 212 212 213
obtain the start time of the previous active interval of a time 210 frame obtain the start time of the previous active interval of a time 210 frame at a given time verify if one or more time frames specified by mc_udid are active at the current time verify if one or more time frames specified by mc_udid are active at a specified time retrieve fields from a time stamp retrieve the current time 205 206 164 162
convert a time stamp to CIM (Common Information Model) 162 format convert a time stamp to the default DateFormat format convert a time stamp to a specified format Chapter 4 Master Rule Language (MRL) reference 164 163 105
Table 43
Primitive/function name Description tolowercase/2 and lower/2 touppercase/2 and upper/2 trunc/2 unrelate/1 unset_cause/0
106
Action-related primitives
An OBJECT value is typically references the event on which the rule is applied, as made available through the variable associated to the event. A SLOTREF typically references a slot of an OBJECT value (for example, $E.SlotName).
Action-related primitives
action_requestor/1 retrieve the identification of the requestor of an action
action_requestor($REQUESTOR) $REQUESTOR=action_requestor()
Table 44
Argument
$REQUESTOR
Use action_requestor/1 to retrieve the identification of the requestor of the action and return the identification in the $REQUESTOR argument. The requestor is either the user who performs the action from a console, or if the action is performed from a rule, the requestor is the name of the rule.
action_requestor/1 example
action AssignTo [Name:STRING($USER)] : EVENT($E) { action_requestor($REQUESTOR); $E.administrator = $REQUESTOR; $E.mc_owner = $USER; } END
In this example, the action AssignTo assigns a selected event to a named owner. The name of the owner is provided by the console user in the Name field of a dialog box, as specified in the action definition argument list. When the action is triggered, it retrieves the identification of the requestor and returns it in the $REQUESTOR variable. This value will be the ID of the console user and is assigned to the administrator slot of the event.
Chapter 4
107
Action-related primitives
The provided owner name is assigned to the mc_owner slot of the event.
action_requestor/2 retrieve the user ID and password of the console user triggering the action
action_requestor($USER,$PASSWD)
Table 45
$USER $PASSWD
Argument Mode
Use action_requestor/2 to retrieve the identification of the requestor of the action, as well as that user's password. The identification is returned in $USER and the password in $PASSWD. A password value will only be returned if the requestor of the action is a console user. For an action requested by a rule, the password is an empty string.
action_requestor/2 example
action UserGetMetrics : EVENT($E) { action_requestor($USER,$PASSWD); admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES); } END
In this example, the action is designed to be used from a console. When the console user triggers the action, the action code first retrieves the user's identification in the $USER variable and the user's password in the $PASSWD variable. This information is passed on to the Administration server named ias1 to request a remote execution of the remote Administration server task GetMetrics on the selected event. No specific arguments are required for this remote task, so the second to last argument of admin_execute is an empty list ([]). The YES value for the last argument indicates that an MC_CELL_ACTION_RESULT event must be generated for this remote action.
108
Action-related primitives
action_requestor/3 retrieve the user ID, password of the console user and rule type that is triggering the action
action_requestor($USER,$PASSWD,$RULETYPE)
Table 46
Argument $USER $PASSWD
$RULETYPE
Use action_requestor/3 to retrieve the identification of the requestor of the action, that user's password, and the type of rule performing the action. The identification is returned in $USER and the password in $PASSWD. A password value will only be returned if the requestor of the action is a console user. For an action requested by a rule, the password is an empty string. If the action is performed from a rule, the type of the rule is returned in $RULETYPE. When the action is performed by a user from a console, $RULETYPE returns an empty string.
action_requestor/3 example
action UserGetMetrics : EVENT($E) { action_requestor($USER,$PASSWD,$RULETYPE); if ( $RULETYPE == '' ) then { admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES); } else { admin_execute(ias1,$E,GetMetrics,[],YES); } } END
In this example, the action can be used from a console, as well as from a rule. If used from a console (represented by the then branch of the example), the credentials of the console user are passed to admin_execute/7. If the action is used from a rule (represented by the else branch of the example), no credentials are passed to admin_execute/5. In this case, it is assumed that the credentials are provided as part of the Administration server specification in the cell directory (mcell.dir).
Chapter 4
109
Action-related primitives
Table 47
$CODE $TEXT
Argument Mode
Use action_return/2 to terminate an internal action and to return a value. The $CODE argument specifies the numeric exit code to be returned. The $TEXT argument specifies the text string to be returned. If the action is invoked from a rule using the perform/5 primitive, the $CODE and $TEXT values will be returned as the last two arguments of the perform/5 call. For more information about perform/5, see perform/5 perform a specified action and return a value on page 113.
action_return/2 example
action AssignTo [Name:STRING($USER)] : EVENT($E) { action_requestor($REQUESTOR); $E.administrator = $REQUESTOR; $E.mc_owner = $USER; action_return(0,Ownership taken) } END
110
Action-related primitives
Table 48
Argument $NAME
STRING STRING
LIST_OF ANY specifies a list of action arguments. Required arguments for the action specified in $ACTION must be of the correct type specified in the action definition and must be included in the $ARGS list.
$ACTEVENT
input
BOOLEAN
Use admin_execute/5 to perform an action on Impact Administration Server (IAS) or other external framework using remote execution. The IAS or external framework must be defined in the DIRECTORY (mcell.dir), including the credentials to log in to it. The credentials must be provided as userid/password in the encryption key field. The action will be performed on IAS or the external framework using the credentials that are provided in the DIRECTORY.
admin_execute/5 example
action UserGetMetrics : EVENT($E) { admin_execute(ias1,$E,GetMetrics,[],YES); } END
In this example, the UserGetMetrics action retrieves metrics for an event from an Administration server. The action performs the GetMetrics remote task on the ias1 Administration server. Credentials are assumed to be provided in mcell.dir for this server.
admin_execute/7 perform an action through remote execution on IAS, providing IAS credentials
admin_execute($NAME,$USER,$PASSWD,$OBJECT,$ACTION,$ARGS,$ACTEVENT)
Chapter 4
111
Action-related primitives
Table 49
Argument $NAME
LIST_OF ANY specifies a list of action arguments. Required arguments for the action specified in $ACTION must be of the correct type specified in the action definition and must be included in the $ARGS list.
$ACTEVENT
input
BOOLEAN
Use admin_execute/7 to perform an action on Impact Administration Server (IAS) or other external framework using remote execution, specifying the user name and password for the account for the remote action agent (IAS or other external framework). An action is executed through the remote action agent named NAME. The USER and PASSWD credentials are used to log in to the remote action agent. If ACTEVENT=YES an MC_CELL_ACTION_RESULT event is generated for the action. When the action is terminated, its output is stored in the action result event.
admin_execute/7 example
action UserGetMetrics : EVENT($E) { action_requestor($USER,$PASSWD); admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES); } END
In this example, the action is designed to be used from a console. When the console user triggers the action, the action code first retrieves the user's identification in the $USER variable and the user's password in the $PASSWD variable.
112
Action-related primitives
This information is passed on to the Administration server named ias1 to request a remote execution of the remote Administration server task GetMetrics on the selected event. No specific arguments are required for this remote task, so the second to last argument of admin_execute is an empty list ([]). The YES value for the last argument indicates that an MC_CELL_ACTION_RESULT event must be generated for this remote action.
Table 50
Argument $OBJECT $ACTION $ARGS
perform/3 arguments
Mode input input input Type OBJECT STRING LIST_OF ANY Description specifies the object handle for the event or data on which the action is to be performed specifies the name of the action to be performed specifies a list of action arguments. Required arguments for the action specified in $ACTION must be of the correct type specified in the action definition and must be included in the $ARGS list.
Use perform/3 to perform the action defined with name specified by the $ACTION argument on the event or data with the object handle specified in the $OBJECT argument. Required arguments for the action must be provided in the $ARGS list. The success of the perform/3 call depends on whether the action succeeds or fails.
perform/3 example
perform($E,AssignTo,[Operator1]);
Table 51
Argument $OBJECT $ACTION
perform/5 arguments
Mode input input Type OBJECT STRING Description specifies the object handle for the event or data on which the action is to be performed specifies the name of the action to be performed Chapter 4 Master Rule Language (MRL) reference 113
Action-related primitives
Table 51
Argument $ARGS
perform/5 arguments
Mode input Type Description LIST_OF ANY specifies a list of action arguments. Required arguments for the action specified in $ACTION must be of the correct type specified in the action definition and must be included in the $ARGS list.
INTEGER STRING
the numeric return code of the specified action the text string returned by the specified action
Use perform/5 to perform the action specified by the $ACTION argument on the event or data with the object handle specified in the $OBJECT argument and return a numeric return code in $RETCODE and a text string in $RETTEXT. Required arguments for the action must be provided in the $ARGS list. If the action returns through action_return/2, the return exit code and text value is determined by the return code and text string values defined in the perform/5 arguments. If the action does not return through the action_return/2 primitive or if it is an external action, the values 0 and the empty string will be returned. For more information on the action_return/2 primitive, see action_return/2 terminate an internal action and return a value on page 110.
perform/5 example
perform($E,AssignTo,[Operator1],$RETCODE,$RETTEXT);
Table 52
Argument $EVENT $PROG
execute/4 arguments
Mode input input Type OBJECT STRING Description specifies the object handle for the event on which the action is to be performed specifies the name of the external program to be run
114
Action-related primitives
Table 52
Argument $ARGS
execute/4 arguments
Mode input Type Description LIST_OF ANY action argument list. Required arguments for the program must be provided in the $ARGS list. The arguments are passed to the external program as command line arguments.
$ACTEVT
input
STRING
Use execute/4 to run the program specified in the $PROG argument as an external process on the event with the object handle specified in the $EVENT argument. The program location is determined in the same manner as it is for actions (See Actions on page 43 for more information.). The execute/4 call terminates immediately when the external process has been set up, even if the program is not yet finished. The remainder of the rule is executed. The program is activated in an environment that contains all the slots of the event, using the slot name as the environment variable name. In addition, some systemdefined variables are available. See the Administration Guide for more information about action execution variables. If the $ACTEVT argument is specified as YES, an MC_CELL_ACTION_RESULT event will be created. Upon termination of the program, the MC_CELL_ACTION_RESULT event will be updated with the result.
execute/4 example
execute($E,mc_modslot,[msg,Hello],NO);
confirm_external/2 run an external program and wait for its termination to continue to process the current event
NOTE
The confirm_external/2 primitive can only be used in a refine rule.
confirm_external($PROG,$ARGS)
Chapter 4
115
Action-related primitives
Table 53
$PROG $ARGS
confirm_external/2 arguments
Type STRING LIST_OF ANY Description specifies the name of the external program to be run action argument list. Required arguments for the program must be provided in the $ARGS list. The arguments are passed to the external program as command line arguments. input input
Argument Mode
Use confirm_external/2 to run the program specified in the $PROG argument as an external process on the current event and wait for the program to terminate before continuing to process the current event. The program location is determined in the same manner as it is for actions. See Actions on page 43 for more information. A call of confirm_external/2 suspends the processing of the current event. Upon termination of the program, processing of the current event is resumed. If the program is successful, 0 is returned as the exit status and the event passes through the remainder of the rules. If the program returns a non-zero exit status, the event is dropped and no other rules are applied to it. The program is activated in an environment that contains all the slots of the event, using the slot name as environment variable name. In addition, some system-defined variables are available. See the Administration Guide for more information about action execution variables.
confirm_external/2 example
confirm_external(mc_ping,[]);
In this example, the mc_ping script performs a ping operation to the host specified in the mc_host_address slot of the event that is currently in the refine rule phase. No arguments are required for this script; therefore, the empty list functions as the second argument of the call. The script returns a 0 exit code if the ping succeeds. If the ping succeeds, the processing of the event will continue. If the ping fails, the event will be dropped.
116
Action-related primitives
get_external/4 run an external program and wait for its termination to continue to process the current event, using data retrieved through an interface object
NOTE
The get_external/4 primitive can only be used in a refine rule.
get_external($PROG,$ARGS,$INTF,$ANS)
Table 54
$PROG $ARGS
get_external/4 arguments
Type STRING Description specifies the name of the external program to be run input input
Argument Mode
LIST_OF ANY action argument list. Required arguments for the program must be provided in the $ARGS list. The arguments are passed to the external program as command line arguments.
$INTF $ANS
input
STRING
specifies the name of the interface class the data produced by the external program returned as an interface object
output OBJECT
Use get_external/4 to run the program specified in the $PROG argument as an external process on the current event and wait for the program to terminate before continuing to process the event. Upon successful return, the interface object specified by the $INTF argument is created that contains the data produced by the external program in the interface file. This object is available in the remainder of the rule, using the $ANS variable. The program location is determined in the same manner as it is for actions (See Actions on page 43 for more information.). A call of get_external/4 suspends the processing of the current event. Upon termination of the program, processing of the current event is resumed. If the program is successful, 0 is returned as the exit status and the event passes through the remainder of the rules. If the program returns a non-zero exit status, the event is dropped and no other rules are applied to it. In addition, a file path is passed as extra first command line argument. The external program is assumed to produce an instance of the $INTF interface class in that file. The program is activated in an environment that contains all the slots of the event, using the slot name as environment variable name. In addition, some system-defined variables are available. See the Administration Guide for more information about action execution variables.
Chapter 4
117
get_external/4 example
In this example, the Knowledge Base contains the following class definition:
MC_INTERFACE: DOOR_INFO DEFINES { door_id: STRING; door_location: STRING; door_status: STRING; }; END
An application could receive events that report incidents on doors. Such events would have mc_object_class set to DOOR. The following refine rule retrieves additional information:
refine get_door_info: EVENT($E) where [$E.mc_object_class==DOOR] { get_external(get_door_info,[$E.mc_object],DOOR_INFO,$DI); $E.msg = concat([Door ,$DI.door_id, at ,$DI.door_location, changed status to ,$DI.door_status]); } END
The external program get_door_info is assumed to return the door information for the door that is indicated in the mc_object slot, as an instance of DOOR_INFO. If the door specified in mc_object is not recognized by the program, the program may fail and return a non-zero exit code. In that case, the event on which the program was triggered will be dropped.
Table 55
$INTVAL $STRVAL
inttostring/2 arguments
Type Description the resulting conversion string input INTEGER specifies the integer value to be converted to a string
Argument Mode
output STRING
Use inttostring/2 to convert the integer value specified in the $INTVAL argument to a string value returned in $STRVAL.
118
inttostring/2 example
$E.msg = concat([Event #,inttostring($E.event_handle)]);
Table 56
$INTVAL $STRVAL
int_to_hex/2 arguments
Type INTEGER Description specifies the integer value to be converted to hexadecimal notation the hexadecimal notation of the integer returned as a string input
Argument Mode
output STRING
Use int_to_hex/2 to convert the integer value specified in the $INTVAL argument to a string containing its hexadecimal notation, returned in $STRVAL.
int_to_hex/2 example
$E.msg = concat([Event # 0x,int_to_hex($E.event_handle)]);
int_to_hex/3 convert an integer value to a string containing its hexadecimal notation in a specified field width
$STRVAL=int_to_hex($INTVAL,$FLDLEN)
Table 57
Argument $INTVAL $FLDLEN $STRVAL
int_to_hex/3 arguments
Mode input input output Type INTEGER INTEGER STRING Description specifies the integer value to be converted to hexadecimal notation specifies the desired resulting field width the hexadecimal notation of the integer returned as a string
Chapter 4
119
Use int_to_hex/3 to convert the integer value specified in the $INTVAL argument to a string containing its hexadecimal notation that is the same width as the field width specified by the $FLDLEN argument. The resulting hexadecimal notation string is returned in the $STRVAL argument. If the resulting notation is smaller than the specified field width, the notation is padded with 0s to the left of the notation until it is the specified width of the field.
int_to_hex/3 example
$E.msg = concat([Event # 0x,int_to_hex($E.event_handle,10)]);
Table 58
Argument $REALVAL $STRVAL
realtostring/2 arguments
Mode input Type INTEGER Description specifies the real value to be converted to a string value the conversion result, returned as a string
output STRING
Use realtostring/2 to convert the real value specified in the $REALVAL argument to a string value returned in $STRVAL.
realtostring/2 example
$DEV = ( $AVERAGE_DURATION - real($E.duration) ) ^ 2; $E.msg = concat([Duration deviation=,realtostring($DEV)]);
Table 59
Argument $PTRVAL $STRVAL
pointertostring/2 arguments
Mode input output Type POINTER STRING Description specifies the pointer value to be converted to a string the conversion result, returned as a string
120
Use pointertostring/2 to convert the pointer value specified in the $PTRVAL argument to a string value returned in $STRVAL.
pointertostring/2 example
$E.msg = concat([Address=,pointertostring($ADDR)]);
Table 60
Argument $ANYVAL $STRVAL
string/2 arguments
Mode input output Type ANY STRING Description specifies any non-list value to be converted to a string the conversion result, returned as a string
Use string/2 to convert the non-list value specified by $ANYVAL to a string value returned in $STRVAL.
string/2 example
$E.msg = concat([Value=,string($ANYVAL)]);
Table 61
Argument $STRVAL $INTVAL
stringtoint/2 arguments
Mode input output Type STRING INTEGER Description specifies the string value to be converted to an integer the conversion result, returned as an integer
Use stringtoint/2 to convert a string value specified in the $STRVAL argument to an integer value returned in $INTVAL.
Chapter 4
121
stringtoint/2 example
$INTVAL = stringtoint($E.msg);
Table 62
Argument $STRVAL $REALVAL
stringtoreal/2 arguments
Mode input output Type REAL Description the conversion result, returned as a real value STRING specifies the string value to be converted to an integer
Use stringtoreal/2 to convert the string value specified in the $STRVAL argument to a real (floating point) value returned in $REALVAL.
stringtoreal/2 example
$REALVAL = stringtoreal($E.msg);
Table 63
Argument $STRVAL $PTRVAL
stringtopointer/2 arguments
Mode input output Type STRING Description specifies the string value to be converted to an integer
Use stringtopointer/2 to convert a string value specified in the $STRVAL argument to a pointer value returned in $PTRVAL.
122
stringtopointer/2 example
$PTRVAL = stringtopointer($E.msg);
Table 64
Argument $NUMBER $INTVAL
int/2 arguments
Mode input Type Description INTEGER|REAL specifies the numeric (integer or real) value that is to be converted to an integer the conversion result, returned as an integer
output INTEGER
Use int/2 to convert the numeric value specified by the $NUMBER argument to an integer value returned in the $INTVAL argument. The conversion truncates the $NUMBER to the largest integer value that is smaller than or equal to it. The following statement is true for the truncation process: X: X-1 < int(X) X
int/2 example
$DEV = int( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );
Table 65
Argument $NUMBER $INTVAL
trunc/2 arguments
Mode input Type Description INTEGER|REAL specifies the numeric (integer or real) value that is to be converted to an integer the conversion result, returned as an integer
output INTEGER
Chapter 4
123
Use trunc/2 to convert the numeric value specified by the $NUMBER argument to an integer value returned in the $INTVAL argument. For positive numbers, the conversion truncates the number to the largest integer value that is smaller than or equal to it. A negative number is truncated to the smallest integer value that is greater than or equal to it. This function is symmetric around 0. The following statement holds true for the truncation process: X 0: X-1 < trunc(X) X X 0: X trunc(X) < X+1
trunc/2 example
$DEV = trunc( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );
Table 66
Argument $NUMBER $INTVAL
round/2 arguments
Mode input Type INTEGER|REAL Description specifies the numeric (integer or real) value that is to be converted to an integer the conversion result, returned as an integer
output INTEGER
Use round/2 to convert a numeric value to an integer value returned in $INTVAL. The conversion rounds the number.
round/2 example
$DEV = round( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );
124
Table 67
Argument $NUMBER $REALVAL
Use real/2 or float/2 to convert a numeric value to a real (floating point) value returned in $REALVAL.
Table 68
$STRVAL $INTVAL
code/2 arguments
Type STRING Description specifies the single character for which you want to return the numeric code input
Argument Mode
Use code/2 to retrieve the internal numeric code of the character specified by the $STRVAL argument and return it as an integer in the $INTVAL argument. The code is implementation dependent. It currently is the Unicode code point. Only the first character of the string is considered.
code/2 example
$CODE = code($E.msg);
char/2 produce a string containing a single character with a specified numeric internal representation
$STRVAL=char($INTVAL)
Chapter 4
125
Mathematical functions
Table 69
Argument $INTVAL $STRVAL
char/2 arguments
Mode input output Type Description INTEGER specifies the integer character code for the single-character string STRING the single character represented by the integer character code, returned as a string
Use char/2 to convert the numeric internal representation specified by $INTVAL into a string returned in $STRVAL. The code is implementation dependent. It currently is the Unicode code point. Not every numeric code results in a valid character.
char/2 example
$E.msg = char($E.msg);
Mathematical functions
max/3 determine the maximum of two values
$MAXVAL=max($VAL1,$VAL2)
Table 70
Argument $VAL1 $VAL2 $MAXVAL
max/3 arguments
Mode input input output Type ANY ANY ANY Description specifies the first value to be compared specifies the second value to be compared to the first value returns the maximum value
Use max/3 to determine the maximum of two values specified in $VAL1 and in $VAL2 and return the result as $MAXVAL. Both input values have to be of the same, simple (non-list) type.
126
Mathematical functions
max/3 example
$MAX_DURATION = max( $PREVIOUS_DURATION , $E.duration );
Table 71
Argument $VAL1 $VAL2 $MINVAL
min/3 arguments
Mode input input output Type ANY ANY ANY Description specifies the first value to be compared specifies the second value to be compared to the first value returns the minimum value
Use min/3 to determine the minimum of two values specified in the $VAL1 and $VAL2 arguments and return the result as $MINVAL. Both input values must be the same, simple (non-list) type.
min/3 example
$MIN_DURATION = min( $PREVIOUS_DURATION , $E.duration );
Table 72
$NUMBER $SIGN
sign/2 arguments
Type INTEGER|REAL Description specifies the numeric (integer or real) value for which the sign is to be returned returns the sign of the number. Possible values include:
I I I
output INTEGER
Chapter 4
127
Mathematical functions
The sign/2 function returns the sign of the numeric value specified by the $NUMBER argument and returned as $SIGN.
NOTE
A real number that is not precisely 0 may still be displayed as 0.0 due to rounding errors or limited precision. The sign of such a real number will not be 0.
sign/2 example
$SIGN = sign( $AVERAGE_DURATION - real($E.duration) );
Table 73
Argument $NUMBER $ABSVAL
abs/2 arguments
Mode input output Type INTEGER|REAL INTEGER|REAL Description specifies the numeric (integer or real) value for which the absolute value is to be returned returns the absolute value of the number
The abs/2 function returns the absolute value of the numeric value specified in the $NUMBER argument as $ABSVAL.
abs/2 example
$ABS = abs( $AVERAGE_DURATION - real($E.duration) );
Table 74
Argument $NUMBER $RESULT
sqrt/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the numeric (integer or real) value for which the square root is to be returned returns the square root of the number
The sqrt/2 function returns the square root value of the numeric value specified by the $NUMBER argument as $RESULT.
128 BMC Knowledge Base Development Reference Guide
Mathematical functions
sqrt/2 example
$SQRT = sqrt( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );
Table 75
Argument $NUMBER $RESULT
exp/2 arguments
Mode input output Type REAL Description returns e raised to the specified number INTEGER|REAL specifies the power to which e is to be raised
The exp/2 function returns the number e (2.718281828...) raised to the power specified by the $NUMBER argument as $RESULT.
exp/2 example
$EXP = exp( $E.duration );
Table 76
Argument $NUMBER $POWER $RESULT
pow/3 arguments
Mode input input output Type INTEGER|REAL INTEGER|REAL REAL Description specifies the numeric (integer or real) value to be raised to the specified power specifies the power to which the numeric value is to be raised returns the number raised to the power
The pow/3 function raises the number specified in the $NUMBER argument to the power specified in the $POWER argument and returns the result in $RESULT.
NOTE
The exponentiation operator ^ can only be used with integer powers. For non-integer powers, pow/3 must be used.
Chapter 4
129
Mathematical functions
pow/3 example
$POW = pow( $VAL , 3.14 );
Table 77
Argument $NUMBER $RESULT
log/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the numeric (integer or real) value for which the natural logarithm is to be returned the natural logarithm of the number, returned as a real value
The log/2 function calculates the natural logarithm (base e or 2.718281828...) of the number specified in the $NUMBER argument and returns the result in the $RESULT argument.
log/2 example
$LOG = log( $VAL );
Table 78
Argument $NUMBER $RESULT
log10/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the numeric (integer or real) value for which the decimal logarithm is to be returned the natural logarithm of the number, returned as a real value
The log10/2 function returns the decimal logarithm (base 10) of the number specified by the $NUMBER argument in the $RESULTargument.
130
Mathematical functions
log10/2 example
$LOG = log10( $VAL );
Table 79
Argument $NUMBER $RESULT
sin/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the angle (expressed in radians) for which the sine is to be returned the sine of the angle, returned as a real value
The sin/2 function returns the sine of the angle specified in the $NUMBER argument in the $RESULT argument.
sin/2 example
$SIN = sin( $ANGLE );
Table 80
Argument $NUMBER $RESULT
cos/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the angle (expressed in radians) for which the cosine is to be returned the cosine of the angle, returned as a real value
The cos/2 function returns the cosine of the angle specified in the $NUMBER argument in the $RESULT argument.
Chapter 4
131
Mathematical functions
cos/2 example
$COS = cos( $ANGLE );
Table 81
Argument $NUMBER $RESULT
tan/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the angle (expressed in radians) for which the tangent is to be returned the tangent of the angle, returned as a real value
The tan/2 function returns the tangent of the angle specified in the $NUMBER argument in the $RESULT argument.
tan/2 example
$TAN = tan( $ANGLE );
Table 82
Argument $NUMBER $RESULT
asin/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the number for which the arc sine is to be returned angle for which the number $NUMBER is the arc sine (expressed in radians)
The asin/2 function returns the arc sine of the number specified in the $NUMBER argument in the $RESULT argument.
132
Mathematical functions
asin/2 example
$ANGLE = asin( $VAL );
Table 83
Argument $NUMBER $RESULT
acos/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the number for which the arc cosine is to be returned angle for which the number $NUMBER is the arc cosine (expressed in radians)
The acos/2 function returns the arc cosine of the number specified in the $NUMBER argument in the $RESULT argument.
acos/2 example
$ANGLE = acos( $VAL );
Table 84
Argument $NUMBER $RESULT
atan/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the number for which the arc tangent is to be returned angle for which the number $NUMBER is the arc tangent (expressed in radians)
The atan/2 function returns the arc tangent of the number specified in the $NUMBER argument in the $RESULT argument.
Chapter 4
133
Mathematical functions
atan/2 example
$ANGLE = atan( $VAL );
Table 85
Argument $NUMBER1 $NUMBER2 $RESULT
atan2/3 arguments
Mode input input output Type INTEGER|REAL INTEGER|REAL REAL Description specifies the first (integer or real) value of the ratio specifies the second (integer or real) value of the ratio angle for which the ratio of $NUMBER1 and $NUMBER2 is the arc tangent (expressed in radians)
The atan2/3 function returns the arc tangent of the ratio of $NUMBER1 and $NUMBER2 in the $RESULT argument.
atan2/3 example
$RIGHTANGLE = atan2( 1 , 0 );
Table 86
Argument $NUMBER1 $NUMBER2 $RESULT
gcd/3 arguments
Mode input input output Type INTEGER INTEGER INTEGER Description specifies the first integer value of the two integers for which a common divisor is to be returned specifies the second integer value of the two integers for which a common divisor is to be returned the greatest common divisor of the two specified numbers
134
Enumeration operations
The gcd/3 function returns the greatest common divisor of $NUMBER1 and $NUMBER2 in $RESULT.
gcd/3 example
$GCD = gcd( $NUM1 , $NUM2 );
random/3 return a random integer that falls between two specified numbers
$RESULT=random($NUMBER1,$NUMBER2)
Table 87
Argument $NUMBER1 $NUMBER2 $RESULT
random/3 arguments
Mode input input Type INTEGER INTEGER Description first number in the range within which a random number is to be returned last number in the range within which a random number is to be returned a random number between both numbers
output INTEGER
The random/3 function returns a random integer number between the integer specified by the $NUMBER1 argument and the integer specified by the $NUMBER2 argument in $RESULT.
random/3 example
$RAND = random( $NUM1 , $NUM2 );
Enumeration operations
incr/1 increment an integer or enumeration slot by 1
incr($SLOT)
Table 88
$SLOT
incr/1 arguments
Type SLOTREF Description specifies an integer or enumeration slot to be incremented input
Argument Mode
Chapter 4
135
Enumeration operations
Use incr/1 to increment the slot referenced in $SLOT by 1. For an enumeration, the slot is set to the next higher value. If there is no higher value, the slot value is not modified.
incr/1 example
incr( $E.mc_priority );
$VAL=incr($SLOT)
Table 89
$SLOT
incr/2 arguments
Type SLOTREF Description specifies an integer or enumeration slot for which the incremented value is to be returned. The actual value of the slot is not incremented. input
Argument Mode
$VAL
output
INTEGER|ENUM
Use incr/2 to return the value of the slot referenced in $SLOT incremented by 1 in the $VAL argument. For an enumeration, the value of the slot is returned as the next higher value. If there is no higher value, the value of the slot that is returned in $VAL is not modified. The referenced slot itself is not modified.
incr/2 example
$NEWPRIO = incr( $E.mc_priority );
136
Enumeration operations
Table 90
Argument $SLOT $INCR
incr/2 arguments
Mode input input Type SLOTREF INTEGER Description specifies an integer or enumeration slot to be incremented specifies the number by which the slot is to be incremented
Use incr/2 to increment the slot referenced in $SLOT by $INCR. For an enumeration, the slot is incremented by $INCR higher values. If there are not $INCR higher values, then the slot is incremented to the highest value available.
incr/2 example
incr( $E.mc_priority , 2 );
Table 91
$SLOT
incr/3 arguments
Type SLOTREF Description specifies an integer or enumeration slot for which the incremented value is to be returned The actual slot value is not incremented. input
Argument Mode
$INCR $VAL
input output
INTEGER INTEGER|ENUM
specifies the number by which the slot value is to be incremented when it is returned in $VAL value of the slot incremented by $INCR
Use incr/3 to retrieve the value of the slot referenced in $SLOT incremented by $INCR in $VAL. For an enumeration, the slot value returned is incremented by $INCR higher values. If there are not $INCR higher values, then the slot value returned is incremented to the highest value available. The referenced slot itself is not modified.
Chapter 4
137
Enumeration operations
incr/3 example
$NEWPRIO = incr( $E.mc_priority , 2 );
incr/3 increment an integer or enumeration slot by a specified value within a specified limit
incr($SLOT,$INCR,$LIMIT)
Table 92
$SLOT $INCR $LIMIT
incr/3 arguments
Type SLOTREF INTEGER Description specifies an integer or enumeration slot to be incremented specifies the number by which the slot is to be incremented input input input
Argument Mode
Use incr/3 to increment the slot referenced in $SLOT by $INCR, limited to the value $LIMIT. For an enumeration, the slot value is incremented by $INCR higher values, limited to $LIMIT.
incr/3 example
incr( $E.mc_priority , 2 , PRIORITY_2 );
incr/4 retrieve the value of an integer or enumeration slot incremented by a given value within a specified limit
$VAL=incr($SLOT,$INCR,$LIMIT)
Table 93
Argument $SLOT
incr/4 arguments
Mode input Type SLOTREF Description specifies an integer or enumeration slot for which the incremented value is to be returned The actual slot value is not incremented.
$INCR
input
INTEGER
specifies the number by which the slot value is to be incremented when it is returned in $VAL
138
Enumeration operations
Table 93
Argument $LIMIT $VAL
incr/4 arguments
Mode input output Type INTEGER|ENUM INTEGER|ENUM Description specifies the limit to which the slot value is to be incremented when it is returned in $VAL value of the slot incremented by $INCR
Use incr/4 to retrieve the value of the slot referenced in $SLOT incremented by $INCR, limited to the value $LIMIT in $VAL. For an enumeration, the slot value returned is incremented by $INCR higher values, limited to $LIMIT. The referenced slot itself is not modified.
incr/4 example
$NEWPRIO = incr( $E.mc_priority , 2 , PRIORITY_2 );
Table 94
Argument $SLOT
decr/1 arguments
Mode input Type SLOTREF Description specifies an integer or enumeration slot to be decremented
Use decr/1 to decrement the slot referenced in $SLOT by 1. For an enumeration, the slot is set to the next lower value, or unmodified if there is no lower value.
decr/1 example
decr( $E.mc_priority );
$VAL=decr($SLOT)
Chapter 4
139
Enumeration operations
Table 95
Argument $SLOT
decr/2 arguments
Mode input Type SLOTREF Description specifies an integer or enumeration slot for which the decremented value is to be returned. The actual value of the slot is not decremented.
$VAL
output
Use decr/2 to retrieve the value of the slot referenced in $SLOT decremented by 1 in $VAL. For an enumeration, the slot value returned is decremented to the next lower value. If there is no lower value, the slot value returned remains unmodified. The referenced slot itself is not modified.
decr/2 example
$NEWPRIO = decr( $E.mc_priority );
Table 96
$SLOT $DECR
decr2 arguments
Description input SLOTREF specifies an integer or enumeration slot to be decremented input INTEGER specifies the number of values that the slot is to be decremented
Use decr2 to decrement the slot referenced in $SLOT by $DECR. For an enumeration, the slot value is decremented to the $DECR next lower value. If there are not $DECR lower values, the slot value is decremented to the lowest value.
140
Enumeration operations
decr2 example
decr( $E.mc_priority , 2 );
decr/3 retrieve the value of an integer or enumeration slot decremented by a specified value
$VAL=decr($SLOT,$DECR)
Table 97
$SLOT
decr/3 arguments
Type SLOTREF Description specifies an integer or enumeration slot for which the decremented value is to be returned. The actual value of the slot is not decremented. input
Argument Mode
$DECR $VAL
input output
INTEGER INTEGER|ENUM
specifies the number by which the slot value returned in $VAL is to be decremented value of the slot decremented by $DECR
Use decr/3 to retrieve the value of the slot referenced in $SLOT decremented by $DECR in $VAL. For an enumeration, the slot value is decremented to the $DECR next lower value. If there are not $DECR lower values, the slot value is decremented to the lowest value. The referenced slot itself is not modified.
decr/3 example
$NEWPRIO = decr( $E.mc_priority , 2 );
decr/3 decrement an integer or enumeration slot by a specified value within a given limit
decr($SLOT,$DECR,$LIMIT)
Chapter 4
141
Enumeration operations
Table 98
Argument $SLOT $DECR $LIMIT
decr/3 arguments
Mode input input input Type SLOTREF INTEGER INTEGER|ENUM Description specifies an integer or enumeration slot to be decremented specifies the number by which the slot is to be decremented specifies the limit to which the slot value is to be decremented
Use decr/3 to decrement the slot referenced in $SLOT by $DECR, limited to the value $LIMIT. For an enumeration, the slot value is decremented to the $DECR next lower value, limited to $LIMIT.
decr/3 example
decr( $E.mc_priority , 2 , PRIORITY_4 );
decr/4 return an integer or enumeration slot value decremented by a specified value within a given limit
$VAL=decr($SLOT,$DECR,$LIMIT)
Table 99
$SLOT
decr/4 arguments
Type SLOTREF Description specifies an integer or enumeration slot for which the decremented value is to be returned. The actual value of the slot is not decremented. input
Argument Mode
specifies the number by which the slot value returned in $VAL is to be decremented specifies the limit to which the slot value returned in $VAL is to be decremented value of the slot decremented by $DECR
Use decr/4 to return the value of the slot specified in $SLOT decremented by $DECR, limited to the value $LIMIT in $VAL. For an enumeration, the slot value returned is decremented to the $DECR next lower value, limited to $LIMIT. The referenced slot itself is not modified.
142
String manipulation
decr/4 example
$NEWPRIO = decr( $E.mc_priority , 2 , PRIORITY_4 );
String manipulation
concat/2 concatenate a list of strings
concat($STRLIST,$STR) $STR=concat($STRLIST)
Use concat/2 to concatenate the strings specified in $STRLIST into the single string $STR. The strings are concatenated as is, without any additional separators.
concat/2 example
concat([Duration: ,inttostring($E.duration), seconds],$E.msg);
Chapter 4
143
String manipulation
Use strlen/2 to calculate the length of the string $STR and return the number of characters in the string in the $LEN argument.
NOTE
The number of characters in the string may differ from the number of bytes needed to store the string.
strlen/2 example
$MSGLEN = strlen($E.msg);
Use tolowercase/2 to convert the original string specified in the $ORGSTR argument to the same string in all lowercase characters returned in $NEWSTR. This function is locale sensitive.
144
String manipulation
tolowercase/2 example
$E.mc_host = tolowercase($E.mc_host);
Use touppercase/2 to convert the string specified in the $ORGSTR argument to the same string in all uppercase characters returned in $NEWSTR. This function is locale sensitive.
touppercase/2 example
$E.mc_host = touppercase($E.mc_host);
strpart/3 determine the starting position of a partial string within a larger string
strpart($STR,$PART,$POS) $POS=strpart($STR,$PART)
Chapter 4
145
String manipulation
Use strpart/3 to determine the first position of the partial string specified in the $PART argument within the string specified in the $STR argument. The starting position is returned in $POS. The starting position is determined by counting 1 as the first character of the string specified in $STR. If the partial string does not occur within the base string, the value 0 is returned as the position of $PART.
strpart/3 example
$HLEN = len($E.mc_host); $ZPOS = strpart($E.mc_host,.); if ( $HLEN == 0 OR $ZPOS == 0 OR $ZPOS == $HLEN ) then $E.mc_location = "Unknown"; else $E.mc_location = substring($E.mc_host,$ZPOS,$HLEN-$ZPOS);
$PART
input
STRING
$CNT
input
INTEGER
$POS
output
INTEGER
146
String manipulation
Use strnpart/4 to determine at what position in $STR the number of occurrences for the partial string $PART reaches $CNT number of occurrences. The position is returned in $POS. The first character of the string is counted as 1. If the partial string does not occur at least $CNT times in the base string, the value 0 is returned as position.
strnpart/4 example
$HLEN = len($E.mc_host); $ZPOS = strnpart($E.mc_host,.,2); if ( $HLEN == 0 OR $ZPOS == 0 OR $ZPOS == $HLEN ) then $E.mc_location = "Unknown"; else $E.mc_location = substring($E.mc_host,$ZPOS,$HLEN-$ZPOS);
strextract/4 retrieve a string of a specified length that begins at a specified position within a larger string
strextract($STR,$POS,$LEN,$NEWSTR) $NEWSTR=strextract($STR,$POS,$LEN)
Use strextract/4 to return part of the string specified in the $STR argument into $NEWSTR. The returned part of the string starts at character position $POS and is $LEN characters long.
$POS is determined by counting 1 as the first character of the string specified in $STR.
Chapter 4
147
String manipulation
strextract/4 example
strextract($YYYYMMDD,5,2,$MM);
substring/3 retrieve a string that begins at a specified position within a larger string and continues through the end of the larger string
$NEWSTR=substring($STR,$SKIP)
Use substring/3 to retrieve a part of the string $STR in another string $NEWSTR. The retrieved string starts after $SKIP characters from the beginning of the base string specified in $STR and extends to the end of the base string.
substring/3 example
$DD = substring($YYYYMMDD,6);
INTEGER specifies the number of characters to skip in the base string before $NEWSTR begins INTEGER specifies the length of $NEWSTR STRING retrieved string
148
String manipulation
Use substring/4 to retrieve part of the string $STR into $NEWSTR. The retrieved part of the string starts $SKIP characters from the start of $STR and is $LEN characters long.
substring/4 example
$MM = substring($YYYYMMDD,4,2);
Use strip/2 to remove the beginning and ending blank spaces from $STR and copy the resulting string into $NEWSTR.
strip/2 example
$MSG = strip($E.msg);
Table 110
Argument $STR $POS $NEWSTR
strip/3 arguments
Mode input input output Type STRING Description specifies the base string from which blank spaces at a specified position are to be removed
INTEGER specifies the position within the base string from which blank spaces are to be removed STRING resulting string after the blank spaces have been removed
Use strip/3 to remove the blank spaces from position $POS within $STR and copy the resulting string into $NEWSTR.
Chapter 4
149
String manipulation
The value of $POS determines the part or parts of the base string where the blank spaces are to be removed. Only the three least significant bits are considered, as shown: Table 111
$POS value 0 1 2 3 4 5 6 7
strip/3 example
$MSG = strip($E.msg,2);
Table 112
Argument $STR $POS $CHARS $NEWSTR
strip/4 arguments
Mode input input input output Type STRING Description specifies the base string from which specified characters are to be removed
INTEGER specifies the part(s) of the string from which specified characters are to be removed STRING STRING specifies the characters to be removed resulting string after the specified characters have been removed
Use strip/4 to make a copy of the string $STR in another string $NEWSTR with all characters from $CHARS stripped off from position $POS.
150
String manipulation
The value of $POS determines the part or parts of the base string where the blank spaces are to be removed. Only the three least significant bits are considered, as shown: Table 113
$POS value 0 1 2 3 4 5 6 7
A character of the base string is considered to be located in the beginning of the string, if it and all characters preceding it, are in the character set $CHARS. A character of the base string is considered to be located in the end of the string, if it and all characters following it, are in the character set $CHARS. A character of the base string is considered to be located in the middle of the string, if it is in the character set $CHARS and if it is neither in the beginning nor in the end of the string. For example, a string contains the following characters: # !!# #a bc #! d # e #!# The first character in the string up to, but not including, a is considered to be the beginning of the string. The part of the string starting from the space after the e through the last character in the string is considered to be the end of the string. The part of the string from the a through the e is considered to be the middle of the string.
strip/4 example
$MSG = strip($E.msg,6, #!);
The variable $MSG gets the contents of the msg slot of the event with all blank spaces, # and ! characters removed, except at the end of the string. Any trailing sequence of those three characters at the end of the slot value are retained.
Chapter 4 Master Rule Language (MRL) reference 151
String manipulation
If $E.msg has the value from this example, $MSG will get the value abcde # !# .
Table 114
Argument $STR $SEP $FLDS
strtolist/3 arguments
Mode input input output Type STRING STRING LIST_OF STRING Description specifies the string to be divided into fields specifies the separator(s) which separates the pieces of the string into fields retrieved fields
Use strtolist/3 to divide a string $STR into pieces, separated by any character from $SEP and collect the fields in $FLDS. The $FLDS argument can be specified as one variable that will get a list value or it can be specified as a list of as many variables as there are fields in the base string.
strtolist/3 example
strtolist(/usr/bin/mcell.exe,/.,$FLDS);
The input string will be divided into pieces that are separated with forward slash or dot characters. The variable $FLDS will be set to the list [usr,bin,mcell,exe].
strmatch/3 match a string with a simple pattern and retrieve fields from it
strmatch($STR,$PAT,$FLDS) $FLDS=strmatch($STR,$PAT)
Table 115
Argument $STR $PAT $FLDS
strmatch/3 arguments
Mode input input output Type STRING STRING Description specifies the string with which the pattern is to be matched specifies the pattern to match with the string
152
String manipulation
Use strmatch/3 to match a string $STR with a pattern $PAT and retrieve fields from it in $FLDS. The pattern $PAT consists of literal text and value substitutes. Literal text is matched literally. Space characters in the pattern are matched with any number of consecutive spaces. Non-printable or special characters can be specified in the text with escape sequences:
\\ \s \n \r \t \0ddd backslash space (single space) new line carriage return tab character code in octal
A substitute is preceded by a % sign, followed by a type indicator. Between the % and the type indicator, an optional * suppression modifier can be added. The values corresponding to the substitutes are collected in the fields in $FLDS, in order of appearance. Suppressed substitutes are matched, but the values are not collected. Possible substitutes are:
%% %d %f %c %s literal match of % decimal integer number floating point real number single character string value
Two substitutes cannot occur without literal text in between them. The portion of the input that matches the substitute of %s depends on the pattern following the substitute:
I I I
a literal: input up to the first literal a space and a literal: input up to the space followed by the literal a space and a substitute: input up to the first space
The $FLDS argument can be specified as one variable that will get a list value or it can be specified as a list of as many variables as there are fields specified in the pattern.
Chapter 4
153
String manipulation
strmatch/3 example
strmatch(abc def 12,%s %d,[$FLD1,$FLD2]);
The pattern defines two fields, one string and one integer number, separated with spaces. The variable $FLD1 will get the value abc def and variable $FLD2 will get the value 12.
strmatch(Hi you there!,Hi %s!,$FLDS);
The pattern defines one string field, preceded by the text Hi and followed by an ! (exclamation point). The variable $FLDS will be set to a list containing the single string you there.
strmatch(Hi there,Hi %s!,$FLDS);
This call will fail because the pattern defines one string field, preceded by the text Hi and followed by an ! (exclamation point), but the input string does not contain an ! (exclamation point) at the end.
strmatch(a b c go,%s %s go,[$FLD1,$FLD2]);
The pattern defines two string fields, separated with spaces and followed by text. The variable $FLD1 will get the value a, because the first string substitute is followed by a space and a substitute which consumes the input up to the first space. The variable $FLD2 will get the value b c because its string substitute is followed by a space and a literal which consumes the input up to the matching literal.
Table 116
Argument $STR $REGEX $OPTS
match_regex/3 arguments
Mode input input input Type STRING STRING STRING Description specifies the string to be matched specifies the regular expression to match with the string specifies the options for how the regular expression engine operates
154
String manipulation
Use match_regex/3 to match a string $STR with regular expression $REGEX applying options specified in $OPTS.
NOTE
The regular expression $REGEX must be compliant with the Perl Compatible Regular Expression specification. For a specification, see http://perldoc.perl.org/perlre.html.
The value of the $OPTS argument can be either an empty string or a sequence of any of the following option indicators:
i m s x perform case insensitive string comparison multi-line mode a dot matches any character, including new line extended mode (see below)
In extended mode, blank space data characters in the pattern are ignored, except when they are escaped or inside a character class. Characters between an unescaped # outside a character class and the next new line character, inclusive, are also ignored. The call of match_regex/3 will succeed if the string matches the regular expression and fail otherwise.
match_regex/3 example
match_regex(2007 02 04 mcell: RULES: xyz, [0-9]* [0-9]* [0-9]* [^:]*: [^:]*: .*,);
The input string, which could be part of a trace, matches the regular expression.
match_regex/4 match a string with a regular expression and retrieve all fields from it
match_regex($STR,$REGEX,$OPTS,$FLDS) $FLDS=match_regex($STR,$REGEX,$OPTS)
Table 117
Argument $STR $REGEX
match_regex/4 arguments
Mode input input Type STRING STRING Description specifies the string to be matched specifies the regular expression to match to the string
Chapter 4
155
String manipulation
Table 117
Argument $OPTS $FLDS
match_regex/4 arguments
Mode input output Type STRING LIST_OF STRING Description specifies the options for how the regular expression engine operates retrieved fields
Use match_regex/4 to match a string $STR with regular expression $REGEX applying options from $OPTS and to collect retrieved fields in $FLDS.
NOTE
The regular expression $REGEX must be compliant with the Perl Compatible Regular Expression specification. For a specification, see http://perldoc.perl.org/perlre.html.
The options argument can be either an empty string or a sequence of any of the following option indicators:
i m s x perform case insensitive string comparison multi-line mode a dot matches any character, including new line extended mode (see below)
The $FLDS argument can be specified as one variable that will get a list value, or it can be specified as a list of as many variables as there are fields in the regular expression.
match_regex/4 example
match_regex(2007 02 04 mcell: RULES: xyz, [0-9]* [0-9]* [0-9]* ([^:]*): ([^:]*): .*,,$FLDS);
The input string, which could be part of a trace, matches the regular expression. The two fields are collected in $FLDS as [mcell,RULES].
156
String manipulation
match_regex/5 match a string with a regular expression and retrieve a given number of fields from it
match_regex($STR,$REGEX,$OPTS,$FLDCNT,$FLDS) $FLDS=match_regex($STR,$REGEX,$OPTS,$FLDCNT)
Table 118
Argument $STR $REGEX $OPTS $FLDCNT $FLDS
match_regex/5 arguments
Mode input input input input output Type STRING STRING STRING INTEGER Description specifies the string to be matched specifies the regular expression to match to the string specifies the options for how the regular expression engine operates requested number of fields to be retrieved
Use match_regex/5 to match a string $STR with regular expression $REGEX applying options from $OPTS and to collect the first $FLDCNT retrieved fields in $FLDS.
NOTE
The regular expression $REGEX must be compliant with the Perl Compatible Regular Expression specification. For a specification, see http://perldoc.perl.org/perlre.html.
The options argument can be either an empty string or a sequence of any of the following option indicators:
i m s x perform case insensitive string comparison multi-line mode a dot matches any character, including new line extended mode (see below)
The $FLDS argument can be specified as one variable that will get a list value, or it can be specified as a list of $FLDCNT variables.
match_regex/5 example
match_regex(2007 02 04 mcell: RULES: xyz, [0-9]* [0-9]* [0-9]* ([^:]*): ([^:]*): .*,,1,[$FLD]);
The input string, which could be part of a trace, matches the regular expression. There are two fields, but only the first one is collected in $FLD as mcell.
Chapter 4
157
String manipulation
Table 119
Argument $FORMAT $ARGS $STR
sprintf/3 arguments
Mode input input Type STRING Description specifies the format for the resulting string resulting string
output STRING
Use sprintf/3 to print a list of arguments specified in $ARGS into the $STR argument using the format specified in $FORMAT. The format specification for sprintf/3 is the same as for the C language sprintf() function.
WARNING
The arguments specified in $ARGS must be compliant with the specified format. Passing incompatible arguments can cause a crash of the cell.
sprintf/3 example
sprintf($E.msg,Event #%x,[$E.event_handle]);
The msg slot is set to the event number in hexadecimal notation (%x format).
mapslots/4 format a series of expressions that refer to event and data objects into a string
$STR=mapslots($OBJECTS,$FORMAT,$EXPRS)
158
String manipulation
Use mapslots/4 to evaluate a list of expressions $EXPRS, referring to objects from $OBJECTS, and to format them into string $STR using format $FORMAT. The format specification for mapslots/4 is the same as for the C language sprintf() function. The expressions given in $EXPRS are compiled and evaluated at the moment the primitive is called, each time mapslots/4 is called. Within these expressions, the objects from $OBJECTS can be referenced as $1, $2,... for the first, second,... element of the object list. The values resulting from the evaluation of the expressions, have to be compliant with the specified format. Incompatible expression evaluation results, can cause a crash of the cell.
mapslots/4 example
$STR = mapslots([$E,$D],Event %s is associated to data %s, [$1.mc_ueid,$2.mc_udid]);
A message is produced stating that an event and data object are associated. The event and data object are passed as $E and $D, respectively, in the first argument. The list of expressions contains two expressions that result in a string. The first one retrieves the mc_ueid slot of the event object, the second one retrieves the mc_udid of the data object.
Use mapslots/3 to evaluate a list of expressions $EXPRS, referring to objects from $OBJECTS, and to format them into string $STR using the first expression as format. The format specification for mapslots/3 is the same as for the C language sprintf() function.
Chapter 4
159
String manipulation
The first element from the list $EXPRS is taken as format. The rest of the expressions given in $EXPRS are compiled and evaluated at the moment the primitive is called, for each call again. Within these expressions, the objects from $OBJECTS can be referenced as $1, $2,... for the first, second,... element of the object list.
WARNING
The values resulting from the evaluation of the expressions must be compliant with the specified format. Incompatible expression evaluation results can cause a crash of the cell.
mapslots/3 example
$STR = mapslots([$E,$D], [Event %s is associated to data %s,$1.mc_ueid,$2.mc_udid]);
A message is produced stating that an event and data object are associated. The event and data object are passed as $E and $D, respectively, in the first argument. The list of expressions contains the format for the message, followed by two expressions that result in a string. The first one retrieves the mc_ueid slot of the event object, the second one retrieves the mc_udid of the data object.
Use has_substring/2 to determine if the string specified by $STRING has the value of $SUBSTRING as a substring or to determine if at least one of the strings of the list specified by $LIST has the value of $SUBSTRING as a substring. The has_substring/2 primitive succeeds or fails depending on whether or not the substring occurs.
160
String manipulation
has_substring/2 example
if ( has_substring($E.msg,NGP) ) ...
This example searches the msg slot of the event being processed to determine if the slot has NGP as a substring, in upper case.
has_substring/3verify the occurrence of a substring within a string or list of strings using a comparison modifier
has_substring($STRING,$SUBSTRING,$MODS) has_substring($LIST,$SUBSTRING,$MODS)
You can use has_substring/3 to determine if the string specified by $STRING has the value of $SUBSTRING as a substring or to determine if at least one of the strings of the list specified by $LIST has the value of $SUBSTRING as a substring with the comparison modified as determined in the list $MODS. The list $MODS can contain either or both of the following keywords to specify the corresponding comparison modification. By default, comparison of strings is case sensitive.
Comparison modifier IGN_CASE IGN_BLANK Description ignore case, perform case insensitive comparison ignore blank, white space in string comparison
The has_substring/3 primitive succeeds or fails depending on whether or not the substring occurs.
Chapter 4
161
has_substring/3 example
select [event_handle,CLASS,msg] from EVENT where [has_substring([$THIS.mc_object_class,$THIS.mc_tool_class],NGP, [IGN_CASE]) ] END
This example searches for events that have NGP as a substring of their mc_object_class or mc_tool_class slots. This command will find any instance of NGP because the case insensitive modifier is specified.
Use time_stamp/1 to retrieve the current system time as a time stamp in $TIME.
time_stamp/1 example
$TM = time_stamp();
162
Use time_stamp_to_cim/2 to convert a time stamp given in $TIME to a string $CIM containing the time stamp in CIM (Common Information Model) format. The CIM format is YYYYMMDDhhmmssuuuuuu+zzz, where:
YYYY MM DD hh mm ss uuuuuu + zzz Year (including century) Month (1..12) Day of month (1..31) Hour (0..23) Minutes (0..59) Seconds (0..61) (value >59 in case of leap seconds) Micro-seconds (0..999999) Time zone offset direction from UTC (+ or -) Time zone offset from UTC in minutes
time_stamp_to_cim/2 example
$CIM = time_stamp_to_cim(time_stamp());
Use time_stamp_to_str/3 to convert a time stamp given in $TIME, to a string $STR containing the time stamp in the format specified in $FORMAT. The format specification for time_stamp_to_str/3 is the same as for the C language
strftime() function.
Chapter 4
163
time_stamp_to_str/3 example
time_stamp_to_str(time_stamp(),%c,$TM);
The current time is formatted in the appropriate date and time representation for the current locale.
Use time_stamp_to_str/2 to convert the time stamp specified in $TIME to a string $STR containing the time stamp in the format specified in the configuration parameter DateFormat.
time_stamp_to_str/2 example
time_stamp_to_str(time_stamp(),$TM);
The current time is formatted as specified in DateFormat. The default value for DateFormat is CIM.
164
Description specifies the field or list of fields to be retrieved retrieved field value or list of retrieved field values
Use time_extract/3 to retrieve one or more fields as specified in $FLDS from the time stamp $TIME into the $VALS argument. The time stamp is a time value in internal numeric form, similar to the
date_reception slot, or as retrieved from the time_stamp/1 primitive. The fields
retrieved from the time stamp reflect the local actual time zone of the system on which the cell is running. Time stamp fields are indicated by name. Available fields are:
date time year month day wday yday hour min sec Date part as an integer of the form YYYYMMDD Time part as an integer of the form HHMMSS Year (including century) Month (1..12) Day of month (1..31) Day of week (0..6, 0=Sunday) Day of year (1..366) Hour (0..23) Minutes (0..59) Seconds (0..61) (value >59 in case of leap seconds)
All returned field values are integer numbers. Note that the values for the date and time fields are also integers, structured in a fixed decimal format. A time value will not always have six significant digits. Times before 10:00:00 only have five significant decimal digits. The $VALS argument can be specified as one variable that will get the single requested field value or a list containing all requested field values. $VALS can also be specified as a list of as many variables as the number of requested fields.
time_extract/3 example
time_extract($E.date_reception,[date,time],[$DT,$TM]);
Variables $DT and $TM will contain the date and time of the time stamp, as integers, for the time the event was received. For instance, if the event was received on 6-Feb2007 at 9:15:20, $DT would be 20070206 and $TM would be 91520.
Chapter 4 Master Rule Language (MRL) reference 165
Use str_to_time_stamp/3 to parse a date/time value from the string $STR, formatted as specified in $FORMAT, and convert to a time stamp in $TIME. The format specification for str_to_time_stamp/3 is the same as for the C language
strptime() function.
If the time is partly or completely missing, zero values are assumed for the missing time component(s). If the date is specified incompletely, a date is calculated from the partial specification and the current time stamp. Whenever possible, the missing parts are determined such that, in combination with the specified time, a time stamp in the future is indicated, using the following rules:
I
If the date is specified as a week of the year, the date is calculated as the first day of that week that results in a future time stamp. If that is not possible, the date is specified as the first day of that week. If the date is specified as a day of the week, the date is calculated as the day of current or next week. If the year is missing from the date, it is assumed to be the current or next year. If the month is missing from the date, it is assumed to be the current or next month. If the day is missing from the date, it is assumed to be the current or next day.
If the date is missing completely, the current date or the first next date is assumed, depending on whether the time value is after or before the current time.
166
List operations
str_to_time_stamp/3 example
str_to_time_stamp($E.date,%c,$TM);
The date slot is parsed to a numeric time stamp value, if it is formatted in the appropriate date and time representation for the current locale.
List operations
listlen/2 determine the length of a list
listlen($LIST,$LEN) $LEN=listlen($LIST)
Use listlen/2 to determine the length of the list $LIST and return the length (in characters) in the $LEN argument.
listlen/2 example
$CNT_BAD_SLOTS=listlen($E.mc_bad_slot_names);
Chapter 4
167
List operations
output ANY
Use listgetelt/3 to retrieve the element at position $POS in list $LIST and return it into $ELEM. The first element in the list is numbered as 1.
listgetelt/3 example
$BAD_SLOT2=listgetelt($E.mc_bad_slot_names,2);
Use listmember/2 to verify whether or not an element $ELEM occurs in list $LIST. This primitive succeeds or fails depending on whether the element occurs in the list or not.
listmember/2 example
if ( listmember($E.mc_bad_slot_names,my_slot) ) ...
168
List operations
output LIST_OF ANY the list with the element removed from it
Use listdelete/3 to remove all occurrences of element $ELEM from list $LIST1 and place the resulting list into $LIST.
listdelete/3 example
$BAD_SLOTS=listdelete($E.mc_bad_slot_names,my_slot);
Use listappend/3 to concatenate list $LIST1 and list $LIST2 into list $LIST. The elements in both lists must be the same type.
listappend/3 example
$BAD_SLOTS=listappend($E.mc_bad_slot_names,$E.mc_bad_slot_values);
listdisjoint/2 verify that two lists do not have any common elements
listdisjoint($LIST1,$LIST1)
Chapter 4
169
List operations
Use listdisjoint/2 to verify if two lists $LIST1 and $LIST2 are disjoint. The two lists are disjoint if they have no common elements. This primitive succeeds or fails depending on whether the lists are disjoint or not. The elements in both lists must be the same type.
listdisjoint/2 example
if ( listdisjoint($E.mc_bad_slot_names,[my_slot1,my_slot2]) ) ...
output LIST_OF ANY list of the common elements of $LIST1 and $LIST2
Use listintersect/3 to construct a new list $LIST which is the intersection of lists $LIST1 and $LIST2. The intersection of the two lists is the list that contains all the elements that are common to both lists. The elements in both lists must be the same type.
170
List operations
listintersect/3 example
$MY_BAD_SLOTS=listintersect($E.mc_bad_slot_names,[my_slot1,my_slot2]);
Use listunion/3 to construct a new list $LIST which is the union of lists $LIST1 and $LIST2. The union of $LIST1 and $LIST2 will include all the elements of both lists. If there are elements duplicated between the two lists, the duplicated elements will only be listed once in $LIST. If there are elements duplicated within a single list, those elements will be duplicated in the resulting list. For example, the union of these two lists:
$LIST1=[a,b,a,c] $LIST2=[b,d,e,e]
$LISTcontains two a characters because $LIST1 has two a characters. $LISTcontains two e characters because $LIST2 has two e characters. $LISTcontains only one b because there is one b in $LIST1 and one b in $LIST2.
listunion/3 example
$MY_BAD_SLOTS=listunion($E.mc_bad_slot_names,[my_slot1,my_slot2]);
listsubtract/3 remove the elements that occur in one list from another list
listsubtract($LIST1,$LIST2,$LIST) $LIST=listsubtract($LIST1,$LIST2)
Chapter 4
171
List operations
Use listsubtract/3 to construct a new list $LIST that contains all elements from list $LIST1 that do not occur in $LIST2. The elements in both lists must be the same type.
listsubtract/3 example
$MY_BAD_SLOTS=listsubtract($E.mc_bad_slot_names,[my_slot1,my_slot2]);
Use listremdup/2 to construct a new list $LIST that contains all the elements from list $LIST1 without duplicates.
listremdup/2 example
$MY_BAD_SLOTS=listremdup($E.mc_bad_slot_names);
172
List operations
Use listwalk/2 to go through each element in list $LIST, returning each element in $ELEM. All instructions following the call of listwalk/2 are executed for each element.
listwalk/2 example
$E.msg = Bad slot names:; listwalk($E.mc_bad_slot_names,$SLTNM); concat([$E.msg, ,$SLTNM],$E.msg);
The msg slot is filled with the sequence of bad slot names.
Use add_to_list/2 to add the value of $ELEM as the first element of the list slot $LISTSLOT. This primitive fails if the indicated slot is not a list slot, or if the type of the element does not correspond to the type of the elements of the list.
Chapter 4
173
add_to_list/2 example
add_to_list(my_slot,$E.mc_bad_slot_names);
Use rem_from_list/2 to remove the first occurrence of the value in $ELEM from the list slot specified in the $LISTSLOT argument. This primitive fails if the indicated slot is not a list slot, or if the type of the element does not correspond to the type of the elements of the list.
rem_from_list/2 example
rem_from_list(my_slot,$E.mc_bad_slot_names);
174
Use find_match/5 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 is 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 highest precedence is selected, using the following precedence rules:
I
A match for the nth element has precedence over a match for the n+1th 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.
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 this example, there are several instances of BEM_MATCH_TABLE, including the following:
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.
find_match(BEM_MATCH_TABLE,t1,[$E.mc_object_class,$E.mc_object], [$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 with the BEM_MATCH_TABLE entry shown above. 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.
176
Use find_match_entry/4 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 $VALUES. The entry is returned in $ENTRY. For a description on how a matching entry is found, see find_match/5 find an entry in a match table and retrieve calculated values from it on page 174. Use apply_match_entry/4 to obtain the output values from the matching entry as described in apply_match_entry/4 obtain output values from a match table entry on page 178.
find_match_entry/4 example
In this example, there are several instances of BEM_MATCH_TABLE, including the following:
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.
$M = find_match_entry(BEM_MATCH_TABLE,t1, [$E.mc_object_class,$E.mc_object]);
This call will return a reference to the match table entry in $M.
Chapter 4
177
Use apply_match_entry/4 to obtain the output values from the match table entry $ENTRY. The input values $VALUES and the objects $OBJECTS are to be used in the evaluation of the output expressions. The results of this evaluation of output expressions for the match table entry are returned in $RESULTS. The input values $VALUES are required only for the evaluation of the output expressions. For a description on how a matching entry is found, see find_match/5 find an entry in a match table and retrieve calculated values from it on page 174. The match table entry is obtained using find_match_entry/4 as described in find_match_entry/4 find an entry in a match table on page 176.
apply_match_entry/4 example
In this example, there are several instances of BEM_MATCH_TABLE, including the following:
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
178
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.
$M = find_match_entry(BEM_MATCH_TABLE,t1, [$E.mc_object_class,$E.mc_object]);
This call will return a reference to the match table entry in $M.
apply_match_entry($M,[$E.mc_object_class,$E.mc_object], [$E,$D],[$MSG,$SEV]); $E.msg = $MSG; $E.severity = $SEV;
The event and data object references are passed through the third 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.
Use get_list_slotvalues/3 to retrieve one or more of the slots specified in the $SLOTS list from the objects in $OBJECTS. The resulting slots are returned in the $VALUES list.
Chapter 4
179
The desired slots must be specified in $SLOTS by name, or by reference to an object and the slot name. A reference to a slot of an object has the form $n.SlotName, where n is the sequence number of the desired object in $OBJECTS. If the slot is only mentioned by name and no object reference, it is taken from the first object in the list.
get_list_slotvalues/3 example
$VALUES = get_list_slotvalues([$E,$D],[mc_ueid,status]);
The list $VALUES will contain the mc_ueid and the status slot from the event object $E.
$VALUES = get_list_slotvalues([$E,$D], [$1.mc_ueid,$1.status,$2.mc_udid]);
The list $VALUES will contain the mc_ueid and the status of the event object $E, and the mc_udid of the data object $D.
Use set_list_slotvalues/3 to assign one or more values from the list $VALUES to the slots listed in $SLOTS for the objects in $OBJECTS. The desired slots must be specified in $SLOTS by name, or by reference to an object and the slot name. A reference to a slot of an object has the form $n.SlotName, where n is the sequence number of the desired object in $OBJECTS. If the slot is only mentioned by name and no object reference, it is taken from the first object in the list. The slot and values lists must contain the same number of elements.
180
set_list_slotvalues/3 example
set_list_slotvalues([$E,$D],[status,msg],[CLOSED,done]);
The status slot of the event object $E is set to CLOSED, and its msg slot is set to done.
set_list_slotvalues([$E,$D],[$1.status,$1.msg,$2.name], [CLOSED,done,john]);
The status slot of the event object $E is set to CLOSED, and its msg slot is set to done. The name slot of the data object $D is set to john.
Use class_path/2 to obtain the complete class hierarchy of the class specified in $CLASS and return the hierarchy in $PATH.
$PATH is a list of class names that starts with the class specified in $CLASS. The next element in the list is the direct super class for $CLASS, and so on, up to the root class.
class_path/2 example
class_path(MC_CELL_ACTION_RESULT,$PATH);
Chapter 4
181
Use reset_default/1 to reset slot $SLOT to its default value. The default value is as specified in the class definition.
reset_default/1 example
reset_default($E.severity);
Use ntadd/2 to add a note with text $SLOT to the event $EVENT. The note is added to the mc_notes slot of the event and time stamped with the current time. The author of the note is set to the identifier of the rule that calls the primitive.
ntadd/2 example
ntadd($E,Event updated by rule);
182
Use ntcnt/2 to count the notes that are attached to event $EVENT, in $COUNT.
ntcnt/2 example
ntcnt($E,$NR_OF_NOTES);
ntget/5 return the time stamp, author, and text of a note attached to an event
ntget($EVENT,$SEQNR,$TIME,$AUTHOR,$TEXT)
INTEGER specifies the sequence number of the desired note INTEGER time stamp of the note STRING STRING author of the note text of the note
Use ntget/5 to obtain the note at the $SEQNR position that is attached to event $EVENT. The time stamp is returned in $TIME, the author is returned in $AUTHOR, and the text of the note is returned in $TEXT. Notes are numbered, starting from 1 for the oldest note. The most recent note can be obtained by specifying 0 as sequence number $SEQNR. To determine the number of notes attached to an event, see ntcnt/2 count the notes attached to an event on page 182.
ntget/5 example
ntget($E,0,$TIME,$AUTHOR,$SLOT);
Chapter 4
183
Use ntset/3 to replace the text of the note in the $SEQNR position with the text $TEXT for the event $EVENT. Notes are numbered, starting from 1 for the oldest note. The most recent note can be obtained by indicating 0 as sequence number.
NOTE
Only the text of a note can be replaced. The time stamp and author cannot be modified.
ntset/3 example
ntset($E,0,New explanation);
Use opadd/4 to add an operation for policy $POLICY with action name $ACTION and argument list $ARGS to event $EVENT. The operation is added to the mc_operations slot of the event and time stamped with the current time. The author of the operation is set to the identifier of the rule that calls the primitive. The argument list must be formatted as a string. $ARGS can be an empty string if no arguments are needed.
184 BMC Knowledge Base Development Reference Guide
opadd/4 example
opadd($E,Policy1,Data Enrichment,);
Use opadd/3 to add an operation with action name $ACTION and argument list $ARGS to event $EVENT. The operation is added to the mc_operations slot of the event and time stamped with the current time. The author of the operation is set to the identifier of the rule that calls the primitive. The argument list must be formatted as a string. $ARGS can be an empty string if no arguments are needed.
opadd/3 example
opadd($E,AcknowledgeEvent,);
Use opcnt/2 to count the operations that are attached to event $EVENT and return the number in $COUNT.
Chapter 4
185
opcnt/2 example
opcnt($E,$NR_OF_OPS);
Use opget/7 to obtain operation $SEQNR that is attached to event $EVENT. The time stamp is returned in $TIME, the author is returned in $AUTHOR, the policy name is returned in $POLICY, the action name is returned in $ACTION, and the argument list is returned in $ARGS. Operations are numbered, starting from 1 for the oldest operation. The most recent operation can be obtained by indicating 0 as the sequence number $SEQNR. To determine the number of operations attached to an event, see opcnt/2 count the operations of an event on page 185.
opget/7 example
opget($E,0,$TIME,$AUTHOR,$POLICY,$ACTION,$ARGS);
186
Use opget/6 to obtain operation $SEQNR that is attached to event $EVENT. The time stamp is returned in $TIME, the author is returned in $AUTHOR, the action name is returned in $ACTION, and the argument list is returned in $ARGS. Operations are numbered, starting from 1 for the oldest operation. The most recent operation can be obtained by indicating 0 as the sequence number $SEQNR. To determine the number of operations attached to an event, see opcnt/2 count the operations of an event on page 185.
opget/6 example
opget($E,0,$TIME,$AUTHOR,$ACTION,$ARGS);
Use opget_time/3 to obtain the time stamp of the operation $SEQNR that is attached to event $EVENT and return the time stamp in $TIME. Operations are numbered, starting from 1 for the oldest operation. The most recent operation can be obtained by indicating 0 as sequence number.
Chapter 4
187
opget_time/3 example
$TIME=opget_time($E,0);
Use opget_author/3 to obtain the author of operation $SEQNR that is attached to event $EVENT and return the value in $AUTHOR. Operations are numbered, starting from 1 for the oldest operation. The most recent operation can be obtained by indicating 0 as the sequence number $SEQNR. To determine the number of operations attached to an event, see opcnt/2 count the operations of an event on page 185.
opget_author/3 example
$AUTHOR=opget_author($E,0);
Use opget_action/3 to obtain the action name of operation $SEQNR that is attached to event $EVENT and return the value in $ACTION.
188
Operations are numbered, starting from 1 for the oldest operation. The most recent operation can be obtained by indicating 0 as the sequence number $SEQNR. To determine the number of operations attached to an event, see opcnt/2 count the operations of an event on page 185.
opget_action/3 example
$ACTION=opget_action($E,0);
Use opget_args/3 to obtain the argument list of operation $SEQNR that is attached to event $EVENT and return the value in $ARGS. Operations are numbered, starting from 1 for the oldest operation. The most recent operation can be obtained by indicating 0 as the sequence number $SEQNR. To determine the number of operations attached to an event, see opcnt/2 count the operations of an event on page 185.
opget_args/3 example
$ARGS=opget_args($E,0);
opset/5 modify the policy name, action, and arguments of an operation of an event
opset($EVENT,$SEQNR,$POLICY,$ACTION,$ARGS)
Chapter 4
189
Use opset/5 to replace the policy name, action name and arguments of operation $SEQNR that is attached to event $EVENT. The policy name is replaced with $POLICY, the action name is replaced with $ACTION, and the argument list is replaced with $ARGS. Operations are numbered, starting from 1 for the oldest operation. The most recent operation can be obtained by indicating 0 as the sequence number $SEQNR. To determine the number of operations attached to an event, see opcnt/2 count the operations of an event on page 185.
NOTE
The time stamp and author of an operation cannot be modified.
opset/5 example
opset($E,0,Policy2,Data Enrichment,);
190
Use opset/4 to replace the action name and arguments of operation $SEQNR that is attached to event $EVENT. The action name is replaced with $ACTION, and the argument list is replaced with $ARGS. Operations are numbered, starting from 1 for the oldest operation. The most recent operation can be obtained by indicating 0 as the sequence number $SEQNR. To determine the number of operations attached to an event, see opcnt/2 count the operations of an event on page 185.
NOTE
The time stamp and author of an operation cannot be modified.
opset/4 example
opset($E,0,CloseEvent,);
Use relate/1 to establish a relation between event $EVENT and the source event set in its mc_relation_source slot. The type of relation is determined by the class of this event or its most specific super-class that has a defined type of relation. The result of this operation is that the type of relation and the mc_ueid of this event are added to the mc_event_relations slot of the source event. For the relation to be established, the mc_relation_source slot of the related event must be set correctly. The agent that produces the related event would usually set the mc_relation_source slot. However, the fact that this slot has a non-empty value does not imply that this event is effectively related to the event indicated in this slot.
Chapter 4
191
relate/1 example
This example involves establishing a relation for trouble tickets. If an event results in a trouble ticket being created at the Help Desk, the trouble ticketing system generates a corresponding trouble ticket event that is related to the source event with relation tt_HD. Definition of the relation:
MC_EVENT_RELATION; type=tt_HD; class=HD_TROUBLE_TICKET; END
When a trouble ticket event is received, the following rule will relate it to its source event:
refine HD_trouble_ticket_relate : HD_TROUBLE_TICKET($E) { relate($E); } END
This assumes that the HD_TROUBLE_TICKET event contains the mc_ueid of the source event in its mc_relation_source slot. The type of the relation will be tt_HD.
Use unrelate/1 to remove the relation of $EVENT to the source event as specified in the mc_relation_source slot for $EVENT. The relation information is removed from the mc_event_relations slot of the source event. The mc_relation_source slot is not modified.
NOTE
The rule that unrelates an event could also clear the mc_relation_source slot to clarify the fact that the event is not related anymore. The mc_relation_source slot is not cleared automatically by the unrelate/1 primitive.
192
unrelate/1 example
This example involves establishing a relation for trouble tickets. If an event results in a trouble ticket being created at the Help Desk, the trouble ticketing system generates a corresponding trouble ticket event that is related to the source event with relation tt_HD. Definition of the relation:
MC_EVENT_RELATION; type=tt_HD; class=HD_TROUBLE_TICKET; END
When a trouble ticket event is received, the following rule will relate it to its source event:
refine HD_trouble_ticket_relate : HD_TROUBLE_TICKET($E) { relate($E); } END
This assumes that the HD_TROUBLE_TICKET event contains the mc_ueid of the source event in its mc_relation_source slot. The type of the relation will be tt_HD. In this scenario, the following rule will undo the relation of a trouble ticket event to its source, when the trouble ticket event is not open anymore:
execute HD_trouble_ticket_unrelate : HD_TROUBLE_TICKET($E) when $E.status != OPEN { unrelate($E); } END
Chapter 4
193
Use cellinfo/2 to obtain information item specified in $FIELD and return the information in $INFO. The following information fields are defined:
HomeDir HostName IPAddress Platform CellName CellRelease CellBuild CellDate Param LogDir Location TmpDir KBDir DirFile ConfigFile TraceDestination home directory of the cell name of the host machine on which cell is running IP address of the host machine on which cell is running platform identifier of the host machine on which cell is running name of the cell release version of the cell build number of this version of the cell build date of this version of the cell value of configuration parameter Param log directory of the cell IP address or port number of the cell service temporary directory of the cell KB directory of the cell directory file (mcell.dir) of the cell configuration file of the cell list of defined trace destination files (of the type LIST_OF STRING)
cellinfo/2 example
$E.mc_host = cellinfo(HostName);
194
cellcontrol/1 example
cellcontrol(pause);
Use kbversion/2 to obtain the version information for the KB module $MODULE and return the version in $VERSION. If no version information is available, the empty string is returned. If the module name is specified as an empty string, the global KB module is assumed.
Chapter 4
195
kbversion/2 example
kbversion(TroubleTicketing,$VERSION);
Use kbversion/1 to obtain the version information for the global KB module and return the version in $VERSION. If no version information is available, the empty string is returned.
kbversion/1 example
kbversion($VERSION);
Table 171
$ENVVAR $VALUE
get_env/2 arguments
Type STRING STRING Description specifies the environment variable name for which the value is to be retrieved value of the environment variable input output
Argument Mode
Use get_env/2 to obtain the value of environment variable $ENVVAR and return the value in $VALUE. If the specified variable is not defined in the environment, the empty string is returned.
196
Propagation
get_env/2 example
$HOME = get_env(HOME);
Propagation
send_to/2 send an event to another cell or gateway
send_to($DEST,$EVENT)
Description
STRING specifies a single destination or a list of possible LIST_OF STRING destinations for the event specifies the event to send
input OBJECT
Use send_to/2 to send event $EVENT to destination $DEST. The destination must be specified by name. If $DEST is a list of destination names, the event modification is sent to the first destination that can be reached. When sending an event with send_to/2, event modifications will not be propagated automatically, either forward or backward.
send_to/2 example
send_to([Cell2,Cell3],$E);
Description
STRING specifies a single destination or a list of possible LIST_OF STRING destinations for the event specifies the event to send specifies a list of modified slots to send
Chapter 4
197
Propagation
Use send_to/3 to send modifications of slots $SLOTS of event $EVENT to destination $DEST. The destination must be specified by name. If $DEST is a list of destination names, the event is sent to the first destination that can be reached. Only the slots that are explicitly indicated will be sent to the destination, in the form of an event modification.
send_to/3 example
send_to([Cell2,Cell3],$E,[status,severity]);
send_to_ext($DEST,$EVENT,$SLOTS,$VALS)
Table 174
$DEST $EVENT $SLOTS $VALS
send_to_ext/4 arguments
Type
I I
Description specifies a single destination or a list of possible destinations for the event specifies the event to send specifies a list of extended slot names to send specifies a list of extended slot values to send
Use send_to_ext/4 to send event $EVENT to destination $DEST, extending the event with the slots specified in $SLOTS and with the corresponding values from $VALS. The destination must be specified by name. If $DEST is a list of destination names, the event is sent to the first destination that can be reached. Besides the regular event slots, defined in the class of the event, additional slots are included in the message that is sent to the destination. The additional slot names are taken from $SLOTS, with corresponding values from in $VALS. The destination should be able to understand the extended event.
198
Propagation
When sending an event with send_to_ext/4, event modifications will not be propagated automatically, either forward or backward.
send_to_ext/4 example
send_to_ext([Cell2,Cell3],$E,[slot1,slot2],[value1,value2]);
$DestNM
input
STRING
$ID
output
INTEGER
Use the propagated_to/3 primitive to determine whether or not the object handle specified in $Object has been propagated to destination $DestNM. If the object has been successfully propagated, $ID will contain the identifier of the event at that destination, which is a strictly positive number. If the event has not been successfully propagated to the specified destination, the value of $ID will be 0.
propagated_to/3 example
The following example will output a list of events that were successfully propagated to destination dest.
mquery -n CellName -a EVENT -w 'propagated_to($THIS,dest) > 0'
Chapter 4
199
smcomps($PARMNAMES,$PARMVALS,$COMPS1,$SHADOWS,$COMPS2)
Table 176
Argument
smcomps/5 arguments
Mode input input output output output Type Description LIST_OF STRING list of parameter names LIST_OF STRING list of parameter values LIST_OF OBJECT list of primary search components LIST_OF OBJECT list of shadow components LIST_OF OBJECT list of secondary search components
Use the smcomps/5 primitive to return a list of pointers to the components that are in the impact path or the cause path of a selected component. Various parameters can be used to refine that list. The smcomps/5 primitive makes it possible to retrieve, manage and propagate a list of impacted components or causal components from within the rules of a Knowledge Base.
NOTE
You can also retrieve root causes using MC_SM_ROOT_CAUSE instead of smcomps.
smcomps/5 searches for Service Model components as specified by the $PARMNAMES and $PARMVALS argument values. The result is returned as a list of primary search components $COMPS1, a list of shadow components $SHADOWS, and a list of secondary search components $COMPS2.
200
The two parameter liststhe $PARMNAMES list that contains only the names of the parameters and the $PARMVALS list that contains the values corresponding to the parameters named in $PARMNAMES in the same orderdetermines the search behavior. Available parameter names and possible values are:
comp dir mc_udid of the focus Service Model component data object. Default value is 0; therefore you must enter a valid value for this parameter.
c | i where c=cause and i=impact. Default direction value is c. impact t | p where t=true impact and p=possible impact. Default impact type is p. events T | F where T=True and F=False. Default value is F (it is not requested that the
components have attached events). ext leaf type
T | F where T=True and F=False. Default value is F (extended search is not turned on). T | F where T=True and F=False. Default value is F (leaf nodes are not required).
component class name. Default is the BMC_BaseElement class.
The smcomps primitive retrieves components, starting with the focus component identified by comp, in direction specified by dir. The other parameters influence whether or not a component is included in the result, and whether or not the search is continued. A component is included if each of the following conditions hold:
I
The component must be an instance of the class given in the type parameter or one of its subclasses. When the events parameter is set to T, only components with attached event(s) (components with self_status!=NONE) are retrieved by smcomps. When the leaf parameter is set to T, only leaf components (components with self_status > impact_status) are retrieved.
In an impact direction search, shadowed components (components with shadow_cells not empty) are always included, regardless of the above conditions. The search is terminated if any of the following conditions hold:
I
if true impact is requested through the impact parameter (impact=t), but the relationship does not have true_impact=YES. if leaf components were requested (leaf = T) and a leaf component has been found
If an extended search is requested through the ext parameter (ext=T) and the primary search is terminated at the focus component, a secondary search is performed, continuing after the focus component under the same conditions.
Chapter 4
201
The $SHADOWS list contains shadow components (components with scope=SHADOW). Such components are included in the result without checking any constraints. The $COMPS2 list contains the components returned from the secondary search and is empty if no extended search was requested. It can only be non-empty if the list $COMPS1 is either empty or only contains the focus component. $SHADOWS and $COMPS2 normally are not used in the context of MRL. The smcomps primitive does not cross cell boundaries.
smcomps/5 example
smcomps([comp,dir,impact,events,leaf],[comp123,i,t,T,T],$COMPS,$SHADOW,$C2); listwalk($COMPS,$COMP); concat([$MSG,' ',$COMP.mc_udid],$MSG);
In this example, a listwalk of the result list is performed to save the mc_udids in a slot of the event. You can then retrieve the desired properties from the components by a using clause referencing the udids.
Use key_version/2 to retrieve the version number from license key $KEY and return it in $VERSION. A license key is a string containing licensing information, as provided by BMC Software. An application that requires a license key can support multiple versions of the license key. Each version can have different restrictions or result in different behavior. With this primitive, the application can retrieve the version of a key and behave according to the returned version.
202
key_version/2 example
key_version($KEY,$VERSION); if ( $VERSION == 1 ) then ...
Use key_verify/2 to validate license key $KEY and to retrieve fields from the license key in $FIELDS. A license key is a string containing licensing information, as provided by BMC Software. The application is responsible to determine the exact number of fields that are expected in the key. The $FIELDS argument has to be specified as a list of as many variables as the number of fields. This primitive will fail if the key is invalid or if the number of fields is not exact. It can be used in an if-statement to test for success.
key_verify/2 example
if ( key_verify($KEY,[$FLD1,$FLD2]) ) then ...
Chapter 4
203
Use key_verify/3 to determine the validity of license key $KEY in $VALID, and to retrieve fields from the key and return them in $FIELDS. A license key is a string containing licensing information, as provided by BMC Software. The application is responsible to determine the exact number of fields that are expected in the key. The $FIELDS argument has to be specified as a list of as many variables as the number of fields. If the key is invalid, or if the number of fields is not exact, $VALID will be set to 0. Otherwise it will be set to 1.
key_verify/3 example
key_verify($KEY,[$FLD1,$FLD2],$VALID); $LICDATA.key_validity = $VALID;
Description
I I I I
time frame name list of time frame names time frame object list of time frame objects
Use tf_active/1 to determine whether the time frame(s) $TIMEFRAME is active at the current moment.
204
A time frame can be specified with its object handle or by name. One or multiple time frames can be specified. If multiple time frames are specified, they must all be specified by either object or name. The primitive will fail if the indicated time frame(s) are not all active.
tf_active/1 example
if ( tf_active($TF) ) then ...
tf_active/2 verify if one or more time frames are active at a given time
tf_active($TIMEFRAME,$TIME)
Description
I I I I
time frame name list of time frame names time frame object list of time frame objects
$TIME
input
INTEGER
Use tf_active/2 to determine whether time frame(s) $TIMEFRAME is active at time $TIME. A time frame can be specified with its object handle or by name. One or multiple time frames can be specified. If multiple time frames are specified, they must all be specified by either object or name. The primitive will fail if the indicated time frame(s) are not all active at the indicated time.
tf_active/2 example
if ( tf_active($TF,$TIME) ) then ...
tf_udid_active/1 verify if one or more time frames specified by mc_udid are active at the current time
tf_udid_active($TIMEFRAME)
Chapter 4
205
Description
I I
Use tf_udid_active/1 to determine whether the time frame(s) $TIMEFRAME is active at the current time. A time frame is specified with its mc_udid. One or multiple time frames can be specified. The primitive will fail if the indicated time frame(s) are not all active.
tf_udid_active/1 example
if ( tf_udid_active([TF.001,TF.002]) ) then ...
tf_udid_active/2 verify if one or more time frames specified by mc_udid are active at a specified time
tf_udid_active($TIMEFRAME,$TIME)
Description
I I
INTEGER
Use tf_udid_active/2 to determine whether time frame(s) $TIMEFRAME is active at time $TIME. A time frame is specified with its mc_udid. One or multiple time frames can be specified. The primitive will fail if the indicated time frame(s) are not all active at the indicated time.
206
tf_udid_active/2 example
if ( tf_udid_active([TF.001,TF.002],$TIME) ) then ...
tf_current_start/2 obtain the start time of the current active interval of a time frame
tf_current_start($TIMEFRAME,$START) $START=tf_current_start($TIMEFRAME)
Use tf_current_start/2 to obtain the start time of the current active interval of time frame $TIMEFRAME and return the start time in $START. A 0 value is returned if the indicated time frame is not active.
tf_current_start/2 example
$START = tf_current_start($TF);
tf_current_start/3 obtain the start time of the active interval of a time frame at a specified time
tf_current_start($TIMEFRAME,$TIME,$START) $START=tf_current_start($TIMEFRAME,$TIME)
INTEGER specifies the time for the active interval INTEGER start time of active interval at given time
Use tf_current_start/3 to obtain the start time of the active interval at $TIME, of time frame $TIMEFRAME in $START. A 0 value is returned if the indicated time frame is not active at the given time.
Chapter 4
207
tf_current_start/3 example
$START = tf_current_start($TF,$TM);
tf_current_end/2 obtain the end time of the current active interval of a time frame
tf_current_end($TIMEFRAME,$END) $END=tf_current_end($TIMEFRAME)
Use tf_current_end/2 to obtain the end time of the current active interval of time frame $TIMEFRAME in $END. A 0 value is returned if the indicated time frame is not active.
tf_current_end/2 example
$END = tf_current_end($TF);
tf_current_end/3 obtain the end time of the active interval of a time frame at a specified time
tf_current_end($TIMEFRAME,$TIME,$END) $END=tf_current_end($TIMEFRAME,$TIME)
Use tf_current_end/3 to obtain the end time of the active interval at $TIME of time frame $TIMEFRAME in $END. A 0 value is returned if the indicated time frame is not active at the given time.
208
tf_current_end/3 example
$END = tf_current_end($TF,$TM);
tf_current_interval/2 obtain the start and end time of the current active interval of a time frame
tf_current_interval($TIMEFRAME,$INTV) $INTV=tf_current_interval($TIMEFRAME)
Use tf_current_interval/2 to obtain the start and end time of the current active interval of time frame $TIMEFRAME in $INTV. Argument $INTV of the primitive must be specified as a list of two variables. A [0,0] value is returned if the indicated time frame is not active.
tf_current_interval/2 example
tf_current_interval($TF,[$START,$END]);
tf_current_interval/3 obtain the start and end time of the active interval of a time frame at a given time
tf_current_interval($TIMEFRAME,$TIME,$INTV) $INTV=tf_current_interval($TIMEFRAME,$TIME)
output LIST_OF INTEGER start and end time of active interval at the specified time
Chapter 4
209
Use tf_current_interval/3 to obtain the start and end time of the active interval at $TIME of time frame $TIMEFRAME in $END. Argument $INTV of the primitive, has to be specified as a list of two variables. A [0,0] value is returned if the indicated time frame is not active at the given time.
tf_current_interval/3 example
tf_current_interval($TF,$TM,[$START,$END]);
tf_prev_start/2 obtain the start time of the previous active interval of a time frame
tf_prev_start($TIMEFRAME,$START) $START=tf_prev_start($TIMEFRAME)
Use tf_prev_start/2 to obtain the start time of the previous active interval of time frame $TIMEFRAME in $START. A 0 value is returned if there is no previous active time frame.
tf_prev_start/2 example
$START = tf_prev_start($TF);
tf_prev_start/3 obtain the start time of the previous active interval of a time frame at a given time
tf_prev_start($TIMEFRAME,$TIME,$START) $START=tf_prev_start($TIMEFRAME,$TIME)
210
output INTEGER start time of previous active interval at the specified time
Use tf_prev_start/3 to obtain the start time of the previous active interval at $TIME, of time frame $TIMEFRAME in $START. A 0 value is returned if there is no previous active time frame at the given time.
tf_prev_start/3 example
$START = tf_prev_start($TF,$TM);
tf_prev_end/2 obtain the end time of the previous active interval of a time frame
tf_prev_end($TIMEFRAME,$END) $END=tf_prev_end($TIMEFRAME)
Use tf_prev_end/2 to obtain the end time of the previous active interval of time frame $TIMEFRAME in $END. A 0 value is returned if there is no previous active time frame.
Chapter 4
211
tf_prev_end/2 example
$END = tf_prev_end($TF);
tf_prev_end/3 obtain the end time of the previous active interval of a time frame at a given time
tf_prev_end($TIMEFRAME,$TIME,$END) $END=tf_prev_end($TIMEFRAME,$TIME)
output INTEGER end time of previous active interval at the specified time
Use tf_prev_end/3 to obtain the end time of the previous active interval at $TIME, of time frame $TIMEFRAME in $END. A 0 value is returned if there is no previous active time frame at the given time.
tf_prev_end/3 example
$END = tf_prev_end($TF,$TM);
tf_prev_interval/2 obtain the start and end time of the previous active interval of a time frame
tf_prev_interval($TIMEFRAME,$INTV) $INTV=tf_prev_interval($TIMEFRAME)
output LIST_OF INTEGER start and end time of the previous active interval
Use tf_prev_interval/2 to obtain the start and end time of the previous active interval of time frame $TIMEFRAME in $INTV.
212
Argument $INTV of the primitive, has to be specified as a list of two variables. A [0,0] value is returned if there is no previous active time frame.
tf_prev_interval/2 example
tf_prev_interval($TF,[$START,$END]);
tf_prev_interval/3 obtain the start and end time of the previous active interval of a time frame at a specified time
tf_prev_interval($TIMEFRAME,$TIME,$INTV) $INTV=tf_prev_interval($TIMEFRAME,$TIME)
Use tf_prev_interval/3 to obtain the start and end time of the previous active interval at $TIME of time frame $TIMEFRAME in $END. Argument $INTV of the primitive, has to be specified as a list of two variables. A [0,0] value is returned if there is no previous active time frame at the given time.
tf_prev_interval/3 example
tf_prev_interval($TF,$TM,[$START,$END]);
tf_next_start/2 obtain the start time of the next active interval of a time frame
tf_next_start($TIMEFRAME,$START) $START=tf_next_start($TIMEFRAME)
Chapter 4
213
Use tf_next_start/2 to obtain the start time of the next active interval of time frame $TIMEFRAME in $START. A 0 value is returned if there is no next active time frame.
tf_next_start/2 example
$START = tf_next_start($TF);
tf_next_start/3 obtain the start time of the next active interval of a time frame at a given time
tf_next_start($TIMEFRAME,$TIME,$START) $START=tf_next_start($TIMEFRAME,$TIME)
Use tf_prev_start/3 to obtain the start time of the next active interval at $TIME of time frame $TIMEFRAME in $START. A 0 value is returned if there is no next active time frame at the given time.
tf_prev_start/3 example
$START = tf_next_start($TF,$TM);
tf_next_end/2 obtain the end time of the next active interval of a time frame
tf_next_end($TIMEFRAME,$END) $END=tf_next_end($TIMEFRAME)
214
Use tf_next_end/2 to obtain the end time of the next active interval of time frame $TIMEFRAME in $END. A 0 value is returned if there is no next active time frame.
tf_next_end/2 example
$END = tf_next_end($TF);
tf_next_end/3 obtain the end time of the next active interval of a time frame at a specified time
tf_next_end($TIMEFRAME,$TIME,$END) $END=tf_next_end($TIMEFRAME,$TIME)
Use tf_next_end/3 to obtain the end time of the next active interval at $TIME, of time frame $TIMEFRAME in $END. A 0 value is returned if there is no next active time frame at the given time.
tf_next_end/3 example
$END = tf_next_end($TF,$TM);
tf_next_interval/2 obtain the start and end time of the next active interval of a time frame
tf_next_interval($TIMEFRAME,$INTV) $INTV=tf_next_interval($TIMEFRAME)
Chapter 4
215
output LIST_OF INTEGER start and end time of next active interval
Use tf_next_interval/2 to obtain the start and end time of the next active interval of time frame $TIMEFRAME in $INTV. Argument $INTV of the primitive, has to be specified as a list of two variables. A [0,0] value is returned if there is no next active time frame.
tf_next_interval/2 example
tf_next_interval($TF,[$START,$END]);
tf_next_interval/3 obtain the start and end time of the next active interval of a time frame at a specified time
tf_next_interval($TIMEFRAME,$TIME,$INTV) $INTV=tf_next_interval($TIMEFRAME,$TIME)
LIST_OF INTEGER start and end time of the next active interval at specified time
Use tf_next_interval/3 to obtain the start and end time of the next active interval at $TIME of time frame $TIMEFRAME in $END. Argument $INTV of the primitive, has to be specified as a list of two variables. A [0,0] value is returned if there is no next active time frame at the given time.
216
tf_next_interval/3 example
tf_next_interval($TF,$TM,[$START,$END]);
tf_duration/3 calculate the duration of all active intervals of a time frame from a specified start time to the current time
tf_duration($TIMEFRAME,$START,$DURATION) $DURATION=tf_duration($TIMEFRAME,$START)
Use tf_duration/3 to calculate the total duration in $DURATION of all active intervals of time frame $TIMEFRAME over the period starting at $START and ending at the current time.
tf_duration/3 example
$DURATION = tf_duration($TF,$TM0);
tf_duration/4 calculate the duration of all active intervals of a time frame during a specified time period
tf_duration($TIMEFRAME,$START,$END,$DURATION) $DURATION=tf_duration($TIMEFRAME,$START,$END)
Chapter 4
217
output INTEGER
Use tf_duration/4 to calculate the total duration in $DURATION, of all active intervals of time frame $TIMEFRAME over the period starting at $START and ending at $END.
tf_duration/4 example
$DURATION = tf_duration($TF,$TM0,$TM1);
generate_event($CLASS,$SLOTS)
LIST_OF ANY specifies the list of slot settings to be included in the new event
Use generate_event/2 to generate a new event of class $CLASS with slot settings as specified in $SLOTS. The value of the $SLOTS argument must be a list of elements of the form SlotName=Value.
218
generate_event/2 example
generate_event(CUSTOM_EVENT,[severity=INFO,msg=$MSG]);
new_data($OBJECT,$CLASS,$SLOTS)
LIST_OF ANY specifies the list of slot settings for the new object
Use new_data/3 to generate a new data object $OBJECT of class $CLASS with slot settings as specified in $SLOTS. The value of the $SLOTS argument must be a list of elements of the form SlotName=Value. A handle for the new data object is returned in $OBJECT.
new_data/3 example
new_data($DATA,CUSTOM_DATA,[mc_udid=$ID,myslot=$VAL]);
remove_data($OBJECT)
Chapter 4
219
remove_data/1 example
remove_data($DATA);
drop_new()
Use drop_new/0 to drop the newly received event, being processed in a new rule.
220
drop_new/0 example
new RepeatTick: MC_CELL_TICK($E) updates duplicate($U) { $U.repeat_count = $U.repeat_count + 1; drop_new; } END
unset_cause()
Use unset_cause/0 to break the cause-to-effect relationship that is established by a correlate rule.
unset_cause/0 example
correlate Corr1: EVENT($E) where ... with EVENT($C) where ... ... when $C.status == CLOSED { unset_cause; } END
set_timer/3 set a timer on an event object that will expire after a specified delay
NOTE
This primitive cannot be used in refine, filter, regulate, or propagate rules.
set_timer($OBJECT,$DURATION,$INFO)
Chapter 4
221
Use set_timer/3 to set a timer on event $OBJECT that will expire after $DURATION seconds and to trigger a timer rule with timer information matching $INFO. The value of $INFO will be substituted for the timer_info in matching timer rules when the timer expires.
set_timer/3 example
new TimeoutNew: EVENT($E) where [ $E.mc_timeout > 0 ] triggers { set_timer($E,$E.mc_timeout,EventTimeout); } END timer TimeoutTimer: EVENT($E) where [ $E.status != CLOSED ] timer_info: == EventTimeout { $E.status = CLOSED; } END
When a new event is received and its mc_timeout slot is greater than 0, a timer will be set on the event to expire after that timeout period. The timer rule in the example will match, because it tests timer_info to ensure that it is equal to EventTimeout.
set_timer_at/3 set a timer on an event object that will expire at a specified time
NOTE
This primitive cannot be used in refine, filter, regulate, or propagate rules.
set_timer_at($OBJECT,$TIME,$INFO)
222
Use set_timer_at/3 to set a timer on event $OBJECT, to expire at time stamp $TIME and to trigger a timer rule with timer information matching $INFO. The value of $INFO will be substituted for the timer_info in matching timer rules, when the timer expires.
set_timer_at/3 example
set_timer_at($E,$EXPTM,EventExpired);
set_timer_at/4 set a timer on an event object that will expire at a specified time represented by a text string
NOTE
This primitive cannot be used in refine, filter, regulate, or propagate rules.
set_timer_at($OBJECT,$STR,$FORMAT,$INFO)
Use set_timer_at/4 to set a timer on event $OBJECT that will expire at time stamp with textual representation $STR in format $FORMAT, and to trigger a timer rule with timer information matching $INFO. The value of $INFO will be substituted for the timer_info in matching timer rules when the timer expires.
Chapter 4
223
set_timer_at/4 example
set_timer_at($E,$DATETIME,%Y%m%d %H%M%S,EventExpired);
The variable $DATETIME should contain a time indication similar to 20070209 153010.
224
Chapter
5
226 226 226 226 227 230 230 233 235 236 237 239 241 242 243 244 245 246 247 248 249 249 249 252 253 253 255 255
Event rules
Rules and event management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rule structure and syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MRL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MRL conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MRL event selection clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using_policy clause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unless clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Body clause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic data in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global records in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Interfaces in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Interface instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Indexes in rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compiling rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tracing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring rule tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing rule trace message headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Undefined events, processing errors, and deprecated slots . . . . . . . . . . . . . . . . . . . . Undefined events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event processing errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using deprecated slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 5
Event rules
225
MRL files
Rule files have an .mrl extension and are located in the rules subdirectory of a Knowledge Base. Rules must be compiled before they can be used by the cell. The compiled files have a .wic or .pkg extension and are also located in the rules subdirectory. The order of loading into the cell at startup, which determines the order of evaluation, is specified in the .load and .loadwic files (files with the compiler extensions).
MRL conventions
BMC Knowledge Base Development Reference Guide addresses the purpose of each rule phase with programming examples. This section focuses on the general syntax of rules and the roles of the different objects and syntactic constructs. When writing rules, use the following conventions:
I
Use single quotation marks for all literal strings. This convention is not mandatory for text without internal spaces but is required for text that does contain spaces. When a cell name contains a hyphen, the cell name must be enclosed in single quotation marks ().
226
When a primitive contains an argument that is a list arg, such as the first argument of a concatenation string, the argument must be enclosed with square brackets.
concat([this,is,a,quick,example],$CONCAT_STR);
The compiler validates syntax on primitive arguments. For example, use of a SIMPLE type instead of a LIST will result in a compilation error.
I
Literal strings can be no more than 65535 characters in length. If you attempt to compile a rule file containing a slot assignment of a string greater than 65535 characters, the compiler replaces it with the empty string. If the newline character, \n, is received as input for a slot value, it is stored as part of the slot value. Neither the cell nor the operators interpret slot values. Therefore, if the newline character is part of the slot value, any search for a match must contain the newline character. Otherwise, the match search is unsuccessful. MRL is case sensitive. References to classes and slots must respect case. An event is referenced with a variable name within the rules. Variable names begin with $ and must contain only alphabetic characters. Slots belonging to a particular event are accessed using the $eventVariable.slotName notation. Many rules contain an action block. The action block contains one or more actions that are executed by the rule. Braces ({}) delimit action blocks, and semicolons (;) separate actions within an action block. Rules end with the END keyword.
Chapter 5
Event rules
227
Figure 14
Rule syntax
RuleType RuleName: <ClassName> { ($<EventVariableName>)} { where [ <BooleanExpression> ]} { | using {ALL} | unless | '{' <ClassName> { ($<ObjectVariableName>)} {where [< BooleanExpression> ]} ... < ClassName> { ($<ObjectVariableName>)} {where [< BooleanExpression> ]} '}' } <RuleSpecific> '{' <Call>; ... <Call>; '}' END
Refine Filter Regulate New Abstract Correlate Execute Threshold Propagate Timer Delete
RuleName
specifies the unique, descriptive name of the rule, using alphanumeric characters (it can include underscores). The name must be unique across the entire Knowledge Base, and it should be descriptive because you need to identify it easily in tracing and log output files.
228
| using {ALL} | unless> | using either {ALL} or unless name of a variable representing an event or data an expression whose value is a boolean an assignment or a primitive call
the body of the rule, specifying actions to be performed on events, slots to be modified, and primitives to be used. The syntax of the rule body and meaning of the primitives depend on the rule type to which the rule belongs.
Chapter 5
Event rules
229
The following rule will accept the instance and will be evaluated.
filter application_events : PASS APPLICATION_EVENT ($APEV) where [ .... ] ...
Where clauses
where clauses are an optional part of the ECF and establish restrictive selection criteria. A where clause consists of the keyword where followed by the criteria within square brackets: where [criteria]
230
Where clauses
The criteria portion of the statement is a logical combination of expressions about the slots of the event.
where clauses can use logical combination operators, as described in Where clauses
MRL primitives, functions, and operations also can be used in expressions. An exhaustive list can be found in MRL functions and primitives on page 100. In the following example, the where clause syntax requires that the mc_host slot of the event under analysis literally is to be set to thishost.
APPLICATION_EVENT ($APEV) where [ $APEV.mc_host == thishost; ]
The syntax in the next example requires that the mc_host slot of the event under analysis literally to be set to thishost or to thathost if the source does not contain NT.
APPLICATION_EVENT ($APEV) where [ $APEV.mc_host == thishost OR $APEV.mc_host == thathost AND NOT $APEV.source contains NT ]
NOTE
Quotation marks are mandatory when the string contains spaces, punctuation characters, or arithmetic operators (+, -, *, /, and so forth).
Chapter 5
Event rules
231
Where clauses
You can write the same rule using parentheses to specify priority or precedence, as shown in the following example:
APPLICATION_EVENT ($APEV) where [ ($APEV.mc_host == thishost) OR (($APEV.mc_host == thathost) AND (NOT ($APEV.source contains NT))); ]
You can also use parentheses to alter the precedence. In the following example, the OR operator would be evaluated first because it is enclosed in parentheses.
APPLICATION_EVENT ($APEV) where [ ($APEV.mc_host == thishost OR $APEV.mc_host == thathost) AND $APEV.source contains NT; ]
For information about the order of precedence for combination operators, see Combination operators on page 83.
232
Using clause
However, they are not equivalent. The rule engine maintains an inheritance table that enables it to be extremely efficient at manipulating classes. In the first syntax example, the rule engine literally must check to see if the class name is the string APPLICATION_EVENT. This literal comparison does not take advantage of the inheritance mechanism, and places a much heavier demand on the performance of the rule engine than the syntax in the second example. Using class comparisons in a where clause does not use the inheritance table optimization and results in performance degradation of the rule engine.
However,
$EV.mc_host:equals thathost
is permitted only for backward compatibility with the first initial releases of the MRL.
Syntax shortcut
In a where clause slot: is a shortcut for $EV.slot.
$EV.slot: is syntactically incorrect.
Using clause
The using clause retrieves information from the event repository of the rule engine to be used in the context of a rule. You can use the using clause to retrieve data instances for a dynamic rule, or to retrieve instances of past events. The syntax for the using clause is as follows:
EventClassName (Variable) where [Expression CondOperator Expression, ...] using [ALL] {DataClassName (Variable) where [Expression CondOperator Expression, Expression CondOperator Expression, ...];
Chapter 5
Event rules
233
Using clause
DataClassName (Variable) where [Expression CondOperator Expression, Expression CondOperator Expression, ...]; ... ; }
To search for event instances, you must write a valid criteria block with a valid event class name instead of a data class name. You can define indexes on events and data. Querying instances can be process intensive and might dramatically reduce cell performance. When there are only conjunctions (ANDs but no ORs) in the using clause, the compiler performs the following optimizations:
I
Equality constraints against mc_ueid and mc_udid (like $D.mc_udid == <value>) are compiled to use the internal hash table associated with these special slots. Equality and order constraints (==, <, >, <=, >=, between, has_prefix) against key slots (a slot with facet key=yes) are compiled to use the internal key index.
If you need to query potentially large tables but the above optimizations are not possible, consider declaring an index on the table and query the table using the index. For further information, see Indexes in rules on page 246. You can use conditions in the using clause to set controls on event processing. For example, you can indicate that the remainder of a rule is to be skipped if no relevant data is located. Table 211 on page 234 lists additional conditions that affect rule processing. Table 211
Condition
Only a single instance of the data is The rule is evaluated only for the single instance. found in the repository. No data that matches the specified criteria is found in the repository. More than one instance of the data exists in the repository. The remainder of the rule is skipped. Only the first data instance is retrieved. Note: You can alter this behavior by using the ALL keyword. If you use the ALL keyword and more than one instance of data is found, the rule is evaluated for each instance. The ALL keyword contains a hidden recursive mechanism that produces this result.
234
Using_policy clause
Table 211
Condition
The using clause in a rule contains The rule engine searches for an instance corresponding to the criteria in several queries. the first using query, then an instance for the criteria in the second query, until all queries are exhausted. At least one instance of each query must exist for the rule to evaluate. For a using clause to succeed, each of its queries must find a solution. If the ALL keyword is present in the using clause, the body of the rule is executed for all the possible combinations of the different query solutions. A condition in a query can refer to the slot values of the main event of the rule, data, or event, each of which is retrieved by preceding queries in the using clause. The ALL keyword is used in the using clause. The rule is evaluated for all combinations of the instances found. For example, if a using clause contains two blocks, the first block retrieving three instances and the second block five, the rule is evaluated a total of fifteen times.
Using_policy clause
Policy instances can be referenced before the selection part of a rule as shown in this example:
new bmc_im_internal_closure: using_policy { EVENT_CLOSURE_POLICY($POL) where [ calendars_active($POL.active_calendars) ] } $POL.closing_event($CLOSING) where [ $CLOSING.status != CLOSED ] updates ALL $POL.closed_event($CLOSED) within $POL.time_window { $CLOSED.status = CLOSED; if ($POL.suppress_restoring_event == 1) then { drop_new; } }
Each instance of EVENT_CLOSURE_POLICY is instantiated at runtime. The closing_event and closed_event criteria are linked dynamically at runtime. ECF slots can be used in place of the class name in the main selection of a static rule. Where clauses specified in the rule are logically ANDed with the where clause in the ECF instance.
Chapter 5
Event rules
235
Unless clause
QUERY slots can be used in place of class names in using or update selections of a static rule. Where clauses specified in the rule are logically ANDed with the where clause of the QUERY instance.
The compiler ensures that the queries used in a dynamic selection respects the order of the query definitions. The compiler compiles the rule, taking into account the class for which the ECF and QUERY slots are defined. Only the slots of these classes can be referenced in the rest of the rule.
using_policy [ALL] executes the rule for all policy instances.
Unless clause
You might want to apply an action if certain instances of data or events do not exist. In these cases, you would use the unless clause. It has the same syntax as the using clause, but the logic is essentially reversed; that is, if the queries inside the unless clause are successful, the selection fails and the action is not applied.
236
When clause
When clause
Use a when clause to trigger part of a rule each time a specified slot of a previously processed event is modified or is assigned a specific value. The when clause can be used n the Execute, Abstract, Correlate, and Propagate rule phases. Rules containing a when clause are evaluated completely when a new event is processed that matches the where condition of the rule. The when clauses in these rules are re-evaluated each time the processed event is modified so that it matches the when condition. The general syntax of the when clause is:
when = WhenCondition CallList CallList is the part of the rule that is re-evaluated when the event is modified. The syntax for WhenCondition depends on whether you want the slots and conditions to
be static or dynamic. To trigger the when clause when a specified slot changes, use the syntax in Figure 16. Figure 16 when condition triggered by any change to a specified slot
In Figure 16, the name of an existing variable must be specified, as well as the name of the slot to be monitored for changes. The when clause is triggered each time the specified slot changes.
Chapter 5
Event rules
237
When clause
To trigger the when clause when a specified slot changes to a specified value, use the syntax in Figure 17. Figure 17 when condition triggered by a specific change to a specified slot
In Figure 17, the name of an existing variable must be specified, as well as the name of the slot to be monitored for changes. The when clause is triggered only when the slot value changes to match the operator and condition expression specified by Op Condition. When the slot name and/or the condition are not known in advance, use the syntax in Figure 18. Figure 18 when condition triggered by a specific change to a specified slot
In Figure 18, $VarName is the name of an existing variable. If $VarName is not specified, the variable used in the where clause of the rule is used. The slot name is determined dynamically by evaluating the expression SlotExpr, which must result in a valid slot name. The condition that the slot must meet also is specified dynamically. The operator is determined by evaluating the expression OpExpr, which must result in a valid operator name. The conditional expression is derived by evaluating the expression CondExpr. CondExpr is evaluated twiceonce to determine a conditional expression and a second time to evaluate if the slot matches that conditional expression. When an event is modified by a rule containing a when clause so that it becomes a candidate for evaluation by another rule, that evaluation does not take place immediately. Instead, the request is queued for the rule engine to process after all other pending requests or events are processed.
238
Body clause
Figure 20
Sample data
NOTIFY_RULE; object_class=CLS1; trigger_slot=severity; trigger_op='>='; trigger_expr=MAJOR; END NOTIFY_RULE; object_class=CLS2; trigger_slot=status; trigger_op=within; trigger_expr='[ACK,ASSIGNED]'; END
The sample data determines in which cases an incoming event will trigger the when clause in the Execute rule, depending on the mc_object_class of the event:
I
For object class CLS1, the when clause is triggered when the event's severity is MAJOR or higher. For object class CLS2, the when clause is triggered when the event's status is within ACK, ASSIGNED. Note for object class CLS2, the list value of trigger_expr must be within single quotation marks to form a STRING type value, instead of a LIST. The arguments used in the when clause must be type STRING.
Body clause
Use a body clause in a rule to call slot assignments, primitives, or functions. In a body clause, functions return an expression and primitives return a Boolean value expressing the success or failure of the primitive. For more information about primitives and functions, see MRL functions and primitives on page 100.
NOTE
When a primitive fails, that is, returns the value FALSE, the remainder of the block is not executed.
Chapter 5
Event rules
239
Body clause
Call ; }
NOTE
Except for the last statement, all statements in a body clause must be separated using a semicolon (;).
if-then-else construct
The if-then-else construct is a special call used in a body clause that specifies a conditional execution. The syntax for the if-then-else construct is:
if Expression then { Variable.SlotName = Value; Call ; } [ else { Variable.SlotName = Value; Call ; } ]
The else body clause is optional. If the Expression is evaluated as true, the statements in the then block are executed. However, if an else block is included in the body clause and the statement is evaluated as false, the statements in the else block are executed.
240
Variables in rules
You can refer to a local variable declared in the then and else block after the ifthen-else call if the variable is declared in both the then and else block with the same data type, as shown in the following example:
if Boolean expression then { ... $TEMP = ' yes' ; ... } else { ... $TEMP = ' no'; ... }; $EV.msg = $TEMP;
NOTE
It is unnecessary to use an if-then-else construct to create a conditional affectation. A simpler solution is to use a conditional expression.
Variables in rules
Use variables in rules to point to MRL objects, such as events, data, global records, or interfaces, and to reference results returned by a primitive. In a rule, you must declare variables at their first occurrence in the text. The scope of the variable is from its declaration to the end of the rule. The value for a variable cannot change during the life of the variable. For example, you cannot assign another value to a variable after the first occurrence in a rule. The syntax for a declaring a variable is as follows:
$VariableName
The name of the variable must be composed of alphanumeric characters; it also can contain underscore characters.
NOTE
The cell uses a naming convention of variables with short uppercase names.
Chapter 5
Event rules
241
In the following example, the variable $EV points to the event being evaluated so that $EV.SlotName refers to the slot of the specified name for that event. The slot must exist in the BAROC definition of that object class. You then can use the $EV variable in expressions in the rule or in assignment statements.
ClassName ($EV) where [expression op expression, . . . , expression op expression ]
NOTE
The same principles that apply to events also apply to interface objects: a variable points to the interface instance returned by an external program. Additionally, it allows the use of the individual slot values in subsequent expressions.
Global record instances are predefined in the Knowledge Base; therefore, the scope of global record variables is the entire Knowledge Base. A variable $UNDER_MAINTENANCE refers to the unique instance of the UNDER_MAINTENANCE global record. You can use variables in primitives to obtain the values they return, as shown in the following example:
concat( [from top, to bottom ], $MSG0; $EV.msg = $MSG ;
The concat primitive concatenates a list of strings into another string. The $MSG variable obtains the result, so that the concatenated string can be used in subsequent clauses. The result is used as an assignment.
242
In the following example, the business impact of an unavailable application determines the severity level of the associated APP_DOWN event. Upon receiving an APP_DOWN event, an Execute rule retrieves the first instance of SEVERITY_BY_APP_DOWN that matches the application name set in the APP_DOWN event. The instance contains the appropriate severity to associate with the application, so the rule makes the assignment as shown: Figure 21 Execute rule using dynamic data
execute Set_App_Down_Severity : APP_DOWN ($AD) using SEVERITY_BY_APP_DOWN ($SBAD) where [$SBAD.application == $AD.application] when $AD.status == OPEN { $AD.severity = $SBAD.severity; } END
The rule searches the data instances to find the instance of the application in the APP_DOWN event. When a match is found, the rule stops searching the data instances and continues processing with the matching instance, as follows:
SEVERITY_BY_APP_DOWN ; application = mail ; severity = CRITICAL ; END
The data must be populated beforehand; otherwise, the rule engine does not find an instance and the remainder of the rule is skipped. In other words, when the using clause is present in a rule, it must return data or the selection fails, and the remainder of the rule is skipped. You can also define dynamic data instances by using the Dynamic Data Editor. For instructions, see the Administration Guide.
NOTE
Using an index dramatically improves the performance of a query in the data repository. If key slots are present in the Event Condition Formula (ECF), optimization is performed on the data query. For information about indexes, see Indexes in rules on page 246.
Interfaces in rules
You can query or modify the contents of a global record either from the rule engine or through the mgetrec or msetrec commands. For more information about the mgetrec and msetrec commands, see Administration Guide. Global records are created using .baroc files. The global record files are located in the Records directory of the cells Knowledge Base.
NOTE
Global records maintain their information when the cell is stopped and restarted.
Global records are addressed by name, so you must know the name of the global record to use it. You can use global records in an expression, an assignment, or a primitive. Use the following syntax in a rule to refer to a slot listed in a global record:
$RecordName.SlotName
Interfaces in rules
Refine rules use interfaces to import external data to the rule engine. For example, you can create an interface and use it as an interface instance to return data to the Refine rule. Interfaces are maintained in .baroc file in MCELL_HOME\etc\CellName\kb\classes on Windows platforms and in MCELL_HOME/etc/CellName/kb/classes on UNIX platforms.
244
Interface instances
Slots defined in an interface follow the same syntax as used in a class definition, as shown:
MC_INTERFACE: InterfaceName DEFINES { SlotName: DataType, Facet, Facet; SlotName: DataType; ... }; END
In the following example, the interface is designed to retrieve additional data about a system that is potentially down.
MC_INTERFACE: LOCATION DEFINES { site: STRING; phone: STRING; }; END
Interface instances
The pieces of data collected by the external program or script are assigned to the slots of the interface, creating an interface instance. The life of an interface instance is limited, since only the calling Refine rule can use it. To access the data in the future, the slot values must be stored in a global record or an event. The syntax for an interface instance is as shown:
InterfaceName ; SlotName = Value ; SlotName = Value ; END
After the external information exists in an interface instance, a Refine rule assigns it to slots or uses it another manner, such as normalizing an event message. In conjunction with the interface instance defined above, the interface instance in Figure 22 provides values for the system location and phone number for the responsible party.
Chapter 5
Event rules
245
Indexes in rules
During rule processing, you can use the following functions or primitives to execute an external script or program: execute, get_external, or confirm_external. The external script or program that you reference in a rule must be located in the correct bin subdirectory or it will not execute. The platform for the host computer that you use determines where the script or program resides. For further information about the bin directory, see Knowledge Base directory structure on page 21. Figure 22 Interface instance example
Indexes in rules
Use indexes to improve rule performance. Indexes enable the rule engine to find event or data instances more rapidly. When only a limited selection of instances is required, an index avoids iteration over all instances. You can also use an index to determine the order of iteration over a set of event or data instances. A sorted index implements an order on the instances. If the goal is to determine the search order, use a sorted index. When the goal is mainly performance improvement, a hashed index (an index based on a hash table) will produce the best results. You should define key slots when there is a need to enforce uniqueness on a combination of slots. Hashed indexes do not enforce uniqueness. Several instances can have the same value for all of their indexed slots, but with key slots, only one instance can have a certain combination of slot values. When there is no need to enforce a uniqueness, use hashed indexes rather than key slots for optimization. Indexes are defined with in the MRL with a rule-like syntax. An index rule will not do any processing on an incoming event. The syntax for an index definition within a rule is
index IndexName : CLASS ( sorted|hashed ) Slot | '[' Slot { , Slot } ']' END
You can define an index for an event class, as well as for a data class. You can define an index for a single slot or for a list of slots. On a list of slots, a sorted index will start sorting on the first slot. Instances with same value in the first slot will be sorted on the second slot and so on. The slots in the slot list must be slots of the indicated class or of one of its superclasses.
246
Using indexes
You can define more than one index for the same class. A subclass inherits an index definition from its superclass if one is defined. An index definition for a subclass does not override an inherited index. All index definitions for a class remain effective whether they are defined directly for the class or inherited from a superclass. The following example shows two index definitions. The first is a sorted index for two slots; the second is a hashed index for a single slot.
index Idx1 : EVENT_CLASS sorted [date_reception,data_handle] END index Idx2 : BMC_Base_Element hashed Name END
Using indexes
You use an index in a using clause. Instead of specifying a class name, you specify an index name defined for that class. The following example shows three general forms of an index using clause.
using index IndexName '[' ']' '(' $IndexVariable ')' [ where '[' ... ']' ] using index IndexName '[' SlotVal [ { , SlotVal } ] ']' '(' $IndexVariable ')' [ where '[' ... ']' ] using index IndexName '[' Slot=SlotVal [ { , Slot=SlotVal } ] ']' '(' $IndexVariable ')' [ where '[' ... ']' ]
The difference among these three forms is in the specification of the actual indexed slot values.
I
The first form does not specify any slot value. The second form specifies one or more values for indexed slots in the same order as in the index definition. The third form specifies one or more values for indexed slots by name. In this case, it is not necessary to list the slots in the same order as in the definition.
A sorted index does not require you to provide an actual value for each of the indexed slots. However, all slots for which an actual value is specified must be at the beginning of the slot list in the definition. For example, if an index is defined for the slot list [slot1, slot2, slot3, slot4], it is valid to have an actual value for slot1 and slot2 and no values for slot3 and slot4. It is not valid to provide an actual value for slot2 and slot3 only, because the first slot, slot1, is left unspecified. It also valid to specify none of the indexed slots for a sorted index. To use a hashed index, you must specify all indexed slots with an actual value. The rule compiler will report invalid use of an index in error messages.
Chapter 5
Event rules
247
Compiling rules
The rules use $E to refer to the EVENT_CLASS instances and $D to refer to the BMC_BaseElement instances that are retrieved through the indexes. The first rule, Rule1 uses the sorted index Idx1 without specifying any of the indexed slots. As a result, it will iterate over all EVENT instances in the order of the index (which can impact performance if there is a large number of instances). The additional where condition will select the desired data instances. The second rule, Rule2 uses a hashed index. It provides the mandatory actual value for the indexed slot Name, assuming that the MY_EVENT instance has a slot ci_name that contains the Name of the relevant BMC_BaseElement instance.
Compiling rules
Rules do not immediately start processing events after they are created. The Knowledge Base (KB) for the cell must be compiled so the rules are read into it. You can use the mccomp command to compile the KB. For more information about using the mccomp command, see Compiling a Knowledge Basemccomp on page 26.
NOTE
To monitor rule behavior you can compile the KB with a tracing option. For more information, see the Effects of compiling a Knowledge Base with tracing enabled on page 26.
248
Testing a rule
Testing a rule
You can test a rule to verify that it processes events correctly. The process for testing a rule is to send an event to a cell and then review how the event is processing through the rules.
Tracing a rule
Tracing enables you to follow the flow of events through each rule phase. Tracing the execution of a rule also helps Knowledge Base developers to find logical errors or enhance performance. The MRL compiler (mccomp) generates rule trace code that contains the following fields:
I I I I I I
message id (identifying the type of statement being executed) source file name source line number name of the rule reference to the main event being processed class name of the main event being processed
This code is generated each time the compiler is run. Impact on performance is minimal when rule trace is not enabled.
Chapter 5
Event rules
249
The TraceRuleLevel parameter controls rule tracing globally. It can have the following values:
I
0 completely disables rule tracing as well as run time error reporting. It is not recommended. 1 enables run time error reporting, and disables rule tracing. This is the recommended setting for normal production environments. 2 enables rule tracing. This should only be used in development, for analysis or when debugging the Knowledge Base.
If rule tracing is enabled, the TraceRulePhases and TraceRuleNames parameters control which rules are traced. A rule is only traced if both the phase to which it belongs and the rule itself are configured for tracing. The TraceRuleNames parameter contains a comma-separated sequence of module:rule combinations or the keyword ALL to indicate all modules and/or rules. Each rule name optionally can be prefixed with a + or - sign to indicate addition or removal from the list. To trace rules from the global module, enter the rule name by itself without an accompanying module name. The list is interpreted in sequential order. The TraceRulePorts parameter determines the category of tracing messages that are reported. This parameter is a comma-separated list of any of the following trace message categories:
I
entrya message is displayed when an event satisfies the main selector of a rule.
If the rules refer to a policy, the messages are displayed for every policy instance that matches the event. For example,
im_internal.mrl, 60: refine im_internal_lowercase_hostname: EVENT #5: Rule execution starting with $EV = 0xd926d0 (class: EVENT, event_handle: 5, mc_ueid: mc.ruleTrc9612.7de944e.0)
250
usinga message is displayed when an object instance is retrieved by a query in a using block. For example,
ruleTrc9612.mrl, 31: refine idx_data_s: IDX_EVENT #5: solution 1 to data query: $X = 0x13c5468 (class: IDX_DATA, data_handle: 374, mc_udid: mc.ruleTrc9612.7f100f7.327)
using_policya message is displayed when a policy is retrieved by a query in a using_policy block. For example,
im_internal.mrl, 207: refine im_internal_timeout: EVENT #5: solution 1 to policy query: $POL = 0x109e4b8 (class: IM_TIMEOUT_POLICY, data_handle: 32, mc_udid: mc.ruleTrc9612.7de9405.19)
using_failurea message is displayed when there are no instances that statisfy a query in a using block. For example,
ruleTrc9612.mrl, 13: refine idx_event_h: IDX_EVENT #5: no solution for $X in context $E = 0x146ca80 (class: IDX_EVENT, event_handle: 5, mc_ueid: mc.ruleTrc9612.7f100f7.349)
using_policy_failurea message is displayed when there are no instances that statisfy a query in a using_policy block. For example,
im_internal.mrl, 18: refine im_internal_blackout: EVENT #5: no solution for $POL in context $EV = 0xd926d0 (class: EVENT, event_handle: 5, mc_ueid: mc.ruleTrc9612.7de940c.0)
All rules from module TroubleTicketing that are not refine or regulate, except rule1 Rules rule1 and rule2 from module SendMail, if they are not refine or
regulate
All entry to the specified rules is traced, as well as assignments within those rules.
Chapter 5
Event rules
251
tracerule on|off globally enables (on) or disables (off) rule tracing tracerule phases Phases modifies the configuration of which rule phases are enabled for tracing. The Phases value has the same format as the TraceRulePhases parameter. For example, mcontrol -n CellName tracerule phases -new,-abstract
tracerule names Names modifies the configuration of which rules are enabled for tracing. The Names value has the same format as the TraceRuleNames parameter. For example, mcontrol -n CellName tracerule names problem_rule
This command enables tracing of the rule named problem_rule (assuming that problem_rule is of a phase that has rule tracing enabled).
I
tracerule ports Ports determines which tracing ports are enabled. Ports is a string with the same format as the TraceRulePorts parameter, described on page 250.
Each time the cell starts, it reverts to the static rule tracing configuration defined in mcell.conf.
252
The header is specified as text and can contain references to parameters, using the following designations to represent the associated parameters:
I I I I I I I I
%I message id %F source file name %L source line number %M KB module name %R rule name %P rule phase %H handle of the main event being processed (event_handle slot) %C class name of the main event being processed
The text of the message is retrieved from the message catalog through the message identifier and can be localized.
Undefined events
Events with errors, or undefined events, are treated so that as much correct data as possible is retained and incorrect data is made available for use in rules. The rule engine determines incorrect data through parsing errors and incompatibilities with the BAROC class definitions. The following incorrect events are handled by the cell as specified:
I
Undefined events
An internal event of class MC_CELL_PARSE_ERROR is created. It contains slots with the complete message text, as well as the line number and column number in the message text that locates the error message. Specific slots for this internal event are listed in Table 212. Table 212 MC_CELL_PARSE_ERROR slots
Slot error_column error_line error_message event_text Data column number in text where error occurs line number on text where error occurs error message complete event message text
The event is of an undefined class. An internal event of class MC_CELL_UNDEFINED_CLASS is generated. Its class definition is shown below:
MC_EV_CLASS: MC_CELL_UNDEFINED_CLASS ISA MC_CELL_EVENT DEFINES { severity : default = MINOR; class_name: STRING; }; END
It contains slots with the undefined class name, a list of slot names, and a list of slot values. The specific slot used is described in Table 213. Table 213 MC_CELL_UNDEFINED_CLASS slots
Slot class_name Data name of class as specified in the message
The event is of a defined class, but contains undefined slots. The event is generated as one of the specified class, and the undefined slots are stored in the bad slot list slots, in corresponding order, as shown below:
The event has slot values that do not match the data type of the slot, such as a nonnumeric value for a numeric type.
254
The event is generated as specified, except the bad slots. Because a valid value is not assigned for the bad slots, the default value applies to those slots. All bad slot values are stored in the two slot lists, as for the event of a defined class with undefined slots.
Chapter 5
Event rules
255
256
Chapter
6
259 259 260 261 261 262 263 263 264 265 266 266 266 267 268 268 270 272 273 273 276 277 278 278 279 280 281 281 283 283 285 285 286 287
257
Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Threshold rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Threshold rule examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Propagate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 Propagate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 Propagate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Propagate rules examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Timer rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Timer rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Timer rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Timer rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Timer rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Delete rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Delete rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Delete rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Delete rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
258
Refine rules
Refine rules
A Refine rule verifies the validity of incoming events and collects additional data for an event before it is sent through the remaining rule phases where further processing takes place. Refine rules collect additional data for an event when
I
I I
event slot values require additional processing (an example: normalizing a message or host name) an event must be confirmed before it can be processed further an external process is executed to confirm an event
Any new data returned from the query must conform to the BAROC interface model for the event. Interface classes are stored in the Knowledge Base with the event classes.
No Match
Match
# 1 2 3
Description The incoming event is compared to the ECFs contained in the Refine rule. The incoming event does not match the ECF contained in the Refine rule. Incoming event matches the ECF in the Refine rule.
Chapter 6
259
ECF
determines whether an action or assignment must take place for the event under analysis For example, a Refine rule can use either the confirm_external or get_external primitives to execute an external program in response to an event. Note: You can use a variable to trigger an ECF event and call in the action clauses that follow. For more information about variables in rules, see Variables in rules on page 241.
Figure 25 shows the syntax of an event condition formula (ECF) definition for a Refine rule. Figure 25 Refine rule ECF syntax
ClassName Variable where [Expression CondOperator Expression, Expression CondOperator Expression] using | using ALL DataName DataVariable where [Expression CondOperator Expression, Expression CondOperator Expression]
determines which events are processed by the Refine rule The class name for the event being processed must match the class name for the rule to evaluated.
retrieves information from the repository of a rule engine to be used in the context of the rule For more information about the Using clause, see Using clause on page 233.
260
command-line arguments. If the primitive is successful the event continues to process, if it fails the event is dropped. For more information about the confirm_external primitive, see page 115.
I
and have the executable pass information back to the cell through an interface. For more information about the get_external primitive, see page 117. In addition to the confirm_external and get_external primitives, Refine rules can utilize any primitive that is not assigned to a particular rule type. See Primitives and functions overview on page 106 for more information about rules and their assigned primitives.
refine Disk_Full_Contact_Info : DISK_FULL ($DF) { get_external (get_site.sh, [], LOCATION, $LOC); $DF.msg = $LOC.site ; } END
Chapter 6
261
Filter rules
The following is an example of the standard output from the get_site.sh script.
LOCATION ; site = B3R123 ; phone = x7734 ; END
Filter rules
Filter rules limit the number of incoming events by discarding those events that need no additional processing or analysis. Filter rules compare incoming events to the event condition formulas (ECFs) contained in the rule to determine if an event is discarded or proceeds to further processing. An incoming event is processed through each Filter rule until a Filter rule discards the event, or all Filter rules are exhausted. An event must match all the Filter rules to be accepted. Filter rules use the following modes to determine whether an incoming event is accepted or discarded
I I
PASSan event meets a defined condition passing to the next rule. NOPASSan event meets a defined condition and is dropped from the rule engine.
NOTE
To improve Filter rule processing, BMC Software recommends that you arrange Filter rules in an order of evaluation so that the rules that discard the most events occur first.
262
2a
No Match
2b
3a
Match
3b
NOPASS Mode
PASS Mode
NOPASS Mode
PASS Mode
event is discarded
event is discarded
# 1 2
Process description An incoming event is compared to the ECFs contained in the Filter rule. The event does not match any of the ECFs contained in the rule. a In NOPASS mode, the Filter rules forwards the event to the next Filter rule b In PASS mode, the Filter rule discards the event.
The event matches at least one of the ECFS contained in the rule. a In NOPASS mode, the Filter rule discards the event. b In PASS mode, the Filter rule forwards the event to the next Filter rule.
Chapter 6
263
Figure 29 is the syntax of an ECF definition included in a Filter rule. Figure 29 Event condition formula in a filter rule
ClassName Variable where [Expression Operator Expression, ..., SlotName: RelationalOperator Value,]
NOTE
Any type of expression can be used in the Where clause.
264
filter f1 : PASS EVENT where [ $THIS.mc_host within [svr1,svr2] ] LOGIN_EVENT END filter f2 : NOPASS EVENT where [ $THIS.severity equals INFO ] LOGIN_SUCCESS END
Table 216 demonstrate how specific events are processed by the Filter rules f1 and f2 in the example in Figure 30. Table 216 f1 and f2 Filter rules event processing examples
Event Example LOGIN_SUCCESS; mc_host=clt1; severity=WARNING; END Filter Rule Process 1. The f1 filter discards the event because mc_host does not satisfy the condition. 2. The f2 filter discards the event because the event type is LOGIN_SUCCESS which matches the condition. 1. The f1 filter accepts the event because it is a The event is accepted for additional processing. login event. 2. The f2 filter accepts the event because its severity level is not INFO and it is not a successful login event. 1. The f1 filter discards the event because the The event is discarded. event does not originate from either the svr1 or svr2 host and is not a login event. 2. The f2 filter does not consider the event because it is discarded by the f1 filter. Result The event is discarded.
Chapter 6
265
Regulate rules
Regulate rules
Use regulate rules to handle time frequency accumulations of events or repetitive occurrences of events. An event is considered a repetition of another if the event has the same values for all the slots that are defined with the dup_detect=yes facet in the BAROC definition of its event class.
In Form 1, the rule releases an event from the Hold queue when a specific number of events (#Events1) occur during the specified time window (TimeFrame1). The event sent from the Hold queue can be specified by a a literal string in the rule or by one of these parameters: $FIRST sends the first event that was received in the time window. $LAST sends the last event that was received in the time window. $HISEV sends the event with the highest severity. $LOSEV sends the event with the lowest severity.
266
The repeat_count slot of the forwarded event is set to the number of events in the Hold queue.
NOTE
The event passed from the regulate rule when specifying $FIRST, $LAST, $HISEV or $LOSEV is not the original event. It is a clone of the event that allows some timestamps and event_handle to be altered. If the event_handle has been altered, this can cause an issue when closing an event on cell B, and you expect the event to be propagated back to cell A to close the event on cell A.
In Form 2, when the Hold condition is met, a new event is generated with the rule defining its class type and its initial slot values. In this form, an instance of a custom event can be sent. Of course, a valid BAROC class definition for the custom event must exist in the Knowledge Base. The send portion is much the same as a BAROC instance for the event, except that the righthand side of the equal sign can contain expressions.
In both forms, the Unless clause resets the time window. The time windows for the Hold and Unless clauses are sliding windows. After the Hold or Unless clause executes, all events in the window are dropped from consideration and the beginning point of the time window moves to the next event received for consideration. The time frame is specified in seconds, minutes, hours, or days.
regulate RuleName : ECF hold #Events1 within TimeFrame2 send $FIRST | $LAST | $HISEV | $LOSEV [ unless #Events3 within TimeFrame4 close ] END
Figure 32 shows the Form 2 Regulate rule syntax. Figure 32 Regulate rule syntax Form 2
regulate RuleName : ECF hold #Events1 within TimeFrame2 send { Chapter 6 Event rule types and syntax 267
Figure 32
ClassName ; SlotName = Value ; ... } [ unless #Events3 within TimeFrame4 close ] END
Figure 33 illustrates the correct syntax for sending a custom event to the next rule rather then an event from the hold queue, as is the default in a Regulate rule. Before the custom event can be sent by the rule, it must be defined in a .baroc file in the Knowledge Base. Figure 33 Regulate rule syntax to send a custom event
regulate RuleName : ClassName where [Expression Operator Expression, ... SlotName: RelationalOperator Value,] hold #Events within TimeFrame send { ClassName ; SlotName = Value ; ... } [ unless #Events within TimeFrame close ] END
268
Figure 34
regulate User_Authentication : LOGIN_FAILURE ($LF) where [ $LF.user outside [root, Administrator] ] hold 5 within 1 m send $FIRST END
Note the required space between the value and the scale factor (hold 5 within 1 m). In Figure 35, the Regulate rule monitors the swap space availability and alerts the administrator of the condition by sending a Repeated_SwapAvail_Low event. The Unless clause determines whether the frequency of duplicate events decreases. If the number of SwapAvail events received decreases so that only one SwapAvail event remains within five minutes, the Repeated_SwapAvail_Low event is closed. Figure 35 regulate rule example 2
regulate Swap_Availability : SwapAvail ($SA) hold 4 within 2 m send { Repeated_SwapAvail_Low ; hostname = $LAST.hostname ; origin = $LAST.origin ; msg = Swap space low condition ; } unless 2 within 5 m close END
The Regulate rule in Figure 36 assumes that a dynamic data table has been designed and populated like the example. Figure 36 Regulate rule example 3
MC_DATA_CLASS : REGULATE_DATA ISA DATA DEFINES { rd_slot_str: STRING, key=yes; rd_slot_hold: INTEGER; rd_slot_hwithin: INTEGER; rd_slot_unless: INTEGER; rd_slot_uwithin: INTEGER; }; END
Chapter 6
269
New rules
The Regulate rule in Figure 37 uses different constants for the regulation of the SwapAvail_Low event, depending on whether the computer is a production computer or a research computer. During the evaluation of the Using clause the appropriate instance is retrieved from the dynamic data tables. If no instance of data is found by the evaluation of the Using clause, the regulate does not occur. Figure 37 Regulate rule example 4
regulate dynamic_reg : SwapAvail ($REV) using REGULATE_DATA ($DATA) where [ $REV.hostname contains $DATA.rd_slot_str ] hold $DATA.rd_slot_hold within $DATA.rd_slot_hwithin send { Repeated_SwapAvail_Low ; hostname = $LAST.hostname ; origin = $LAST.origin ; msg = Swap space low condition ; } unless $DATA.rd_slot_unless within $DATA.rd_slot_uwithin close END
New rules
Use New rules to execute an action when a new event is received, for example increasing the severity level for an event or updating an existing event with new event data. New rules determine if an event becomes permanent and is placed in the repository.
NOTE
If an event is CLOSED before the New rule phase, a search for a duplicate event is conducted and, if found, is closed. The new event is dropped and no subsequent rule is evaluated. This is the default behavior. You can deactivate this behavior by setting the global configuration parameter EventAutoClose to No in the mcell.conf file. For more information about this topic see the Administration Guide.
The New rule phase is the last opportunity to prevent an event from entering the repository. An event becomes permanent and is placed in the repository when it passes the New rule phase. In the preceding rule phases, the event is not yet registered in the repository and can be dropped. Queries return only stored events. Consequently, only stored events are:
I I I
displayed in the console returned by the MQUERY command referenced by Using or Update clauses in MRL
270
New rules
The dup_detect=yes slots cannot be changed after the event becomes permanent. Such slots can be modified in the Refine and New rule phases but not in subsequent rule phases. The duplicate aspect of the event is permanently set, and as a result the dup_detect slots cannot be modified.
Incoming Event
No Match
Match
# 1 2 3
Description The incoming event is compared to the ECFs contained in the New rule. The incoming event does not match the ECF contained in the New rule. The incoming event matches the ECF in the New rule.
Chapter 6
271
triggers
executes every time a new event is received Note: Zero (0), one (1) or more trigger blocks can be present in the rule.
updates
modifies an event that matches the ECF The optional ALL keyword modifies all matching events. Two forms exist: the first updates a duplicate event. A duplicate event is a previously received event, which holds the same values for all the slots with a dup_detect=yes facet. The second form updates any event that matches the second ECF. The old event modification must be performed in the block after the selection. The rule can have zero (0), one (1) or more Update blocks.
within TimeFrame optional time window that limits to a certain value the search for a duplicate or an old event The value can be an expression, possibly dynamic if a Using clause is evaluated in the first ECF. Note: The use of time windows limits the number of events that the rule engine has to search in the repository. Use time windows whenever possible as they have a positive impact on performance.
NOTE
The drop_new primitive can be used in a block to discard the incoming event. For example, when an event of a specific class is used only to close another event but does not need to enter the repository. See New rule examples on page 273 for an example on how to use the drop_new primitive.
272
In the next example, the New rule contains a Trigger block that is used to always discard the HOST_UP event.
new UpClosesDown : HOST_UP($IN_HU) where [ status: equals OPEN ] triggers { drop_new; } updates HOST_DOWN($ORIG_HD) where [ status: equals OPEN, hostname: equals $IN_HU.hostname ] { $ORIG_HD.status = CLOSED; } END
Chapter 6
273
NOTE
The new HOST_UP event is discarded only at the end of the New rule, so the drop_new primitive can be used anywhere in the Trigger block.
The following New rule illustrates how to use the duplicate keyword to retain an old event updated while discarding all new events.
new Duplicate_Disk_Used_Percentage: DISK_USED_PERCENTAGE ($IN_DUP) updates duplicate($ORG_DUP) where [ status: not_equals CLOSED ] { $ORG_DUP.value = $IN_DUP.value ; $ORG_DUP.repeat_count = $ORG_DUP.repeat_count + 1 ; drop_new ; } END
The New rule searches the repository for another DISK_USED_PERCENTAGE event. If one is found, it is updatedthe old value is replaced by the new one and the repeat_count is increasedand the new event is discarded. If a DISK_USED_PERCENTAGE event does not exist, the new event is not discarded. The new event enters the repository and is updated by subsequent duplicate events.
274
In this example, the developer creates the data class definition to hold the up-down pairs, as well as the maximum time interval used to correlate the up event with the down event:
MC_DATA_CLASS: CLOSE_RELATION ISA DATA DEFINES { class_close: STRING, key=yes ; #eg host_down class_up: STRING ; #eg host_up interval: INTEGER, default=60 ; }; END
Once the data class structure is defined, the developer creates the data instances necessary to cover the up closes down relationships.
Close_Relation ; class_close= HOST_DOWN ; class_up= HOST_UP ; interval= 10 m ; END Close_Relation ; class_close= PROCESS_DOWN ; class_up= PROCESS_UP ; interval= 2 m ; END Close_Relation ; class_close= LINK_DOWN ; class_up= LINK_UP ; interval= 5 m ; END
The administrator than creates a generic New rule that looks up all CLOSE_RELATION instances to determine which up event updates all its matching down events found in the interval specified in the instance.
new Up_Closes_Down: EVENT ($IN_EV) using {CLOSE_RELATION($CR) where [$CR.class_up == $IN_EV.CLASS]} updates ALL EVENT($OLD_EV) where [$OLD_EV.CLASS == $CR.class_close, $OLD_EV.hostname == $IN_EV.hostname, $OLD_EV.status != CLOSED] within $CR.interval { $OLD_EV.status = CLOSED ; drop_new ; } END
Chapter 6
275
Abstract rules
Abstract rules
Abstract rules create high-level, or abstract, events based on low-level events. A new event starts at the new rules phase, skipping the filter and regulate rules phases. With Abstract rules, you can keep low-level events with cells in the lower-level of the cell hierarchy, abstract the data from low-level events into high-level events, and propagate them to a higher-level cell. A high-level cell in the hierarchy can consolidate abstract events from several low-level cells and prevent a large number of abstracted technical events for which no consolidating rules apply. For example, you can use Abstract rules to generate an abstract event that indicates
I
a service is potentially under attack because the cell has received several LOGIN_FAILURE events from a server an application is down, based on certain APPLICATION_SERVICE_DOWN messages it has received
When an Abstract rule executes, the following slots for the events are updated
I
mc_abstractions the abstracted from event, contains the list of abstraction, or high-level, events the low-level event generated mc_abstracted the abstract event, contains the list of abstracted from, or lowlevel, events that created the high-level event.
NOTE
Once an abstract event is created, the relationship cannot be removed.
276
abstract RuleName : ClassName (Variable) ##Abstraction from ClassName (Variable) ##Abstracted From ECF setup { ##Abstraction Variable.SlotName = Value ; Variable.SlotName = Value ; ... } when Variable.SlotName: RelationalOperator Value { Call ; Variable.SlotName = Value ; ... } ... END
ClassName (Variable) class that the generated, or abstract event, will have from ClassName (Variable) ECF class of the original events, that is, those events abstracted from performs an implicit duplicate detection. For example, assume that there are no events at all in the system. When the first event is received that matches the from ECF, a new abstract event is generated. When a second arrives that would lead to the same abstract event, the rule engine checks whether a duplicate of the event exists. In this case, a duplicate exists, so the instance of the duplicate event is used in the remainder of the rule. setup is executed every time the Abstract rule fires with a new low-level event The variable points to a new event or to an old one, depending on the circumstances. The Setup clause initializes, or updates, slots for the abstraction event. If slot values are not specified in the Setup clause, then the default values are assigned. Note: The behavior of the Setup block makes it a poor location in which to use a primitive. If you need the functionality of a primitive in the Setup block, it is recommended that you use the equivalent function. For more information about functions, see MRL functions and primitives on page 100. when is evaluated when a new event is received as well as when a slot change has occurred for either the abstract event or any of its related events
Chapter 6
277
abstract SLA : SERVERS_LOGIN_ATTACK($SLA) from LOGIN_FAILURE($LF) where [ origin: ip_matches 200.200.*.<25] setup { $SLA.date = $LF.date ; $SLA.hostname = SUBNET ; $SLA.origin = 200.200.0.0 ; $SLA.msg = Servers under login attack ; } when $LF.status : equals OPEN { $SLA.num_servers = $SLA.num_servers + 1 ; } when $LF.status : equals CLOSED { $SLA.num_servers = $SLA.num_servers 1 ; } END
278
Correlate rules
In Figure 40, the Abstract rule creates the APP_MISSING_PROCESS abstraction event when a PROCESS_DOWN event is received. An abstract event exists if any of the processes has failed. The setup clause populates the slots for the new abstract event. The when clauses add and remove processes from the list of down processes as corresponding events open and close. Figure 40 Abstract rule example 2
abstract AMP : APP_MISSING_PROCESSES ($AMP) from PROCESS_DOWN ($PD) where [sub_origin: within [process1, process2, process3] ] setup { $AMP.date = $PD.date ; $AMP.hostname = $PD.hostname ; $AMP.origin = $PD.origin ; $AMP.application = ABC ; $AMP.msg = Processes missing for application abc; } when $PD.status: equals OPEN { add_to_list($PD.sub_origin, $AMP.processes) ; } when $PD.status: equals CLOSED { rem_from_list($PD.sub_origin, $AMP.processes) ; } END
Correlate rules
Correlate rules build an effect-to-cause relationship between an event that occurs as a result of another event. Correlate rules execute whenever a cause or an effect event is received. The relationship between correlated events can be broken. When a Correlate rule executes and builds events, the following slot values are updated inside the cause and effect event
I I
mc_cause slotcontains the reference to the cause event mc_effects slotcontains the list of the consequence events
NOTE
The relationship between correlated rules can be broken using the unset_cause primitive. For more information about the unset_cause primitive, see Correlate rule primitives on page 281.
Chapter 6
279
correlate RuleName : ClassName ($Variable) ## Effect ECF with ClassName ($Variable) ## Cause ECF within TimeFrame when Variable.SlotName: RelationalOperator Value { Call ; Variable.SlotName = Value ; } with ClassName ($Variable) ## Cause ECF within TimeFrame when Variable.SlotName: RelationalOperator Value { Call ; Variable.SlotName = Value ; } ... END
with
specifies the attributes for the event If more than one With clause exists in a rule, the order implies the degree of correlation. For example, the first With clause has a stronger correlation than the second With clause. If a correlation already exists for the second With clause and a new event arrives that matches the first With clause, the correlation is broken with the second With clause and established with the first With clause. Note: You can use a With clause to create a correlation within a time frame.
within
specifies the maximum time difference, in seconds, between the cause and effect events for them to be considered as correlated You can use the s, m, h, and d operators to express time, respectively, in seconds, minutes, hours or days. The time frame can be an expression although this expression cannot refer to events or data objects. Only global records are permitted in the time expression.
when
are evaluated when either a cause event or an effect event is received as well as when a slot change has occurred from any of them
280
correlate App_Down : APP_DOWN ($AD) with APP_MISSING_PROCESSES ($AMP) where [ $AMP.application equals $AD.application ] within 1 m when $AMP.status equals OPEN { $AMP.severity=CRITICAL ; } END
Chapter 6
281
The Correlate rule example in Figure 43 includes multiple potential causes for a NFS server not responding. Figure 43 Correlate rule example 2
correlate nfs_and_hd : NFS_NO_RESP ($NFS) with HOST_DOWN ($HD) where [$HD.hostname equals $NFS.server] within 10 m when $HD.status not_equals CLOSED { $NFS.severity=INFO ; } when $HD.status equals CLOSED { reset_default($NFS.severity) ; unset_cause ; } with PROCESS_DOWN($PD) where [ $PD.hostname equals $NFS.server, $PD.sub_origin equals nfsd ] within 10 m when $PD.status not_equals CLOSED { $NFS.severity=INFO ; } when $PD.status equals CLOSED { reset_default ($NFS.severity) ; unset_cause ; } END
The event examples in Table 217 demonstrate how specific events are processed by the Correlate rule in Figure 43. Table 217 Correlate rule event examples
Event Cause
Example Event
The HOST_DOWN event is the cause. If an NFS_NO_RESP event and a HOST_DOWN event arrive within ten minutes of each other the cell correlates the two events. By placing the HOST_DOWN event in the first With clause, the Correlate rule considers the HOST_DOWN event to be the most likely cause of the NFS_NO_RESP event and builds a relationship between the two events, even if events match in another With clause. If the cell receives an NFS_NO_RESP event and a PROCESS_DOWN event The PROCESS_DOWN event is the within ten (10) minutes, and no HOST_DOWN event has entered the cell, cause. then the Correlate rule builds a relationship between the events.
282
Execute rules
Execute rules
The Execute rule performs a specified action when a slot value has changed in the repository. The specified action, which is either internal to the cell or running an external executable, is based on the characteristics of one or more events. The Execute rule can
I I I I
perform actions on an event format an event message update a global record or slot value generate a new event
execute RuleName : ECF when Variable.SlotName { Call; Variable.SlotName = ... } when Variable.SlotName { Call; Variable.SlotName = ... } ... END
CondOperator Value
Value;
CondOperator Value
Value;
when
causes an action to occur and is executed if the ECF for the rule passes Note: The When clause in rule phases is reevaluated whenever a value changes for a slot, if the ECF condition is met. This means that if a rule phase subsequent to the Execute phase changes a slot value, and the ECF for the Execute rule passes, the When clause is re-evaluated for that event in the Execute rule phase.
Chapter 6
283
The When clause in an Execute rule can also be written as shown in Figure 45. This form of the When clause executes the action block when the value of the slot changes, regardless of what the change is. Figure 45 When clause in an Execute rule
when Variable.SlotName
NOTE
Dynamic data values as resulting from a Using clause in the ECF may not be used in the When clause.
All slots are passed in the environment in the form of variables (with the same names as their slot names) containing the slot values.
284
All variables that exist in the environment in which the cell is started are also passed but they cannot be enumerated because they are determined by the actual runtime environment. All external action primitives have the same environment. All variables from the initial cell startup environment are passed to the environment of external actions launched from the cell.
reset_defaultresets the default value for a slot that you specify generate_eventcreates a new event add_to_listadds a value to a specified slot rem_from_list--removes a value from a specified slot
set_timersets a timer to execute at a period of time in the future executeruns an executable file for a cell
execute Disk_Msg : DiskUsedPercentage ($DUP) when $DUP.status: equals OPEN { $V1 = round($DUP.value * 100) ; concat([$DUP.sub_origin, : , $V1, % of space used], $V2) ; $DUP.msg = $V2 ; } END
Chapter 6
285
Threshold rules
In Figure 47 the Execute rule contains several When clauses for the APP_MISSING_PROCESSES event, illustrating how to use primitives such as generate_event or execute.
I
The first when clause executes upon receipt of an OPEN event. A new message is created with the concat primitive and a new event, APP_DOWN, is generated from the original event indicating the application is down. The second when clause fires to close the APP_MISSING_PROCESSES event when all processes for the application are running. The third when clause fires and generates a new event, APP_UP, indicating the application is up when the original event is CLOSED. In addition, an executable is fired that sends a sound to the system indicating the application is up again. Execute rule example 2
Figure 47
execute Event_Status : APP_MISSING_PROCESSES ($AMP) when $AMP.status: equals OPEN { concat ([Application , $AMP.application, is down.], $MSG) ; generate_event (APP_DOWN, [hostname = $AMP.hostname, origin = $AMP.origin, date = $AMP.date, application = $AMP.application, msg = $MSG ]) ; } when $AMP.processes: equals [] { $AMP.status = CLOSED ; } when $AMP.status: equals CLOSED { generate_event (APP_UP, [hostname = $AMP.hostname, origin = $AMP.origin, application = $AMP.application]) ; execute ($AMP, make_noise, [], NO) ; } END
Threshold rules
The Threshold rule counts the number of events that matches the criteria you specify, if the number of these events exceeds the amount allowed within a time frame the Threshold rule executes.
286
Incoming Event
Duplicate Event?
Added to queue
Matches Threshold?
# 1 2 3 4 5 6
Process Description An incoming event is compared to determine if it is a duplicate of another event. The event is a duplicate event and is added to the existing queue. The event is not a duplicate event, a new queue is created. The event is compared against the rule to determine if a threshold is reached. If a threshold is reached, the code in the rule is executed and the queue is deleted. If a threshold is not reached, the event remains in the queue.
Chapter 6
287
threshold RuleName : ECF when NumberOfEvents within TimeFrame { Call; Variable.SlotName = Value ; } END
NumberOfEvents TimeFrame
maximum number of events allowed in the queue specified time frame in which the number of events is received
threshold too_many_authentication_failures: SNMP_AUTHENTICATION_FAILURE ($EV) where [ $EV.status != CLOSED AND $EV.status != BLACKOUT ] when 10 within 120 { generate_event (TOO_MANY_AUTH_FAILS, [ mb_object = $EV.snmp_source_addr ]); } END
288
Propagate rules
Propagate rules
A cell uses Propagate rules to forward events or messages to one or more destination cells or gateways. For example, a Propagate rule can escalate an event from a lowerlevel cell to a higher-level cell in an environment. Each cell has one propagation buffer and one or more destination buffers. There is a destination buffer for each destination to which the cell is propagating events. Every time an event is propagated it occupies one entry in the propagation buffer. The entry for the event remains in the buffer as long as the propagate operation persists. A propagate operation terminates when the message has been acknowledged by the destination cell or when it has not been acknowledged within a specified time period. Once the propagate operation is terminated, the event is removed from the buffer. The originating cell has one destination buffer for each destination. Each event that is propagated occupies one entry in the destination buffer for each destination to which the event is propagated. When an event is propagated to all destinations, the event is immediately entered in the destination buffer of every destination. Each event in the destination buffer is in either a wait or sent state. The event remains in the wait state as long as the destination cell cannot be reached. The event is in a sent state if the event was sent to the destination cell but has not yet been acknowledged. As soon as the specified time-out periods expire and the specified retries are finished, the event is removed from the destination buffer, and the propagate operation is assumed to have failed for that destination. A Propagate rule starts with an Event Condition Formula (ECF) that must match the event under analysis to make the rule engine evaluate the rule. The Propagate rule is composed of one or more When clauses. Note that in Propagate rules, the When keyword appears at the bottom of the block unlike the syntax of the other rule phases (Execute, Abstract, Correlate) that allow When clauses. When an event is new, the When clauses are evaluated and propagation may be performed at that time. Afterwards, modifications are propagated according to the different When clauses. Propagate rules use the following modes of propagation:
I I I
topropagates to one specific cell to allpropagates to all cells in the list to one_ofpropagates to only one cell in the list. Typically, cells are tried in turn.
NOTE
If there are two Propagate rules, one that forwards all OPEN events and one that forwards all CRITICAL events, an event that arrives as OPEN and CRITICAL is propagated twice, once for each Propagate rule. To avoid generating unnecessary work for the rule engine, try to avoid this situation.
Chapter 6
289
You can use the to one_of propagation rule to configure event propagation so that when an event is sent and the first destination cell does not acknowledge the event within a specified time, then the next destination is tried. When each destination has been tried without success, the cell restarts with the first destination. You can use the to all propagation rule to propagate to all destinations. In a to all propagation, an entry is entered in each destination buffer for all destinations. The propagation operation is terminated only when all destinations either have acknowledged or timed out. The following slots for each event contains information about the path an event followed in the cell hierarchy.
I
mc_historycontains the list of cells, and the identification of the event inside
each cell, through which the event flowed before reaching the current cell.
I
which the event was forwarded. Once events have been propagated using rules, some changes are propagated automatically without the need for Propagate rules. The parameters for this mechanism reside in the mcell.propagate file. By default, status, severity and eventspecific slot changes are propagated forward, while the status is propagated backward.
NOTE
How individual slots propagate is configured in the mcell.propagate file. For more information about how to use and set up the propagation configuration file, see the Administration Guide.
290
propagate Prop_Critical : APP_DOWN ($AD) where [origin: ip_matches 172.16.23.* ] to all [ server1, server2, server3 ] when $AD.severity equals CRITICAL to one_of [ server1, server2 ] when $AD.origin ip_matches 172.16.23.<10 END
Timer rules
Use Timer rules to create timed triggers to call a rule. Timer rules are evaluated when a timer expires. Timer rules can be used to
I I I
escalate a problem delay the execution on a problem wait for a time period to see if an event remains open or changes in severity.
Timer rules can be used in the New, Abstract, Correlate, Execute, Timer, or Delete rule phases.
Chapter 6
291
NOTE
Timer rules are maintained even if a cell is restarted. Timer rules that expired when a cell was stopped execute immediately when the cell is restarted. Timer rules not yet expired execute as soon as they expire, as if the cell had not restarted.
timer RuleName : ECF timer_info : RelationalOperator { Call ; Variable.SlotName = Value ; ... } timer_info : RelationalOperator { Call ; Variable.SlotName = Value ; ... } ... END
TimerTrigger1
TimerTrigger2
292
The following primitives are not assigned to Timer rules, but can be used to help set up a timer
I I
set_timersets a timer to execute at a period of time in the future. set_timer_atsets a timer to execute on a specific date and time.
execute Timer_on_Rpt_Low_Swap : Repeated_Swap_Avail_Low($RSAL) where [$RSAL.status : equals OPEN] when $RSAL.origin : ip_matches 200.200.*.<25 { set_timer($RSAL, 120, CRITICAL) ; } when $RSAL.hostname : ip_matches 200.200.*.>25 { set_timer($RSAL, 600, MINOR) ; } END
The Timer rule in Figure 54 verifies that the event status is OPEN before evaluating the timer_info clauses. If an event matches the rule, the event severity is modified. Figure 54 Timer rule example 2
timer Rpt_Low_Swap : Repeated_Swap_Avail_Low($RSAL) where [ status: equals OPEN] timer_info : equals CRITICAL { $RSAL.severity=CRITICAL ; } timer_info : equals MINOR { $RSAL.severity=MINOR ; } END
Chapter 6
293
Delete rules
Delete rules
The purpose of Delete rules is to perform actions before an event is discarded from the repository, such as a rule that suppresses data that has no meaning without an event instance. Delete rules are evaluated whenever an event is deleted from the repository or when events are deleted using the Delete flag in the mposter command.
delete Remove_MyData : HOST_DOWN($EV) where [ $EV.status equals OPEN ] using ALL { MYDATA($MD) where <records relevant for this event> } { remove_data($MD); 294 BMC Knowledge Base Development Reference Guide
Figure 56
} END The definition for the data could be: MC_DATA_CLASS : MYDATA ISA DATA DEFINES { name : STRING ; name : INTEGER ; { END
Chapter 6
295
296
Chapter
7
298 298 300 301 303 304 306 306 306 307 307 308 308 309 309
297
Collector syntax on page 298 Collector security on page 301 Defining static collectors on page 303 Defining dynamic collectors on page 304
Collector syntax
Figure 57 Collector definition syntax
2 3 1 4
[create Expression
6
[ delete ] ]
7
298
Collector syntax
# Description 1 keyword that specifies how the text in the collector file is interpreted 2 a composed sequence consisting of the Collector Tree name, followed by the names of the collectors down the path to the actually defined collector. Collector names can contain only alphanumeric characters and the underscore character The CollectorName is assigned by: I defining the cell itself using the keyword self I specifying the parent collector name, such as Network I specifying the child collector name, such as Network.Subnet I specifying a dynamic collector name by using an asterisk, such as Network.* Note: An ECF cannot be specified in the definition of the Collector Tree. 3 specifies the permission level that users have to the collector Available permission levels include I rread access I wwrite access I xexecute access 4 role level that can access the collector Multiple roles with unique access rights may be defined for any collector. Also, the asterisk (*) creates dynamic role definitions. See Defining dynamic collectors on page 304 for more information. 5 The format for expression is the keyword $THIS followed by the name of an event slot. $THIS substitutes the slot value in place of the * in relevant collector names. Examples of the Create clause using the CORE_EVENT base class:
I I
$THIS.mc_originsubstitutes the value of mc_origin for the asterisk in the collector name $THIS.mc_causesubstitues the value of mc_cause for the asterisk in the collector name
Note: The Create clause is required when defining a dynamic collector. 6 instructs the cell to delete an empty dynamic collector after it and its child collectors have been empty for a defined period of time A Create or Delete clause always refers to the last named component only, defined as an asterisk (*). Collector definitions with a fixed last name component cannot use either a Create or Delete clause. The time period is specified in the CollectorKeepEmpty parameter in the mcell.conf configuration file. The default value is 600 seconds; the minimum value is 60 seconds. An empty dynamic collector with or without a Delete clause is deleted when empty for the specified time period and when the cell is restarted.
299
# Description 7 identifies which events require further processing by the collector This section is referred to as an Event Condition Formula (ECF). The ECF includes the name of the event class and all the slot conditions for that class. Note: The ECF portion of a collector can contain references to the dynamic data by using a Using clause. Use this type of reference with extreme care because it can result in the performance degradation of the cell, particularly when large tables are searched on unindexed slots. 8 collects all events, including any events not picked up by the collectors you define
Define Where clauses in event condition formulas (ECFs) as simply as possible. Use narrowly defined classes rather than complex Where clauses. For example:
Avoid complex pattern-matching conditions on slot contents. Design collectors to take full advantage of the class hierarchy and its specialization properties. For example, write a collector condition on a class that catches all events belonging to any of its subclasses. In the following example, the collector catches all instances of any HOST_DOWN or HOST_UP events, assuming HOST_EVENT is a superclass of HOST_UP and HOST_DOWN.
300
Collector security
The following collector does not catch all instances of HOST_UP or HOST_DOWN events because the comparison is done literally on the string.
collector HostsEvents : EVENT where (CLASS: equals HOST_EVENT) END
I
If you want to use dynamic data in the Using clause of an ECF, keep tables short and always search on indexed slots.
Collector security
The administrator for BMC Impact Manager specifies which collectors in each Knowledge Base users can view and act upon in the console. For example, a user might be able to connect to a cell but not view all the collectors. Table 219 lists the standard BMC Impact Manager roles that can be defined within the collectors. Table 219 BMC Impact Manager standard roles
Role Administrator roles Full Access Service Administrator Service Manager roles Service Managers- Senior manages services and events with full customization capabilities Service Managers Operator roles Service Operators- Senior manages events and services with full customization capabilities Service Operators manages events and services with limited customization capabilities manages services and events with limited customization capabilities manages everything in the environment manages the BMC Impact Manager infrastructure events, events, and services Description
In addition, the read-only role restricts you to viewing events and services. For more information about user roles in BMC Impact Manager, see the Administration Guide.
301
Collector security
collector self: {r[Full Access]; w[Full Access]; x[Full Access]} END collector c1: {r[Service Administrator,Service Operators]; w[Service Administrator,Service Operators]; x[Service Administrator,Service Operators]} END collector c1.one: {r[Service Managers-Senior]} END collector c1.two: {r[Service Managers-Senior], w[Service Managers-Senior]} END collector c2: {r[Service Managers-Senior,Service Administrator]; w[Service ManagersSenior,Service Administrator]; x[Service Managers-Senior,Service Administrator]} END collector c2.one: {r[Service Operators], w[Service Operators]} END collector c2.two: {r[Service Operators]} END
The following points describe the user roles and associated permissions for the collectors defined in Figure 58:
I
Users with a Full Access role have read, write, and execute permissions for all collectors and subcollectors defined in this example. Users with Service Administrator and Service Operators roles have read, write, and execute permissions on collector c1 and subcollectors c1.one and c1.two.
302
Users with a Service Managers-Senior role have read permissions at collector c1, subcollector c1.one, and read and write permissions on subcollector c1.two. Users with Service Managers-Senior and Service Administrator roles have read, write, and execute permissions on collector c2, and subcollectors c2.one and c2.two. Users with a Service Operators role have read permissions at collector c2, subcollector c2.two, and read and write permissions at subcollector c2.one.
collector self : END collector Networks : { r [Service Administrator] } END collector Networks.Local : { r [Service Operators] w [Service Operators, Service Administrator] } : EVENT where [source: ip_matches 172.16.23.<128] END
collector Networks.Remote : { w [Service Administrator] } : EVENT where [source: ip_matches 172.16.23.>128] END
The Local and Remote child collectors in Figure 59 accept only events that originate from a computer within the specified IP address range. The Local collector inherits the rights and roles defined for the Networks collector and defines additional access rights for Service Operators and Service Administrator users. The Remote child collector inherits the Networks collector rights and roles and defines additional access rights for Service Administrator users.
303
When multiple ECFs exist for a single collector, the cell interprets the ECFs by using the OR operator. If multiple slot conditions exist in the same ECF for a collector, the cell uses the AND operator. In Figure 60, the static collectors are defined with single and multiple ECFs. Figure 60 Static collector example 2
collector AllEvents : {r [Service Operators, Service Administrator, Full Access ] w [Service Operators, Service Administrator, Full Access ] x [Service Administrator, Full Access] } END collector AllEvents.Open : EVENT where [status: equals OPEN] END collector AllEvents.Ack : {x [Service Operators]}: EVENT where [status: equals ACK, severity: equals FATAL] EVENT where [severity: not_equals UNKNOWN] END collector AllEvents.NotOpen : EVENT where [status: not_equals OPEN] END
When a collector uses multiple ECFs, you must ensure that the ECFs match outcomes. For example, in Figure 60 the AllEvents.Ack collector accepts events with an ACK status. The first ECF complies with that request and adds another stipulation to accept only events with an ACK status and a FATAL severity. However, the second ECF states that the collector accepts an event with any status as long as its severity is not UNKNOWN. The access rights and permissions set in the AllEvents parent collector are inherited by all of its children collectors. The only modification to the inherited permissions is in the AllEvents.Ack collector, which adds execute access rights for a Service Operators user.
304
The following is the definition of class NET, for which events are generated for network-related issues:
MC_EV_CLASS: NET ISA EVENT ; END
In the following example, NET events are generated for network-related issues. When the issue is specific to a subsystem, the kind of subsystem is specified in the mc_object_class slot. The collector definitions shown create a collector structure for each subsystem that produces events. The name of the collector is determined by the mc_object_class slot. Events that are not related to a specific subsystem are collected in the Global subcollector. Within the subsystem collector, a distinction is made between events coming from servers and events coming from clients. When the mc_origin_class slot has the value SERVER, the event is assumed to come from a server. In that case, a subcollector is created for each server that produces events. The name of the subcollector is taken from the mc_origin slot.
collector Net END collector Net.* : NET where [$THIS.mc_object_class != ''] create $THIS.mc_object_class delete END collector Net.*.Server : NET where [$THIS.mc_origin_class == SERVER] END collector Net.*.Server.* : NET create $THIS.mc_origin END collector Net.*.Client : NET END collector Net.Global : NET END
This example assigns a read permission to a role having the same name as the value of the mc_origin slot. For example, if the name of a server is host12 in an event, the dynamic collector creates a new collector host12. The role host12 must be listed in the list of roles if it is to see what is contained in the collector.
305
NOTE
The roles computed dynamically and assigned to dynamic collectors must be defined in the BMC Portal. Also, users must receive these roles before they can access the collectors. [WRONG: not necessarily in the PORTAL anymore]. For more information about user roles, see Administration Guide.
self_collector.mrl
The self collector defines a collector for the cell. It is the parent node for all collectors defined for that cell. Figure 61 Self collector definition
catchall_collector.mrl
The catchall collector defines the All Events collector for a cell, which is the last collector in the tree. This collector is used to capture events that do not match any collector criteria. Figure 62 Catchall collector definition
Events' : Administrators'] Administrators'] Administrators']
306
mc_bystatus_collectors.mrl
mc_bystatus_collectors.mrl
This file defines the By status collector set. Table 220 lists the collectors included in the mc_bystatus_collectors.mrl file. Table 220 By Status collector set
Subcollector branch ByStatus.Open ByStatus.Acknowledged ByStatus.Assigned ByStatus.Closed ByStatus.Blackout Description shows all events in OPEN status shows all events in ACK status shows all events in ASSIGNED status shows all events in CLOSED status shows all events in BLACKOUT status
mc_bylocation_collectors.mrl
This file defines the By location collector set. This collector set collects either system events or standard events. System events are directed to the static collector named ByLocation.Syste; other events go to the By Location.* dynamic subcollector branch. Table 221 lists the collectors included in the mc_bylocation_collectors.mrl file. Table 221 By Location collector set (part 1 of 2)
Subcollector branch ByLocation.System Description This collector stores events belonging to the following classes:
I I I I I
I I
MC_CELL_CONTROL MC_CLIENT_BASE MC_ADAPTER_CONTROL MC_MCCS 'By Location'.System.'Event Processor' that collects MC_CELL_CONTROL events 'By Location'.System.'Event Processor'.'Heartbeat Log' that collects MC_CELL_HEARTBEAT_EVT events 'By Location'.System.'Event Processor'.'Connection Log' that collects MC_CELL_CLIENT and MC_CELL_CONNECT events 'By Location'.System.'Event Processor'.'Action Log' that collects MC_CELL_ACTION_RESULT events 'By Location'.System.'Adapters' that collects MC_CLIENT_BASE and MC_ADAPTER_CONTROL events 'By Location'.System.'Configuration Server' that collects MC_MCCS events
307
collector By Location.*.* At this second level, events are stored in a dynamic collector named by host name, which is extracted from their mc_host slot. If this slot is empty, the mc_host_address slot is used. If this slot is also empty, the event goes into the Unknown collector. By Location.*.*.* The name of the third level is based directly on slot mc_tool_class. Events with an empty mc_tool_class slot are not accepted at this subcollector level. The name of the fourth level is based directly on the mc_tool slot. Events with an empty mc_tool slot are not accepted at this
By Location.*.*.*.*
subcollector level.
bii4p_collectors.mrl
The bii4p_collectors.mrl file contains collector rules used by BMC Impact Integration for PATROL Enterprise Manager. For more information, see the BMC Impact Integration for PATROL User Guide.
308
mc_evr_collectors.mrl
mc_evr_collectors.mrl
The mc_evr_collectors.mrl file contains collector rules for event relations. This collector tree is used internally.
collector MC_SMC_Events: { r['Full Access', 'Service Administrators'] w['Full Access', 'Service Administrators'] x['Full Access', 'Service Administrators'] } END collector MC_SMC_Events.*: EVENT where [$THIS.mc_smc_id != ""] create cond($THIS.mc_smc_type == '', "Unknown", $THIS.mc_smc_type) END collector MC_SMC_Events.*.Impacts: EVENT where [$THIS.mc_smc_impact == 1] END collector MC_SMC_Events.*.History: SMC_STATE_CHANGE END
309
This query varies depending on the menu command selected in the Services View:
Menu command Query type All Events Impact Events History Events any open or acknowledged event associated to the component any open or acknowledged event associated to the component and elected any open or closed event of class SMC_STATE_CHANGE for that component
310
Chapter
8
312 313 314 314 314
Chapter 8
311
Event policies
Event policies
An event policy provides a mechanism to perform actions against events, much like rules. However, unlike rules, event policies are created using the policy editors in the console. For instructions for using these editors and information about out-of-the-box policies, see the Administration guide. Event policies also differ from rules in that the policy instance employs an event selector that allows specification of a number of events that meet selection criteria, giving the event policy greater flexibility. The syntax for a policy class is shown in Figure 64. Figure 64 Policy class syntax
MC_DATA_CLASS: policy_class_name ISA POLICY DEFINES { slot_name: ECF class_name; slot_name: QUERY class_name; slot_name: data_type [default=value]; ... } END
The policy entry defines the actual event selection criteria and data values to be used in the rule. The syntax for a policy entry is shown in Figure 65. Figure 65 Policy entry syntax
POLICY_CLASS_NAME; name=value; slot_name=value; ECF_slot_name=EVENT_CLASS_NAME ($Variable) [where clause]; QUERY_slot_name=CLASS_NAME ($Variable) [where clause [order clause]]; ... END
312
Event selectors
The syntax for a policy contained in a rule is shown in Figure 66. Figure 66 Policy in a rule syntax
RuleType RuleName : using_policy { policy_class_name ($Variable) where [expression op expression, ..., expression op expression] } END
Event selectors
An event selector, a required component of an event policy, provides a mechanism to select one or more events to which an event policy can apply. Rather than specifying an event upon which to perform an action, such as in a rule, a selector allows the specification of a list of event selection criteria, known as an Event Condition Formula (ECF). When an incoming event meets any of the specified event selection criteria, the cell applies the event policy to the event. The syntax for a selector class is shown in Figure 67. Figure 67 Selector class syntax
MC_DATA_CLASS: SELECTOR DEFINES { name: STRING; description: STRING; based_on: STRING, default=EVENT; ecfs: LIST_OF ECF; }; END
The syntax for a selector entry is shown in Figure 68. Figure 68 Selector entry syntax
Chapter 8
313
314
: : : : : : : :
LIST_OF STRING; LIST_OF STRING; LIST_OF STRING; LIST_OF STRING; STRING; STRING; ECF EVENT; INTEGER, default=0;
2. The tf_active calls evaluate local timeframes for the policy. The tf_udid_active calls evaluate global timeframes for the policy. 3. The selector ECF selects the event to process. 4. The actions implement the policy and the opadd call adds an entry to the operations log of the event. You can view examples of rules for policy types in MCELL_HOME/kb/rules/im_internal.mrl.
Chapter 8
315
316
Chapter
9
317 319 320 320 322 322 323 323 323 324 324 324 324 328 331 335 339
Overview
A Common Event Model (CEM) enables a consistent definition of an event. This definition specifies the format and the data, both of which each event should contain. The event should contain the same format and data, regardless of its originating source. By mapping all event sources to CEM definitions, you significantly reduce the overhead of managing and maintaining an event management solution.
Chapter 9
317
Overview
CEM definitions provide a single set of rules that work with all events. Because of the common set of rules, you can build and maintain integration clients more easily than if you had to customize event rules. An integration client that uses CEM definitions has the following advantages.
I
Reporting is standardized. A single report template work with any event, regardless of its source. Event enrichment and correlation rules are simplified. For example, one enrichment rule works with any event that is CEM-compliant. Slot names have common definition and uses. You can easily map IT events with business impacts. The CEM event format consist of default and optional fields that let you specify
I I I I I I I
event type CEM version origin information domain information object information management processes such as availability, scheduling, and so forth parameters
TIP
Events do not always contain all the information that CEM requires. In these instances, you can enrich the event by adding contextual information to it. For example, if a raw event does not contain a specific slot, you can still add slot-related information to the event through a data-enrichment process.
BMC intends to make its integrations compatible with the Common Event Model. BMC recommends that customers building any new integrations be consistent with the Common Event Model described below. The Common Event Model (CEM) defines the event fields and formats for the BMC_BaseEvent class, a super class that contains the CORE_EVENT class of the cell. The BMC_BaseEvent class makes available to the CORE_EVENT subclass several new event-related attributes. The super class BMC_BaseEvent organizes the event properties into the following groupings, as depicted in Table 223 on page 319:
318
Versioning support
Reporter component properties related to the component that has reported the event. This component is a required part of the event information if the source component and reporter component are different. If the reporter component properties are not included, it is assumed that the source and reporter components are the same. The reportable properties include event time, event ID, and component host address. Situation properties associated with detailed information about the event. These include its ITIL category, the time when the event occurred, and the severity level of the event. an optional category. The properties include metric name, metric value, metric value unit, and metric threshold. You must include all properties of the metric that you provide.
Metrics
CEM supports the following data types: Table 224 Data types
Data types INTEGER REAL STRING <ENUMNAME> LIST_OF Description 32-bit signed value 64-bit real value UTF-8 string value with a maximum length of 65535 bytes enumeration a collection of objects
Versioning support
CEM uses the EventModelVersion field (mc_event_model_version slot) to indicate the class version of the CEM that the event management system uses. If the cell implements the same CEM version number, of course there is no compatibility issue. If the cell implements a later CEM version, it translates the event to the most recent CEM format.
Chapter 9
319
Internationalization compatibility
Internationalization compatibility
The CEM classes are compatible with internationalization requirements and provide language support. You should use Unicode encoding for all text.
PropagationHistory is required if the event provider wants to receive synchronized event. RelationSource is required if the consumer wants to send or receive updates.
320
BMC recommends that you use ReconciliationIdentity (mc_smc_id) and Alias (mc_smc_alias) because they make it easier to track configuration items. Table 227 CEM to BAROC: reporter information
CEM property ResourceId (reporter) ComponentHostAddress ComponentURI ComponentCaption ComponentType EventTime EventType EventId EventSeverity EventSuggestion BAROC slot mc_tool_id mc_tool_address mc_tool_uri mc_tool mc_tool_class mc_tool_time mc_tool_rule mc_tool_key mc_tool_sev mc_tool_suggestion Required or optional optional required optional required optional required optional required optional optional
Chapter 9
321
Define your CI instances with as much detail as possible. Extend the Common Data Model only when none of its classes can contain your component objects.
If your integration sends CEM events about a BMC Atrium CI, then the event description must identify the CI. You can chose one of two options:
I
Specify the BMC Atrium CMDB ReconciliationId assigned to the CI in the mc_smc_id slot of the event description. The association between event and CI is made automatically. Use the SIM alias feature. Define an alias for a CI in its ComponentAlias field. The format of the alias syntax consists of a prefix that identifies your integration application and a value that represents a CI. Ensure that the mc_smc_alias slot, which contains the alias, of your event description exactly matches the events you want to associate with the CI. Otherwise, you can create an alias by combining slot values of the event or events that you want to associate with the CI.
Status computation
You can enable the CEM event to be included in the status computation of the component represented by the configuration item (CI). This process is known as attaching the event to the CI. To do so, define the EventInformation::EventToCIAssociationType parameter value appropriately. See Table 230 on page 323 for a listing of the values.
322
Root cause
Root cause
The CEM base class does not store this information. However, you can either
I
add a root cause attribute in an extended class derived from the CDM generate two corresponding events: one for the impacted component and another for the root cause component
BMC service impact management (SIM) best practice is to generate the two events. Both the impacted and root cause components should be defined in the same service model. When the SIM cell receives the event for the root cause component, it computes the status of the impacted component automatically.
Cross-launching
CEM makes the cross-launching from one application to another easier. CEM uses the componentURI slot (mc_object_uri and mc_tool_uri) to specify the address used to cross-launch to the
I I
components location reporters location (the component that reports the status of another)
When an application broadcasts it URI, it makes it possible for another application to access and cross-launch to it.
Chapter 9
323
Event synchronization
NOTE
BMC recommends that you also look at using federated links to perform cross-launching in the BMC Atrium CMDB. See your BMC Atrium CMDB documentation.
Event synchronization
To synchronize events with a third-party management system, you need to identify the
I I I
specific event management system that is the source of the event class that the event management system belongs to key inside the event
Free-format text
BMC recommends that you minimize free-format text because it makes pattern matching more difficult.
General properties
The general property group contains metadata information about the event. Table 231 ReportTime (optional)
Property name BAROC name Description Data type Format Example ReportTime mc_incident_report_time date and time when the event was reported by the reporting object integer UTC 1151651591
324
General properties
Data type
Chapter 9
325
General properties
Example
Description
0 - rules determine whether the event is attached to a configuration item (default value) 1 - a predefined rule attaches this event to a configuration item 2 - the event is not attached to a configuration item
integer 0
326
General properties
Chapter 9
327
328
Chapter 9
329
330
NOTE
Event providers, such BMC Performance Monitor, that are also registered in the BMC Atrium CMDB as components enhance the self-monitoring capabilities of the CEM-enabled solution.
Chapter 9
331
mc_origin_sev
Slots that begin with the mc_origin prefix follow the same format as slots that begin with mc_tool. Table 254 ResourceId (optional)
Property name BAROC name Description Data type Format Example ResourceId mc_tool_id identifies a manageable resource (component) that reports an event string text BPMPrimary
332
Chapter 9
333
334
Situation properties
Situation properties
These are descriptive properties that depict the type of event by category, its time, its assigned priority, severity, descriptive text, and so forth. Table 264 SituationCategory (required)
Property name BAROC name Description SituationCategory mc_event_category the Information Technology Infrastructure Library (ITIL) process that the event represents ENUMERATION (MC_EVENT_CATEGORY) Possible values include
I I I I I I I I I I I I
SLA_MANAGEMENT CAPACITY_MANAGEMENT SERVICE_CONTINUITY_MANAGEMENT AVAILABILITY_MANAGEMENT INCIDENT_MANAGEMENT CONFIGURATION_MANAGEMENT RELEASE_MANAGEMENT PROBLEM_MANAGEMENT CHANGE_MANAGEMENT OPERATIONS_MANAGEMENT SECURITY_MANAGEMENT FINANCIAL_MANAGEMENT SERVICE_DESK_MANAGEMENT
ENUMERATION SLA
CAPACITY_MANAGEMENT
Chapter 9
335
Situation properties
AVAILABILITY_MANAGEMENT
INCIDENT_MANAGEMENT
CONFIGURATION_MANAGEMENT
RELEASE_MANAGEMENT
PROBLEM_MANAGEMENT
CHANGE_MANAGEMENT
OPERATIONS_MANAGEMENT
SECURITY_MANAGEMENT
336
Situation properties
SERVICE_DESK_MANAGEMENT
Chapter 9
337
Situation properties
338
Metric properties
Metric properties
Metric properties are optional. However, if you do use the metric definition, you must include all related metric properties. Table 273 MetricName (optional)
Property name BAROC name Description Data type Format Example MetricName mc_parameter name of the metric parameter that went into alarm or that triggered the event string Unicode text HardDiskUsage
Metric properties
340
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index
Symbols
# , usage in BAROC 46 $, in variable name 227 *, usage in BAROC 46 +, usage in BAROC 46 .baroc files 22, 23 .load files 22, 24, 226 .loadwic files 24, 226 .mrl files 23, 24, 226 .pkg files 23, 226 .wic files 23, 24, 226 .xact files 26, 249 <>, usage in BAROC 46 @kbversion annotation 27 SLOTREF 106 STRING 83, 106 asterisk (*), usage in BAROC 46
B
BAROC asterisk 46 brackets 46 compiling and loading files 58 identifiers 46 language symbols 46 language syntax 46 base classes CORE_EVENT 49 based_on slot 77 BEM_MATCH_TABLE data class 74 pattern matching 75 processing 75 bem_match_table.baroc file 60 bii4p.baroc file 60 bii4p_collectors.mrl file 308 bin directory 22 BMC Impact Manager class files 60 roles 301 BMC Portal defining roles for collectors 306 BMC Software, contacting 2 Body clause in rules 239 syntax 239 braces to delimit action blocks 227 brackets required for primitive arguments 227 usage in BAROC 46
A
Abstract rules described 276 examples 278 phase described 36 primitives 278 syntax 277 When clause 237 action blocks 227 action-related primitives and functions 107 actions directory 24 adapter_host slot 63 administrator slot 63 ALL keyword Using clause 235 angle brackets, usage in BAROC 46 ANY argument type decribed 83, 106 apache.baroc file 60 argument types ANY 83, 106 ENUM 83, 106 for primitives and functions 83, 106 INTEGER 83, 106 LIST_OF 83, 106 OBJECT 106 POINTER 106 REAL 83, 106
C
catchall_collector.mrl file 306 cell names spaces in 226
Index
341
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
CELL_BUILD variable 284 CELL_DATE variable 284 cell_location slot 69 cell_name slot 69 CELL_NAME variable 284 CELL_RELEASE variable 284 cells sending events to 249 starting and stopping 27 character case for MRL 227 class hierarchy 62 class instances defining 55 CLASS variable 284 class_name slot 254 classes CORE_DATA 72, 73 CORE_EVENT 62, 63 data hierarchy 72 defining 47 definition examples 56 directory 22 files for 60 syntax for defining 47 clauses Body 239 conditions for Using 234 Unless 236 Using 233 When 237 Where 230 collector keyword 299 collectors bii4p_collectors.mrl 308 catchall_collector.mrl 306 creating 298 defaults for event management 306 defaults for service impact management 309 directory 23, 24, 298 expression 300 mc_bylocation_collectors.mrl 307 mc_bystatus_collectors.mrl 307 mc_evr_collectors.mrl 309 MCxP 308 MCxP collector set 308 naming 299 permissions 299, 302 roles 299, 301 security 301 self_collector.mrl 306 static 303 syntax 298, 300 commands mccomp 26, 248 mcontrol 26 mcrtcell 25 mgetinfo 28 mkb 25 msend 249 Common Event Model (CEM) adding attributes 323 associating events with CIs 322 BMC_BaseEvent class 318 component address elements 332 component address properties 330 CORE_EVENT class 318 data types 319 description 317 event reporting 331 event synchronization 324 general properties 324 I18N 320 ITIL processes 335 mapping to Baroc 320 mapping to CORE_EVENT 320 mc_event_category 335 mc_event_category values 335 metric properties 339 property groupings 319 reporter component properties 331 root cause 323 situation properties 335 source component properties 328 versioning 319 compiling BAROC 58 Knowledge Bases 26 Knowledge Bases with trace 26 rules 248 version annotations 28 condition operators for Where clauses 231, 232 conditions for Using clause 234 confirm_external() primitive in Refine rules 261 conventions for MRL 226 CORE_DATA class 49, 72, 73 CORE_EVENT base class 49, 63 CORE_EVENT class 62 Correlate rules described 279 examples 281 phase described 36 primitives 281 syntax 280 When clause 237 Create clauses in collectors 299 creating collectors 298 Knowledge Bases 25
342
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
customer support 3 described 294 examples 294 phase described 36 primitives 294 syntax 294 deprecated slots 255 substitution 79 description slot 77 directories bin 22 classes 22 collector 298 collectors 23 data 23 for KB components 23 lib 23 record 23 rules 23 structure for Knowledge Bases 21 dup_detect facet, described 51 duration slot 63 dynamic collectors defining 304 roles 305 specifying 299 dynamic data creating New rule for 274 retrieving in rules 233 using in rules 242
D
data defining indexes for 234 dynamic 242 retrieving in rules 229 data classes BEM-MATCH_TABLE 74 CORE_DATA 49, 73 defining 47 definition example 57 directory 23 hierarchy 72 MC_CALENDARING 73 MC_SM_DATA class 73 metaclass 48 POLICY 77 SCHEDULE 74 SELECTOR 77 TIME_FRAME 74 TIME_ZONE 74 universal identifier 50 data directory 23 data instances directory 23 retrieving with Using clause 233 data types described 82 ENUM 82 EnumName 49 INT32 49 INTEGER 49, 82 LIST_OF 49 POINTER 49, 82 REAL 49, 82 SIMPLE 49 STRING 49, 82 Tivoli TEC 49 data_handle slot 73 date slot 63 date_reception slot 63 declaring variables 241 default facet, described 51 defining class instances 55 classes 47 classes, examples 56 dynamic collectors 304 global records 58 indexes 246 static collectors 303 Delete clauses in collectors 299 Delete rules
E
ea_event.baroc file 60 ECFs in collectors 300 Where clause 230 ecfs slot 77 ecfs_descr slot 77 enabled slot 77 END keyword 227 ENUM argument type described 83, 106 enumerations internal 52 MC_EVENT_CATEGORY 53 MC_EVENT_SUBCATEGORY 55 MC_PRIORITY 53 MC_YESNO 55 SEVERITY 52 STATUS 52 syntax 51 EnumName data type 49 error_code slot 255 error_column slot 254 error_goal slot 255 error_line slot 254
Index
343
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
error_message slot 254, 255 error_source slot 255 errors in event processing 255 EVENT class 69 event classes CORE_EVENT 63 definition example 56, 57 directory 23 EVENT 69 hierarchy 62 MC_CELL_CONTROL 69 metaclass 48 universal identifier 50 Event Condition Formulas, See ECFs event management collectors 306 event policies described 312 MC_CALENDARING data class 73 rules 314 syntax 312 event processing errors 255 rule phases 35 event selection clauses described 230 event selectors described 313 event slot 255 event_handle slot 63 event_text slot 254 eventlog.baroc file 60 events defining classes 47 defining indexes for 234 MC_CELL_PARSE_ERROR 254 MC_CELL_PROCESS_ERROR 255 MC_CELL_UNDEFINED_CLASS 254 MC_EVENT_CATEGORY enumeration 53 MC_EVENT_SUBCATEGORY enumeration 55 MC_PRIORITY enumeration 53 MC_YESNO enumeration 55 referencing a particular slot in rules 227 retrieving with Using clause 233 selecting in rules 230 sending to a cell 249 SEVERITY enumeration 52 STATUS enumeration 52 undefined 253 Execute rules described 283 environment variables 284 examples 285 phase described 36 primitives 285 syntax 283 When clause 237 expressions in collectors 300
F
facets default 51 described 50 dup_detect 51 hidden 51 key 51 parse 51 read_only 51 representation 51 files .baroc 22, 23 .load 22, 24, 226 .loadwic 24, 226 .mrl 23, 24, 226 .pkg 23, 226 .wic 23, 24, 226 .xact 26, 249 apache.baroc 60 bem_match_table.baroc 60 bii4p.baroc 60 bii4p_collectors.mrl 308 catchall_collector.mrl 306 ea_event.baroc 60 eventlog.baroc 60 extensions for KB components 23 for classes 60 im_policies.baroc 60 ips.baroc 60 loading BAROC 58 manifest.kb 24 mc_bylocation_collectors.mrl 307 mc_bystatus_collectors.mrl 307 mc_deprecated_filter.baroc 60 mc_deprecated_kb_data.baroc 60 mc_deprecated_notification.baroc 60 mc_deprecated_propagation.baroc 60 mc_evr_collectors.mrl 309 mc_evtdata_internal.baroc 60 mc_root_internal.baroc 48, 60 mc_root_redef.baroc 60, 78 mc_sm_cost.baroc 61 mc_sm_custom.baroc 61 mc_sm_event_mapping.baroc 61 mc_sm_maintenance.baroc 61 mc_sm_notifiy.baroc 61 mc_sm_object.baroc 61 mc_sm_propagation.baroc 61 mc_sm_root.baroc 61 mc_sm_slm.baroc 61 mc_tec_severity.baroc 61
344
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
mccs.baroc 61 mcxa.baroc 61 mcxp.baroc 61 MRL 226 patrol_em.baroc 61 patrol_portal.baroc 61 ppm_classes.baroc 61 self_collector.mrl 306 sim.wic 23 sim_decl.wic 23 state_change.baroc 61 Filter rules described 262 examples 265 phase described 35 primitives 264 processing during phase 263 syntax 263 find_match() function and primitive creating BEM_MATCH_TABLE 74 functions in Body clause 239 functions and primitives argument types 83, 106 overview 106 input_match slot 74 instances defining 55 of interface classes 245 querying 234 syntax for definitions 55 INT32 data type 49 INTEGER argument type described 83, 106 INTEGER data type 49 interface classes defining 47 definition example 57 directory 24 metaclass 48 interfaces instances 245 syntax in rule 245 using in rules 244 internal enumerations 52 ips.baroc file 60
K
kbmodules argument 28 kbsources argument 28 kbversion primitive described 28 key facet, described 51 Knowledge Bases compiling 26 compiling with trace 26 creating 25 directories 23 directory structure 21 file extensions 23 importing 25 index file 24 integrating with a unified KB 25 loading 26 managing 24 retrieving version information with kbversion 28 retrieving version information with mgetinfo 28 subdirectories 22 versioning 27 versioning mechanism 27
G
generic rule, creating 274 get_external() primitive in Refine rules 261 global records defining 58 directory 24 syntax 244 using in rules 243
H
hashed indexes described 246 hidden facet, described 51 HOME variable 284
I
identifiers, usage in BAROC 46 if-then-else construct 240 im_policies.baroc file 60 importing Knowledge Bases 25 indexes defining 246 defining on events and data 234 in Using clause 247 using in rules 246
L
lib directory 23 limit for literal strings 227 LIST_OF argument type described 83, 106 LIST_OF data type 49 literal strings
Index
345
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
character length limit 227 single quotes 226 loading BAROC files 58 Knowledge Bases 26 LOGNAME variable 284 mc_host_class slot 65 mc_incident_report_time slot 65 mc_incident_time slot 65 MC_INTERFACE metaclass 48 mc_local_reception_time slot 65 mc_location slot 65 mc_modhist slot 65 mc_modification_time slot 73 mc_notes slot 65 mc_notification_history slot 65 mc_object slot 65 mc_object_class slot 66 mc_object_owner slot 66 mc_object_uri slot 66 mc_operations slot 66 mc_origin slot 66 mc_origin_class slot 66 mc_origin_key slot 66 mc_origin_sev slot 66 mc_original_priority slot 66 mc_original_severity slot 66 mc_owner slot 66 mc_parameter slot 67 mc_parameter_threshold slot 67 mc_parameter_unit slot 67 mc_parameter_value slot 67 MC_PRIORITY enumeration 53 mc_priority slot 67 mc_propagations slot 67 MC_PUBLISH_DATA_CLASS metaclass 48 mc_relation_source slot 67 mc_root_internal.baroc file 48, 60 mc_root_redef.baroc file 60 mc_root_redef.baroc files 78 mc_service slot 67 mc_sm_cost.baroc file 61 mc_sm_custom.baroc file 61 MC_SM_DATA class 73 mc_sm_event_mapping.baroc file 61 mc_sm_maintenance.baroc file 61 mc_sm_notify.baroc file 61 mc_sm_object.baroc file 61 mc_sm_propagation.baroc file 61 mc_sm_root.baroc file 61 mc_sm_slm.baroc file 61 mc_smc_id slot 67 mc_smc_impact slot 67 mc_smc_priority slot 67 mc_smc_type slot 67 mc_tec_severity.baroc file 61 mc_timeout slot 68 mc_tool slot 68 mc_tool_address slot 68 mc_tool_class slot 68 mc_tool_key slot 68 mc_tool_rule slot 68 mc_tool_sev slot 68
M
managing Knowledge Bases 24 manifest.kb file 24 mc_abstracted slot 63 mc_abstraction slot 63 mc_account slot 63 mc_acl slot 63 mc_action_count slot 63 mc_arrival_time slot 63 mc_associations slot 63 mc_bad_slot_names slot 64 mc_bad_slot_values slot 64 mc_bylocation_collectors.mrl file 307 mc_bystatus_collectors.mrl file 307 MC_CALENDARING class 73 mc_cause slot 64 MC_CELL_CONTROL class 69 MC_CELL_PARSE_ERROR event 254 slots 254 MC_CELL_PROCESS_ERROR event 255 slots 255 MC_CELL_UNDEFINED_CLASS event 254 slots 254 mc_client_address slot 64 mc_collectors slot 64 mc_creation_time slot 73 MC_DATA_CLASS metaclass 48 mc_date_modification slot 64 mc_deprecated_filter.baroc file 60 mc_deprecated_kb_data.baroc file 60 mc_deprecated_notification.baroc file 60 mc_deprecated_propagation.baroc file 60 mc_effects slot 64 MC_EV_CLASS metaclass 48 MC_EVENT_CATEGORY enumeration 53 mc_event_category slot 64 mc_event_model_version slot 64 mc_event_relations slot 64 MC_EVENT_SUBCATEGORY enumeration 55 mc_evr_collectors.mrl file 309 mc_evtdata_internal.baroc file 60 mc_history slot 64 mc_host slot 64 mc_host_address slot 65
346
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
mc_tool_suggestion slot 68 mc_tool_time slot 68 mc_tool_uri slot 68 mc_udid slot 50, 73 mc_ueid slot 50, 69 MC_YESNO enumeration 55 mccomp command 26, 248 mccs.baroc file 61 MCELL_HOME environment variable 284 mcontrol command 26 mcrtcell command 25 mcxa.baroc file 61 MCxP collector set 308 mcxp.baroc file 61 metaclasses described 48 MC_DATA_CLASS 48 MC_EV_CLASS 48 MC_INTERFACE 48 MC_PUBLISH_DATA_CLASS 48 TEC_CLASS 48 mgetinfo command 28 mkb command 25 ModuleName parameter 27 MRL character case 227 conventions 226 END keyword 227 files 226 syntax 227 variable names 227 msend command 249 msg slot 69
P
parse facet, described 51 PASS mode 262 patrol_em.baroc file 61 patrol_portal.baroc file 61 pattern matching 75 permissions for collectors 299, 302 phases of event processing 35 PKG_NAME variable 284 plus sign (+), usage in BAROC 46 POINTER argument type described 106 POINTER data type 49 POLICY class described 77 syntax 312 pound sign (# ), usage in BAROC 46 ppm_classes.baroc file 61 primitives argument syntax 227 in Body clause 239 primitives and functions action-related 107 argument types 83, 106 overview 106 product support 3 Propagate rules described 289 examples 291 phase described 36 primitives 291 syntax 290 When clause 237 publishing metaclass 48
N
name slot 74, 77 naming collectors 299 New rules creating for dynamic data 274 described 270 examples 273 phase described 35 primitives 273 syntax 272 newline characters in slot values 227 NOPASS mode 262
Q
query clause, in rules 229 quotation marks for literal strings 226
R
read_only facet 51 REAL argument type described 83, 106 REAL data type 49 records directory 23 ref_instances_classes slot 74 Refine rules described 259 examples 261
O
OBJECT argument type described 106 output_expressions slot 74
Index
347
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
phase described 35 primitives 261 processing during phase 259 syntax 260 using interfaces in 245 Regulate rules described 266 examples 268 forms of 266 phase described 35 primitives 268 processing during phase 266 syntax 267 repeat_count slot 69 representation facet, described 51 REQUESTOR variable 284 roles collector access 299 in BMC Impact Manager 301 in collectors 301 in dynamic collectors 305 rule phases described 35 illustrated 35 RULE_NAME variable 284 rules body 229 Body clause 239 compiling 248 directory 23, 24 ending 227 event processing phases 35 for event policies 314 global records 243 if-then-else construct 240 query clause 229 querying instances 234 retrieving data 229 selecting events 230 syntax 227 testing 249 tracing 249 Unless clause 236 Using clause 233 using dynamic data 242 using indexes 246 using interfaces 244 using variables in 241 When clause 237 Where clause 230 writing 226 security for collectors 301 selection criteria in rules 230 SELECTOR class described 77 syntax 313 selectors described 313 syntax 313 self collectors file 306 self keyword 299 self_collector.mrl file 306 sending events to a cell 249 service impact management collectors 309 service models class definitions directory 24 publishing metaclass 48 SEVERITY enumeration 52 severity slot 69 SHELL variable 284 sim.wic file 23 sim_decl.wic file 23 SIMPLE data type 49 single quotes for cell names 226 for literal strings 226 slot assignments in Body clause 239 slot facets, See facets slot values newline character 227 SLOTREF argument type described 106 slots adapter_host 63 administrator 63 based_on 77 cell_location 69 cell_name 69 data_handle 73 date 63 date_reception 63 defining enumerations 51 deprecated substitution 79 description 77 duration 63 ecfs 77 ecfs_descr 77 enabled 77 event_handle 63 input_match 74 mc_abstracted 63 mc_abstraction 63
S
SCHEDULE data class 74 scripts and programs directory 24
348
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
mc_account 63 mc_acl 63 mc_action 63 mc_arrival time 63 mc_associations 63 mc_bad_slot_names 64 mc_bad_slot_value 64 mc_cause 64 MC_CELL_PARSE_ERROR 254 MC_CELL_PROCESS_ERROR 255 MC_CELL_UNDEFINED_CLASS 254 mc_client_address 64 mc_collectors 64 mc_creation_time 73 mc_date_modification 64 mc_effects 64 mc_event_category 64 mc_event_model_version 64 mc_event_relations 64 mc_history 64 mc_host 64 mc_host_address 65 mc_host_class 65 mc_incident_report_time 65 mc_incident_time 65 mc_local_receptions_time 65 mc_location 65 mc_modhist 65 mc_modification_time 73 mc_notes 65 mc_notification_history 65 mc_object 65 mc_object_class 66 mc_object_owner 66 mc_object_uri 66 mc_operations 66 mc_orgin_key 66 mc_orginal_severity 66 mc_origin 66 mc_origin_class 66 mc_origin_sev 66 mc_original_priority 66 mc_owner 66 mc_parameter 67 mc_parameter_threshold 67 mc_parameter_unit 67 mc_parameter_value 67 mc_priority 67 mc_propagations 67 mc_relations_source 67 mc_service 67 mc_smc_id 67 mc_smc_impacts 67 mc_smc_priority 67 mc_smc_type 67 mc_timeout 68 mc_tool 68 mc_tool_address 68 mc_tool_class 68 mc_tool_key 68 mc_tool_rule 68 mc_tool_sev 68 mc_tool_suggestion 68 mc_tool_time 68 mc_tool_uri 68 mc_udid 73 mc_ueid 69 msg 69 name 74, 77 output_expressions 74 ref_instances_classes 74 referencing in rules 227 repeat_count 69 severity 69 status 69 syntax for defining 47 tag 74 types of 49 SLOTS variable 284 sorted indexes described 246 spaces in cell name 226 starting cells with mcell 27 state_change.baroc file 61 static collectors defining 303 STATUS enumeration 52 status slot 69 stopping cells with mkill 27 STRING argument type described 83, 106 STRING data type 49 string length 227 strings character limit 227 support, customer 3 symbols for BAROC language 46 syntax for BAROC language 46 for Body clause 239 for collectors 298, 300 for enumerations 51 for event policies 312 for Filter rules 263 for global records 244 for instance definitions 55 for interface rule 245 for rules 227 for variables 241 of class definitions 47
Index
349
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
of selectors 313
V
variables CELL_BUILD 284 CELL_DATE 284 CELL_NAME 284 CELL_RELEASE 284 CLASS 284 declaring 241 HOME 284 LOGNAME 284 MCELL_HOME 284 naming 227 PKG_NAME 284 REQUESTOR 284 RULE_NAME 284 SHELL 284 SLOTS 284 syntax 241 TERM 284 using in rules 241 WINDOWID 284 VersionID parameter 27 versioning compiling 28 Knowledge Bases 27 mechanism 27 retrieving version information with kbversion 28 retrieving version information with mgetinfo 28 viewing transaction logs 249
T
tag slot 74 TEC_CLASS metaclass 48 technical support 3 TERM variable 284 testing rules 249 Threshold rules described 286 examples 288 phase described 36 primitives 288 processing during phase 287 syntax 288 TIME_FRAME data class 74 TIME_ZONE data class 74 timeframes data class 73 Timer rules described 291 examples 293 phase described 36 primitives 292 processing during phase 292 syntax 292 Tivoli TEC data type 49 metaclass 48 tracing rules 249 transaction logs viewing 249
W
When clauses in rules 237 Where clauses condition operators 231, 232 in collectors 300 in rules 230 wildcards BEM_MATCH_TABLE 75 WINDOWID variable 284 writing rules 226
U
undefined events 253 universal identifiers for events and data 50 mc_udid 50 mc_ueid 50 Unless clauses in rules 236 unset_cause() primitive in Correlate rule 281 Using clauses ALL keyword 235 conditions 234 in rules 229, 233 indexes in 247
350
Notes