bmc knowledge base development reference guide.pdf
DESCRIPTION
BMC Knowledge Base Development Reference Guide.pdfTRANSCRIPT
www.bmc.com
BMC Knowledge Base Development Reference Guide
Supporting
BMC Event and Impact Management 2.0BMC ProactiveNet Performance Manager 8.0
November 2009
Contacting BMC Software
You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada
Address BMC SOFTWARE INC2101 CITYWEST BLVDHOUSTON TX 77042-2827 USA
Telephone 713 918 8800 or800 841 2031
Fax 713 918 8000
Outside United States and Canada
Telephone (01) 713 918 8800 Fax (01) 713 918 8000
© 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.
Restricted rights legendU.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA. Any contract notices should be sent to this address.
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
■ 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
Support by telephone or e-mail
In the United States and Canada, if you need technical support and do not have access to the web, call 800 537 1813 or send an e-mail message to [email protected]. (In the subject line, enter SupID:<yourSupportContractID>, such as SupID:12345). Outside the United States and Canada, contact your local support center for assistance.
Before contacting BMC
Have the following information available so that Customer Support can begin working on your issue immediately:
■ 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
■ 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
3
4 BMC Knowledge Base Development Reference Guide
ContentsChapter 1 Working with the Knowledge Base 19
What is a Knowledge Base? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20How a KB is created. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Components of a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Knowledge Base directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Knowledge Base index files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Managing a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Integrating a unified KB with pre-7.2 cell definitions . . . . . . . . . . . . . . . . . . . . . . . 25Creating a new production or test Knowledge Base—mcrtcell . . . . . . . . . . . . . . . 25Importing Knowledge Base information into a cell—mkb . . . . . . . . . . . . . . . . . . . 25Compiling a Knowledge Base—mccomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Loading a Knowledge Base into a running cell—mcontrol . . . . . . . . . . . . . . . . . . 26Implementing changes to a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Versioning a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Event classification and formatting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30How event classes are structured . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30How the Knowledge Base classifies incoming events . . . . . . . . . . . . . . . . . . . . . . . 32
Event processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Event management policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33How an event management policy differs from a rule . . . . . . . . . . . . . . . . . . . . . . 33When to use an event management policy rather than a rule . . . . . . . . . . . . . . . . 34How events are processed using rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Event collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41MetaCollectors (only available for BMC Impact Solutions) . . . . . . . . . . . . . . . . . . 43Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Chapter 2 Defining classes to manage events 45
BAROC language syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46BAROC language symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Use of quotation marks in the BAROC language . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Class definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Metaclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Slot data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Universal event and data identifier slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Slot facets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Internal enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Class instance definition syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Contents 5
Class definition examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Global record definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Global record definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Loading and compiling BAROC modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Chapter 3 Event and data classes 59
Knowledge Base class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Event class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62CORE_EVENT base event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
EVENT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69MC_CELL_CONTROL event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69PPM_EV event class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Data class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72CORE_DATA base class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
MC_SM_DATA data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73MC_CALENDARING data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73BEM_MATCH_TABLE data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74POLICY data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77SELECTOR data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Cell information class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Deprecated slots and their replacements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Chapter 4 Master Rule Language (MRL) reference 81
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Integer data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Enumeration data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Condition operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Condition operators to test ordering conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Condition operators to test range conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Condition operators to test match conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Condition operators to test conditions on IP addresses. . . . . . . . . . . . . . . . . . . . . . 94Condition operators to test class hierarchy conditions . . . . . . . . . . . . . . . . . . . . . . 97Expression operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
MRL functions and primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Primitives and functions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Action-related primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Value type conversion primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Mathematical functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Enumeration operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135String manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Time stamp functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162List operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Match table lookup primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Object slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Specific slot manipulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Object relation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6 BMC Knowledge Base Development Reference Guide
Operation environment inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Service model inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200License key functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Time frame operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Object creation and deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Specific rule-based functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Chapter 5 Event rules 225
Rules and event management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Rule structure and syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
MRL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226MRL conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226General rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
MRL event selection clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Where clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Using clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Using_policy clause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Unless clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236When clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Body clause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Variables in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Dynamic data in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Global records in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Interfaces in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Interface instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Indexes in rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Using indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Compiling rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248Testing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249Tracing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Configuring rule tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249Customizing rule trace message headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Undefined events, processing errors, and deprecated slots . . . . . . . . . . . . . . . . . . . . 253Undefined events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Event processing errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255Using deprecated slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Chapter 6 Event rule types and syntax 257
Refine rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Refine rule processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Refine rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Refine rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261Refine rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Filter rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262Filter rule processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Filter rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Filter rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Contents 7
Filter rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Regulate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Regulate rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Forms of the Regulate rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Regulate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Regulate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Regulate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
New rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270New rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272New rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273New rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Abstract rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Abstract rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Abstract rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Correlate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279Correlate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Correlate rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Correlate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283Execute rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Execute rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Threshold rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Threshold rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Threshold rule examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Propagate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Propagate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290Propagate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Propagate rules examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Timer rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Timer rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Timer rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Timer rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Timer rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Delete rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Delete rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Delete rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Delete rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Chapter 7 Working with collectors 297
Creating or modifying a collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Collector syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Best practices for defining collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Collector security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Defining static collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303Defining dynamic collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
8 BMC Knowledge Base Development Reference Guide
Default event management collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306self_collector.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306catchall_collector.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306mc_bystatus_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307mc_bylocation_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307MCxP collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308bii4p_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308mc_evr_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Default service impact management event collector . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Chapter 8 Policy and selector syntax 311
Event policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Event selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Format of event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . 314How a rule for a policy type is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Chapter 9 Common Event Model 317
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Versioning support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Internationalization compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Mapping quick reference: CEM to BAROC (CORE_EVENT). . . . . . . . . . . . . . . . 320
Guidelines for applying CEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Associating events with configuration items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Root cause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Adding attributes vs. adding generic slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Cross-launching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Event synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Free-format text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
CEM property groupings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Source component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Reporter component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Situation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Metric properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Index 341
Contents 9
10 BMC Knowledge Base Development Reference Guide
FiguresKnowledge Base directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Output from mgetinfo kbsources argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Event processing rule phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Enumeration definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Class hierarchy definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Superclass definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Subclass definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Data class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Interface class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57CORE_EVENT class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62CORE_DATA class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Permitted integer combinations in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Event selection criteria example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230when condition triggered by any change to a specified slot . . . . . . . . . . . . . . . . . . . 237when condition triggered by a specific change to a specified slot . . . . . . . . . . . . . . . 238when condition triggered by a specific change to a specified slot . . . . . . . . . . . . . . . 238Rule containing a when clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Sample data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Execute rule using dynamic data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Interface instance example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246Refine rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Refine rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Refine rule ECF syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Refine rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261Filter rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Filter rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Event condition formula in a filter rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264Filter rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Regulate rule syntax form 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Regulate rule syntax Form 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Regulate rule syntax to send a custom event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Regulate rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269regulate rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Regulate rule example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Regulate rule example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Abstract rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Abstract rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Figures 11
Correlate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Correlate rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Correlate rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283When clause in an Execute rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284Execute rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Execute rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Threshold rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Propagate rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Timer rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Timer rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Timer rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Delete rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Delete rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Collector definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Collector tree definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Static collector example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303Static collector example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304Self collector definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Catchall collector definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306MC_SMC_EVENTS collector definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Policy class syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Policy entry syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Policy in a rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Selector class syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Selector entry syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
12 BMC Knowledge Base Development Reference Guide
TablesKnowledge Base subdirectories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Knowledge Base file extensions and directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Cell rule phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35BAROC syntax symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Core and metaclass event and data classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Slot facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51MC_EVENT_CATEGORY event categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Default Knowledge Base class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60CORE_EVENT base class slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63MC_CELL_CONTROL slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69PPM_EV slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70ABNORMALITY slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70ALARM slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71CORE_DATA slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73BEM_MATCH_TABLE class attribute (slot) definitions . . . . . . . . . . . . . . . . . . . . . . . . 74POLICY slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77SELECTOR slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77MC_CELL_INFO slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Deprecated slot substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Logical combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83==/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85!=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86</2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86<=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87>/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87>=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88between/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88within/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89outside/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89contains/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90contained_in/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91contains_one_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91has_prefix/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92has_suffix/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92matches/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93ip_smaller_or_equals/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94ip_greater_or_equals/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95ip_matches/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96ip_matched_by/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Tables 13
superclass_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97subclass_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Alphabetical list of primitives and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100action_requestor/1 syntax argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107action_requestor/2 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108action_requestor/3 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109action_return/2 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110admin_execute/5 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111admin_execute/5 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112perform/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113perform/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113execute/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114confirm_external/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116get_external/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117inttostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118int_to_hex/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119int_to_hex/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119realtostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120pointertostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120string/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121stringtoint/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121stringtoreal/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122stringtopointer/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122int/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123trunc/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123round/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124real/2 or float/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125code/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125char/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126max/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126min/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127sign/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127abs/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128sqrt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128exp/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129pow/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129log/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130log10/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130sin/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131cos/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131tan/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132asin/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132acos/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133atan/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133atan2/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134gcd/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134random/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135incr/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135incr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
14 BMC Knowledge Base Development Reference Guide
incr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137incr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137incr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138incr/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138decr/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139decr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140decr2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140decr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141decr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142decr/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142concat/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143strlen/2 and len/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143tolowercase/2 and lower/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144touppercase/2 and upper/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145strpart/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146strnpart/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146strextract/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147substring/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148substring/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148strip/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149strip/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Possible values for the $POS argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150strip/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Possible values for the $POS argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151strtolist/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152strmatch/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152match_regex/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154match_regex/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155match_regex/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157sprintf/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158mapslots/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158mapslots/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159has_substring/2 syntax argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160has_substring/3 syntax argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161time_stamp/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162time_stamp_to_cim/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162time_stamp_to_str/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163time_stamp_to_str/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164time_extract/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164str_to_time_stamp/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166listlen/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167listgetelt/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167listmember/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168listdelete/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169listappend/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169listdisjoint/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170listintersect/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170listunion/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171listsubtract/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Tables 15
listremdup/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172listwalk/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173add_to_list/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173rem_from_list/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174find_match/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174find_match_entry/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177apply_match_entry/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178get_list_slotvalues/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179set_list_slotvalues/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180class_path/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181reset_default/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182ntadd/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182ntcnt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182ntget/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183ntset/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184opadd/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184opadd/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185opcnt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185opget/7 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186opget/6 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187opget_time/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187opget_author/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188opget_action/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188opget_args/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189opset/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190opset/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190relate/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191unrelate/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192cellinfo/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193cellcontrol/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194kbversion/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195kbversion/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196get_env/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196send_to/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197send_to/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197send_to_ext/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198propagated_to/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199smcomps/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200key_version/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202key_verify/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203key_verify/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203tf_active/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204tf_active/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205tf_udid_active/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206tf_udid_active/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206tf_current_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207tf_current_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207tf_current_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208tf_current_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
16 BMC Knowledge Base Development Reference Guide
tf_current_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209tf_current_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209tf_prev_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210tf_prev_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211tf_prev_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211tf_prev_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212tf_prev_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212tf_prev_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213tf_next_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214tf_prev_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214tf_next_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215tf_next_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215tf_next_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216tf_next_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216tf_duration/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217tf_duration/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217generate_event/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218new_data/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219remove_data/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220set_timer/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222set_timer_at/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223set_timer_at/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Syntax object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Conditions for the using clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234MC_CELL_PARSE_ERROR slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254MC_CELL_UNDEFINED_CLASS slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254MC_CELL_PROCESS_ERROR slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255Filter rule syntax descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264f1 and f2 Filter rules event processing examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Correlate rule event examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282Available environment variables in Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284BMC Impact Manager standard roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301By Status collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307By Location collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307Collectors included in the MCxP collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Property groupings: BMC_BaseEvent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319CEM to BAROC: Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320CEM to BAROC: source information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320CEM to BAROC: reporter information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321CEM to BAROC: situation information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321CEM to BAROC: metric information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321EventInformation::EventToCIAssociationType parameter values . . . . . . . . . . . . . . 323ReportTime (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324EventModelVersion (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325EventClass (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325EventId (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325Status (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325Timeout (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Tables 17
Notes (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326EventToCIAssociationType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326PropagationHistory (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327RelationSource (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Owner (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Account (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328ResourceId (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328ReconciliationIdentity (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Alias (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329ComponentHost (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329ComponentHostAddress (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329Location (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329ComponentURI (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330ComponentCaption (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330ComponentType (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330ComponentOwner (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Slots for event monitoring information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331ResourceId (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332ComponentHostAddress (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332ComponentURI (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332ComponentCaption (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333ComponentType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333EventTime (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333EventType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333EventId (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334EventSeverity (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334EventSuggestion (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334SituationCategory (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Situation category (mc_event_category) values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335SituationTime (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Priority (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Severity (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Message (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Application (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338LongMessage (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339RepeatCount (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339MetricName (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339MetricValue (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339MetricValueUnit (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340MetricThreshold (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
18 BMC Knowledge Base Development Reference Guide
C h a p t e r 1
1 Working with the Knowledge BaseThis chapter presents the following topics:
What is a Knowledge Base? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Components of a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
How a KB is created. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Knowledge Base directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Knowledge Base index files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Managing a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Integrating a unified KB with pre-7.2 cell definitions . . . . . . . . . . . . . . . . . . . . . . . 25Creating a new production or test Knowledge Base—mcrtcell . . . . . . . . . . . . . . . 25Importing Knowledge Base information into a cell—mkb . . . . . . . . . . . . . . . . . . . 25Compiling a Knowledge Base—mccomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Loading a Knowledge Base into a running cell—mcontrol . . . . . . . . . . . . . . . . . . 26Implementing changes to a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Versioning a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Event classification and formatting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30How event classes are structured . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30How the Knowledge Base classifies incoming events . . . . . . . . . . . . . . . . . . . . . . . 32
Event processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Event management policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33How an event management policy differs from a rule . . . . . . . . . . . . . . . . . . . . . . 33When to use an event management policy rather than a rule . . . . . . . . . . . . . . . . 34How events are processed using rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Event collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41MetaCollectors (only available for BMC Impact Solutions) . . . . . . . . . . . . . . . . . . 43Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Chapter 1 Working with the Knowledge Base 19
What is a Knowledge Base?
What is a Knowledge Base?A Knowledge Base (KB) defines the behavior of a cell. KB classes define what information is contained in each event. KB rules define how the events are processed. You can modify the KB to customize its behavior in your environment.
The KB is similar to a script and the cell is the engine that runs the script.
The KB is a compiled collection of files, such as event processing rules, class definitions, and executables, organized in a directory structure. The KB files are loaded by a cell at start time. The Knowledge Base instructs the cell how to format incoming event data, process received events, and display events in a console. Although many KBs can exist within a distributed environment, each cell can be associated with only one KB at a time.
How a KB is createdDuring 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 cell’s KB directory path: MCELL_HOME/etc/CellName/kb. Modifications to the KB in the CellName/kb directory apply to the CellName cell only.
Components of a Knowledge Base
A KB includes the following:
■ 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 BMC Knowledge Base Development Reference Guide
Knowledge Base directory structure
■ 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.
Knowledge Base directory structure
The Knowledge Base uses a defined directory structure to organize its files and executables. The Knowledge Base directories are in the following locations:
■ 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 Working with the Knowledge Base 21
Knowledge Base directory structure
Figure 1 lists the directory structure for a Knowledge Base.
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.
Figure 1 Knowledge Base directory structure
kb\bin
\A\h1\l2\p4\s5\w4
\classes\collectors\data\lib\records\rules
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:
■ A—independent, all UNIX, or non-Windows■ h1—HP-UX■ l2 —Linux■ p4 —AIX ■ s5 —Solaris ■ w4 —Windows
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 BMC Knowledge Base Development Reference Guide
Knowledge Base directory structure
Table 2 lists the file extensions and directory location for the each of the components contained in a KB.
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:
■ sim.wic—contains the compiled implementation of primitives and functions that are loaded by the cell at startup
■ sim_decl.wic—contains 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 Knowledge Base file extensions and directories (part 1 of 2)
Component File extension Directory
event classes .baroc kb\classes
data classes .baroc kb\classes
data instances .baroc kb\data
Table 1 Knowledge Base subdirectories (part 2 of 2)
Knowledge Base subdirectory Description
Chapter 1 Working with the Knowledge Base 23
Knowledge Base index files
Knowledge Base index files
The following files are included with the installation and are necessary for the Knowledge Base to run properly:
■ manifest.kb—serves 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.
■ .load—serves 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.
■ .loadwic—Before 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.
Managing a Knowledge BaseTo manage a Knowledge Base, you must perform several tasks by using the cell command-line interface (CLI). This section briefly describes these tasks; for more information about syntax and options available for the CLI commands, see the Administration Guide.
global records .baroc kb\records
rules .mrl kb\rules
collectors .mrl kb\collector
action executables .mrl kb\bin
service model class definitions .baroc kb\classes
interface classes .baroc kb\classes
scripts and programs not applicable kb\bin\platform
Table 2 Knowledge Base file extensions and directories (part 2 of 2)
Component File extension Directory
24 BMC Knowledge Base Development Reference Guide
Integrating a unified KB with pre-7.2 cell definitions
Integrating a unified KB with pre-7.2 cell definitions
In version 7.2.00, the unified Knowledge Base was introduced. You can integrate your cell definitions from cells older than version 7.2.00 with the unified KB of the current version of the cell.
1 Create a new cell using the mcrtcell CLI with either the -ae or -as option.
2 Copy the modifications or extensions you’ve made in old cell’s KB to the new cell’s KB.
To do so, you can manually edit the files or use your specific utilities.
3 Recompile the KB, and restart the cell.
Creating a new production or test Knowledge Base—mcrtcell
Use the mcrtcell command to create a new production or test cell and Knowledge Base. The mcrtcell command can be run only on the local computer where the cell is being created. For more information about syntax and options available with mcrtcell, see the Administration Guide.
Importing Knowledge Base information into a cell—mkb
You can use the mkb command to import an existing Knowledge Base. You can also use this command to import files containing definitions for event classes, interfaces, global records, data classes, collectors, or rules from an existing Knowledge Base.
For more information about syntax and options available with mkb, see the Administration Guide.
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.
Chapter 1 Working with the Knowledge Base 25
Compiling a Knowledge Base—mccomp
Compiling a Knowledge Base—mccomp
Each time you change, add, or delete actions, classes, collectors, or rules, you must compile the KB. The cell recognizes changes to the KB only when the cell is restarted.
Use the mccomp command to compile the Knowledge Base. The mccomp command parses event, data class and global records, and compiles the rules. For more information about syntax and options available with mccomp, see the Administration Guide.
Effects of compiling a Knowledge Base with tracing enabled
If you enable tracing by using the -t option when compiling a KB and if TraceRuleToXact=Yes in mcell.conf, an event can be tracked in the transaction log, an .xact file, as it progresses through the rule execution. Entries in the log file related to rule tracing are include a TRCX header.
However, deploying a KB compiled with the -t option can degrade performance by as much as 50 percent. BMC recommends that you do not use the -t option to compile the production KB.
Loading a Knowledge Base into a running cell—mcontrol
You must load a KB on a running cell each time that you edit collectors. Use the mcontrol reload kb command to reload the Knowledge Base while the cell is still running. For more information about the mcontrol command, see the Administration Guide.
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 BMC Knowledge Base Development Reference Guide
Implementing changes to a Knowledge Base
Implementing changes to a Knowledge Base
You must stop and start the cell to implement any changes to a cell’s KB. For instructions on stopping and starting a cell, see the Administration Guide.
Versioning a Knowledge Base
KB versioning enables you to determine which KB and which version of the KB is loaded in a cell. You can implement version information for
■ 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 modules—Version 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 Description
ModuleName 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 specifies the version (v.r.mm)
For example, 1.2.10.
Chapter 1 Working with the Knowledge Base 27
Versioning a Knowledge Base
The mccomp command compiles the @kbversion annotations into the KB object files and includes the following information about each source file in the KB:
■ 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
This example specifies that the KB contains a logical module called HelpDesk, and that its version is 1.2.01.
Retrieving KB version information in rules
You can retrieve KB module version information in a rule by using the kbversion primitive. For information about the kbversion primitive, see “kbversion/1 — retrieve global Knowledge Base module version information” on page 196.
Retrieving KB version information by using a command—mgetinfo
You use the mgetinfo command with the kbmodules and kbsources arguments to retrieve version information from the cell's loaded KB.
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.
@kbversion( HelpDesk , '1.2.01' )
mgetinfo -n cellName [-v] kbmodules|kbsources
Argument Returned results
kbmodules list of KB modules with version information
kbsources list of KB source files with compiler version information
28 BMC Knowledge Base Development Reference Guide
Versioning a Knowledge Base
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.
In addition, the KB also includes a reference copy of
■ the BMC Atrium CMDB (Configuration Management Database) Common Data Model (CDM) Service class definitions used in a cell’s service model
■ the service model for the cell, published by a BMC Impact Publishing Server
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.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 848 2351849679 collectors/pom_activeevents_collectors.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 1298 1572060265 collectors/pom_intelligentevents_collectors.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 2276 3736979305 collectors/catchall_collector.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 882 4217293348 collectors/pom_byuser_collectors.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 5411 3623989645 collectors/ibrsd_collectors.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 143 4015122127 rules/kbversem.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 145 3230031018 rules/kbverssim.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 455 3870777253 rules/mc_startup.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 1348 4183429197 rules/refine_multiple_server_events.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 35175 1041057786 rules/im_internal.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 3009 1294038250 rules/mc_intevt.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 2364 3554485946 rules/impact_admin_server.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 2595 287947525 rules/ips.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 1896 51731806 rules/mc_sm_start.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 3885 2912043582 rules/mc_sm_associate.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 11587 1724466729 rules/mc_ci_policies.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 2126 3683660578 rules/mc_sm_maintenance.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 957 4072896080 rules/mc_sm_elect.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 1865 2174473777 rules/mc_sm_attach.mrlCompiler: 8.x.xx (Build: xxx - 5-Nov-2xxx) Source file (size/checksum/name): 3885 3336615242 rules/mc_sm_shadow.mrl
Chapter 1 Working with the Knowledge Base 29
Event classification and formatting
Event classification and formattingThe event source (an event adapter, an integration application, another cell, an API, or a CLI) must provide events in the BAROC format and structure. The cell accepts and processes an incoming event if it matches an event class definition in the Knowledge Base (KB).
The following sections explain how event classes are structured and how the Knowledge Base uses event classes to classify and format incoming events.
How event classes are structured
An event class defines the types of events that the cell will accept and classifies source event data for processing. For example, one class of event might be Microsoft Windows operating system events. That event class has several subclasses: application events, security events, and system events. Each event subclass represents a common type of event that occurs, such as a network logon, that contains varying data values, such as a time stamp and the name of the host on which the logon occurred. The varying data values from a source event are stored in data fields called slots (attributes). An actual event is an instance of an event class.
Using the BAROC language, you define each event class and its slots. Each slot has a data type and can have specific attributes, called facets, that can control the values that the slot can have or control aspects of the event’s processing. Slot enumerations specify acceptable values for a particular slot.
You can think of a class definition as an empty form with its input fields representing slots, and a class instance as a completed form. A valid instance must respect slot types, and if some slot values are not specified, they are implicitly set to their default values, which are inherited from the parent class.
The following example illustrates the event class structure for Windows Event Log classes:
Class: CORE_EVENTClass: EVENTClass: MC_ADAPTER_BASEClass: WIN_EVENTLOGClass: WIN_EL_APPLICATIONClass: WIN_EL_SECURITYClass: WIN_EL_SYSTEM
30 BMC Knowledge Base Development Reference Guide
How event classes are structured
The following shows the same example with some of the slots defined for these classes:
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.
Class: CORE_EVENT - Flags: pSlot: mc_client_address - Type: STRING - Flags: rkpdh - Def:Class: EVENTClass: MC_ADAPTER_BASEClass: WIN_EVENTLOGSlot: mc_tool_class - Type: STRING - Flags: rkPDh - Def: WINEventLogClass: WIN_EL_APPLICATIONSlot: mc_tool - Type: STRING - Flags: rkPdh - Def: ApplicationClass: WIN_EL_SECURITYSlot: mc_tool - Type: STRING - Flags: rkPdh - Def: SecurityClass: WIN_EL_SYSTEMSlot: mc_tool - Type: STRING - Flags: rkPdh - Def: System
Chapter 1 Working with the Knowledge Base 31
How the Knowledge Base classifies incoming events
In summary, subclasses
■ 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
How the Knowledge Base classifies incoming events
When the event is collected by the cell, the cell compares the incoming event to the predefined event classes in the Knowledge Base to determine the event type of the incoming event and validate the event.
If an incoming event does not match one the predefined event classes, the cell takes one of the following actions:
■ 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 processingOnce 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 cell’s KB. Rules and rule syntax are described in Chapter 5, “Event rules.”
Event management policies
An event management policy is 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 management policies can be defined interactively using predefined, out-of-the-box policy types accessed through the console. You can also create new user-defined policy types to add new event processing actions.
Whether predefined or user-defined, all event management policies consist of
■ event selector■ process(es)■ timeframe(s)■ evaluation order
How an event management policy differs from a rule
Like a rule, an event management policy processes events and performs event management.
Chapter 1 Working with the Knowledge Base 33
When to use an event management policy rather than a rule
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.
When to use an event management policy rather than a rule
Use a policy if there is a fairly simple, routine action that you would like to apply to many events. If some complex event manipulation is required that is specific to a small subset of events, a rule written in MRL may be more appropriate.
In some cases, a rule can provide better performance than its event management policy equivalent. If an event management policy gives problematic performance, substituting an equivalent rule might rectify the performance issue.
How events are processed using rules
Rules are associated with a specific rule phase based on their type; each phase represents a logical stage of event processing. The cell processes each incoming event one phase at a time and evaluates each event against one rule at a time. Internal events are always processed before external events. The order in which the cell evaluates events against rules is determined by the order in which the rules were loaded.
Figure 3 on page 35 identifies the rule phases and shows how event processing proceeds, and Table 3 on page 35 describes the phases.
34 BMC Knowledge Base Development Reference Guide
How events are processed using rules
Figure 3 Event processing rule phases
Table 3 Cell rule phases (part 1 of 2)
# Rule phase Description
1 Refine validates incoming events and, if necessary, collects additional data needed before the event is processed further
2 Filter identifies events that should be discarded
2 Regulate evaluates events, and, if evaluated as true, collects duplicate events for a time period.
If a specified threshold of duplicates is reached, the Regulate phase passes an event to the next processing phase.
4 New determines which events in the event repository should be updated with new information from new incoming events
During this phase:
■ 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.
Propagate
Filter
Regulate
Abstract The New, Abstract, Correlate, and Execute rule phases can trigger a Timer rule.
Delete rules execute when a record is removed during repository cleanup.
89
5
3
2
1 Refine
Event
Delete11
Timer10
Repository
New4
An event can be discarded during any one of these phases before being added to the repository.
Threshold88
Execute7
Correlate6
to other cells
Chapter 1 Working with the Knowledge Base 35
How events are processed using rules
Rule phase processing overview
The cell uses a main loop that starts transactions for each triggering event, such as:
■ 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:
■ 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 first-in, first-out queue
5 Abstract evaluates events, and, if certain conditions are met, triggers the generation of abstraction events.
An abstraction event is a summary event based on other events that are occurring.
6 Correlate determines whether any events have a cause-and-effect relationship
7 Execute 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
Table 3 Cell rule phases (part 2 of 2)
# Rule phase Description
36 BMC Knowledge Base Development Reference Guide
How events are processed using rules
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.
Rule phase processing details
Each incoming event's processing begins with the Refine phase. A Refine phase rule allows the rule engine to start an external program to confirm the event or to obtain more information from the environment. The processing of this event is suspended until the external program returns its results. The rule engine is not idle because it processes other events in the meantime.
After the Refine phase, the incoming event enters the Filter phase where it can be discarded if it does not meet the requirements for processing. If the event is discarded in the Filter phase, it is not stored in the event repository, so it cannot be accessed by any future processes that rely on the event repository.
The Regulate rule phase, like the Refine phase, can suspend the evaluation process while it waits for events similar to those held to appear before a time window closes. Depending on the rules and circumstances, the event is then discarded or it continues the evaluation process through the remaining rules.
The New phase is the last in which the rule engine can discard an incoming event without its entering the event repository. After this phase, an event can be dropped only if it is explicitly deleted or discarded during the cleanup process.
The event then goes through the final phases, Abstract, Correlate, Execute, Threshold, and Propagate, in that order, if any rules have been defined for those phases.
Abstract rules can be used to create high-level, or abstract, events based on low-level events, such as a SERVERS_LOGIN_ATTACK event based on certain LOGIN_FAILURE events.
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 Working with the Knowledge Base 37
How events are processed using rules
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.
Internal event processing by rules
Internal events are processed in the same way as external events, but have a higher priority than external events.
The rule engine processes all the internal events before accepting new external events.
All events are process in first-in, first-out order. For example, if, during the evaluation of an internal event, another internal event is generated, the rule engine processes the second internal event first.
Internal requests by a rule
Internal requests are actions that a rule requests during the processing of an event.
The rule engine processes all internal requests in a first-in, first-out order before anything else is processed. Examples of internal requests are
■ 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 BMC Knowledge Base Development Reference Guide
How events are processed using rules
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 Working with the Knowledge Base 39
How events are processed using rules
For example, this record
is used in a rule in im_internal.mrl to set a default value to the location slot of the following event:
It also is used in the following rule:
For more information about global records, see “Global record definition syntax” on page 58.
Using event management policies for event processing
There are two types of event management policies—predefined event management policies and user-defined event management policies. Predefined event management policies are provided out-of-the box. User-defined policies are custom policies that you create.
Each event management policy defines selection criteria that is applied to incoming events to determine which events are processed. A timeframe determines when the policy is active or inactive. The evaluation order determines which policies are implemented first if there is a conflict.
RECORD EM_KB_OPTIONS DEFINES{startup_script_enabled: MC_YESNO, default = NO;default_location: STRING;}END
...if ($EM_KB_OPTIONS.default_location != "") then{$EV.mc_location = $EM_KB_OPTIONS.default_location;}...
refine exec_script_at_cell_startup:MC_CELL_START ($START) where[$EM_KB_OPTIONS.startup_script_enabled == YES]{execute($START, "startup_script", [], 'yes');}END
40 BMC Knowledge Base Development Reference Guide
Event collectors
Predefined event management policies
The two types of predefined event management policies are standard and dynamic data enrichment.
A standard event management policy requires you to use the console to input data into a policy. This type of policy works well if you only want to apply the policy to a small number of events or hosts.
A dynamic data enrichment policy provides additional context to an event by extracting data from an external source and appending it to the event so it is accessible to IT operations. For example, it may be useful for you to know the location of a particular piece of equipment. This type of information is not normally included in a standard technical event; however, you can use dynamic data enrichment to add this information to the event by accessing data stored external to the product (for example, an asset store). If you want to apply a policy to a large number of hosts or events, you should use a dynamic data enrichment policy.
Dynamic data enrichment policies require the same components as standard event management policies. However, dynamic enrichment policies allow you to import external enrichment data into the policy, rather than having to enter it manually.
An external enrichment data source can provide additional information about an event that is not available from the technology from which the event originates. An example of an external enrichment data source is a database such as an asset data store.
User-defined event policies
Predefined policies cannot cover all requirements of different product implementations. To support specialized event processing, you can also define and implement custom event policy types to do specialized event processing not supported by the predefined policy types. For instructions on creating event policy types, see the Administration Guide.
Event collectorsYou 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 Working with the Knowledge Base 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 cell’s Knowledge Base, they appear in any console that displays that cell. The cell provides default event collectors—PATROL, All Events, By Location, By Status—for the console.
How collectors are structured
Collectors are created using MRL, defined in the collectors subdirectory of the Knowledge Base, and organized in a hierarchical structure. This type of structure means that specialized collectors appear at the lowest level of the hierarchy and are subsets of the generic collectors in the higher levels of the hierarchy. As such collectors can be characterized by their position in the hierarchy as either a parent collector or a child collector.
Each collector tree represents a collector type, and each branch is a path that an event follows to locate matching criteria. When an event passes through a collector definition and matches the criteria set for that collector, the event is displayed within that collector group in the console.
After an event finds matching criteria, it ignores any remaining paths in the collector tree. An event continues to the end of the current path and searches for an accepting collector, with one of the following results:
The event is stored in the first accepting collector it encounters. This is called the event’s endpoint collector. For each collector tree, the event can be stored in only one endpoint collector.
If there is no collector on the current level that accepts the event, it proceeds to the next higher level and is stored in the first accepting collector that it encounters there. This is the event’s endpoint collector.
For more information about collectors and how event status and severity are displayed, see the User Guide.
42 BMC Knowledge Base Development Reference Guide
MetaCollectors (only available for BMC Impact Solutions)
MetaCollectors (only available for BMC Impact Solutions)
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.
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 cell’s 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.
NOTE MetaCollectors are not available for BMC ProactiveNet.
NOTE An incoming event that changes slot conditions can move from one collector to another within a cell.
Chapter 1 Working with the Knowledge Base 43
Actions
44 BMC Knowledge Base Development Reference Guide
C h a p t e r 2
2 Defining classes to manage eventsThis chapter presents the following topics:
BAROC language syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46BAROC language symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Use of quotation marks in the BAROC language . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Class definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Metaclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Slot data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Universal event and data identifier slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Slot facets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Internal enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Class instance definition syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Class definition examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Global record definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Global record definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Loading and compiling BAROC modifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Chapter 2 Defining classes to manage events 45
BAROC language syntax
BAROC language syntaxThe following syntax rules apply to the BAROC language:
■ 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 (#).
BAROC language symbols
The following symbols are used to define the syntax of the BAROC language:
Use of quotation marks in the BAROC language
You may use quotation marks for backward compatibility. Filters, for instance, are saved with quotation marks. If you use quotation marks, be sure to apply the following quoting rules:
Table 4 BAROC syntax symbols
Symbol name Symbol Description or usage
angle brackets <> Angle brackets enclose an identifier that is a non-terminal symbol that is defined elsewhere in the language definition.
square brackets
[] A block enclosed in square brackets indicates it is an optional block. The brackets themselves are not language tokens.
asterisk * An asterisk indicates a possible repetition of the preceding block.
plus + A plus sign indicates one or more instances of the preceding block.
pound # A pound symbol beginning a line denotes a comment line. Comments are not part of the language; they are not read by the BAROC parser.
NOTE All other symbols are tokens of the language.
46 BMC Knowledge Base Development Reference Guide
Class definition syntax
■ STRING—String 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 containing a single quote ( ' ) within the value.
■ LIST_OF_STRING—String 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.
Class definition syntax A BAROC class definition includes a name and one or more slot definitions that delimit acceptable values. The basic syntax for defining a class in the BAROC language is as follows:
<MetaClassName>: <ClassName> [ISA <ClassName>][DEFINES {
[ SlotName: SlotType [, SlotFacet]* ;]*}];
END
Chapter 2 Defining classes to manage events 47
Metaclasses
The syntax elements are defined as follows:
MetaclassesA 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:
■ MC_EV_CLASS■ MC_DATA_CLASS■ MC_PUBLISH_DATA_CLASS■ MC_INTERFACE■ TEC_CLASS
<MetaClassName> = MC_EV_CLASS| MC_DATA_CLASS| MC_INTERFACE| MC_PUBLISH_DATA_CLASS| TEC_CLASS
<ClassName> and <SlotName> = an optionally quoted (‘ or “) sequence of characters excluding blanks “ ‘ ; : , = ( ) [ ] { }<SlotType> = [ SINGLE | LIST_OF]
INTEGER | REAL | STRING | <Enum><SlotFacet>=
default = <SlotValC>| parse = <YesOrNo>| dup_detect = <YesOrNo>| read_only = <YesOrNo>| key = <YesOrNo>| representation = <STRING>
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.
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 BMC Knowledge Base Development Reference Guide
Slot data types
The syntax for defining event and data classes is essentially the same; however, their core classes and metaclasses differ:
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.
Slot data typesSlot definitions specify the slot types that are acceptable for processing by assigning data types to the slot.
Slot values can be simple or a list of simple values. The keyword SIMPLE identifies the simple data type and LIST_OF identifies the list data type. The keyword SIMPLE is optional and is generally omitted.
The simple data types include:
■ INTEGER—32-bit signed value■ REAL—64-bit real value■ STRING—string, maximum 64 KB■ EnumName—an enumeration whose definition must appear before the slot
definition in the BAROC declaration file
For further information about enumerations, see “Enumerations” on page 51.
Table 5 Core and metaclass event and data classes
Class type Event Data
metaclass MC_EV_CLASS MC_DATA_CLASS
base class CORE_EVENT CORE_DATA
NOTE Additional slot data types INT32 and POINTER are supported for compatibility with the Tivoli TEC product.
Chapter 2 Defining classes to manage events 49
Universal event and data identifier slots
Universal event and data identifier slotsThe following slots provide unique identifiers for event and data instances:
■ mc_ueid slot—the universal event identifier■ mc_udid slot—the 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_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:
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 facetsSlot definitions can also have slot facets that control aspects of a class instance’s 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.
mc.cellName.<extension>
mc.cellName.<extension>
50 BMC Knowledge Base Development Reference Guide
Enumerations
EnumerationsEnumerations 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
Table 6 Slot facets
Facet Description
default 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 flag indicating whether the slot is displayed in the console
parse 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.
ENUMERATION EnumName[NumVal SymbVal]*
END
Chapter 2 Defining classes to manage events 51
Internal enumerations
Internal enumerations
The following internal enumerations are included in the Knowledge Base:
■ STATUS■ SEVERITY■ MC_PRIORITY■ MC_EVENT_CATEGORY■ MC_EVENT_SUBCATEGORY■ MC_YESNO
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:
■ OPEN■ ACK■ ASSIGNED■ CLOSED■ BLACKOUT
SEVERITY enumeration
The SEVERITY enumeration lists the possible severity values for an event, as follows:
■ UNKNOWN■ OK■ INFO■ WARNING■ MINOR■ MAJOR■ CRITICAL
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.
52 BMC Knowledge Base Development Reference Guide
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.
■ PRIORITY_5 (lowest priority)■ PRIORITY_4■ PRIORITY_3■ PRIORITY_2
■ PRIORITY_1 (highest priority)
MC_EVENT_CATEGORY enumeration
The MC_EVENT_CATEGORY enumeration lists the possible categories for an event, as follows:
Table 7 MC_EVENT_CATEGORY event categories (part 1 of 2)
Category Description
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.
AVAILABILITY_MANAGEMENT
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.
Chapter 2 Defining classes to manage events 53
Internal enumerations
INCIDENT_MANAGEMENT
events relating to the Incident Management process
The process restores normal service operation as quickly as possible and minimizes the adverse impact on business operations, ensuring that the best possible levels of service quality and availability are maintained.
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.
Table 7 MC_EVENT_CATEGORY event categories (part 2 of 2)
Category Description
54 BMC Knowledge Base Development Reference Guide
Class instance definition syntax
MC_EVENT_SUBCATEGORY enumeration
The MC_EVENT_SUBCATEGORY enumeration defines the sub-category for an event, as follows:
■ 10 OTHER■ 20 APPLICATION■ 30 DATABASE■ 40 NETWORK■ 50 SYSTEM■ 60 USER_TRANSACTIONS
MC_YESNO enumeration
The MC_YESNO enumeration is used to set a YES or NO value for a slot.
Class instance definition syntax
Class; [Slot = SlotVal;] *
END
Chapter 2 Defining classes to manage events 55
Class definition examples
The syntax elements are defined as follows:
Class definition examples
In Figure 5, the data class SEVERITY_BY_APP_DOWN assigns specific severities to the appropriate APP_DOWN events:
Figure 5 Class definition example
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.
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.
SlotVal = SlotSmplVal|SlotListValSlotSmplVal =
sequence of alphanumeric or _ characters|quoted (' or ") sequence of characters
SlotListVal = '[' [SlotSmplVal {,SlotSmplVal}] ']'
MC_DATA_CLASS:SEVERITY_BY_APP_DOWN ISA DATADEFINES{
application:STRING,key=yes;severity:SEVERITY,default=WARNING;
};END
Figure 6 Class hierarchy definition example
MC_EV_CLASS :SECURITY_EVENT ISA EVENT;
END
Figure 7 Superclass definition example
MC_EV_CLASS :p_LOGIN_EVENT ISA SECURITY_EVENTDEFINES {
mc_host: dup_detect = yes ;user: STRING, dup_detect = yes ;
56 BMC Knowledge Base Development Reference Guide
Class definition examples
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.
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.
In Figure 10, the location class is an interface class with a single slot, site.
You can also define data instances in the Administration console. For information, see the Administration Guide.
};END
Figure 8 Subclass definition example
MC_EV_CLASS :LOGIN_FAILURE ISA LOGIN_EVENTDEFINES {
severity: default = MINOR ;};
END
Figure 9 Data class definition example
MC_DATA_CLASS :AppByHost ISA DATADEFINES {
host: STRING, key=yes;applications: LIST_OF STRING;
};END
Figure 10 Interface class definition example
MC_INTERFACE : location DEFINES {
site: STRING;};
END
Figure 7 Superclass definition example
Chapter 2 Defining classes to manage events 57
Global record definition syntax
Global record definition syntaxGlobal records are persistent structured global variables. The scope of these variables is the entire Knowledge Base; any other variable has a scope limited to the current rule. Global records are addressed by name.
Global record definition example
For example, a global record called UNDER_MAINTENANCE has the following definition:
In a rule, you can refer to one of the slots, as shown in the following example:
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.
Loading and compiling BAROC modificationsThe .load file determines the order in which the cell loads the BAROC files. You can maintain classes in single or multiple files, as required. Any time a new file is created, add it to the Knowledge Base for a cell.
After you modify BAROC definitions, recompile the Knowledge Base. For information about compiling the Knowledge Base, see “Managing a Knowledge Base” on page 24.
RECORDUNDER_MAINTENANCE DEFINES {
hosts: LIST_OF STRING ;}
END
$UNDER_MAINTENANCE.hosts
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.
58 BMC Knowledge Base Development Reference Guide
C h a p t e r 3
3 Event and data classesThis chapter provides information on the hierarchical structure, class files, and slot information for the base classes. This chapter presents the following topics:
Knowledge Base class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Event class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62CORE_EVENT base event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
EVENT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69MC_CELL_CONTROL event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69PPM_EV event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Data class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72CORE_DATA base class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
MC_SM_DATA data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73MC_CALENDARING data class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73BEM_MATCH_TABLE data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74POLICY data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77SELECTOR data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Cell information class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Deprecated slots and their replacements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Chapter 3 Event and data classes 59
Knowledge Base class files
Knowledge Base class filesTable 8 lists the BAROC files contained in the Knowledge Base classes directory. These BAROC files contain the event and service management class definitions.
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 Default Knowledge Base class files (part 1 of 2)
File name Description
apache.baroc Apache log file adapter class definitions
bem_match_table.baroc data class for defining match tables
For further information, see “BEM_MATCH_TABLE data class” on page 74.
bii4p.baroc BMC Impact Integration for PATROL 7 class definitions
ea_event.baroc BMC Impact Integration for SmartDBA class definitions
eventlog.baroc event log class definitions
im_policies.baroc the data classes used internally for event management in the event processor of a cell. These data classes are related to policies.
ips.baroc 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.
mc_deprecated_filter.baroc FILTER_POLICY class definition
mc_deprecated_kb_data.baroc deprecated data classes provided in the default KB and supported in the service model in prior releases
mc_deprecated_notification.baroc deprecated notification policy classes for e-mail and paging
mc_deprecated_propagation.baroc deprecated event propagation classes
mc_evtdata_internal.baroc 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 BMC Knowledge Base Development Reference Guide
Knowledge Base class files
mc_sm_cost.baroc MC_SM_COST class definition
mc_sm_custom.baroc COMPONENT_CREATION class definitions
Note: By the default, the mc_sm_custom.baroc file is not loaded into the Knowledge Base.
mc_sm_event_mapping.baroc SLOT_FORMULAS class definitions
mc_sm_maintenance.baroc SM_MAINTENANCE class definitions
mc_sm_notify.baroc client notification registry classes
mc_sm_object.baroc hierarchy with BMC_Base_Element and BMC_Impact subclasses
This hierarchy reflects the CMDB CDM class hierarchy.
mc_sm_propagation.baroc MC_SM_PROPAGATION_POLICY class definitions
mc_sm_root.baroc defines the service management internal classes
mc_sm_slm.baroc for the integration to the Remedy Service Level Management product
mc_tec_severity.baroc enumeration definitions for Tivoli Enterprise Console compatibility
Note: By default, the mc_tec_severity.baroc file is not loaded into the Knowledge Base.
mccs.baroc defines the events that are generated internally by the Impact Administration Server
mcxa.baroc classes that define mposter and mc-client, the adapter system, and the BMC Impact Event Adapters
mcxp.baroc 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.
ppm_classes.baroc definitions for BMC ProactiveNet event classes—PPM_EV, ALARM, and ABNORMALITY
patrol_em.baroc BMC II for PATROL EM integration PEM_EV event class definition
patrol_portal.baroc BMC Performance Manager integration event class definitions
state_change.baroc 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.
Table 8 Default Knowledge Base class files (part 2 of 2)
File name Description
Chapter 3 Event and data classes 61
Event class hierarchy
Event class hierarchyFigure 11 presents the hierarchical relationship between CORE_EVENT and its subclasses. Only high-level classes and sub-classes are listed.
Figure 11 CORE_EVENT class hierarchyCORE_EVENT
EVENT
MC_UPDATE_EVENT
MC_SMC_ROOT
MC_MCCS
MC_CLIENT_BASE
MC_ADAPTER_BASE
PATROL_EV
MC_CELL_CONTROL
MC_CELL_START
MC_CELL_STOP
MC_CELL_TICK
MC_CELL_STATBLD_START
MC_CELL_DB_CLEANUP
MC_CELL_CONNECT
MC_CELL_CLIENT
MC_CELL_DESTINATION_UNREACHABLE
MC_CELL_EVENT
PEM_EV
MC_CELL_STATBLD_STOP
MC_CELL_HEARTBEAT_EVT
MC_CELL_RESOURCES
MC_CELL_ACTION_RESULT
MC_CELL_PUBLISH_RESULT
PPM_EV
62 BMC Knowledge Base Development Reference Guide
CORE_EVENT base event class
CORE_EVENT base event classCORE_EVENT is the base class for all cell event classes. Its class definition is internal and is not visible in the Knowledge Base. This class cannot be changed and is documented in the mc_root_internal.baroc file.
All cell components populate these slots as specified. Internal cell-generated events are also populated as specified.
Table 9 CORE_EVENT base class slots (part 1 of 7)
Slot Type Description
adapter_host STRING name of the host where the adapter that sent the event is running
administrator STRING identification of the user that last modified the event, as user@host or package:rulename
date STRING if empty, when entering the cell, it is set as textual format of data_reception, as defined with the parameter DateFormat
date_reception INTEGERrepresenation = date
timestamp as set by the source of the event
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.
duration INTEGER, parse = no
elapsed time, in seconds from event creation to the time the event was closed
event_handle INTEGERparse = no
event identifier in the local cell
mc_abstracted LIST_OF INTEGERparse = no
system reserved
mc_abstraction LIST_OF INTEGERparse = no
system reserved
mc_account STRING identifies the account associated with the event.
mc_acl LIST OF STRINGparse = no
controls write and execute access to events when read access is provided by the collector
mc_action_count INTEGERparse = no
number of actions performed on the event
mc_arrival_time INTEGERrepresentation = date
timestamp when the event arrived at the network at either an adapter or a cell
Its value is never zero (0).
mc_associations LIST_OF STRINGparse = no
system reserved
Chapter 3 Event and data classes 63
CORE_EVENT base event class
mc_bad_slot_names LIST_OF STRING list with names of slots that could not be set when the event was reserved
This can be a non-existing slot or a slot with an invalid value.
mc_bad_slot_values LIST_OF STRING corresponding values of the bad slots
mc_cause INTEGERparse = no
system reserved
mc_client_address STRINGparse = no
network address of the host where the adapter that sent the event is running
mc_collectors LIST_OF STRING system reserved
mc_date_modification INTEGERrepresentation=date
timestamp of last modification of certain slots
The slots are those mentioned in mcell.modify.
mc_effects LIST_OF INTEGERparse = no
system reserved
mc_event_category MC_EVENT_CATEGORY high-level normalized category of the object the event represents based on an appropriate Information Technology Infrastructure Library (ITIL) core process
mc_event_model_version STRING denotes the version (<major_version>.<minor_version>.<service_version>) of the event model that instantiates the event. The event model version is required for compatibility purposes. For example, 1.0.00
mc_event_relations LIST_OF STRINGparse=no, hidden=yes
a list of tuples
■ The first element of the tuple contains the relation type.
■ 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.
mc_history LIST_OF STRING system reserved
mc_host STRING fully-qualified name of the host on which the problem occurred
Table 9 CORE_EVENT base class slots (part 2 of 7)
Slot Type Description
64 BMC Knowledge Base Development Reference Guide
CORE_EVENT base event class
mc_host_address STRING network address corresponding to the mc_host slot
Note: This slot can contain some other type of information in situations in which a host value is not meaningful.
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 INTEGERrepresentation=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.
mc_local_reception_time INTEGERrepresentation=date
timestamp when the event arrived in the local component
It is never zero (0).
mc_location STRING location at which the managed object resides
mc_long_msg STRING expands the information in msg
mc_modhist LIST_OF STRING system reserved
mc_notes LIST_OF STRING list of free text annotations added to the event
The contents of this slot is implementation-dependent. Rules or users should not rely on a particular value in this slot.
mc_notification_history LIST_OF STRING indicates the status of the event with respect to the notification system over time
mc_object STRING 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.
Table 9 CORE_EVENT base class slots (part 3 of 7)
Slot Type Description
Chapter 3 Event and data classes 65
CORE_EVENT base event class
mc_object_class STRING identifies the class of an object
If the object class cannot be derived from the original event, it should be filled in during enrichment.
mc_object_owner STRING identifies the owner of the source component
mc_object_uri STRING address used to cross-launch directly to the component
mc_operations LIST_OF STRING slot containing a list of operation history entries
mc_origin STRING 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 de-escalated
mc_original_severity SEVERITY records the original severity of the event to determine if the event’s severity has been modified
mc_owner STRING current user assigned to the event
Table 9 CORE_EVENT base class slots (part 4 of 7)
Slot Type Description
66 BMC Knowledge Base Development Reference Guide
CORE_EVENT base event class
mc_parameter STRING name of the metric or property that went into alarm or that triggered the event
mc_parameter_threshold STRING threshold value that was crossed to cause the generation of the event
mc_parameter_unit STRING unit description of the metric
mc_parameter_value STRING actual value of the parameter
mc_priority MC_PRIORITYdefault = PRIORITY_5
current priority of the event
Possible values include■ PRIORITY_5 (lowest priority)■ PRIORITY_4■ PRIORITY_3■ PRIORITY_2■ PRIORITY_1 (highest priority)
mc_propagations LIST_OF STRINGparse = no
system reserved
mc_relation_source STRING the mc_ueid of the source event to which this event is related
This slot links a related event to its source event.
mc_service STRING service related to the event
mc_smc_ida STRING event is attached to the SIM component with the specified identifier
mc_smc_impacta INTEGERdefault = 0
set to 1 if event has an impact on a SIM component
mc_smc_prioritya REALparse = no
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:
■ 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
Table 9 CORE_EVENT base class slots (part 5 of 7)
Slot Type Description
Chapter 3 Event and data classes 67
CORE_EVENT base event class
mc_timeout INTEGER event timeout in seconds
mc_tool STRING For BMC Event Management events, mc_tool represents any event that is within any value that can further distinguish where the event is coming from within a mc_tool_class value.
For example, for the NT Event Log Adapter, mc_tool could be the name of the log to which the incident was logged. If the mc_tool_class is a management tool (such as PATROL or ITO), then the mc_tool should be a string that enables an action on the event to initiate a communication in context with the mc_tool.
For BMC ProactiveNet events, mc_tool contains the fully-qualified DNS name of the NGP Server.
mc_tool_address STRING the network address of the Reporter
mc_tool_class STRING 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.
mc_tool_key STRING unique key used by the sending tool to enumerate the event
mc_tool_rule STRING name of the adapter or integration mapping rule that generated the event
mc_tool_sev STRING severity as given by mc_tool
mc_tool_suggestion STRING the Reporter’s suggested solution to the problem posed by the event. This is similar to expert advice information that other applications provide.
mc_tool_time INTEGER 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.
mc_tool_uri STRING the address used to cross-launch directly to the Reporter
Table 9 CORE_EVENT base class slots (part 6 of 7)
Slot Type Description
68 BMC Knowledge Base Development Reference Guide
EVENT class
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?)
MC_CELL_CONTROL event class
The MC_CELL_CONTROL class is a subclass of the CORE_EVENT base class. MC_CELL_CONTROL is the base class for the internal cell events.
mc_ueid STRING universal event identifier
When an event is propagated, the receiving cell gets a new local identifier, event_handle, but the event keeps the old universal identifier mc_ueid.
msg STRING text description of the event
repeat_count INTEGER number of copies received from this event
severity SEVERITYdefault = WARNING
severity value of the event
status STATUSdefault = OPEN
status value of the event
a These slots are not in use for the current version of BMC ProactiveNet.
NOTE No user or application should create internal cell events. These events only should be generated by the cell.
Table 10 MC_CELL_CONTROL slot definitions
Slot Type Description
cell_name STRING name of the cell
cell_location STRING location information for the cell
Table 9 CORE_EVENT base class slots (part 7 of 7)
Slot Type Description
Chapter 3 Event and data classes 69
PPM_EV event class
PPM_EV event class
The PPM_EV class is a subclass of the EVENT class. The PPM_EV class is the parent class for BMC ProactiveNet events.
ABNORMALITY event class
The ABNORMALITY event class is a subclass of the PPM_EV event class. The ABNORMALITY class stores the data for abnormalities that have been triggered.
Table 11 PPM_EV slot definitions
Slot Type Description
pn_baseline_type BASELINE baseline used to trigger an abnormality.
Possible values are:■ NO■ HOURLY■ DAILY■ WEEKLY■ MONTHLY■ ALL■ HOURLY_DAILY
pn_groups LIST OF STRING
list of the names of the groups to which the mc_object slot of the event belongs
pn_thresh_duration INTEGER duration (in minutes) that data points have to meet the trigger condition before the event is created
pn_vm_host STRING name of the VM host machine. Value is empty if no VM host is being used.
severity SEVERITY severity value of the event
Table 12 ABNORMALITY slot definitions
Slot Type Description
pn_avg_value STRING average value of all the data points that contribute to the creation of the abnormality
pn_baseline_daily_high STRING daily baseline high at the time the abnormality is triggered
pn_baseline_daily_low STRING daily baseline low at the time the abnormality is triggered
pn_baseline_hourly_high STRING hourly baseline high at the time the abnormality is triggered
pn_baseline_hourly_low STRING hourly baseline low at the time the abnormality is triggered
pn_baseline_weekly_high STRING weekly baseline high at the time the abnormality is triggered
pn_baseline_weekly_low STRING weekly baseline low at the time the abnormality is triggered
pn_event_score REAL abnormality score as returned by the Root-Cause Analysis engine
70 BMC Knowledge Base Development Reference Guide
PPM_EV event class
ALARM event class
The ALARM event class is a subclass of the PPM_EV event class. The ALARM class represents BMC ProactiveNet alarm objects, which are any objects that have a severity of [PREDICTIVE] MINOR, MAJOR, or CRITICAL.
Table 13 ALARM slot definitions
Slot Type Description
pn_alarm_id INTEGER The internal ID for an alarm
pn_is_predicted BOOLEAN indicates whether or not the alarm has a Predictive severity:
■ 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.
pn_is_suppressing BOOLEAN indicates whether or not this alarm is suppressing other alarms
■ 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:■ blank (the value is empty)■ MINOR■ MAJOR■ CRITICAL
Chapter 3 Event and data classes 71
Data class hierarchy
Data class hierarchyThe classes listed in Figure 12 presents the hierarchical relationship between CORE_DATA and its subclasses. Only high-level classes and subclasses are listed.
Figure 12 CORE_DATA class hierarchy
CORE_DATA
DATA
MC_CELL_DIR_COMPONENT
MC_CELL_REGULATE
MC_CELL_HEARTBEAT
MC_CELL_METRIC
MC_ACL
MC_CELL_DATA
TIME_ZONE
TIME_FRAME
SCHEDULE
MC_CALENDARING
BMC_BaseElement
BMC_Impact
BMC_SIM_DATA
MC_SIM_INTERNAL
MC_SM_DATA
POLICY
SELECTOR
MC_SM_CUSTOM
MC_SM_ALIAS
IM_POLICY
PATROL_IDX
SIM_NOTIFICATION_REGISTRY
MC_EVENT_RELATION
BEM_MATCH_TABLE
72 BMC Knowledge Base Development Reference Guide
CORE_DATA base class
CORE_DATA base classCORE_DATA is the base data class for all cell data classes. Table 14 lists the slot definitions, together with an explanation for each slot.
MC_SM_DATA data class
The MC_SM_DATA class is the root class for all service model related data classes. By default, the MC_SM_DATA subclass has no slots initially defined other the inherited ones; however, slots can be added.
For complete information about service model data classes, see the BMC Impact Solutions: Service Model Administrator’s Guide.
MC_CALENDARING data class
The MC_CALENDARING class is the root class for local timeframes, which are used in event policies. Local timeframes comprise three data subclasses of the MC_CALENDARING data class:
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 CORE_DATA slot definitions
Slot Type Description
data_handle INTEGERparse = no, read_only = yes
data identifier for a local cell
mc_udid STRINGread_only = yes
universal data ID
mc_creation_time INTEGERparse = no, read_only = yes, representation = date
creation time
mc_modification_time INTEGERparse = no, read_only -= yes, representation = date
modification time
Chapter 3 Event and data classes 73
BEM_MATCH_TABLE data class
■ SCHEDULE—the association between a timeframe and an action (a schedule allows you to specify an action that begins at the beginning or end of an active timeframe)
■ TIME_FRAME—the periods of time that the event policy is active
■ TIME_ZONE—the 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.
BEM_MATCH_TABLE data class
BEM_MATCH_TABLE is the superclass for defining a match table, which you use in the find_match() function. Use a match table to evaluate a set of patterns against a set of input values (such as event slot values) and then use associated expressions to build output values.
Table 15 BEM_MATCH_TABLE class attribute (slot) definitions
Slot Type Description
name STRING a short description or name of the instance (optional)
tag STRING used to group instances in the match table into subsets according to the tag
input_match LIST_OF STRING list of patterns
For more information, see “BEM_MATCH_TABLE pattern matching” on page 75.
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 BMC Knowledge Base Development Reference Guide
BEM_MATCH_TABLE data class
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.
BEM_MATCH_TABLE pattern matching
Patterns must be one of the following:
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.
BEM_MATCH_TABLE output_expressions references
The output_expressions attribute can refer to objects passed to the fourth argument of the find_match primitive with variables such as $1, $2, and so on.
They can also reference the input string (third argument of find_match) with $V1, $V2, and so on.
Syntax Matches
'*' any string
‘<pattern>’ exact pattern
‘<pattern>*” strings with prefix pattern
‘*<pattern>’ strings with suffix pattern
‘*<pattern>*’ strings containing pattern
Chapter 3 Event and data classes 75
BEM_MATCH_TABLE data class
BEM_MATCH_TABLE output_expressions example
Each string in the output_expressions slot represents an MRL expression, such as the following example:
In the above example, the string ‘tolowercase($1.msg)’represents the following MRL expression:
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:
The following expression is not valid:
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:
For information about the find_match primitive, see page 174.
output_expressions=['tolowercase($1.msg)']
tolowercase($1)
'quoted.string'
non-quoted.string
output_expressions=['"quoted.string"']
76 BMC Knowledge Base Development Reference Guide
POLICY data class
POLICY data class
The POLICY class is a subclass of the CORE_DATA base class.
For more information about policies, see “Event policies” on page 312.
SELECTOR data class
The SELECTOR class is a subclass of the base CORE_DATA class. Table 17 lists the slot definitions for the SELECTOR class and provides an explanation for each slot.
For more information about selectors, see “Event selectors” on page 313.
Table 16 POLICY slot definitions
Slot Type Description
name STRING unique name for the policy
description STRING text description of the policy
enabled INTEGER,default = 1
indicates if the policy has been enabled
If set to 0, the policy is ignored, if the enabled slot is set to 1 the policy impacts the processing of events.
Table 17 SELECTOR slot definitions
Slot Definition Description
based_on STRING event class on which the event policy is based and to which the selector should apply
name STRING unique name for the event selector; also the mechanism that provides a way to access the selector
description STRING text description of the event selector
ecfs LIST_OF ECF a list of ECFs or event selection criteria that specifies a class and a list of constraints that must be met to cause the selection of an event
ecfs_descr LIST_OF STRING text description of the ECFs
Chapter 3 Event and data classes 77
Cell information class
Cell information classEach cell has a predefined MC_CELL_INFO record that is populated with general information about the cell.
Deprecated slots and their replacementsThe following deprecated slots for the cell are available in the mc_root_redef.baroc file which, by default, is not loaded into the Knowledge Base. To continue to use the deprecated slots you must either enable the mc_root_redef.baroc file in the .load file or define the required slots.
Table 18 MC_CELL_INFO slot definitions
Slot Type Description
cell_name STRING name of the cell
cell_description STRING description of the cell, as specified in the CellDescription parameter
cell_release STRING indicates the release version of the cell program
cell_build STRING build number of the cell program
cell_date STRING build date of the cell program (in textual form)
service_address STRING IP address of the cell service
service_port INTEGER port number of the cell service
alternate_address STRING IP address of the alternate cell server of a high availability cell
alternate_port INTEGER port number of the alternate cell server of a high availability cell
home_dir STRING cell installation home directory
start_date INTEGER timestamp of when the cell was last started
platform STRING platform on which the cell is running
ha_failover MC_YESNO indicates that the cell is a high availability cell
ha_duplicate MC_YESNO indicates that the cell is secondary server of a high availability cell
ha_standby MC_YESNO indicates that cell is in standby mode
■ acl ■ acl_name
■ consumer_logical_id ■ cost
■ credibility ■ ext_id
■ generic_slot1 ■ generic_slot2
■ generic_slot3 ■ generic_slot4
■ mc_host ■ location
78 BMC Knowledge Base Development Reference Guide
Deprecated slots and their replacements
Table 19 lists the slots that can be substituted for a deprecated slot.
■ logical_id ■ mc_it_mgmt_process
■ msg_catalog ■ msg_index
■ num_actions ■ origin
■ provider_logical_id ■ server_handle
■ site ■ source
■ state_change_events ■ state_change_ueid
■ sub_origin ■ sub_source
Table 19 Deprecated slot substitution (part 1 of 2)
Deprecated slot Slot substitution
description Description
hostname mc_host
home_cell HomeCell
icon Icon
name Name
origin mc_host_address
owner_name OwnerName
propagation_model PropagationModel
state State
status_model StatusModel
tool_tip_slots ToolTipSlots
sub_origin mc_object
site mc_location
scope component_scope
source 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:
■ mc_tool_class■ mc_tool■ mc_origin_class■ mc_origin
sub_source
Chapter 3 Event and data classes 79
Deprecated slots and their replacements
server_handle There are no slots that can substitute information for these deprecated slots. acl
credibility
msg_catalog
msg_index
num_actions
mc_it_mgmt_process
Table 19 Deprecated slot substitution (part 2 of 2)
Deprecated slot Slot substitution
80 BMC Knowledge Base Development Reference Guide
C h a p t e r 4
4 Master Rule Language (MRL) referenceThis chapter presents the following topics:
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Integer data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Enumeration data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Condition operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Expression operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
MRL functions and primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Primitives and functions overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Action-related primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Value type conversion primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Enumeration operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135String manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Time stamp functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162List operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Match table lookup primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Object slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Specific slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Object relation functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Operation environment inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Service model inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200License key functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Time frame operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Object creation and deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Specific rule-based functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Chapter 4 Master Rule Language (MRL) reference 81
Data types
Data typesTable 20 lists the types of data that can be stored by the cell.
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 Permitted integer combinations in rules
Enumeration data
An enumeration associates constant values with names. The general format is
Table 20 Data types
Data type Description Default value
INTEGER a whole number that does not have a fractional part 0
REAL numeric data in form of a decimal fraction 0
POINTER a 32-bit value 0
STRING sequence of characters, words, or phrases ‘ ’ (empty string)
ENUM list of values used as the range of a particular attribute type
The first ordinal value that corresponds to the lowest numeric value.
pointer = pointer + integerpointer = integer + pointerpointer = pointer - integer integer = pointer - pointer pointer = max(pointer, pointer) pointer = min(pointer, pointer)
ENUMERATION enum_nameinteger_value string_valueinteger_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 BMC Knowledge Base Development Reference Guide
Operators
OperatorsThere are three kinds of operators:
■ 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:
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:
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.
STRING an expression evaluating to a value of type STRING
INTEGER an expression evaluating to a value of type INTEGER
REAL an expression evaluating to a value of type REAL
ENUM an expression evaluating to a value of an enumeration type
ANY any simple (non-list) value
LIST_OF T a list of elements of type T
Table 21 Logical combination operators
Operator syntax Description
NOT c1 specifies logical negation. The expression evaluates to true if c1 evaluates to false.
c1 AND c2 specifies logical conjunction. The expression evaluates to true if both c1 and c2 evaluate to true.
c1 OR c2 specifies logical disjunction. The expression evaluates to true if either c1 or c2 evaluate to true or both c1 and c2 evaluate to true.
Chapter 4 Master Rule Language (MRL) reference 83
Condition operators
Combination operator example
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:
■ 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:
which refers to the named slot of the current event.
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.
( $POL.active_timeframes == [] OR tf_active($POL.active_timeframes) ) AND NOT tf_active($POL.except_timeframes)
NOTE A short-cut slot reference is equivalent to $THIS.SlotName. However, the use of this short-cut syntax is discouraged because it is less readable.
84 BMC Knowledge Base Development Reference Guide
Condition operators to test ordering conditions
Condition operator example 1
Condition operator example 2
Condition operators to test ordering conditions
==/2 - equals/2 — compare two values for equality
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.
when $E.status != OPEN
timer_info: == EventTimeout
$EXPR1 == $EXPR2$EXPR1 equals $EXPR2
Table 22 ==/2 arguments
Argument Type Description
$EXPR1 ■ ANY■ LIST_OF ANY
expression to the left of the operator
$EXPR2 ■ ANY■ LIST_OF ANY
expression to the right of the operator
Chapter 4 Master Rule Language (MRL) reference 85
Condition operators to test ordering conditions
==/2 - equals/2 example
!=/2 - not_equals/2 — compare two values for inequality
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 - not_equals/2 example
</2 - smaller_than/2 - less_than/2 — determine if one value is less than another value
Use </2 to determine if the value of expression $EXPR1 is less than the value of $EXPR2.
$E.status == OPEN
$EXPR1 != $EXPR2$EXPR1 not_equals $EXPR2
Table 23 !=/2 arguments
Argument Type Description
$EXPR1 ■ ANY■ LIST_OF ANY
expression to the left of the operator
$EXPR2 ■ ANY■ LIST_OF ANY
expression to the right of the operator
$E.status != CLOSED
$EXPR1 < $EXPR2$EXPR1 smaller_than $EXPR2$EXPR1 less_than $EXPR2
Table 24 </2 arguments
Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 ANY expression to the right of the operator
86 BMC Knowledge Base Development Reference Guide
Condition operators to test ordering conditions
</2 - smaller_than/2 - less_than/2 example
<=/2 - smaller_or_equals/2 - less_or_equals/2 — determine if one value is less than or equal to another value
Use <=/2 to determine if the value of expression $EXPR1 is less than or equal to the value of $EXPR2.
<=/2 - smaller_or_equals/2 - less_or_equals/2 example
>/2 - greater_than/2 — determine if one value is greater than another value
Use >/2 to determine if the value of expression $EXPR1 is greater than the value of $EXPR2.
MINOR < $E.severity
$EXPR1 <= $EXPR2$EXPR1 smaller_or_equals $EXPR2$EXPR1 less_or_equals $EXPR2
Table 25 <=/2 arguments
Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 ANY expression to the right of the operator
MAJOR <= $E.severity
$EXPR1 > $EXPR2$EXPR1 greater_than $EXPR2
Table 26 >/2 arguments
Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 ANY expression to the right of the operator
Chapter 4 Master Rule Language (MRL) reference 87
Condition operators to test range conditions
>/2 - greater_than/2 example
>=/2 - greater_or_equals/2 — determine if one value is greater than or equal to another value
Use >=/2 to determine if the value of expression $EXPR1 is greater than or equal to the value of $EXPR2.
>=/2 - greater_or_equals/2 example
Condition operators to test range conditions
between/2 — determine if one value is between two other values
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.
$E.severity > MINOR
$EXPR1 >= $EXPR2$EXPR1 greater_or_equals $EXPR2
Table 27 >=/2 arguments
Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 ANY expression to the right of the operator
$E.severity >= MAJOR
$EXPR1 between $EXPR2
Table 28 between/2 arguments
Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 LIST_OF ANY expression to the right of the operator
88 BMC Knowledge Base Development Reference Guide
Condition operators to test range conditions
If $EXPR2 evaluates to [$VAL1,$VAL2], then the condition $EXPR1 between $EXPR2 is equivalent to: $VAL1 <= $EXPR1 AND $EXPR1 <= $VAL2.
between/2 example
within/2 — determine if one value is present within a set of values
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
outside/2 — determine if one value is not included in a set of values
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.
$E.duration between [100,199]
$EXPR1 within $EXPR2
Table 29 within/2 arguments
Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 LIST_OF ANY expression to the right of the operator
$E.mc_host within [host1,host2,host3]
$EXPR1 outside $EXPR2
Table 30 outside/2 arguments
Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 LIST_OF ANY expression to the right of the operator
Chapter 4 Master Rule Language (MRL) reference 89
Condition operators to test match conditions
outside/2 example
Condition operators to test match conditions
contains/2 — determine if one value contains another value
Use contains/2 to determine if the value of expression $EXPR1 contains the value of $EXPR2.
There are three possible uses of this operator:
■ 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.
$E.mc_host outside [host1,host2,host3]
$EXPR1 contains $EXPR2
Table 31 contains/2 arguments
Argument Type Description
$EXPR1 ■ STRING■ LIST_OF ANY
expression to the left of the operator
$EXPR2 ■ STRING■ LIST_OF STRING■ ANY
expression to the right of the operator
90 BMC Knowledge Base Development Reference Guide
Condition operators to test match conditions
contains/2 example
contained_in/2 — determine if one value is contained in another value
Use contained_in/2 to determine if the value of expression $EXPR1 is a substring of the value of $EXPR2.
contained_in/2 example
contains_one_of/2 — determine if one value contains one of a set of values
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.
$E.msg contains ’Disk full’$E.msg contains [’Not enough’,’disk’,’space’]$E.mc_bad_slotnames contains myslot
$EXPR1 contained_in $EXPR2
Table 32 contained_in/2 arguments
Argument Type Description
$EXPR1 STRING expression to the left of the operator
$EXPR2 STRING expression to the right of the operator
’Disk full’ contained_in $E.msg
$EXPR1 contains_one_of $EXPR2
Table 33 contains_one_of/2 arguments
Argument Type Description
$EXPR1 STRING expression to the left of the operator
$EXPR2 LIST_OF STRING expression to the right of the operator
Chapter 4 Master Rule Language (MRL) reference 91
Condition operators to test match conditions
contains_one_of/2 example
has_prefix/2 — determine if one string has another string as prefix
Use has_prefix/2 to determine if the value of expression $EXPR1 has the value of $EXPR2 as a prefix.
has_prefix/2 example
has_suffix/2 — determine if one string has another string as suffix
Use has_suffix/2 to determine if the value of expression $EXPR1 has the value of $EXPR2 as a suffix.
$E.msg contains_one_of [’Disk’,’CPU’,’Memory’]
$EXPR1 has_prefix $EXPR2
Table 34 has_prefix/2 arguments
Argument Type Description
$EXPR1 STRING expression to the left of the operator
$EXPR2 STRING expression to the right of the operator
$E.mc_host has_prefix ’svc_’
$EXPR1 has_suffix $EXPR2
Table 35 has_suffix/2 arguments
Argument Type Description
$EXPR1 STRING expression to the left of the operator
$EXPR2 STRING expression to the right of the operator
92 BMC Knowledge Base Development Reference Guide
Condition operators to test match conditions
has_suffix/2 example
matches/2 — to determine if the pattern of one string matches the pattern of another string
Use matches/2 to determine if the value of expression $EXPR1 matches the pattern $EXPR2.
There are two possible uses of this operator:
■ $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:
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.
$E.mc_host has_suffix ’_clt’
$EXPR1 matches $EXPR2
Table 36 matches/2 arguments
Argument Type Description
$EXPR1 ■ STRING■ LIST_OF_STRING
expression to the left of the operator
$EXPR2 ■ STRING expression to the right of the operator
\\ backslash
\s space (single space)
\n new line
\r carriage return
\t tab
\0ddd character code in octal
Chapter 4 Master Rule Language (MRL) reference 93
Condition operators to test conditions on IP addresses
Possible substitutes are:
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:
■ 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
Condition operators to test conditions on IP addresses
ip_smaller_or_equals/2 — determine if one IP address is less than or equal to another one
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.
%% literal match of %
%d decimal integer number
%f floating point real number
%c single character
%s string value
$E.msg matches ’%s failure’
NOTE IP addresses are stored as strings in dotted decimal notation.
$EXPR1 ip_smaller_or_equals $EXPR2
Table 37 ip_smaller_or_equals/2 arguments
Argument Type Description
$EXPR1 STRING expression to the left of the operator
$EXPR2 STRING expression to the right of the operator
94 BMC Knowledge Base Development Reference Guide
Condition operators to test conditions on IP addresses
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
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.
ip_greater_or_equals/2 — determine if one IP address is greater than or equal to another one
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
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.
$E.mc_host_address ip_smaller_or_equals ’10.1.1.100’
$EXPR1 ip_greater_or_equals $EXPR2
Table 38 ip_greater_or_equals/2 arguments
Argument Type Description
$EXPR1 STRING expression to the left of the operator
$EXPR2 STRING expression to the right of the operator
$E.mc_host_address ip_greater_or_equals ’10.1.1.100’
Chapter 4 Master Rule Language (MRL) reference 95
Condition operators to test conditions on IP addresses
ip_matches/2 — determine if an IP address matches an IP address pattern
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:
■ * — 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
Any IP address in the range 10.1.1.0 to 10.1.1.255 for mc_host_address will satisfy this condition.
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.
$EXPR1 ip_matches $EXPR2
Table 39 ip_matches/2 arguments
Argument Type Description
$EXPR1 STRING expression to the left of the operator
$EXPR2 STRING expression to the right of the operator
$E.mc_host_address ip_matches ’10.1.1.*’
$E.mc_host_address ip_matches ’10.>200.<100.*’
96 BMC Knowledge Base Development Reference Guide
Condition operators to test class hierarchy conditions
ip_matched_by/2 — determine if an IP address matches an IP address pattern
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
Condition operators to test class hierarchy conditions
superclass_of/2 — determine if one class is a superclass of another class
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.
$EXPR1 ip_matched_by $EXPR2
Table 40 ip_matched_by/2 arguments
Argument Type Description
$EXPR1 STRING expression to the left of the operator
$EXPR2 STRING expression to the right of the operator
’10.1.1.*’ ip_matched_by $E.mc_host_address
$EXPR1 superclass_of $EXPR2
Table 41 superclass_of/2 arguments
Argument Type Description
$EXPR1 STRING expression to the left of the operator
$EXPR2 STRING expression to the right of the operator
Chapter 4 Master Rule Language (MRL) reference 97
Expression operators
superclass_of/2 example
subclass_of/2 — determine if one class is a subclass of another class
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
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.
Example of expression evaluation order
PATROL_EV superclass_of $E.CLASS
$EXPR1 subclass_of $EXPR2
Table 42 subclass_of/2 arguments
Argument Type Description
$EXPR1 STRING expression to the left of the operator
$EXPR2 STRING expression to the right of the operator
$E.CLASS subclass_of PATROL_EV
$E1 + $E2 * $E3
98 BMC Knowledge Base Development Reference Guide
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.
Exponentiation and special division operators
Exponentiation and special division operators take two numeric arguments and produce a numeric result.
Multiplicative operators
Multiplicative operators take two numeric arguments and produce a numeric result.
Additive operators
Additive operators take two numeric arguments and produce a numeric result.
Single numeral operators
These operators take a single numeric argument and produce a numeric result.
e1 ^ e2 Value of e1 to the power e2
e1 ** e2 Value of e1 to the power e2
e1 rem e2 Remainder of division of e1 by e2
e1 mod e2 Modulo of division of e1 by e2
e1 * e2 Value of e1 multiplied by e2
e1 / e2 Value of e1 divided by e2
e1 // e2 Integer division of e1 by e2
e1 >> e2 Bitwise right shift of e1 by e2 positions
e1 << e2 Bitwise left shift of e1 by e2 positions
e1 + e2 The sum of e1 and e2
e1 - e2 Value of e1 subtracted by e2
e1 /\ e2 Bitwise conjunction (AND) of e1 and e2
e1 \/ e2 Bitwise inclusive disjunction (OR) of e1 and e2
e1 xor e2 Bitwise exclusive disjunction (XOR) of e1 and e2
+ e1 The value e1
- e1 The numeric negation of the value e1
\ e1 The logical or bitwise negation (complement) of the value e1
Chapter 4 Master Rule Language (MRL) reference 99
MRL functions and primitives
Concatenation operator
The following operator takes two string arguments and produces a string result.
Expression operator example
MRL functions and primitivesThe primitives and functions in this section are grouped by usage. Table 43 allows you to look up the location of the function and primitive descriptions alphabetically.
e1 || e2 Concatenation of string e1 with string e2
$E.msg = ’Host ’ || $E.mc_host || ’ went down’;
Table 43 Alphabetical list of primitives and functions (part 1 of 7)
Primitive/function name Description Page
abs/2 determine the absolute value of a numeric value 128
acos/2 return the arc cosine of a specified number 133
action_requestor/1 retrieve the identification of the requestor of an action 107
action_requestor/2 retrieve the user ID and password of the console user triggering the action
108
action_requestor/3 retrieve the user ID and password of the console user, as well as the type of rule triggering the action
109
action_return/2 terminate an internal action and return a value 110
add_to_list/2 add an element at the beginning of a list slot 173
apply_match_entry/4 obtain output values from a match table entry 178
admin_execute/5 perform an action through remote execution on Impact Administration Server
110
admin_execute/7 perform an action through remote execution on IAS, providing Impact Administration Server credentials
111
asin/2 return the arc sine of a specified number 132
atan/2 return the arc tangent of a specified number 133
atan2/3 return the arc tangent of the ratio of two numbers 134
cellcontrol/1 perform a cell control command 194
cellinfo/2 retrieve cell-specific information 193
char/2 produce a string containing a single character with a specified numeric internal representation
125
class_path/2 obtain the class hierarchy of a class 181
100 BMC Knowledge Base Development Reference Guide
MRL functions and primitives
code/2 retrieve the internal numeric representation of a character 125
concat/2 concatenate a list of strings 143
confirm_external/2 run an external program and wait for its termination to continue to process the current event
115
cos/2 return the cosine of an angle 131
decr/1 decrement an integer or enumeration slot by 1 139
decr/2 decrement an integer or enumeration slot by a specified value
140
decr/2 and prev/2 return an integer or enumeration slot value decremented by 1
139
decr/3 retrieve the value of an integer or enumeration slot decremented by a specified value
141
decr/3 decrement an integer or enumeration slot by a specified value within a given limit
141
decr/4 return an integer or enumeration slot value decremented by a specified value within a given limit
142
drop_new/0 drop a new event object 220
execute/4 run a program as an external process 114
exp/2 raise e (2.718281828...) to a specified power 129
find_match/5 find an entry in a match table and retrieve calculated values from it
174
find_match_entry/4 find an entry in a match table 176
gcd/3 return the greatest common divisor of two numbers 134
generate_event/2 generate a new event 218
get_env/2 retrieve the value of an environment variable 196
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
117
get_list_slotvalues/3 retrieve a list of slots from one or more objects 179
has_substring/2 verify the occurrence of a substring within a string or list of strings
160
has_substring/3 verify the occurrence of a substring within a string or list of strings using a comparison modifier
161
incr/1 increment an integer or enumeration slot by 1 135
incr/2 increment an integer or enumeration slot by a specified value
136
incr/2 and next/2 return an integer or enumeration slot value incremented by 1 136
incr/3 return an integer or enumeration slot value incremented by a specified value
137
incr/3 increment an integer or enumeration slot by a specified value within a specified limit
138
Table 43 Alphabetical list of primitives and functions (part 2 of 7)
Primitive/function name Description Page
Chapter 4 Master Rule Language (MRL) reference 101
MRL functions and primitives
incr/4 retrieve the value of an integer or enumeration slot incremented by a given value within a specified limit
138
int/2 truncate a numeric value to an integer value 123
int_to_hex/2 convert an integer value to a string containing its hexadecimal notation
119
int_to_hex/3 convert an integer value to a string containing its hexadecimal notation in a specified field width
119
inttostring/2 convert an integer value to a string value 118
kbversion/1 retrieve global Knowledge Base module version information 196
kbversion/2 retrieve Knowledge Base module version information 195
key_verify/2 validate and retrieve fields from a license key 203
key_verify/3 validate and retrieve fields from a license key 203
key_version/2 retrieve the version from a license key 202
listappend/3 concatenate two lists 169
listdelete/3 remove all occurrences of an element from a list 168
listdisjoint/2 verify that two lists do not have any common elements 169
listgetelt/3 retrieve a list element located at a specified position within a list
167
listintersect/3 determine the common elements of two lists 170
listlen/2 determine the length of a list 167
listmember/2 verify that an element is included in a list 168
listremdup/2 remove duplicate elements from a list 172
listsubtract/3 remove the elements that occur in one list from another list 171
listunion/3 determine the union of two lists 171
listwalk/2 execute instructions against each element in a list 172
log/2 return the natural logarithm of a specified number 130
log10/2 return the decimal logarithm of a specified number 130
mapslots/3 format a series of expressions that refer to objects into a string
159
mapslots/4 format a series of expressions that refer to event and data objects into a string
158
match_regex/3 match a string with a regular expression 154
match_regex/4 match a string with a regular expression and retrieve all fields from it
155
match_regex/5 match a string with a regular expression and retrieve a given number of fields from it
157
max/3 determine the maximum of two values 126
min/3 determine the minimum of two values 127
new_data/3 create a new data object 219
ntadd/2 add a note to an event 182
Table 43 Alphabetical list of primitives and functions (part 3 of 7)
Primitive/function name Description Page
102 BMC Knowledge Base Development Reference Guide
MRL functions and primitives
ntcnt/2 count the notes attached to an event 182
ntget/5 return the time stamp, author, and text of a note attached to an event
183
ntset/3 modify the text of a note attached to an event 183
opadd/3 add an operation to an event 185
opadd/4 add a policy operation to an event 184
opcnt/2 count the operations of an event 185
opget/6 retrieve an operation of an event 186
opget/7 retrieve a policy operation of an event 186
opget_action/3 retrieve the action name of an operation of an event 188
opget_args/3 retrieve the argument list of an operation of an event 189
opget_author/3 retrieve the author of an operation of an event 188
opget_time/3 retrieve the time stamp of an operation of an event 187
opset/4 modify the action and arguments of an operation of an event 190
opset/5 modify the policy name, action, and arguments of an operation of an event
189
perform/3 perform a specified action 113
perform/5 perform a specified action and return a value 113
pointertostring/2 convert a pointer value to a string value 120
pow/3 raise a number to a specified power 129
propagated_to/3 verify that an event has been propagated to a specified destination
199
random/3 return a random integer that falls between two specified numbers
135
real/2 and float/2 convert a numeric value to a real value 124
realtostring/2 convert a real value to a string value 120
relate/1 establish the relation of an event to a source event 191
rem_from_list/2 remove the first occurrence of an element from a list slot 174
remove_data/1 delete a data object 219
reset_default/1 reset a slot to its default value 181
round/2 convert a numeric value to an integer value by rounding the number
124
send_to/2 send an event to another cell or gateway 197
send_to/3 send an event modification to another cell or gateway 197
send_to_ext/4 send an extended event to another cell or gateway 198
set_list_slotvalues/3 assign values to a list of slots for one or more objects 180
set_timer/3 set a timer on an event object that will expire after a specified delay
221
set_timer_at/3 set a timer on an event object that will expire at a specified time
222
Table 43 Alphabetical list of primitives and functions (part 4 of 7)
Primitive/function name Description Page
Chapter 4 Master Rule Language (MRL) reference 103
MRL functions and primitives
set_timer_at/4 set a timer on an event object that will expire at a specified time represented by a text string
223
sign/2 determine whether a numeric value is positive, negative, or zero
127
sin/2 return the sine of an angle 131
smcomps/5 search for certain Service Model components 200
sprintf/3 format a series of values into a string 158
sqrt/2 determine the square root of a numeric value 128
str_to_time_stamp/3 convert a string to a time stamp 166
strextract/4 retrieve a string of a specified length that begins at a specified position within a larger string
147
string/2 convert any non-list value to a string value 121
stringtoint/2 convert a string value to an integer value 121
stringtopointer/2 convert a string value to a pointer value 122
stringtoreal/2 convert a string value to a real value 122
strip/2 strip leading and trailing blank spaces from a string 149
strip/3 remove blank spaces from specified parts of a string 149
strip/4 remove specified characters from specified parts of a string 150
strlen/2 and len/2 determine the length of a string 143
strmatch/3 match a string with a simple pattern and retrieve fields from it
152
strnpart/4 determine the start position of a specified occurrence of a part of a string
152
strpart/3 determine the starting position of a partial string within a larger string
145
strtolist/3 divide a string into parts at specified separators 152
substring/3 retrieve a string that begins at a specified position within a larger string and continues through the end of the larger string
148
substring/4 retrieve a substring of a specified length beginning at a specified offset
148
tan/2 return the tangent of an angle 132
tf_active/1 verify if one or more time frames are active 204
tf_active/2 verify if one or more time frames are active at a given time 205
tf_current_end/2 obtain the end time of the current active interval of a time frame
208
tf_current_end/3 obtain the end time of the active interval of a time frame at a specified time
208
tf_current_interval/2 obtain the start and end time of the current active interval of a time frame
209
Table 43 Alphabetical list of primitives and functions (part 5 of 7)
Primitive/function name Description Page
104 BMC Knowledge Base Development Reference Guide
MRL functions and primitives
tf_current_interval/3 obtain the start and end time of the active interval of a time frame at a given time
209
tf_current_start/2 obtain the start time of the current active interval of a time frame
207
tf_current_start/3 obtain the start time of the active interval of a time frame at a specified time
207
tf_duration/3 calculate the duration of all active intervals of a time frame from a specified start time to the current time
217
tf_duration/4 calculate the duration of all active intervals of a time frame during a specified time period
217
tf_next_end/2 obtain the end time of the next active interval of a time frame 214
tf_next_end/3 obtain the end time of the next active interval of a time frame at a specified time
215
tf_next_interval/2 obtain the start and end time of the next active interval of a time frame
215
tf_next_interval/3 obtain the start and end time of the next active interval of a time frame at a specified time
216
tf_next_start/2 obtain the start time of the next active interval of a time frame
213
tf_next_start/3 obtain the start time of the next active interval of a time frame at a given time
214
tf_prev_end/2 obtain the end time of the previous active interval of a time frame
211
tf_prev_end/3 obtain the end time of the previous active interval of a time frame at a given time
212
tf_prev_interval/2 obtain the start and end time of the previous active interval of a time frame
212
tf_prev_interval/3 obtain the start and end time of the previous active interval of a time frame at a specified time
213
tf_prev_start/2 obtain the start time of the previous active interval of a time frame
210
tf_prev_start/3 obtain the start time of the previous active interval of a time frame at a given time
210
tf_udid_active/1 verify if one or more time frames specified by mc_udid are active at the current time
205
tf_udid_active/2 verify if one or more time frames specified by mc_udid are active at a specified time
206
time_extract/3 retrieve fields from a time stamp 164
time_stamp/1 retrieve the current time 162
time_stamp_to_cim/2 convert a time stamp to CIM (Common Information Model) format
162
time_stamp_to_str/2 convert a time stamp to the default DateFormat format 164
time_stamp_to_str/3 convert a time stamp to a specified format 163
Table 43 Alphabetical list of primitives and functions (part 6 of 7)
Primitive/function name Description Page
Chapter 4 Master Rule Language (MRL) reference 105
Primitives and functions overview
Primitives and functions overview
In the following sections, each primitive/function is indicated by its name followed by the number of arguments. When used as a function, there is one argument less, which is replaced with the function return value.
The description for each primitive/function shows the possible usage of the primitive and/or function. Some can be used as a primitive in a statement, some can be used as a function in an expression, and some can be used both as a primitive and as a function.
The arguments for each primitive/function are listed in a table. For each argument, the mode is indicated as input or output. An actual input argument can be any expression. The expression is evaluated before it is passed as an argument to the primitive. For an output argument, a variable is required.
Each argument has a type. The type is the expected type of the actual value for input arguments and the resulting value type for output arguments. Whenever necessary, the compiler will insert type conversions for input arguments.
The following argument types are used:
tolowercase/2 and lower/2
convert a string to all lowercase characters 144
touppercase/2 and upper/2
convert a string to all uppercase characters 145
trunc/2 truncate a real number to an integer (symmetric around 0) 123
unrelate/1 remove a relation of a related event to a source event 192
unset_cause/0 break the cause-to-effect relationship from a correlate rule 221
STRING an expression evaluating to a value of type STRING
INTEGER an expression evaluating to a value of type INTEGER
REAL an expression evaluating to a value of type REAL
POINTER an expression evaluating to a value of type POINTER
ENUM an expression evaluating to a value of an enumeration type
OBJECT a reference to an event or data object
SLOTREF a reference to a slot of an event, data or record object
ANY any simple (non-list) value
LIST_OF T a list of elements of type T
Table 43 Alphabetical list of primitives and functions (part 7 of 7)
Primitive/function name Description Page
106 BMC Knowledge Base Development Reference Guide
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
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
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.
action_requestor($REQUESTOR)$REQUESTOR=action_requestor()
Table 44 action_requestor/1 syntax argument
Argument Mode Type Description
$REQUESTOR output STRING the user or rule that requested the action
action AssignTo [Name:STRING($USER)] : EVENT($E){action_requestor($REQUESTOR);$E.administrator = $REQUESTOR;$E.mc_owner = $USER;}END
Chapter 4 Master Rule Language (MRL) reference 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
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
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.
action_requestor($USER,$PASSWD)
Table 45 action_requestor/2 syntax arguments
Argument Mode Type Description
$USER output STRING the requestor of the action
$PASSWD output STRING the password of the requestor of the action
action UserGetMetrics : EVENT($E) {
action_requestor($USER,$PASSWD);admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES);
}END
108 BMC Knowledge Base Development Reference Guide
Action-related primitives
action_requestor/3 — retrieve the user ID, password of the console user and rule type that is triggering the action
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
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).
action_requestor($USER,$PASSWD,$RULETYPE)
Table 46 action_requestor/3 syntax arguments
Argument Mode Type Description
$USER output STRING the requestor of the action
$PASSWD output STRING the password of the requestor of the action
$RULETYPE output STRING the type of rule that performs the action. This string is empty if a user performs the action.
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
Chapter 4 Master Rule Language (MRL) reference 109
Action-related primitives
action_return/2 — terminate an internal action and return a value
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
admin_execute/5 — perform an action through remote execution on IAS
action_return($CODE,$TEXT)
Table 47 action_return/2 syntax arguments
Argument Mode Type Description
$CODE input INTEGER specifies the numeric exit code to be returned when the action is terminated
$TEXT input STRING specifies the text to be returned when the action is terminated
action AssignTo [Name:STRING($USER)] : EVENT($E){action_requestor($REQUESTOR);$E.administrator = $REQUESTOR;$E.mc_owner = $USER;action_return(0,’Ownership taken’)}END
admin_execute($NAME,$OBJECT,$ACTION,$ARGS,$ACTEVENT)
110 BMC Knowledge Base Development Reference Guide
Action-related primitives
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
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
Table 48 admin_execute/5 syntax arguments
Argument Mode Type Description
$NAME input STRING specifies the name of the remote execution agent (Impact Administration Server or other external framework such as a cell or gateway)
$OBJECT input STRING specifies the object handle for the event or data on which the action is to be performed
$ACTION input STRING specifies the name of the action to be performed
$ARGS input 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 YES|NO — specifies whether or not to generate an action result event
action UserGetMetrics : EVENT($E) {
admin_execute(ias1,$E,GetMetrics,[],YES);}END
admin_execute($NAME,$USER,$PASSWD,$OBJECT,$ACTION,$ARGS,$ACTEVENT)
Chapter 4 Master Rule Language (MRL) reference 111
Action-related primitives
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
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.
Table 49 admin_execute/5 syntax arguments
Argument Mode Type Description
$NAME input STRING specifies the name of the remote execution agent (Impact Administration Server or other external framework such as a cell or gateway)
$USER input STRING specifies the user name of the account for the IAS or other external framework
$PASSWD input STRING specifies the password of the account for the IAS or other external framework
$OBJECT input STRING specifies the object handle for the event or data on which the action is to be performed
$ACTION input STRING specifies the name of the remote action to be performed
$ARGS input 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 YES|NO — specifies whether or not to generate an action result event
action UserGetMetrics : EVENT($E) {
action_requestor($USER,$PASSWD);admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES);
}END
112 BMC Knowledge Base Development Reference Guide
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.
perform/3 — perform a specified action
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/5 — perform a specified action and return a value
perform($OBJECT,$ACTION,$ARGS)
Table 50 perform/3 arguments
Argument Mode Type Description
$OBJECT input OBJECT specifies the object handle for the event or data on which the action is to be performed
$ACTION input STRING specifies the name of the action to be performed
$ARGS input 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.
perform($E,AssignTo,[Operator1]);
perform($OBJECT,$ACTION,$ARGS,$RETCODE,$RETTEXT)
Table 51 perform/5 arguments
Argument Mode Type Description
$OBJECT input OBJECT specifies the object handle for the event or data on which the action is to be performed
$ACTION input STRING specifies the name of the action to be performed
Chapter 4 Master Rule Language (MRL) reference 113
Action-related primitives
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
execute/4 — run a program as an external process
$ARGS input 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.
$RETCODE output INTEGER the numeric return code of the specified action
$RETTEXT output STRING the text string returned by the specified action
perform($E,AssignTo,[Operator1],$RETCODE,$RETTEXT);
execute($EVENT,$PROG,$ARGS,$ACTEVT)
Table 52 execute/4 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the object handle for the event on which the action is to be performed
$PROG input STRING specifies the name of the external program to be run
Table 51 perform/5 arguments
Argument Mode Type Description
114 BMC Knowledge Base Development Reference Guide
Action-related primitives
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 system-defined 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
confirm_external/2 — run an external program and wait for its termination to continue to process the current event
$ARGS input 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 YES|NO
Indicates whether or not to generate an action event.
execute($E,mc_modslot,[msg,’Hello’],NO);
NOTE The confirm_external/2 primitive can only be used in a refine rule.
confirm_external($PROG,$ARGS)
Table 52 execute/4 arguments
Argument Mode Type Description
Chapter 4 Master Rule Language (MRL) reference 115
Action-related primitives
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
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.
Table 53 confirm_external/2 arguments
Argument Mode Type Description
$PROG input STRING specifies the name of the external program to be run
$ARGS input 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.
confirm_external(mc_ping,[]);
116 BMC Knowledge Base Development Reference Guide
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
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.
NOTE The get_external/4 primitive can only be used in a refine rule.
get_external($PROG,$ARGS,$INTF,$ANS)
Table 54 get_external/4 arguments
Argument Mode Type Description
$PROG input STRING specifies the name of the external program to be run
$ARGS input 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 input STRING specifies the name of the interface class
$ANS output OBJECT the data produced by the external program returned as an interface object
Chapter 4 Master Rule Language (MRL) reference 117
Value type conversion primitives
get_external/4 example
In this example, the Knowledge Base contains the following class definition:
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:
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.
Value type conversion primitives
inttostring/2 — convert an integer value to a string value
Use inttostring/2 to convert the integer value specified in the $INTVAL argument to a string value returned in $STRVAL.
MC_INTERFACE: DOOR_INFO DEFINES {door_id: STRING;door_location: STRING;door_status: STRING;}; END
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
inttostring($INTVAL,$STRVAL)$STRVAL=inttostring($INTVAL)
Table 55 inttostring/2 arguments
Argument Mode Type Description
$INTVAL input INTEGER specifies the integer value to be converted to a string
$STRVAL output STRING the resulting conversion string
118 BMC Knowledge Base Development Reference Guide
Value type conversion primitives
inttostring/2 example
int_to_hex/2 — convert an integer value to a string containing its hexadecimal notation
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
int_to_hex/3 — convert an integer value to a string containing its hexadecimal notation in a specified field width
$E.msg = concat([’Event #’,inttostring($E.event_handle)]);
$STRVAL=int_to_hex($INTVAL)
Table 56 int_to_hex/2 arguments
Argument Mode Type Description
$INTVAL input INTEGER specifies the integer value to be converted to hexadecimal notation
$STRVAL output STRING the hexadecimal notation of the integer returned as a string
$E.msg = concat([’Event # 0x’,int_to_hex($E.event_handle)]);
$STRVAL=int_to_hex($INTVAL,$FLDLEN)
Table 57 int_to_hex/3 arguments
Argument Mode Type Description
$INTVAL input INTEGER specifies the integer value to be converted to hexadecimal notation
$FLDLEN input INTEGER specifies the desired resulting field width
$STRVAL output STRING the hexadecimal notation of the integer returned as a string
Chapter 4 Master Rule Language (MRL) reference 119
Value type conversion primitives
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
realtostring/2 — convert a real value to a string value
Use realtostring/2 to convert the real value specified in the $REALVAL argument to a string value returned in $STRVAL.
realtostring/2 example
pointertostring/2 — convert a pointer value to a string value
$E.msg = concat([’Event # 0x’,int_to_hex($E.event_handle,10)]);
realtostring($REALVAL,$STRVAL)$STRVAL=realtostring($REALVAL)
Table 58 realtostring/2 arguments
Argument Mode Type Description
$REALVAL input INTEGER specifies the real value to be converted to a string value
$STRVAL output STRING the conversion result, returned as a string
$DEV = ( $AVERAGE_DURATION - real($E.duration) ) ^ 2;$E.msg = concat([’Duration deviation=’,realtostring($DEV)]);
pointertostring($PTRVAL,$STRVAL)$STRVAL=pointertostring($PTRVAL)
Table 59 pointertostring/2 arguments
Argument Mode Type Description
$PTRVAL input POINTER specifies the pointer value to be converted to a string
$STRVAL output STRING the conversion result, returned as a string
120 BMC Knowledge Base Development Reference Guide
Value type conversion primitives
Use pointertostring/2 to convert the pointer value specified in the $PTRVAL argument to a string value returned in $STRVAL.
pointertostring/2 example
string/2 — convert any non-list value to a string value
Use string/2 to convert the non-list value specified by $ANYVAL to a string value returned in $STRVAL.
string/2 example
stringtoint/2 — convert a string value to an integer value
Use stringtoint/2 to convert a string value specified in the $STRVAL argument to an integer value returned in $INTVAL.
$E.msg = concat([’Address=’,pointertostring($ADDR)]);
$STRVAL=string($ANYVAL)
Table 60 string/2 arguments
Argument Mode Type Description
$ANYVAL input ANY specifies any non-list value to be converted to a string
$STRVAL output STRING the conversion result, returned as a string
$E.msg = concat([’Value=’,string($ANYVAL)]);
stringtoint($STRVAL,$INTVAL)$INTVAL=stringtoint($STRVAL)
Table 61 stringtoint/2 arguments
Argument Mode Type Description
$STRVAL input STRING specifies the string value to be converted to an integer
$INTVAL output INTEGER the conversion result, returned as an integer
Chapter 4 Master Rule Language (MRL) reference 121
Value type conversion primitives
stringtoint/2 example
stringtoreal/2 — convert a string value to a real value
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
stringtopointer/2 — convert a string value to a pointer value
Use stringtopointer/2 to convert a string value specified in the $STRVAL argument to a pointer value returned in $PTRVAL.
$INTVAL = stringtoint($E.msg);
stringtoreal($STRVAL,$REALVAL)$REALVAL=stringtoreal($STRVAL)
Table 62 stringtoreal/2 arguments
Argument Mode Type Description
$STRVAL input STRING specifies the string value to be converted to an integer
$REALVAL output REAL the conversion result, returned as a real value
$REALVAL = stringtoreal($E.msg);
stringtopointer($STRVAL,$PTRVAL)$PTRVAL=stringtopointer($STRVAL)
Table 63 stringtopointer/2 arguments
Argument Mode Type Description
$STRVAL input STRING specifies the string value to be converted to an integer
$PTRVAL output POINTER the conversion result, returned as a pointer
122 BMC Knowledge Base Development Reference Guide
Value type conversion primitives
stringtopointer/2 example
int/2 — truncate a numeric value to an integer value
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
trunc/2 — truncate a real number to an integer (symmetric around 0)
$PTRVAL = stringtopointer($E.msg);
$INTVAL=int($NUMBER)
Table 64 int/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the numeric (integer or real) value that is to be converted to an integer
$INTVAL output INTEGER the conversion result, returned as an integer
$DEV = int( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );
$INTVAL=trunc($NUMBER)
Table 65 trunc/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the numeric (integer or real) value that is to be converted to an integer
$INTVAL output INTEGER the conversion result, returned as an integer
Chapter 4 Master Rule Language (MRL) reference 123
Value type conversion primitives
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
round/2 — convert a numeric value to an integer value by rounding the number
Use round/2 to convert a numeric value to an integer value returned in $INTVAL. The conversion rounds the number.
round/2 example
real/2 and float/2 — convert a numeric value to a real value
$DEV = trunc( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );
$INTVAL=round($NUMBER)
Table 66 round/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the numeric (integer or real) value that is to be converted to an integer
$INTVAL output INTEGER the conversion result, returned as an integer
$DEV = round( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );
$REALVAL=real($NUMBER)$REALVAL=float($NUMBER)
124 BMC Knowledge Base Development Reference Guide
Value type conversion primitives
Use real/2 or float/2 to convert a numeric value to a real (floating point) value returned in $REALVAL.
real/2 or float/2 example
code/2 — retrieve the internal numeric representation of a character
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
char/2 — produce a string containing a single character with a specified numeric internal representation
Table 67 real/2 or float/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the numeric (integer or real) value to be converted to a real (floating point) value
$REALVAL output REAL the conversion result, returned as a real (floating point) value
$DEV = ( $AVERAGE_DURATION - real($E.duration) ) ^ 2;
$INTVAL=code($STRVAL)
Table 68 code/2 arguments
Argument Mode Type Description
$STRVAL input STRING specifies the single character for which you want to return the numeric code
$INTVAL output INTEGER the numeric code of the character, returned as an integer
$CODE = code($E.msg);
$STRVAL=char($INTVAL)
Chapter 4 Master Rule Language (MRL) reference 125
Mathematical functions
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
Mathematical functions
max/3 — determine the maximum of two values
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.
Table 69 char/2 arguments
Argument Mode Type Description
$INTVAL input INTEGER specifies the integer character code for the single-character string
$STRVAL output STRING the single character represented by the integer character code, returned as a string
$E.msg = char($E.msg);
$MAXVAL=max($VAL1,$VAL2)
Table 70 max/3 arguments
Argument Mode Type Description
$VAL1 input ANY specifies the first value to be compared
$VAL2 input ANY specifies the second value to be compared to the first value
$MAXVAL output ANY returns the maximum value
126 BMC Knowledge Base Development Reference Guide
Mathematical functions
max/3 example
min/3 — determine the minimum of two values
.
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
sign/2 — determine whether a numeric value is positive, negative, or zero
$MAX_DURATION = max( $PREVIOUS_DURATION , $E.duration );
$MINVAL=min($VAL1,$VAL2)
Table 71 min/3 arguments
Argument Mode Type Description
$VAL1 input ANY specifies the first value to be compared
$VAL2 input ANY specifies the second value to be compared to the first value
$MINVAL output ANY returns the minimum value
$MIN_DURATION = min( $PREVIOUS_DURATION , $E.duration );
$SIGN=sign($NUMBER)
Table 72 sign/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the numeric (integer or real) value for which the sign is to be returned
$SIGN output INTEGER returns the sign of the number. Possible values include:
■ -1 — negative number■ 0 — zero value■ 1 — positive number
Chapter 4 Master Rule Language (MRL) reference 127
Mathematical functions
The sign/2 function returns the sign of the numeric value specified by the $NUMBER argument and returned as $SIGN.
sign/2 example
abs/2 — determine the absolute value of a numeric value
The abs/2 function returns the absolute value of the numeric value specified in the $NUMBER argument as $ABSVAL.
abs/2 example
sqrt/2 — determine the square root of a numeric value
The sqrt/2 function returns the square root value of the numeric value specified by the $NUMBER argument as $RESULT.
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 = sign( $AVERAGE_DURATION - real($E.duration) );
$ABSVAL=abs($NUMBER)
Table 73 abs/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the numeric (integer or real) value for which the absolute value is to be returned
$ABSVAL output INTEGER|REAL returns the absolute value of the number
$ABS = abs( $AVERAGE_DURATION - real($E.duration) );
$RESULT=sqrt($NUMBER)
Table 74 sqrt/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the numeric (integer or real) value for which the square root is to be returned
$RESULT output REAL returns the square root of the number
128 BMC Knowledge Base Development Reference Guide
Mathematical functions
sqrt/2 example
exp/2 — raise e (2.718281828...) to a specified power
The exp/2 function returns the number e (2.718281828...) raised to the power specified by the $NUMBER argument as $RESULT.
exp/2 example
pow/3 — raise a number to a specified 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.
$SQRT = sqrt( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );
$RESULT=exp($NUMBER)
Table 75 exp/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the power to which e is to be raised
$RESULT output REAL returns e raised to the specified number
$EXP = exp( $E.duration );
$RESULT=pow($NUMBER,$POWER)
Table 76 pow/3 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the numeric (integer or real) value to be raised to the specified power
$POWER input INTEGER|REAL specifies the power to which the numeric value is to be raised
$RESULT output REAL returns the number raised to the power
NOTE The exponentiation operator ^ can only be used with integer powers. For non-integer powers, pow/3 must be used.
Chapter 4 Master Rule Language (MRL) reference 129
Mathematical functions
pow/3 example
log/2 — return the natural logarithm of a specified number
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
log10/2 — return the decimal logarithm of a specified number
The log10/2 function returns the decimal logarithm (base 10) of the number specified by the $NUMBER argument in the $RESULTargument.
$POW = pow( $VAL , 3.14 );
$RESULT=log($NUMBER)
Table 77 log/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the numeric (integer or real) value for which the natural logarithm is to be returned
$RESULT output REAL the natural logarithm of the number, returned as a real value
$LOG = log( $VAL );
$RESULT=log10($NUMBER)
Table 78 log10/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the numeric (integer or real) value for which the decimal logarithm is to be returned
$RESULT output REAL the natural logarithm of the number, returned as a real value
130 BMC Knowledge Base Development Reference Guide
Mathematical functions
log10/2 example
sin/2 — return the sine of an angle
The sin/2 function returns the sine of the angle specified in the $NUMBER argument in the $RESULT argument.
sin/2 example
cos/2 — return the cosine of an angle
The cos/2 function returns the cosine of the angle specified in the $NUMBER argument in the $RESULT argument.
$LOG = log10( $VAL );
$RESULT=sin($NUMBER)
Table 79 sin/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the angle (expressed in radians) for which the sine is to be returned
$RESULT output REAL the sine of the angle, returned as a real value
$SIN = sin( $ANGLE );
$RESULT=cos($NUMBER)
Table 80 cos/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the angle (expressed in radians) for which the cosine is to be returned
$RESULT output REAL the cosine of the angle, returned as a real value
Chapter 4 Master Rule Language (MRL) reference 131
Mathematical functions
cos/2 example
tan/2 — return the tangent of an angle
The tan/2 function returns the tangent of the angle specified in the $NUMBER argument in the $RESULT argument.
tan/2 example
asin/2 — return the arc sine of a specified number
The asin/2 function returns the arc sine of the number specified in the $NUMBER argument in the $RESULT argument.
$COS = cos( $ANGLE );
$RESULT=tan($NUMBER)
Table 81 tan/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the angle (expressed in radians) for which the tangent is to be returned
$RESULT output REAL the tangent of the angle, returned as a real value
$TAN = tan( $ANGLE );
$RESULT=asin($NUMBER)
Table 82 asin/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the number for which the arc sine is to be returned
$RESULT output REAL angle for which the number $NUMBER is the arc sine (expressed in radians)
132 BMC Knowledge Base Development Reference Guide
Mathematical functions
asin/2 example
acos/2 — return the arc cosine of a specified number
The acos/2 function returns the arc cosine of the number specified in the $NUMBER argument in the $RESULT argument.
acos/2 example
atan/2 — return the arc tangent of a specified number
The atan/2 function returns the arc tangent of the number specified in the $NUMBER argument in the $RESULT argument.
$ANGLE = asin( $VAL );
$RESULT=acos($NUMBER)
Table 83 acos/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the number for which the arc cosine is to be returned
$RESULT output REAL angle for which the number $NUMBER is the arc cosine (expressed in radians)
$ANGLE = acos( $VAL );
$RESULT=atan($NUMBER)
Table 84 atan/2 arguments
Argument Mode Type Description
$NUMBER input INTEGER|REAL specifies the number for which the arc tangent is to be returned
$RESULT output REAL angle for which the number $NUMBER is the arc tangent (expressed in radians)
Chapter 4 Master Rule Language (MRL) reference 133
Mathematical functions
atan/2 example
atan2/3 — return the arc tangent of the ratio of two numbers
The atan2/3 function returns the arc tangent of the ratio of $NUMBER1 and $NUMBER2 in the $RESULT argument.
atan2/3 example
gcd/3 — return the greatest common divisor of two numbers
$ANGLE = atan( $VAL );
$RESULT=atan2($NUMBER1,$NUMBER2)
Table 85 atan2/3 arguments
Argument Mode Type Description
$NUMBER1 input INTEGER|REAL specifies the first (integer or real) value of the ratio
$NUMBER2 input INTEGER|REAL specifies the second (integer or real) value of the ratio
$RESULT output REAL angle for which the ratio of $NUMBER1 and $NUMBER2 is the arc tangent (expressed in radians)
$RIGHTANGLE = atan2( 1 , 0 );
$RESULT=gcd($NUMBER1,$NUMBER2)
Table 86 gcd/3 arguments
Argument Mode Type Description
$NUMBER1 input INTEGER specifies the first integer value of the two integers for which a common divisor is to be returned
$NUMBER2 input INTEGER specifies the second integer value of the two integers for which a common divisor is to be returned
$RESULT output INTEGER the greatest common divisor of the two specified numbers
134 BMC Knowledge Base Development Reference Guide
Enumeration operations
The gcd/3 function returns the greatest common divisor of $NUMBER1 and $NUMBER2 in $RESULT.
gcd/3 example
random/3 — return a random integer that falls between two specified numbers
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
Enumeration operations
incr/1 — increment an integer or enumeration slot by 1
$GCD = gcd( $NUM1 , $NUM2 );
$RESULT=random($NUMBER1,$NUMBER2)
Table 87 random/3 arguments
Argument Mode Type Description
$NUMBER1 input INTEGER first number in the range within which a random number is to be returned
$NUMBER2 input INTEGER last number in the range within which a random number is to be returned
$RESULT output INTEGER a random number between both numbers
$RAND = random( $NUM1 , $NUM2 );
incr($SLOT)
Table 88 incr/1 arguments
Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot to be incremented
Chapter 4 Master Rule Language (MRL) reference 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/2 and next/2 — return an integer or enumeration slot value incremented by 1
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
incr/2 — increment an integer or enumeration slot by a specified value
incr( $E.mc_priority );
NOTE The next/2 function has the same functionality as incr/2 but is used only on enumeration type slots. This function is deprecated.
$VAL=incr($SLOT)
Table 89 incr/2 arguments
Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot for which the incremented value is to be returned.
The actual value of the slot is not incremented.
$VAL output INTEGER|ENUM value of the slot incremented by 1
$NEWPRIO = incr( $E.mc_priority );
incr($SLOT,$INCR)
136 BMC Knowledge Base Development Reference Guide
Enumeration operations
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/3 — return an integer or enumeration slot value incremented by a specified value
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.
Table 90 incr/2 arguments
Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot to be incremented
$INCR input INTEGER specifies the number by which the slot is to be incremented
incr( $E.mc_priority , 2 );
$VAL=incr($SLOT,$INCR)
Table 91 incr/3 arguments
Argument Mode Type Description
$SLOT input SLOTREF 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
$VAL output INTEGER|ENUM value of the slot incremented by $INCR
Chapter 4 Master Rule Language (MRL) reference 137
Enumeration operations
incr/3 example
incr/3 — increment an integer or enumeration slot by a specified value within a specified limit
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/4 — retrieve the value of an integer or enumeration slot incremented by a given value within a specified limit
$NEWPRIO = incr( $E.mc_priority , 2 );
incr($SLOT,$INCR,$LIMIT)
Table 92 incr/3 arguments
Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot to be incremented
$INCR input INTEGER specifies the number by which the slot is to be incremented
$LIMIT input INTEGER|ENUM specifies the limit to which the slot value is to be incremented
incr( $E.mc_priority , 2 , PRIORITY_2 );
$VAL=incr($SLOT,$INCR,$LIMIT)
Table 93 incr/4 arguments
Argument Mode Type Description
$SLOT input SLOTREF 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 BMC Knowledge Base Development Reference Guide
Enumeration operations
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
decr/1 — decrement an integer or enumeration slot by 1
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/2 and prev/2 — return an integer or enumeration slot value decremented by 1
$LIMIT input INTEGER|ENUM specifies the limit to which the slot value is to be incremented when it is returned in $VAL
$VAL output INTEGER|ENUM value of the slot incremented by $INCR
$NEWPRIO = incr( $E.mc_priority , 2 , PRIORITY_2 );
decr($SLOT)
Table 94 decr/1 arguments
Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot to be decremented
decr( $E.mc_priority );
NOTE The prev/2 function has the same functionality as decr/2 but is used only on enumeration type slots. This function is deprecated.
$VAL=decr($SLOT)
Table 93 incr/4 arguments
Argument Mode Type Description
Chapter 4 Master Rule Language (MRL) reference 139
Enumeration operations
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
decr/2 — decrement an integer or enumeration slot by a specified value
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.
Table 95 decr/2 arguments
Argument Mode Type Description
$SLOT input SLOTREF 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 INTEGER|ENUM value of the slot decremented by 1
$NEWPRIO = decr( $E.mc_priority );
decr($SLOT,$DECR)
Table 96 decr2 arguments
Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot to be decremented
$DECR input INTEGER specifies the number of values that the slot is to be decremented
140 BMC Knowledge Base Development Reference Guide
Enumeration operations
decr2 example
decr/3 — retrieve the value of an integer or enumeration slot decremented by a specified value
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
decr/3 — decrement an integer or enumeration slot by a specified value within a given limit
decr( $E.mc_priority , 2 );
$VAL=decr($SLOT,$DECR)
Table 97 decr/3 arguments
Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot for which the decremented value is to be returned.
The actual value of the slot is not decremented.
$DECR input INTEGER specifies the number by which the slot value returned in $VAL is to be decremented
$VAL output INTEGER|ENUM value of the slot decremented by $DECR
$NEWPRIO = decr( $E.mc_priority , 2 );
decr($SLOT,$DECR,$LIMIT)
Chapter 4 Master Rule Language (MRL) reference 141
Enumeration operations
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/4 — return an integer or enumeration slot value decremented by a specified value within a given limit
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.
Table 98 decr/3 arguments
Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot to be decremented
$DECR input INTEGER specifies the number by which the slot is to be decremented
$LIMIT input INTEGER|ENUM specifies the limit to which the slot value is to be decremented
decr( $E.mc_priority , 2 , PRIORITY_4 );
$VAL=decr($SLOT,$DECR,$LIMIT)
Table 99 decr/4 arguments
Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot for which the decremented value is to be returned.
The actual value of the slot is not decremented.
$DECR input INTEGER specifies the number by which the slot value returned in $VAL is to be decremented
$LIMIT input INTEGER|ENUM specifies the limit to which the slot value returned in $VAL is to be decremented
$VAL output INTEGER|ENUM value of the slot decremented by $DECR
142 BMC Knowledge Base Development Reference Guide
String manipulation
decr/4 example
String manipulation
concat/2 — concatenate a list of strings
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
strlen/2 and len/2 — determine the length of a string
$NEWPRIO = decr( $E.mc_priority , 2 , PRIORITY_4 );
concat($STRLIST,$STR)$STR=concat($STRLIST)
Table 100 concat/2 arguments
Argument Mode Type Description
$STRLIST input LIST_OF STRING list of strings to be concatenated
$STR output STRING the result of concatenating the specified strings
concat([’Duration: ’,inttostring($E.duration),’ seconds’],$E.msg);
NOTE The len/2 function has the same functionality as strlen/2 but exists only as a function.
strlen($STR,$LEN)$LEN=strlen($STR)$LEN=len($STR)
Table 101 strlen/2 and len/2 arguments
Argument Mode Type Description
$STR input STRING the string for which the length is to be returned
$LEN output INTEGER string length in characters
Chapter 4 Master Rule Language (MRL) reference 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.
strlen/2 example
tolowercase/2 and lower/2 — convert a string to all lowercase characters
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.
NOTE The number of characters in the string may differ from the number of bytes needed to store the string.
$MSGLEN = strlen($E.msg);
NOTE The lower/2 function has the same functionality as tolowercase/2 but exists only as a function.
tolowercase($ORGSTR,$NEWSTR)$NEWSTR=tolowercase($ORGSTR)$NEWSTR=lower($ORGSTR)
Table 102 tolowercase/2 and lower/2 arguments
Argument Mode Type Description
$ORGSTR input STRING specifies the string to be converted to lowercase
$NEWSTR output STRING returns the all lowercase version of original string
144 BMC Knowledge Base Development Reference Guide
String manipulation
tolowercase/2 example
touppercase/2 and upper/2 — convert a string to all uppercase characters
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
strpart/3 — determine the starting position of a partial string within a larger string
$E.mc_host = tolowercase($E.mc_host);
NOTE The upper/2 function has the same functionality as touppercase/2 but exists only as a function.
touppercase($ORGSTR,$NEWSTR)$NEWSTR=touppercase($ORGSTR)$NEWSTR=upper($ORGSTR)
Table 103 touppercase/2 and upper/2 arguments
Argument Mode Type Description
$ORGSTR input STRING specifies the string to be converted to uppercase
$NEWSTR output STRING returns the all uppercase version of original string
$E.mc_host = touppercase($E.mc_host);
strpart($STR,$PART,$POS)$POS=strpart($STR,$PART)
Chapter 4 Master Rule Language (MRL) reference 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
strnpart/4 — determine the start position of a specified occurrence of a part of a string
Table 104 strpart/3 arguments
Argument Mode Type Description
$STR input STRING specifies the base string within which you want to determine the starting position of another, partial, string
$PART input STRING specifies the partial string for which you are trying to determine the starting position within $STR
$POS output INTEGER starting position of the partial string within $STR
$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);
strnpart($STR,$PART,$CNT,$POS)$POS=strnpart($STR,$PART,$CNT)
Table 105 strnpart/4 arguments
Argument Mode Type Description
$STR input STRING specifies the base string within which you want to determine the starting position of a specified reoccurrence of a another, partial, string
$PART input STRING specifies the partial string for which you are trying to determine the starting position after a specified number of occurrences within $STR
$CNT input INTEGER specifies the number of occurrences of the partial string to count before returning the position of the beginning of the last counted occurrence of the partial string
$POS output INTEGER starting position of the partial string within $STR
146 BMC Knowledge Base Development Reference Guide
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
strextract/4 — retrieve a string of a specified length that begins at a specified position within a larger string
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.
$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($STR,$POS,$LEN,$NEWSTR)$NEWSTR=strextract($STR,$POS,$LEN)
Table 106 strextract/4 arguments
Argument Mode Type Description
$STR input STRING specifies the base string within which you want to retrieve another, partial, string that starts at $POS
$POS input INTEGER specifies the starting position for the partial string that you want to return
$LEN input INTEGER specifies the length (number of characters) of the partial string that you want to return
$NEWSTR output STRING retrieved string
Chapter 4 Master Rule Language (MRL) reference 147
String manipulation
strextract/4 example
substring/3 — retrieve a string that begins at a specified position within a larger string and continues through the end of the larger string
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
substring/4 — retrieve a substring of a specified length beginning at a specified offset
strextract($YYYYMMDD,5,2,$MM);
$NEWSTR=substring($STR,$SKIP)
Table 107 substring/3 arguments
Argument Mode Type Description
$STR input STRING specifies the base string within which you want to retrieve another, partial, string that starts after $SKIP
$SKIP input INTEGER specifies the number of characters to skip in the base string before $NEWSTR begins
$NEWSTR output STRING retrieved string
$DD = substring($YYYYMMDD,6);
$NEWSTR=substring($STR,$SKIP,$LEN)
Table 108 substring/4 arguments
Argument Mode Type Description
$STR input STRING specifies the base string within which you want to retrieve another, partial, string that starts after $SKIP
$SKIP input INTEGER specifies the number of characters to skip in the base string before $NEWSTR begins
$LEN input INTEGER specifies the length of $NEWSTR
$NEWSTR output STRING retrieved string
148 BMC Knowledge Base Development Reference Guide
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
strip/2 — strip leading and trailing blank spaces from a string
Use strip/2 to remove the beginning and ending blank spaces from $STR and copy the resulting string into $NEWSTR.
strip/2 example
strip/3 — remove blank spaces from specified parts of a string
Use strip/3 to remove the blank spaces from position $POS within $STR and copy the resulting string into $NEWSTR.
$MM = substring($YYYYMMDD,4,2);
$NEWSTR=strip($STR)
Table 109 strip/2 arguments
Argument Mode Type Description
$STR input STRING specifies the base string from which blank spaces at the beginning and end of the string are to be removed
$NEWSTR output STRING resulting string after the blank spaces have been removed
$MSG = strip($E.msg);
$NEWSTR=strip($STR,$POS)
Table 110 strip/3 arguments
Argument Mode Type Description
$STR input STRING specifies the base string from which blank spaces at a specified position are to be removed
$POS input INTEGER specifies the position within the base string from which blank spaces are to be removed
$NEWSTR output STRING resulting string after the blank spaces have been removed
Chapter 4 Master Rule Language (MRL) reference 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:
strip/3 example
strip/4 — remove specified characters from specified parts of a string
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.
Table 111 Possible values for the $POS argument
$POS value Binary value Impacted part of the string
0 000 none
1 001 end
2 010 middle
3 011 middle + end
4 100 beginning
5 101 beginning + end
6 110 beginning + middle
7 111 beginning + middle + end
$MSG = strip($E.msg,2);
$NEWSTR=strip($STR,$POS,$CHARS)
Table 112 strip/4 arguments
Argument Mode Type Description
$STR input STRING specifies the base string from which specified characters are to be removed
$POS input INTEGER specifies the part(s) of the string from which specified characters are to be removed
$CHARS input STRING specifies the characters to be removed
$NEWSTR output STRING resulting string after the specified characters have been removed
150 BMC Knowledge Base Development Reference Guide
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:
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
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.
Table 113 Possible values for the $POS argument
$POS value Binary value Impacted part of the string
0 000 none
1 001 end
2 010 middle
3 011 middle and end
4 100 beginning
5 101 beginning and end
6 110 beginning and middle
7 111 beginning, middle, and end (entire string)
$MSG = strip($E.msg,6,’ #!’);
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 #!# .
strtolist/3 — divide a string into parts at specified separators
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
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
strtolist($STR,$SEP,$FLDS)$FLDS=strtolist($STR,$SEP)
Table 114 strtolist/3 arguments
Argument Mode Type Description
$STR input STRING specifies the string to be divided into fields
$SEP input STRING specifies the separator(s) which separates the pieces of the string into fields
$FLDS output LIST_OF STRING retrieved fields
strtolist(’/usr/bin/mcell.exe’,’/.’,$FLDS);
strmatch($STR,$PAT,$FLDS)$FLDS=strmatch($STR,$PAT)
Table 115 strmatch/3 arguments
Argument Mode Type Description
$STR input STRING specifies the string with which the pattern is to be matched
$PAT input STRING specifies the pattern to match with the string
$FLDS output LIST_OF STRING retrieved fields
152 BMC Knowledge Base Development Reference Guide
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:
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:
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:
■ 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.
\\ backslash
\s space (single space)
\n new line
\r carriage return
\t tab
\0ddd character code in octal
%% literal match of %
%d decimal integer number
%f floating point real number
%c single character
%s string value
Chapter 4 Master Rule Language (MRL) reference 153
String manipulation
strmatch/3 example
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.
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.
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.
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.
match_regex/3 — match a string with a regular expression
strmatch(’abc def 12’,’%s %d’,[$FLD1,$FLD2]);
strmatch(’Hi you there!’,’Hi %s!’,$FLDS);
strmatch(’Hi there’,’Hi %s!’,$FLDS);
strmatch(’a b c go’,’%s %s go’,[$FLD1,$FLD2]);
match_regex($STR,$REGEX,$OPTS)
Table 116 match_regex/3 arguments
Argument Mode Type Description
$STR input STRING specifies the string to be matched
$REGEX input STRING specifies the regular expression to match with the string
$OPTS input STRING specifies the options for how the regular expression engine operates
154 BMC Knowledge Base Development Reference Guide
String manipulation
Use match_regex/3 to match a string $STR with regular expression $REGEX applying options specified in $OPTS.
The value of the $OPTS argument can be either an empty string or a sequence of any of the following option indicators:
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
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
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.
i perform case insensitive string comparison
m multi-line mode
s a dot matches any character, including new line
x extended mode (see below)
match_regex(’2007 02 04 mcell: RULES: xyz’,’[0-9]* [0-9]* [0-9]* [^:]*: [^:]*: .*’,’’);
match_regex($STR,$REGEX,$OPTS,$FLDS)$FLDS=match_regex($STR,$REGEX,$OPTS)
Table 117 match_regex/4 arguments
Argument Mode Type Description
$STR input STRING specifies the string to be matched
$REGEX input STRING specifies the regular expression to match to the string
Chapter 4 Master Rule Language (MRL) reference 155
String manipulation
Use match_regex/4 to match a string $STR with regular expression $REGEX applying options from $OPTS and to collect retrieved fields in $FLDS.
The options argument can be either an empty string or a sequence of any of the following option indicators:
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
The input string, which could be part of a trace, matches the regular expression. The two fields are collected in $FLDS as [mcell,RULES].
$OPTS input STRING specifies the options for how the regular expression engine operates
$FLDS output LIST_OF STRING retrieved fields
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.
i perform case insensitive string comparison
m multi-line mode
s a dot matches any character, including new line
x extended mode (see below)
match_regex(’2007 02 04 mcell: RULES: xyz’,’[0-9]* [0-9]* [0-9]* ([^:]*): ([^:]*): .*’,’’,$FLDS);
Table 117 match_regex/4 arguments
Argument Mode Type Description
156 BMC Knowledge Base Development Reference Guide
String manipulation
match_regex/5 — match a string with a regular expression and retrieve a given number of fields from it
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.
The options argument can be either an empty string or a sequence of any of the following option indicators:
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
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.
match_regex($STR,$REGEX,$OPTS,$FLDCNT,$FLDS)$FLDS=match_regex($STR,$REGEX,$OPTS,$FLDCNT)
Table 118 match_regex/5 arguments
Argument Mode Type Description
$STR input STRING specifies the string to be matched
$REGEX input STRING specifies the regular expression to match to the string
$OPTS input STRING specifies the options for how the regular expression engine operates
$FLDCNT input INTEGER requested number of fields to be retrieved
$FLDS output LIST_OF STRING retrieved fields
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.
i perform case insensitive string comparison
m multi-line mode
s a dot matches any character, including new line
x extended mode (see below)
match_regex(’2007 02 04 mcell: RULES: xyz’,’[0-9]* [0-9]* [0-9]* ([^:]*): ([^:]*): .*’,’’,1,[$FLD]);
Chapter 4 Master Rule Language (MRL) reference 157
String manipulation
sprintf/3 — format a series of values into a 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.
sprintf/3 example
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
sprintf($STR,$FORMAT,$ARGS)$STR=sprintf($FORMAT,$ARGS)
Table 119 sprintf/3 arguments
Argument Mode Type Description
$FORMAT input STRING specifies the format for the resulting string
$ARGS input LIST_OF ANY specifies the arguments to be printed as a string
$STR output STRING resulting string
WARNING The arguments specified in $ARGS must be compliant with the specified format. Passing incompatible arguments can cause a crash of the cell.
sprintf($E.msg,’Event #%x’,[$E.event_handle]);
$STR=mapslots($OBJECTS,$FORMAT,$EXPRS)
Table 120 mapslots/4 arguments
Argument Mode Type Description
$OBJECTS input LIST_OF OBJECT specifies the list of event or data objects
$FORMAT input STRING specifies the format to be applied
$EXPRS input LIST_OF STRING specifies the expressions to be evaluated
$STR output STRING resulting string
158 BMC Knowledge Base Development Reference Guide
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
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.
mapslots/3 — format a series of expressions that refer to objects into a string
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.
$STR = mapslots([$E,$D],’Event %s is associated to data %s’,[’$1.mc_ueid’,’$2.mc_udid’]);
$STR=mapslots($OBJECTS,$EXPRS)
Table 121 mapslots/3 arguments
Argument Mode Type Description
$OBJECTS input LIST_OF OBJECT specifies the list of event or data objects
$EXPRS input LIST_OF STRING specifies the format and expressions to be evaluated
$STR output STRING resulting string
Chapter 4 Master Rule Language (MRL) reference 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.
mapslots/3 example
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.
has_substring/2 — verify the occurrence of a substring within a string or list of strings
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.
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.
$STR = mapslots([$E,$D],[’Event %s is associated to data %s’,’$1.mc_ueid’,’$2.mc_udid’]);
has_substring($STRING,$SUBSTRING)has_substring($LIST,$SUBSTRING)
Table 122 has_substring/2 syntax argument
Argument Mode Type Description
$STRING input STRING string that you want to test for a specified substring
$LIST input LIST_OF STRING list of strings that you want to test for a specified substring
$SUBSTRING input STRING substring that you want to search for
160 BMC Knowledge Base Development Reference Guide
String manipulation
has_substring/2 example
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/3—verify the occurrence of a substring within a string or list of strings using a comparison modifier
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.
The has_substring/3 primitive succeeds or fails depending on whether or not the substring occurs.
if ( has_substring($E.msg,NGP) ) ...
has_substring($STRING,$SUBSTRING,$MODS)has_substring($LIST,$SUBSTRING,$MODS)
Table 123 has_substring/3 syntax argument
Argument Mode Type Description
$STRING input STRING string that you want to test for a specified substring
$LIST input LIST_OF STRING list of strings that you want to test for a specified substring
$SUBSTRING input STRING substring that you want to search for
$MODS input LIST_OF STRING list of modifiers to control comparison; allows you to ignore case and blank spaces
Comparison modifier Description
IGN_CASE ignore case, perform case insensitive comparison
IGN_BLANK ignore blank, white space in string comparison
Chapter 4 Master Rule Language (MRL) reference 161
Time stamp functions
has_substring/3 example
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.
Time stamp functions
time_stamp/1— retrieve the current time
Use time_stamp/1 to retrieve the current system time as a time stamp in $TIME.
time_stamp/1 example
time_stamp_to_cim/2 — convert a time stamp to CIM (Common Information Model) format
select [event_handle,CLASS,msg] from EVENT where [has_substring([$THIS.mc_object_class,$THIS.mc_tool_class],NGP,[IGN_CASE]) ] END
time_stamp($TIME)$TIME=time_stamp()
Table 124 time_stamp/1 arguments
Argument Mode Type Description
$TIME output INTEGER time stamp for the current time
$TM = time_stamp();
time_stamp_to_cim($TIME,$CIM)$CIM=time_stamp_to_cim($TIME)
Table 125 time_stamp_to_cim/2 arguments
Argument Mode Type Description
$TIME input INTEGER specifies the time stamp to be converted
$CIM output STRING time stamp in CIM format
162 BMC Knowledge Base Development Reference Guide
Time stamp functions
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:
time_stamp_to_cim/2 example
time_stamp_to_str/3 — convert a time stamp to a specified format
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.
YYYY Year (including century)
MM Month (1..12)
DD Day of month (1..31)
hh Hour (0..23)
mm Minutes (0..59)
ss Seconds (0..61) (value >59 in case of leap seconds)
uuuuuu Micro-seconds (0..999999)
+ Time zone offset direction from UTC (+ or -)
zzz Time zone offset from UTC in minutes
$CIM = time_stamp_to_cim(time_stamp());
time_stamp_to_str($TIME,$FORMAT,$STR)$STR=time_stamp_to_str($TIME,$FORMAT)
Table 126 time_stamp_to_str/3 arguments
Argument Mode Type Description
$TIME input INTEGER specifies the time stamp to be converted
$FORMAT input STRING specifies the format for the time stamp
$STR output STRING time stamp in specified format
Chapter 4 Master Rule Language (MRL) reference 163
Time stamp functions
time_stamp_to_str/3 example
The current time is formatted in the appropriate date and time representation for the current locale.
time_stamp_to_str/2 — convert a time stamp to the default DateFormat format
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
The current time is formatted as specified in DateFormat. The default value for DateFormat is CIM.
time_extract/3 — retrieve fields from a time stamp
time_stamp_to_str(time_stamp(),’%c’,$TM);
time_stamp_to_str($TIME,$STR)$STR=time_stamp_to_str($TIME)
Table 127 time_stamp_to_str/2 arguments
Argument Mode Type Description
$TIME input INTEGER specifies the time stamp to be converted
$STR output STRING time stamp in the specified format
time_stamp_to_str(time_stamp(),$TM);
time_extract($TIME,$FLDS,$VALS)$VALS=time_extract($TIME,$FLDS)
Table 128 time_extract/3 arguments
Argument Mode Type Description
$TIME input INTEGER specifies the time stamp from which a field or list of fields are to be retrieved
164 BMC Knowledge Base Development Reference Guide
Time stamp functions
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:
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
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-Feb-2007 at 9:15:20, $DT would be 20070206 and $TM would be 91520.
$FLDS input ■ STRING■ LIST_OF STRING
specifies the field or list of fields to be retrieved
$VALS output ■ INTEGER■ LIST_OF INTEGER
retrieved field value or list of retrieved field values
date Date part as an integer of the form YYYYMMDD
time Time part as an integer of the form HHMMSS
year Year (including century)
month Month (1..12)
day Day of month (1..31)
wday Day of week (0..6, 0=Sunday)
yday Day of year (1..366)
hour Hour (0..23)
min Minutes (0..59)
sec Seconds (0..61) (value >59 in case of leap seconds)
time_extract($E.date_reception,[date,time],[$DT,$TM]);
Table 128 time_extract/3 arguments
Argument Mode Type Description
Chapter 4 Master Rule Language (MRL) reference 165
Time stamp functions
str_to_time_stamp/3 — convert a string to a time stamp
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:
■ 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.
str_to_time_stamp($STR,$FORMAT,$TIME)$TIME=str_to_time_stamp($STR,$FORMAT)
Table 129 str_to_time_stamp/3 arguments
Argument Mode Type Description
$STR input STRING specifies a time stamp represented as text
$FORMAT input STRING specifies the format to which the time stamp is to be converted
$TIME output INTEGER time stamp in internal numeric form
166 BMC Knowledge Base Development Reference Guide
List operations
str_to_time_stamp/3 example
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
Use listlen/2 to determine the length of the list $LIST and return the length (in characters) in the $LEN argument.
listlen/2 example
listgetelt/3 — retrieve a list element located at a specified position within a list
str_to_time_stamp($E.date,’%c’,$TM);
listlen($LIST,$LEN)$LEN=listlen($LIST)
Table 130 listlen/2 arguments
Argument Mode Type Description
$LIST input LIST_OF ANY specifies the list for which the length is to be determined
$LEN output INTEGER length of list
$CNT_BAD_SLOTS=listlen($E.mc_bad_slot_names);
listgetelt($LIST,$POS,$ELEM)$ELEM=listgetelt($LIST,$POS)
Table 131 listgetelt/3 arguments
Argument Mode Type Description
$LIST input LIST_OF ANY specifies the list from which the element in the specified location is to be retrieved
Chapter 4 Master Rule Language (MRL) reference 167
List operations
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
listmember/2 — verify that an element is included in a list
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
listdelete/3 — remove all occurrences of an element from a list
$POS input INTEGER specifies of the position of requested element
$ELEM output ANY element at the specified position in list
$BAD_SLOT2=listgetelt($E.mc_bad_slot_names,2);
listmember($LIST,$ELEM)
Table 132 listmember/2 arguments
Argument Mode Type Description
$LIST input LIST_OF ANY specifies the list in which the presence of an element is to be verified
$ELEM input ANY specifies the element to be searched for within the list
if ( listmember($E.mc_bad_slot_names,my_slot) ) ...
listdelete($LIST1,$ELEM,$LIST)$LIST=listdelete($LIST1,$ELEM)
Table 131 listgetelt/3 arguments
Argument Mode Type Description
168 BMC Knowledge Base Development Reference Guide
List operations
Use listdelete/3 to remove all occurrences of element $ELEM from list $LIST1 and place the resulting list into $LIST.
listdelete/3 example
listappend/3 — concatenate two lists
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
listdisjoint/2 — verify that two lists do not have any common elements
Table 133 listdelete/3 arguments
Argument Mode Type Description
$LIST1 input LIST_OF ANY specifies the list from which the element is to be removed
$ELEM input ANY specifies the element to be removed
$LIST output LIST_OF ANY the list with the element removed from it
$BAD_SLOTS=listdelete($E.mc_bad_slot_names,my_slot);
listappend($LIST1,$LIST2,$LIST)$LIST=listappend($LIST1,$LIST2)
Table 134 listappend/3 arguments
Argument Mode Type Description
$LIST1 input LIST_OF ANY specifies the first list to be concatenated
$LIST2 input LIST_OF ANY specifies the second list to be concatenated
$LIST output LIST_OF ANY concatenation of first and second list
$BAD_SLOTS=listappend($E.mc_bad_slot_names,$E.mc_bad_slot_values);
listdisjoint($LIST1,$LIST1)
Chapter 4 Master Rule Language (MRL) reference 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
listintersect/3 — determine the common elements of two lists
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.
Table 135 listdisjoint/2 arguments
Argument Mode Type Description
$LIST1 input LIST_OF ANY specifies the first list to be compared
$LIST2 input LIST_OF ANY specifies the second list to be compared with the first list
if ( listdisjoint($E.mc_bad_slot_names,[my_slot1,my_slot2]) ) ...
listintersect($LIST1,$LIST2,$LIST)$LIST=listintersect($LIST1,$LIST2)
Table 136 listintersect/3 arguments
Argument Mode Type Description
$LIST1 input LIST_OF ANY specifies the first list to be compared
$LIST2 input LIST_OF ANY specifies the second list to be compared with the first list
$LIST output LIST_OF ANY list of the common elements of $LIST1 and $LIST2
170 BMC Knowledge Base Development Reference Guide
List operations
listintersect/3 example
listunion/3 — determine the union of two lists
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]
would be this list:$LIST=[a,b,a,c,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
listsubtract/3 — remove the elements that occur in one list from another list
$MY_BAD_SLOTS=listintersect($E.mc_bad_slot_names,[my_slot1,my_slot2]);
listunion($LIST1,$LIST2,$LIST)$LIST=listunion($LIST1,$LIST2)
Table 137 listunion/3 arguments
Argument Mode Type Description
$LIST1 input LIST_OF ANY specifies the first list to be compared
$LIST2 input LIST_OF ANY specifies the second list to be compared with the first list
$LIST output LIST_OF ANY union of both lists
$MY_BAD_SLOTS=listunion($E.mc_bad_slot_names,[my_slot1,my_slot2]);
listsubtract($LIST1,$LIST2,$LIST)$LIST=listsubtract($LIST1,$LIST2)
Chapter 4 Master Rule Language (MRL) reference 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
listremdup/2 — remove duplicate elements from a list
Use listremdup/2 to construct a new list $LIST that contains all the elements from list $LIST1 without duplicates.
listremdup/2 example
listwalk/2 — execute instructions against each element in a list
Table 138 listsubtract/3 arguments
Argument Mode Type Description
$LIST1 input LIST_OF ANY specifies the list from which elements are to be removed
$LIST2 input LIST_OF ANY specifies the list of elements that are to be removed from $LIST1
$LIST output LIST_OF ANY list resulting from removing the elements of $LIST2 from $LIST1
$MY_BAD_SLOTS=listsubtract($E.mc_bad_slot_names,[my_slot1,my_slot2]);
listremdup($LIST1,$LIST)$LIST=listremdup($LIST1)
Table 139 listremdup/2 arguments
Argument Mode Type Description
$LIST1 input LIST_OF ANY specifies the list from which duplicate elements are to be removed
$LIST output LIST_OF ANY list without duplicate elements
$MY_BAD_SLOTS=listremdup($E.mc_bad_slot_names);
listwalk($LIST,$ELEM)$ELEM=listwalk($LIST)
172 BMC Knowledge Base Development Reference Guide
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
The msg slot is filled with the sequence of bad slot names.
add_to_list/2 — add an element at the beginning of a list slot
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.
Table 140 listwalk/2 arguments
Argument Mode Type Description
$LIST input LIST_OF ANY specifies the list for which each element is to be executed against
$ELEM output ANY elements from the list against which instructions are to be executed
$E.msg = ’Bad slot names:’;listwalk($E.mc_bad_slot_names,$SLTNM);concat([$E.msg,’ ’,$SLTNM],$E.msg);
add_to_list($ELEM,$LISTSLOT)
Table 141 add_to_list/2 arguments
Argument Mode Type Description
$ELEM input ANY specifies the element to add to the list
$LISTSLOT input SLOTREF specifies the list slot to which to the element is to be added
Chapter 4 Master Rule Language (MRL) reference 173
Match table lookup primitives
add_to_list/2 example
rem_from_list/2 — remove the first occurrence of an element from a list slot
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
Match table lookup primitives
find_match/5 — find an entry in a match table and retrieve calculated values from it
add_to_list(my_slot,$E.mc_bad_slot_names);
rem_from_list($ELEM,$LISTSLOT)
Table 142 rem_from_list/2 arguments
Argument Mode Type Description
$ELEM input ANY specifies the element to be removed from the list
$LISTSLOT input SLOTREF specifies the list slot from which the first occurrence of $ELEM is to be removed
rem_from_list(my_slot,$E.mc_bad_slot_names);
find_match($TBLNAME,$TAG,$VALUES,$OBJECTS,$RESULTS)$RESULTS=find_match($TBLNAME,$TAG,$VALUES,$OBJECTS)
Table 143 find_match/5 arguments
Argument Mode Type Description
$TBLNAME input STRING specifies the class name of the match table
$TAG input STRING specifies the tag to identify the requested part of the match table
174 BMC Knowledge Base Development Reference Guide
Match table lookup primitives
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:
■ A match for the nth element has precedence over a match for the n+1’th 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.
Once a matching entry is found, output expressions, as defined in the output_expressions slot of the matching entry, are evaluated. The results of these evaluations are returned in $RESULTS. The resulting list must contain as many elements as there are output expressions in the entry.
$VALUES input LIST_OF STRING specifies the values to be matched as inputs
$OBJECTS input LIST_OF OBJECT specifies the objects to be used for evaluation of the output expressions
$RESULTS output LIST_OF STRING results of the output expression evaluation
Table 143 find_match/5 arguments
Argument Mode Type Description
Chapter 4 Master Rule Language (MRL) reference 175
Match table lookup primitives
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:
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.
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.
find_match_entry/4 — find an entry in a match table
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
find_match(BEM_MATCH_TABLE,t1,[$E.mc_object_class,$E.mc_object],[$E,$D],[$MSG,$SEV]);$E.msg = $MSG;$E.severity = $SEV;
find_match_entry($TBLNAME,$TAG,$VALUES,$ENTRY)$ENTRY=find_match_entry($TBLNAME,$TAG,$VALUES)
176 BMC Knowledge Base Development Reference Guide
Match table lookup primitives
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:
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.
This call will return a reference to the match table entry in $M.
Table 144 find_match_entry/4 arguments
Argument Mode Type Description
$TBLNAME input STRING specifies the class name of the match table
$TAG input STRING specifies the tag to identify the requested part of the match table
$VALUES input LIST_OF STRING specifies the values to be matched as inputs
$ENTRY output OBJECT matching entry
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
$M = find_match_entry(BEM_MATCH_TABLE,t1,[$E.mc_object_class,$E.mc_object]);
Chapter 4 Master Rule Language (MRL) reference 177
Match table lookup primitives
apply_match_entry/4 — obtain output values from a match table entry
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:
RESULTS($ENTRY,$VALUES,$OBJECTS,$RESULTS)$ENTRY=apply_match_entry($ENTRY,$VALUES,$OBJECTS)
Table 145 apply_match_entry/4 arguments
Argument Mode Type Description
$ENTRY input OBJECT specifies the match table entry
$VALUES input LIST_OF STRING specifies the values to be matched as inputs
$OBJECTS input LIST_OF OBJECT specifies the objects to be used for evaluation of output expressions
$RESULTS output LIST_OF STRING results of output expression evaluation
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 BMC Knowledge Base Development Reference Guide
Object slot manipulation
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.
This call will return a reference to the match table entry in $M.
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.
Object slot manipulation
get_list_slotvalues/3 — retrieve a list of slots from one or more objects
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.
$M = find_match_entry(BEM_MATCH_TABLE,t1,[$E.mc_object_class,$E.mc_object]);
apply_match_entry($M,[$E.mc_object_class,$E.mc_object],[$E,$D],[$MSG,$SEV]);$E.msg = $MSG;$E.severity = $SEV;
get_list_slotvalues($OBJECTS,$SLOTS,$VALUES)$VALUES=get_list_slotvlaues($OBJECTS,$SLOTS)
Table 146 get_list_slotvalues/3 arguments
Argument Mode Type Description
$OBJECTS input LIST_OF OBJECT specifies the list of objects from which a slot list is to be retrieved
$SLOTS input LIST_OF STRING
specifies the list of slots to be retrieved from $OBJECTS
$VALUES output LIST_OF_STRING
resulting list of slot values
Chapter 4 Master Rule Language (MRL) reference 179
Object slot manipulation
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
The list $VALUES will contain the mc_ueid and the status slot from the event object $E.
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.
set_list_slotvalues/3 — assign values to a list of slots for one or more objects
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.
$VALUES = get_list_slotvalues([$E,$D],[mc_ueid,status]);
$VALUES = get_list_slotvalues([$E,$D],[’$1.mc_ueid’,’$1.status’,’$2.mc_udid’]);
set_list_slotvalues($OBJECTS,$SLOTS,$VALUES)
Table 147 set_list_slotvalues/3 arguments
Argument Mode Type Description
$OBJECTS input LIST_OF OBJECT list of objects
$SLOTS input LIST_OF STRING list of desired slots
$VALUES input LIST_OF ANY list of slot values to assign
180 BMC Knowledge Base Development Reference Guide
Specific slot manipulation
set_list_slotvalues/3 example
The status slot of the event object $E is set to CLOSED, and its msg slot is set to done.
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.
Specific slot manipulation
class_path/2 — obtain the class hierarchy of a class
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
The variable $PATH will be [MC_CELL_ACTION_RESULT,MC_CELL_CONTROL,CORE_EVENT].
reset_default/1 — reset a slot to its default value
set_list_slotvalues([$E,$D],[status,msg],[CLOSED,done]);
set_list_slotvalues([$E,$D],[’$1.status’,’$1.msg’,’$2.name’],[CLOSED,done,john]);
class_path($CLASS,$PATH)$PATH=class_path($CLASS)
Table 148 class_path/2 arguments
Argument Mode Type Description
$CLASS input STRING specifies the name of the class for which the hierarchy is to be determined
$PATH output LIST_OF STRING list of class hierarchy names
class_path(MC_CELL_ACTION_RESULT,$PATH);
reset_default($SLOT)
Chapter 4 Master Rule Language (MRL) reference 181
Specific slot manipulation
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
ntadd/2 — add a note to an event
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
ntcnt/2 — count the notes attached to an event
Table 149 reset_default/1 arguments
Argument Mode Type Description
$SLOT input SLOTREF specifies the slot to be reset
reset_default($E.severity);
ntadd($EVENT,$SLOT)
Table 150 ntadd/2 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event to which a note will be added
$SLOT input STRING text to be added as the note
ntadd($E,’Event updated by rule’);
ntcnt($EVENT,$COUNT)
Table 151 ntcnt/2 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which notes are to be counted
$COUNT output INTEGER number of notes attached to event
182 BMC Knowledge Base Development Reference Guide
Specific slot manipulation
Use ntcnt/2 to count the notes that are attached to event $EVENT, in $COUNT.
ntcnt/2 example
ntget/5 — return the time stamp, author, and text of a note attached to an event
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
ntset/3 — modify the text of a note attached to an event
ntcnt($E,$NR_OF_NOTES);
ntget($EVENT,$SEQNR,$TIME,$AUTHOR,$TEXT)
Table 152 ntget/5 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which a note is to be retrieved
$SEQNR input INTEGER specifies the sequence number of the desired note
$TIME output INTEGER time stamp of the note
$AUTHOR output STRING author of the note
$TEXT output STRING text of the note
ntget($E,0,$TIME,$AUTHOR,$SLOT);
ntset($EVENT,$SEQNR,$TEXT)
Chapter 4 Master Rule Language (MRL) reference 183
Specific slot manipulation
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.
ntset/3 example
opadd/4 — add a policy operation to an event
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.
Table 153 ntset/3 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which the note text is to be modified
$SEQNR input INTEGER specifies the sequence number of the desired note
$TEXT input STRING specifies the new text of the note
NOTE Only the text of a note can be replaced. The time stamp and author cannot be modified.
ntset($E,0,’New explanation’);
opadd($EVENT,$POLICY,$ACTION,$ARGS)
Table 154 opadd/4 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event to which to add an operation
$POLICY input STRING specifies the policy name of the operation to be added
$ACTION input STRING specifies the action name of the operation
$ARGS input STRING specifies the arguments for operation action
184 BMC Knowledge Base Development Reference Guide
Specific slot manipulation
opadd/4 example
opadd/3 — add an operation to an event
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
opcnt/2 — count the operations of an event
Use opcnt/2 to count the operations that are attached to event $EVENT and return the number in $COUNT.
opadd($E,’Policy1’,’Data Enrichment’,’’);
opadd($EVENT,$ACTION,$ARGS)
Table 155 opadd/3 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event to which to add an operation
$ACTION input STRING specifies the action name of the operation
$ARGS input STRING specifies the arguments for operation action
opadd($E,’AcknowledgeEvent’,’’);
opcnt($EVENT,$COUNT)
Table 156 opcnt/2 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which operations are to be counted
$COUNT output INTEGER number of operations attached to the event
Chapter 4 Master Rule Language (MRL) reference 185
Specific slot manipulation
opcnt/2 example
opget/7 — retrieve a policy operation of an event
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/6 — retrieve an operation of an event
opcnt($E,$NR_OF_OPS);
opget($EVENT,$SEQNR,$TIME,$AUTHOR,$POLICY,$ACTION,$ARGS)
Table 157 opget/7 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which to retrieve an operation
$SEQNR input INTEGER specifies the sequence number of the desired operation
$TIME output INTEGER time stamp of the operation
$AUTHOR output STRING author of the operation
$POLICY output STRING policy name of the operation
$ACTION output STRING action name of the operation
$ARGS output STRING arguments for the operation action
opget($E,0,$TIME,$AUTHOR,$POLICY,$ACTION,$ARGS);
opget($EVENT,$SEQNR,$TIME,$AUTHOR,$ACTION,$ARGS)
186 BMC Knowledge Base Development Reference Guide
Specific slot manipulation
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_time/3 — retrieve the time stamp of an operation of an event
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.
Table 158 opget/6 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which to retrieve an operation
$SEQNR input INTEGER specifies the sequence number of the desired operation
$TIME output INTEGER time stamp of the operation
$AUTHOR output STRING author of the operation
$ACTION output STRING action name of the operation
$ARGS output STRING arguments for the operation action
opget($E,0,$TIME,$AUTHOR,$ACTION,$ARGS);
$TIME=opget_time($EVENT,$SEQNR)
Table 159 opget_time/3 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which to retrieve an operation
$SEQNR input INTEGER specifies the sequence number of the desired operation
$TIME output INTEGER time stamp of operation
Chapter 4 Master Rule Language (MRL) reference 187
Specific slot manipulation
opget_time/3 example
opget_author/3 — retrieve the author of an operation of an event
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
opget_action/3 — retrieve the action name of an operation of an event
Use opget_action/3 to obtain the action name of operation $SEQNR that is attached to event $EVENT and return the value in $ACTION.
$TIME=opget_time($E,0);
$AUTHOR=opget_author($EVENT,$SEQNR)
Table 160 opget_author/3 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which to retrieve an operation
$SEQNR input INTEGER specifies the sequence number of the desired operation
$AUTHOR output STRING author of the operation
$AUTHOR=opget_author($E,0);
$ACTION=opget_action($EVENT,$SEQNR)
Table 161 opget_action/3 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which to retrieve an operation
$SEQNR input INTEGER specifies the sequence number of the desired operation
$ACTION output STRING action name of the operation
188 BMC Knowledge Base Development Reference Guide
Specific slot manipulation
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
opget_args/3 — retrieve the argument list of an operation of an event
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
opset/5 — modify the policy name, action, and arguments of an operation of an event
$ACTION=opget_action($E,0);
$ARGS=opget_args($EVENT,$SEQNR)
Table 162 opget_args/3 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which to retrieve an operation
$SEQNR input INTEGER specifies the sequence number of the desired operation
$ARGS output STRING arguments for the operation action
$ARGS=opget_args($E,0);
opset($EVENT,$SEQNR,$POLICY,$ACTION,$ARGS)
Chapter 4 Master Rule Language (MRL) reference 189
Specific slot manipulation
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.
opset/5 example
opset/4 — modify the action and arguments of an operation of an event
Table 163 opset/5 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which an operation is to be modified
$SEQNR input INTEGER specifies the sequence number of the desired operation
$POLICY input STRING new policy name of the operation
$ACTION input STRING new action name of the operation
$ARGS input STRING new arguments for the operation action
NOTE The time stamp and author of an operation cannot be modified.
opset($E,0,’Policy2’,’Data Enrichment’,’’);
opset($EVENT,$SEQNR,$ACTION,$ARGS)
Table 164 opset/4 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event for which an operation is to be modified
$SEQNR input INTEGER specifies the sequence number of the desired operation
$ACTION input STRING new action name of the operation
$ARGS input STRING new arguments for the operation action
190 BMC Knowledge Base Development Reference Guide
Object relation functions
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.
opset/4 example
Object relation functions
relate/1 — establish the relation of an event to a source event
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.
NOTE The time stamp and author of an operation cannot be modified.
opset($E,0,’CloseEvent’,’’);
relate($EVENT)
Table 165 relate/1 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event to be related to a source event
Chapter 4 Master Rule Language (MRL) reference 191
Object relation functions
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:
When a trouble ticket event is received, the following rule will relate it to its source event:
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.
unrelate/1 — remove a relation of a related event to a source event
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.
MC_EVENT_RELATION; type=tt_HD; class=HD_TROUBLE_TICKET; END
refine HD_trouble_ticket_relate : HD_TROUBLE_TICKET($E){ relate($E); }END
unrelate($EVENT)
Table 166 unrelate/1 arguments
Argument Mode Type Description
$EVENT input OBJECT specifies the event to be unrelated from a source event
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 BMC Knowledge Base Development Reference Guide
Operation environment inquiry
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:
When a trouble ticket event is received, the following rule will relate it to its source event:
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:
Operation environment inquiry
cellinfo/2 — retrieve cell-specific information
MC_EVENT_RELATION; type=tt_HD; class=HD_TROUBLE_TICKET; END
refine HD_trouble_ticket_relate : HD_TROUBLE_TICKET($E){ relate($E); }END
execute HD_trouble_ticket_unrelate : HD_TROUBLE_TICKET($E)when $E.status != OPEN { unrelate($E); }END
cellinfo($FIELD,$INFO)$INFO=cellinfo($FIELD)
Table 167 cellinfo/2 arguments
Argument Mode Type Description
$FIELD input STRING specifies the desired information item to be retrieved
$INFO output STRINGLIST_OF STRING
retrieved cell information
Chapter 4 Master Rule Language (MRL) reference 193
Operation environment inquiry
Use cellinfo/2 to obtain information item specified in $FIELD and return the information in $INFO.
The following information fields are defined:
cellinfo/2 example
cellcontrol/1 — perform a cell control command
Use cellcontrol/1 to perform the control command specified in $COMMAND.
HomeDir home directory of the cell
HostName name of the host machine on which cell is running
IPAddress IP address of the host machine on which cell is running
Platform platform identifier of the host machine on which cell is running
CellName name of the cell
CellRelease release version of the cell
CellBuild build number of this version of the cell
CellDate build date of this version of the cell
Param value of configuration parameter Param
LogDir log directory of the cell
Location IP address or port number of the cell service
TmpDir temporary directory of the cell
KBDir KB directory of the cell
DirFile directory file (mcell.dir) of the cell
ConfigFile configuration file of the cell
TraceDestination list of defined trace destination files (of the type LIST_OF STRING)
$E.mc_host = cellinfo(HostName);
cellcontrol($COMMAND)
Table 168 cellcontrol/1 arguments
Argument Mode Type Description
$COMMAND input STRING control command to be performed
194 BMC Knowledge Base Development Reference Guide
Operation environment inquiry
The following commands are defined:
cellcontrol/1 example
kbversion/2 — retrieve Knowledge Base module version information
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.
stop terminate the cell normally
shutdown terminate the cell as quickly as possible
standby switch operation mode to standby
pause switch operation mode to pause (no longer accepting new events)
start switch operation mode back to normal
reload reload the cell configuration
statbld initiate a state build immediately
cellcontrol(pause);
kbversion($MODULE,$VERSION)$VERSION=kbversion($MODULE)
Table 169 kbversion/2 arguments
Argument Mode Type Description
$MODULE input STRING specifies identifier for the KB module
$VERSION output STRING KB module version information
Chapter 4 Master Rule Language (MRL) reference 195
Operation environment inquiry
kbversion/2 example
kbversion/1 — retrieve global Knowledge Base module version information
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
get_env/2 — retrieve the value of an environment variable
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.
kbversion(TroubleTicketing,$VERSION);
kbversion($VERSION)$VERSION=kbversion()
Table 170 kbversion/1 arguments
Argument Mode Type Description
$VERSION output STRING KB module version information
kbversion($VERSION);
get_env($ENVVAR,$VALUE)$VALUE=get_env($ENVVAR)
Table 171 get_env/2 arguments
Argument Mode Type Description
$ENVVAR input STRING specifies the environment variable name for which the value is to be retrieved
$VALUE output STRING value of the environment variable
196 BMC Knowledge Base Development Reference Guide
Propagation
get_env/2 example
Propagation
send_to/2 — send an event to another cell or gateway
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/3 — send an event modification to another cell or gateway
$HOME = get_env(HOME);
send_to($DEST,$EVENT)
Table 172 send_to/2 arguments
Argument Mode Type Description
$DEST input ■ STRING■ LIST_OF STRING
specifies a single destination or a list of possible destinations for the event
$EVENT input OBJECT specifies the event to send
send_to([Cell2,Cell3],$E);
send_to($DEST,$EVENT,$SLOTS)
Table 173 send_to/3 arguments
Argument Mode Type Description
$DEST input ■ STRING■ LIST_OF STRING
specifies a single destination or a list of possible destinations for the event
$EVENT input OBJECT specifies the event to send
$SLOTS input LIST_OF STRING specifies a list of modified slots to send
Chapter 4 Master Rule Language (MRL) reference 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_ext/4 — send an extended event to another cell or gateway
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.
send_to([Cell2,Cell3],$E,[status,severity]);
WARNING Do not use send_to_ext to change the values of slots within the current event. This is not supported and may cause inconsistent and undesired results. For example, you cannot change the severity or the mc_ueid of the current event using this function.
send_to_ext($DEST,$EVENT,$SLOTS,$VALS)
Table 174 send_to_ext/4 arguments
Argument Mode Type Description
$DEST input ■ STRING■ LIST_OF STRING
specifies a single destination or a list of possible destinations for the event
$EVENT input OBJECT specifies the event to send
$SLOTS input LIST_OF STRING specifies a list of extended slot names to send
$VALS input LIST_OF STRING specifies a list of extended slot values to send
198 BMC Knowledge Base Development Reference Guide
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
propagated_to/3—verify that an event has been propagated to a specified destination
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.
send_to_ext([Cell2,Cell3],$E,[slot1,slot2],[value1,value2]);
propagated_to($Object,$DestNM,$ID)$ID = propagated_to($Object,$DestNM)
Table 175 propagated_to/3 arguments
Argument Mode Type Description
$Object input OBJECT specifies the handle of the object that may or may not have been propagated to the specified destination $DestNM
$DestNM input STRING specifies the destination that you want to search to determine whether or not the specified object has been propagated
$ID output INTEGER identifier of the object at the specified destination. $ID output is 0 if the object was not propagated to the specified destination.
mquery -n CellName -a EVENT -w 'propagated_to($THIS,dest) > 0'
Chapter 4 Master Rule Language (MRL) reference 199
Service model inquiry
Service model inquiry
smcomps/5 — search for certain Service Model 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.
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.
WARNING This is an advanced primitive and can possibly cause the cell to become unresponsive for a certain time when performing a in-depth search of a large Service Model.
smcomps($PARMNAMES,$PARMVALS,$COMPS1,$SHADOWS,$COMPS2)
Table 176 smcomps/5 arguments
Argument Mode Type Description
$PARMNAMES input LIST_OF STRING list of parameter names
$PARMVALS input LIST_OF STRING list of parameter values
$COMPS1 output LIST_OF OBJECT list of primary search components
$SHADOW output LIST_OF OBJECT list of shadow components
$COMPS2 output LIST_OF OBJECT list of secondary search components
NOTE You can also retrieve root causes using MC_SM_ROOT_CAUSE instead of smcomps.
200 BMC Knowledge Base Development Reference Guide
Service model inquiry
The two parameter lists—the $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 order—determines the search behavior. Available parameter names and possible values are:
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:
■ 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:
■ 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.
comp mc_udid of the focus Service Model component data object. Default value is 0; therefore you must enter a valid value for this parameter.
dir 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 T | F where T=True and F=False. Default value is F (extended search is not turned on).
leaf T | F where T=True and F=False. Default value is F (leaf nodes are not required).
type component class name. Default is the BMC_BaseElement class.
Chapter 4 Master Rule Language (MRL) reference 201
License key functions
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
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.
License key functions
key_version/2 — retrieve the version from a license key
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.
smcomps([comp,dir,impact,events,leaf],[comp123,i,t,T,T],$COMPS,$SHADOW,$C2);listwalk($COMPS,$COMP);concat([$MSG,' ',$COMP.mc_udid],$MSG);
key_version($KEY,$VERSION)
Table 177 key_version/2 arguments
Argument Mode Type Description
$KEY input STRING specifies the license key
$VERSION output INTEGER version of key
202 BMC Knowledge Base Development Reference Guide
License key functions
key_version/2 example
key_verify/2 — validate and retrieve fields from a license key
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
key_verify/3 — validate and retrieve fields from a license key
key_version($KEY,$VERSION);if ( $VERSION == 1 ) then ...
key_verify($KEY,$FIELDS)
Table 178 key_verify/2 arguments
Argument Mode Type Description
$KEY input STRING specifies the license key
$FIELDS output LIST_OF STRING list of fields from key
if ( key_verify($KEY,[$FLD1,$FLD2]) ) then ...
key_verify($KEY,$FIELDS,$VALID)
Table 179 key_verify/3 arguments (part 1 of 2)
Argument Mode Type Description
$KEY input STRING specifies the license key
Chapter 4 Master Rule Language (MRL) reference 203
Time frame operations
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
Time frame operations
tf_active/1 — verify if one or more time frames are active
Use tf_active/1 to determine whether the time frame(s) $TIMEFRAME is active at the current moment.
$FIELDS output LIST_OF STRING list of fields from key
$VALID output INTEGER key validity (0=invalid, 1=valid)
key_verify($KEY,[$FLD1,$FLD2],$VALID);$LICDATA.key_validity = $VALID;
tf_active($TIMEFRAME)
Table 180 tf_active/1 arguments
Argument Mode Type Description
$TIMEFRAME input ■ STRING■ LIST_OF STRING■ OBJECT■ LIST_OF OBJECT
■ time frame name■ list of time frame names■ time frame object■ list of time frame objects
Table 179 key_verify/3 arguments (part 2 of 2)
Argument Mode Type Description
204 BMC Knowledge Base Development Reference Guide
Time frame operations
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
tf_active/2 — verify if one or more time frames are active at a given time
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
tf_udid_active/1 — verify if one or more time frames specified by mc_udid are active at the current time
if ( tf_active($TF) ) then ...
tf_active($TIMEFRAME,$TIME)
Table 181 tf_active/2 arguments
Argument Mode Type Description
$TIMEFRAME input ■ STRING■ LIST_OF STRING■ OBJECT■ LIST_OF OBJECT
■ time frame name■ list of time frame names■ time frame object■ list of time frame objects
$TIME input INTEGER time to check activity
if ( tf_active($TF,$TIME) ) then ...
tf_udid_active($TIMEFRAME)
Chapter 4 Master Rule Language (MRL) reference 205
Time frame operations
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
tf_udid_active/2 — verify if one or more time frames specified by mc_udid are active at a specified time
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.
Table 182 tf_udid_active/1 arguments
Argument Mode Type Description
$TIMEFRAME input ■ STRING■ LIST_OF STRING
■ time frame mc_udid■ mc_udid list for multiple time frames
if ( tf_udid_active([’TF.001’,’TF.002’]) ) then ...
tf_udid_active($TIMEFRAME,$TIME)
Table 183 tf_udid_active/2 arguments
Argument Mode Type Description
$TIMEFRAME input ■ STRING■ LIST_OF STRING
■ time frame mc_udid■ mc_udid list for multiple time frames
$TIME input INTEGER specified time to check activity
206 BMC Knowledge Base Development Reference Guide
Time frame operations
tf_udid_active/2 example
tf_current_start/2 — obtain the start time of the current active interval of a time frame
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
tf_current_start/3 — obtain the start time of the active interval of a time frame at a specified 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.
if ( tf_udid_active([’TF.001’,’TF.002’],$TIME) ) then ...
tf_current_start($TIMEFRAME,$START)$START=tf_current_start($TIMEFRAME)
Table 184 tf_current_start/2 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$START output INTEGER start time of current active interval
$START = tf_current_start($TF);
tf_current_start($TIMEFRAME,$TIME,$START)$START=tf_current_start($TIMEFRAME,$TIME)
Table 185 tf_current_start/3 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$TIME input INTEGER specifies the time for the active interval
$START output INTEGER start time of active interval at given time
Chapter 4 Master Rule Language (MRL) reference 207
Time frame operations
tf_current_start/3 example
tf_current_end/2 — obtain the end time of the current active interval of a time frame
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
tf_current_end/3 — obtain the end time of the active interval of a time frame at a specified 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.
$START = tf_current_start($TF,$TM);
tf_current_end($TIMEFRAME,$END)$END=tf_current_end($TIMEFRAME)
Table 186 tf_current_end/2 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$END output INTEGER end time of current active interval
$END = tf_current_end($TF);
tf_current_end($TIMEFRAME,$TIME,$END)$END=tf_current_end($TIMEFRAME,$TIME)
Table 187 tf_current_end/3 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$TIME input INTEGER specifies the time for the active interval
$END output INTEGER end time of active interval at given time
208 BMC Knowledge Base Development Reference Guide
Time frame operations
tf_current_end/3 example
tf_current_interval/2 — obtain the start and end time of the current active interval of a time frame
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/3 — obtain the start and end time of the active interval of a time frame at a given time
$END = tf_current_end($TF,$TM);
tf_current_interval($TIMEFRAME,$INTV)$INTV=tf_current_interval($TIMEFRAME)
Table 188 tf_current_interval/2 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$INTV output LIST_OF INTEGER start and end time of current active interval
tf_current_interval($TF,[$START,$END]);
tf_current_interval($TIMEFRAME,$TIME,$INTV)$INTV=tf_current_interval($TIMEFRAME,$TIME)
Table 189 tf_current_interval/3 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$TIME input INTEGER specifies the time for the active interval
$INTV output LIST_OF INTEGER start and end time of active interval at the specified time
Chapter 4 Master Rule Language (MRL) reference 209
Time frame operations
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_prev_start/2 — obtain the start time of the previous active interval of a time frame
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
tf_prev_start/3 — obtain the start time of the previous active interval of a time frame at a given time
tf_current_interval($TF,$TM,[$START,$END]);
tf_prev_start($TIMEFRAME,$START)$START=tf_prev_start($TIMEFRAME)
Table 190 tf_prev_start/2 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$START output INTEGER start time of previous active interval
$START = tf_prev_start($TF);
tf_prev_start($TIMEFRAME,$TIME,$START)$START=tf_prev_start($TIMEFRAME,$TIME)
210 BMC Knowledge Base Development Reference Guide
Time frame operations
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
tf_prev_end/2 — obtain the end time of the previous active interval of a time frame
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.
Table 191 tf_prev_start/3 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$TIME input INTEGER specifies the time for the active interval
$START output INTEGER start time of previous active interval at the specified time
$START = tf_prev_start($TF,$TM);
tf_prev_end($TIMEFRAME,$END)$END=tf_prev_end($TIMEFRAME)
Table 192 tf_prev_end/2 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$END output INTEGER end time of previous active interval
Chapter 4 Master Rule Language (MRL) reference 211
Time frame operations
tf_prev_end/2 example
tf_prev_end/3 — obtain the end time of the previous active interval of a time frame at a given 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
tf_prev_interval/2 — obtain the start and end time of the previous active interval of a time frame
Use tf_prev_interval/2 to obtain the start and end time of the previous active interval of time frame $TIMEFRAME in $INTV.
$END = tf_prev_end($TF);
tf_prev_end($TIMEFRAME,$TIME,$END)$END=tf_prev_end($TIMEFRAME,$TIME)
Table 193 tf_prev_end/3 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$TIME input INTEGER specifies the time for the active interval
$END output INTEGER end time of previous active interval at the specified time
$END = tf_prev_end($TF,$TM);
tf_prev_interval($TIMEFRAME,$INTV)$INTV=tf_prev_interval($TIMEFRAME)
Table 194 tf_prev_interval/2 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$INTV output LIST_OF INTEGER start and end time of the previous active interval
212 BMC Knowledge Base Development Reference Guide
Time frame operations
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/3 — obtain the start and end time of the previous active interval of a time frame at a specified 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_next_start/2 — obtain the start time of the next active interval of a time frame
tf_prev_interval($TF,[$START,$END]);
tf_prev_interval($TIMEFRAME,$TIME,$INTV)$INTV=tf_prev_interval($TIMEFRAME,$TIME)
Table 195 tf_prev_interval/3 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$TIME input INTEGER specifies the time for the active interval
$INTV output LIST_OF INTEGER start and end time of previous active interval at given time
tf_prev_interval($TF,$TM,[$START,$END]);
tf_next_start($TIMEFRAME,$START)$START=tf_next_start($TIMEFRAME)
Chapter 4 Master Rule Language (MRL) reference 213
Time frame operations
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
tf_next_start/3 — obtain the start time of the next active interval of a time frame at a given 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
tf_next_end/2 — obtain the end time of the next active interval of a time frame
Table 196 tf_next_start/2 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$START output INTEGER start time of next active interval
$START = tf_next_start($TF);
tf_next_start($TIMEFRAME,$TIME,$START)$START=tf_next_start($TIMEFRAME,$TIME)
Table 197 tf_prev_start/3 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$TIME input INTEGER specifies the time for the active interval
$START output INTEGER start time of next active interval at given time
$START = tf_next_start($TF,$TM);
tf_next_end($TIMEFRAME,$END)$END=tf_next_end($TIMEFRAME)
214 BMC Knowledge Base Development Reference Guide
Time frame operations
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
tf_next_end/3 — obtain the end time of the next active interval of a time frame at a specified 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
tf_next_interval/2 — obtain the start and end time of the next active interval of a time frame
Table 198 tf_next_end/2 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$END output INTEGER end time of next active interval
$END = tf_next_end($TF);
tf_next_end($TIMEFRAME,$TIME,$END)$END=tf_next_end($TIMEFRAME,$TIME)
Table 199 tf_next_end/3 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$TIME input INTEGER specifies the time for the active interval
$END output INTEGER end time of next active interval at the specified time
$END = tf_next_end($TF,$TM);
tf_next_interval($TIMEFRAME,$INTV)$INTV=tf_next_interval($TIMEFRAME)
Chapter 4 Master Rule Language (MRL) reference 215
Time frame operations
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/3 — obtain the start and end time of the next active interval of a time frame at a 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.
Table 200 tf_next_interval/2 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$INTV output LIST_OF INTEGER start and end time of next active interval
tf_next_interval($TF,[$START,$END]);
tf_next_interval($TIMEFRAME,$TIME,$INTV)$INTV=tf_next_interval($TIMEFRAME,$TIME)
Table 201 tf_next_interval/3 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$TIME input INTEGER specifies the time for the active interval
$INTV output LIST_OF INTEGER start and end time of the next active interval at specified time
216 BMC Knowledge Base Development Reference Guide
Time frame operations
tf_next_interval/3 example
tf_duration/3 — calculate the duration of all active intervals of a time frame from a specified start time to the current time
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
tf_duration/4 — calculate the duration of all active intervals of a time frame during a specified time period
tf_next_interval($TF,$TM,[$START,$END]);
tf_duration($TIMEFRAME,$START,$DURATION)$DURATION=tf_duration($TIMEFRAME,$START)
Table 202 tf_duration/3 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$START input INTEGER specifies the start of the period during which active interval duration is to be calculated
$DURATION output INTEGER total active interval duration from the time specified in $START until the current time
$DURATION = tf_duration($TF,$TM0);
tf_duration($TIMEFRAME,$START,$END,$DURATION)$DURATION=tf_duration($TIMEFRAME,$START,$END)
Table 203 tf_duration/4 arguments
Argument Mode Type Description
$TIMEFRAME input OBJECT specifies the time frame object
$START input INTEGER specifies the start of the period during which active interval duration is to be calculated
Chapter 4 Master Rule Language (MRL) reference 217
Object creation and deletion
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
Object creation and deletion
generate_event/2 — generate a 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.
$END input INTEGER specifies the end of the period during which active interval duration is to be calculated
$DURATION output INTEGER total active interval duration over the specified period
$DURATION = tf_duration($TF,$TM0,$TM1);
NOTE This primitive cannot be used in refine, filter, regulate, or propagate rules.
generate_event($CLASS,$SLOTS)
Table 204 generate_event/2 arguments
Argument Mode Type Description
$CLASS input STRING specifies the event class name
$SLOTS input LIST_OF ANY specifies the list of slot settings to be included in the new event
Table 203 tf_duration/4 arguments
Argument Mode Type Description
218 BMC Knowledge Base Development Reference Guide
Object creation and deletion
generate_event/2 example
new_data/3 — create a new data 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
remove_data/1 — delete a data object
generate_event(CUSTOM_EVENT,[severity=INFO,msg=$MSG]);
NOTE This primitive cannot be used in filter, regulate, or propagate rules.
new_data($OBJECT,$CLASS,$SLOTS)
Table 205 new_data/3 arguments
Argument Mode Type Description
$CLASS input STRING specifies the data class for the new object
$SLOTS input LIST_OF ANY specifies the list of slot settings for the new object
$OBJECT output OBJECT new data object
new_data($DATA,CUSTOM_DATA,[mc_udid=$ID,myslot=$VAL]);
NOTE This primitive cannot be used in refine, filter, regulate, or propagate rules.
remove_data($OBJECT)
Chapter 4 Master Rule Language (MRL) reference 219
Specific rule-based functions
Use remove_data/1 to delete the data object $OBJECT.
remove_data/1 example
Specific rule-based functions
drop_new/0 — drop a new event object
Use drop_new/0 to drop the newly received event, being processed in a new rule.
Table 206 remove_data/1 arguments
Argument Mode Type Description
$OBJECT input OBJECT specifies the data object to be deleted
remove_data($DATA);
NOTE This primitive can only be used in new rules.
drop_new()
220 BMC Knowledge Base Development Reference Guide
Specific rule-based functions
drop_new/0 example
unset_cause/0 — break the cause-to-effect relationship from a correlate rule
Use unset_cause/0 to break the cause-to-effect relationship that is established by a correlate rule.
unset_cause/0 example
set_timer/3 — set a timer on an event object that will expire after a specified delay
new RepeatTick: MC_CELL_TICK($E)updates duplicate($U){$U.repeat_count = $U.repeat_count + 1;drop_new;}END
NOTE This primitive can only be used in correlate rules.
unset_cause()
correlate Corr1: EVENT($E) where ...with EVENT($C) where ......when $C.status == CLOSED{unset_cause;}END
NOTE This primitive cannot be used in refine, filter, regulate, or propagate rules.
set_timer($OBJECT,$DURATION,$INFO)
Chapter 4 Master Rule Language (MRL) reference 221
Specific rule-based functions
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
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
Table 207 set_timer/3 arguments
Argument Mode Type Description
$OBJECT input OBJECT specifies the event object
$DURATION input INTEGER specifies the duration until timer expiration, in seconds
$INFO input STRING specifies the information item as timer_info
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
NOTE This primitive cannot be used in refine, filter, regulate, or propagate rules.
set_timer_at($OBJECT,$TIME,$INFO)
222 BMC Knowledge Base Development Reference Guide
Specific rule-based functions
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/4 — set a timer on an event object that will expire at a specified time represented by a text string
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.
Table 208 set_timer_at/3 arguments
Argument Mode Type Description
$OBJECT input OBJECT specifies the event object
$TIME input INTEGER specifies the time stamp at which the timer will expire
$INFO input STRING specifies the information item as timer_info
set_timer_at($E,$EXPTM,EventExpired);
NOTE This primitive cannot be used in refine, filter, regulate, or propagate rules.
set_timer_at($OBJECT,$STR,$FORMAT,$INFO)
Table 209 set_timer_at/4 arguments
Argument Mode Type Description
$OBJECT input OBJECT specifies the event object
$STR input STRING specifies the time stamp in textual representation at which the timer will expire
$FORMAT input STRING specifies the format for the time stamp $STR
$INFO input STRING specifies the information item as timer_info
Chapter 4 Master Rule Language (MRL) reference 223
Specific rule-based functions
This is the same as:
set_timer_at/4 example
The variable $DATETIME should contain a time indication similar to 20070209 153010.
set_timer_at($OBJ,str_to_time_stamp($STR,$FORMAT),$INFO)
set_timer_at($E,$DATETIME,’%Y%m%d %H%M%S’,EventExpired);
224 BMC Knowledge Base Development Reference Guide
C h a p t e r 5
5 Event rulesRules and event management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Rule structure and syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
MRL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226MRL conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226General rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
MRL event selection clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Where clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Using clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Using_policy clause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Unless clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236When clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Body clause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Variables in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Dynamic data in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Global records in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Interfaces in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Interface instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Indexes in rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Using indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Compiling rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248Testing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249Tracing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Configuring rule tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249Customizing rule trace message headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Undefined events, processing errors, and deprecated slots . . . . . . . . . . . . . . . . . . . . 253Undefined events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Event processing errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255Using deprecated slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Chapter 5 Event rules 225
Rules and event management
Rules and event managementRules specify which events are selected for processing and then determine how they are processed. Rules differ from policies insofar as rules are manually edited, require more effort to implement, but provide more flexibility.
Rule structure and syntaxYou write rules using MRL and then compile and store them in the cell’s KB. For detailed information about MRL, see Chapter 4, “Master Rule Language (MRL) reference.”.
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:
■ 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 BMC Knowledge Base Development Reference Guide
General rule syntax
■ 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.
The compiler validates syntax on primitive arguments. For example, use of a SIMPLE type instead of a LIST will result in a compilation error.
■ 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.
General rule syntax
All rules, in general, have the same structure which includes the rule introduction, the event selection criteria, and the rule body.
The generic rule syntax presented in Figure 14 on page 228 shows the syntax objects that can appear in a rule, and Table 210 on page 228 describes those objects.
concat([this,is,a,quick,example],$CONCAT_STR);
Chapter 5 Event rules 227
General rule syntax
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
Table 210 Syntax object description (part 1 of 2)
Object Description
RuleType specifies the phase for which the rule is written
The rule types are:
■ 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 BMC Knowledge Base Development Reference Guide
General rule syntax
Event condition formula event condition formula (ECF) begins with <ClassName>
The ECF specifies the conditions that the event currently being processed must match for the rule to be evaluated. ClassName specifies the event class that the event must match. The class of the event instance can be a subclass of ClassName.
Note: To apply the rule to all incoming event instances, specify ClassName as EVENT
optional clause The optional clause is enclosed within the curly braces. It begins with { | using and ends before <RuleSpecific>.
This portion of the syntax contains a query clause that directs the rule engine to retrieve data or events from the dynamic data repository to be used in the remainder of the rule.
This example includes the Using clause qualified by an Unless clause.
The object that matches the specified conditions is retrieved by the Using query clause and can be used in the body of the rule.
If the query has no matches, then the Unless clause is applied.
The body of the rule (see below) is executed for every match to these queries when the optional keyword "ALL" is specified after the “using” keyword.
For more information about the use of clauses, see “MRL event selection clauses” on page 230.
{ } optional clause indicators (curly braces)
‘{‘ the actual character ‘{‘
| using {ALL} | unless> | using either {ALL} or unless
<EventVariableName> name of a variable representing an event
<ObjectVariableName> name of a variable representing an event or data
< BooleanExpression> an expression whose value is a boolean
<Call> an assignment or a primitive call<RuleSpecific> 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.
Table 210 Syntax object description (part 2 of 2)
Object Description
Chapter 5 Event rules 229
MRL event selection clauses
MRL event selection clausesWhether the event being processed triggers the execution of the rule depends on the events’s conformance with the selection criteria specified in the rule.
For example, suppose that an event class is defined as follows:
And the engine receives the following event:
The following rule will accept the instance and will be evaluated.
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:
Figure 15 Event selection criteria example
MC_EV_CLASS :APPLICATION_UP ISA APPLICATION_EVENT DEFINES{
severity: default = INFO;};
END
APPLICATION_UP;mc_host=babble;...status=OPEN;
END
filter application_events : PASSAPPLICATION_EVENT ($APEV)
where [....]
...
where [criteria]
230 BMC Knowledge Base Development Reference Guide
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” on page 230, as well as any of the following condition operators:
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’.
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.
equals (==) within matches
not_equals (!=) outside ip_greater_or_equals
greater_than (>) has_prefix ip_smaller_or_equals
greater_or_equal(<) has_suffix ip_matches
smaller_than (>=) contains ip_matched_by
smaller_or_equals (<=) contains_one_of superclass_of
between contained_in subclass_of
APPLICATION_EVENT ($APEV)where [$APEV.mc_host == ‘thishost’;]
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:
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.
For information about the order of precedence for combination operators, see “Combination operators” on page 83.
Where clause syntax best practices
Maintaining the rule engine performance
To avoid slowing the performance of the rule engine, try to specify a selector that refers to a specific event class. It takes the cell less processing time to search a specific class than it does a generic class. Also, try to avoid performance-intensive where clauses and complex queries in the Using clause.
For example, using a match_regex() call can cause performance problems. Instead, use an equals, contains, matches, has_prefix, or has_suffix clause.
The following line:
may appear equivalent to
APPLICATION_EVENT ($APEV)where [($APEV.mc_host == ‘thishost’) OR (($APEV.mc_host == ‘thathost’) AND
(NOT ($APEV.source contains ‘NT’)));]
APPLICATION_EVENT ($APEV)where [($APEV.mc_host == ‘thishost’ OR $APEV.mc_host == ‘thathost’)
AND $APEV.source contains ‘NT’;]
EVENT($EV) where [$EV.CLASS == ‘APPLICATION_EVENT’]
APPLICATION_EVENT ($EV)
232 BMC Knowledge Base Development Reference Guide
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.
Equivalent syntax and backward compatibility
The following line:
can also be written as
However,
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:
$APEV.mc_host equals ‘thathost’
mc_host:equals thathost
$EV.mc_host:equals ‘thathost’
EventClassName (Variable)where [Expression CondOperator Expression, ...]
using [ALL] {DataClassName (Variable)where [Expression CondOperator Expression,
Expression CondOperator Expression,...];
Chapter 5 Event rules 233
Using clause
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:
■ 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.
DataClassName (Variable)where [Expression CondOperator Expression,
Expression CondOperator Expression,...];
... ;}
Table 211 Conditions for the using clause (part 1 of 2)
Condition Result
Only a single instance of the data is found in the repository.
The rule is evaluated only for the single instance.
No data that matches the specified criteria is found in the repository.
The remainder of the rule is skipped.
More than one instance of the data exists in the repository.
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 BMC Knowledge Base Development Reference Guide
Using_policy clause
Using_policy clause
Policy instances can be referenced before the selection part of a rule as shown in this example:
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.
The using clause in a rule contains several queries.
The rule engine searches for an instance corresponding to the criteria in 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.
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; }
}
Table 211 Conditions for the using clause (part 2 of 2)
Condition Result
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.
This construct is called a DynamicSelection and is defined as:
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.
<DynamicSelection>= [ using_policy [ALL] ‘{’ [ <UsingCriteria> { <UsingCriteria> } ] ‘}’ ]
<DynamicCriteria>[ using [ ALL ] '{'
[ <DynamicCriteria> { <DynamicCriteria> } ] '}' ]<DynamicCriteria> = <VariableSlot> [ ( <Variable> ) ] [ where '[' [ <SlotExp> ] ']' ] ¦ <Criteria>
<Criteria> = <Class> [ ( <Variable> ) ] [ where '[' [ <SlotExp> ] ']' ]
<UsingCriteria> = <Class> [ ‘(’ <Variable> ‘)’ ] [ <Where> ] [ <Sorting> ]
236 BMC Knowledge Base Development Reference Guide
When clause
The syntax of the unless clause is as follows:
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:
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.
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.
EventClassName (Variable)where [Expression CondOperator Expression, ...]
unless {DataClassName (Variable)where [Expression CondOperator Expression,
Expression CondOperator Expression,...];
DataClassName (Variable)where [Expression CondOperator Expression,
Expression CondOperator Expression,...];
... ;}
when = WhenCondition CallList
Figure 16 when condition triggered by any change to a specified slot
WhenCond = when $VarName.SlotName
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.
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.
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 twice—once 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.
Figure 17 when condition triggered by a specific change to a specified slot
WhenCond = when $VarName.SlotName [:] Op Condition
Figure 18 when condition triggered by a specific change to a specified slot
WhenCond = when ([$VarName,]SlotExpr,OpExpr,CondExpr)
238 BMC Knowledge Base Development Reference Guide
Body clause
when clause example
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:
■ 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.
The syntax of the body clause is as follows:
Figure 19 Rule containing a when clause
execute Exec1: EVENT($E) where ...using { NOTIFY_RULE($N) where [$N.object_class == $E.mc_object_class] }when($N.trigger_slot,$N.trigger_op,$N.trigger_expr){...}
Figure 20 Sample data
NOTIFY_RULE; object_class=CLS1; trigger_slot=severity; trigger_op='>='; trigger_expr=MAJOR; ENDNOTIFY_RULE; object_class=CLS2; trigger_slot=status; trigger_op=within; trigger_expr='[ACK,ASSIGNED]'; END
NOTE When a primitive fails, that is, returns the value FALSE, the remainder of the block is not executed.
{Variable.SlotName = Value;
Chapter 5 Event rules 239
Body clause
The syntax to call a slot assignment in a body clause is as follows:
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:
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.
Call ;}
NOTE Except for the last statement, all statements in a body clause must be separated using a semicolon (;).
$EV.SlotName = expression
if Expression then
{ Variable.SlotName = Value; Call ;
}[ else
{ Variable.SlotName = Value; Call ;
}]
240 BMC Knowledge Base Development Reference Guide
Variables in rules
You can refer to a local variable declared in the then and else block after the if-then-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:
Variables in rulesUse 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:
The name of the variable must be composed of alphanumeric characters; it also can contain underscore characters.
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.
$VariableName
NOTE The cell uses a naming convention of variables with short uppercase names.
Chapter 5 Event rules 241
Dynamic data in rules
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.
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:
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.
Dynamic data in rulesDynamic data objects are BAROC objects that are used as parameters within rules and as structured objects in the Service Information Management model. Like events, they are stored in the persistent repository of the cell. The cell uses dynamic data objects to process rules.
Using dynamic data enables you to avoid writing several similar rules that differ only by values that can be stored within the data instances. When the cell evaluates a generic rule that references dynamic data, it queries a dynamic data table to access the relevant data.
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.
concat( [‘from top’, ‘to bottom’ ], $MSG0; $EV.msg = $MSG ;
242 BMC Knowledge Base Development Reference Guide
Global records in rules
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
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:
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.
Global records in rulesGlobal records maintain specified values across rule phases. You can use global records for sharing data between events. For example, you can use a global record to maintain a list of systems under maintenance. You can ignore the new events for one of these systems using a Filter rule until the system is no longer part of the global record list.
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
SEVERITY_BY_APP_DOWN ;application = mail ;severity = CRITICAL ;
END
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.
Chapter 5 Event rules 243
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 cell’s Knowledge Base.
The syntax for global records is as follows:
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:
The following is a simple example of a global record:
Interfaces in rulesRefine 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.
NOTE Global records maintain their information when the cell is stopped and restarted.
RECORD RecordNameDEFINES {
SlotName : SlotType ; SlotName : SlotType ;
}END
$RecordName.SlotName
RECORDUNDER_MAINTENANCE DEFINES {
hosts: LIST_OF STRING ; }
END
244 BMC Knowledge Base Development Reference Guide
Interface instances
Slots defined in an interface follow the same syntax as used in a class definition, as shown:
In the following example, the interface is designed to retrieve additional data about a system that is potentially down.
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:
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.
MC_INTERFACE: InterfaceNameDEFINES {
SlotName: DataType, Facet, Facet; SlotName: DataType; ...
};END
MC_INTERFACE: LOCATIONDEFINES {
site: STRING; phone: STRING;
}; END
InterfaceName ; SlotName = Value ; SlotName = Value ;
END
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.
Indexes in rulesUse 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
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.
Figure 22 Interface instance example
LOCATION ; site = B3R123 ‘ phone = 555-555-5555 ;
END
index IndexName : CLASS ( sorted|hashed )Slot | '[' Slot { , Slot } ']'
END
246 BMC Knowledge Base Development Reference Guide
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.
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.
The difference among these three forms is in the specification of the actual indexed slot values.
■ 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.
index Idx1 : EVENT_CLASS sorted [date_reception,data_handle] ENDindex Idx2 : BMC_Base_Element hashed Name END
using index IndexName '[' ']' '(' $IndexVariable ')' [ where '[' ... ']' ]using index IndexName '[' SlotVal [ { , SlotVal } ] ']' '(' $IndexVariable ')' [ where '[' ... ']' ]using index IndexName '[' Slot=SlotVal [ { , Slot=SlotVal } ] ']' '(' $IndexVariable ')' [ where '[' ... ']' ]
Chapter 5 Event rules 247
Compiling rules
For these indexes:
the following example illustrates their use in New 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 rulesRules 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 Base—mccomp” on page 26.
index Idx1 : EVENT_CLASS sorted [date_reception,data_handle] ENDindex Idx2 : BMC_Base_Element hashed Name END
new Rule1 : EVENT($EV) where [...] using ALL { index Idx1[]($E) where [...] } ... END new Rule2 : MY_EVENT($EV) where [...] using { index Idx2[$EV.ci_name]($D) } ... END
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 BMC Knowledge Base Development Reference Guide
Testing a rule
Testing a ruleYou 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.
To send an event to a cell
Use the msend command to send an event to a specific cell from any source. For more information about the msend command, see the Administration Guide.
To review event processing
Use rule tracing as described in “Tracing a rule.”
Tracing a ruleTracing 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:
■ 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.
Configuring rule tracing
You can configure rule tracing both statically and dynamically.
Chapter 5 Event rules 249
Configuring rule tracing
Configuring static rule tracing
Rule tracing can be statically configured in mcell.conf. Each time the cell starts, it reverts to this rule trace configuration. While the cell is running, the rule trace configuration can be adapted dynamically.
The following mcell.conf parameters determine which rules are traced and the level of tracing:
■ TraceRuleLevel■ TraceRulePhases■ TraceRuleNames■ TraceRulePorts
The TraceRuleLevel parameter controls rule tracing globally. It can have the following values:
■ 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:
■ entry—a 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 BMC Knowledge Base Development Reference Guide
Configuring rule tracing
■ using—a message is displayed when an object instance is retrieved by a query in a using block. For example,
■ using_policy—a message is displayed when a policy is retrieved by a query in a using_policy block. For example,
■ using_failure—a message is displayed when there are no instances that statisfy a query in a using block. For example,
■ using_policy_failure—a message is displayed when there are no instances that statisfy a query in a using_policy block. For example,
■ assign—a message is displayed for each assignment instruction. For example,
Static rule tracing configuration example
These settings enable tracing of the following rules:
■ 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.
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)
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)
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)
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)
im_internal.mrl, 167: refine im_internal_default_location: EVENT #5: $EV.mc_location = 'bmc.com'
TraceRuleLevel=2TraceRulePhases=ALL,-refine,-regulateTraceRuleNames=TroubleTicketing:ALL,-TroubleTicketing:rule1,SendMail:rule1,SendMail:rule2TraceRulePorts=entry,assign
Chapter 5 Event rules 251
Customizing rule trace message headers
Configuring dynamic rule tracing
While the cell is running, rule tracing configuration can be changed using the mcontrol CLI. Controls that influence rule tracing are:
■ 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
This command disables tracing of all new and abstract rules.
■ 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).
■ 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.
Customizing rule trace message headers
Each rule trace message is a standard cell trace message. The first part of this message is the standard cell trace message header. This header can be customized using the TraceRuleHeader parameter in mcell.conf.
252 BMC Knowledge Base Development Reference Guide
Undefined events, processing errors, and deprecated slots
The header is specified as text and can contain references to parameters, using the following designations to represent the associated parameters:
■ %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
For example, the following default TraceRuleHeader parameter value:
results in messages like:
The text of the message is retrieved from the message catalog through the message identifier and can be localized.
Undefined events, processing errors, and deprecated slots
This section briefly describes how the rule engine handles undefined events and errors in event processing. It also tells you how to process deprecated slots that you wish to continue to use.
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:
■ The event message cannot be parsed as an event.
TraceRuleHeader= %F, %L: %P %R: %C #%H:
mc_intevt.mrl, 42: new StbldStop: MC_CELL_STATBLD_STOP #118: Rule execution starting
Chapter 5 Event rules 253
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.
■ The event is of an undefined class.
An internal event of class MC_CELL_UNDEFINED_CLASS is generated. Its class definition is shown below:
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.
■ 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 non-numeric value for a numeric type.
Table 212 MC_CELL_PARSE_ERROR slots
Slot Data
error_column column number in text where error occurs
error_line line number on text where error occurs
error_message error message
event_text complete event message text
MC_EV_CLASS: MC_CELL_UNDEFINED_CLASS ISA MC_CELL_EVENT DEFINES { severity : default = MINOR; class_name: STRING; };END
Table 213 MC_CELL_UNDEFINED_CLASS slots
Slot Data
class_name name of class as specified in the message
mc_bad_slot_names : LIST_OF STRING;mc_bad_slot_values: LIST_OF STRING;
254 BMC Knowledge Base Development Reference Guide
Event processing errors
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.
Event processing errors
When an error occurs during the processing of an event, the cell’s trace displays an error message. It also generates an internal event of class MC_CELL_PROCESS_ERROR, with the slots listed in Table 214.
Using deprecated slots
Deprecated slots are obsolete in the product and may not be available in a future release. They were retained for a limited time for backward compatibility with earlier releases. If you are using slots that have been deprecated and want to continue to use them, define them and enable them. The definitions for deprecated slots are located in mc_root_redef.baroc. You can enable this file in the .load file, or you can define the individual slots that you need.
If you enable deprecated slots, their values are displayed in the Deprecated subtab of the details pane in the Events View. Administrators can access the Deprecated subtab, and they can grant access to other user roles.
Table 214 MC_CELL_PROCESS_ERROR slots
Slot Data
error_code the error number
error_goal the part of the processing command that has the error
error_message an error description message
error_source the position in the rule source where the error occurred
event the mc_ueid of the event that was being processed
Chapter 5 Event rules 255
Using deprecated slots
256 BMC Knowledge Base Development Reference Guide
C h a p t e r 6
6 Event rule types and syntaxThis chapter presents the following topics:
Refine rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Refine rule processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Refine rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Refine rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261Refine rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Filter rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262Filter rule processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Filter rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Filter rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264Filter rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Regulate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Regulate rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Forms of the Regulate rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Regulate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Regulate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Regulate rule examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
New rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270New rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272New rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273New rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Abstract rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Abstract rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Abstract rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Correlate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279Correlate rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Correlate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Correlate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283Execute rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Execute rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Threshold rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Chapter 6 Event rule types and syntax 257
Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Threshold rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Threshold rule examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Propagate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Propagate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290Propagate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Propagate rules examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Timer rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Timer rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Timer rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Timer rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Timer rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Delete rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Delete rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Delete rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Delete rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
258 BMC Knowledge Base Development Reference Guide
Refine rules
Refine rulesA 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
■ 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.
Refine rule processing
Figure 23 illustrates how a Refine rule processes incoming events.
Figure 23 Refine rule processing
# Description
1 The incoming event is compared to the ECFs contained in the Refine rule.
2 The incoming event does not match the ECF contained in the Refine rule.
3 Incoming event matches the ECF in the Refine rule.
Incoming Event
Refine Rule(ECFs)
1
No Match Match
32
event data is deleted
event data is retained
Chapter 6 Event rule types and syntax 259
Refine rule syntax
Refine rule syntax
The syntax for the Refine rule is shown in Figure 24.
Figure 25 shows the syntax of an event condition formula (ECF) definition for a Refine rule.
Figure 24 Refine rule syntax
refine RuleName :ECF{
Call;Variable.SlotName = Value;...
}END
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 Refine rule ECF syntax
ClassName Variablewhere [Expression CondOperator Expression,
Expression CondOperator Expression]using | using ALL DataName DataVariable
where [Expression CondOperator Expression,Expression CondOperator Expression]
ClassName Variable where 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.
using | using ALL 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 BMC Knowledge Base Development Reference Guide
Refine rule primitives
Refine rule primitives
The following primitives are specifically assigned to be used in Refine rules
■ confirm_external—calls a program to run on the cell and supplies all necessary 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.
■ get_external—runs an executable on the same computer on which the cell runs 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 rule examples
In Figure 26, the get_external primitive calls the get_site.sh script to populate the msg slot of an incoming event with information about a site.
The following is an example BAROC definition for the LOCATION interface.
Figure 26 Refine rule example
refine Disk_Full_Contact_Info : DISK_FULL ($DF){
get_external (‘get_site.sh’, [], LOCATION, $LOC); $DF.msg = $LOC.site ;
}END
MC_INTERFACE : LOCATIONDEFINES {
site: STRING ; phone: STRING ;
}END
Chapter 6 Event rule types and syntax 261
Filter rules
The following is an example of the standard output from the get_site.sh script.
Filter rulesFilter 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
■ PASS—an event meets a defined condition passing to the next rule. ■ NOPASS—an event meets a defined condition and is dropped from the rule
engine.
LOCATION ; site = ‘B3R123’ ; phone = ‘x7734’ ;
END
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 BMC Knowledge Base Development Reference Guide
Filter rule processing
Filter rule processing
Figure 27 illustrates how a Filter rule processes an incoming event.
Figure 27 Filter rule processing
Filter rule syntax
Figure 28 shows the Filter rule syntax.
# Process description
1 An incoming event is compared to the ECFs contained in the Filter rule.
2 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.
3 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.
Figure 28 Filter rule syntax
filter RuleName :PASS | NOPASSECFECF...
END
Incoming Event
Filter Rule(ECFs)
1
No Match Match
32
3b3a2b2a
PASS ModeNOPASS Mode PASS ModeNOPASS Mode
event is discardedevent moves to next filter event moves to the next filterevent is discarded
Chapter 6 Event rule types and syntax 263
Filter rule primitives
Figure 29 is the syntax of an ECF definition included in a Filter rule.
Filter rule primitives
There are no primitives specifically for Filter rules. You can use any primitive that is not specifically assigned to a particular rule type in Filter rules. See “MRL functions and primitives” on page 100 for more information about primitives.
Table 215 Filter rule syntax descriptions
filter keyword that specifies how the text in the rule is interpreted
RuleName name of the rule
Rule names should■ be self-explanatory of their purpose■ be unique across the Knowledge Base ■ contain only alphanumeric characters■ utilize only the underscore character
PASS | NOPASS indicates what mode the Filter rule is using
ECF list of the ECF for the Filter rule, multiple ECFs can exist in each Filter rule
Note: All rule types can include an ECF, which determines which events should be processed by the rule.
Figure 29 Event condition formula in a filter rule
ClassName Variablewhere [Expression Operator Expression, ..., SlotName: RelationalOperator Value,]
NOTE Any type of expression can be used in the Where clause.
264 BMC Knowledge Base Development Reference Guide
Filter rule examples
Filter rule examples
In Figure 30 the f1 Filter rule specifies that the events accepted by the rule must either originate from the svr1 and svr2 hosts, or is a login event. The f2 Filter rule specifies that any INFO events and all successful login events are discarded by the rule.
Table 216 demonstrate how specific events are processed by the Filter rules f1 and f2 in the example in Figure 30.
Figure 30 Filter rule example
filter f1 : PASSEVENT where [ $THIS.mc_host within [svr1,svr2] ]LOGIN_EVENT
ENDfilter f2 : NOPASS
EVENT where [ $THIS.severity equals INFO ]LOGIN_SUCCESS
END
Table 216 f1 and f2 Filter rules event processing examples
Event Example Filter Rule Process Result
LOGIN_SUCCESS;mc_host=clt1; severity=WARNING;
END
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.
The event is discarded.
LOGIN_FAILURE; mc_host=clt1;severity=WARNING;
END
1. The f1 filter accepts the event because it is a login event.
2. The f2 filter accepts the event because its severity level is not INFO and it is not a successful login event.
The event is accepted for additional processing.
SERVERS_LOGIN_ATTACK;mc_host=svr3;severity=CRITICAL;
END
1. The f1 filter discards the event because the 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.
The event is discarded.
Chapter 6 Event rule types and syntax 265
Regulate rules
Regulate rulesUse 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.
Regulate rule processing
An incoming event that satisfies the Regulate rule ECFs is added to a Hold queue. If the event repeats a given number of times within a specified time frame, the Regulate rule executes and passes an event. It does not execute again until the time frame is reset by the Unless clause.
The Unless clause is read as, “When I have fewer events than specified in the rule during the time window specified in the rule, then reset.” Events in the Hold queue that age beyond the time frame are dropped from the queue when the time frame resets. You can use the Unless clause as a minimum threshold to reset the mechanism. If no Unless clause is specified, a new time window is started.
You can write dynamic Regulate rules. The values for the number of events (#Events1, #Events3) and the time frame windows (TimeFrame2, TimeFrame4) can be expressions. It is possible, by writing a Using clause in the ECF, to obtain values from the dynamic data tables and use them in these parameters.
Forms of the Regulate rule
There are two basic forms of the Regulate rule:
■ 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 BMC Knowledge Base Development Reference Guide
Regulate rule syntax
The repeat_count slot of the forwarded event is set to the number of events in the Hold queue.
■ 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 right-hand 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 rule syntax
The Regulate rule has two forms. Figure 31 shows the Form 1 Regulate rule syntax.
Figure 32 shows the Form 2 Regulate rule syntax.
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.
Figure 31 Regulate rule syntax form 1
regulate RuleName :ECFhold #Events1 within TimeFrame2send $FIRST | $LAST | $HISEV | $LOSEV[ unless #Events3 within TimeFrame4 close ]
END
Figure 32 Regulate rule syntax Form 2
regulate RuleName :ECFhold #Events1 within TimeFrame2send {
Chapter 6 Event rule types and syntax 267
Regulate rule primitives
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.
Regulate rule primitives
There are no primitives specifically assigned to Regulate rules. Regulate rules can utilize any primitive that is not specifically assigned to a particular rule type. See “MRL functions and primitives” on page 100 for more information about primitives.
Regulate rule examples
The purpose of the Regulate rule in Figure 34 is to send one LOGIN_FAILURE event, rather than five, to the next rule when the user name does not match either root or Administrator.
ClassName ;SlotName = Value ;...
}[ unless #Events3 within TimeFrame4 close ]
END
Figure 33 Regulate rule syntax to send a custom event
regulate RuleName : ClassName
where [Expression Operator Expression,...SlotName: RelationalOperator Value,]
hold #Events within TimeFramesend {
ClassName ; SlotName = Value ; ...
}[ unless #Events within TimeFrame close ]
END
Figure 32 Regulate rule syntax Form 2
268 BMC Knowledge Base Development Reference Guide
Regulate rule examples
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.
The Regulate rule in Figure 36 assumes that a dynamic data table has been designed and populated like the example.
Figure 34 Regulate rule example 1
regulate User_Authentication :LOGIN_FAILURE ($LF)
where [ $LF.user outside [root, Administrator] ]hold 5 within 1 msend $FIRST
END
Figure 35 regulate rule example 2
regulate Swap_Availability :SwapAvail ($SA)hold 4 within 2 msend {
Repeated_SwapAvail_Low ;hostname = $LAST.hostname ;origin = $LAST.origin ;msg = ‘Swap space low condition’ ;
}unless 2 within 5 m close
END
Figure 36 Regulate rule example 3
MC_DATA_CLASS :REGULATE_DATA ISA DATADEFINES {
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 Event rule types and syntax 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.
New rulesUse 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.
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:
■ displayed in the console■ returned by the MQUERY command■ referenced by Using or Update clauses in MRL
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_hwithinsend {
Repeated_SwapAvail_Low ;hostname = $LAST.hostname ;origin = $LAST.origin ;msg = ‘Swap space low condition’ ;
}unless $DATA.rd_slot_unless within $DATA.rd_slot_uwithinclose
END
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.
270 BMC Knowledge Base Development Reference Guide
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.
# Description
1 The incoming event is compared to the ECFs contained in the New rule.
2 The incoming event does not match the ECF contained in the New rule.
3 The incoming event matches the ECF in the New rule.
Incoming Event
New Rule(ECFs)
1
No Match Match
32
event data is deleted
event data is retained
Chapter 6 Event rule types and syntax 271
New rule syntax
New rule syntax
new RuleName :ECFtriggers
{Call;Variable.SlotName = Value;...}
updates {ALL} duplicate | ClassName (Variable)ECF
[ within TimeFrame ]{Call;Variable.SlotName = Value;...}
END
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 BMC Knowledge Base Development Reference Guide
New rule primitives
New rule primitives
The drop_new primitive is the only primitive assigned to be used in New rules. The purpose of the drop_new primitive is to discard new events. See page 220 for more information about the primitive.
In addition to the drop_new primitive, New 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.
New rule examples
In the following example, the HOST_DOWN event is closed when a HOST_UP event is received from the same host. If there is no HOST_DOWN event or if it is already closed, the new HOST_UP event is not discarded.
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 [$IN_HU.status equals OPEN ]updates HOST_DOWN($ORIG_HD)where [$ORIG_HD.status equals OPEN,$ORIG_HD.hostname equals $IN_HU.hostname ]{$ORIG_HD.status = CLOSED;drop_new;}END
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 Event rule types and syntax 273
New rule examples
The following New rule illustrates how to use the duplicate keyword to retain an old event updated while discarding all new events.
The New rule searches the repository for another DISK_USED_PERCENTAGE event. If one is found, it is updated—the old value is replaced by the new one and the repeat_count is increased—and 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.
Creating a generic rule using dynamic data and New rules
In a business environment, situations arise that are different in specifics yet have a similar solution. In such as scenario, you can use the Dynamic Data Model in the rule engine to write one rule that can be applied to many situations.
For example, hosts, processes, and links alternate between being available or unavailable. The specifics require a host_up closes host_down, process_up closes process_down, link_up closes link_down, and so on. While the details vary, the solution is the same. That is, any up event should close its matching down event. The developer uses dynamic data to write one generic rule instead of having as many rules as there are “up closes down” relationships.
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.
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
274 BMC Knowledge Base Development Reference Guide
New rule examples
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:
Once the data class structure is defined, the developer creates the data instances necessary to cover the “up closes down” relationships.
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.
MC_DATA_CLASS: CLOSE_RELATION ISA DATADEFINES {
class_close: STRING, key=yes ; #eg host_downclass_up: STRING ; #eg host_upinterval: INTEGER, default=60 ;
}; END
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
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 Event rule types and syntax 275
Abstract rules
Abstract rulesAbstract 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
■ 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
■ 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 low-level, events that created the high-level event.
NOTE Once an abstract event is created, the relationship cannot be removed.
276 BMC Knowledge Base Development Reference Guide
Abstract rule syntax
Abstract rule syntax
Figure 38 is an example of the Abstract rule syntax.
Figure 38 Abstract rule syntax
abstract RuleName :ClassName (Variable) ##Abstractionfrom ClassName (Variable) ##Abstracted From
ECFsetup { ##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)
class of the original events, that is, those events abstracted from
ECF 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 Event rule types and syntax 277
Abstract rule primitives
Abstract rule primitives
There are no primitives or functions specifically associated to Abstract rules. Abstract rules can use any primitive or function that is not associated with a specific rule type. For more information about primitives and functions, see Appendix 4, “Master Rule Language (MRL) reference.”
Abstract rule examples
In Figure 39 the from clause executes the Abstract rule when a LOGIN_FAILURE event is received from a system with an IP address within the specified IP range. The setup clause populates the slots of the abstraction, or SERVERS_LOGIN_ATTACK, event. The when clauses keep a count of servers under login attack by incrementing the num_servers slot when the LOGIN_FAILURE event’s status is OPEN and decreases the count when the event closes.
Figure 39 Abstract rule example 1
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 BMC Knowledge Base Development Reference Guide
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.
Correlate rulesCorrelate 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
■ mc_cause slot—contains the reference to the cause event■ mc_effects slot—contains the list of the consequence events
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
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 Event rule types and syntax 279
Correlate rule syntax
Correlate rule syntax
Figure 41 is an example of the Correlate rule syntax.
Figure 41 Correlate rule syntax
correlate RuleName :ClassName ($Variable) ## Effect
ECFwith ClassName ($Variable) ## Cause
ECFwithin TimeFramewhen Variable.SlotName: RelationalOperator Value{
Call ;Variable.SlotName = Value ;
}with ClassName ($Variable) ## Cause
ECFwithin TimeFramewhen 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 BMC Knowledge Base Development Reference Guide
Correlate rule primitives
Correlate rule primitives
The unset_cause primitive is the only primitive assigned to be used in Correlate rules. The purpose of the unset_cause primitive is to break the cause and effect relationship between two events. See page 221 for more information about the primitive.
In addition to the unset_cause primitive, Correlate rules can utilize any primitive not specifically assigned to a particular rule type. See “Primitives and functions overview” on page 106 for more information about rules and assigned primitives.
Correlate rule examples
The Correlate rule example in Figure 42 correlates the APP_DOWN and APP_MISSING_PROCESSES events if the application slot of both events contains the same value. When the APP_MISSING_PROCESSES event status is open, the Correlate rule sets the event severity to critical.
Figure 42 Correlate rule example 1
correlate App_Down :APP_DOWN ($AD)with APP_MISSING_PROCESSES ($AMP)
where [ $AMP.application equals $AD.application ]within 1 mwhen $AMP.status equals OPEN{
$AMP.severity=CRITICAL ;}
END
Chapter 6 Event rule types and syntax 281
Correlate rule examples
The Correlate rule example in Figure 43 includes multiple potential causes for a NFS server not responding.
The event examples in Table 217 demonstrate how specific events are processed by the Correlate rule in Figure 43.
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 mwhen $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 mwhen $PD.status not_equals CLOSED{
$NFS.severity=INFO ;}when $PD.status equals CLOSED{reset_default ($NFS.severity) ;unset_cause ;}
END
Table 217 Correlate rule event examples
Example Event Event 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.
The HOST_DOWN event is the cause.
If the cell receives an NFS_NO_RESP event and a PROCESS_DOWN event within ten (10) minutes, and no HOST_DOWN event has entered the cell, then the Correlate rule builds a relationship between the events.
The PROCESS_DOWN event is the cause.
282 BMC Knowledge Base Development Reference Guide
Execute rules
Execute rulesThe 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
■ perform actions on an event ■ format an event message ■ update a global record or slot value ■ generate a new event
Execute rule syntax
Figure 44 is an example of the Execute rule syntax.
Figure 44 Execute rule syntax
execute RuleName :ECFwhen Variable.SlotName CondOperator Value{
Call;Variable.SlotName = Value;...
}when Variable.SlotName CondOperator Value{
Call;Variable.SlotName = Value;...
}...
END
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 Event rule types and syntax 283
Execute rule syntax
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.
Environment variables for Execute rules
When creating an executable you can use the environment variables listed in Table 218 in the executable script or program.
All slots are passed in the environment in the form of variables (with the same names as their slot names) containing the slot values.
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.
Table 218 Available environment variables in Execute rules
Variable Description
CELL_BUILD build number found in the About dialog box of the console
CELL_DATE date of the build
CELL_NAME name of the cell
CELL_RELEASE release number for the cell, for example 1.1
CLASS class of the event under analysis
HOME home directory of the requestor
LOGNAME log file name
MCELL_HOME home directory where the cell resides
PKG_NAME name of the rule package
REQUESTOR requestor of the external action
Can be either user@host for an action from a client or package:rule for an action initiated from a rule.
RULE_NAME name of rule that triggered the external action
SHELL shell program
SLOTS list of slot names for the class
TERM terminal type (for UNIX only)
WINDOWID window ID for the requested console
284 BMC Knowledge Base Development Reference Guide
Execute rule primitives
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.
Execute rule primitives
There are no primitives specifically for Execute rules. Execute rules can use any primitive that is not associated with a specific rule type. For more information about primitives, see “MRL functions and primitives” in Appendix 4, “Master Rule Language (MRL) reference.”
You can use the following primitives to help set up an Execute rule:
■ reset_default—resets the default value for a slot that you specify■ generate_event—creates a new event ■ add_to_list—adds a value to a specified slot ■ rem_from_list--removes a value from a specified slot■ set_timer—sets a timer to execute at a period of time in the future■ execute—runs an executable file for a cell
Execute rule examples
The Execute rule in Figure 46 executes when a DiskUsedPercentage event is received. The When clause generates a new message that is sent by the event containing a value for the disk space used. The When clause uses the concat primitive to convert the number received from the event to a whole number and then concatenates the message.
Figure 46 Execute rule example 1
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 Event rule types and syntax 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.
■ 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.
Threshold rulesThe 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.
Figure 47 Execute rule example 2
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
286 BMC Knowledge Base Development Reference Guide
Threshold rule processing
Threshold rule processing
Figure 48 shows how Threshold rule processing occurs.
Figure 48 Threshold rule processing
# Process Description
1 An incoming event is compared to determine if it is a duplicate of another event.
2 The event is a duplicate event and is added to the existing queue.
3 The event is not a duplicate event, a new queue is created.
4 The event is compared against the rule to determine if a threshold is reached.
5 If a threshold is reached, the code in the rule is executed and the queue is deleted.
6 If a threshold is not reached, the event remains in the queue.
Incoming Event
Duplicate Event?
1
Added to queue
New queue created
32
Matches Threshold?
rule is executed and the queue is
deleted
65
event is retained in the queue
4
Chapter 6 Event rule types and syntax 287
Threshold rule syntax
Threshold rule syntax
Figure 49 is an example of the Threshold rule syntax.
Threshold rule primitives
There are no primitives specifically assigned to Threshold rules. Threshold rules can use any primitive that is not assigned with a specific rule type. For more information about primitives, see Appendix 4, “Master Rule Language (MRL) reference.”
Threshold rule examples
The Threshold rule in Figure 50 generates a TOO_MANY_AUTH_FAILS event when 10 SNMP_AUTHENTICATION_FAILURE events occur within 120 seconds.
Figure 49 Threshold rule syntax
threshold RuleName : ECFwhen NumberOfEvents within TimeFrame{
Call;Variable.SlotName = Value ;
}END
NumberOfEvents maximum number of events allowed in the queue
TimeFrame specified time frame in which the number of events is received
Figure 50 Threshold rule example
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 BMC Knowledge Base Development Reference Guide
Propagate rules
Propagate rulesA 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 lower-level 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:
■ to—propagates to one specific cell■ to all—propagates to all cells in the list■ to one_of—propagates to only one cell in the list. Typically, cells are tried in turn.
The rule engine stops when propagation is successful.
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 Event rule types and syntax 289
Propagate rule syntax
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.
■ mc_history—contains the list of cells, and the identification of the event inside each cell, through which the event flowed before reaching the current cell.
■ mc_propagations—contains the list of cells, and their internal identifications, to 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 event-specific slot changes are propagated forward, while the status is propagated backward.
Propagate rule syntax
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.
propagate RuleName :ECFto CellName | to all
[CellName, ...] | to one_of[CellName, ...]
when Variable.SlotName CondOperator Valueto CellName | to all
[CellName, ...] | to one_of[CellName, ...]
when Variable.SlotName CondOperator Value...
END
290 BMC Knowledge Base Development Reference Guide
Propagate rule primitives
Propagate rule primitives
There are no primitives specifically assigned to Propagate rules. Propagate rules can utilize any primitive that is not specifically assigned to a particular rule type. See “MRL functions and primitives” on page 100 for more information about primitives.
Propagate rules examples
The Propagate rule in Figure 51 sends all APP_DOWN events originating from a system in the IP address range of 172.16.23.* to server1, server2, and server3 when the status the status of the event is CRITICAL.
The Propagate rule example in Figure 51 also sends APP_DOWN events, regardless of the event status, originating from a system in the IP address range of 172.16.23.[1-10] to server1. If server1 is unavailable, the event is propagated to server2.
Timer rulesUse Timer rules to create timed triggers to call a rule. Timer rules are evaluated when a timer expires. Timer rules can be used to
■ 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.
Figure 51 Propagate rule example
propagate Prop_Critical :APP_DOWN ($AD)
where [origin: ip_matches ‘172.16.23.*’ ]to all [ server1, server2, server3 ]
when $AD.severity equals CRITICALto one_of [ server1, server2 ]
when $AD.origin ip_matches ‘172.16.23.<10’END
Chapter 6 Event rule types and syntax 291
Timer rule processing
Timer rule processing
An event for which a timer has expired goes through the Timer phase. After having been tested against the ECF, the timer_info value of the timer is tested against an expression. That value is in fact what was put in the info_label argument to the set_timer primitive. If the condition matches, the corresponding block is executed.
Timer rule syntax
Figure 52 is an example of the Timer rule syntax.
Timer rule primitives
There are no primitives assigned specifically to Timer rules. Timer rules can use any primitive that is not associated with a specific rule type. For more information about primitives, see Appendix 4, “Master Rule Language (MRL) reference.”
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.
Figure 52 Timer rule syntax
timer RuleName :ECFtimer_info : RelationalOperator TimerTrigger1{
Call ;Variable.SlotName = Value ;...
}timer_info : RelationalOperator TimerTrigger2{
Call ;Variable.SlotName = Value ;...
}...
END
292 BMC Knowledge Base Development Reference Guide
Timer rule examples
The following primitives are not assigned to Timer rules, but can be used to help set up a timer
■ set_timer—sets a timer to execute at a period of time in the future. ■ set_timer_at—sets a timer to execute on a specific date and time.
Timer rule examples
The Timer rule in Figure 53 demonstrates how the rule performs selective escalation for an issue that does not disappear immediately. In the example, different timers are set according to the origin of the problem, which is assumed to originate with a server located in the lowest portion of the address range. The Timer rule also assumes that problems on servers are more severe than on other computers.
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 53 Timer rule example 1
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
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 Event rule types and syntax 293
Delete rules
Delete rulesThe 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 rule syntax
Figure 55 shows the Delete rule syntax.
Delete rule primitives
There are no primitives specifically assigned to Delete rules. Delete rules can utilize any primitive that is not assigned to a particular rule type. See “MRL functions and primitives” on page 100 for more information about primitives.
Delete rule examples
The Delete rule in Figure 56 removes event data from a dynamic data table when an event is deleted.
Figure 55 Delete rule syntax
delete RuleName : ECF{
Call; Variable.SlotName = Value; ...
}END
Figure 56 Delete rule example (part 1 of 2)
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
Delete rule examples
}ENDThe definition for the data could be: MC_DATA_CLASS :
MYDATA ISA DATADEFINES {
name : STRING ; name : INTEGER ;
{END
Figure 56 Delete rule example (part 2 of 2)
Chapter 6 Event rule types and syntax 295
Delete rule examples
296 BMC Knowledge Base Development Reference Guide
C h a p t e r 7
7 Working with collectorsThis chapter describes the procedures for defining and working with collectors. It depicts the default event collectors that are included with the installation. This chapter presents the following topics:
Creating or modifying a collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Collector syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Best practices for defining collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Collector security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Defining static collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303Defining dynamic collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Default event management collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306self_collector.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306catchall_collector.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306mc_bystatus_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307mc_bylocation_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307MCxP collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308bii4p_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308mc_evr_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Default service impact management event collector . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Chapter 7 Working with collectors 297
Creating or modifying a collector
Creating or modifying a collectorThe collector .mrl file can be named anything you choose, but it must be located in the Knowledge Base collectors directory and must be added to the .load file. Any time you make a change to a collector, recompile the Knowledge Base for that cell and restart the service. For more information, see “Compiling a Knowledge Base—mccomp” on page 26.
The following topics describe how to create or modify a collector:
■ “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
collector CollectorName {[ r | w | x Role ]}
[create Expression
[ delete ] ]
[ CLASSEVENTNAME where
[slot_name: condition_operator slot_value,
. . . ]
| CatchAll ]
END
2
4
3
6
7
8
5
1
298 BMC Knowledge Base Development Reference Guide
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:■ defining the cell itself using the keyword self■ specifying the parent collector name, such as Network■ specifying the child collector name, such as Network.Subnet■ 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■ r—read access■ w—write access■ x—execute 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:
■ $THIS.mc_origin—substitutes the value of mc_origin for the asterisk in the collector name■ $THIS.mc_cause—substitues 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.
Chapter 7 Working with collectors 299
Best practices for defining collectors
Best practices for defining collectors
To preserve the optimum cell performance, observe the following guidelines. Any new event or any slot change forces the cell to reconfigure collector conditions.
■ Define Where clauses in event condition formulas (ECFs) as simply as possible. Use narrowly defined classes rather than complex Where clauses. For example:
is more efficient than
■ 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.
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
collector HostsDown : HOST_DOWNEND
collector HostsDown : EVENTwhere (CLASS: equals ‘HOST_DOWN’)
END
collector AllHostsEvents : HOST_EVENTEND
# Description
300 BMC Knowledge Base Development Reference Guide
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.
■ 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.
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.
collector HostsEvents : EVENTwhere (CLASS: equals ‘HOST_EVENT’)
END
Table 219 BMC Impact Manager standard roles
Role Description
Administrator roles
Full Access manages everything in the environment
Service Administrator manages the BMC Impact Manager infrastructure events, events, and services
Service Manager roles
Service Managers- Senior manages services and events with full customization capabilities
Service Managers manages services and events with limited customization capabilities
Operator roles
Service Operators- Senior manages events and services with full customization capabilities
Service Operators manages events and services with limited customization capabilities
Chapter 7 Working with collectors 301
Collector security
How collector permissions work
Child collectors inherit the permissions and role assignments specified for the parent collector. You cannot override a role assignment at a child collector level once the role has been assigned at a parent level. Therefore, roles and related permissions should be assigned at the highest level collector.
A self collector must be defined in each collector tree. If more than one .mrl file containing collector definitions exists for any Knowledge Base, you need only one self collector defined. Figure 58 illustrates the main collector, self, followed by the c1 collector and its child collectors, c1.one and c1.two. The collector tree also contains the c2 collector and its child collectors, c2.one and c2.two.
The following points describe the user roles and associated permissions for the collectors defined in Figure 58:
■ 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.
Figure 58 Collector tree definition example
collector self:{r[Full Access]; w[Full Access]; x[Full Access]}
ENDcollector c1:
{r[Service Administrator,Service Operators]; w[Service Administrator,Service Operators]; x[Service Administrator,Service Operators]}ENDcollector c1.one:
{r[Service Managers-Senior]}ENDcollector c1.two:
{r[Service Managers-Senior], w[Service Managers-Senior]}ENDcollector c2:
{r[Service Managers-Senior,Service Administrator]; w[Service Managers-Senior,Service Administrator]; x[Service Managers-Senior,Service Administrator]}ENDcollector c2.one:
{r[Service Operators], w[Service Operators]}ENDcollector c2.two:
{r[Service Operators]}END
302 BMC Knowledge Base Development Reference Guide
Defining static collectors
■ 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.
Defining static collectors
Static collectors remain visible for a cell regardless of whether that collector contains any events. A static collector requires that event criteria are fully defined.
In Figure 59, the self collector has no roles or access rights defined. The Networks parent collector does not have an ECF but it does define read access rights for a user with the Service Administrator role.
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.
Figure 59 Static collector example 1
collector self :ENDcollector Networks :
{ r [Service Administrator] }ENDcollector 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
Chapter 7 Working with collectors 303
Defining dynamic collectors
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.
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.
Defining dynamic collectors
Dynamic collectors are created automatically when specified events are received. When specified events are deleted or changed and the associated collector becomes empty, the collector is removed. Dynamic collectors reflect the dynamic nature of event sources.
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]
} ENDcollector 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]
ENDcollector AllEvents.NotOpen :
EVENT where [status: not_equals OPEN]END
304 BMC Knowledge Base Development Reference Guide
Defining dynamic collectors
The following is the definition of class NET, for which events are generated for network-related issues:
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.
Dynamic roles in dynamic collectors
In a dynamic collector, dynamic role assignments depend on characteristics of the incoming event. The dynamic roles are created with the dynamic collector. The $THIS variable in the following example refers to the incoming event and is used in the role name definition.
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.
MC_EV_CLASS: NET ISA EVENT ; END
collector Net ENDcollector Net.* : NET where [$THIS.mc_object_class != '']create $THIS.mc_object_class deleteENDcollector Net.*.Server : NET where [$THIS.mc_origin_class == SERVER]ENDcollector Net.*.Server.* : NETcreate $THIS.mc_originENDcollector Net.*.Client : NETENDcollector Net.Global : NETEND
collector Net.*.Server.* : { r[$THIS.mc_origin] } : NETcreate $THIS.mc_origin
END
Chapter 7 Working with collectors 305
Default event management collectors
Default event management collectorsThe following collectors, which group events based on their associated collector rules, are defined in the Knowledge Base collectors directory.
self_collector.mrl
The self collector defines a collector for the cell. It is the parent node for all collectors defined for that cell.
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.
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.
Figure 61 Self collector definition
collector self :{ r['Full Access'] w['Full Access'] x['Full Access']}END
Figure 62 Catchall collector definition
collector 'All Events' :{ r['Service Administrators'] w['Service Administrators'] x['Service Administrators']}
catchallEND
306 BMC Knowledge Base Development Reference Guide
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.
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 220 By Status collector set
Subcollector branch Description
‘ByStatus’.Open shows all events in OPEN status
‘ByStatus’.Acknowledged shows all events in ACK status
‘ByStatus’.Assigned shows all events in ASSIGNED status
‘ByStatus’.Closed shows all events in CLOSED status
‘ByStatus’.Blackout shows all events in BLACKOUT status
Table 221 By Location collector set (part 1 of 2)
Subcollector branch Description
ByLocation.System This collector stores events belonging to the following classes:
■ 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
Chapter 7 Working with collectors 307
MCxP collector set
MCxP collector set
The MCxP collector set contains a hierarchy of dynamic collectors that collect PATROL_EV events.
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.
‘By Location’.* This collector collects all event types except SMC_STATE_CHANGE events. Events are stored in a dynamic collector named by their domain name, which is stored in their mc_location slot. If this slot is empty, the event goes into the Unknown collector.
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.
‘By Location’.*.*.*.* 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 subcollector level.
Table 222 Collectors included in the MCxP collector set
Collector Description
MCxP.* The first level of the hierarchy is created based on mc_host slot.MCxP.*.* The second level of the hierarchy is created based on the
p_application slot, provided this slot is not empty. MCxP.*.*.* The third level of the hierarchy is created based on p_instance slot,
provided this slot is not empty.MCxP.*.*.*.* The fourth level of the hierarchy is created based on mc_parameter slot,
provided this slot is not empty.
Table 221 By Location collector set (part 2 of 2)
Subcollector branch Description
308 BMC Knowledge Base Development Reference Guide
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.
Default service impact management event collector
The service model requires only the MC_SMC_Events collector node. This collector tree is used by the Services View to retrieve the events of a specific component, based on its type and its logical ID, stored in the mc_udid slot. Figure 63 shows the MC_SMC_EVENTS collector definition.
Figure 63 MC_SMC_EVENTS collector definition
An example query issued by the collector is shown in the following example:
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
select open events from collector MC_SMC_EVENTS.component_typewhere [$THIS.mc_smc_id equals component_mc_udid]
Chapter 7 Working with collectors 309
Default service impact management event collector
This query varies depending on the menu command selected in the Services View:
Menu command Query type
All Events any open or acknowledged event associated to the component
Impact Events any open or acknowledged event associated to the component and elected
History Events any open or closed event of class SMC_STATE_CHANGE for that component
310 BMC Knowledge Base Development Reference Guide
C h a p t e r 8
8 Policy and selector syntaxThis chapter presents the following topics:
Event policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Event selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Format of event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . 314How a rule for a policy type is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Chapter 8 Policy and selector syntax 311
Event policies
Event policiesAn 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.
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 64 Policy class syntax
MC_DATA_CLASS: policy_class_name ISA POLICYDEFINES
{slot_name: ECF class_name; slot_name: QUERY class_name;slot_name: data_type [default=value];...
}END
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 BMC Knowledge Base Development Reference Guide
Event selectors
The syntax for a policy contained in a rule is shown in Figure 66.
Event selectorsAn 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.
The syntax for a selector entry is shown in Figure 68.
Figure 66 Policy in a rule syntax
RuleType RuleName : using_policy{
policy_class_name ($Variable)where [expression op expression, ...,expression op expression]
}END
Figure 67 Selector class syntax
MC_DATA_CLASS: SELECTORDEFINES
{name: STRING; description: STRING; based_on: STRING, default=”EVENT”;ecfs: LIST_OF ECF;
};END
Figure 68 Selector entry syntax
SELECTOR; name=string_value; description=string_value; based_on=BASE_EVENT_CLASS_NAME;ecfs=[“EVENT_CLASS_NAME [where clause]”, . . .];
END
Chapter 8 Policy and selector syntax 313
Event processing rules for policy types
Event processing rules for policy typesThis section describes the form of policy type rules and discusses how they work.
Format of event processing rules for policy types
A typical event processing rule for a user-defined policy type has this form:
How a rule for a policy type is processed
The processing of a rule for a policy type is a follows:
1. The using_policy clause finds the applicable policy, that is, the instance of the user-defined policy class (derived from IM_POLICY).
<rule-phase> rule-name: using_policy { <POLICY_TYPE> ($POL) where [ ($POL.enabled == 1) AND (($POL.active_timeframes == [] OR tf_active($POL.active_timeframes)) AND NOT tf_active($POL.except_timeframes)) AND (($POL.active_global_timeframes == [] OR tf_udid_active($POL.active_global_timeframes)) AND NOT tf_udid_active($POL.except_global_timeframes)) ]} $POL.selector_ecf ($EV) where [ <other conditions> ] { <actions>; opadd($EV, $POL.name, "action name", ""); } END
314 BMC Knowledge Base Development Reference Guide
How a rule for a policy type is processed
These class definitions describe the slots available in a policy class:
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.
MC_DATA_CLASS : POLICY ISA CORE_DATA DEFINES { name : STRING, key = yes, read_only = yes; description : STRING; enabled : INTEGER, default = 1; };END MC_DATA_CLASS: IM_POLICY ISA POLICY DEFINES { active_timeframes : LIST_OF STRING; except_timeframes : LIST_OF STRING; active_global_timeframes : LIST_OF STRING; except_global_timeframes : LIST_OF STRING; selector_name : STRING; selector_class : STRING; selector_ecf : ECF EVENT; ordinal : INTEGER, default=0; };END
Chapter 8 Policy and selector syntax 315
How a rule for a policy type is processed
316 BMC Knowledge Base Development Reference Guide
C h a p t e r 9
9 Common Event ModelThis chapter describes the different property groupings of the Common Event Model (CEM). It presents the following topics:
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Versioning support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Internationalization compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Mapping quick reference: CEM to BAROC (CORE_EVENT). . . . . . . . . . . . . . . . 320
Guidelines for applying CEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Associating events with configuration items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Root cause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Adding attributes vs. adding generic slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Cross-launching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Event synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Free-format text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
CEM property groupings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Source component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Reporter component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Situation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Metric properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
OverviewA 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 Common Event Model 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.
■ 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
■ event type■ CEM version■ origin information■ domain information■ object information■ management processes such as availability, scheduling, and so forth■ parameters
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:
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.
318 BMC Knowledge Base Development Reference Guide
Versioning support
CEM supports the following data types:
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.
Table 223 Property groupings: BMC_BaseEvent class
Property group Description
General basic information about the event, including the event class, event Id, status, and so forth
Source component properties related to the component that is associated with the source of the event. These include the component host name and the host address.
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.
Metrics 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.
Table 224 Data types
Data types Description
INTEGER 32-bit signed value
REAL 64-bit real value
STRING UTF-8 string value with a maximum length of 65535 bytes
<ENUMNAME> enumeration
LIST_OF a collection of objects
Chapter 9 Common Event Model 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.
Mapping quick reference: CEM to BAROC (CORE_EVENT)
The following tables list the mapping associations between CEM properties and their respective BAROC slots in the CORE_EVENT class.
PropagationHistory is required if the event provider wants to receive synchronized event. RelationSource is required if the consumer wants to send or receive updates.
Table 225 CEM to BAROC: Metadata
CEM property BAROC slot Required or optional
EventModelVersion mc_event_model_version required
EventClass CLASS required
EventId mc_ueid required
Status status optional
ReportTime mc_incident_report_time optional
EventToCIAssociationType mc_smc_impact optional
Timeout mc_timeout optional
Notes mc_notes optional
PropagationHistory mc_history required
RelationSource mc_relation_source required
Owner mc_owner optional
Account mc_account optional
Table 226 CEM to BAROC: source information (part 1 of 2)
CEM property BAROC slot Required or optional
ResourceId (source) mc_tool_id optional
ReconciliationIdentity mc_smc_id recommended
Alias mc_smc_alias recommended
ComponentHost mc_host required
ComponentHostAddress mc_host_address required
Location mc_location optional
ComponentURI mc_object_uri optional
ComponentCaption mc_object recommended
320 BMC Knowledge Base Development Reference Guide
Mapping quick reference: CEM to BAROC (CORE_EVENT)
BMC recommends that you use ReconciliationIdentity (mc_smc_id) and Alias (mc_smc_alias) because they make it easier to track configuration items.
ComponentType mc_object_class recommended
ComponentOwner mc_object_owner optional
Table 227 CEM to BAROC: reporter information
CEM property BAROC slot Required or optional
ResourceId (reporter) mc_tool_id optional
ComponentHostAddress mc_tool_address required
ComponentURI mc_tool_uri optional
ComponentCaption mc_tool required
ComponentType mc_tool_class optional
EventTime mc_tool_time required
EventType mc_tool_rule optional
EventId mc_tool_key required
EventSeverity mc_tool_sev optional
EventSuggestion mc_tool_suggestion optional
Table 228 CEM to BAROC: situation information
CEM property BAROC slot Required or optional
SituationCategory mc_event_category required
SituationTime mc_incident_time required
Priority mc_priority optional
Severity severity required
Message msg recommended
Application mc_service optional
LongMessage mc_long_msg optional
RepeatCount repeat_count optional
Table 229 CEM to BAROC: metric information
CEM property BAROC slot Required or optional
MetricName mc_parameter optional
MetricValue mc_parameter_value optional
MetricValueUnit mc_parameter_unit optional
MetricThreshold mc_parameter_threshold optional
Table 226 CEM to BAROC: source information (part 2 of 2)
CEM property BAROC slot Required or optional
Chapter 9 Common Event Model 321
Guidelines for applying CEM
Guidelines for applying CEMThis section provides some high-level guidelines for using CEM.
Associating events with configuration items
You can customize your CEM-enabled integration to create configuration item (CI) instances in the BMC Atrium CMDB that represent your integration’s service model components. If your CEM-enabled integration is going to create its unique configuration item (CI) instances in the BMC Atrium CMDB, then follow these guidelines:
■ 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:
■ 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 BMC Knowledge Base Development Reference Guide
Root cause
Root cause
The CEM base class does not store this information. However, you can either
■ 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.
Adding attributes vs. adding generic slots
Instead of adding generic slots to the CEM, BMC recommends that you add meaningful attributes to the extended classes that you have derived from CEM.
The problem with adding generic slots is that their semantics are not easily defined and standardized so that all applications understand the generic slots.
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
■ component’s location■ reporter’s 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.
Table 230 EventInformation::EventToCIAssociationType parameter values
Value Description
0 MRL rules determine whether the event attaches to the CI
1 a default rule attaches this particular event to a CI
2 event does not impact the component status
Chapter 9 Common Event Model 323
Event synchronization
Event synchronization
To synchronize events with a third-party management system, you need to identify the
■ 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.
CEM property groupingsThis section lists and defines the parameters of the different CEM property groupings. Each CEM property corresponds to a specific CORE_EVENT slot.
General properties
The general property group contains metadata information about the event.
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.
Table 231 ReportTime (optional)
Property name ReportTime
BAROC name mc_incident_report_time
Description date and time when the event was reported by the reporting object
Data type integer
Format UTC
Example 1151651591
324 BMC Knowledge Base Development Reference Guide
General properties
Table 232 EventModelVersion (required)
Property name EventModelVersion
BAROC name mc_event_model_version
Description version of the Common Event Model (CEM) that is used to instantiate the event
Data type string
Format xx, yy, zz
Example 1.1.00
Table 233 EventClass (required)
Property name EventClass
BAROC name CLASS
Description
event class name as defined by the CEM. Internally, this is the class name that is used to create the event. Each event provider should use its own value so that specific rules can be written for the designated event provider.
Data type String
Format Event_ClassName
Example BMC_MVEvent
Table 234 EventId (required)
Property name EventId
BAROC name mc_ueid
Descriptionglobally unique identifier of the event. If the mc_ueid is not defined, then it is automatically generated by the first cell that receives the event.
Data type String
Format
<ProductPrefix><separator><mc_tool_id><separator><mc_tool_key>
You can choose which <separator> to use.
Example BPM:BPMPrimary:12345abcd
Table 235 Status (optional)
Property name Status
BAROC name mc_status
Description a specified listing of distinct object states. The default status value is OPEN.
Data type
ENUMERATION. The values are
■ OPEN■ ACK■ ASSIGNED■ CLOSED ■ BLACKOUT
Chapter 9 Common Event Model 325
General properties
Format Enumeration
Example OPEN
Table 236 Timeout (optional)
Property name Timeout
BAROC name mc_timeout
Description specified timeout period in seconds after which an event is automatically closed
Data type Integer
Format Integer
Example 300
Table 237 Notes (optional)
Property name Notes
BAROC name mc_notes
Description a list of free text annotations that are added to an event
Data type LIST_OF strings
Format Unicode text
Example
Comment this.Comment that.Comment the other.
Table 238 EventToCIAssociationType (optional)
Property name EventToCIAssociationType
BAROC name mc_smc_impact
Description
indicates the impact type and whether this event is used in the status computation of the configuration item
By populating the mc_smc_alias, you can associate an event with a configuration item. However, the event may not affect the status computation of the configuration item. You must attach the event to the configuration item to affect its status computation.
Data type
integer. Valid values are
■ 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
Format integer
Example 0
Table 235 Status (optional)
326 BMC Knowledge Base Development Reference Guide
General properties
PropagationHistory is required only if the provider wants to receive its synchronized events back from the cell.
RelationSource is required if the consumer object wants to send or receive updates.
Table 239 PropagationHistory (required)
Property name PropagationHistory
BAROC name mc_history
Description
list of cells and the event Ids inside each cell through which the received event flowed before it reached the current cell. An event provider can define this slot so that it can receive the synchronized events back from the cell.
Data type LIST_OF string
Format <gateway_name>:0
Example [BiiOVO1:0]
Table 240 RelationSource (required)
Property name RelationSource
BAROC name mc_relation_source
Description contains the mc_ueid of the source event to which the current event is related
Data type string
Format
<ProductPrefix><separator><mc_tool_id><separator><mc_tool_key>
You can choose which <separator> to use.
Example BPM:BPMPrimary:12345abcd
Table 241 Owner (optional)
Property name Owner
BAROC name mc_owner
Description current user assigned to the event
Data type string
Format text
Example Pablo
Chapter 9 Common Event Model 327
Source component properties
Source component properties
The source component property group applies to the source component that is associated with the event. This property group, but not all of its members, is required.
Table 242 Account (optional)
Property name Account
BAROC name mc_account
Descriptionidentification of the account associated with the event. (This slot does not support multi tenancy.)
Data type String
Format text
Example Account1
Table 243 ResourceId (optional)
Property name ResourceId
BAROC name [for future development]
Description
unique identifier of the manageable resource on which the event has occurred. This id is different from the BMC Atrium CMDB Reconciliation ID or the alias.
Do not use the ResourceId to associate events with CIs. Instead use the reconciliation ID or the alias.
Data type string
Format GUID
Example SJSC_GICT0002.j17rul.00004
Table 244 ReconciliationIdentity (recommended)
Property name ReconciliationIdentity
BAROC name mc_smc_id
Description
identifier of a manageable resource associated with an event and is used to associate the event with a configuration item. BMC recommends that this value be the reconciliation Id value generated by the BMC Atrium CMDB.
Data type string
Format ReconciliationId
Example OS-838310E3AEF4168FC895B883ADC8F7
328 BMC Knowledge Base Development Reference Guide
Source component properties
Table 245 Alias (recommended)
Property name Alias
BAROC name mc_smc_alias
Description
identifier of a manageable resource associated with an event. BMC recommends that this value be taken from the alias defined in the BMC Atrium CMDB. This property helps to associate the event to the configuration item. Generally, event providers supply this value with the component’s alias value.
Data type String
Format <ProductPrefix>:<GUID>
Example BPM:838310E3AEF4168FC895B883ADC8F7
Table 246 ComponentHost (required)
Property name ComponentHost
BAROC name mc_host
DescriptionFully-qualified host name of the system on which the problem occurred. The ComponentHost is required in the ComponentHostAddress is not specified.
Data type String
Format fully qualified domain name
Example opensource.adprod.bmc.com
Table 247 ComponentHostAddress (required)
Property name ComponentHostAddress
BAROC name mc_host_address
Description
Network address for the host on which the problem occurred. It can be used to supplement the value of the ComponentHost property. The ComponentHostAddress is required if the ComponentHost property is not specified.
Data type String
Format IP address/type
Example 192.168.0.100
Table 248 Location (optional)
Property name Location
BAROC name mc_location
Descriptionlocation at which the source component resides. This slot provides additional contextual information for the event.
Data type String
Format Text
Example SJ1-DC1
Chapter 9 Common Event Model 329
Source component properties
Component address properties
This is a subset of the source component properties. These slots designate the address of the source component. The component address properties can represent alternate addresses of the source component.
Table 249 ComponentURI (optional)
Property name ComponentURI
BAROC name mc_object_uri
Description the address that can be used to cross launch directly into a component
Data type String
Format URI
Example http://192.168.175.149/ews/index.htm
Table 250 ComponentCaption (recommended)
Property name ComponentCaption
BAROC name mc_object
Description
A text representation of the subcomponent of the host to which the event is related. This property is the equivalent of the Name attribute of BMC_BaseElement in the Common Data Model.
Note: If the BMC Atrium CMDB is populated correctly, the Name attribute is also available as a property of the CI data element in SIM.
Data type string
Format text; or the in the CDM, the name format
Examplehou-ex-04.adprod.bmc.com192.168.0.100:Microsoft Exchange Server
Table 251 ComponentType (recommended)
Property name ComponentType
BAROC name mc_object_class
Description identifies the class name of the source component
Data type string
FormatCDM class name. If the CDM class name is unknown, you can use a user-defined categorization of the source component.
Example BMC_ComputerSystem
330 BMC Knowledge Base Development Reference Guide
Reporter component properties
Reporter component properties
The reporter component is simply the component that reports the event, not necessarily the source of the event. The reporter component is required when the reporter component is different from the source component, from which the event originated. If the reporter component property is not declared, you can assume that source and reporter components are the same.
Event reporting and event monitoring
The cell can distinguish between an event monitor and an event reporter. An event monitor is a component that detects the event. It is not the source of the event, nor does it report the event. An event reporter component reports the event.
An event can have multiple event reporter components, but only one event monitor component. The cell uses the following optional slots to record event monitoring information.
Table 252 ComponentOwner (optional)
Property name ComponentOwner
BAROC name mc_object_owner
Description identifies the owner of the source component
Data type string
Format text
Example APAC_IT
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.
Table 253 Slots for event monitoring information (part 1 of 2)
Slot Description
mc_origin specifies the event management system that is “closest” to the source of the event and is deemed to have detected the event
mc_origin_address network IP address of the event management system
Chapter 9 Common Event Model 331
Reporter component properties
Slots that begin with the mc_origin prefix follow the same format as slots that begin with mc_tool.
Component address properties for reporting
These are component address elements for the reporting component:
mc_origin_key unique identifier of the event in the event monitor component. It is often the same as the eventId of the event management system that detected the event
mc_origin_sev severity of the event defined by the event monitor component. The severity is internal to the component and does not map to CEM severity values.
Table 254 ResourceId (optional)
Property name ResourceId
BAROC name mc_tool_id
Description identifies a manageable resource (component) that reports an event
Data type string
Format text
Example BPMPrimary
Table 255 ComponentHostAddress (required)
Property name ComponentHostAddress
BAROC name mc_tool_address
Description network address of the reporter component
Data type string
Format IP address/text
Example 192.168.0.100
Table 256 ComponentURI (optional)
Property name ComponentURI
BAROC name mc_tool_uri
Description address that can be used to cross-launch to the reporter component
Data type string
Format URI
Example http://192.168.175.149/ews/index.htm
Table 253 Slots for event monitoring information (part 2 of 2)
Slot Description
332 BMC Knowledge Base Development Reference Guide
Reporter component properties
Table 257 ComponentCaption (required)
Property name ComponentCaption
BAROC name mc_tool
Description object that reports the event
Data type string
Format text
Example HPVOInst1
Table 258 ComponentType (optional)
Property name ComponentType
BAROC name mc_tool_class
Description user-defined categorization of the object that reports the event
Data type string
Format text
Example BPM Portal Server
Table 259 EventTime (required)
Property name EventTime
BAROC name mc_tool_time
Descriptiontime that the reporter component received the event. This is the reporter time translated into epoch time.
Data type integer
Format coordinated universal time (UTC)
Example 1110637098173
Table 260 EventType (optional)
Property name EventType
BAROC name mc_tool_rule
Description condition that triggers the event
Data type string
Format text
Example CPU usage high
Chapter 9 Common Event Model 333
Reporter component properties
Table 261 EventId (required)
Property name EventType
BAROC name mc_tool_key
Descriptionunique identifier of the event in the Reporter. This identifier is usually the event id assigned to the event by the system that detected the event.
Data type string
Format text
Example 3eb61c54-0806-71db-0009-8948e4720000
Table 262 EventSeverity (optional)
Property name EventSeverity
BAROC name mc_tool_sev
Descriptionthe severity level as defined by the reported component. This severity level does not map to the BEM or BMC SIM severity levels.
Data type string
Format text
Example critical
Table 263 EventSuggestion (optional)
Property name EventSuggestion
BAROC name mc_tool_suggestion
Description predefined text suggestion for solving the situation described by the event
Data type string
Format text
Example Expert advice in PATROL
334 BMC Knowledge Base Development Reference Guide
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 SituationCategory
BAROC name mc_event_category
Descriptionthe Information Technology Infrastructure Library (ITIL) process that the event represents
Data type
ENUMERATION (MC_EVENT_CATEGORY)
Possible values include
■ 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
Format ENUMERATION
Example SLA
Table 265 Situation category (mc_event_category) values (part 1 of 3)
ITIL category Description
SLA_MANAGEMENT events relating to the Service Level Agreement Management process. The process covers planning, coordinating, drafting, agreeing, 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 something about capacity (for example, disk full) or performance (Transactions/sec) should be categorized as Capacity Management events.
Chapter 9 Common Event Model 335
Situation properties
SERVICE_CONTINUITY_MANAGEMENT
events relating to the Service Continuity Management process. The process covers supporting 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 required, and agreed, business timescales.
AVAILABILITY_MANAGEMENT events relating to the Availability Management process. The process is about 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 Management events.
INCIDENT_MANAGEMENT events relating to the Incident Management process. The process is about restoring normal service operation as quickly as possible and minimize the adverse impact on business operations, thus ensuring that the best possible levels of service quality and availability are maintained
CONFIGURATION_MANAGEMENT events relating to the Configuration Management process. The process of identifying and defining Configuration Items in a system, recording and reporting the status of Configuration Items and Requests for Change, and verifying 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 Problem Management is to minimize the adverse impact of Incidents and Problems on the business that are caused by errors within the IT Infrastructure, and to prevent recurrence of Incidents related to these errors. In order to achieve this goal, Problem Management seeks to get to the root cause of Incidents and then initiate actions to improve or correct the situation.
CHANGE_MANAGEMENT The events relating to the Change Management process. The process of controlling 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 Operations Management process. The process is concerned not solely with the incidents reported by users, but with events generated by or recorded by the infrastructure.
SECURITY_MANAGEMENT The events relating to the Security Management process. The process that consists of activities that are carried out by the Security Management itself or activities that are controlled by the Security Management. Events related to Identity Management as well as events reporting security breaches fall into this category
Table 265 Situation category (mc_event_category) values (part 2 of 3)
ITIL category Description
336 BMC Knowledge Base Development Reference Guide
Situation properties
FINANCIAL_MANAGEMENT The events relating to the Financial Management process. The process which deals with accounting for IT usage. It is used to plan, control and recover costs expended in providing the IT Service negotiated and agreed to in the SLA.
SERVICE_DESK_MANAGEMENT The events relating to the Service Desk Management process. The process to manage the Service Desk itself.
Table 266 SituationTime (required)
Property name SituationTime
BAROC name mc_incident_time
Description
time when the event occurred, translated into epoch time to accommodate the requirements of the cell
Internally the impact manager works with epoch time. Doing the translations over and over again when needed would have an impact of efficiency. Therefore we ask the providers to calculate once the epoch time, so processing of time-related information is as optimal as possible.
Data type integer
Format coordinated universal time (UTC)
Example 1110637098173
Table 267 Priority (optional)
Property name Priority
BAROC name mc_priority
Description
represents the importance of an event. This slot supports management functions requiring an event to be associated with a priority. Valid values in ascending order of significance are:
■ PRIORITY_5■ PRIORITY_4■ PRIORITY_3■ PRIORITY_2■ PRIORITY_1
PRIORITY_1 is the highest priority.
Data type ENUMERATION (MC_PRIORITY)
Format Enumeration
Example PRIORITY_1
Table 265 Situation category (mc_event_category) values (part 3 of 3)
ITIL category Description
Chapter 9 Common Event Model 337
Situation properties
Table 268 Severity (required)
Property name Severity
BAROC name mc_severity
Description
Represents the perceived severity of the status the event is describing with respect to the application that reports the event.
Current values
■ UNKNOWN■ OK■ INFO■ WARNING■ MINOR■ MAJOR■ CRITICAL
Data type ENUMERATION (MC_SEVERITY)
Format Enumeration
Example Major
Table 269 Message (recommended)
Property name Message
BAROC name mc_message
Descriptiondescriptive text that is part of an event. BMC recommends a terse description of the event content.
Data type string
Format text (Unicode)
Example This component is down.
Table 270 Application (optional)
Property name Application
BAROC name mc_service or mc_application
Description
service or application to which the event is related. Use this slot to add contextual information about the service or application to the event. The value of this slot would be typically set by “enrichment.”
Data type string
Format text
Example OracleListener
338 BMC Knowledge Base Development Reference Guide
Metric properties
Metric properties
Metric properties are optional. However, if you do use the metric definition, you must include all related metric properties.
Table 271 LongMessage (optional)
Property name LongMessage
BAROC name mc_long_message
Description
descriptive text that is part of an event. BMC recommends that you use this slot to convey additional relevant information about the event. Do not include any MRL rules.
Data type string
Format text (Unicode)
Example this event is enriched
Table 272 RepeatCount (optional)
Property name RepeatCount
BAROC name mc_repeat_count
Description number of time that this incident described in the event has occurred
Data type integer
Format integer
Example 4
Table 273 MetricName (optional)
Property name MetricName
BAROC name mc_parameter
Description name of the metric parameter that went into alarm or that triggered the event
Data type string
Format Unicode text
Example HardDiskUsage
Table 274 MetricValue (optional)
Property name MetricValue
BAROC name mc_parameter_value
Description value of the metric
Data type string
Format Unicode text
Example 80
Chapter 9 Common Event Model 339
Metric properties
Table 275 MetricValueUnit (optional)
Property name MetricValueUnit
BAROC name mc_parameter_unit
Description unit description of the metric
Data type string
Format Unicode text
Example %
Table 276 MetricThreshold (optional)
Property name MetricThreshold
BAROC name mc_parameter_threshold
Description threshold value that was exceeded and result in the generation of the event
Data type string
Format Unicode text
Example 75
340 BMC Knowledge Base Development Reference Guide
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
AAbstract rules
described 276examples 278phase described 36primitives 278syntax 277When clause 237
action blocks 227action-related primitives and functions 107actions
directory 24adapter_host slot 63administrator slot 63ALL keyword
Using clause 235angle brackets, usage in BAROC 46ANY argument type
decribed 83, 106apache.baroc file 60argument types
ANY 83, 106ENUM 83, 106for primitives and functions 83, 106INTEGER 83, 106LIST_OF 83, 106OBJECT 106POINTER 106REAL 83, 106
SLOTREF 106STRING 83, 106
asterisk (*), usage in BAROC 46
BBAROC
asterisk 46brackets 46compiling and loading files 58identifiers 46language symbols 46language syntax 46
base classesCORE_EVENT 49
based_on slot 77BEM_MATCH_TABLE
data class 74pattern matching 75processing 75
bem_match_table.baroc file 60bii4p.baroc file 60bii4p_collectors.mrl file 308bin directory 22BMC Impact Manager
class files 60roles 301
BMC Portaldefining roles for collectors 306
BMC Software, contacting 2Body clause
in rules 239syntax 239
bracesto delimit action blocks 227
bracketsrequired for primitive arguments 227usage in BAROC 46
Ccatchall_collector.mrl file 306cell 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 284CELL_DATE variable 284cell_location slot 69cell_name slot 69CELL_NAME variable 284CELL_RELEASE variable 284cells
sending events to 249starting and stopping 27
character casefor MRL 227
class hierarchy 62class instances
defining 55CLASS variable 284class_name slot 254classes
CORE_DATA 72, 73CORE_EVENT 62, 63data hierarchy 72defining 47definition examples 56directory 22files for 60syntax for defining 47
clausesBody 239conditions for Using 234Unless 236Using 233When 237Where 230
collector keyword 299collectors
bii4p_collectors.mrl 308catchall_collector.mrl 306creating 298defaults for event management 306defaults for service impact management 309directory 23, 24, 298expression 300mc_bylocation_collectors.mrl 307mc_bystatus_collectors.mrl 307mc_evr_collectors.mrl 309MCxP 308MCxP collector set 308naming 299permissions 299, 302roles 299, 301security 301self_collector.mrl 306static 303syntax 298, 300
commandsmccomp 26, 248mcontrol 26mcrtcell 25
342 BMC Impact Event Adapters User Guide
mgetinfo 28mkb 25msend 249
Common Event Model (CEM)adding attributes 323associating events with CIs 322BMC_BaseEvent class 318component address elements 332component address properties 330CORE_EVENT class 318data types 319description 317event reporting 331event synchronization 324general properties 324I18N 320ITIL processes 335mapping to Baroc 320mapping to CORE_EVENT 320mc_event_category 335mc_event_category values 335metric properties 339property groupings 319reporter component properties 331root cause 323situation properties 335source component properties 328versioning 319
compilingBAROC 58Knowledge Bases 26Knowledge Bases with trace 26rules 248version annotations 28
condition operatorsfor Where clauses 231, 232
conditionsfor Using clause 234
confirm_external() primitivein Refine rules 261
conventionsfor MRL 226
CORE_DATA class 49, 72, 73CORE_EVENT base class 49, 63CORE_EVENT class 62Correlate rules
described 279examples 281phase described 36primitives 281syntax 280When clause 237
Create clausesin collectors 299
creatingcollectors 298Knowledge Bases 25
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
Ddata
defining indexes for 234dynamic 242retrieving in rules 229
data classesBEM-MATCH_TABLE 74CORE_DATA 49, 73defining 47definition example 57directory 23hierarchy 72MC_CALENDARING 73MC_SM_DATA class 73metaclass 48POLICY 77SCHEDULE 74SELECTOR 77TIME_FRAME 74TIME_ZONE 74universal identifier 50
data directory 23data instances
directory 23retrieving with Using clause 233
data typesdescribed 82ENUM 82EnumName 49INT32 49INTEGER 49, 82LIST_OF 49POINTER 49, 82REAL 49, 82SIMPLE 49STRING 49, 82Tivoli TEC 49
data_handle slot 73date slot 63date_reception slot 63declaring variables 241default facet, described 51defining
class instances 55classes 47classes, examples 56dynamic collectors 304global records 58indexes 246static collectors 303
Delete clausesin collectors 299
Delete rules
described 294examples 294phase described 36primitives 294syntax 294
deprecated slots 255substitution 79
description slot 77directories
bin 22classes 22collector 298collectors 23data 23for KB components 23lib 23record 23rules 23structure for Knowledge Bases 21
dup_detect facet, described 51duration slot 63dynamic collectors
defining 304roles 305specifying 299
dynamic datacreating New rule for 274retrieving in rules 233using in rules 242
Eea_event.baroc file 60ECFs
in collectors 300Where clause 230
ecfs slot 77ecfs_descr slot 77enabled slot 77END keyword 227ENUM argument type
described 83, 106enumerations
internal 52MC_EVENT_CATEGORY 53MC_EVENT_SUBCATEGORY 55MC_PRIORITY 53MC_YESNO 55SEVERITY 52STATUS 52syntax 51
EnumName data type 49error_code slot 255error_column slot 254error_goal slot 255error_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, 255error_source slot 255errors
in event processing 255EVENT class 69event classes
CORE_EVENT 63definition example 56, 57directory 23EVENT 69hierarchy 62MC_CELL_CONTROL 69metaclass 48universal identifier 50
Event Condition Formulas, See ECFsevent management
collectors 306event policies
described 312MC_CALENDARING data class 73rules 314syntax 312
event processingerrors 255rule phases 35
event selection clausesdescribed 230
event selectorsdescribed 313
event slot 255event_handle slot 63event_text slot 254eventlog.baroc file 60events
defining classes 47defining indexes for 234MC_CELL_PARSE_ERROR 254MC_CELL_PROCESS_ERROR 255MC_CELL_UNDEFINED_CLASS 254MC_EVENT_CATEGORY enumeration 53MC_EVENT_SUBCATEGORY enumeration 55MC_PRIORITY enumeration 53MC_YESNO enumeration 55referencing a particular slot in rules 227retrieving with Using clause 233selecting in rules 230sending to a cell 249SEVERITY enumeration 52STATUS enumeration 52undefined 253
Execute rulesdescribed 283environment variables 284examples 285phase described 36primitives 285syntax 283
344 BMC Impact Event Adapters User Guide
When clause 237expressions
in collectors 300
Ffacets
default 51described 50dup_detect 51hidden 51key 51parse 51read_only 51representation 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, 249apache.baroc 60bem_match_table.baroc 60bii4p.baroc 60bii4p_collectors.mrl 308catchall_collector.mrl 306ea_event.baroc 60eventlog.baroc 60extensions for KB components 23for classes 60im_policies.baroc 60ips.baroc 60loading BAROC 58manifest.kb 24mc_bylocation_collectors.mrl 307mc_bystatus_collectors.mrl 307mc_deprecated_filter.baroc 60mc_deprecated_kb_data.baroc 60mc_deprecated_notification.baroc 60mc_deprecated_propagation.baroc 60mc_evr_collectors.mrl 309mc_evtdata_internal.baroc 60mc_root_internal.baroc 48, 60mc_root_redef.baroc 60, 78mc_sm_cost.baroc 61mc_sm_custom.baroc 61mc_sm_event_mapping.baroc 61mc_sm_maintenance.baroc 61mc_sm_notifiy.baroc 61mc_sm_object.baroc 61mc_sm_propagation.baroc 61mc_sm_root.baroc 61mc_sm_slm.baroc 61mc_tec_severity.baroc 61
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 61mcxa.baroc 61mcxp.baroc 61MRL 226patrol_em.baroc 61patrol_portal.baroc 61ppm_classes.baroc 61self_collector.mrl 306sim.wic 23sim_decl.wic 23state_change.baroc 61
Filter rulesdescribed 262examples 265phase described 35primitives 264processing during phase 263syntax 263
find_match() function and primitivecreating BEM_MATCH_TABLE 74
functionsin Body clause 239
functions and primitivesargument types 83, 106overview 106
Ggeneric rule, creating 274get_external() primitive
in Refine rules 261global records
defining 58directory 24syntax 244using in rules 243
Hhashed indexes
described 246hidden facet, described 51HOME variable 284
Iidentifiers, usage in BAROC 46if-then-else construct 240im_policies.baroc file 60importing Knowledge Bases 25indexes
defining 246defining on events and data 234in Using clause 247using in rules 246
input_match slot 74instances
defining 55of interface classes 245querying 234syntax for definitions 55
INT32 data type 49INTEGER argument type
described 83, 106INTEGER data type 49interface classes
defining 47definition example 57directory 24metaclass 48
interfacesinstances 245syntax in rule 245using in rules 244
internal enumerations 52ips.baroc file 60
Kkbmodules argument 28kbsources argument 28kbversion primitive
described 28key facet, described 51Knowledge Bases
compiling 26compiling with trace 26creating 25directories 23directory structure 21file extensions 23importing 25index file 24integrating with a unified KB 25loading 26managing 24retrieving version information with kbversion 28retrieving version information with mgetinfo 28subdirectories 22versioning 27versioning mechanism 27
Llib directory 23limit for literal strings 227LIST_OF argument type
described 83, 106LIST_OF data type 49literal 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 227single quotes 226
loadingBAROC files 58Knowledge Bases 26
LOGNAME variable 284
Mmanaging
Knowledge Bases 24manifest.kb file 24mc_abstracted slot 63mc_abstraction slot 63mc_account slot 63mc_acl slot 63mc_action_count slot 63mc_arrival_time slot 63mc_associations slot 63mc_bad_slot_names slot 64mc_bad_slot_values slot 64mc_bylocation_collectors.mrl file 307mc_bystatus_collectors.mrl file 307MC_CALENDARING class 73mc_cause slot 64MC_CELL_CONTROL class 69MC_CELL_PARSE_ERROR
event 254slots 254
MC_CELL_PROCESS_ERRORevent 255slots 255
MC_CELL_UNDEFINED_CLASSevent 254slots 254
mc_client_address slot 64mc_collectors slot 64mc_creation_time slot 73MC_DATA_CLASS metaclass 48mc_date_modification slot 64mc_deprecated_filter.baroc file 60mc_deprecated_kb_data.baroc file 60mc_deprecated_notification.baroc file 60mc_deprecated_propagation.baroc file 60mc_effects slot 64MC_EV_CLASS metaclass 48MC_EVENT_CATEGORY enumeration 53mc_event_category slot 64mc_event_model_version slot 64mc_event_relations slot 64MC_EVENT_SUBCATEGORY enumeration 55mc_evr_collectors.mrl file 309mc_evtdata_internal.baroc file 60mc_history slot 64mc_host slot 64mc_host_address slot 65
346 BMC Impact Event Adapters User Guide
mc_host_class slot 65mc_incident_report_time slot 65mc_incident_time slot 65MC_INTERFACE metaclass 48mc_local_reception_time slot 65mc_location slot 65mc_modhist slot 65mc_modification_time slot 73mc_notes slot 65mc_notification_history slot 65mc_object slot 65mc_object_class slot 66mc_object_owner slot 66mc_object_uri slot 66mc_operations slot 66mc_origin slot 66mc_origin_class slot 66mc_origin_key slot 66mc_origin_sev slot 66mc_original_priority slot 66mc_original_severity slot 66mc_owner slot 66mc_parameter slot 67mc_parameter_threshold slot 67mc_parameter_unit slot 67mc_parameter_value slot 67MC_PRIORITY enumeration 53mc_priority slot 67mc_propagations slot 67MC_PUBLISH_DATA_CLASS metaclass 48mc_relation_source slot 67mc_root_internal.baroc file 48, 60mc_root_redef.baroc file 60mc_root_redef.baroc files 78mc_service slot 67mc_sm_cost.baroc file 61mc_sm_custom.baroc file 61MC_SM_DATA class 73mc_sm_event_mapping.baroc file 61mc_sm_maintenance.baroc file 61mc_sm_notify.baroc file 61mc_sm_object.baroc file 61mc_sm_propagation.baroc file 61mc_sm_root.baroc file 61mc_sm_slm.baroc file 61mc_smc_id slot 67mc_smc_impact slot 67mc_smc_priority slot 67mc_smc_type slot 67mc_tec_severity.baroc file 61mc_timeout slot 68mc_tool slot 68mc_tool_address slot 68mc_tool_class slot 68mc_tool_key slot 68mc_tool_rule slot 68mc_tool_sev slot 68
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 68mc_tool_time slot 68mc_tool_uri slot 68mc_udid slot 50, 73mc_ueid slot 50, 69MC_YESNO enumeration 55mccomp command 26, 248mccs.baroc file 61MCELL_HOME environment variable 284mcontrol command 26mcrtcell command 25mcxa.baroc file 61MCxP collector set 308mcxp.baroc file 61metaclasses
described 48MC_DATA_CLASS 48MC_EV_CLASS 48MC_INTERFACE 48MC_PUBLISH_DATA_CLASS 48TEC_CLASS 48
mgetinfo command 28mkb command 25ModuleName parameter 27MRL
character case 227conventions 226END keyword 227files 226syntax 227variable names 227
msend command 249msg slot 69
Nname slot 74, 77naming
collectors 299New rules
creating for dynamic data 274described 270examples 273phase described 35primitives 273syntax 272
newline charactersin slot values 227
NOPASS mode 262
OOBJECT argument type
described 106output_expressions slot 74
Pparse facet, described 51PASS mode 262patrol_em.baroc file 61patrol_portal.baroc file 61pattern matching 75permissions
for collectors 299, 302phases
of event processing 35PKG_NAME variable 284plus sign (+), usage in BAROC 46POINTER argument type
described 106POINTER data type 49POLICY class
described 77syntax 312
pound sign (#), usage in BAROC 46ppm_classes.baroc file 61primitives
argument syntax 227in Body clause 239
primitives and functionsaction-related 107argument types 83, 106overview 106
product support 3Propagate rules
described 289examples 291phase described 36primitives 291syntax 290When clause 237
publishing metaclass 48
Qquery clause, in rules 229quotation marks
for literal strings 226
Rread_only facet 51REAL argument type
described 83, 106REAL data type 49records directory 23ref_instances_classes slot 74Refine rules
described 259examples 261
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 35primitives 261processing during phase 259syntax 260using interfaces in 245
Regulate rulesdescribed 266examples 268forms of 266phase described 35primitives 268processing during phase 266syntax 267
repeat_count slot 69representation facet, described 51REQUESTOR variable 284roles
collector access 299in BMC Impact Manager 301in collectors 301in dynamic collectors 305
rule phasesdescribed 35illustrated 35
RULE_NAME variable 284rules
body 229Body clause 239compiling 248directory 23, 24ending 227event processing phases 35for event policies 314global records 243if-then-else construct 240query clause 229querying instances 234retrieving data 229selecting events 230syntax 227testing 249tracing 249Unless clause 236Using clause 233using dynamic data 242using indexes 246using interfaces 244using variables in 241When clause 237Where clause 230writing 226
SSCHEDULE data class 74scripts and programs directory 24
348 BMC Impact Event Adapters User Guide
securityfor collectors 301
selection criteriain rules 230
SELECTOR classdescribed 77syntax 313
selectorsdescribed 313syntax 313
self collectorsfile 306
self keyword 299self_collector.mrl file 306sending
events to a cell 249service impact management
collectors 309service models
class definitions directory 24publishing metaclass 48
SEVERITY enumeration 52severity slot 69SHELL variable 284sim.wic file 23sim_decl.wic file 23SIMPLE data type 49single quotes
for cell names 226for literal strings 226
slot assignmentsin Body clause 239
slot facets, See facetsslot values
newline character 227SLOTREF argument type
described 106slots
adapter_host 63administrator 63based_on 77cell_location 69cell_name 69data_handle 73date 63date_reception 63defining enumerations 51deprecated substitution 79description 77duration 63ecfs 77ecfs_descr 77enabled 77event_handle 63input_match 74mc_abstracted 63mc_abstraction 63
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 63mc_acl 63mc_action 63mc_arrival time 63mc_associations 63mc_bad_slot_names 64mc_bad_slot_value 64mc_cause 64MC_CELL_PARSE_ERROR 254MC_CELL_PROCESS_ERROR 255MC_CELL_UNDEFINED_CLASS 254mc_client_address 64mc_collectors 64mc_creation_time 73mc_date_modification 64mc_effects 64mc_event_category 64mc_event_model_version 64mc_event_relations 64mc_history 64mc_host 64mc_host_address 65mc_host_class 65mc_incident_report_time 65mc_incident_time 65mc_local_receptions_time 65mc_location 65mc_modhist 65mc_modification_time 73mc_notes 65mc_notification_history 65mc_object 65mc_object_class 66mc_object_owner 66mc_object_uri 66mc_operations 66mc_orgin_key 66mc_orginal_severity 66mc_origin 66mc_origin_class 66mc_origin_sev 66mc_original_priority 66mc_owner 66mc_parameter 67mc_parameter_threshold 67mc_parameter_unit 67mc_parameter_value 67mc_priority 67mc_propagations 67mc_relations_source 67mc_service 67mc_smc_id 67mc_smc_impacts 67mc_smc_priority 67mc_smc_type 67mc_timeout 68mc_tool 68
mc_tool_address 68mc_tool_class 68mc_tool_key 68mc_tool_rule 68mc_tool_sev 68mc_tool_suggestion 68mc_tool_time 68mc_tool_uri 68mc_udid 73mc_ueid 69msg 69name 74, 77output_expressions 74ref_instances_classes 74referencing in rules 227repeat_count 69severity 69status 69syntax for defining 47tag 74types of 49
SLOTS variable 284sorted indexes
described 246spaces
in cell name 226starting cells
with mcell 27state_change.baroc file 61static collectors
defining 303STATUS enumeration 52status slot 69stopping cells
with mkill 27STRING argument type
described 83, 106STRING data type 49string length 227strings
character limit 227support, customer 3symbols
for BAROC language 46syntax
for BAROC language 46for Body clause 239for collectors 298, 300for enumerations 51for event policies 312for Filter rules 263for global records 244for instance definitions 55for interface rule 245for rules 227for variables 241of 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
Ttag slot 74TEC_CLASS metaclass 48technical support 3TERM variable 284testing
rules 249Threshold rules
described 286examples 288phase described 36primitives 288processing during phase 287syntax 288
TIME_FRAME data class 74TIME_ZONE data class 74timeframes
data class 73Timer rules
described 291examples 293phase described 36primitives 292processing during phase 292syntax 292
Tivoli TECdata type 49metaclass 48
tracingrules 249
transaction logsviewing 249
Uundefined events 253universal identifiers
for events and data 50mc_udid 50mc_ueid 50
Unless clausesin rules 236
unset_cause() primitivein Correlate rule 281
Using clausesALL keyword 235conditions 234in rules 229, 233indexes in 247
350 BMC Impact Event Adapters User Guide
Vvariables
CELL_BUILD 284CELL_DATE 284CELL_NAME 284CELL_RELEASE 284CLASS 284declaring 241HOME 284LOGNAME 284MCELL_HOME 284naming 227PKG_NAME 284REQUESTOR 284RULE_NAME 284SHELL 284SLOTS 284syntax 241TERM 284using in rules 241WINDOWID 284
VersionID parameter 27versioning
compiling 28Knowledge Bases 27mechanism 27retrieving version information with kbversion 28retrieving version information with mgetinfo 28
viewingtransaction logs 249
WWhen clauses
in rules 237Where clauses
condition operators 231, 232in collectors 300in rules 230
wildcardsBEM_MATCH_TABLE 75
WINDOWID variable 284writing rules 226
Notes
*106562**106562**106562**106562*
*106562*