You are on page 1of 408

BMC Impact Solutions:

Knowledge Base Development


Reference Guide

Supporting
BMC Impact Manager 7.2
BMC Impact Explorer 7.2
BMC Impact Portal 7.2

June 2008

www.bmc.com
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 INC Telephone 713 918 8800 or Fax 713 918 8000
2101 CITYWEST BLVD 800 841 2031
HOUSTON TX 77042-2827
USA
Outside United States and Canada
Telephone (01) 713 918 8800 Fax (01) 713 918 8000

© Copyright 2005-2008 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.
BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is
subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted
rights notices included in this documentation.

Restricted rights legend


U.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_home.
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 customer_support@bmc.com. (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 Impact Solutions: Knowledge Base Development User Guide
Contents
Chapter 1 Working with the Knowledge Base 19
What is a Knowledge Base? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Components of a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Unified Knowledge Base template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Knowledge Base directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Knowledge Base index files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Managing a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Creating a new production or test Knowledge Base—mcrtcell . . . . . . . . . . . . . . . 29
Importing Knowledge Base information into a cell—mkb . . . . . . . . . . . . . . . . . . . 29
Compiling a Knowledge Base—mccomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Loading a Knowledge Base into a running cell—mcontrol . . . . . . . . . . . . . . . . . . 30
Implementing changes to a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Versioning a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Enabling KB versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
KB versioning example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Retrieving KB version information in rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Retrieving KB version information by using a command—mgetinfo . . . . . . . . . . 32

Chapter 2 BAROC language fundamentals 35


BAROC overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
BAROC class inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
BAROC language syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
BAROC language symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Use of quotation marks in the BAROC language . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Class definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Metaclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Slot data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Universal event and data identifier slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Slot facets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Internal enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Class definition examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Class instance definition syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Class instance definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Global record definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Global record definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Loading and compiling BAROC modifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Contents 5
Chapter 3 Creating rules 51
Rules overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Incoming event processing by rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Internal event processing by rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Internal requests by a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Undefined events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Event processing errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Rule structure and syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
MRL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
MRL conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
General rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
MRL event selection clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Where clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Using clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Using_policy clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Unless clause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
When clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Body clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Variables in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Dynamic data in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Global records in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Interfaces in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Interface instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Indexes in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Using indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Relating events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Event relation definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Creating an event relation definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Compiling rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Testing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Tracing a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Configuring rule tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Customizing rule trace message headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Chapter 4 Creating collectors 89


Collector overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
How collectors are structured . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Creating or modifying a collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Collector syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Best practices for defining collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Collector security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Defining static collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Defining dynamic collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Default event management collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
self_collector.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
catchall_collector.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
mc_bystatus_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
mc_bylocation_collectors.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

6 BMC Impact Solutions: Knowledge Base Development Reference Guide


MCxP collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
bii4p_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
mc_evr_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Default service impact management event collector . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Chapter 5 Creating remote actions 105


Remote actions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Remote action execution methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Remote action result events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Location of remote actions and executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Remote action definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
File naming guidelines for action executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Defining a remote action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Remote action definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Remote action execution results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Action execution variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Defining a remote action in a BMC Impact Manager cell . . . . . . . . . . . . . . . . . . . 115

Appendix A Event and data classes 117


BMC Impact Manager class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Event class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
CORE_EVENT base event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
EVENT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
MC_CELL_CONTROL event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Data class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
CORE_DATA base class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
MC_SM_DATA data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
MC_CALENDARING data class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
BEM_MATCH_TABLE data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
POLICY data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
SELECTOR data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Cell information class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Deprecated slots and their replacements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Appendix B Master Rule Language (MRL) reference 137


Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Integer data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Enumeration data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Condition operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Condition operators to test ordering conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Condition operators to test range conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Condition operators to test match conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Condition operators to test conditions on IP addresses . . . . . . . . . . . . . . . . . . . . 150
Condition operators to test class hierarchy conditions . . . . . . . . . . . . . . . . . . . . . 153
Expression operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Contents 7
MRL functions and primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Primitives and functions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Action-related primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Value type conversion primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Mathematical functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Enumeration operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
String manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Time stamp functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
List operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Match table lookup primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Object slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Specific slot manipulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Object relation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Operation environment inquiry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Propagation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Service model inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
License key functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Time frame operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Object creation and deletion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Specific rule-based functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Appendix C Event rules and syntax 275


Refine rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Refine rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Refine rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Refine rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Refine rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Filter rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Filter rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Filter rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Filter rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Filter rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Regulate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Regulate rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Forms of the Regulate rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Regulate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Regulate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Regulate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
New rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
New rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
New rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
New rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Abstract rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Abstract rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Abstract rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Correlate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Correlate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Correlate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

8 BMC Impact Solutions: Knowledge Base Development Reference Guide


Correlate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Execute rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Execute rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Threshold rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Threshold rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Threshold rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Propagate rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Propagate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Propagate rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Propagate rules examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Timer rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Timer rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Timer rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Timer rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Timer rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Delete rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Delete rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Delete rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Delete rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Appendix D Default rule sets 313


Event management rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
bii4p.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
im_internal.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
ips.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
mc_deprecated_filter.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
mc_deprecated_notification.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
mc_deprecated_propagation.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
mc_deprecated_schedules.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
mc_intevt.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
mc_mccs.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
mc_startup.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
mcxp.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Service impact management rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
mc_sm_associate.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
mc_sm_attach.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
mc_sm_elect.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
mc_sm_maintenance.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
mc_sm_shadow.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
mc_sm_slm.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
mc_sm_start.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Appendix E Policy and selector syntax 325


Event policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Contents 9
Event selectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Event processing rules for policy types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Format of event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . 328
How a rule for a policy type is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Appendix F Environment variables 331


Microsoft Windows environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Recreating environment variables on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
UNIX environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Recreating environment variables on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Appendix G Common Event Model 335


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Versioning support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Internationalization compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Mapping quick reference: CEM to BAROC (CORE_EVENT) . . . . . . . . . . . . . . . . 338
Guidelines for applying CEM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Associating events with configuration items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Root cause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Adding attributes vs. adding generic slots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Cross-launching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Event synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Free-format text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
CEM property groupings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Source component properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Reporter component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Situation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Metric properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Glossary 359

Index 393

10 BMC Impact Solutions: Knowledge Base Development Reference Guide


Figures
Knowledge Base directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Output from mgetinfo kbsources argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Enumeration definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Class hierarchy definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Superclass definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Subclass definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Data class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Interface class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Event processing in the rule phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Event selection criteria example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Execute rule using dynamic data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Interface instance example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Event relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Collectors in BMC Impact Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Collector definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Collector tree definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Static collector example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Static collector example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Self collector definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Catchall collector definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
MC_SMC_EVENTS collector definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Action rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Example of a specified role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Action argument syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Primitive to perform an action from a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Example of exit code that returns a specified value . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Example of exit code that returns an argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
CORE_EVENT class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
CORE_DATA class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Permitted integer combinations in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Refine rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Refine rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Refine rule ECF syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Refine rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Filter rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Filter rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Event condition formula in a filter rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Filter rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Figures 11
Regulate rule syntax form 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Regulate rule syntax Form 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Regulate rule syntax to send a custom event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Regulate rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
regulate rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Regulate rule example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Regulate rule example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Abstract rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Abstract rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Correlate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Correlate rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Correlate rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
When clause in an Execute rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Execute rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Execute rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Threshold rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Propagate rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Timer rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Timer rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Timer rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Delete rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Delete rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Policy class syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Policy entry syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Policy in a rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Selector class syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Selector entry syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

12 BMC Impact Solutions: Knowledge Base Development Reference Guide


Tables
Knowledge Base file extensions and directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Knowledge Base subdirectories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
BAROC syntax symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Core and metaclass event and data classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Slot facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
BMC Impact Manager rule phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
MC_CELL_PARSE_ERROR slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
MC_CELL_UNDEFINED_CLASS slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
MC_CELL_PROCESS_ERROR slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Syntax objects in a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Conditions for the using clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Related event and source event slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Example event relation definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
BMC Impact Manager standard roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
By Status collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
By Location collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Collectors included in the MCxP collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Standard locations for action executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Action rule syntax variable descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Action execution variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Tags for defining multiple local actions in one file . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Default Knowledge Base class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
CORE_EVENT base class slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
MC_CELL_CONTROL slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
CORE_DATA slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
BEM_MATCH_TABLE class attribute (slot) definitions . . . . . . . . . . . . . . . . . . . . . . . 130
POLICY slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
SELECTOR slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
MC_CELL_INFO slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Deprecated slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Deprecated slot substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Logical combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
==/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
!=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
</2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
<=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
>/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
>=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
between/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Tables 13
within/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
outside/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
contains/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
contained_in/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
contains_one_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
has_prefix/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
has_suffix/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
matches/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
ip_smaller_or_equals/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
ip_greater_or_equals/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
ip_matches/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
ip_matched_by/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
superclass_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
subclass_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Alphabetical list of primitives and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
action_requestor/1 syntax argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
action_requestor/2 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
action_requestor/3 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
action_return/2 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
admin_execute/5 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
admin_execute/5 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
perform/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
perform/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
execute/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
confirm_external/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
get_external/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
inttostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
int_to_hex/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
int_to_hex/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
realtostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
pointertostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
string/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
stringtoint/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
stringtoreal/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
stringtopointer/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
int/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
trunc/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
round/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
real/2 or float/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
code/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
char/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
max/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
min/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
sign/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
abs/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
sqrt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
exp/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
pow/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
log/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

14 BMC Impact Solutions: Knowledge Base Development Reference Guide


log10/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
sin/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
cos/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
tan/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
asin/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
acos/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
atan/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
atan2/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
gcd/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
random/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
incr/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
incr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
incr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
incr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
incr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
incr/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
decr/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
decr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
decr2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
decr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
decr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
decr/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
concat/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
strlen/2 and len/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
tolowercase/2 and lower/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
touppercase/2 and upper/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
strpart/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
strnpart/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
strextract/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
substring/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
substring/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
strip/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
strip/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Possible values for the $POS argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
strip/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Possible values for the $POS argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
strtolist/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
strmatch/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
match_regex/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
match_regex/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
match_regex/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
sprintf/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
mapslots/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
mapslots/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
time_stamp/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
time_stamp_to_cim/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
time_stamp_to_str/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
time_stamp_to_str/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
time_extract/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Tables 15
str_to_time_stamp/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
listlen/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
listgetelt/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
listmember/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
listdelete/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
listappend/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
listdisjoint/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
listintersect/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
listunion/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
listsubtract/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
listremdup/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
listwalk/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
add_to_list/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
rem_from_list/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
find_match/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
find_match_entry/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
apply_match_entry/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
get_list_slotvalues/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
set_list_slotvalues/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
class_path/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
reset_default/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
ntadd/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
ntcnt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
ntget/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
ntset/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
opadd/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
opadd/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
opcnt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
opget/7 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
opget/6 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
opget_time/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
opget_author/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
opget_action/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
opget_args/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
opset/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
opset/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
relate/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
unrelate/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
cellinfo/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
cellcontrol/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
kbversion/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
kbversion/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
get_env/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
send_to/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
send_to/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
send_to_ext/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
smcomps/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
key_version/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
key_verify/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

16 BMC Impact Solutions: Knowledge Base Development Reference Guide


key_verify/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
tf_active/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
tf_active/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
tf_udid_active/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
tf_udid_active/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
tf_current_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
tf_current_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
tf_current_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
tf_current_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
tf_current_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
tf_current_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
tf_prev_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
tf_prev_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
tf_prev_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
tf_prev_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
tf_prev_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
tf_prev_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
tf_next_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
tf_prev_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
tf_next_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
tf_next_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
tf_next_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
tf_next_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
tf_duration/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
tf_duration/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
generate_event/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
new_data/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
remove_data/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
set_timer/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
set_timer_at/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
set_timer_at/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Filter rule syntax descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
f1 and f2 Filter rules event processing examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Correlate rule event examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Available environment variables in Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Event Management MRL rule definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Service Management MRL rule definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Microsoft Windows environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
UNIX environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Property groupings: BMC_BaseEvent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
CEM to BAROC: Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
CEM to BAROC: source information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
CEM to BAROC: reporter information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
CEM to BAROC: situation information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
CEM to Baroc: metric information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
EventInformation::EventToCIAssociationType parameter values . . . . . . . . . . . . . . 341
ReportTime (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
EventModelVersion (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

Tables 17
EventClass (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
EventId (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Status (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Timeout (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Notes (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
EventToCIAssociationType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
PropagationHistory (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
RelationSource (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Owner (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Account (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
ResourceId (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
ReconciliationIdentity (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Alias (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
ComponentHost (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
ComponentHostAddress (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Location (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
ComponentURI (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
ComponentCaption (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
ComponentType (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
ComponentOwner (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Slots for event monitoring information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
ResourceId (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
ComponentHostAddress (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
ComponentURI (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
ComponentCaption (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
ComponentType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
EventTime (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
EventType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
EventId (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
EventSeverity (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
EventSuggestion (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
SituationCategory (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Situation category (mc_event_category) values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
SituationTime (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Priority (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Severity (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Message (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Application (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
LongMessage (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
RepeatCount (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
MetricName (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
MetricValue (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
MetricValueUnit (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
MetricThreshold (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

18 BMC Impact Solutions: Knowledge Base Development Reference Guide


Chapter

1
1 Working with the Knowledge Base
This chapter describes how the Knowledge Base is organized and used in BMC
Impact Manager. This chapter presents the following topics:

Components of a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20


Unified Knowledge Base template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Knowledge Base directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Knowledge Base index files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Managing a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Creating a new production or test Knowledge Base—mcrtcell . . . . . . . . . . . . . . . 29
Importing Knowledge Base information into a cell—mkb . . . . . . . . . . . . . . . . . . . 29
Compiling a Knowledge Base—mccomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Loading a Knowledge Base into a running cell—mcontrol . . . . . . . . . . . . . . . . . . 30
Implementing changes to a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Versioning a Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Enabling KB versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Retrieving KB version information in rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Retrieving KB version information by using a command—mgetinfo . . . . . . . . . . 32

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 BMC Impact Manager instance
(also referred to as 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. A KB is installed with
each BMC Impact Manager. 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 BMC Impact Explorer. Although many KBs
can exist within a distributed BMC Impact Manager environment, each cell can be
associated with only one KB at a time.

Components of a Knowledge Base


A basic event management KB contains definitions for

■ event classes
■ data classes
■ global records
■ event management rules
■ event management policies
■ event collectors
■ action executables
■ interface classes

In addition to event management definitions, a service impact management (SIM) 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

■ a cell’s service model, published by a BMC Impact Publishing Server

In version 7.2 of BMC Impact Manager, the cell has a unified KB, in which the default
KBs for event management (EM) and service impact management (SIM) are unified
into a SIM KB. This unified KB is stored under the directory path
$MCELL_HOME/etc/default/SIM/kb. Any new cell you create in version 7.2 will contain a
unified KB by default.

20 BMC Impact Solutions: Knowledge Base Development Reference Guide


Components of a Knowledge Base

Table 1 lists the file extensions and directory location for the each of the components
contained in a KB.

Table 1 Knowledge Base file extensions and directories


Component File extension Directory
event classes .baroc kb\classes
data classes .baroc kb\classes
data instances .baroc kb\data
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

Event classes
An event class defines the types of events to 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, and 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, the service administrator or service manager defines
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. Event classes and their syntax are described in
Chapter 2, “BAROC language fundamentals” on page 35.

The event source (an adapter, an integration component, another cell, an API, or a
BMC Impact Manager CLI) must provide the events in the BAROC format and
structure. The cell accepts and processes an incoming event if it matches an event
class definition in the KB.

Data classes and dynamic data


A data class defines dynamic data instances. Dynamic data is similar to a small
database within the cell. Dynamic data can be used to look up information to be used
in rules and policies during event processing. The benefit of dynamic data is that it
makes it easy to maintain event management rules. For example, without using

Chapter 1 Working with the Knowledge Base 21


Components of a Knowledge Base

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 data instance, the service administrator or service manager must first
define a new data class.

As new hosts are added to the environment, the service administrator or service
manager adds new data instances dynamically through the BMC Impact Explorer
Administration View, 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.

Data classes and their syntax are described in Chapter 2, “BAROC language
fundamentals” on page 35.

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. Service managers and administrators use global records to share
information between events during event processing. For more information about
global records, see Chapter 2, “BAROC language fundamentals” on page 35.

Event management rules


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. The service administrator or service
manager writes rules using the Master Rule Language (MRL) and compiles and
stores them in the cell’s KB. Rules and their syntax are described in Chapter 3,
“Creating rules” on page 51.

Event management policies


An event management policy is similar to a rule in that it performs actions against
events that meet specified selection criteria. 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.

22 BMC Impact Solutions: Knowledge Base Development Reference Guide


Components of a Knowledge Base

However, unlike rules, an event management policy

■ is defined interactively through the BMC Impact Explorer Administrator interface


of the BMC Impact Explorer 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.

For more information about event management policies, see the BMC Impact
Solutions: General Administration guide.

Event collectors
You can use event collectors to organize events in meaningful groups for display in an
event list and to show operators event relationships. An event collector consists of a
filter that queries the event repository and displays the results in a BMC Impact
Manager (cell) event list, which is represented by a node on the Events View tree and
in BMC Impact Manager event groups in the BMC Impact Explorer interface.

Each cell has default collectors for BMC Impact Explorer and collectors that the
service manager or service administrator creates. The service manager or service
administrator specifies in the collector definition and the user groups that can access
a collector.

For an event to be displayed in an event collector, the service administrator or service


manager specifies criteria that an event must match and specifies which user groups
can view a collector and the events within a collector. The service administrator or
service manager defines collectors in MRL and stores them in the cell’s KB. Collectors
and their syntax are described in Chapter 4, “Creating collectors” on page 89.

Action executables
An action is an executable program or script that performs an automated task on a
particular event. Service managers and service administrators create actions and use
them in rules or make them available to users in BMC Impact Explorer. Arguments
can be passed to an action by rules or through user input in the BMC Impact Explorer
Actions interface.

■ Remote actions are defined in a cell’s KB and can be executed by rules or launched
by a user in the BMC Impact Explorer console. For more information, see
Chapter 5, “Creating remote actions” on page 105.

Chapter 1 Working with the Knowledge Base 23


Unified Knowledge Base template

■ Local actions are defined in local BMC Impact Explorer configuration files and can
be launched only by a user from an event in the console. For more information, see
the BMC Impact Solutions: General Administration guide.

Service model class definitions


A service model is a representation of the IT assets that interoperate to deliver business
services and the critical relationships that exist among them. Service model
components and relationships are instances of the Common Data Model (CDM)
classes for BMC Atrium CMDB, the configuration management database used by
BMC Software. Both service models and the CDM classes used to define the service
models are stored in BMC Atrium CMDB.

Service models can be built dynamically from rules, though the BMC Impact Explorer
interface, or from external sources. A service manager publishes (distributes) the
latest version of the service model to BMC Impact Manager cells that use this data in
service impact management.

If the service model is published from the CMDB, then you cannot edit the service
model or the SIM KB class definitions that reside on a cell. You must use the BMC
Impact Service Model Editor to edit service model components and relationships. To
edit CDM SIM class definitions, you must use the BMC CMDB Class Manager
console. For more information, see BMC Service Model Administrator’s Guide.

If the service model is created by another source, it can be edited.

Interface classes
An interface class defines the format of data that comes from an external source. This
allows the external information to be used in a rule.

Interfaces are described in “Interfaces in rules” on page 73.

Unified Knowledge Base template


During installation, a unified KB that serves as a template for all cell KBs is created for
the BMC Impact Manager cell. The unified KB contains the default BMC Impact
Manager Event Management (EM) and Service Impact Management (SIM) KBs. The
unified 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.

24 BMC Impact Solutions: Knowledge Base Development Reference Guide


Knowledge Base directory structure

The unified KB is installed into the MCELL_HOME/etc/default/SIM/kb directory. It


contains the KB elements used by Service Impact Management and by Event
Management. These components define how service models are stored, interact, and
behave and how events are processed. The SIM code of the unified KB is active only if
the cell is configured as a SIM cell and the ServiceModelEnabled parameter of the
MCELL_HOME/etc/mcell.conf file is set equal to Yes. (Refer to the BMC Impact Solutions:
General Administration guide for additional information about the mcell.conf parameters.)

The EM-only KB, stored under MCELL_HOME/etc/default/EM/kb, remains for


backward compatibility with pre-7.2 versions of the mcrtcell CLI. It contains the KB
elements used by Event Management to process events.

In version 7.2, when you create or install a new cell via the mcrtcell command, you
always create or install a unified SIM 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.

NOTE
If you modify the template KB in either MCELL_HOME\etc\default\SIM or
MCELL_HOME\etc\default\EM any cell that you install or create will include those
modifications.

Integrating a unified KB with pre-7.2 cell definitions


You can integrate your cell definitions from pre-7.2 cells with the unified KB of the 7.2
cell.

1 Create a new 7.2 cell using the mcrtcell CLI with either the -ae or -as option.

2 Copy the modifications or extensions you’ve made in current 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.

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.

Chapter 1 Working with the Knowledge Base 25


Knowledge Base directory structure

■ The template Knowledge Base resides in the MCELL_HOME\etc\default\SIM or


MCELL_HOME\etc\default\EM directory. The Knowledge Base available (EM only
or both EM and SIM) will depend on the type specified when the cell was created.

Cells are created during installation of a BMC Impact Manager instance or by using
the mcrtcell command. For information about this command, see BMC Impact
Solutions: General Administration.

NOTE
The environment variables created during installation that define paths to BMC Impact
Manager configuration files and executables are listed in Appendix F, “Environment
variables.”

Figure 1 lists the directory structure for a Knowledge Base.

Figure 1 Knowledge Base directory structure


kb
\bin
\A
\h1
\l2
\p4
\s5
\w4
\classes
\collectors
\data
\lib
\records
\rules

In the Knowledge Base, each subdirectory is labeled to indicate the type of files or
programs it stores, as listed in Table 2 on page 27.

26 BMC Impact Solutions: Knowledge Base Development Reference Guide


Knowledge Base directory structure

Table 2 Knowledge Base subdirectories (part 1 of 2)


Knowledge
Base
subdirectory Description
bin stores the external scripts that can execute during rule processing and actions that can be run
from BMC Impact Explorer

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. Actions and their syntax are described in Chapter 5, “Creating remote actions” on
page 105.
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 2, “BAROC language fundamentals” on
page 35. For information about base event and data classes, see Appendix A, “Event and data
classes” on page 117.
collectors stores collector rule definitions

Collector definitions are used to organize the event lists that are viewed in the BMC Impact
Explorer console. Collector rules are defined in .mrl files. Collectors and their syntax are
described in Chapter 4, “Creating 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 2,
“BAROC language fundamentals” on page 35 and in “Dynamic data in rules” on page 70.
lib stores primitives and functions used in the Knowledge Base

For example, the SIM 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 Appendix B, “Master Rule Language
(MRL) reference” on page 137.

Chapter 1 Working with the Knowledge Base 27


Knowledge Base index files

Table 2 Knowledge Base subdirectories (part 2 of 2)


Knowledge
Base
subdirectory Description
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 2, “BAROC language
fundamentals” on page 35 and in “Global records in rules” on page 72.
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 3,
“Creating rules” on page 51, Appendix B, “Master Rule Language (MRL) reference” on
page 137, Appendix C, “Event rules and syntax” on page 275, and in Appendix D, “Default
rule sets” on page 313.

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.

28 BMC Impact Solutions: Knowledge Base Development Reference Guide


Managing a Knowledge Base

Managing a Knowledge Base


To manage a Knowledge Base, you must perform several tasks by using the BMC
Impact Manager command-line interface (CLI). This section briefly describes these
tasks; for more information about syntax and options available for the CLI
commands, see the BMC Impact Solutions: General 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.

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 BMC Impact Solutions: General Administration CLI reference
appendix.

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, BMC Impact
Solutions: General Administration CLI reference appendix.

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.

Chapter 1 Working with the Knowledge Base 29


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 BMC Impact
Solutions: General Administration CLI reference appendix.

Effects of compiling a Knowledge Base with tracing


enabled
If you enable tracing by using the -t option when compiling a KB, 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.

NOTE
The TraceRuleLevel parameter in the mcell.conf file must be set to 2 for rules tracing to
occur.

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 BMC Impact
Solutions: General Administration CLI reference appendix.

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 BMC Impact Solutions: General
Administration.

30 BMC Impact Solutions: Knowledge Base Development Reference Guide


Versioning a Knowledge Base

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.

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.

Chapter 1 Working with the Knowledge Base 31


KB versioning example

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
@kbversion( HelpDesk , '1.2.01' )

This example specifies that the KB contains a logical module called HelpDesk, and
that its version is 1.2.01.

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/2 —
retrieve Knowledge Base module version information” on page 247.

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.

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

32 BMC Impact Solutions: Knowledge Base Development Reference Guide


Retrieving KB version information by using a command—mgetinfo

The information is displayed in raw format. You can use the -v switch to obtain the
information in a more readable format. Figure 2 on page 33 shows a portion of the
information returned from the kbsources argument.

Figure 2 Output from mgetinfo kbsources argument


BMC Impact InfoRetrieval 7.0.00 (Build 1332814 - 27-Apr-2006)
Copyright 1998-2006 BMC Software, Inc. as an unpublished work. All rights reserved.
7.0.00 1332814 27-Apr-2006 collectors/self_collector.mrl 329 215528602
7.0.00 1332814 27-Apr-2006 collectors/mc_bystatus_collectors.mrl 8682876756519
7.0.00 1332814 27-Apr-2006 collectors/mc_bylocation_collectors.mrl 2673155257002
7.0.00 1332814 27-Apr-2006 collectors/mc_evr_collectors.mrl 17193192677488
7.0.00 1332814 27-Apr-2006 collectors/bii4p_collectors.mrl 1861 72069569
7.0.00 1332814 27-Apr-2006 collectors/mc_sm_collectors.mrl 1351 3438665385
7.0.00 1332814 27-Apr-2006 collectors/catchall_collector.mrl 3813425794528
7.0.00 1332814 27-Apr-2006 rules/mc_startup.mrl 578 2337723164
7.0.00 1332814 27-Apr-2006 rules/im_internal.mrl 36351 4174289538
7.0.00 1332814 27-Apr-2006 rules/mc_intevt.mrl 3115 1930567566
7.0.00 1332814 27-Apr-2006 rules/mc_mccs.mrl 2296 2571308892
7.0.00 1332814 27-Apr-2006 rules/ips.mrl 2333 2499185120
7.0.00 1332814 27-Apr-2006 rules/mc_sm_start.mrl 1196 92543871
7.0.00 1332814 27-Apr-2006 rules/mc_sm_associate.mrl 3389 3376465454
7.0.00 1332814 27-Apr-2006 rules/mc_sm_maintenance.mrl 1885 797195742
7.0.00 1332814 27-Apr-2006 rules/mc_sm_elect.mrl 1055 4013285370
7.0.00 1332814 27-Apr-2006 rules/mc_sm_attach.mrl 1943 1558282738
7.0.00 1332814 27-Apr-2006 rules/mc_sm_shadow.mrl 3781 4283488066
7.0.00 1332814 27-Apr-2006 rules/mc_sm_slm.mrl 4512 1631402620
7.0.00 1332814 27-Apr-2006 rules/bii4p.mrl 10473 1881293223
7.0.00 1332814 27-Apr-2006 0 1073706332
7.0.00 1332814 27-Apr-2006 bin/mc_actions.mrl 1304 3908443203
7.0.00 1332814 27-Apr-2006 bin/im_operations.mrl 16424 2639831549
7.0.00 1332814 27-Apr-2006 bin/sim_operations.mrl 3992 3834546431

Chapter 1 Working with the Knowledge Base 33


Retrieving KB version information by using a command—mgetinfo

34 BMC Impact Solutions: Knowledge Base Development Reference Guide


Chapter

2
2 BAROC language fundamentals
This chapter presents the following topics:

BAROC overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
BAROC class inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
BAROC language syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
BAROC language symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Use of quotation marks in the BAROC language . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Class definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Metaclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Slot data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Universal event and data identifier slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Slot facets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Internal enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Class definition examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Class instance definition syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Class instance definition syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Class instance definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Global record definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Global record definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Loading and compiling BAROC modifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Chapter 2 BAROC language fundamentals 35


BAROC overview

BAROC overview
The BAROC language is a highly-structured language that defines

■ event classes
■ data classes and dynamic data instances (also known as data objects)
■ global records
■ interfaces

Using these items, BAROC provides the ability to capture the meanings of events,
physical objects, and logical objects, and then render those objects in a format suitable
for processing. For information about these items, see Table 1 on page 21.

Using BAROC, you specify objects through classes, and specify different object types
using entities called slots. You can also control the values a slot can have, or control a
slot’s processing, using facets. 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.

BAROC class inheritance


BAROC class definitions are organized in a hierarchical system where existing classes
(superclasses) can be assigned subclasses and have 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.

In summary, subclasses

■ inherit slots from superclasses


■ inherit rules from superclasses
■ can have their own slots

36 BMC Impact Solutions: Knowledge Base Development Reference Guide


BAROC language syntax

■ can override superclass slots (but must contain the same data type)
■ can be a subclass of only one class

BAROC language syntax


The 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:

Table 3 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 [] A block enclosed in square brackets indicates it is an optional block. The brackets
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.

Chapter 2 BAROC language fundamentals 37


Use of quotation marks in 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:

■ 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


NOTE
When you define a new event class, slot, enumeration, or enumeration value, you can define
user-friendly presentation names to be displayed in the BMC Impact Explorer and BMC
Impact Portal consoles. For further information and instructions, see BMC Impact Solutions:
General Administration.

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

38 BMC Impact Solutions: Knowledge Base Development Reference Guide


Metaclasses

The syntax elements are defined as follows:

<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>

Metaclasses
A metaclass is a class that defines other classes. In BMC Impact Manager, 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

NOTE
For Tivoli users: The mc_root_internal.baroc file defines the metaclass TEC_CLASS for TME
10 classes.

Chapter 2 BAROC language fundamentals 39


Slot data types

The syntax for defining event and data classes is essentially the same; however, their
core classes and metaclasses differ:

Table 4 Core and metaclass event and data classes


Class type Event Data
metaclass MC_EV_CLASS MC_DATA_CLASS
base class CORE_EVENT CORE_DATA

For information about the default event and data class definitions, see Appendix A,
“Event and data classes” on page 117.

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 or BMC
Impact Explorer). For further information about service model component classes
and service model publishing, see BMC Impact Solutions: General Administration.

Slot data types


Slot 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 42.

NOTE
Additional slot data types INT32 and POINTER are supported for compatibility with the
Tivoli TEC product.

40 BMC Impact Solutions: Knowledge Base Development Reference Guide


Universal event and data identifier slots

Universal event and data identifier slots


The 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 BMC Impact Manager universal event ID, uniquely identifies
an event to all cells of a network. The mc_ueid slot provides a convenient way to
retrieve an event in a cell hierarchy. When a cell receives a syntactically valid event
with a non-empty mc_ueid slot, it determines whether a prior event has been
received with that same mc_ueid. If such an event has been received, the new event is
ignored. When a cell receives a syntactically valid event with an empty mc_ueid, it
generates an mc_ueid of the form:

mc.cellName.<extension>

mc_udid slot
The mc_udid slot, BMC Impact Manager universal data ID, uniquely identifies the
data in the cell. If not set, the cell automatically generates an mc_udid of the form:

mc.cellName.<extension>

This slot is used to associate an event to a component. To attach an event to a


component, you set the mc_smc_id attribute value of the event to the mc_udid value
of the component rather than to the logical_id value used in older releases.

Use this slot when importing data from an external system, such as an asset
management system. By carefully selecting the mc_udid, you can identify the data in
the cell that corresponds to a particular component defined in the external system.

Slot facets
Slot definitions can also have slot facets that control aspects of a class 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 5 on
page 42 lists the facets available for slot definitions.

Chapter 2 BAROC language fundamentals 41


Enumerations

Table 5 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.

Enumerations
Enumerations list acceptable values for a particular slot. Enumerations must be
declared and labeled in BAROC before they can be used.

Figure 3 Enumeration definition syntax


ENUMERATION EnumName
[NumVal SymbVal]*
END

42 BMC Impact Solutions: Knowledge Base Development Reference Guide


Internal enumerations

Internal enumerations
The following internal enumerations are included in the Event Manager (EM)
Knowledge Base:

■ STATUS
■ SEVERITY
■ MC_PRIORITY
■ MC_EVENT_CATEGORY
■ MC_YESNO

WARNING
Modifying these internal enumerations is not recommended, except to add new values.
Removing built-in values or modifying their order can render the cell unable to perform its
tasks.

For information about the service model enumerations included in the Service Impact
Manager (SIM) KB, see BMC Impact Solutions: General Administration.

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

Chapter 2 BAROC language fundamentals 43


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:

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_ events relating to the Capacity Management process
MANAGEMENT
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_ events relating to the Service Continuity Management process
CONTINUITY_
MANAGEMENT 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_ events relating to the Availability Management process
MANAGEMENT
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.
INCIDENT_ events relating to the Incident Management process
MANAGEMENT
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.

44 BMC Impact Solutions: Knowledge Base Development Reference Guide


Internal enumerations

Category Description
CONFIGURATION_ events relating to the Configuration Management process
MANAGEMENT
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_ events relating to the Release Management process
MANAGEMENT
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_ events relating to the Problem Management process
MANAGEMENT
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_ events relating to the Change Management process
MANAGEMENT
This process controls changes to the infrastructure or any aspect of services in a
controlled manner, enabling approved changes with minimum disruption.
OPERATIONS_ events relating to the Operational Management process
MANAGEMENT
The process is not only concerned with the incidents reported by users, but also
with events generated by or recorded by the infrastructure.
SECURITY_ events relating to the Security Management process
MANAGEMENT
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_ events relating to the Financial Management process
MANAGEMENT
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_ events relating to the Service Desk Management process
MANAGEMENT
This process manages the Service Desk.

Chapter 2 BAROC language fundamentals 45


Class definition examples

MC_YESNO enumeration
The MC_YESNO enumeration is used to set a YES or NO value for a slot.

Class definition examples


In Figure 4, the data class SEVERITY_BY_APP_DOWN assigns specific severities to the
appropriate APP_DOWN events:

Figure 4 Class definition example


MC_DATA_CLASS:SEVERITY_BY_APP_DOWN ISA DATA
DEFINES{
application:STRING,key=yes;
severity:SEVERITY,default=WARNING;
};
END

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 5, the SECURITY_EVENT class inherits all of the slots of the EVENT class.

Figure 5 Class hierarchy definition example


MC_EV_CLASS :
SECURITY_EVENT ISA EVENT;
END

In Figure 6, the LOGIN_EVENT class inherits all the slots of SECURITY_EVENT and adds
two new slots, mc_host and user. These two new slots are declared with facet
dup_detect=yes. This means that two event instances are considered identical if
they have the same values for these slots.

Figure 6 Superclass definition example


MC_EV_CLASS :p_
LOGIN_EVENT ISA SECURITY_EVENT
DEFINES {
mc_host: dup_detect = yes ;
user: STRING, dup_detect = yes ;
};
END

46 BMC Impact Solutions: Knowledge Base Development Reference Guide


Class instance definition syntax

In Figure 7, the LOGIN_FAILURE class is a subclass of LOGIN_EVENT. It inherits all the


slots except the severity slot, which is inherited from the base EVENT class; the
default value is set to MINOR for this class.

Figure 7 Subclass definition example


MC_EV_CLASS :
LOGIN_FAILURE ISA LOGIN_EVENT
DEFINES {
severity: default = MINOR ;
};
END

In Figure 8, the AppByHost data class is a table that stores a list of applications present
on each host. The host slot is defined as the unique key for this table. The system will
prevent the creation of two AppByHost class instances, or a subclass of AppByHost,
with the same host slot value.

Figure 8 Data class definition example


MC_DATA_CLASS :
AppByHost ISA DATA
DEFINES {
host: STRING, key=yes;
applications: LIST_OF STRING;
};
END

In Figure 9, the location class is an interface class with a single slot, site.

Figure 9 Interface class definition example


MC_INTERFACE : location
DEFINES {
site: STRING;
};
END

Class instance definition syntax


Class;
[Slot = SlotVal;] *
END

The syntax elements are defined as follows:

Chapter 2 BAROC language fundamentals 47


Class instance definition example

SlotVal = SlotSmplVal|SlotListVal
SlotSmplVal =
sequence of alphanumeric or _ characters
|quoted (' or ") sequence of characters
SlotListVal = '[' [SlotSmplVal {,SlotSmplVal}] ']'

Class instance definition example


LOGIN_FAILURE;
Severity = WARNING;
Status = OPEN;
mc_host = server4;
Origin = 172.16.23.4;
Acl = [admin, troyt, samg];
Msg = ‘Failed login attempt for user admin’;
END

You can also define data instances in the Administration tab of BMC Impact Explorer.
For information, see BMC Impact Solutions: General Administration.

Global record definition syntax


Global 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:

RECORD
UNDER_MAINTENANCE DEFINES {
hosts: LIST_OF STRING ;
}
END

In a rule, you can refer to one of the slots, as shown in the following example:

$UNDER_MAINTENANCE.hosts

48 BMC Impact Solutions: Knowledge Base Development Reference Guide


Loading and compiling BAROC modifications

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 72.

Loading and compiling BAROC modifications


The .load file determines the order in which the cell loads the BAROC files. You can
maintain classes can be maintained in single or multiple files, as required. Any time a
new file is created, add it to the Knowledge Base for a cell.

NOTE
The BMC Impact Manager executable contains default BAROC definitions. For reference
purposes, those definitions are provided in the default KB in the mc_root_internal.baroc.mrl
file. Do not reference this file in the .load file.

After you modify BAROC definitions, recompile the Knowledge Base. For
information about compiling the Knowledge Base, see “Compiling a Knowledge
Base—mccomp” on page 30.

Chapter 2 BAROC language fundamentals 49


Loading and compiling BAROC modifications

50 BMC Impact Solutions: Knowledge Base Development Reference Guide


Chapter

3
3 Creating rules
This chapter presents the following topics:

Rules overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Incoming event processing by rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Internal event processing by rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Internal requests by a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Undefined events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Event processing errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Rule structure and syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
MRL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
MRL conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
General rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
MRL event selection clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Where clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Using clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Unless clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
When clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Body clause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Variables in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Dynamic data in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Global records in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Interfaces in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Interface instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Indexes in rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Using indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Relating events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Event relation definition example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Creating an event relation definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Compiling rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Testing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Tracing a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Configuring rule tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Customizing rule trace message headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Chapter 3 Creating rules 51


Rules overview

Rules overview
The Master Rule Language (MRL) is a compact and powerful declarative language
used to create rules that determine and control the behavior of the cells. Rules are
processing statements that use the BAROC data associated with an event to
determine if, when, and how to respond to events, data, records, and interfaces. For
example, a rule might designate that an event should be responded to if considered
significant or discarded if considered insignificant.

Rules are stored within the cell’s Knowledge Base. They 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. The order in which the cell evaluates events
against rules is determined by the order in which the rules were loaded (as specified
in the .load file). For more information about the .load file, see “Knowledge Base index
files” on page 28.

As an event passes through a phase, it is acted on by every applicable rule within that
phase until all the rules are exhausted or the event is discarded. When all the rules in
one phase are evaluated, the cell moves to the next phase.

Figure 10 on page 53 identifies the rule phases and shows how event processing
proceeds, and Table 6 on page 53 describes the phases.

52 BMC Impact Solutions: Knowledge Base Development Reference Guide


Rules overview

Figure 10 Event processing in the rule phases

Event

1 Refine

An event can be
discarded during any 2 Filter
one of these phases
before being added
to the repository. 3 Regulate

4 New

5 Abstract The New, Abstract,


Correlate, and
Execute rule
6 Correlate 10 Timer phases can trigger
a Timer rule.

7 Execute
Repository
8 Threshold

Delete rules execute


9
8 Propagate 11 Delete when a record is
removed during
repository cleanup.
to other cells

Table 6 BMC Impact Manager 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

Note: This is the last opportunity to prevent an event from entering the event repository.
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.

Chapter 3 Creating rules 53


Incoming event processing by rules

Table 6 BMC Impact Manager rule phases (part 2 of 2)


# Rule phase Description
6 Correlate determines whether any events have a cause-and-effect relationship
7 Execute evaluates events, and, if certain conditions are met, triggers specified actions
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

Incoming event processing by rules


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.

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.

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.

54 BMC Impact Solutions: Knowledge Base Development Reference Guide


Internal event processing by rules

Internal event processing by rules


Incoming events can be generated by an external system or internally. Internal events
are events generated either by the rule engine or by a rule rather than by an external
system. 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.
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

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
following incorrect events are handled by the cell as specified:

■ The event message cannot be parsed as an event.

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 7.

Table 7 MC_CELL_PARSE_ERROR slots (part 1 of 2)


Slot Data
error_column column number in text where error occurs
error_line line number on text where error occurs

Chapter 3 Creating rules 55


Event processing errors

Table 7 MC_CELL_PARSE_ERROR slots (part 2 of 2)


Slot Data
error_message error message
event_text complete event message text

■ The event is of an undefined class.

An internal event of class MC_CELL_UNDEFINED_CLASS is generated. 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 8.

Table 8 MC_CELL_UNDEFINED_CLASS slots


Slot Data
class_name name of class as specified in the message

■ The event is of a defined class, but contains undefined slots.

The event is generated as one of the specified class, and the undefined slots are
stored in the bad slot list slots, in corresponding order.

■ 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.

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 9.

Table 9 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

56 BMC Impact Solutions: Knowledge Base Development Reference Guide


Rule structure and syntax

Rule structure and syntax


The service administrator or service manager writes rules using MRL and compiles
and stores them in the cell’s KB. For detailed information about MRL, see
Appendix B, “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
Appendix C, “Event rules and syntax” 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 (‘).

■ When a primitive contains an argument that is a list arg, 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.

Chapter 3 Creating rules 57


General rule syntax

■ 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 11 on page 59 shows the syntax objects
that can appear in a rule, and Table 10 on page 59 describes those objects according to
the number key in the figure.

58 BMC Impact Solutions: Knowledge Base Development Reference Guide


General rule syntax

Figure 11 Rule syntax

RuleType RuleName : 2

ClassName (variable) where

[expression op expression,
3
...,

expression op expression]

using [ALL] |unless |where {

ClassName (variable) where


[booleanExpression],
4
. . .,

ClassName (variable) where [boolean


Expression]

{call;

. . .; 5

call;

variable.slot=expression;}

Table 10 Syntax objects in a rule (part 1 of 2)


# Description
1 RuleType specifies the phase for which the rule is written.

You can specify one of the following types of rules:


■ Refine ■ New ■ Execute ■ Timer
■ Filter ■ Abstract ■ Threshold ■ Delete
■ Regulate ■ Correlate ■ Propagate
2 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.

Chapter 3 Creating rules 59


MRL event selection clauses

Table 10 Syntax objects in a rule (part 2 of 2)


# Description
3 This portion of the syntax contains the Event Condition Formula (ECF) and an
optional clause.

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.
■ variable specifies.
■ expression is.
■ op is a Boolean operator.

Note: To apply the rule to all incoming event instances, specify ClassName as EVENT.
4 (optional) This portion of the syntax contains a query clause that directs the rule
engine to retrieve data from the dynamic data repository to be used in the remainder
of the rule.

It includes the Using clause. For more information about the use of clauses, see
“MRL event selection clauses” on page 60.
5 This portion contains 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 phase
to which the rule belongs.

MRL event selection clauses


Whether 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:

Figure 12 Event selection criteria example


MC_EV_CLASS :
APPLICATION_UP ISA APPLICATION_EVENT DEFINES
{
severity: default = INFO;
};
END

60 BMC Impact Solutions: Knowledge Base Development Reference Guide


Where clauses

And the engine receives the following event:

APPLICATION_UP;
mc_host=babble;
...
status=OPEN;
END

The following rule will accept the instance and will be evaluated.

filter application_events : PASS


APPLICATION_EVENT ($APEV)
where [
....
]
...

Where clauses
where clauses are part of the ECF and establish restrictive selection criteria. A where
clause consists of the keyword where followed by the criteria within square brackets:

where [criteria]

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 “Operators” on


page 139, as well as any of the following condition operators:

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

MRL primitives, functions, and operations also can be used in expressions. An


exhaustive list can be found in Appendix B, “Master Rule Language (MRL)
reference.”

Chapter 3 Creating rules 61


Where clauses

In the following example, the where clause syntax requires that the mc_host slot of
the event under analysis literally is to be set to ‘thishost’.

APPLICATION_EVENT ($APEV)
where [
$APEV.mc_host == ‘thishost’;
]

The syntax in the next example requires that the mc_host slot of the event under
analysis literally to be set to ‘thishost’ or to ‘thathost’ if the source does not contain
NT.

APPLICATION_EVENT ($APEV)
where [
$APEV.mc_host == ‘thishost’ OR
$APEV.mc_host == ‘thathost’ AND
NOT $APEV.source contains ‘NT’
]

You can write the same rule using parentheses, as shown in the following example:

APPLICATION_EVENT ($APEV)
where [
($APEV.mc_host == ‘thishost’) OR
(($APEV.mc_host == ‘thathost’) AND
(NOT ($APEV.source contains ‘NT’)));
]

You can also use parentheses to alter the precedence. In the following example, the OR
operator would be evaluated first because it is enclosed in parentheses.

APPLICATION_EVENT ($APEV)
where [
($APEV.mc_host == ‘thishost’ OR
$APEV.mc_host == ‘thathost’)
AND $APEV.source contains ‘NT’;
]

For information about the order of precedence for combination operators, see
“Combination operators” on page 139.

62 BMC Impact Solutions: Knowledge Base Development Reference Guide


Where clauses

Where clause syntax best practices

Maintaining the rule engine performance

To avoid slowing the performance of the rule engine, try to select events based on the
name as much as possible and design a good hierarchy of classes. Also, try to avoid
performance-intensive where clauses when possible.

The following line:

EVENT($EV) where [$EV.CLASS == ‘APPLICATION_EVENT’]

may appear equivalent to

APPLICATION_EVENT ($EV)

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:

$APEV.mc_host equals ‘thathost’

can also be written as

mc_host:equals thathost

However,

mc_host:equals ‘thathost’

is permitted only for backward compatibility with previous releases of the MRL.

Chapter 3 Creating rules 63


Using clause

Syntax shortcut

In a where clause slot: is a shortcut for $EV.slot.

$EV.slot: is syntactically incorrect.

Using clause
The using clause retrieves information from the event repository of the rule engine to
be used in the context of a rule. You can use the using clause to retrieve data
instances for a dynamic rule, or to retrieve instances of past events. The syntax for the
using clause is as follows:

EventClassName (Variable)
where [Expression CondOperator Expression, ...]
using [ALL] {DataClassName (Variable)
where [Expression CondOperator Expression,
Expression CondOperator Expression,
...];
DataClassName (Variable)
where [Expression CondOperator Expression,
Expression CondOperator Expression,
...];
... ;
}

To search for event instances, you must write a valid criteria block with a valid event
class name instead of a data class name.

You can define indexes on events and data. Querying instances can be
computationally intensive and might dramatically reduce cell performance. When
there are only conjunctions (ANDs but no ORs) in the where 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 74.

64 BMC Impact Solutions: Knowledge Base Development Reference Guide


Using_policy clause

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 11 on page 65 lists additional conditions that affect rule
processing.

Table 11 Conditions for the using clause


Condition Result
Only a single instance of the data is The rule is evaluated only for the single instance.
found in the repository.
No data that matches the specified The remainder of the rule is skipped.
criteria is found in the repository.
More than one instance of the data Only the first data instance is retrieved.
exists in the repository.
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.
The using clause in a rule contains The rule engine searches for an instance corresponding to the criteria in
several blocks. the first block, then an instance for the criteria in the second block, until
all blocks are exhausted. At least one instance of each block must exist
for the rule to evaluate.
The ALL keyword is used in the The rule is evaluated for all combinations of the instances found.
using clause.
For example, if a using clause contains two blocks, the first block
retrieving three instances and the second block five, the rule is
evaluated a total of fifteen times.

Using_policy clause
Policy instances can be referenced before the selection part of a rule as shown in this
example:

new bmc_im_internal_closure:
using_policy { EVENT_CLOSURE_POLICY($POL)
where [ calendars_active($POL.active_calendars) ] }
$POL.closing_event($CLOSING)
where [ $CLOSING.status != CLOSED ]
updates ALL $POL.closed_event($CLOSED)
within $POL.time_window
{
$CLOSED.status = CLOSED;
if ($POL.suppress_restoring_event == 1) then
{
drop_new;
}
}

Chapter 3 Creating rules 65


Unless clause

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.

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:

<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> ]

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.

66 BMC Impact Solutions: Knowledge Base Development Reference Guide


When clause

The syntax of the unless clause is as follows:

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 clause
when clauses are present in Execute, Abstract, Correlate, and Propagate rule phases.
These rules are evaluated in the following situations:

■ a new event is processed and the when condition is met


■ a previously received event is modified in such a way that the when condition is
met

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.

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 Appendix B, “Master Rule Language (MRL) reference.”

NOTE
When a primitive fails, that is, returns the value FALSE, the remainder of the block is not
executed.

Chapter 3 Creating rules 67


Body clause

The syntax of the body clause is as follows:

{
Variable.SlotName = Value;
Call ;
}

NOTE
Except for the last statement, all statements in a body clause must be separated using a
semicolon (;).

The syntax to call a slot assignment in a body clause is as follows:

$EV.SlotName = expression

if-then-else construct

The if-then-else construct is a special call used in a body clause that specifies a
conditional execution. The syntax for the if-then-else construct is:

if Expression
then
{
Variable.SlotName = Value;
Call ;
}
[ else
{
Variable.SlotName = Value;
Call ;
}
]

The else body clause is optional. If the Expression is evaluated as true, the
statements in the then body are executed. However, if an else body is included in
the body clause and the statement is evaluated as false, the statements in the else
body are executed.

68 BMC Impact Solutions: Knowledge Base Development Reference Guide


Variables in rules

You can refer to a local variable declared in the then and else body after the if-
then-else call if the variable is declared in both the then and else body with the
same data type, as shown in the following example:

if Boolean expression then


{
...
$TEMP = ' yes' ;
...
}
else
{
...
$TEMP = ' no';
...
};
$EV.msg = $TEMP;

NOTE
It is unnecessary to use an if-then-else construct to create a conditional affectation. A
simpler solution is to use a conditional expression. For information about conditional
constructs, see Appendix B, “Master Rule Language (MRL) reference.”

Variables in rules
Use variables in rules to point to MRL objects, such as events, data, global records, or
interfaces, and to reference results returned by a primitive.

In a rule, you must declare variables at their first occurrence in the text. The scope of
the variable is from its declaration to the end of the rule. The value for a variable
cannot change during the life of the variable. For example, you cannot assign another
value to a variable after the first occurrence in a rule.

The syntax for a declaring a variable is as follows:

$VariableName

The name of the variable must be composed of alphanumeric characters; it also can
contain underscore characters.

NOTE
BMC Impact Manager uses a naming convention of variables with short uppercase names.

Chapter 3 Creating rules 69


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.

ClassName ($EV) where


[expression op expression,
. . . ,
expression op expression ]

NOTE
The same principles that apply to events also apply to interface objects: a variable points to the
interface instance returned by an external program. Additionally, it allows the use of the
individual slot values in subsequent expressions.

Global record instances are predefined in the Knowledge Base; therefore, the scope of
variables is the entire Knowledge Base. A variable $UNDER_MAINTENANCE refers to the
unique instance of the UNDER_MAINTENANCE global record. You can use variables in
primitives to obtain the values they return, as shown in the following example:

concat( [‘from top’, ‘to bottom’ ], $MSG0;


$EV.msg = $MSG ;

The concat primitive concatenates a list of strings into another string. The $MSG
variable obtains the result, so that the concatenated string can be used in subsequent
clauses. The result is used as an assignment.

Dynamic data in rules


Dynamic 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.

70 BMC Impact Solutions: Knowledge Base Development Reference Guide


Dynamic data 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 13 Execute rule using dynamic data


execute Set_App_Down_Severity :
APP_DOWN ($AD)
using SEVERITY_BY_APP_DOWN ($SBAD)
where [$SBAD.application == $AD.application]
when $AD.status == OPEN
{
$AD.severity = $SBAD.severity;
}
END

The rule searches the data instances to find the instance of the application in the
APP_DOWN event. When a match is found, the rule stops searching the data instances
and continues processing with the matching instance, as follows:

SEVERITY_BY_APP_DOWN ;
application = mail ;
severity = CRITICAL ;
END

The data must be populated beforehand; otherwise, the rule engine does not find an
instance and the remainder of the rule is skipped. In other words, when the using
clause is present in a rule, it must return data or the selection fails, and the remainder
of the rule is skipped. You can also define dynamic data instances by using the
Dynamic Data Editor in BMC Impact Explorer. For instructions, see BMC Impact
Solutions: General Administration.

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 74.

Chapter 3 Creating rules 71


Global records in rules

Global records in rules


Global 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.

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 BMC Impact Solutions: General Administration.

Global records are created using .baroc files. The global record files are located in the
Records directory of the cell Knowledge Base.

NOTE
Global records maintain their information when the cell is stopped and restarted.

The syntax for global records is as follows:

RECORD RecordName
DEFINES {
SlotName : SlotType ;
SlotName : SlotType ;
}
END

Global records are addressed by name, so you must know the name of the global
record to use it. You can use global records in an expression, an assignment, or a
primitive. Use the following syntax in a rule to refer to a slot listed in a global record:

$RecordName.SlotName

The following is a simple example of a global record:

RECORD
UNDER_MAINTENANCE DEFINES {
hosts: LIST_OF STRING ;
}
END

72 BMC Impact Solutions: Knowledge Base Development Reference Guide


Interfaces in rules

Interfaces in rules
Refine rules use interfaces to import external data to the rule engine. For example,
you can create an interface and use it as an interface instance to return data to the
Refine rule.

Interfaces are maintained in .baroc file in %MCELL_HOME%\etc\CellName\kb\classes


on Windows platforms and in $MCELL_HOME/etc/CellName/kb/classes on UNIX
platforms.

Slots defined in an interface follow the same syntax as used in a class definition, as
shown:

MC_INTERFACE: InterfaceName
DEFINES {
SlotName: DataType, Facet, Facet;
SlotName: DataType;
...
};
END

In the following example, the interface is designed to retrieve additional data about a
system that is potentially down.

MC_INTERFACE: LOCATION
DEFINES {
site: STRING;
phone: STRING;
};
END

Interface instances
The pieces of data collected by the external program or script are assigned to the slots
of the interface, creating an interface instance. The life of an interface instance is
limited, since only the calling Refine rule can use it. To access the data in the future,
the slot values must be stored in a global record or an event.

The syntax for an interface instance is as shown:

InterfaceName ;
SlotName = Value ;
SlotName = Value ;
END

Chapter 3 Creating rules 73


Indexes in rules

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 14 provides values for the system location and phone number for the
responsible party.

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 Table 2 on page 27.

Figure 14 Interface instance example


LOCATION ;
site = B3R123 ‘
phone = 555-555-5555 ;
END

Indexes in rules
Use indexes to improve rule performance. Indexes enable the rule engine to find
event or data instances more rapidly. When only a limited selection of instances is
required, an index avoids iteration over all instances. You can also use an index to
determine the order of iteration over a set of event or data instances.

A sorted index implements an order on the instances. If the goal is to determine the
search order, use a sorted index. When the goal is mainly performance improvement,
a hashed index 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 pseudo-rules, which look like rules, but they are different. An
index rule will not do any processing on an incoming event. The syntax for an index
definition within a rule is

index IndexName : CLASS ( sorted|hashed )


Slot | '[' Slot { , Slot } ']'
END

74 BMC Impact Solutions: Knowledge Base Development Reference Guide


Using indexes

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.

You can define more than one index for the same class. A subclass inherits an index
definition from its superclass if one is defined. An index definition for a subclass does
not override an inherited index. All index definitions for a class remain effective
whether they are defined directly for the class or inherited from a superclass.

The following example shows two index definitions. The first is a sorted index for
two slots; the second is a hashed index for a single slot.

index Idx1 : EVENT_CLASS sorted [date_reception,data_handle] END


index Idx2 : BMC_Base_Element hashed Name END

Using indexes
You use an index in a using clause. Instead of specifying a class name, you specify an
index name defined for that class.

The following example shows three general forms of an index using clause.

using index IndexName '[' ']' '(' $IndexVariable ')' [ where '[' ... ']' ]
using index IndexName '[' SlotVal [ { , SlotVal } ] ']' '(' $IndexVariable ')'
[ where '[' ... ']' ]
using index IndexName '[' Slot=SlotVal [ { , Slot=SlotVal } ] ']' '('
$IndexVariable ')' [ where '[' ... ']' ]

The difference among these three forms is in the specification of the actual indexed
slot values.

■ 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.

Chapter 3 Creating rules 75


Using indexes

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.

For these indexes:

index Idx1 : EVENT_CLASS sorted [date_reception,data_handle] END


index Idx2 : BMC_Base_Element hashed Name END

the following example illustrates their use in New rules:

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

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.

76 BMC Impact Solutions: Knowledge Base Development Reference Guide


Relating events

Relating events
Certain operations on an event can generate another event. You can associate that
generated event to the source event. Several types of event relations can occur, such
as the following examples:

■ an action result event related to the event on which an action was performed
■ a trouble ticket event related to the event that automatically created the trouble
ticket

One event can have multiple related events, but a related event can be related to only
one source event. From the source event, you can retrieve all its related events.

The following definitions will help you to better understand this section:

Term Definition
source event an event that generates a related event
related event an event that is generated by a source event

A related event can also be the source of other related events.


relation a logical association that expresses the relevance of one event to another
relation definition a data instance that defines a relation
relation type a string in the relation definition for an event class that indicates its type

Generic event relations mechanism


By using the generic event relations mechanism, you can define relationships
between events. The generic event relations mechanism consists of the following KB
elements:

■ slots in the CORE_EVENT class that identify source events and related events

■ the MC_EVENT_RELATION data class for defining relations

■ the relate and unrelate primitives to establish and remove a relation between
two events

Chapter 3 Creating rules 77


Relating events

■ a console command mechanism that creates a Related Events command so users


can view event relations in the BMC Impact Explorer console, as shown:

Event relation slots


Table 12 lists the CORE_EVENT slots used to identify source events and related events
and the presentation names for those slots that are displayed in the BMC Impact
Explorer and BMC Impact Portal consoles. For more information about the
CORE_EVENT class, see “CORE_EVENT base event class” on page 121.

Table 12 Related event and source event slots


Slot name and definition Presentation name Contains
mc_relation_source Relation Source the mc_ueid of the source event to which this event is related

This slot links a related event to its source event.


mc_event_relations Event Relations 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.

78 BMC Impact Solutions: Knowledge Base Development Reference Guide


Relating events

Figure 15 illustrates how the slots are populated.

Figure 15 Event relations

In a source event, the mc_event_relations


source event slot contains the relation type and the
mc_ueid of one ore more related event.

related event In a related event, the mc_relation_source


and source related event related event slot contains the mc_ueid of the source
event event. A related event can be associated
with only one source event.

related event related event

Event relation data class


The MC_EVENT_RELATION data class defines the types of relations between events. The
presentation name displayed in the BMC Impact Explorer and BMC Impact Portal
consoles for the MC_EVENT_RELATION class is Event Relation.

MC_DATA_CLASS: MC_EVENT_RELATION ISA MC_CELL_DATA


DEFINES {
class : STRING, read_only=yes, key=yes; # Related event class
type : STRING; # Relation type
}; END

You create a relation definition by defining an instance of the MC_EVENT_RELATION


data class. The data instance defines the possible relation types for a specific event
class. For an example, see “Event relation definition example” on page 81.

Slot Value
class specifies the class of the related events

A subclass of a class that is used in a relation inherits this relation. A relation defined
on a more specific class overrides any inherited relation.
type specifies the relation type

Only one type of relation is allowed per event class, and only one event class should
be named explicitly in a relation type.

Chapter 3 Creating rules 79


Relating events

Modifications to an MC_EVENT_RELATION data instance do not affect existing event


relations, even after a cell restart. After two events have been related, they remain
related until they are explicitly unrelated.

WARNING
When an MC_EVENT_RELATION data instance is modified, performing an unrelate operation
on existing event relations of that type might yield unexpected results. Therefore, you should
not modify an existing type of relation as long as there are related events of that type.

Event relation primitives


The following table lists the primitives used to establish and remove event relations.

Primitive Description
relate(Object) establishes a relation between a generated event and a source event

The relation primitive associates the related event’s object handle (Object) to the
source event as set in the mc_relation_source slot of the source event. The
relation type is determined by the class of this event or its most specific superclass
that has a relation type defined.

The result of this operation is that the relation type and the mc_ueid of this event
are added to the mc_event_relations slot of the source event.

For the relation to occur, the mc_relation_source slot of the related event must
be set correctly. The slot should be set by the agent that generates the related event.
However, the fact that this slot has a non-empty value does not imply that this event
is correctly related to the event indicated in the mc_relation_source slot.
unrelate(Object) removes an existing relation between two events

The unrelate primitive uses the related event’s object handle (Object) to remove
the related event’s mc_ueid from the mc_event_relations slot of the source
event.

The related event contains the mc_ueid of the source event in the
mc_relation_source slot. The mc_relation_source slot is not modified.

The rule that performs the unrelate could also clear the mc_relation_source slot
to ensure that the event is no longer related.

80 BMC Impact Solutions: Knowledge Base Development Reference Guide


Event relation definition example

Event relation definition example


Suppose that one relation is evaluated for action results and one is evaluated for
trouble tickets. Whenever an action is performed on an event, a corresponding action
result event is generated. The generated event is related to the source event with a
relation type of action. If an event triggers a trouble ticket to be created in BMC
Remedy Service Desk, it generates a corresponding trouble ticket event that is related
to the source event with relation type of tt_ars.

Instances of the MC_EVENT_RELATION data class define the event relations, as shown:

MC_EVENT_RELATION; type=action; class=MC_CELL_ACTION_RESULT; END


MC_EVENT_RELATION; type=tt_ars; class=ARS_TROUBLE_TICKET; END

Now, event E001 generates the related action result event A001.

EVENT;
mc_ueid=E001;
...
mc_event_relations=[action,A001];
END
MC_CELL_ACTION_RESULT
mc_ueid=A001;
...
event=E001;
mc_relation_source=E001;
END

The generated action event has a slot named event that contains the same value as
the mc_relation_source slot. This ensures backward compatibility with existing
action events.

Chapter 3 Creating rules 81


Creating an event relation definition

Now, event E002 generates the associated trouble ticket event T001 and two action
result events, A002 and A003.

EVENT;
mc_ueid=E002;
...
mc_event_relations=[action,A003,tt_ars,T001,action,A002];
END
MC_CELL_ACTION_RESULT
mc_ueid=A002;
...
event=E002;
mc_relation_source=E002;
END
MC_CELL_ACTION_RESULT
mc_ueid=A003;
...
event=E002;
mc_relation_source=E002;
END
ARS_TROUBLE_TICKET
mc_ueid=T001;
...
mc_relation_source=E002;
END

Creating an event relation definition


Follow these steps to create an event relation definition:

1 In the cell’s \EM or \SM KB directory, which is


%MCELL_HOME%\etc\CellName\kb on Windows platforms and in
$MCELL_HOME/etc/CellName/kb on UNIX platforms, create the files and entries
shown in Table 13.

Table 13 Example event relation definitions (part 1 of 2)


File to create Entry to include in file
classes/test_tt.baroc MC_EV_CLASS: ARS_TROUBLE_TICKET ISA EVENT; END
data/test_tt.baroc MC_EVENT_RELATION; class=ARS_TROUBLE_TICKET; type=tt_ars; END
rules/test_tt.mrl refine ars_trouble_ticket_relate : ARS_TROUBLE_TICKET($E)
{ relate($E); }
END
execute ars_trouble_ticket_unrelate : ARS_TROUBLE_TICKET($E)
when $E.status != OPEN { unrelate($E); }
END
bin/test_tt.mrl action ARS test_tt [] END

82 BMC Impact Solutions: Knowledge Base Development Reference Guide


Compiling rules

Table 13 Example event relation definitions (part 2 of 2)


File to create Entry to include in file
bin/A/test_tt mposter -n $CELL_NAME -a ARS_TROUBLE_TICKET -b
"mc_relation_source=$mc_ueid;"
bin/w4/test_tt.cmd @echo off
mposter -n %CELL_NAME% -a ARS_TROUBLE_TICKET -b
mc_relation_source=%mc_ueid%;

2 Add test_tt to the .load file in the \classes, \data, \rules, and \bin directories.

3 Stop the cell, compile the KB, and restart the cell.

For information, see “Managing a Knowledge Base” on page 29.

4 In BMC Impact Explorer, connect to the cell.

For instructions, see BMC Impact Solutions: Event Monitoring Operator’s Guide.

5 In the Events list, right-click an event and choose Actions => Remote Actions=> ARS.

The following events are generated:

MC_CELL_ACTION_RESULT
ARS_TROUBLE_TICKET

6 To view the event relations, choose View => Related Events and then select the
relation type.

7 Select the ARS_TROUBLE_TICKET event and close it.

The ARS_TROUBLE_TICKET event is unrelated.

Compiling rules
Rules do not immediately start processing events after they are created. The
Knowledge Base (KB) for the cell must be compiled so the rules are read into it. You
can use the mccomp command to compile the KB. For more information about using
the mccomp command, see “Compiling a Knowledge Base—mccomp” on page 30.

NOTE
To monitor rule behavior you can compile the KB with a tracing option. For more information,
see “Effects of compiling a Knowledge Base with tracing enabled” on page 30.

Chapter 3 Creating rules 83


Testing a rule

Testing a rule
You can test a rule to verify that it processes events correctly. The process for testing a
rule is to send an event to a cell and then review how the event is processing through
the rules.

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 BMC Impact Solutions: General
Administration.

To review event processing

Use rule tracing as described in “Tracing a rule.”

Tracing a rule
Tracing enables you to follow the flow of events through each rule phase. Tracing the
execution of a rule also helps Knowledge Base developers to find logical errors or
enhance performance.

The MRL compiler (mccomp) generates rule trace code that contains the following
fields:

■ 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.

84 BMC Impact Solutions: Knowledge Base Development Reference Guide


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)

Chapter 3 Creating rules 85


Configuring rule tracing

■ using—a message is displayed when an object instance is retrieved by a query in a


using block. For example,

ruleTrc9612.mrl, 31: refine idx_data_s: IDX_EVENT #5: solution 1 to data query:


$X = 0x13c5468 (class: IDX_DATA, data_handle: 374, mc_udid: mc.ruleTrc9612.7f100f7.327)

■ using_policy—a message is displayed when a policy is retrieved by a query in a


using_policy block. For example,

im_internal.mrl, 207: refine im_internal_timeout: EVENT #5: solution 1 to policy query:


$POL = 0x109e4b8 (class: IM_TIMEOUT_POLICY, data_handle: 32, mc_udid:
mc.ruleTrc9612.7de9405.19)

■ using_failure—a message is displayed when there are no instances that statisfy


a query in a using block. For example,

ruleTrc9612.mrl, 13: refine idx_event_h: IDX_EVENT #5: no solution for $X in context


$E = 0x146ca80 (class: IDX_EVENT, event_handle: 5, mc_ueid: mc.ruleTrc9612.7f100f7.349)

■ using_policy_failure—a message is displayed when there are no instances that


statisfy a query in a using_policy block. For example,

im_internal.mrl, 18: refine im_internal_blackout: EVENT #5: no solution for $POL in context
$EV = 0xd926d0 (class: EVENT, event_handle: 5, mc_ueid: mc.ruleTrc9612.7de940c.0)

■ assign—a message is displayed for each assignment instruction. For example,

im_internal.mrl, 167: refine im_internal_default_location: EVENT #5: $EV.mc_location =


'bmc.com'

Static rule tracing configuration example

TraceRuleLevel=2
TraceRulePhases=ALL,-refine,-regulate
TraceRuleNames=TroubleTicketing:ALL,-
TroubleTicketing:rule1,SendMail:rule1,SendMail:rule2
TraceRulePorts=entry,assign

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.

86 BMC Impact Solutions: Knowledge Base Development Reference Guide


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 85.

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.

Chapter 3 Creating rules 87


Customizing rule trace message headers

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:

TraceRuleHeader= %F, %L: %P %R: %C #%H:

results in messages like:

mc_intevt.mrl, 42: new StbldStop: MC_CELL_STATBLD_STOP #118: Rule execution starting

The text of the message is retrieved from the message catalog through the message
identifier and can be localized.

88 BMC Impact Solutions: Knowledge Base Development Reference Guide


Chapter

4
4 Creating collectors
This chapter presents the following topics:

Collector overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Creating or modifying a collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Collector syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Best practices for defining collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Collector security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Defining static collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Defining dynamic collectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Default event management collectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
self_collector.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
catchall_collector.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
mc_bystatus_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
mc_bylocation_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
MCxP collector set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
bii4p_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
mc_evr_collectors.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Default service impact management event collector . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Chapter 4 Creating collectors 89


Collector overview

Collector overview
Event collectors group events for display in an event list. You create event collectors
to provide operators with meaningful groups of events and to show relationship
through the hierarchy of the nodes in the navigation tree. An event collector defines
which events should appear in an event list and also specifies which user roles have
access to the events in an event list. Operators access the event list for an event
collector by clicking the event collector node in the navigation tree.

Event collectors are dynamic or static.

■ Nodes for dynamic event collectors appear or disappear from the navigation tree
based on whether events are present that meet the event collectors’ criteria.
■ Nodes for static event collectors remain in the navigation tree whether events 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.

Figure 16 shows the default collector tree for a cell in BMC Impact Explorer.

Figure 16 Collectors in BMC Impact Explorer

90 BMC Impact Solutions: Knowledge Base Development Reference Guide


How collectors are structured

NOTE
A collector that contains grouped events from multiple cells is called a MetaCollector. A
MetaCollector exists in the BMC Impact Explorer only as a virtual collector that operators can
customize according to their requirements. A MetaCollector can contain collectors from
multiple cells across the network. For more information about MetaCollectors, see BMC
Impact Solutions: Event Monitoring Operator’s Guide.

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 BMC Impact Explorer.

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.

NOTE
An incoming event that changes slot conditions can move from one collector to another
within a cell.

For more information about collectors and how event status and severity are
displayed, see BMC Impact Solutions: Event Monitoring Operator’s Guide.

Chapter 4 Creating collectors 91


Creating or modifying a collector

Creating or modifying a collector


The 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 instructions, see “Managing a Knowledge Base” on page 29.

The following topics describe how to create or modify a collector:

■ “Collector syntax” on page 92


■ “Collector security” on page 95
■ “Defining static collectors” on page 97
■ “Defining dynamic collectors” on page 98

Collector syntax
Figure 17 Collector definition syntax
2
3

1 4

collector CollectorName {[ r | w | x Role ]}


5
[create Expression
6
[ delete ] ]
7
[ CLASSEVENTNAME where
8
[slot_name: condition_operator slot_value,

. . . ]

| CatchAll ]

END

92 BMC Impact Solutions: 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 98 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 in BMC Impact Explorer 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 4 Creating collectors 93


Best practices for defining collectors

# Description
7 identifies which events require further processing by the collector

This section is referred to as an Event Condition Formula (ECF). The ECF includes the name of the event
class and all the slot conditions for that class.

Note: The ECF portion of a collector can contain references to the dynamic data by using a Using clause.
Use this type of reference with extreme care because it can result in the performance degradation of the
cell, particularly when large tables are searched on unindexed slots.
8 collects all events, including any events not picked up by the collectors you define

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:

collector HostsDown : HOST_DOWN


END

is more efficient than

collector HostsDown : EVENT


where (CLASS: equals ‘HOST_DOWN’)
END

■ 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.

collector AllHostsEvents : HOST_EVENT


END

94 BMC Impact Solutions: 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.

collector HostsEvents : EVENT


where (CLASS: equals ‘HOST_EVENT’)
END

■ 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 BMC Impact Explorer console.
For example, a user might be able to connect to a cell but not view all the collectors.

Table 14 lists the standard BMC Impact Manager roles that can be defined within the
collectors.

Table 14 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

For more information about user roles in BMC Impact Manager, see the BMC Impact
Solutions: General Administration.

Chapter 4 Creating collectors 95


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 18 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.

Figure 18 Collector tree definition example


collector self:
{r[Full Access]; w[Full Access]; x[Full Access]}
END
collector c1:
{r[Service Administrator,Service Operators]; w[Service Administrator,Service
Operators]; x[Service Administrator,Service Operators]}
END
collector c1.one:
{r[Service Managers-Senior]}
END
collector c1.two:
{r[Service Managers-Senior], w[Service Managers-Senior]}
END
collector c2:
{r[Service Managers-Senior,Service Administrator]; w[Service Managers-
Senior,Service Administrator]; x[Service Managers-Senior,Service Administrator]}
END
collector c2.one:
{r[Service Operators], w[Service Operators]}
END
collector c2.two:
{r[Service Operators]}
END

The following points describe the user roles and associated permissions for the
collectors defined in Figure 18:

■ 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.

96 BMC Impact Solutions: 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 19, 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.

Figure 19 Static collector example 1


collector self :
END
collector Networks :
{ r [Service Administrator] }
END
collector Networks.Local :
{ r [Service Operators]
w [Service Operators, Service Administrator]
} :
EVENT where
[source: ip_matches 172.16.23.<128]
END

collector Networks.Remote :
{ w [Service Administrator] } :
EVENT where
[source: ip_matches 172.16.23.>128]
END

The Local and Remote child collectors in Figure 19 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.

Chapter 4 Creating collectors 97


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 20, the static collectors are defined with single
and multiple ECFs.

Figure 20 Static collector example 2


collector AllEvents :
{r [Service Operators, Service Administrator, Full Access ]
w [Service Operators, Service Administrator, Full Access ]
x [Service Administrator, Full Access]
}
END
collector AllEvents.Open :
EVENT where [status: equals OPEN]
END

collector AllEvents.Ack :
{x [Service Operators]}:
EVENT where [status: equals ACK,
severity: equals FATAL]
EVENT where [severity: not_equals UNKNOWN]
END
collector AllEvents.NotOpen :
EVENT where [status: not_equals OPEN]
END

When a collector uses multiple ECFs, you must ensure that the ECFs match outcomes.
For example, in Figure 20 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.

98 BMC Impact Solutions: 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:

MC_EV_CLASS: NET ISA EVENT ; END

In the following example, NET events are generated for network-related issues. When
the issue is specific to a subsystem, the kind of subsystem is specified in the
mc_object_class slot. The collector definitions shown create a collector structure for
each subsystem that produces events. The name of the collector is determined by the
mc_object_class slot. Events that are not related to a specific subsystem are
collected in the Global subcollector.

Within the subsystem collector, a distinction is made between events coming from
servers and events coming from clients. When the mc_origin_class slot has the
value SERVER, the event is assumed to come from a server. In that case, a subcollector
is created for each server that produces events. The name of the subcollector is taken
from the mc_origin slot.

collector Net END


collector Net.* : NET where [$THIS.mc_object_class != '']
create $THIS.mc_object_class delete
END
collector Net.*.Server : NET where [$THIS.mc_origin_class == SERVER]
END
collector Net.*.Server.* : NET
create $THIS.mc_origin
END
collector Net.*.Client : NET
END
collector Net.Global : NET
END

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.

collector Net.*.Server.* : { r[$THIS.mc_origin] } : NET


create $THIS.mc_origin
END

This example assigns a read permission to a role having the same name as the value
of the mc_origin slot. For example, if the name of a server is host12 in an event, the
dynamic collector creates a new collector host12. The role host12 must be listed in
the list of roles if it is to see what is contained in the collector.

Chapter 4 Creating collectors 99


Default event management collectors

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. For
more information about user roles, see BMC Impact Solutions: General Administration.

Default event management collectors


The 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.

Figure 21 Self collector definition


collector self :
{
r['Full Access']
w['Full Access']
x['Full Access']
}
END

catchall_collector.mrl
The catchall collector defines the All Events collector for a cell, which is the last
collector in the tree. This collector is used to capture events that do not match any
collector criteria.

Figure 22 Catchall collector definition


collector 'All Events' :
{
r['Service Administrators']
w['Service Administrators']
x['Service Administrators']
}

catchall
END

100 BMC Impact Solutions: Knowledge Base Development Reference Guide


mc_bystatus_collectors.mrl

mc_bystatus_collectors.mrl
This file defines the By status collector set. Table 15 lists the collectors included in
the mc_bystatus_collectors.mrl file.

Table 15 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

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 16 lists the collectors included in the
mc_bylocation_collectors.mrl file.

Table 16 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 4 Creating collectors 101


MCxP collector set

Table 16 By Location collector set (part 2 of 2)


Subcollector branch Description
‘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.

MCxP collector set


The MCxP collector set contains a hierarchy of dynamic collectors that collect
PATROL_EV events.

Table 17 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.

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.

102 BMC Impact Solutions: 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. The event
relations collector tree is not visible in the Events View in BMC Impact Explorer. 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 23 shows the
MC_SMC_EVENTS collector definition.

Figure 23 MC_SMC_EVENTS collector definition


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

An example query issued by the collector is shown in the following example:

select open events from collector MC_SMC_EVENTS.component_type


where [$THIS.mc_smc_id equals component_mc_udid]

Chapter 4 Creating collectors 103


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

104 BMC Impact Solutions: Knowledge Base Development Reference Guide


Chapter

5
5 Creating remote actions
This chapter describes how to create and use actions to execute a script or program
against an event or data instance. This chapter presents the following topics:

Remote actions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106


Remote action execution methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Remote action result events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Location of remote actions and executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Remote action definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
File naming guidelines for action executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Defining a remote action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Remote action definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Remote action execution results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Action execution variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Defining a remote action in a BMC Impact Manager cell . . . . . . . . . . . . . . . . . . . 115

Chapter 5 Creating remote actions 105


Remote actions overview

Remote actions overview


Actions are a series of commands executed on an event or data instance. 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 an Impact Manager (cell).
These actions usually are launched by a user in the BMC Impact Explorer (IX) console
but can also be triggered by rules. In both cases, the action runs in the cell’s
environment.

Actions defined in a cell are remote actions. Actions defined in IX are local actions.
Remote actions are executed remotely (by the Impact Manager) in IX, while local
actions are executed on the system running IX. For information on local actions, see
BMC Impact Solutions: General Administration.

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.

The action definition can prompt the user performing the action for arguments. 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.

Remote action execution methods


There are two methods by which remote actions can be executed:

■ in the BMC Impact Explorer console by an operator

The action name and arguments are displayed in the console. The operator is asked
to provide values for the arguments when performing an action on an event.
Actions performed from the BMC Impact Explorer console always generate a
result event in the form of MC_CELL_ACTION_RESULT.

■ in rules using the perform primitive (see the perform primitive on page 169)

If an action is executed in a rule, an action result event is not automatically


generated, nor is the result available in the BMC Impact Explorer console. If you
want to generate an action result event, you must code the action definition to
generate it.

External program actions are executed asynchronously; therefore, an asynchronous


result notification mechanism is provided.

106 BMC Impact Solutions: Knowledge Base Development Reference Guide


Remote action result events

Remote action result events


An external action that is performed on an event from the console will result in
another event. An event that occurs as the result of an action is designated as an
internal event of class MC_CELL_ACTION_RESULT.

This MC_CELL_ACTION_RESULT instance consists of the return code and the standard
output and error streams produced by the external program. If the size of those
streams is not too large, they are included literally in the action result event.
Otherwise, they are stored in a file whose reference name is stored in the action result.
The size limit is set with configuration parameter ActionResultInlineLimit, which
has a default value of 4096, or 4KB. For information about this parameter, see BMC
Impact Solutions: General Administration.

Location of remote actions and executables


Actions and relevant executables are placed in the cell’s kb\bin directory. The
subdirectory location within the bin directory depends on the platform type on which
the cell is running, as defined in Table 18:

Table 18 Standard locations for action executables


Directory Platform
A independent
h1 HP-UX 11+
l2 Linux
p4 AIX
s5 Solaris
w4 Windows

Executables that can run on multiple platforms, such as all UNIX, can be located in
the A subdirectory. A cell first looks for executables in the platform-specific directory,
and then in the independent directory (A). An executable also can be located
anywhere on a file system. In that case, the cell requires the path to the executable in
order to locate it.

Remote action definitions


Remote actions are defined in .mrl files and saved within the Knowledge Base, and
are defined in the cell’s kb\bin directory at the root level. The action definition
includes the action name as it appears in BMC Impact Explorer and the path to the
associated executable.

Chapter 5 Creating remote actions 107


File naming guidelines for action executables

The action definition also can indicate permission roles that are required in order to
perform the action. An optional selection condition indicates the events to which the
action is restricted. The definition also lists the requested arguments by name or
description.

File naming guidelines for action executables


Files are executable under different conditions, depending on the operating system.
On UNIX systems, the file's execute permission must be set, and the file must have an
UNIX executable file format. Also on UNIX, a text file is considered executable if it
begins with the characters #! followed by a path used to interpret the script. On
Windows platforms a file is executable if it has a suffix that corresponds to an
executable system. These suffixes are listed in the PATHEXT environment variable.

Defining a remote action


This section describes how to define a remote action in the KB of a cell. You can also
refer to the “Remote Execution” chapter in the BMC Impact Solutions: General
Administration guide.

Remote action definitions


The following sections describe how to define a remote action, as well as how to
specify roles and arguments. This section also provides examples of remote actions.

Common action rule syntax


Both internal and external remote actions are defined through an action rule. The
basic syntax of an action rule is shown in Figure 24.

Figure 24 Action rule syntax


action ActionName : { [ Role , Role , ... ] } [ Argument , Argument , ... ]
ActionCodeInternal
END
action ActionName [ Argument , Argument , ... ]
ActionCodeInternal
END
action ActionName : { [ Role , Role , ... ] }
ActionCodeInternalOrExternal
END
action ActionName

108 BMC Impact Solutions: Knowledge Base Development Reference Guide


Remote action definitions

Figure 24 Action rule syntax


ActionCodeInternalOrExternal
END

Table 19 describes the variables of the action rule syntax.

Table 19 Action rule syntax variable descriptions


Variable Description
ActionName ActionName is the name that is used to
represent the action in a console and to refer to
the action when performing it from a rule. For
example, an ActionName could be SendMail or
ModifyEvent.

For more information, see “Specifying an action


name” on page 109.
Role [Optional.] Role specifies the permissions
required to perform the action. The use of roles
only applies when you are performing the
action from a console. An example of a role is
Service Administrators.

For more information, see “Specifying roles” on


page 110.
Argument [Optional.] Argument is used as label in a
console to request an actual value for the
argument from the user.

For more information, see “Specifying arguments”


on page 110.
ActionCodeInternal ActionCode represents the code that defines the
ActionCodeInternalOrExternal actual internal or external action.

For more information, see “ActionCode syntax for


external actions” on page 110 and “ActionCode
syntax for internal actions” on page 111.

Specifying an action name


An action name can be a single name, or a composed name, consisting of two names
separated by a period. The name before the period is the action group name, and the
name after the period is the base name of the action. For example, the default KB
includes a group of actions called im_operations. A composed name of an action
within this group is im_operations.Acknowledge. If the group name is not
specified, it is considered to be the empty string (‘’”). Actions can be displayed in a
console by group. The action name can be displayed in its localized language instead
of the value in the KB.

Chapter 5 Creating remote actions 109


Remote action definitions

Specifying roles
Roles (permissions) are optional. Roles for remote actions are specified as they are in
other types of rules. If you choose to provide roles, roles specify the permissions
required to perform the action. The use of roles only applies when you are
performing the action from a console. When performing the action from a rule, roles
are ignored.

Figure 25 provides an example of an action that is limited to the Service


Administrators role.

Figure 25 Example of a specified role


action ModifySlotValue : { ['Service Administrators'] }
mc_modslot [SlotName , NewValue ]
END

Specifying arguments
Arguments are optional. If you choose to include action arguments, specify them as a
list, using the following format for each argument as shown in Figure 26.

Figure 26 Action argument syntax


ArgumentName : SlotType ( $Variable )
ArgumentName : SlotType
ArgumentName ( $Variable )
ArgumentName ( $Variable )

A standard slot type declaration is used to specify the type of the value that is
expected for the argument. This can be a single value or a list of single values
(LIST_OF). If no type declaration is provided, it defaults to STRING.

If a Variable is specified, the actual value of the argument is available in the action
code through that variable.

For an external action, the optional arguments are specified inside the ActionCode.
For more information, see “ActionCode syntax for external actions.”

ActionCode syntax for external actions


For external actions, the action code is one of four types:

■ an action with arguments that will be performed on an event that matches the
specified selection conditions

: Selection ActionProgram [ Argument , Argument , ... ]

110 BMC Impact Solutions: Knowledge Base Development Reference Guide


Remote action definitions

■ an action without arguments that will be performed on an event that matches the
specified selection conditions

: Selection ActionProgram

■ an action with arguments that is performed on any event

ActionProgram [ Argument , Argument , ... ]

■ an action without arguments that is performed on any event

ActionProgram

Selection specifies an optional condition (where-clause) on the events. It has the


same form as in other rules. The action will not be performed on an event that does
not match those conditions. The arguments are specified as above. However, for
external actions, any variables in the specification are ignored.

The ActionProgram is the name of the external program or script to be executed. If


this program or script is not available from the kb/bin directory, you must specify the
full path to the executable program.

ActionCode syntax for internal actions


For internal actions, the action code syntax is one of two types:

■ an action that is performed on any event

{ Call ; Call ; ... }

■ an action that is only performed on an event matching the specified selection


conditions

: Selection { Call ; Call ; ... } Selection { Call ; Call ; ... } ...

The action code can contain zero or one or more Selection criteria that specify
conditions on the event. If Selection is not defined, the action code applies to any
event. If a Selection is included, the event is evaluated against the selection
condition. Only the piece of code following the first matching selection is performed
on the event. If no selection conditions match, then no code is performed.

Chapter 5 Creating remote actions 111


Remote action definitions

The action code itself is a sequence of calls, similar to other rules. Within these calls,
the actual values of the action arguments are available through the variables that are
specified in the argument list. For example, a call might be the following primitive to
retrieve the requestor of the action;

action_requestor( $REQ )

Another call might be the following function to retrieve the requestor of the action:

action_requestor()

An internal action can return a value consisting of a numeric return code and a return
text by calling the following primitive at the end of the internal action code:

action_return( ReturnCode , ReturnText )

Performing an action from a rule


Actions can be performed by an operator from a console or from a rule. To perform
an action from a rule, the primitive in Figure 27 must be called.

Figure 27 Primitive to perform an action from a rule


perform( $EVENT , ActionName , [ $ARG1 , $ARG2 , ... ] , $RET_CODE , $RET_TEXT )
perform( $EVENT , ActionName , [ $ARG1 , $ARG2 , ... ] )

The action designated by ActionName is performed on the event that is represented


by $EVENT. Actual values for the action arguments must be of the declared type. The
first form retrieves the return value of the action. For an internal action, that is the
value returned with action_return. For an external action, the value will be 0 and
the empty string.

Examples of actions
The following sections provides examples of internal and external actions.

Close any event

The following example illustrates an internal action to close any event:

action CloseEvent : EVENT($E) { $E.status = CLOSED; } END

112 BMC Impact Solutions: Knowledge Base Development Reference Guide


Remote action execution results

Assign an event owner to a specified value

The following example illustrates an internal action to assign an event owner to a


specified value:

action AssignEvent [To:STRING($D)] : EVENT($E) { $E.mc_owner = $D; } END

Modify an event slot value

This action can be defined as either an internal or external action. The internal action
yields better performance than the external action that performs the same function.

The following example illustrates an internal action that allows only users with the
Service Administrators role to modify an event slot value:

action ModifySlotValue : { ['Service Administrators'] }


[SlotName:STRING($SLTNM),NewValue:STRING($VAL)] : EVENT($E)
{ set_list_slotvalues([$E],[$SLTNM],[$VAL]); }
END

The following example illustrates an external action that allows only users with the
Service Administrators role to modify an event slot value:

action ModifySlotValue : { ['Service Administrators'] }


mc_modslot [SlotName , NewValue ]
END

Remote action execution results


The standard cell action mechanism provides for results consisting only of the
standard output and error stream; you must implement other mechanisms. If the
result must be in a file, the external program can write the file and return the file path
in the standard output stream. The external program also can use a CLI to modify a
cell event or to send a new event to the cell containing the desired result.

NOTE
It is impossible to return an exit code from a .bat script on Windows operating systems
versions prior to Windows 2000. This is a Windows/DOS limitation. However, you can
circumvent this limitation. By definition, the exit code of the script is the exit code of the last
executed external program. You can write a small C program whose only function is to return
the argument it receives as the exit code, as shown in Figure 28. Call that program from the
script with an argument that specifies the desired exit code. This program should be placed in
the kb\bin\w4 directory.

Chapter 5 Creating remote actions 113


Action execution variables

Figure 28 Example of exit code that returns an argument


exitcode.c
int main( int argc , char *argv[] )
{
return( ( argc <= 1 ) ? 0 : atoi(argv[1]) );
}

To return 123 as the exit code, call the special program at the end of the script as:

Figure 29 Example of exit code that returns a specified value


exitcode 123

Action execution variables


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. In addition, the variables listed in Table 20 are added by the
cell.

Table 20 Action execution variables


Variable Description
<slot> For every slot listed in SLOTS, a variable is defined with the name of the
slot and as value the slot value.
CELL_BUILD build number of the cell
CELL_DATE cell build date
CELL_NAME name of the cell
CELL_RELEASE release number of the cell
CLASS class name of the event on which the action is performed
MCELL_HOME cell home directory
PKG_NAME name of package containing the rule that triggered the action

The variable is empty if the action was triggered by an operator.


REQUESTOR identification of the requestor of the action

For a rule, it is package:rule and for an operator, it is user@host.


RULE_NAME name of the rule that triggered the action

The variable is empty if the action was triggered by an operator.


SLOTS list of colon-separated names of the event’s defined slots

The action execution trigger, such as rule name or user name, can be passed as an
environment variable.

114 BMC Impact Solutions: Knowledge Base Development Reference Guide


Defining a remote action in a BMC Impact Manager cell

Defining a remote action in a BMC Impact Manager cell


1 Place the script or executable files in their corresponding OS folders in the kb\bin
directory, as detailed in Table 18 on page 107.

2 Create an .mrl file to refer to the executable and define the action or add the file to
an existing .mrl file as explained in “Defining multiple actions in one file” on
page 115.

3 If you created a new <actions>.mrl file, update the .load file to reference the .mrl file
in the kb\bin directory.

4 Compile the Knowledge Base, using the mccomp command.

5 Restart the cell and test the remote action from the rules or from the BMC Impact
Explorer console.

Defining multiple actions in one file


Multiple actions can be defined in a single .mrl file, as shown.

<Actions>
<ActionDef id="" type="executable" target="">
<Argument label=""
tip=""required="Y|N|T|F|yes|no|true|false" defaultvalue=""
type="" fieldsize="" rows=""columns=""/>
<Argument label="" tip""required=required"" defaultvalue=""
type="" fieldsize="" rows="" columns=""/>
<Argument label=""tip""required=required""defaultvalue=
""type=""fieldsize=""rows="" columns=””/>
</ActionDef>
<ActionDef id=""label=""type"executable"target=""/>
</Actions>

Table 21 lists the tags for the syntax.

Table 21 Tags for defining multiple local actions in one file (part 1 of 2)
Tags Attributes
ActionDef “label” shows as the name of the action in the action tree; if not specified, label
= “”
ActionDef “target” for fully qualified path to an executable to be run when executing action; if
not specified, target = “”
type = “executable”
ActionDef “id” identifies the action; if not specified, id = “”
Argument “label” name of the argument; if not specified, default value = “”

Chapter 5 Creating remote actions 115


Defining a remote action in a BMC Impact Manager cell

Table 21 Tags for defining multiple local actions in one file (part 2 of 2)
Tags Attributes
Argument “tip” tooltip to be shown when hovering over the argument label; if not
specified, default value = “”
Argument “required” determines if this argument is required; if not specified,

required = “false”
Argument “defaultvalue” default value to be displayed for the argument; if not specified,
default value = “”
Argument “fieldsize” size of the argument field; if not specified, field size = 50
Argument “type” type of argument, either: ‘textfield’ or ‘textarea’; if not
specified, type = textfield
Argument “rows” number of rows to make the displayed size of the text area

Only use if type = ‘textarea’; if not specified, rows = 5


Argument “columns” number of columns to make the displayed size of the text area

Only use if type = ‘textarea’; if not specified, columns = 25

116 BMC Impact Solutions: Knowledge Base Development Reference Guide


Appendix

A
A Event and data classes
This appendix provides information on the hierarchical structure, class files, and slot
information for the CORE_EVENT and CORE_DATA base classes. This appendix presents
the following topics:

BMC Impact Manager class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118


Event class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
CORE_EVENT base event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
EVENT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
MC_CELL_CONTROL event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Data class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
CORE_DATA base class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
MC_SM_DATA data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
MC_CALENDARING data class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
BEM_MATCH_TABLE data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
POLICY data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
SELECTOR data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Cell information class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Deprecated slots and their replacements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Appendix A Event and data classes 117


BMC Impact Manager class files

BMC Impact Manager class files


Table 22 lists the BAROC files contained in the BMC Impact Manager 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 22 Default Knowledge Base class files (part 1 of 2)


File name Description
apache.baroc Apache log file adapter class definitions
bii4p.baroc BMC Impact Integration for PATROL 7 class definitions
bem_match_table.baroc data class for defining match tables

For further information, see “BEM_MATCH_TABLE data class” on


page 130.
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 a BMC
Impact Manager event processor
ips.baroc generates events for monitoring the BMC Impact Publishing Server

To enable generation of Publishing Server monitoring events, see


BMC Impact Solutions: General Administration.
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.

118 BMC Impact Solutions: Knowledge Base Development Reference Guide


BMC Impact Manager class files

Table 22 Default Knowledge Base class files (part 2 of 2)


File name Description
mc_root_redef.baroc redefinition of the core event class

This file includes classes and attributes (slots) that have been
deprecated in this release and prior releases of the product.
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 new 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 state change events for service model component instances with an
associated SLA
mc_tec_severity.baroc enumeration definitions

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.
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 provides STATE_CHANGE_EVENT backward compatibility from
SIM_NOTIFICATION_REGISTRY events

Appendix A Event and data classes 119


Event class hierarchy

Event class hierarchy


The classes listed in Figure 30 presents the hierarchical relationship between
CORE_EVENT and its subclasses. Only high-level classes and sub-classes are listed.

Figure 30 CORE_EVENT class hierarchy

CORE_EVENT

EVENT

MC_CELL_EVENT

MC_UPDATE_EVENT

MC_SMC_ROOT

MC_MCCS

MC_CLIENT_BASE

MC_ADAPTER_BASE

PEM_EV

PATROL_EV

MC_CELL_CONTROL

MC_CELL_START

MC_CELL_STOP

MC_CELL_TICK

MC_CELL_STATBLD_START

MC_CELL_STATBLD_STOP

MC_CELL_DB_CLEANUP

MC_CELL_CONNECT

MC_CELL_CLIENT

MC_CELL_DESTINATION_UNREACHABLE

MC_CELL_HEARTBEAT_EVT

MC_CELL_RESOURCES

MC_CELL_ACTION_RESULT

MC_CELL_PUBLISH_RESULT

120 BMC Impact Solutions: Knowledge Base Development Reference Guide


CORE_EVENT base event class

CORE_EVENT base event class


CORE_EVENT is the base class for all BMC Impact Manager event classes. Its class
definition is internal and is not visible in the Knowledge Base. This internal class is
defined in the mc_root_internal.baroc file, and extended in the mc_root_redef.baroc file.

All BMC Impact Manager components populate these slots as specified. Internal cell-
generated events are also populated as specified.

Table 23 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 INTEGER timestamp as set by the source of the event
represenation = date
If not set by the source, on its arrival at a cell,
its value is set to the value of
incident_time. If there is no
incident_time value, its value is set to the
mc_arrival_time value.
duration INTEGER, elapsed time, in seconds from event creation
parse = no to the time the event was closed
event_handle INTEGER event identifier in the local cell
parse = no
mc_abstracted LIST_OF INTEGER system reserved
parse = no
mc_abstraction LIST_OF INTEGER system reserved
parse = no
mc_account STRING identifies the account associated with the
event.
mc_acl LIST OF STRING list of the roles that have access to a
parse = no component or event in BMC Impact Explorer

Role ownership for the event is determined by


adding roles defined in this slot to those roles
defined on a collector that contains the event.
Event-level, role-based access is implemented
in BMC Impact Explorer.
mc_action_count INTEGER number of actions performed on the event
parse = no

Appendix A Event and data classes 121


CORE_EVENT base event class

Table 23 CORE_EVENT base class slots (part 2 of 7)


Slot Type Description
mc_arrival_time INTEGER timestamp when the event arrived at the BMC
representation = date Impact Manager network at either an adapter
or a cell

Its value is never zero (0).


mc_associations LIST_OF STRING system reserved
parse = no
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 INTEGER system reserved
parse = no
mc_client_address STRING network address of the host where the adapter
parse = no that sent the event is running
mc_collectors LIST_OF STRING system reserved
mc_date_modification INTEGER timestamp of last modification of certain slots
representation = date
The slots are those mentioned in
mcell.modify.
mc_effects LIST_OF INTEGER system reserved
parse = no
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_vers
ion>) 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 STRING a list of tuples
parse=no, hidden=yes
■ 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_history LIST_OF STRING system reserved
mc_host STRING fully-qualified name of the host on which the
problem occurred

122 BMC Impact Solutions: Knowledge Base Development Reference Guide


CORE_EVENT base event class

Table 23 CORE_EVENT base class slots (part 3 of 7)


Slot Type Description
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 INTEGER timestamp corresponding to the time at which
representation = date 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 INTEGER timestamp when the event arrived in the local
representation = date component

It is never zero (0).


mc_location STRING location at which the managed object resides
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.

Appendix A Event and data classes 123


CORE_EVENT base event class

Table 23 CORE_EVENT base class slots (part 4 of 7)


Slot Type Description
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 BMC
Impact Manager, 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

124 BMC Impact Solutions: Knowledge Base Development Reference Guide


CORE_EVENT base event class

Table 23 CORE_EVENT base class slots (part 5 of 7)


Slot Type Description
mc_parameter STRING name of the metric or property that went into
alarm or that triggered the event
mc_parameter_value STRING actual value of the parameter
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_priority MC_PRIORITY current priority of the event
default = PRIORITY_5
Possible values include
■ PRIORITY_5 (lowest priority)
■ PRIORITY_4
■ PRIORITY_3
■ PRIORITY_2
■ PRIORITY_1 (highest priority)

mc_propagations LIST_OF STRING system reserved


parse = no
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_causes LIST_OF STRING obsolete
parse = no
mc_smc_effects LIST_OF STRING obsolete
parse = no
mc_smc_id STRING event is attached to the SIM component with
the specified identifier
mc_smc_impact INTEGER set to 1 if event has an impact on a SIM
default = 0 component

Appendix A Event and data classes 125


CORE_EVENT base event class

Table 23 CORE_EVENT base class slots (part 6 of 7)


Slot Type Description
mc_smc_priority REAL prioritizes events with respect to their impact
parse = no 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_type STRING value is set to the class of the SIM component
to which the event is attached
mc_timeout INTEGER event timeout in seconds
mc_tool STRING where any event 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, it


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.
mc_tool_address STRING the network address of the Reporter
mc_tool_class STRING 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.
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

126 BMC Impact Solutions: Knowledge Base Development Reference Guide


EVENT class

Table 23 CORE_EVENT base class slots (part 7 of 7)


Slot Type Description
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
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 SEVERITY severity value of the event
default = WARNING
status STATUS status value of the event
default = OPEN

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.

MC_CELL_CONTROL event class


The MC_CELL_CONTROL class is a subclass of the CORE_EVENT base class.

Table 24 MC_CELL_CONTROL slot definitions


Slot Type Description
cell_name STRING name of the cell
cell_location STRING location information for the cell

Appendix A Event and data classes 127


Data class hierarchy

Data class hierarchy


The classes listed in Figure 31 presents the hierarchical relationship between
CORE_DATA and its subclasses. Only high-level classes and subclasses are listed.

Figure 31 CORE_DATA class hierarchy

CORE_DATA

DATA

MC_CELL_DATA

MC_CELL_DIR_COMPONENT

MC_CELL_REGULATE

MC_CELL_HEARTBEAT

MC_CELL_METRIC

MC_EVENT_RELATION

MC_ACL

MC_CALENDARING

TIME_ZONE

TIME_FRAME

SCHEDULE

MC_SM_DATA

BMC_BaseElement

BMC_Impact

BMC_SIM_DATA

MC_SIM_INTERNAL

MC_SM_CUSTOM

MC_SM_ALIAS

SIM_NOTIFICATION_REGISTRY

BEM_MATCH_TABLE

PATROL_IDX

POLICY

IM_POLICY

SELECTOR

128 BMC Impact Solutions: Knowledge Base Development Reference Guide


CORE_DATA base class

CORE_DATA base class


CORE_DATA is the base data class for all BMC Impact Manager data classes. Table 25
lists the slot definitions, together with an explanation for each slot.

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 25 CORE_DATA slot definitions


Slot Type Description
data_handle INTEGER data identifier for a local cell
parse = no,
read_only = yes
mc_udid STRING universal data ID
read_only = yes
mc_creation_time INTEGER creation time
parse = no,
read_only = yes,
representation = date
mc_modification_time INTEGER modification time
parse = no,
read_only -= yes,
representation = date

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:

Appendix A Event and data classes 129


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 BMC
Impact Solutions: General Administration.

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 26 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 131.
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 131 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 131 and
“BEM_MATCH_TABLE output_expressions references”
on page 131.

130 BMC Impact Solutions: 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:

Syntax Matches
'*' any string
‘<pattern>’ exact pattern
‘<pattern>*” strings with prefix pattern
‘*<pattern>’ strings with suffix pattern
‘*<pattern>*’ strings containing pattern

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.

Appendix A Event and data classes 131


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:

output_expressions=['tolowercase($1.msg)']

In the above example, the string ‘tolowercase($1.msg)’represents the following


MRL expression:

tolowercase($1)

Although a string is a simple valid expression, BAROC requires single quotation


marks around a string that contains non-alphanumeric characters, such as in
‘tolowercase($1.msg)’.

It is mandatory to put single quotation marks around strings that contains periods or
spaces. The following is a valid expression:

'quoted.string'

The following expression is not valid:

non-quoted.string

When the encoded expressions in output_expressions slot are literal and contain
non-alphanumeric characters, you must use double quotation marks. In the following
example, the first level of quotation marks delimits the string in BAROC; the second
level of quotation marks indicates the MRL expression is a literal:

output_expressions=['"quoted.string"']

For information about the find_match primitive, see page 227.

132 BMC Impact Solutions: Knowledge Base Development Reference Guide


POLICY data class

POLICY data class


The POLICY class is a subclass of the CORE_DATA base class.

Table 27 POLICY slot definitions


Slot Type Description
name STRING unique name for the policy
description STRING text description of the policy
enabled INTEGER, indicates if the policy has been enabled
default = 1
If set to 0, the policy is ignored, if the enabled slot is set to 1 the policy
impacts the processing of events.

For more information about policies, see “Event policies” on page 326.

SELECTOR data class


The SELECTOR class is a subclass of the base CORE_DATA class. Table 28 lists the slot
definitions for the SELECTOR class and provides an explanation for each slot.

Table 28 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

For more information about selectors, see “Event selectors” on page 327.

Appendix A Event and data classes 133


Cell information class

Cell information class


Each cell has a predefined MC_CELL_INFO record that is populated with general
information about the cell.

Table 29 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

Deprecated slots and their replacements


Table 30 on page 135 lists the deprecated slots for BMC Impact Manager. The
deprecated slots 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.

The values for deprecated slot values appear in the Deprecated tab for administrators
of the BMC Impact Explorer.

134 BMC Impact Solutions: Knowledge Base Development Reference Guide


Deprecated slots and their replacements

Table 30 Deprecated slots


Deprecated Slots
acl
acl_name
consumer_logical_id
cost
credibility
ext_id
generic_slot1
generic_slot2
generic_slot3
generic_slot4
mc_host
location
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 31 on page 135 lists the slots that can be substituted for a deprecated slot.

Table 31 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

Appendix A Event and data classes 135


Deprecated slots and their replacements

Table 31 Deprecated slot substitution (part 2 of 2)


Deprecated slot Slot substitution
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
sub_source 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
server_handle There are no slots that can substitute information for these
acl deprecated slots.

credibility
msg_catalog
msg_index
num_actions
mc_it_mgmt_process

136 BMC Impact Solutions: Knowledge Base Development Reference Guide


Appendix

B
Master Rule Language (MRL)
B

reference
This appendix presents the following topics:

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138


Integer data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Enumeration data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Condition operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Expression operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
MRL functions and primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Primitives and functions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Action-related primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Value type conversion primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Enumeration operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
String manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Time stamp functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
List operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Match table lookup primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Object slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Specific slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Object relation functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Operation environment inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Service model inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
License key functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Time frame operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Object creation and deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Specific rule-based functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Appendix B Master Rule Language (MRL) reference 137


Data types

Data types
Table 32 lists the types of data that can be stored by the cell.

Table 32 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 The first ordinal value that
type corresponds to the lowest
numeric value.

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 32 Permitted integer combinations in rules


pointer = pointer + integer
pointer = integer + pointer
pointer = pointer - integer
integer = pointer - pointer
pointer = max(pointer, pointer)
pointer = min(pointer, pointer)

Enumeration data
An enumeration associates constant values with names. The general format is

ENUMERATION enum_name
integer_value string_value
integer_value string_value
...
END

WARNING
Enumeration names must be unique throughout the class and the enumeration names of the
application. The name of an enumeration must not be equal to a class name.

138 BMC Impact Solutions: Knowledge Base Development Reference Guide


Operators

Operators
There 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:

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

Combination operators
Combination operators allow you to combine conditions in a logical expression. The
result is a logical value. Combination operators can be used in where clauses.

There are three logical combination operators, NOT, AND, and OR, listed in order of
evaluation:

Table 33 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.

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.

Appendix B Master Rule Language (MRL) reference 139


Condition operators

Combination operator example


( $POL.active_timeframes == [] OR tf_active($POL.active_timeframes) )
AND NOT tf_active($POL.except_timeframes)

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.

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.

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.

Condition operator example 1

when $E.status != OPEN

Condition operator example 2

timer_info: == EventTimeout

140 BMC Impact Solutions: Knowledge Base Development Reference Guide


Condition operators to test ordering conditions

Condition operators to test ordering conditions

==/2 - equals/2 — compare two values for equality


$EXPR1 == $EXPR2
$EXPR1 equals $EXPR2

Table 34 ==/2 arguments


Argument Type Description
$EXPR1 ■ ANY expression to the left of the operator
■ LIST_OF ANY
$EXPR2 ■ ANY expression to the right of the operator
■ LIST_OF ANY

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.

==/2 - equals/2 example

$E.status == OPEN

!=/2 - not_equals/2 — compare two values for inequality


$EXPR1 != $EXPR2
$EXPR1 not_equals $EXPR2

Table 35 !=/2 arguments


Argument Type Description
$EXPR1 ■ ANY expression to the left of the operator
■ LIST_OF ANY
$EXPR2 ■ ANY expression to the right of the operator
■ LIST_OF ANY

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.

Appendix B Master Rule Language (MRL) reference 141


Condition operators to test ordering conditions

!=/2 - not_equals/2 example

$E.status != CLOSED

</2 - smaller_than/2 - less_than/2 — determine if one value


is less than another value
$EXPR1 < $EXPR2
$EXPR1 smaller_than $EXPR2
$EXPR1 less_than $EXPR2

Table 36 </2 arguments


Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 ANY expression to the right of the operator

Use </2 to determine if the value of expression $EXPR1 is less than the value of
$EXPR2.

</2 - smaller_than/2 - less_than/2 example

MINOR < $E.severity

<=/2 - smaller_or_equals/2 - less_or_equals/2 — determine


if one value is less than or equal to another value
$EXPR1 <= $EXPR2
$EXPR1 smaller_or_equals $EXPR2
$EXPR1 less_or_equals $EXPR2

Table 37 <=/2 arguments


Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 ANY expression to the right of the operator

Use <=/2 to determine if the value of expression $EXPR1 is less than or equal to the
value of $EXPR2.

<=/2 - smaller_or_equals/2 - less_or_equals/2 example

MAJOR <= $E.severity

142 BMC Impact Solutions: Knowledge Base Development Reference Guide


Condition operators to test ordering conditions

>/2 - greater_than/2 — determine if one value is greater


than another value
$EXPR1 > $EXPR2
$EXPR1 greater_than $EXPR2

Table 38 >/2 arguments


Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 ANY expression to the right of the operator

Use >/2 to determine if the value of expression $EXPR1 is greater than the value of
$EXPR2.

>/2 - greater_than/2 example

$E.severity > MINOR

>=/2 - greater_or_equals/2 — determine if one value is


greater than or equal to another value
$EXPR1 >= $EXPR2
$EXPR1 greater_or_equals $EXPR2

Table 39 >=/2 arguments


Argument Type Description
$EXPR1 ANY expression to the left of the operator
$EXPR2 ANY expression to the right of the operator

Use >=/2 to determine if the value of expression $EXPR1 is greater than or equal to the
value of $EXPR2.

>=/2 - greater_or_equals/2 example

$E.severity >= MAJOR

Appendix B Master Rule Language (MRL) reference 143


Condition operators to test range conditions

Condition operators to test range conditions

between/2 — determine if one value is between two other


values
$EXPR1 between $EXPR2

Table 40 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

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.

If $EXPR2 evaluates to [$VAL1,$VAL2], then the condition $EXPR1 between $EXPR2


is equivalent to: $VAL1 <= $EXPR1 AND $EXPR1 <= $VAL2.

between/2 example

$E.duration between [100,199]

within/2 — determine if one value is present within a set of


values
$EXPR1 within $EXPR2

Table 41 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

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.

144 BMC Impact Solutions: Knowledge Base Development Reference Guide


Condition operators to test match conditions

within/2 example

$E.mc_host within [host1,host2,host3]

outside/2 — determine if one value is not included in a set


of values
$EXPR1 outside $EXPR2

Table 42 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

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.

outside/2 example

$E.mc_host outside [host1,host2,host3]

Condition operators to test match conditions

contains/2 — determine if one value contains another


value
$EXPR1 contains $EXPR2

Table 43 contains/2 arguments


Argument Type Description
$EXPR1 ■ STRING expression to the left of the operator
■ LIST_OF ANY
$EXPR2 ■ STRING expression to the right of the operator
■ LIST_OF STRING
■ ANY

Appendix B Master Rule Language (MRL) reference 145


Condition operators to test match conditions

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.

contains/2 example

$E.msg contains ’Disk full’


$E.msg contains [’Not enough’,’disk’,’space’]
$E.mc_bad_slotnames contains myslot

contained_in/2 — determine if one value is contained in


another value
$EXPR1 contained_in $EXPR2

Table 44 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

Use contained_in/2 to determine if the value of expression $EXPR1 is a substring of the


value of $EXPR2.

contained_in/2 example

’Disk full’ contained_in $E.msg

146 BMC Impact Solutions: Knowledge Base Development Reference Guide


Condition operators to test match conditions

contains_one_of/2 — determine if one value contains one


of a set of values
$EXPR1 contains_one_of $EXPR2

Table 45 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

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.

contains_one_of/2 example

$E.msg contains_one_of [’Disk’,’CPU’,’Memory’]

has_prefix/2 — determine if one string has another string


as prefix
$EXPR1 has_prefix $EXPR2

Table 46 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

Use has_prefix/2 to determine if the value of expression $EXPR1 has the value of
$EXPR2 as a prefix.

has_prefix/2 example

$E.mc_host has_prefix ’svc_’

Appendix B Master Rule Language (MRL) reference 147


Condition operators to test match conditions

has_suffix/2 — determine if one string has another string


as suffix
$EXPR1 has_suffix $EXPR2

Table 47 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

Use has_suffix/2 to determine if the value of expression $EXPR1 has the value of
$EXPR2 as a suffix.

has_suffix/2 example

$E.mc_host has_suffix ’_clt’

matches/2 — to determine if the pattern of one string


matches the pattern of another string
$EXPR1 matches $EXPR2

Table 48 matches/2 arguments


Argument Type Description
$EXPR1 ■ STRING expression to the left of the operator
■ LIST_OF_STRING
$EXPR2 ■ STRING expression to the right of the operator

Use matches/2 to determine if the value of expression $EXPR1 matches the pattern
$EXPR2.

There are two possible uses of this operator:

■ $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.

148 BMC Impact Solutions: Knowledge Base Development Reference Guide


Condition operators to test match conditions

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:

\\ backslash
\s space (single space)
\n new line
\r carriage return
\t tab
\0ddd character code in octal

A substitute is preceded by a % sign, followed by a type indicator. Between the % and


the type indicator, an optional * suppression modifier can be added.

Possible substitutes are:

%% literal match of %
%d decimal integer number
%f floating point real number
%c single character
%s string value

Two substitutes cannot occur without literal text in between them. The portion of the
input that matches the substitute of %s depends on the pattern following the
substitute:

■ a literal: input up to the first literal


■ a space and a literal: input up to the space followed by the literal
■ a space and a substitute: input up to the first space

matches/2 example

$E.msg matches ’%s failure’

Appendix B Master Rule Language (MRL) reference 149


Condition operators to test conditions on IP addresses

Condition operators to test conditions on IP addresses


NOTE
IP addresses are stored as strings in dotted decimal notation.

ip_smaller_or_equals/2 — determine if one IP address is


less than or equal to another one

$EXPR1 ip_smaller_or_equals $EXPR2

Table 49 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

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.

If either of the expressions do not evaluate to an IP address in dotted decimal


notation, the operator condition fails.

The IP addresses are compared as numbers.

ip_smaller_or_equals/2 example

$E.mc_host_address ip_smaller_or_equals ’10.1.1.100’

Any IP address in the range 0.0.0.0 to 10.1.1.100 for mc_host_address will satisfy this
condition. An address such as 10.1.2.1 will not satisfy the condition.

150 BMC Impact Solutions: Knowledge Base Development Reference Guide


Condition operators to test conditions on IP addresses

ip_greater_or_equals/2 — determine if one IP address is


greater than or equal to another one
$EXPR1 ip_greater_or_equals $EXPR2

Table 50 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

Use ip_greater_or_equals/2 to determine if the value of expression $EXPR1 is an IP


address that is greater than or equal to the IP address value of $EXPR2.

If either of the expressions do not evaluate to an IP address in dotted decimal


notation, the operator condition fails.

The IP addresses are compared as numbers.

ip_greater_or_equals/2 example

$E.mc_host_address ip_greater_or_equals ’10.1.1.100’

Any IP address within the range 10.1.1.100 to 255.255.255.255 for mc_host_address will
satisfy this condition. An address like 9.1.1.101 will not satisfy this condition.

ip_matches/2 — determine if an IP address matches an IP


address pattern
$EXPR1 ip_matches $EXPR2

Table 51 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

Use ip_matches/2 to determine if the value of expression $EXPR1 is an IP address that


matches the IP address pattern of $EXPR2.

Appendix B Master Rule Language (MRL) reference 151


Condition operators to test conditions on IP addresses

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

$E.mc_host_address ip_matches ’10.1.1.*’

Any IP address in the range 10.1.1.0 to 10.1.1.255 for mc_host_address will satisfy this
condition.

$E.mc_host_address ip_matches ’10.>200.<100.*’

Any IP address in the ranges 10.201.0.0 to 10.201.99.255, 10.202.0.0 to 10.202.99.255 up to


10.255.0.0 to 10.255.99.255 for mc_host_address will satisfy this condition.

ip_matched_by/2 — determine if an IP address matches an


IP address pattern
$EXPR1 ip_matched_by $EXPR2

Table 52 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

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.

152 BMC Impact Solutions: Knowledge Base Development Reference Guide


Condition operators to test class hierarchy conditions

This is the reverse of ip_matches/2: the condition $EXPR1 ip_matched_by $EXPR2 is


equivalent to $EXPR2 ip_matches $EXPR1.

ip_matched_by/2 example

’10.1.1.*’ ip_matched_by $E.mc_host_address

Condition operators to test class hierarchy conditions

superclass_of/2 — determine if one class is a superclass of


another class
$EXPR1 superclass_of $EXPR2

Table 53 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

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.

superclass_of/2 example

PATROL_EV superclass_of $E.CLASS

subclass_of/2 — determine if one class is a subclass of


another class
$EXPR1 subclass_of $EXPR2

Table 54 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

Appendix B Master Rule Language (MRL) reference 153


Expression operators

Use subclass_of/2 to determine if the value of expression $EXPR1 is the name of a class
that is a subclass the class name that is the value of $EXPR2.

For this operator each class is considered to be a subclass of itself.

subclass_of/2 example

$E.CLASS subclass_of PATROL_EV

Expression operators
Expression operators are mainly arithmetic operators that take numeric values as
arguments. There is also one expression operator that takes textual arguments.
Results of expression operators are numeric or textual values. They can be reused as
arguments in an expression. Logical operators take integer arguments that are
interpreted as bit sets. The operation is performed on the bits and the result is
interpreted as an integer value.

The operators are listed in groups. All operators within the same group are evaluated
at the same time, when they appear in an expression without parentheses. Operators
from earlier groups are evaluated before operators from later groups.

Example of expression evaluation order

$E1 + $E2 * $E3

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.

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

154 BMC Impact Solutions: Knowledge Base Development Reference Guide


Expression operators

Multiplicative operators
Multiplicative operators take two numeric arguments and produce a numeric result.

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

Additive operators
Additive operators take two numeric arguments and produce a numeric result.

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

Single numeral operators


These operators take a single numeric argument and produce a numeric result.

+ e1 The value e1
- e1 The numeric negation of the value e1
\ e1 The logical or bitwise negation (complement) of the value e1

Concatenation operator
The following operator takes two string arguments and produces a string result.

e1 || e2 Concatenation of string e1 with string e2

Appendix B Master Rule Language (MRL) reference 155


MRL functions and primitives

Expression operator example


$E.msg = ’Host ’ || $E.mc_host || ’ went down’;

MRL functions and primitives


The primitives and functions in this section are grouped by usage. Table 55 allows
you to look up the location of the function and primitive descriptions alphabetically.

Table 55 Alphabetical list of primitives and functions (part 1 of 6)


Primitive/function name Description Page
abs/2 determine the absolute value of a numeric value 183
acos/2 return the arc cosine of a specified number 187
action_requestor/1 retrieve the identification of the requestor of an action 163
action_requestor/2 retrieve the user ID and password of the console user 163
triggering the action
action_requestor/3 retrieve the user ID and password of the console user, as 164
well as the type of rule triggering the action
action_return/2 terminate an internal action and return a value 165
add_to_list/2 add an element at the beginning of a list slot 226
apply_match_entry/4 obtain output values from a match table entry 230
admin_execute/5 perform an action through remote execution on IAS 166
admin_execute/7 perform an action through remote execution on IAS, 167
providing IAS credentials
asin/2 return the arc sine of a specified number 187
atan/2 return the arc tangent of a specified number 188
atan2/3 return the arc tangent of the ratio of two numbers 188
cellcontrol/1 perform a cell control command 246
cellinfo/2 retrieve cell-specific information 245
char/2 produce a string containing a single character with a 180
specified numeric internal representation
class_path/2 obtain the class hierarchy of a class 233
code/2 retrieve the internal numeric representation of a character 180
concat/2 concatenate a list of strings 197
confirm_external/2 run an external program and wait for its termination to 171
continue to process the current event
cos/2 return the cosine of an angle 186
decr/1 decrement an integer or enumeration slot by 1 194

156 BMC Impact Solutions: Knowledge Base Development Reference Guide


MRL functions and primitives

Table 55 Alphabetical list of primitives and functions (part 2 of 6)


Primitive/function name Description Page
decr/2 decrement an integer or enumeration slot by a specified 195
value
decr/2 and prev/2 return an integer or enumeration slot value decremented by 194
1
decr/3 retrieve the value of an integer or enumeration slot 195
decremented by a specified value
decr/3 decrement an integer or enumeration slot by a specified 196
value within a given limit
decr/4 return an integer or enumeration slot value decremented by 196
a specified value within a given limit
drop_new/0 drop a new event object 270
execute/4 run a program as an external process 170
exp/2 raise e (2.718281828...) to a specified power 184
find_match/5 find an entry in a match table and retrieve calculated values 227
from it
find_match_entry/4 find an entry in a match table 229
gcd/3 return the greatest common divisor of two numbers 189
generate_event/2 generate a new event 268
get_env/2 retrieve the value of an environment variable 248
get_external/4 run an external program and wait for its termination to 172
continue to process the current event, using data retrieved
through an interface object
get_list_slotvalues/3 retrieve a list of slots from one or more objects 231
incr/1 increment an integer or enumeration slot by 1 190
incr/2 increment an integer or enumeration slot by a specified 191
value
incr/2 and next/2 return an integer or enumeration slot value incremented by 1 191
incr/3 return an integer or enumeration slot value incremented by a 192
specified value
incr/3 increment an integer or enumeration slot by a specified 192
value within a specified limit
incr/4 retrieve the value of an integer or enumeration slot 193
incremented by a given value within a specified limit
int/2 truncate a numeric value to an integer value 178
int_to_hex/2 convert an integer value to a string containing its 174
hexadecimal notation
int_to_hex/3 convert an integer value to a string containing its 174
hexadecimal notation in a specified field width
inttostring/2 convert an integer value to a string value 173
kbversion/1 retrieve global Knowledge Base module version information 248
kbversion/2 retrieve Knowledge Base module version information 247

Appendix B Master Rule Language (MRL) reference 157


MRL functions and primitives

Table 55 Alphabetical list of primitives and functions (part 3 of 6)


Primitive/function name Description Page
key_verify/2 validate and retrieve fields from a license key 254
key_verify/3 validate and retrieve fields from a license key 254
key_version/2 retrieve the version from a license key 253
listappend/3 concatenate two lists 222
listdelete/3 remove all occurrences of an element from a list 221
listdisjoint/2 verify that two lists do not have any common elements 222
listgetelt/3 retrieve a list element located at a specified position within a 220
list
listintersect/3 determine the common elements of two lists 223
listlen/2 determine the length of a list 220
listmember/2 verify that an element is included in a list 221
listremdup/2 remove duplicate elements from a list 225
listsubtract/3 remove the elements that occur in one list from another list 224
listunion/3 determine the union of two lists 223
listwalk/2 execute instructions against each element in a list 225
log/2 return the natural logarithm of a specified number 185
log10/2 return the decimal logarithm of a specified number 185
mapslots/3 format a series of expressions that refer to objects into a 214
string
mapslots/4 format a series of expressions that refer to event and data 213
objects into a string
match_regex/3 match a string with a regular expression 209
match_regex/4 match a string with a regular expression and retrieve all 210
fields from it
match_regex/5 match a string with a regular expression and retrieve a given 211
number of fields from it
max/3 determine the maximum of two values 181
min/3 determine the minimum of two values 182
new_data/3 create a new data object 269
ntadd/2 add a note to an event 234
ntcnt/2 count the notes attached to an event 235
ntget/5 return the time stamp, author, and text of a note attached to 235
an event
ntset/3 modify the text of a note attached to an event 236
opadd/3 add an operation to an event 237
opadd/4 add a policy operation to an event 236
opcnt/2 count the operations of an event 237
opget/6 retrieve an operation of an event 239
opget/7 retrieve a policy operation of an event 238

158 BMC Impact Solutions: Knowledge Base Development Reference Guide


MRL functions and primitives

Table 55 Alphabetical list of primitives and functions (part 4 of 6)


Primitive/function name Description Page
opget_action/3 retrieve the action name of an operation of an event 240
opget_args/3 retrieve the argument list of an operation of an event 241
opget_author/3 retrieve the author of an operation of an event 240
opget_time/3 retrieve the time stamp of an operation of an event 239
opset/4 modify the action and arguments of an operation of an event 242
opset/5 modify the policy name, action, and arguments of an 241
operation of an event
perform/3 perform a specified action 169
perform/5 perform a specified action and return a value 169
pointertostring/2 convert a pointer value to a string value 176
pow/3 raise a number to a specified power 184
random/3 return a random integer that falls between two specified 190
numbers
real/2 and float/2 convert a numeric value to a real value 179
realtostring/2 convert a real value to a string value 175
relate/1 establish the relation of an event to a source event 243
rem_from_list/2 remove the first occurrence of an element from a list slot 226
remove_data/1 delete a data object 270
reset_default/1 reset a slot to its default value 234
round/2 convert a numeric value to an integer value by rounding the 179
number
send_to/2 send an event to another cell or gateway 249
send_to/3 send an event modification to another cell or gateway 249
send_to_ext/4 send an extended event to another cell or gateway 250
set_list_slotvalues/3 assign values to a list of slots for one or more objects 232
set_timer/3 set a timer on an event object that will expire after a specified 271
delay
set_timer_at/3 set a timer on an event object that will expire at a specified 272
time
set_timer_at/4 set a timer on an event object that will expire at a specified 273
time represented by a text string
sign/2 determine whether a numeric value is positive, negative, or 182
zero
sin/2 return the sine of an angle 186
smcomps/5 search for certain Service Model components 251
sprintf/3 format a series of values into a string 212
sqrt/2 determine the square root of a numeric value 183
str_to_time_stamp/3 convert a string to a time stamp 218
strextract/4 retrieve a string of a specified length that begins at a 201
specified position within a larger string

Appendix B Master Rule Language (MRL) reference 159


MRL functions and primitives

Table 55 Alphabetical list of primitives and functions (part 5 of 6)


Primitive/function name Description Page
string/2 convert any non-list value to a string value 176
stringtoint/2 convert a string value to an integer value 176
stringtopointer/2 convert a string value to a pointer value 177
stringtoreal/2 convert a string value to a real value 177
strip/2 strip leading and trailing blank spaces from a string 203
strip/3 remove blank spaces from specified parts of a string 204
strip/4 remove specified characters from specified parts of a string 205
strlen/2 and len/2 determine the length of a string 198
strmatch/3 match a string with a simple pattern and retrieve fields from 207
it
strnpart/4 determine the start position of a specified occurrence of a part 207
of a string
strpart/3 determine the starting position of a partial string within a 200
larger string
strtolist/3 divide a string into parts at specified separators 206
substring/3 retrieve a string that begins at a specified position within a 202
larger string and continues through the end of the larger
string
substring/4 retrieve a substring of a specified length beginning at a 203
specified offset
tan/2 return the tangent of an angle 186
tf_active/1 verify if one or more time frames are active 255
tf_active/2 verify if one or more time frames are active at a given time 256
tf_current_end/2 obtain the end time of the current active interval of a time 259
frame
tf_current_end/3 obtain the end time of the active interval of a time frame at a 259
specified time
tf_current_interval/2 obtain the start and end time of the current active interval of 260
a time frame
tf_current_interval/3 obtain the start and end time of the active interval of a time 260
frame at a given time
tf_current_start/2 obtain the start time of the current active interval of a time 258
frame
tf_current_start/3 obtain the start time of the active interval of a time frame at a 258
specified time
tf_duration/3 calculate the duration of all active intervals of a time frame 267
from a specified start time to the current time
tf_duration/4 calculate the duration of all active intervals of a time frame 268
during a specified time period
tf_next_end/2 obtain the end time of the next active interval of a time frame 265
tf_next_end/3 obtain the end time of the next active interval of a time frame 265
at a specified time

160 BMC Impact Solutions: Knowledge Base Development Reference Guide


MRL functions and primitives

Table 55 Alphabetical list of primitives and functions (part 6 of 6)


Primitive/function name Description Page
tf_next_interval/2 obtain the start and end time of the next active interval of a 266
time frame
tf_next_interval/3 obtain the start and end time of the next active interval of a 267
time frame at a specified time
tf_next_start/2 obtain the start time of the next active interval of a time 264
frame
tf_next_start/3 obtain the start time of the next active interval of a time 264
frame at a given time
tf_prev_end/2 obtain the end time of the previous active interval of a time 262
frame
tf_prev_end/3 obtain the end time of the previous active interval of a time 262
frame at a given time
tf_prev_interval/2 obtain the start and end time of the previous active interval 263
of a time frame
tf_prev_interval/3 obtain the start and end time of the previous active interval 263
of a time frame at a specified time
tf_prev_start/2 obtain the start time of the previous active interval of a time 261
frame
tf_prev_start/3 obtain the start time of the previous active interval of a time 261
frame at a given time
tf_udid_active/1 verify if one or more time frames specified by mc_udid are 256
active at the current time
tf_udid_active/2 verify if one or more time frames specified by mc_udid are 257
active at a specified time
time_extract/3 retrieve fields from a time stamp 217
time_stamp/1 retrieve the current time 215
time_stamp_to_cim/2 convert a time stamp to CIM (Common Information Model) 215
format
time_stamp_to_str/2 convert a time stamp to the default DateFormat format 217
time_stamp_to_str/3 convert a time stamp to a specified format 216
tolowercase/2 and convert a string to all lowercase characters 198
lower/2
touppercase/2 and convert a string to all uppercase characters 199
upper/2
trunc/2 truncate a real number to an integer (symmetric around 0) 178
unrelate/1 remove a relation of a related event to a source event 244
unset_cause/0 break the cause-to-effect relationship from a correlate rule 271

Appendix B Master Rule Language (MRL) reference 161


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:

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

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).

162 BMC Impact Solutions: Knowledge Base Development Reference Guide


Action-related primitives

Action-related primitives

action_requestor/1 — retrieve the identification of the


requestor of an action

action_requestor($REQUESTOR)
$REQUESTOR=action_requestor()

Table 56 action_requestor/1 syntax argument


Argument Mode Type Description
$REQUESTOR output STRING the user or rule that requested the 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

action AssignTo [Name:STRING($USER)] : EVENT($E)


{
action_requestor($REQUESTOR);
$E.administrator = $REQUESTOR;
$E.mc_owner = $USER;
}
END

In this example, the action AssignTo assigns a selected event to a named owner.

The name of the owner is provided by the console user in the Name field of a dialog
box, as specified in the action definition argument list.

When the action is triggered, it retrieves the identification of the requestor and
returns it in the $REQUESTOR variable. This value will be the ID of the console user
and is assigned to the administrator slot of the event.

The provided owner name is assigned to the mc_owner slot of the event.

action_requestor/2 — retrieve the user ID and password of


the console user triggering the action

action_requestor($USER,$PASSWD)

Appendix B Master Rule Language (MRL) reference 163


Action-related primitives

Table 57 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

Use action_requestor/2 to retrieve the identification of the requestor of the action, as


well as that user's password. The identification is returned in $USER and the
password in $PASSWD. A password value will only be returned if the requestor of the
action is a console user. For an action requested by a rule, the password is an empty
string.

action_requestor/2 example

action UserGetMetrics : EVENT($E)


{
action_requestor($USER,$PASSWD);
admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES);
}
END

In this example, the action is designed to be used from a console. When the console
user triggers the action, the action code first retrieves the user's identification in the
$USER variable and the user's password in the $PASSWD variable.

This information is passed on to the Administration server named ias1 to request a


remote execution of the remote Administration server task GetMetrics on the
selected event.

No specific arguments are required for this remote task, so the second to last
argument of admin_execute is an empty list ([]). The YES value for the last
argument indicates that an MC_CELL_ACTION_RESULT event must be generated for
this remote action.

action_requestor/3 — retrieve the user ID, password of the


console user and rule type that is triggering the action

action_requestor($USER,$PASSWD,$RULETYPE)

Table 58 action_requestor/3 syntax arguments (part 1 of 2)


Argument Mode Type Description
$USER output STRING the requestor of the action

164 BMC Impact Solutions: Knowledge Base Development Reference Guide


Action-related primitives

Table 58 action_requestor/3 syntax arguments (part 2 of 2)


Argument Mode Type Description
$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.

Use action_requestor/3 to retrieve the identification of the requestor of the action, that
user's password, and the type of rule performing the action. The identification is
returned in $USER and the password in $PASSWD. A password value will only be
returned if the requestor of the action is a console user. For an action requested by a
rule, the password is an empty string. If the action is performed from a rule, the type
of the rule is returned in $RULETYPE. When the action is performed by a user from a
console, $RULETYPE returns an empty string.

action_requestor/3 example

action UserGetMetrics : EVENT($E)


{
action_requestor($USER,$PASSWD,$RULETYPE);
if ( $RULETYPE == '' ) then
{
admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES);
}
else
{
admin_execute(ias1,$E,GetMetrics,[],YES);
}
}
END

In this example, the action can be used from a console, as well as from a rule. If used
from a console (represented by the then branch of the example), the credentials of the
console user are passed to admin_execute/7.

If the action is used from a rule (represented by the else branch of the example), no
credentials are passed to admin_execute/5. In this case, it is assumed that the
credentials are provided as part of the Administration server specification in the cell
directory (mcell.dir).

action_return/2 — terminate an internal action and return


a value

action_return($CODE,$TEXT)

Appendix B Master Rule Language (MRL) reference 165


Action-related primitives

Table 59 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

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 169.

action_return/2 example

action AssignTo [Name:STRING($USER)] : EVENT($E)


{
action_requestor($REQUESTOR);
$E.administrator = $REQUESTOR;
$E.mc_owner = $USER;
action_return(0,’Ownership taken’)
}
END

admin_execute/5 — perform an action through remote


execution on IAS

admin_execute($NAME,$OBJECT,$ACTION,$ARGS,$ACTEVENT)

Table 60 admin_execute/5 syntax arguments (part 1 of 2)


Argument Mode Type Description
$NAME input STRING specifies the name of the Impact Administration
Server
$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

166 BMC Impact Solutions: Knowledge Base Development Reference Guide


Action-related primitives

Table 60 admin_execute/5 syntax arguments (part 2 of 2)


Argument Mode Type Description
$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

Use admin_execute/5 to perform an action on Impact Administration Server (IAS)


using remote execution. The IAS 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, using the credentials that are provided in the
DIRECTORY.

admin_execute/5 example

action UserGetMetrics : EVENT($E)


{
admin_execute(ias1,$E,GetMetrics,[],YES);
}
END

In this example, the UserGetMetrics action retrieves metrics for an event from an
Administration server.

The action performs the GetMetrics remote task on the ias1 Administration server.
Credentials are assumed to be provided in mcell.dir for this server.

admin_execute/7 — perform an action through remote


execution on IAS, providing IAS credentials

admin_execute($NAME,$USER,$PASSWD,$OBJECT,$ACTION,$ARGS,$ACTEVENT)

Table 61 admin_execute/5 syntax arguments (part 1 of 2)


Argument Mode Type Description
$NAME input STRING specifies the name of the Impact Administration
Server (IAS)
$USER input STRING specifies the user name of the IAS account
$PASSWD input STRING specifies the password of the IAS account

Appendix B Master Rule Language (MRL) reference 167


Action-related primitives

Table 61 admin_execute/5 syntax arguments (part 2 of 2)


Argument Mode Type Description
$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

Use admin_execute/7 to perform an action on Impact Administration Server (IAS)


using remote execution, specifying the IAS account user name and password.

An action is executed through IAS named NAME. The USER and PASSWD credentials are
used to log in to IAS.

If ACTEVENT=YES an MC_CELL_ACTION_RESULT event is generated for the action.


When the action is terminated, its output is stored in the action result event.

admin_execute/7 example

action UserGetMetrics : EVENT($E)


{
action_requestor($USER,$PASSWD);
admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES);
}
END

In this example, the action is designed to be used from a console. When the console
user triggers the action, the action code first retrieves the user's identification in the
$USER variable and the user's password in the $PASSWD variable.

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.

168 BMC Impact Solutions: Knowledge Base Development Reference Guide


Action-related primitives

perform/3 — perform a specified action

perform($OBJECT,$ACTION,$ARGS)

Table 62 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.

Use perform/3 to perform the action defined with name specified by the $ACTION
argument on the event or data with the object handle specified in the $OBJECT
argument. Required arguments for the action must be provided in the $ARGS list. The
success of the perform/3 call depends on whether the action succeeds or fails.

perform/3 example

perform($E,AssignTo,[Operator1]);

perform/5 — perform a specified action and return a value

perform($OBJECT,$ACTION,$ARGS,$RETCODE,$RETTEXT)

Table 63 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
$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

Appendix B Master Rule Language (MRL) reference 169


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 165.

perform/5 example

perform($E,AssignTo,[Operator1],$RETCODE,$RETTEXT);

execute/4 — run a program as an external process

execute($EVENT,$PROG,$ARGS,$ACTEVT)

Table 64 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
$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.

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 “Location
of remote actions and executables” on page 107). 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 “Action execution variables” on page 114).

170 BMC Impact Solutions: Knowledge Base Development Reference Guide


Action-related primitives

If the $ACTEVT argument is specified as YES, an MC_CELL_ACTION_RESULT event


will be created. Upon termination of the program, the MC_CELL_ACTION_RESULT
event will be updated with the result.

execute/4 example

execute($E,mc_modslot,[msg,’Hello’],NO);

confirm_external/2 — run an external program and wait


for its termination to continue to process the current event
NOTE
The confirm_external/2 primitive can only be used in a refine rule.

confirm_external($PROG,$ARGS)

Table 65 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.

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 “Location of remote actions and executables” on
page 107).

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 “Action execution variables” on page 114).

confirm_external/2 example

confirm_external(mc_ping,[]);

Appendix B Master Rule Language (MRL) reference 171


Action-related primitives

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.

get_external/4 — run an external program and wait for its


termination to continue to process the current event, using
data retrieved through an interface object
NOTE
The get_external/4 primitive can only be used in a refine rule.

get_external($PROG,$ARGS,$INTF,$ANS)

Table 66 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

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
“Location of remote actions and executables” on page 107). 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.

172 BMC Impact Solutions: Knowledge Base Development Reference Guide


Value type conversion primitives

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 “Action execution variables” on page 114).

get_external/4 example

In this example, the Knowledge Base contains the following class definition:

MC_INTERFACE: DOOR_INFO DEFINES {


door_id: STRING;
door_location: STRING;
door_status: STRING;
}; END

An application could receive events that report incidents on doors. Such events
would have mc_object_class set to DOOR. The following refine rule retrieves
additional information:

refine get_door_info: EVENT($E) where [$E.mc_object_class==DOOR]


{
get_external(get_door_info,[$E.mc_object],DOOR_INFO,$DI);
$E.msg = concat([’Door ’,$DI.door_id,’ at ’,$DI.door_location,
’ changed status to ’,$DI.door_status]);
}
END

The external program get_door_info is assumed to return the door information for
the door that is indicated in the mc_object slot, as an instance of DOOR_INFO. If the
door specified in mc_object is not recognized by the program, the program may fail
and return a non-zero exit code. In that case, the event on which the program was
triggered will be dropped.

Value type conversion primitives

inttostring/2 — convert an integer value to a string value

inttostring($INTVAL,$STRVAL)
$STRVAL=inttostring($INTVAL)

Appendix B Master Rule Language (MRL) reference 173


Value type conversion primitives

Table 67 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

Use inttostring/2 to convert the integer value specified in the $INTVAL argument to a
string value returned in $STRVAL.

inttostring/2 example

$E.msg = concat([’Event #’,inttostring($E.event_handle)]);

int_to_hex/2 — convert an integer value to a string


containing its hexadecimal notation

$STRVAL=int_to_hex($INTVAL)

Table 68 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

Use int_to_hex/2 to convert the integer value specified in the $INTVAL argument to a
string containing its hexadecimal notation, returned in $STRVAL.

int_to_hex/2 example

$E.msg = concat([’Event # 0x’,int_to_hex($E.event_handle)]);

int_to_hex/3 — convert an integer value to a string


containing its hexadecimal notation in a specified field
width

$STRVAL=int_to_hex($INTVAL,$FLDLEN)

174 BMC Impact Solutions: Knowledge Base Development Reference Guide


Value type conversion primitives

Table 69 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

Use int_to_hex/3 to convert the integer value specified in the $INTVAL argument to a
string containing its hexadecimal notation that is the same width as the field width
specified by the $FLDLEN argument. The resulting hexadecimal notation string is
returned in the $STRVAL argument. If the resulting notation is smaller than the
specified field width, the notation is padded with 0s to the left of the notation until it
is the specified width of the field.

int_to_hex/3 example

$E.msg = concat([’Event # 0x’,int_to_hex($E.event_handle,10)]);

realtostring/2 — convert a real value to a string value

realtostring($REALVAL,$STRVAL)
$STRVAL=realtostring($REALVAL)

Table 70 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

Use realtostring/2 to convert the real value specified in the $REALVAL argument to a
string value returned in $STRVAL.

realtostring/2 example

$DEV = ( $AVERAGE_DURATION - real($E.duration) ) ^ 2;


$E.msg = concat([’Duration deviation=’,realtostring($DEV)]);

Appendix B Master Rule Language (MRL) reference 175


Value type conversion primitives

pointertostring/2 — convert a pointer value to a string


value

pointertostring($PTRVAL,$STRVAL)
$STRVAL=pointertostring($PTRVAL)

Table 71 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

Use pointertostring/2 to convert the pointer value specified in the $PTRVAL argument
to a string value returned in $STRVAL.

pointertostring/2 example

$E.msg = concat([’Address=’,pointertostring($ADDR)]);

string/2 — convert any non-list value to a string value

$STRVAL=string($ANYVAL)

Table 72 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

Use string/2 to convert the non-list value specified by $ANYVAL to a string value
returned in $STRVAL.

string/2 example

$E.msg = concat([’Value=’,string($ANYVAL)]);

stringtoint/2 — convert a string value to an integer value

stringtoint($STRVAL,$INTVAL)
$INTVAL=stringtoint($STRVAL)

176 BMC Impact Solutions: Knowledge Base Development Reference Guide


Value type conversion primitives

Table 73 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

Use stringtoint/2 to convert a string value specified in the $STRVAL argument to an


integer value returned in $INTVAL.

stringtoint/2 example

$INTVAL = stringtoint($E.msg);

stringtoreal/2 — convert a string value to a real value

stringtoreal($STRVAL,$REALVAL)
$REALVAL=stringtoreal($STRVAL)

Table 74 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

Use stringtoreal/2 to convert the string value specified in the $STRVAL argument to a
real (floating point) value returned in $REALVAL.

stringtoreal/2 example

$REALVAL = stringtoreal($E.msg);

stringtopointer/2 — convert a string value to a pointer


value

stringtopointer($STRVAL,$PTRVAL)
$PTRVAL=stringtopointer($STRVAL)

Table 75 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

Appendix B Master Rule Language (MRL) reference 177


Value type conversion primitives

Use stringtopointer/2 to convert a string value specified in the $STRVAL argument to a


pointer value returned in $PTRVAL.

stringtopointer/2 example

$PTRVAL = stringtopointer($E.msg);

int/2 — truncate a numeric value to an integer value

$INTVAL=int($NUMBER)

Table 76 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

Use int/2 to convert the numeric value specified by the $NUMBER argument to an
integer value returned in the $INTVAL argument. The conversion truncates the
$NUMBER to the largest integer value that is smaller than or equal to it.

The following statement is true for the truncation process:

∀X: X-1 < int(X) ≤ X

int/2 example

$DEV = int( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );

trunc/2 — truncate a real number to an integer (symmetric


around 0)

$INTVAL=trunc($NUMBER)

Table 77 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

178 BMC Impact Solutions: Knowledge Base Development Reference Guide


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

$DEV = trunc( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );

round/2 — convert a numeric value to an integer value by


rounding the number

$INTVAL=round($NUMBER)

Table 78 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

Use round/2 to convert a numeric value to an integer value returned in $INTVAL. The
conversion rounds the number.

round/2 example

$DEV = round( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );

real/2 and float/2 — convert a numeric value to a real value

$REALVAL=real($NUMBER)
$REALVAL=float($NUMBER)

Appendix B Master Rule Language (MRL) reference 179


Value type conversion primitives

Table 79 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

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

$DEV = ( $AVERAGE_DURATION - real($E.duration) ) ^ 2;

code/2 — retrieve the internal numeric representation of a


character

$INTVAL=code($STRVAL)

Table 80 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

Use code/2 to retrieve the internal numeric code of the character specified by the
$STRVAL argument and return it as an integer in the $INTVAL argument. The code is
implementation dependent. It currently is the Unicode code point.

Only the first character of the string is considered.

code/2 example

$CODE = code($E.msg);

char/2 — produce a string containing a single character


with a specified numeric internal representation

$STRVAL=char($INTVAL)

180 BMC Impact Solutions: Knowledge Base Development Reference Guide


Mathematical functions

Table 81 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

Use char/2 to convert the numeric internal representation specified by $INTVAL into a
string returned in $STRVAL. The code is implementation dependent. It currently is the
Unicode code point.

Not every numeric code results in a valid character.

char/2 example

$E.msg = char($E.msg);

Mathematical functions

max/3 — determine the maximum of two values

$MAXVAL=max($VAL1,$VAL2)

Table 82 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

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.

max/3 example

$MAX_DURATION = max( $PREVIOUS_DURATION , $E.duration );

Appendix B Master Rule Language (MRL) reference 181


Mathematical functions

min/3 — determine the minimum of two values

$MINVAL=min($VAL1,$VAL2)

Table 83 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

Use min/3 to determine the minimum of two values specified in the $VAL1 and $VAL2
arguments and return the result as $MINVAL. Both input values must be the same,
simple (non-list) type.

min/3 example

$MIN_DURATION = min( $PREVIOUS_DURATION , $E.duration );

sign/2 — determine whether a numeric value is positive,


negative, or zero

$SIGN=sign($NUMBER)

Table 84 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

The sign/2 function returns the sign of the numeric value specified by the $NUMBER
argument and returned as $SIGN.

NOTE
A real number that is not precisely 0 may still be displayed as 0.0 due to rounding errors or
limited precision. The sign of such a real number will not be 0.

182 BMC Impact Solutions: Knowledge Base Development Reference Guide


Mathematical functions

sign/2 example

$SIGN = sign( $AVERAGE_DURATION - real($E.duration) );

abs/2 — determine the absolute value of a numeric value

$ABSVAL=abs($NUMBER)

Table 85 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

The abs/2 function returns the absolute value of the numeric value specified in the
$NUMBER argument as $ABSVAL.

abs/2 example

$ABS = abs( $AVERAGE_DURATION - real($E.duration) );

sqrt/2 — determine the square root of a numeric value

$RESULT=sqrt($NUMBER)

Table 86 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

The sqrt/2 function returns the square root value of the numeric value specified by the
$NUMBER argument as $RESULT.

sqrt/2 example

$SQRT = sqrt( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );

Appendix B Master Rule Language (MRL) reference 183


Mathematical functions

exp/2 — raise e (2.718281828...) to a specified power

$RESULT=exp($NUMBER)

Table 87 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

The exp/2 function returns the number e (2.718281828...) raised to the power specified
by the $NUMBER argument as $RESULT.

exp/2 example

$EXP = exp( $E.duration );

pow/3 — raise a number to a specified power

$RESULT=pow($NUMBER,$POWER)

Table 88 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

The pow/3 function raises the number specified in the $NUMBER argument to the
power specified in the $POWER argument and returns the result in $RESULT.

NOTE
The exponentiation operator ^ can only be used with integer powers. For non-integer powers,
pow/3 must be used.

pow/3 example

$POW = pow( $VAL , 3.14 );

184 BMC Impact Solutions: Knowledge Base Development Reference Guide


Mathematical functions

log/2 — return the natural logarithm of a specified number

$RESULT=log($NUMBER)

Table 89 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

The log/2 function calculates the natural logarithm (base e or 2.718281828...) of the
number specified in the $NUMBER argument and returns the result in the $RESULT
argument.

log/2 example

$LOG = log( $VAL );

log10/2 — return the decimal logarithm of a specified


number

$RESULT=log10($NUMBER)

Table 90 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

The log10/2 function returns the decimal logarithm (base 10) of the number specified
by the $NUMBER argument in the $RESULTargument.

log10/2 example

$LOG = log10( $VAL );

Appendix B Master Rule Language (MRL) reference 185


Mathematical functions

sin/2 — return the sine of an angle

$RESULT=sin($NUMBER)

Table 91 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

The sin/2 function returns the sine of the angle specified in the $NUMBER argument in
the $RESULT argument.

sin/2 example

$SIN = sin( $ANGLE );

cos/2 — return the cosine of an angle

$RESULT=cos($NUMBER)

Table 92 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

The cos/2 function returns the cosine of the angle specified in the $NUMBER argument
in the $RESULT argument.

cos/2 example

$COS = cos( $ANGLE );

tan/2 — return the tangent of an angle

$RESULT=tan($NUMBER)

186 BMC Impact Solutions: Knowledge Base Development Reference Guide


Mathematical functions

Table 93 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

The tan/2 function returns the tangent of the angle specified in the $NUMBER argument
in the $RESULT argument.

tan/2 example

$TAN = tan( $ANGLE );

asin/2 — return the arc sine of a specified number

$RESULT=asin($NUMBER)

Table 94 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)

The asin/2 function returns the arc sine of the number specified in the $NUMBER
argument in the $RESULT argument.

asin/2 example

$ANGLE = asin( $VAL );

acos/2 — return the arc cosine of a specified number

$RESULT=acos($NUMBER)

Appendix B Master Rule Language (MRL) reference 187


Mathematical functions

Table 95 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)

The acos/2 function returns the arc cosine of the number specified in the $NUMBER
argument in the $RESULT argument.

acos/2 example

$ANGLE = acos( $VAL );

atan/2 — return the arc tangent of a specified number

$RESULT=atan($NUMBER)

Table 96 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)

The atan/2 function returns the arc tangent of the number specified in the $NUMBER
argument in the $RESULT argument.

atan/2 example

$ANGLE = atan( $VAL );

atan2/3 — return the arc tangent of the ratio of two


numbers

$RESULT=atan2($NUMBER1,$NUMBER2)

188 BMC Impact Solutions: Knowledge Base Development Reference Guide


Mathematical functions

Table 97 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)

The atan2/3 function returns the arc tangent of the ratio of $NUMBER1 and $NUMBER2 in
the $RESULT argument.

atan2/3 example

$RIGHTANGLE = atan2( 1 , 0 );

gcd/3 — return the greatest common divisor of two


numbers

$RESULT=gcd($NUMBER1,$NUMBER2)

Table 98 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

The gcd/3 function returns the greatest common divisor of $NUMBER1 and $NUMBER2 in
$RESULT.

gcd/3 example

$GCD = gcd( $NUM1 , $NUM2 );

Appendix B Master Rule Language (MRL) reference 189


Enumeration operations

random/3 — return a random integer that falls between


two specified numbers

$RESULT=random($NUMBER1,$NUMBER2)

Table 99 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

The random/3 function returns a random integer number between the integer
specified by the $NUMBER1 argument and the integer specified by the $NUMBER2
argument in $RESULT.

random/3 example

$RAND = random( $NUM1 , $NUM2 );

Enumeration operations

incr/1 — increment an integer or enumeration slot by 1

incr($SLOT)

Table 100 incr/1 arguments


Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot to be incremented

Use incr/1 to increment the slot referenced in $SLOT by 1. For an enumeration, the slot
is set to the next higher value. If there is no higher value, the slot value is not
modified.

incr/1 example

incr( $E.mc_priority );

190 BMC Impact Solutions: Knowledge Base Development Reference Guide


Enumeration operations

incr/2 and next/2 — return an integer or enumeration slot


value incremented by 1
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 101 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

Use incr/2 to return the value of the slot referenced in $SLOT incremented by 1 in the
$VAL argument. For an enumeration, the value of the slot is returned as the next
higher value. If there is no higher value, the value of the slot that is returned in $VAL
is not modified.

The referenced slot itself is not modified.

incr/2 example

$NEWPRIO = incr( $E.mc_priority );

incr/2 — increment an integer or enumeration slot by a


specified value

incr($SLOT,$INCR)

Table 102 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

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.

Appendix B Master Rule Language (MRL) reference 191


Enumeration operations

incr/2 example

incr( $E.mc_priority , 2 );

incr/3 — return an integer or enumeration slot value


incremented by a specified value

$VAL=incr($SLOT,$INCR)

Table 103 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

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.

incr/3 example

$NEWPRIO = incr( $E.mc_priority , 2 );

incr/3 — increment an integer or enumeration slot by a


specified value within a specified limit

incr($SLOT,$INCR,$LIMIT)

Table 104 incr/3 arguments (part 1 of 2)


Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot to be
incremented

192 BMC Impact Solutions: Knowledge Base Development Reference Guide


Enumeration operations

Table 104 incr/3 arguments (part 2 of 2)


Argument Mode Type Description
$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

Use incr/3 to increment the slot referenced in $SLOT by $INCR, limited to the value
$LIMIT. For an enumeration, the slot value is incremented by $INCR higher values,
limited to $LIMIT.

incr/3 example

incr( $E.mc_priority , 2 , PRIORITY_2 );

incr/4 — retrieve the value of an integer or enumeration


slot incremented by a given value within a specified limit

$VAL=incr($SLOT,$INCR,$LIMIT)

Table 105 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
$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

Use incr/4 to retrieve the value of the slot referenced in $SLOT incremented by $INCR,
limited to the value $LIMIT in $VAL. For an enumeration, the slot value returned is
incremented by $INCR higher values, limited to $LIMIT.

The referenced slot itself is not modified.

incr/4 example

$NEWPRIO = incr( $E.mc_priority , 2 , PRIORITY_2 );

Appendix B Master Rule Language (MRL) reference 193


Enumeration operations

decr/1 — decrement an integer or enumeration slot by 1

decr($SLOT)

Table 106 decr/1 arguments


Argument Mode Type Description
$SLOT input SLOTREF specifies an integer or enumeration slot to be decremented

Use decr/1 to decrement the slot referenced in $SLOT by 1. For an enumeration, the slot
is set to the next lower value, or unmodified if there is no lower value.

decr/1 example

decr( $E.mc_priority );

decr/2 and prev/2 — return an integer or enumeration slot


value decremented by 1
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 107 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

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.

194 BMC Impact Solutions: Knowledge Base Development Reference Guide


Enumeration operations

decr/2 example

$NEWPRIO = decr( $E.mc_priority );

decr/2 — decrement an integer or enumeration slot by a


specified value

decr($SLOT,$DECR)

Table 108 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

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.

decr2 example

decr( $E.mc_priority , 2 );

decr/3 — retrieve the value of an integer or enumeration


slot decremented by a specified value

$VAL=decr($SLOT,$DECR)

Table 109 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

Appendix B Master Rule Language (MRL) reference 195


Enumeration operations

Use decr/3 to retrieve the value of the slot referenced in $SLOT decremented by $DECR
in $VAL. For an enumeration, the slot value is decremented to the $DECR next lower
value. If there are not $DECR lower values, the slot value is decremented to the lowest
value.

The referenced slot itself is not modified.

decr/3 example

$NEWPRIO = decr( $E.mc_priority , 2 );

decr/3 — decrement an integer or enumeration slot by a


specified value within a given limit

decr($SLOT,$DECR,$LIMIT)

Table 110 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

Use decr/3 to decrement the slot referenced in $SLOT by $DECR, limited to the value
$LIMIT. For an enumeration, the slot value is decremented to the $DECR next lower
value, limited to $LIMIT.

decr/3 example

decr( $E.mc_priority , 2 , PRIORITY_4 );

decr/4 — return an integer or enumeration slot value


decremented by a specified value within a given limit

$VAL=decr($SLOT,$DECR,$LIMIT)

196 BMC Impact Solutions: Knowledge Base Development Reference Guide


String manipulation

Table 111 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

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.

decr/4 example

$NEWPRIO = decr( $E.mc_priority , 2 , PRIORITY_4 );

String manipulation

concat/2 — concatenate a list of strings

concat($STRLIST,$STR)
$STR=concat($STRLIST)

Table 112 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

Use concat/2 to concatenate the strings specified in $STRLIST into the single string
$STR. The strings are concatenated as is, without any additional separators.

concat/2 example

concat([’Duration: ’,inttostring($E.duration),’ seconds’],$E.msg);

Appendix B Master Rule Language (MRL) reference 197


String manipulation

strlen/2 and len/2 — determine the length of a string


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 113 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

Use strlen/2 to calculate the length of the string $STR and return the number of
characters in the string in the $LEN argument.

NOTE
The number of characters in the string may differ from the number of bytes needed to store
the string.

strlen/2 example

$MSGLEN = strlen($E.msg);

tolowercase/2 and lower/2 — convert a string to all


lowercase characters
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)

198 BMC Impact Solutions: Knowledge Base Development Reference Guide


String manipulation

Table 114 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

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.

tolowercase/2 example

$E.mc_host = tolowercase($E.mc_host);

touppercase/2 and upper/2 — convert a string to all


uppercase characters
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 115 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

Use touppercase/2 to convert the string specified in the $ORGSTR argument to the same
string in all uppercase characters returned in $NEWSTR. This function is locale
sensitive.

touppercase/2 example

$E.mc_host = touppercase($E.mc_host);

Appendix B Master Rule Language (MRL) reference 199


String manipulation

strpart/3 — determine the starting position of a partial


string within a larger string

strpart($STR,$PART,$POS)
$POS=strpart($STR,$PART)

Table 116 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

Use strpart/3 to determine the first position of the partial string specified in the $PART
argument within the string specified in the $STR argument. The starting position is
returned in $POS.

The starting position is determined by counting 1 as the first character of the string
specified in $STR. If the partial string does not occur within the base string, the value
0 is returned as the position of $PART.

strpart/3 example

$HLEN = len($E.mc_host);
$ZPOS = strpart($E.mc_host,’.’);
if ( $HLEN == 0 OR $ZPOS == 0 OR $ZPOS == $HLEN ) then
$E.mc_location = "Unknown";
else
$E.mc_location = substring($E.mc_host,$ZPOS,$HLEN-$ZPOS);

strnpart/4 — determine the start position of a specified


occurrence of a part of a string
strnpart($STR,$PART,$CNT,$POS)
$POS=strnpart($STR,$PART,$CNT)

200 BMC Impact Solutions: Knowledge Base Development Reference Guide


String manipulation

Table 117 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

Use strnpart/4 to determine at what position in $STR the number of occurrences for the
partial string $PART reaches $CNT number of occurrences. The position is returned in
$POS.

The first character of the string is counted as 1. If the partial string does not occur at
least $CNT times in the base string, the value 0 is returned as position.

strnpart/4 example

$HLEN = len($E.mc_host);
$ZPOS = strnpart($E.mc_host,’.’,2);
if ( $HLEN == 0 OR $ZPOS == 0 OR $ZPOS == $HLEN ) then
$E.mc_location = "Unknown";
else
$E.mc_location = substring($E.mc_host,$ZPOS,$HLEN-$ZPOS);

strextract/4 — retrieve a string of a specified length that


begins at a specified position within a larger string

strextract($STR,$POS,$LEN,$NEWSTR)
$NEWSTR=strextract($STR,$POS,$LEN)

Table 118 strextract/4 arguments (part 1 of 2)


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

Appendix B Master Rule Language (MRL) reference 201


String manipulation

Table 118 strextract/4 arguments (part 2 of 2)


Argument Mode Type Description
$LEN input INTEGER specifies the length (number of characters) of the partial
string that you want to return
$NEWSTR output STRING retrieved 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.

strextract/4 example

strextract($YYYYMMDD,5,2,$MM);

substring/3 — retrieve a string that begins at a specified


position within a larger string and continues through the
end of the larger string

$NEWSTR=substring($STR,$SKIP)

Table 119 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

Use substring/3 to retrieve a part of the string $STR in another string $NEWSTR. The
retrieved string starts after $SKIP characters from the beginning of the base string
specified in $STR and extends to the end of the base string.

substring/3 example

$DD = substring($YYYYMMDD,6);

202 BMC Impact Solutions: Knowledge Base Development Reference Guide


String manipulation

substring/4 — retrieve a substring of a specified length


beginning at a specified offset

$NEWSTR=substring($STR,$SKIP,$LEN)

Table 120 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

Use substring/4 to retrieve part of the string $STR into $NEWSTR. The retrieved part of
the string starts $SKIP characters from the start of $STR and is $LEN characters long.

substring/4 example

$MM = substring($YYYYMMDD,4,2);

strip/2 — strip leading and trailing blank spaces from a


string
$NEWSTR=strip($STR)

Table 121 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

Use strip/2 to remove the beginning and ending blank spaces from $STR and copy the
resulting string into $NEWSTR.

strip/2 example

$MSG = strip($E.msg);

Appendix B Master Rule Language (MRL) reference 203


String manipulation

strip/3 — remove blank spaces from specified parts of a


string
$NEWSTR=strip($STR,$POS)

Table 122 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

Use strip/3 to remove the blank spaces from position $POS within $STR and copy the
resulting string into $NEWSTR.

The value of $POS determines the part or parts of the base string where the blank
spaces are to be removed. Only the three least significant bits are considered, as
shown:

Table 123 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

strip/3 example

$MSG = strip($E.msg,2);

204 BMC Impact Solutions: Knowledge Base Development Reference Guide


String manipulation

strip/4 — remove specified characters from specified parts


of a string
$NEWSTR=strip($STR,$POS,$CHARS)

Table 124 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

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.

The value of $POS determines the part or parts of the base string where the blank
spaces are to be removed. Only the three least significant bits are considered, as
shown:

Table 125 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)

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.

Appendix B Master Rule Language (MRL) reference 205


String manipulation

For example, a string contains the following characters:

# !!# #a bc #! d # e #!#

The first character in the string up to, but not including, a is considered to be the
beginning of the string.

The part of the string starting from the space after the e through the last character in
the string is considered to be the end of the string.

The part of the string from the a through the e is considered to be the middle of the
string.

strip/4 example

$MSG = strip($E.msg,6,’ #!’);

The variable $MSG gets the contents of the msg slot of the event with all blank spaces, #
and ! characters removed, except at the end of the string. Any trailing sequence of
those three characters at the end of the slot value are retained.

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
strtolist($STR,$SEP,$FLDS)
$FLDS=strtolist($STR,$SEP)

Table 126 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

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.

206 BMC Impact Solutions: Knowledge Base Development Reference Guide


String manipulation

strtolist/3 example

strtolist(’/usr/bin/mcell.exe’,’/.’,$FLDS);

The input string will be divided into pieces that are separated with forward slash or
dot characters. The variable $FLDS will be set to the list [usr,bin,mcell,exe].

strmatch/3 — match a string with a simple pattern and


retrieve fields from it
strmatch($STR,$PAT,$FLDS)
$FLDS=strmatch($STR,$PAT)

Table 127 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

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:

\\ backslash
\s space (single space)
\n new line
\r carriage return
\t tab
\0ddd character code in octal

A substitute is preceded by a % sign, followed by a type indicator. Between the % and


the type indicator, an optional * suppression modifier can be added. The values
corresponding to the substitutes are collected in the fields in $FLDS, in order of
appearance. Suppressed substitutes are matched, but the values are not collected.

Appendix B Master Rule Language (MRL) reference 207


String manipulation

Possible substitutes are:

%% literal match of %
%d decimal integer number
%f floating point real number
%c single character
%s string value

Two substitutes cannot occur without literal text in between them. The portion of the
input that matches the substitute of %s depends on the pattern following the
substitute:

■ 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.

strmatch/3 example

strmatch(’abc def 12’,’%s %d’,[$FLD1,$FLD2]);

The pattern defines two fields, one string and one integer number, separated with
spaces. The variable $FLD1 will get the value abc def and variable $FLD2 will get the
value 12.

strmatch(’Hi you there!’,’Hi %s!’,$FLDS);

The pattern defines one string field, preceded by the text Hi and followed by an !
(exclamation point). The variable $FLDS will be set to a list containing the single
string you there.

strmatch(’Hi there’,’Hi %s!’,$FLDS);

This call will fail because the pattern defines one string field, preceded by the text Hi
and followed by an ! (exclamation point), but the input string does not contain an !
(exclamation point) at the end.

strmatch(’a b c go’,’%s %s go’,[$FLD1,$FLD2]);

208 BMC Impact Solutions: Knowledge Base Development Reference Guide


String manipulation

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


match_regex($STR,$REGEX,$OPTS)

Table 128 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

Use match_regex/3 to match a string $STR with regular expression $REGEX applying
options specified in $OPTS.

NOTE
The regular expression $REGEX must be compliant with the Perl Compatible Regular
Expression specification. For a specification, see http://perldoc.perl.org/perlre.html.

The value of the $OPTS argument can be either an empty string or a sequence of any
of the following option indicators:

i perform case insensitive string comparison


m multi-line mode
s a dot matches any character, including new line
x extended mode (see below)

In extended mode, blank space data characters in the pattern are ignored, except
when they are escaped or inside a character class. Characters between an unescaped #
outside a character class and the next new line character, inclusive, are also ignored.

The call of match_regex/3 will succeed if the string matches the regular expression and
fail otherwise.

Appendix B Master Rule Language (MRL) reference 209


String manipulation

match_regex/3 example

match_regex(’2007 02 04 mcell: RULES: xyz’,


’[0-9]* [0-9]* [0-9]* [^:]*: [^:]*: .*’,’’);

The input string, which could be part of a trace, matches the regular expression.

match_regex/4 — match a string with a regular expression


and retrieve all fields from it
match_regex($STR,$REGEX,$OPTS,$FLDS)
$FLDS=match_regex($STR,$REGEX,$OPTS)

Table 129 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
$OPTS input STRING specifies the options for how the regular
expression engine operates
$FLDS output LIST_OF STRING retrieved fields

Use match_regex/4 to match a string $STR with regular expression $REGEX applying
options from $OPTS and to collect retrieved fields in $FLDS.

NOTE
The regular expression $REGEX must be compliant with the Perl Compatible Regular
Expression specification. For a specification, see http://perldoc.perl.org/perlre.html.

The options argument can be either an empty string or a sequence of any of the
following option indicators:

i perform case insensitive string comparison


m multi-line mode
s a dot matches any character, including new line
x extended mode (see below)

The $FLDS argument can be specified as one variable that will get a list value, or it can
be specified as a list of as many variables as there are fields in the regular expression.

210 BMC Impact Solutions: Knowledge Base Development Reference Guide


String manipulation

match_regex/4 example

match_regex(’2007 02 04 mcell: RULES: xyz’,


’[0-9]* [0-9]* [0-9]* ([^:]*): ([^:]*): .*’,’’,$FLDS);

The input string, which could be part of a trace, matches the regular expression. The
two fields are collected in $FLDS as [mcell,RULES].

match_regex/5 — match a string with a regular expression


and retrieve a given number of fields from it
match_regex($STR,$REGEX,$OPTS,$FLDCNT,$FLDS)
$FLDS=match_regex($STR,$REGEX,$OPTS,$FLDCNT)

Table 130 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

Use match_regex/5 to match a string $STR with regular expression $REGEX applying
options from $OPTS and to collect the first $FLDCNT retrieved fields in $FLDS.

NOTE
The regular expression $REGEX must be compliant with the Perl Compatible Regular
Expression specification. For a specification, see http://perldoc.perl.org/perlre.html.

The options argument can be either an empty string or a sequence of any of the
following option indicators:

i perform case insensitive string comparison


m multi-line mode
s a dot matches any character, including new line
x extended mode (see below)

The $FLDS argument can be specified as one variable that will get a list value, or it can
be specified as a list of $FLDCNT variables.

Appendix B Master Rule Language (MRL) reference 211


String manipulation

match_regex/5 example

match_regex(’2007 02 04 mcell: RULES: xyz’,


’[0-9]* [0-9]* [0-9]* ([^:]*): ([^:]*): .*’,’’,1,[$FLD]);

The input string, which could be part of a trace, matches the regular expression.
There are two fields, but only the first one is collected in $FLD as mcell.

sprintf/3 — format a series of values into a string


sprintf($STR,$FORMAT,$ARGS)
$STR=sprintf($FORMAT,$ARGS)

Table 131 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

Use sprintf/3 to print a list of arguments specified in $ARGS into the $STR argument
using the format specified in $FORMAT.

The format specification for sprintf/3 is the same as for the C language sprintf()
function.

WARNING
The arguments specified in $ARGS must be compliant with the specified format. Passing
incompatible arguments can cause a crash of the cell.

sprintf/3 example

sprintf($E.msg,’Event #%x’,[$E.event_handle]);

The msg slot is set to the event number in hexadecimal notation (%x format).

212 BMC Impact Solutions: Knowledge Base Development Reference Guide


String manipulation

mapslots/4 — format a series of expressions that refer to


event and data objects into a string
$STR=mapslots($OBJECTS,$FORMAT,$EXPRS)

Table 132 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

Use mapslots/4 to evaluate a list of expressions $EXPRS, referring to objects from


$OBJECTS, and to format them into string $STR using format $FORMAT.

The format specification for mapslots/4 is the same as for the C language sprintf()
function.

The expressions given in $EXPRS are compiled and evaluated at the moment the
primitive is called, each time mapslots/4 is called. Within these expressions, the objects
from $OBJECTS can be referenced as $1, $2,... for the first, second,... element of the
object list.

The values resulting from the evaluation of the expressions, have to be compliant
with the specified format. Incompatible expression evaluation results, can cause a
crash of the cell.

mapslots/4 example

$STR = mapslots([$E,$D],’Event %s is associated to data %s’,


[’$1.mc_ueid’,’$2.mc_udid’]);

A message is produced stating that an event and data object are associated. The event
and data object are passed as $E and $D, respectively, in the first argument. The list of
expressions contains two expressions that result in a string. The first one retrieves the
mc_ueid slot of the event object, the second one retrieves the mc_udid of the data
object.

Appendix B Master Rule Language (MRL) reference 213


String manipulation

mapslots/3 — format a series of expressions that refer to


objects into a string
$STR=mapslots($OBJECTS,$EXPRS)

Table 133 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

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.

The first element from the list $EXPRS is taken as format. The rest of the expressions
given in $EXPRS are compiled and evaluated at the moment the primitive is called, for
each call again. Within these expressions, the objects from $OBJECTS can be
referenced as $1, $2,... for the first, second,... element of the object list.

WARNING
The values resulting from the evaluation of the expressions must be compliant with
the specified format. Incompatible expression evaluation results can cause a crash of
the cell.

mapslots/3 example

$STR = mapslots([$E,$D],
[’Event %s is associated to data %s’,’$1.mc_ueid’,’$2.mc_udid’]);

A message is produced stating that an event and data object are associated. The event
and data object are passed as $E and $D, respectively, in the first argument. The list of
expressions contains the format for the message, followed by two expressions that
result in a string. The first one retrieves the mc_ueid slot of the event object, the
second one retrieves the mc_udid of the data object.

214 BMC Impact Solutions: Knowledge Base Development Reference Guide


Time stamp functions

Time stamp functions

time_stamp/1— retrieve the current time


time_stamp($TIME)
$TIME=time_stamp()

Table 134 time_stamp/1 arguments


Argument Mode Type Description
$TIME output INTEGER time stamp for the current time

Use time_stamp/1 to retrieve the current system time as a time stamp in $TIME.

time_stamp/1 example

$TM = time_stamp();

time_stamp_to_cim/2 — convert a time stamp to CIM


(Common Information Model) format

time_stamp_to_cim($TIME,$CIM)
$CIM=time_stamp_to_cim($TIME)

Table 135 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

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.

Appendix B Master Rule Language (MRL) reference 215


Time stamp functions

The CIM format is YYYYMMDDhhmmssuuuuuu+zzz, where:

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

time_stamp_to_cim/2 example

$CIM = time_stamp_to_cim(time_stamp());

time_stamp_to_str/3 — convert a time stamp to a


specified format

time_stamp_to_str($TIME,$FORMAT,$STR)
$STR=time_stamp_to_str($TIME,$FORMAT)

Table 136 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

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.

time_stamp_to_str/3 example

time_stamp_to_str(time_stamp(),’%c’,$TM);

The current time is formatted in the appropriate date and time representation for the
current locale.

216 BMC Impact Solutions: Knowledge Base Development Reference Guide


Time stamp functions

time_stamp_to_str/2 — convert a time stamp to the


default DateFormat format

time_stamp_to_str($TIME,$STR)
$STR=time_stamp_to_str($TIME)

Table 137 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

Use time_stamp_to_str/2 to convert the time stamp specified in $TIME to a string $STR
containing the time stamp in the format specified in the configuration parameter
DateFormat.

time_stamp_to_str/2 example

time_stamp_to_str(time_stamp(),$TM);

The current time is formatted as specified in DateFormat. The default value for
DateFormat is CIM.

time_extract/3 — retrieve fields from a time stamp

time_extract($TIME,$FLDS,$VALS)
$VALS=time_extract($TIME,$FLDS)

Table 138 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
$FLDS input ■ STRING specifies the field or list of fields to be
■ LIST_OF STRING retrieved
$VALS output ■ INTEGER retrieved field value or list of retrieved field
■ LIST_OF INTEGER values

Use time_extract/3 to retrieve one or more fields as specified in $FLDS from the time
stamp $TIME into the $VALS argument.

Appendix B Master Rule Language (MRL) reference 217


Time stamp functions

The time stamp is a time value in internal numeric form, similar to the
date_reception slot, or as retrieved from the time_stamp/1 primitive. The fields
retrieved from the time stamp reflect the local actual time zone of the system on
which the cell is running.

Time stamp fields are indicated by name. Available fields are:

date 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)

All returned field values are integer numbers. Note that the values for the date and
time fields are also integers, structured in a fixed decimal format. A time value will
not always have six significant digits. Times before 10:00:00 only have five significant
decimal digits.

The $VALS argument can be specified as one variable that will get the single requested
field value or a list containing all requested field values. $VALS can also be specified
as a list of as many variables as the number of requested fields.

time_extract/3 example

time_extract($E.date_reception,[date,time],[$DT,$TM]);

Variables $DT and $TM will contain the date and time of the time stamp, as integers,
for the time the event was received. For instance, if the event was received on 6-Feb-
2007 at 9:15:20, $DT would be 20070206 and $TM would be 91520.

str_to_time_stamp/3 — convert a string to a time stamp

str_to_time_stamp($STR,$FORMAT,$TIME)
$TIME=str_to_time_stamp($STR,$FORMAT)

218 BMC Impact Solutions: Knowledge Base Development Reference Guide


Time stamp functions

Table 139 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

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/3 example

str_to_time_stamp($E.date,’%c’,$TM);

The date slot is parsed to a numeric time stamp value, if it is formatted in the
appropriate date and time representation for the current locale.

Appendix B Master Rule Language (MRL) reference 219


List operations

List operations

listlen/2 — determine the length of a list

listlen($LIST,$LEN)
$LEN=listlen($LIST)

Table 140 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

Use listlen/2 to determine the length of the list $LIST and return the length (in
characters) in the $LEN argument.

listlen/2 example

$CNT_BAD_SLOTS=listlen($E.mc_bad_slot_names);

listgetelt/3 — retrieve a list element located at a specified


position within a list

listgetelt($LIST,$POS,$ELEM)
$ELEM=listgetelt($LIST,$POS)

Table 141 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
$POS input INTEGER specifies of the position of requested element
$ELEM output ANY element at the specified position in list

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.

220 BMC Impact Solutions: Knowledge Base Development Reference Guide


List operations

listgetelt/3 example

$BAD_SLOT2=listgetelt($E.mc_bad_slot_names,2);

listmember/2 — verify that an element is included in a list

listmember($LIST,$ELEM)

Table 142 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

Use listmember/2 to verify whether or not an element $ELEM occurs in list $LIST.

This primitive succeeds or fails depending on whether the element occurs in the list
or not.

listmember/2 example

if ( listmember($E.mc_bad_slot_names,my_slot) ) ...

listdelete/3 — remove all occurrences of an element from a


list

listdelete($LIST1,$ELEM,$LIST)
$LIST=listdelete($LIST1,$ELEM)

Table 143 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

Use listdelete/3 to remove all occurrences of element $ELEM from list $LIST1 and place
the resulting list into $LIST.

Appendix B Master Rule Language (MRL) reference 221


List operations

listdelete/3 example

$BAD_SLOTS=listdelete($E.mc_bad_slot_names,my_slot);

listappend/3 — concatenate two lists


listappend($LIST1,$LIST2,$LIST)
$LIST=listappend($LIST1,$LIST2)

Table 144 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

Use listappend/3 to concatenate list $LIST1 and list $LIST2 into list $LIST.

The elements in both lists must be the same type.

listappend/3 example

$BAD_SLOTS=listappend($E.mc_bad_slot_names,$E.mc_bad_slot_values);

listdisjoint/2 — verify that two lists do not have any


common elements

listdisjoint($LIST1,$LIST1)

Table 145 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

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.

222 BMC Impact Solutions: Knowledge Base Development Reference Guide


List operations

listdisjoint/2 example

if ( listdisjoint($E.mc_bad_slot_names,[my_slot1,my_slot2]) ) ...

listintersect/3 — determine the common elements of two


lists

listintersect($LIST1,$LIST2,$LIST)
$LIST=listintersect($LIST1,$LIST2)

Table 146 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

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.

listintersect/3 example

$MY_BAD_SLOTS=listintersect($E.mc_bad_slot_names,[my_slot1,my_slot2]);

listunion/3 — determine the union of two lists

listunion($LIST1,$LIST2,$LIST)
$LIST=listunion($LIST1,$LIST2)

Table 147 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

Appendix B Master Rule Language (MRL) reference 223


List operations

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

$MY_BAD_SLOTS=listunion($E.mc_bad_slot_names,[my_slot1,my_slot2]);

listsubtract/3 — remove the elements that occur in one list


from another list

listsubtract($LIST1,$LIST2,$LIST)
$LIST=listsubtract($LIST1,$LIST2)

Table 148 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

Use listsubtract/3 to construct a new list $LIST that contains all elements from list
$LIST1 that do not occur in $LIST2.

The elements in both lists must be the same type.

listsubtract/3 example

$MY_BAD_SLOTS=listsubtract($E.mc_bad_slot_names,[my_slot1,my_slot2]);

224 BMC Impact Solutions: Knowledge Base Development Reference Guide


List operations

listremdup/2 — remove duplicate elements from a list

listremdup($LIST1,$LIST)
$LIST=listremdup($LIST1)

Table 149 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

Use listremdup/2 to construct a new list $LIST that contains all the elements from list
$LIST1 without duplicates.

listremdup/2 example

$MY_BAD_SLOTS=listremdup($E.mc_bad_slot_names);

listwalk/2 — execute instructions against each element in a


list

listwalk($LIST,$ELEM)
$ELEM=listwalk($LIST)

Table 150 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

Use listwalk/2 to go through each element in list $LIST, returning each element in
$ELEM. All instructions following the call of listwalk/2 are executed for each element.

listwalk/2 example

$E.msg = ’Bad slot names:’;


listwalk($E.mc_bad_slot_names,$SLTNM);
concat([$E.msg,’ ’,$SLTNM],$E.msg);

The msg slot is filled with the sequence of bad slot names.

Appendix B Master Rule Language (MRL) reference 225


List operations

add_to_list/2 — add an element at the beginning of a list


slot

add_to_list($ELEM,$LISTSLOT)

Table 151 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

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.

add_to_list/2 example

add_to_list(my_slot,$E.mc_bad_slot_names);

rem_from_list/2 — remove the first occurrence of an


element from a list slot

rem_from_list($ELEM,$LISTSLOT)

Table 152 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

Use rem_from_list/2 to remove the first occurrence of the value in $ELEM from the list
slot specified in the $LISTSLOT argument.

This primitive fails if the indicated slot is not a list slot, or if the type of the element
does not correspond to the type of the elements of the list.

rem_from_list/2 example

rem_from_list(my_slot,$E.mc_bad_slot_names);

226 BMC Impact Solutions: Knowledge Base Development Reference Guide


Match table lookup primitives

Match table lookup primitives

find_match/5 — find an entry in a match table and retrieve


calculated values from it

find_match($TBLNAME,$TAG,$VALUES,$OBJECTS,$RESULTS)
$RESULTS=find_match($TBLNAME,$TAG,$VALUES,$OBJECTS)

Table 153 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
$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

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.

Appendix B Master Rule Language (MRL) reference 227


Match table lookup primitives

■ 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.

During evaluation of the output expressions, instances from $OBJECTS can be


referenced. These references are indicated as $1, $2,... in the output expression to
refer to the first, second,... element of $OBJECTS. Each object passed in $OBJECTS must
be an instance of the class specified at the same position in the slot
ref_instances_classes of the matching entry.

find_match/5 example

In this example, there are several instances of BEM_MATCH_TABLE, including the


following:

BEM_MATCH_TABLE;
tag=t1;
input_match=[’<SERVICE>’,’<svc_>*’];
ref_instances_classes=[EVENT,DATA];
output_expressions=[’sprintf("Service %s (%s) changed to %s",
[$1.mc_object,$2.description,$1.mc_parameter_value])’,MINOR];
END

In this example, the KB contains data objects that provide a description of registered
services. A rule that handles service-related events can look up the data object for the
service, returned in $D in the following piece of code, while the event is referenced
through $E.

find_match(BEM_MATCH_TABLE,t1,[$E.mc_object_class,$E.mc_object],
[$E,$D],[$MSG,$SEV]);
$E.msg = $MSG;
$E.severity = $SEV;

If the mc_object_class of the event has the value SERVICE, and its mc_object starts
with svc_, the call of find_match/5 will match with the BEM_MATCH_TABLE entry
shown above.

The event and data object references are passed through the fourth argument. They
are referred to in the output expressions as $1 and $2 respectively.

228 BMC Impact Solutions: Knowledge Base Development Reference Guide


Match table lookup primitives

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

find_match_entry($TBLNAME,$TAG,$VALUES,$ENTRY)
$ENTRY=find_match_entry($TBLNAME,$TAG,$VALUES)

Table 154 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

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 227. 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 230.

find_match_entry/4 example

In this example, there are several instances of BEM_MATCH_TABLE, including the


following:

BEM_MATCH_TABLE;
tag=t1;
input_match=[’<SERVICE>’,’<svc_>*’];
ref_instances_classes=[EVENT,DATA];
output_expressions=[’sprintf("Service %s (%s) changed to %s",
[$1.mc_object,$2.description,$1.mc_parameter_value])’,MINOR];
END

Appendix B Master Rule Language (MRL) reference 229


Match table lookup primitives

In this example, the KB contains data objects that provide a description of registered
services. A rule that handles service-related events can look up the data object for the
service, returned in $D in the following piece of code, while the event is referenced
through $E.

$M = find_match_entry(BEM_MATCH_TABLE,t1,
[$E.mc_object_class,$E.mc_object]);

This call will return a reference to the match table entry in $M.

apply_match_entry/4 — obtain output values from a match


table entry

RESULTS($ENTRY,$VALUES,$OBJECTS,$RESULTS)
$ENTRY=apply_match_entry($ENTRY,$VALUES,$OBJECTS)

Table 155 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

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 227. 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 229.

230 BMC Impact Solutions: Knowledge Base Development Reference Guide


Object slot manipulation

apply_match_entry/4 example

In this example, there are several instances of BEM_MATCH_TABLE, including the


following:

BEM_MATCH_TABLE;
tag=t1;
input_match=[’<SERVICE>’,’<svc_>*’];
ref_instances_classes=[EVENT,DATA];
output_expressions=[’sprintf("Service %s (%s) changed to %s",
[$1.mc_object,$2.description,$1.mc_parameter_value])’,MINOR];
END

In this example, the KB contains data objects that provide a description of registered
services. A rule that handles service-related events can look up the data object for the
service, returned in $D in the following piece of code, while the event is referenced
through $E.

$M = find_match_entry(BEM_MATCH_TABLE,t1,
[$E.mc_object_class,$E.mc_object]);

This call will return a reference to the match table entry in $M.

apply_match_entry($M,[$E.mc_object_class,$E.mc_object],
[$E,$D],[$MSG,$SEV]);
$E.msg = $MSG;
$E.severity = $SEV;

The event and data object references are passed through the third argument. They are
referred to in the output expressions as $1 and $2 respectively.

Evaluation of the two output expressions returns a message into $MSG and a severity
in $SEV. The severity is a constant value. The message is produced by filling in some
slots from the event (mc_object and mc_parameter_value) and the description
slot of the data object in a message format.

Object slot manipulation

get_list_slotvalues/3 — retrieve a list of slots from one or


more objects

get_list_slotvalues($OBJECTS,$SLOTS,$VALUES)
$VALUES=get_list_slotvlaues($OBJECTS,$SLOTS)

Appendix B Master Rule Language (MRL) reference 231


Object slot manipulation

Table 156 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 ANY resulting list of slot values

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.

The desired slots must be specified in $SLOTS by name, or by reference to an object


and the slot name. A reference to a slot of an object has the form $n.SlotName, where n
is the sequence number of the desired object in $OBJECTS. If the slot is only
mentioned by name and no object reference, it is taken from the first object in the list.

get_list_slotvalues/3 example

$VALUES = get_list_slotvalues([$E,$D],[mc_ueid,status]);

The list $VALUES will contain the mc_ueid and the status slot from the event object
$E.

$VALUES = get_list_slotvalues([$E,$D],
[’$1.mc_ueid’,’$1.status’,’$2.mc_udid’]);

The list $VALUES will contain the mc_ueid and the status of the event object $E, and
the mc_udid of the data object $D.

set_list_slotvalues/3 — assign values to a list of slots for


one or more objects

set_list_slotvalues($OBJECTS,$SLOTS,$VALUES)

Table 157 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

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.

232 BMC Impact Solutions: Knowledge Base Development Reference Guide


Specific 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.

The slot and values lists must contain the same number of elements.

set_list_slotvalues/3 example

set_list_slotvalues([$E,$D],[status,msg],[CLOSED,done]);

The status slot of the event object $E is set to CLOSED, and its msg slot is set to done.

set_list_slotvalues([$E,$D],[’$1.status’,’$1.msg’,’$2.name’],
[CLOSED,done,john]);

The status slot of the event object $E is set to CLOSED, and its msg slot is set to done.
The name slot of the data object $D is set to john.

Specific slot manipulation

class_path/2 — obtain the class hierarchy of a class

class_path($CLASS,$PATH)
$PATH=class_path($CLASS)

Table 158 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

Use class_path/2 to obtain the complete class hierarchy of the class specified in $CLASS
and return the hierarchy in $PATH.

$PATH is a list of class names that starts with the class specified in $CLASS. The next
element in the list is the direct super class for $CLASS, and so on, up to the root class.

class_path/2 example

class_path(MC_CELL_ACTION_RESULT,$PATH);

Appendix B Master Rule Language (MRL) reference 233


Specific slot manipulation

The variable $PATH will be


[MC_CELL_ACTION_RESULT,MC_CELL_CONTROL,CORE_EVENT].

reset_default/1 — reset a slot to its default value

reset_default($SLOT)

Table 159 reset_default/1 arguments


Argument Mode Type Description
$SLOT input SLOTREF specifies the slot to be reset

Use reset_default/1 to reset slot $SLOT to its default value.

The default value is as specified in the class definition.

reset_default/1 example

reset_default($E.severity);

ntadd/2 — add a note to an event

ntadd($EVENT,$SLOT)

Table 160 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

Use ntadd/2 to add a note with text $SLOT to the event $EVENT.

The note is added to the mc_notes slot of the event and time stamped with the
current time. The author of the note is set to the identifier of the rule that calls the
primitive.

ntadd/2 example

ntadd($E,’Event updated by rule’);

234 BMC Impact Solutions: Knowledge Base Development Reference Guide


Specific slot manipulation

ntcnt/2 — count the notes attached to an event

ntcnt($EVENT,$COUNT)

Table 161 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

Use ntcnt/2 to count the notes that are attached to event $EVENT, in $COUNT.

ntcnt/2 example

ntcnt($E,$NR_OF_NOTES);

ntget/5 — return the time stamp, author, and text of a note


attached to an event

ntget($EVENT,$SEQNR,$TIME,$AUTHOR,$TEXT)

Table 162 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

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 235.

Appendix B Master Rule Language (MRL) reference 235


Specific slot manipulation

ntget/5 example

ntget($E,0,$TIME,$AUTHOR,$SLOT);

ntset/3 — modify the text of a note attached to an event

ntset($EVENT,$SEQNR,$TEXT)

Table 163 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

Use ntset/3 to replace the text of the note in the $SEQNR position with the text $TEXT
for the event $EVENT.

Notes are numbered, starting from 1 for the oldest note. The most recent note can be
obtained by indicating 0 as sequence number.

NOTE
Only the text of a note can be replaced. The time stamp and author cannot be
modified.

ntset/3 example

ntset($E,0,’New explanation’);

opadd/4 — add a policy operation to an event

opadd($EVENT,$POLICY,$ACTION,$ARGS)

Table 164 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

236 BMC Impact Solutions: Knowledge Base Development Reference Guide


Specific slot manipulation

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.

opadd/4 example

opadd($E,’Policy1’,’Data Enrichment’,’’);

opadd/3 — add an operation to an event

opadd($EVENT,$ACTION,$ARGS)

Table 165 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

Use opadd/3 to add an operation with action name $ACTION and argument list $ARGS
to event $EVENT.

The operation is added to the mc_operations slot of the event and time stamped
with the current time. The author of the operation is set to the identifier of the rule
that calls the primitive.

The argument list must be formatted as a string. $ARGS can be an empty string if no
arguments are needed.

opadd/3 example

opadd($E,’AcknowledgeEvent’,’’);

opcnt/2 — count the operations of an event

opcnt($EVENT,$COUNT)

Appendix B Master Rule Language (MRL) reference 237


Specific slot manipulation

Table 166 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

Use opcnt/2 to count the operations that are attached to event $EVENT and return the
number in $COUNT.

opcnt/2 example

opcnt($E,$NR_OF_OPS);

opget/7 — retrieve a policy operation of an event

opget($EVENT,$SEQNR,$TIME,$AUTHOR,$POLICY,$ACTION,$ARGS)

Table 167 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

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 237.

opget/7 example

opget($E,0,$TIME,$AUTHOR,$POLICY,$ACTION,$ARGS);

238 BMC Impact Solutions: Knowledge Base Development Reference Guide


Specific slot manipulation

opget/6 — retrieve an operation of an event

opget($EVENT,$SEQNR,$TIME,$AUTHOR,$ACTION,$ARGS)

Table 168 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

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 237.

opget/6 example

opget($E,0,$TIME,$AUTHOR,$ACTION,$ARGS);

opget_time/3 — retrieve the time stamp of an operation of


an event

$TIME=opget_time($EVENT,$SEQNR)

Table 169 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

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.

Appendix B Master Rule Language (MRL) reference 239


Specific slot manipulation

Operations are numbered, starting from 1 for the oldest operation. The most recent
operation can be obtained by indicating 0 as sequence number.

opget_time/3 example

$TIME=opget_time($E,0);

opget_author/3 — retrieve the author of an operation of


an event

$AUTHOR=opget_author($EVENT,$SEQNR)

Table 170 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

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 237.

opget_author/3 example

$AUTHOR=opget_author($E,0);

opget_action/3 — retrieve the action name of an operation


of an event

$ACTION=opget_action($EVENT,$SEQNR)

Table 171 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

240 BMC Impact Solutions: Knowledge Base Development Reference Guide


Specific slot manipulation

Use opget_action/3 to obtain the action name of operation $SEQNR that is attached to
event $EVENT and return the value in $ACTION.

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 237.

opget_action/3 example

$ACTION=opget_action($E,0);

opget_args/3 — retrieve the argument list of an operation


of an event

$ARGS=opget_args($EVENT,$SEQNR)

Table 172 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

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 237.

opget_args/3 example

$ARGS=opget_args($E,0);

opset/5 — modify the policy name, action, and arguments


of an operation of an event

opset($EVENT,$SEQNR,$POLICY,$ACTION,$ARGS)

Appendix B Master Rule Language (MRL) reference 241


Specific slot manipulation

Table 173 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

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 237.

NOTE
The time stamp and author of an operation cannot be modified.

opset/5 example

opset($E,0,’Policy2’,’Data Enrichment’,’’);

opset/4 — modify the action and arguments of an


operation of an event

opset($EVENT,$SEQNR,$ACTION,$ARGS)

Table 174 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

242 BMC Impact Solutions: 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 237.

NOTE
The time stamp and author of an operation cannot be modified.

opset/4 example

opset($E,0,’CloseEvent’,’’);

Object relation functions

relate/1 — establish the relation of an event to a source


event

relate($EVENT)

Table 175 relate/1 arguments


Argument Mode Type Description
$EVENT input OBJECT specifies the event to be related 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.

Appendix B Master Rule Language (MRL) reference 243


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:

MC_EVENT_RELATION; type=tt_HD; class=HD_TROUBLE_TICKET; END

When a trouble ticket event is received, the following rule will relate it to its source
event:

refine HD_trouble_ticket_relate : HD_TROUBLE_TICKET($E)


{ relate($E); }
END

This assumes that the HD_TROUBLE_TICKET event contains the mc_ueid of the source
event in its mc_relation_source slot. The type of the relation will be tt_HD.

unrelate/1 — remove a relation of a related event to a


source event

unrelate($EVENT)

Table 176 unrelate/1 arguments


Argument Mode Type Description
$EVENT input OBJECT specifies the event to be unrelated from 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.

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.

244 BMC Impact Solutions: 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:

MC_EVENT_RELATION; type=tt_HD; class=HD_TROUBLE_TICKET; END

When a trouble ticket event is received, the following rule will relate it to its source
event:

refine HD_trouble_ticket_relate : HD_TROUBLE_TICKET($E)


{ relate($E); }
END

This assumes that the HD_TROUBLE_TICKET event contains the mc_ueid of the source
event in its mc_relation_source slot. The type of the relation will be tt_HD.

In this scenario, the following rule will undo the relation of a trouble ticket event to its
source, when the trouble ticket event is not open anymore:

execute HD_trouble_ticket_unrelate : HD_TROUBLE_TICKET($E)


when $E.status != OPEN { unrelate($E); }
END

Operation environment inquiry

cellinfo/2 — retrieve cell-specific information

cellinfo($FIELD,$INFO)
$INFO=cellinfo($FIELD)

Table 177 cellinfo/2 arguments


Argument Mode Type Description
$FIELD input STRING specifies the desired information item to be retrieved
$INFO output STRING retrieved cell information
LIST_OF STRING

Use cellinfo/2 to obtain information item specified in $FIELD and return the
information in $INFO.

Appendix B Master Rule Language (MRL) reference 245


Operation environment inquiry

The following information fields are defined:

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)

cellinfo/2 example

$E.mc_host = cellinfo(HostName);

cellcontrol/1 — perform a cell control command

cellcontrol($COMMAND)

Table 178 cellcontrol/1 arguments


Argument Mode Type Description
$COMMAND input STRING control command to be performed

Use cellcontrol/1 to perform the control command specified in $COMMAND.

246 BMC Impact Solutions: Knowledge Base Development Reference Guide


Operation environment inquiry

The following commands are defined:

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/1 example

cellcontrol(pause);

kbversion/2 — retrieve Knowledge Base module version


information

kbversion($MODULE,$VERSION)
$VERSION=kbversion($MODULE)

Table 179 kbversion/2 arguments


Argument Mode Type Description
$MODULE input STRING specifies identifier for the KB module
$VERSION output STRING KB 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.

kbversion/2 example

kbversion(TroubleTicketing,$VERSION);

Appendix B Master Rule Language (MRL) reference 247


Operation environment inquiry

kbversion/1 — retrieve global Knowledge Base module


version information

kbversion($VERSION)
$VERSION=kbversion()

Table 180 kbversion/1 arguments


Argument Mode Type Description
$VERSION output STRING KB 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

kbversion($VERSION);

get_env/2 — retrieve the value of an environment variable

get_env($ENVVAR,$VALUE)
$VALUE=get_env($ENVVAR)

Table 181 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

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.

get_env/2 example

$HOME = get_env(HOME);

248 BMC Impact Solutions: Knowledge Base Development Reference Guide


Propagation

Propagation

send_to/2 — send an event to another cell or gateway

send_to($DEST,$EVENT)

Table 182 send_to/2 arguments


Argument Mode Type Description
$DEST input ■ STRING specifies a single destination or a list of possible
■ LIST_OF STRING destinations for the event
$EVENT input OBJECT specifies the event to send

Use send_to/2 to send event $EVENT to destination $DEST.

The destination must be specified by name. If $DEST is a list of destination names, the
event modification is sent to the first destination that can be reached.

When sending an event with send_to/2, event modifications will not be propagated
automatically, either forward or backward.

send_to/2 example

send_to([Cell2,Cell3],$E);

send_to/3 — send an event modification to another cell or


gateway

send_to($DEST,$EVENT,$SLOTS)

Table 183 send_to/3 arguments


Argument Mode Type Description
$DEST input ■ STRING specifies a single destination or a list of possible
■ LIST_OF STRING 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

Use send_to/3 to send modifications of slots $SLOTS of event $EVENT to destination


$DEST.

Appendix B Master Rule Language (MRL) reference 249


Propagation

The destination must be specified by name. If $DEST is a list of destination names, the
event is sent to the first destination that can be reached.

Only the slots that are explicitly indicated will be sent to the destination, in the form
of an event modification.

send_to/3 example

send_to([Cell2,Cell3],$E,[status,severity]);

send_to_ext/4 — send an extended event to another cell or


gateway
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 184 send_to_ext/4 arguments


Argument Mode Type Description
$DEST input ■ STRING specifies a single destination or a list of
■ LIST_OF STRING 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

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.

When sending an event with send_to_ext/4, event modifications will not be


propagated automatically, either forward or backward.

250 BMC Impact Solutions: Knowledge Base Development Reference Guide


Service model inquiry

send_to_ext/4 example

send_to_ext([Cell2,Cell3],$E,[slot1,slot2],[value1,value2]);

Service model inquiry

smcomps/5 — search for certain Service Model


components
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 185 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

Use the smcomps/5 primitive to return a list of pointers to the components that are in
the impact path or the cause path of a selected component. Various parameters can be
used to refine that list.

The smcomps/5 primitive makes it possible to retrieve, manage and propagate a list of
impacted components or causal components from within the rules of a Knowledge
Base.

NOTE
You can also retrieve root causes using MC_SM_ROOT_CAUSE instead of smcomps.

smcomps/5 searches for Service Model components as specified by the $PARMNAMES


and $PARMVALS argument values. The result is returned as a list of primary search
components $COMPS1, a list of shadow components $SHADOWS, and a list of secondary
search components $COMPS2.

Appendix B Master Rule Language (MRL) reference 251


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:

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.

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.

252 BMC Impact Solutions: Knowledge Base Development Reference Guide


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

smcomps([comp,dir,impact,events,leaf],[comp123,i,t,T,T],$COMPS,$SHADOW,$C2);
listwalk($COMPS,$COMP);
concat([$MSG,' ',$COMP.mc_udid],$MSG);

In this example, a listwalk of the result list is performed to save the mc_udids in a
slot of the event. You can then retrieve the desired properties from the components
by a using clause referencing the udids.

License key functions

key_version/2 — retrieve the version from a license key

key_version($KEY,$VERSION)

Table 186 key_version/2 arguments


Argument Mode Type Description
$KEY input STRING specifies the license key
$VERSION output INTEGER version of 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.

Appendix B Master Rule Language (MRL) reference 253


License key functions

key_version/2 example

key_version($KEY,$VERSION);
if ( $VERSION == 1 ) then ...

key_verify/2 — validate and retrieve fields from a license


key

key_verify($KEY,$FIELDS)

Table 187 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

Use key_verify/2 to validate license key $KEY and to retrieve fields from the license
key in $FIELDS.

A license key is a string containing licensing information, as provided by BMC


Software.

The application is responsible to determine the exact number of fields that are
expected in the key. The $FIELDS argument has to be specified as a list of as many
variables as the number of fields.

This primitive will fail if the key is invalid or if the number of fields is not exact. It can
be used in an if-statement to test for success.

key_verify/2 example

if ( key_verify($KEY,[$FLD1,$FLD2]) ) then ...

key_verify/3 — validate and retrieve fields from a license


key

key_verify($KEY,$FIELDS,$VALID)

Table 188 key_verify/3 arguments (part 1 of 2)


Argument Mode Type Description
$KEY input STRING specifies the license key

254 BMC Impact Solutions: Knowledge Base Development Reference Guide


Time frame operations

Table 188 key_verify/3 arguments (part 2 of 2)


Argument Mode Type Description
$FIELDS output LIST_OF STRING list of fields from key
$VALID output INTEGER key validity (0=invalid, 1=valid)

Use key_verify/3 to determine the validity of license key $KEY in $VALID, and to
retrieve fields from the key and return them in $FIELDS.

A license key is a string containing licensing information, as provided by BMC


Software.

The application is responsible to determine the exact number of fields that are
expected in the key. The $FIELDS argument has to be specified as a list of as many
variables as the number of fields.

If the key is invalid, or if the number of fields is not exact, $VALID will be set to 0.
Otherwise it will be set to 1.

key_verify/3 example

key_verify($KEY,[$FLD1,$FLD2],$VALID);
$LICDATA.key_validity = $VALID;

Time frame operations

tf_active/1 — verify if one or more time frames are active

tf_active($TIMEFRAME)

Table 189 tf_active/1 arguments


Argument Mode Type Description
$TIMEFRAME input ■ STRING ■ time frame name
■ LIST_OF STRING ■ list of time frame names
■ OBJECT ■ time frame object
■ LIST_OF OBJECT ■ list of time frame objects

Use tf_active/1 to determine whether the time frame(s) $TIMEFRAME is active at the
current moment.

Appendix B Master Rule Language (MRL) reference 255


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

if ( tf_active($TF) ) then ...

tf_active/2 — verify if one or more time frames are active


at a given time

tf_active($TIMEFRAME,$TIME)

Table 190 tf_active/2 arguments


Argument Mode Type Description
$TIMEFRAME input ■ STRING ■ time frame name
■ LIST_OF STRING ■ list of time frame names
■ OBJECT ■ time frame object
■ LIST_OF OBJECT ■ list of time frame objects
$TIME input INTEGER time to check activity

Use tf_active/2 to determine whether time frame(s) $TIMEFRAME is active at time


$TIME.

A time frame can be specified with its object handle or by name. One or multiple time
frames can be specified. If multiple time frames are specified, they must all be
specified by either object or name.

The primitive will fail if the indicated time frame(s) are not all active at the indicated
time.

tf_active/2 example

if ( tf_active($TF,$TIME) ) then ...

tf_udid_active/1 — verify if one or more time frames


specified by mc_udid are active at the current time

tf_udid_active($TIMEFRAME)

256 BMC Impact Solutions: Knowledge Base Development Reference Guide


Time frame operations

Table 191 tf_udid_active/1 arguments


Argument Mode Type Description
$TIMEFRAME input ■ STRING ■ time frame mc_udid
■ LIST_OF STRING ■ mc_udid list for multiple time frames

Use tf_udid_active/1 to determine whether the time frame(s) $TIMEFRAME is active at


the current time.

A time frame is specified with its mc_udid. One or multiple time frames can be
specified.

The primitive will fail if the indicated time frame(s) are not all active.

tf_udid_active/1 example

if ( tf_udid_active([’TF.001’,’TF.002’]) ) then ...

tf_udid_active/2 — verify if one or more time frames


specified by mc_udid are active at a specified time

tf_udid_active($TIMEFRAME,$TIME)

Table 192 tf_udid_active/2 arguments


Argument Mode Type Description
$TIMEFRAME input ■ STRING ■ time frame mc_udid
■ LIST_OF STRING ■ mc_udid list for multiple time frames
$TIME input INTEGER specified time to check activity

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.

tf_udid_active/2 example

if ( tf_udid_active([’TF.001’,’TF.002’],$TIME) ) then ...

Appendix B Master Rule Language (MRL) reference 257


Time frame operations

tf_current_start/2 — obtain the start time of the current


active interval of a time frame

tf_current_start($TIMEFRAME,$START)
$START=tf_current_start($TIMEFRAME)

Table 193 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

Use tf_current_start/2 to obtain the start time of the current active interval of time
frame $TIMEFRAME and return the start time in $START.

A 0 value is returned if the indicated time frame is not active.

tf_current_start/2 example

$START = tf_current_start($TF);

tf_current_start/3 — obtain the start time of the active


interval of a time frame at a specified time

tf_current_start($TIMEFRAME,$TIME,$START)
$START=tf_current_start($TIMEFRAME,$TIME)

Table 194 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

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.

tf_current_start/3 example

$START = tf_current_start($TF,$TM);

258 BMC Impact Solutions: Knowledge Base Development Reference Guide


Time frame operations

tf_current_end/2 — obtain the end time of the current


active interval of a time frame

tf_current_end($TIMEFRAME,$END)
$END=tf_current_end($TIMEFRAME)

Table 195 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

Use tf_current_end/2 to obtain the end time of the current active interval of time frame
$TIMEFRAME in $END.

A 0 value is returned if the indicated time frame is not active.

tf_current_end/2 example

$END = tf_current_end($TF);

tf_current_end/3 — obtain the end time of the active


interval of a time frame at a specified time

tf_current_end($TIMEFRAME,$TIME,$END)
$END=tf_current_end($TIMEFRAME,$TIME)

Table 196 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

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.

tf_current_end/3 example

$END = tf_current_end($TF,$TM);

Appendix B Master Rule Language (MRL) reference 259


Time frame operations

tf_current_interval/2 — obtain the start and end time of


the current active interval of a time frame

tf_current_interval($TIMEFRAME,$INTV)
$INTV=tf_current_interval($TIMEFRAME)

Table 197 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

Use tf_current_interval/2 to obtain the start and end time of the current active interval
of time frame $TIMEFRAME in $INTV.

Argument $INTV of the primitive must be specified as a list of two variables.

A [0,0] value is returned if the indicated time frame is not active.

tf_current_interval/2 example

tf_current_interval($TF,[$START,$END]);

tf_current_interval/3 — obtain the start and end time of


the active interval of a time frame at a given time

tf_current_interval($TIMEFRAME,$TIME,$INTV)
$INTV=tf_current_interval($TIMEFRAME,$TIME)

Table 198 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

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.

260 BMC Impact Solutions: Knowledge Base Development Reference Guide


Time frame operations

tf_current_interval/3 example

tf_current_interval($TF,$TM,[$START,$END]);

tf_prev_start/2 — obtain the start time of the previous


active interval of a time frame

tf_prev_start($TIMEFRAME,$START)
$START=tf_prev_start($TIMEFRAME)

Table 199 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

Use tf_prev_start/2 to obtain the start time of the previous active interval of time frame
$TIMEFRAME in $START.

A 0 value is returned if there is no previous active time frame.

tf_prev_start/2 example

$START = tf_prev_start($TF);

tf_prev_start/3 — obtain the start time of the previous


active interval of a time frame at a given time

tf_prev_start($TIMEFRAME,$TIME,$START)
$START=tf_prev_start($TIMEFRAME,$TIME)

Table 200 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

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.

Appendix B Master Rule Language (MRL) reference 261


Time frame operations

tf_prev_start/3 example

$START = tf_prev_start($TF,$TM);

tf_prev_end/2 — obtain the end time of the previous active


interval of a time frame

tf_prev_end($TIMEFRAME,$END)
$END=tf_prev_end($TIMEFRAME)

Table 201 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

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.

tf_prev_end/2 example

$END = tf_prev_end($TF);

tf_prev_end/3 — obtain the end time of the previous active


interval of a time frame at a given time

tf_prev_end($TIMEFRAME,$TIME,$END)
$END=tf_prev_end($TIMEFRAME,$TIME)

Table 202 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

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.

262 BMC Impact Solutions: Knowledge Base Development Reference Guide


Time frame operations

tf_prev_end/3 example

$END = tf_prev_end($TF,$TM);

tf_prev_interval/2 — obtain the start and end time of the


previous active interval of a time frame

tf_prev_interval($TIMEFRAME,$INTV)
$INTV=tf_prev_interval($TIMEFRAME)

Table 203 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

Use tf_prev_interval/2 to obtain the start and end time of the previous 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 previous active time frame.

tf_prev_interval/2 example

tf_prev_interval($TF,[$START,$END]);

tf_prev_interval/3 — obtain the start and end time of the


previous active interval of a time frame at a specified time

tf_prev_interval($TIMEFRAME,$TIME,$INTV)
$INTV=tf_prev_interval($TIMEFRAME,$TIME)

Table 204 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

Appendix B Master Rule Language (MRL) reference 263


Time frame operations

Use tf_prev_interval/3 to obtain the start and end time of the previous active interval at
$TIME of time frame $TIMEFRAME in $END.

Argument $INTV of the primitive, has to be specified as a list of two variables.

A [0,0] value is returned if there is no previous active time frame at the given time.

tf_prev_interval/3 example

tf_prev_interval($TF,$TM,[$START,$END]);

tf_next_start/2 — obtain the start time of the next active


interval of a time frame

tf_next_start($TIMEFRAME,$START)
$START=tf_next_start($TIMEFRAME)

Table 205 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

Use tf_next_start/2 to obtain the start time of the next active interval of time frame
$TIMEFRAME in $START.

A 0 value is returned if there is no next active time frame.

tf_next_start/2 example

$START = tf_next_start($TF);

tf_next_start/3 — obtain the start time of the next active


interval of a time frame at a given time

tf_next_start($TIMEFRAME,$TIME,$START)
$START=tf_next_start($TIMEFRAME,$TIME)

264 BMC Impact Solutions: Knowledge Base Development Reference Guide


Time frame operations

Table 206 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

Use tf_prev_start/3 to obtain the start time of the next active interval at $TIME of time
frame $TIMEFRAME in $START.

A 0 value is returned if there is no next active time frame at the given time.

tf_prev_start/3 example

$START = tf_next_start($TF,$TM);

tf_next_end/2 — obtain the end time of the next active


interval of a time frame

tf_next_end($TIMEFRAME,$END)
$END=tf_next_end($TIMEFRAME)

Table 207 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

Use tf_next_end/2 to obtain the end time of the next active interval of time frame
$TIMEFRAME in $END.

A 0 value is returned if there is no next active time frame.

tf_next_end/2 example

$END = tf_next_end($TF);

tf_next_end/3 — obtain the end time of the next active


interval of a time frame at a specified time

tf_next_end($TIMEFRAME,$TIME,$END)
$END=tf_next_end($TIMEFRAME,$TIME)

Appendix B Master Rule Language (MRL) reference 265


Time frame operations

Table 208 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

Use tf_next_end/3 to obtain the end time of the next active interval at $TIME, of time
frame $TIMEFRAME in $END.

A 0 value is returned if there is no next active time frame at the given time.

tf_next_end/3 example

$END = tf_next_end($TF,$TM);

tf_next_interval/2 — obtain the start and end time of the


next active interval of a time frame

tf_next_interval($TIMEFRAME,$INTV)
$INTV=tf_next_interval($TIMEFRAME)

Table 209 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

Use tf_next_interval/2 to obtain the start and end time of the next active interval of
time frame $TIMEFRAME in $INTV.

Argument $INTV of the primitive, has to be specified as a list of two variables.

A [0,0] value is returned if there is no next active time frame.

tf_next_interval/2 example

tf_next_interval($TF,[$START,$END]);

266 BMC Impact Solutions: Knowledge Base Development Reference Guide


Time frame operations

tf_next_interval/3 — obtain the start and end time of the


next active interval of a time frame at a specified time

tf_next_interval($TIMEFRAME,$TIME,$INTV)
$INTV=tf_next_interval($TIMEFRAME,$TIME)

Table 210 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

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.

tf_next_interval/3 example

tf_next_interval($TF,$TM,[$START,$END]);

tf_duration/3 — calculate the duration of all active


intervals of a time frame from a specified start time to the
current time

tf_duration($TIMEFRAME,$START,$DURATION)
$DURATION=tf_duration($TIMEFRAME,$START)

Table 211 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

Appendix B Master Rule Language (MRL) reference 267


Object creation and deletion

Use tf_duration/3 to calculate the total duration in $DURATION of all active intervals of
time frame $TIMEFRAME over the period starting at $START and ending at the current
time.

tf_duration/3 example

$DURATION = tf_duration($TF,$TM0);

tf_duration/4 — calculate the duration of all active


intervals of a time frame during a specified time period

tf_duration($TIMEFRAME,$START,$END,$DURATION)
$DURATION=tf_duration($TIMEFRAME,$START,$END)

Table 212 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
$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

Use tf_duration/4 to calculate the total duration in $DURATION, of all active intervals of
time frame $TIMEFRAME over the period starting at $START and ending at $END.

tf_duration/4 example

$DURATION = tf_duration($TF,$TM0,$TM1);

Object creation and deletion

generate_event/2 — generate a new event


NOTE
This primitive cannot be used in refine, filter, regulate, or propagate rules.

generate_event($CLASS,$SLOTS)

268 BMC Impact Solutions: Knowledge Base Development Reference Guide


Object creation and deletion

Table 213 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

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.

generate_event/2 example

generate_event(CUSTOM_EVENT,[severity=INFO,msg=$MSG]);

new_data/3 — create a new data object


NOTE
This primitive cannot be used in filter, regulate, or propagate rules.

new_data($OBJECT,$CLASS,$SLOTS)

Table 214 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

Use new_data/3 to generate a new data object $OBJECT of class $CLASS with slot
settings as specified in $SLOTS.

The value of the $SLOTS argument must be a list of elements of the form
SlotName=Value.

A handle for the new data object is returned in $OBJECT.

new_data/3 example

new_data($DATA,CUSTOM_DATA,[mc_udid=$ID,myslot=$VAL]);

Appendix B Master Rule Language (MRL) reference 269


Specific rule-based functions

remove_data/1 — delete a data object


NOTE
This primitive cannot be used in refine, filter, regulate, or propagate rules.

remove_data($OBJECT)

Table 215 remove_data/1 arguments


Argument Mode Type Description
$OBJECT input OBJECT specifies the data object to be deleted

Use remove_data/1 to delete the data object $OBJECT.

remove_data/1 example

remove_data($DATA);

Specific rule-based functions

drop_new/0 — drop a new event object


NOTE
This primitive can only be used in new rules.

drop_new()

Use drop_new/0 to drop the newly received event, being processed in a new rule.

drop_new/0 example

new RepeatTick: MC_CELL_TICK($E)


updates duplicate($U)
{
$U.repeat_count = $U.repeat_count + 1;
drop_new;
}
END

270 BMC Impact Solutions: Knowledge Base Development Reference Guide


Specific rule-based functions

unset_cause/0 — break the cause-to-effect relationship


from a correlate rule
NOTE
This primitive can only be used in correlate rules.

unset_cause()

Use unset_cause/0 to break the cause-to-effect relationship that is established by a


correlate rule.

unset_cause/0 example

correlate Corr1: EVENT($E) where ...


with EVENT($C) where ...
...
when $C.status == CLOSED
{
unset_cause;
}
END

set_timer/3 — set a timer on an event object that will


expire after a specified delay
NOTE
This primitive cannot be used in refine, filter, regulate, or propagate rules.

set_timer($OBJECT,$DURATION,$INFO)

Table 216 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

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.

Appendix B Master Rule Language (MRL) reference 271


Specific rule-based functions

The value of $INFO will be substituted for the timer_info in matching timer rules
when the timer expires.

set_timer/3 example

new TimeoutNew: EVENT($E) where [ $E.mc_timeout > 0 ]


triggers
{
set_timer($E,$E.mc_timeout,EventTimeout);
}
END

timer TimeoutTimer: EVENT($E) where [ $E.status != CLOSED ]


timer_info: == EventTimeout
{
$E.status = CLOSED;
}
END

When a new event is received and its mc_timeout slot is greater than 0, a timer will
be set on the event to expire after that timeout period. The timer rule in the example
will match, because it tests timer_info to ensure that it is equal to EventTimeout.

set_timer_at/3 — set a timer on an event object that will


expire at a specified time
NOTE
This primitive cannot be used in refine, filter, regulate, or propagate rules.

set_timer_at($OBJECT,$TIME,$INFO)

Table 217 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

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.

272 BMC Impact Solutions: Knowledge Base Development Reference Guide


Specific rule-based functions

set_timer_at/3 example

set_timer_at($E,$EXPTM,EventExpired);

set_timer_at/4 — set a timer on an event object that will


expire at a specified time represented by a text string
NOTE
This primitive cannot be used in refine, filter, regulate, or propagate rules.

set_timer_at($OBJECT,$STR,$FORMAT,$INFO)

Table 218 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

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.

This is the same as:

set_timer_at($OBJ,str_to_time_stamp($STR,$FORMAT),$INFO)

set_timer_at/4 example

set_timer_at($E,$DATETIME,’%Y%m%d %H%M%S’,EventExpired);

The variable $DATETIME should contain a time indication similar to 20070209 153010.

Appendix B Master Rule Language (MRL) reference 273


Specific rule-based functions

274 BMC Impact Solutions: Knowledge Base Development Reference Guide


Appendix

C
C Event rules and syntax
This appendix presents the following topics:

Refine rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277


Refine rule processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Refine rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Refine rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Refine rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Filter rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Filter rule processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Filter rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Filter rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Filter rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Regulate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Regulate rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Forms of the Regulate rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Regulate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Regulate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Regulate rule examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
New rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
New rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
New rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
New rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Abstract rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Abstract rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Abstract rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Correlate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Correlate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Correlate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Correlate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Execute rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Execute rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Threshold rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Appendix C Event rules and syntax 275


Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Threshold rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Threshold rule examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Propagate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Propagate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Propagate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Propagate rules examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Timer rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Timer rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Timer rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Timer rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Timer rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Delete rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Delete rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Delete rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Delete rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

276 BMC Impact Solutions: Knowledge Base Development Reference Guide


Refine rules

Refine rules
A Refine rule verifies the validity of incoming events and collects additional data for
an event before it is sent through the remaining rule phases where further processing
takes place. Refine rules collect additional data for an event when

■ 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 33 illustrates how a Refine rule processes incoming events.

Figure 33 Refine rule processing

Incoming Event

Refine Rule
2 (ECFs) 3

No Match Match

event data is event data is


deleted retained

Appendix C Event rules and syntax 277


Refine rule syntax

Refine rule syntax


The syntax for the Refine rule is shown in Figure 34.

Figure 34 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 69.

Figure 35 shows the syntax of an event condition formula (ECF) definition for a
Refine rule.

Figure 35 Refine rule ECF syntax


ClassName Variable
where [Expression CondOperator Expression,
Expression CondOperator Expression]
using | using ALL DataName DataVariable
where [Expression CondOperator Expression,
Expression CondOperator Expression]

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 64.

278 BMC Impact Solutions: 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 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 171.

■ 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 172.

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 162 for more information about rules and their assigned
primitives.

Refine rule examples


In Figure 36, the get_external primitive calls the get_site.sh script to populate the
msg slot of an incoming event with information about a site.

Figure 36 Refine rule example


refine Disk_Full_Contact_Info :
DISK_FULL ($DF)
{
get_external (‘get_site.sh’, [], LOCATION, $LOC);
$DF.msg = $LOC.site ;
}
END

The following is an example BAROC definition for the LOCATION interface.

MC_INTERFACE : LOCATION
DEFINES {
site: STRING ;
phone: STRING ;
}
END

Appendix C Event rules and syntax 279


Filter rules

The following is an example of the standard output from the get_site.sh script.

LOCATION ;
site = ‘B3R123’ ;
phone = ‘x7734’ ;
END

Filter rules
Filter rules limit the number of incoming events by discarding those events that need
no additional processing or analysis. Filter rules compare incoming events to the
event condition formulas (ECFs) contained in the rule to determine if an event is
discarded or proceeds to further processing. An incoming event is processed through
each Filter rule until a Filter rule discards the event, or all Filter rules are exhausted.
An event must match all the Filter rules to be accepted.

Filter rules use the following modes to determine whether an incoming event is
accepted or discarded

■ 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.

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.

280 BMC Impact Solutions: Knowledge Base Development Reference Guide


Filter rule processing

Filter rule processing


Figure 37 illustrates how a Filter rule processes an incoming event.

Figure 37 Filter rule processing

Incoming Event

Filter Rule
2 (ECFs) 3

2a No Match 2b 3a Match 3b

NOPASS Mode PASS Mode NOPASS Mode PASS Mode

event moves to next filter event is discarded event is discarded event moves to the next filter

# 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.

Filter rule syntax


Figure 38 shows the Filter rule syntax.

Figure 38 Filter rule syntax


filter RuleName :
PASS | NOPASS
ECF
ECF
...
END

Appendix C Event rules and syntax 281


Filter rule primitives

Table 219 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 39 is the syntax of an ECF definition included in a Filter rule.

Figure 39 Event condition formula in a filter rule


ClassName Variable
where [Expression Operator Expression,
...,
SlotName: RelationalOperator Value,]

NOTE
Any type of expression can be used in the Where clause.

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 156 for more information about primitives.

282 BMC Impact Solutions: Knowledge Base Development Reference Guide


Filter rule examples

Filter rule examples


In Figure 40 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.

Figure 40 Filter rule example


filter f1 : PASS
EVENT where [ $THIS.mc_host within [svr1,svr2] ]
LOGIN_EVENT
END
filter f2 : NOPASS
EVENT where [ $THIS.severity equals INFO ]
LOGIN_SUCCESS
END

Table 220 demonstrate how specific events are processed by the Filter rules f1 and f2
in the example in Figure 40.

Table 220 f1 and f2 Filter rules event processing examples


Event Example Filter Rule Process Result
LOGIN_SUCCESS; 1. The f1 filter discards the event because The event is discarded.
mc_host=clt1; mc_host does not satisfy the condition.
severity=WARNING;
END 2. The f2 filter discards the event because the
event type is LOGIN_SUCCESS which
matches the condition.
LOGIN_FAILURE; 1. The f1 filter accepts the event because it is a The event is accepted for
mc_host=clt1; login event. additional processing.
severity=WARNING;
END 2. The f2 filter accepts the event because its
severity level is not INFO and it is not a
successful login event.
SERVERS_LOGIN_ATTACK; 1. The f1 filter discards the event because the The event is discarded.
mc_host=svr3; event does not originate from either the svr1
severity=CRITICAL; or svr2 host and is not a login event.
END
2. The f2 filter does not consider the event
because it is discarded by the f1 filter.

Appendix C Event rules and syntax 283


Regulate rules

Regulate rules
Use regulate rules to handle time frequency accumulations of events or repetitive
occurrences of events. An event is considered a repetition of another if the event has
the same values for all the slots that are defined with the dup_detect=yes facet in the
BAROC definition of its event class.

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.

284 BMC Impact Solutions: 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.

NOTE
The event passed from the regulate rule when specifying $FIRST, $LAST, $HISEV or $LOSEV
is not the original event.

It is a clone of the event that allows some timestamps and event_handle to be altered.

If the event_handle has been altered, this can cause an issue when closing an event on cell
B, and you expect the event to be propagated back to cell A to close the event on cell A.

■ In Form 2, when the Hold condition is met, a new event is generated with the rule
defining its class type and its initial slot values.

In this form, an instance of a custom event can be sent. Of course, a valid BAROC
class definition for the custom event must exist in the Knowledge Base. The send
portion is much the same as a BAROC instance for the event, except that the 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 41 shows the Form 1 Regulate rule syntax.

Figure 41 Regulate rule syntax form 1


regulate RuleName :
ECF
hold #Events1 within TimeFrame2
send $FIRST | $LAST | $HISEV | $LOSEV
[ unless #Events3 within TimeFrame4 close ]
END

Figure 42 shows the Form 2 Regulate rule syntax.

Figure 42 Regulate rule syntax Form 2


regulate RuleName :
ECF
hold #Events1 within TimeFrame2
send {

Appendix C Event rules and syntax 285


Regulate rule primitives

Figure 42 Regulate rule syntax Form 2


ClassName ;
SlotName = Value ;
...
}
[ unless #Events3 within TimeFrame4 close ]
END

Figure 43 illustrates the correct syntax for sending a custom event to the next rule
rather then an event from the hold queue, as is the default in a Regulate rule. Before
the custom event can be sent by the rule, it must be defined in a .baroc file in the
Knowledge Base.

Figure 43 Regulate rule syntax to send a custom event


regulate RuleName :
ClassName
where [Expression Operator Expression,
...
SlotName: RelationalOperator Value,]
hold #Events within TimeFrame
send {
ClassName ;
SlotName = Value ;
...
}
[ unless #Events within TimeFrame close ]
END

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 156 for more information about primitives.

Regulate rule examples


The purpose of the Regulate rule in Figure 44 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.

286 BMC Impact Solutions: Knowledge Base Development Reference Guide


Regulate rule examples

Figure 44 Regulate rule example 1


regulate User_Authentication :
LOGIN_FAILURE ($LF)
where [ $LF.user outside [root, Administrator] ]
hold 5 within 1 m
send $FIRST
END

Note the required space between the value and the scale factor (hold 5 within 1 m).

In Figure 45, the Regulate rule monitors the swap space availability and alerts the
administrator of the condition by sending a Repeated_SwapAvail_Low event. The
Unless clause determines whether the frequency of duplicate events decreases. If the
number of SwapAvail events received decreases so that only one SwapAvail event
remains within five minutes, the Repeated_SwapAvail_Low event is closed.

Figure 45 regulate rule example 2


regulate Swap_Availability :
SwapAvail ($SA)
hold 4 within 2 m
send {
Repeated_SwapAvail_Low ;
hostname = $LAST.hostname ;
origin = $LAST.origin ;
msg = ‘Swap space low condition’ ;
}
unless 2 within 5 m close
END

The Regulate rule in Figure 46 assumes that a dynamic data table has been designed
and populated like the example.

Figure 46 Regulate rule example 3


MC_DATA_CLASS :
REGULATE_DATA ISA DATA
DEFINES {
rd_slot_str: STRING, key=yes;
rd_slot_hold: INTEGER;
rd_slot_hwithin: INTEGER;
rd_slot_unless: INTEGER;
rd_slot_uwithin: INTEGER;
};
END

Appendix C Event rules and syntax 287


New rules

The Regulate rule in Figure 47 uses different constants for the regulation of the
SwapAvail_Low event, depending on whether the computer is a production
computer or a research computer. During the evaluation of the Using clause the
appropriate instance is retrieved from the dynamic data tables. If no instance of data
is found by the evaluation of the Using clause, the regulate does not occur.

Figure 47 Regulate rule example 4


regulate dynamic_reg : SwapAvail ($REV)
using REGULATE_DATA ($DATA)
where [ $REV.hostname contains $DATA.rd_slot_str ]
hold $DATA.rd_slot_hold within $DATA.rd_slot_hwithin
send {
Repeated_SwapAvail_Low ;
hostname = $LAST.hostname ;
origin = $LAST.origin ;
msg = ‘Swap space low condition’ ;
}
unless $DATA.rd_slot_unless within $DATA.rd_slot_uwithin
close
END

New rules
Use New rules to execute an action when a new event is received, for example
increasing the severity level for an event or updating an existing event with new
event data. New rules determine if an event becomes permanent and is placed in the
repository.

NOTE
If an event is CLOSED before the New rule phase, a search for a duplicate event is conducted
and, if found, is closed. The new event is dropped and no subsequent rule is evaluated.

This is the default behavior. You can deactivate this behavior by setting the global
configuration parameter EventAutoClose to No in the mcell.conf file. For more information
about this topic see the BMC Impact Solutions: General Administration.

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

288 BMC Impact Solutions: Knowledge Base Development Reference Guide


New rule syntax

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.

New rule syntax


new RuleName :
ECF
triggers
{
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.

Appendix C Event rules and syntax 289


New rule primitives

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 290 for an example on how to use the
drop_new primitive.

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 270 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 162 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.

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

290 BMC Impact Solutions: Knowledge Base Development Reference Guide


New rule examples

In the next example, the New rule contains a Trigger block that is used to always
discard the HOST_UP event.

new UpClosesDown :
HOST_UP($IN_HU)
where [ status: equals OPEN ]
triggers
{
drop_new;
}
updates HOST_DOWN($ORIG_HD)
where [ status: equals OPEN,
hostname: equals $IN_HU.hostname ]
{
$ORIG_HD.status = CLOSED;
}
END

NOTE
The new HOST_UP event is discarded only at the end of the New rule, so the drop_new
primitive can be used anywhere in the Trigger block.

The following New rule illustrates how to use the duplicate keyword to retain an
old event updated while discarding all new events.

new Duplicate_Disk_Used_Percentage:
DISK_USED_PERCENTAGE ($IN_DUP)
updates duplicate($ORG_DUP)
where [ status: not_equals CLOSED ]
{
$ORG_DUP.value = $IN_DUP.value ;
$ORG_DUP.repeat_count = $ORG_DUP.repeat_count +
1 ; drop_new ;
}
END

The New rule searches the repository for another DISK_USED_PERCENTAGE event. If
one is found, it is 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.

Appendix C Event rules and syntax 291


New rule examples

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.

In this example, the developer creates the data class definition to hold the up-down
pairs, as well as the maximum time interval used to correlate the “up” event with the
“down” event:

MC_DATA_CLASS: CLOSE_RELATION ISA DATA


DEFINES {
class_close: STRING, key=yes ; #eg host_down
class_up: STRING ; #eg host_up
interval: INTEGER, default=60 ;
};
END

Once the data class structure is defined, the developer creates the data instances
necessary to cover the “up closes down” relationships.

Close_Relation ;
class_close= “HOST_DOWN” ;
class_up= “HOST_UP” ;
interval= “10 m” ;
END
Close_Relation ;
class_close= “PROCESS_DOWN” ;
class_up= “PROCESS_UP” ;
interval= “2 m” ;
END
Close_Relation ;
class_close= “LINK_DOWN” ;
class_up= “LINK_UP” ;
interval= “5 m” ;
END

292 BMC Impact Solutions: Knowledge Base Development Reference Guide


Abstract rules

The administrator than creates a generic New rule that looks up all CLOSE_RELATION
instances to determine which “up” event updates all its matching “down” events
found in the interval specified in the instance.

new Up_Closes_Down:
EVENT ($IN_EV)
using {CLOSE_RELATION($CR) where [$CR.class_up == $IN_EV.CLASS]}
updates ALL EVENT($OLD_EV)
where [$OLD_EV.CLASS == $CR.class_close,
$OLD_EV.hostname == $IN_EV.hostname, $OLD_EV.status != CLOSED]
within $CR.interval
{
$OLD_EV.status = CLOSED ;
drop_new ;
}
END

Abstract rules
Abstract rules create high-level, or abstract, events based on low-level events. A new
event starts at the new rules phase, skipping the filter and regulate rules phases. With
Abstract rules, you can keep low-level events with cells in the lower-level of the cell
hierarchy, abstract the data from low-level events into high-level events, and
propagate them to a higher-level cell. A high-level cell in the hierarchy can
consolidate abstract events from several low-level cells and prevent a large number of
abstracted technical events for which no consolidating rules apply.

For example, you can use Abstract rules to generate an abstract event that indicates

■ 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.

Appendix C Event rules and syntax 293


Abstract rule syntax

NOTE
Once an abstract event is created, the relationship cannot be removed.

Abstract rule syntax


Figure 48 is an example of the Abstract rule syntax.

Figure 48 Abstract rule syntax


abstract RuleName :
ClassName (Variable) ##Abstraction
from ClassName (Variable) ##Abstracted From
ECF
setup { ##Abstraction Variable.SlotName = Value ;
Variable.SlotName = Value ;
...
}
when Variable.SlotName: RelationalOperator Value
{
Call ;
Variable.SlotName = Value ;
...
}
...
END

ClassName (Variable) class that the generated, or abstract event, will have
from ClassName class of the original events, that is, those events abstracted from
(Variable)
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.

294 BMC Impact Solutions: Knowledge Base Development Reference Guide


Abstract rule primitives

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 156.
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

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 B, “Master Rule
Language (MRL) reference.”

Appendix C Event rules and syntax 295


Abstract rule examples

Abstract rule examples


In Figure 49 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 49 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

296 BMC Impact Solutions: Knowledge Base Development Reference Guide


Correlate rules

In Figure 50, the Abstract rule creates the APP_MISSING_PROCESS abstraction event
when a PROCESS_DOWN event is received. An abstract event exists if any of the
processes has failed. The setup clause populates the slots for the new abstract event.
The when clauses add and remove processes from the list of down processes as
corresponding events open and close.

Figure 50 Abstract rule example 2


abstract AMP :
APP_MISSING_PROCESSES ($AMP)
from PROCESS_DOWN ($PD)
where [sub_origin: within [process1, process2,
process3] ]
setup {
$AMP.date = $PD.date ;
$AMP.hostname = $PD.hostname ;
$AMP.origin = $PD.origin ;
$AMP.application = “ABC” ;
$AMP.msg = “Processes missing for application abc”;
}
when $PD.status: equals OPEN
{
add_to_list($PD.sub_origin, $AMP.processes) ;
}
when $PD.status: equals CLOSED
{
rem_from_list($PD.sub_origin, $AMP.processes) ;
}
END

Correlate rules
Correlate rules build an effect-to-cause relationship between an event that occurs as a
result of another event. Correlate rules execute whenever a cause or an effect event is
received. The relationship between correlated events can be broken.

When a Correlate rule executes and builds events, the following slot values are
updated inside the cause and effect event

■ mc_cause slot—contains the reference to the cause event


■ mc_effects slot—contains the list of the consequence events

NOTE
The relationship between correlated rules can be broken using the unset_cause primitive.
For more information about the unset_cause primitive, see “Correlate rule primitives” on
page 299.

Appendix C Event rules and syntax 297


Correlate rule syntax

Correlate rule syntax


Figure 51 is an example of the Correlate rule syntax.

Figure 51 Correlate rule syntax


correlate RuleName :
ClassName ($Variable) ## Effect
ECF
with ClassName ($Variable) ## Cause
ECF
within TimeFrame
when Variable.SlotName: RelationalOperator Value
{
Call ;
Variable.SlotName = Value ;
}
with ClassName ($Variable) ## Cause
ECF
within TimeFrame
when Variable.SlotName: RelationalOperator Value
{
Call ;
Variable.SlotName = Value ;
}
...
END

with specifies the attributes for the event

If more than one With clause exists in a rule, the order implies the degree of correlation. For
example, the first With clause has a stronger correlation than the second With clause. If a
correlation already exists for the second With clause and a new event arrives that matches the first
With clause, the correlation is broken with the second With clause and established with the first
With clause.

Note: You can use a With clause to create a correlation within a time frame.
within specifies the maximum time difference, in seconds, between the cause and effect events for them to
be considered as correlated

You can use the s, m, h, and d operators to express time, respectively, in seconds, minutes, hours or
days. The time frame can be an expression although this expression cannot refer to events or data
objects. Only global records are permitted in the time expression.
when are evaluated when either a cause event or an effect event is received as well as when a slot change
has occurred from any of them

298 BMC Impact Solutions: 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 271 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 162 for more information about rules and assigned primitives.

Correlate rule examples


The Correlate rule example in Figure 52 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 52 Correlate rule example 1


correlate App_Down :
APP_DOWN ($AD)
with APP_MISSING_PROCESSES ($AMP)
where [ $AMP.application equals $AD.application ]
within 1 m
when $AMP.status equals OPEN
{
$AMP.severity=CRITICAL ;
}
END

Appendix C Event rules and syntax 299


Correlate rule examples

The Correlate rule example in Figure 53 includes multiple potential causes for a NFS
server not responding.

Figure 53 Correlate rule example 2


correlate nfs_and_hd :
NFS_NO_RESP ($NFS)
with HOST_DOWN ($HD)
where [$HD.hostname equals $NFS.server]
within 10 m
when $HD.status not_equals CLOSED
{
$NFS.severity=INFO ;
}
when $HD.status equals CLOSED
{
reset_default($NFS.severity) ;
unset_cause ;
}
with PROCESS_DOWN($PD)
where [ $PD.hostname equals $NFS.server,
$PD.sub_origin equals nfsd ]
within 10 m
when $PD.status not_equals CLOSED
{
$NFS.severity=INFO ;
}
when $PD.status equals CLOSED
{
reset_default ($NFS.severity) ;
unset_cause ;
}
END

The event examples in Table 221 demonstrate how specific events are processed by
the Correlate rule in Figure 53.

Table 221 Correlate rule event examples


Example Event Event Cause
If an NFS_NO_RESP event and a HOST_DOWN event arrive within ten The HOST_DOWN event is the cause.
minutes of each other the cell correlates the two events. By placing the
HOST_DOWN event in the first With clause, the Correlate rule considers
the HOST_DOWN event to be the most likely cause of the NFS_NO_RESP
event and builds a relationship between the two events, even if events
match in another With clause.
If the cell receives an NFS_NO_RESP event and a PROCESS_DOWN event The PROCESS_DOWN event is the
within ten (10) minutes, and no HOST_DOWN event has entered the cell, cause.
then the Correlate rule builds a relationship between the events.

300 BMC Impact Solutions: Knowledge Base Development Reference Guide


Execute rules

Execute rules
The Execute rule performs a specified action when a slot value has changed in the
repository. The specified action, which is either internal to the cell or running an
external executable, is based on the characteristics of one or more events. The Execute
rule can

■ perform actions on an event


■ format an event message
■ update a global record or slot value
■ generate a new event

Execute rule syntax


Figure 54 is an example of the Execute rule syntax.

Figure 54 Execute rule syntax


execute RuleName :
ECF
when 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.

Appendix C Event rules and syntax 301


Execute rule syntax

The When clause in an Execute rule can also be written as shown in Figure 55. This
form of the When clause executes the action block when the value of the slot changes,
regardless of what the change is.

Figure 55 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.

Environment variables for Execute rules


When creating an executable you can use the environment variables listed in
Table 222 in the executable script or program.

Table 222 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

All slots are passed in the environment in the form of variables (with the same names
as their slot names) containing the slot values.

302 BMC Impact Solutions: 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 B, “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 56 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 56 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

Appendix C Event rules and syntax 303


Threshold rules

In Figure 57 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.

Figure 57 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

Threshold rules
The Threshold rule counts the number of events that matches the criteria you specify,
if the number of these events exceeds the amount allowed within a time frame the
Threshold rule executes.

304 BMC Impact Solutions: Knowledge Base Development Reference Guide


Threshold rule processing

Threshold rule processing


Figure 58 shows how Threshold rule processing occurs.

Figure 58 Threshold rule processing

Incoming Event

Duplicate
2 Event? 3

Added to New queue


queue created

Matches
5 Threshold? 6

rule is executed event is retained


and the queue is in the queue
deleted

# 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.

Appendix C Event rules and syntax 305


Threshold rule syntax

Threshold rule syntax


Figure 59 is an example of the Threshold rule syntax.

Figure 59 Threshold rule syntax


threshold RuleName :
ECF
when 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

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 B, “Master Rule Language (MRL) reference.”

Threshold rule examples


The Threshold rule in Figure 60 generates a TOO_MANY_AUTH_FAILS event when 10
SNMP_AUTHENTICATION_FAILURE events occur within 120 seconds.

Figure 60 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

306 BMC Impact Solutions: Knowledge Base Development Reference Guide


Propagate rules

Propagate rules
Propagate rules forward events to other cells. For example, a Propagate rule can
escalate an event from a lower-level cell to a higher-level cell in an environment.

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.

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.

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 BMC
Impact Solutions: General Administration.

Appendix C Event rules and syntax 307


Propagate rule syntax

Propagate rule syntax

propagate RuleName :
ECF
to CellName | to all
[CellName, ...] | to one_of
[CellName, ...]
when Variable.SlotName CondOperator Value
to CellName | to all
[CellName, ...] | to one_of
[CellName, ...]
when Variable.SlotName CondOperator Value
...
END

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 156 for more information about primitives.

Propagate rules examples


The Propagate rule in Figure 61 sends all APP_DOWN events with a status of CRITICAL
to the cells server1 and server2. The Propagate rule example in Figure 61

■ sends any events originating from a system in the IP address range of


172.16.23.[1-10] to server1

■ sends events to server2 if server1 is unavailable

Figure 61 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 CRITICAL
to one_of [ server1, server2 ]
when $AD.origin ip_matches ‘172.16.23.<10’
END

308 BMC Impact Solutions: Knowledge Base Development Reference Guide


Timer rules

Timer rules
Use Timer rules to create timed triggers to call a rule. Timer rules are evaluated when
a timer expires. Timer rules can be used to

■ 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.

NOTE
Timer rules are maintained even if a cell is restarted. Timer rules that expired when a cell was
stopped execute immediately when the cell is restarted. Timer rules not yet expired execute as
soon as they expire, as if the cell had not restarted.

Timer 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.

Appendix C Event rules and syntax 309


Timer rule syntax

Timer rule syntax


Figure 62 is an example of the Timer rule syntax.

Figure 62 Timer rule syntax


timer RuleName :
ECF
timer_info : RelationalOperator TimerTrigger1
{
Call ;
Variable.SlotName = Value ;
...
}
timer_info : RelationalOperator TimerTrigger2
{
Call ;
Variable.SlotName = Value ;
...
}
...
END

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 B, “Master Rule Language (MRL) reference.”

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 63 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.

310 BMC Impact Solutions: Knowledge Base Development Reference Guide


Delete rules

Figure 63 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

The Timer rule in Figure 64 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 64 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

Delete rules
The purpose of Delete rules is to perform actions before an event is discarded from
the repository, such as a rule that suppresses data that has no meaning without an
event instance. Delete rules are evaluated whenever an event is deleted from the
repository or when events are deleted using the Delete flag in the mposter command.

Appendix C Event rules and syntax 311


Delete rule syntax

Delete rule syntax


Figure 65 shows the Delete rule syntax.

Figure 65 Delete rule syntax


delete RuleName :
ECF
{
Call;
Variable.SlotName = Value;
...
}
END

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 156 for more information about primitives.

Delete rule examples


The Delete rule in Figure 66 removes event data from a dynamic data table when an
event is deleted.

Figure 66 Delete rule example


delete Remove_MyData :
HOST_DOWN($EV)
where [ $EV.status equals ‘OPEN’ ]
using ALL
{
MYDATA($MD) where <records relevant for this event>
}
{
remove_data($MD);
}
END
The definition for the data could be:
MC_DATA_CLASS :
MYDATA ISA DATA
DEFINES {
name : STRING ;
name : INTEGER ;
{
END

312 BMC Impact Solutions: Knowledge Base Development Reference Guide


Appendix

D
D Default rule sets
This appendix presents the following topics:

Event management rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314


bii4p.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
im_internal.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
ips.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
mc_deprecated_filter.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
mc_deprecated_notification.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
mc_deprecated_propagation.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
mc_deprecated_schedules.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
mc_intevt.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
mc_mccs.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
mc_startup.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
mcxp.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Service impact management rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
mc_sm_associate.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
mc_sm_attach.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
mc_sm_elect.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
mc_sm_maintenance.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
mc_sm_shadow.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
mc_sm_slm.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
mc_sm_start.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Appendix D Default rule sets 313


Event management rules

Event management rules


Table 223 lists the MRL files that contain the default event management rule
definitions for BMC Impact Manager.

NOTE
Rule files with the term deprecated in their file name are files that remain in the Knowledge
Base for backward compatibility purposes.

Table 223 Event Management MRL rule definition files


File name Page
bii4p.mrl 314
im_internal.mrl 314
ips.mrl 315
mc_deprecated_filter.mrl 315
mc_deprecated_notification.mrl 315
mc_deprecated_propagation.mrl 316
mc_deprecated_schedules.mrl 317
mc_intevt.mrl 318
mc_mccs.mrl 319
mc_startup.mrl 319
mcxp.mrl 320

bii4p.mrl
The bii4p.mrl file contains rules used by BMC Impact Integration for PATROL 7. For
more information, see the BMC Impact Integration for PATROL Installation and
Configuration Guide.

im_internal.mrl
The im_internal.mrl file contains the generic rules used by policies in BMC Impact
Manager. For more information about policies, see the BMC Impact Solutions: General
Administration.

314 BMC Impact Solutions: Knowledge Base Development Reference Guide


ips.mrl

ips.mrl
The ips.mrl file contains the rules used to monitor the BMC Impact Publishing Server.
For information about enabling monitoring for the Publishing Server, see BMC Impact
Solutions: General Administration.

mc_deprecated_filter.mrl
The filter_using_dynamic_policy rule implements an optional filter based on the
associated DEPRECATED_FILTER_POLICY data instances. With this rule, you can
define simple, dynamic filters by creating instances of DEPRECATED_FILTER_POLICY.
When a new event arrives, if an instance of DEPRECATED_FILTER_POLICY includes all
of the following conditions, the event is filtered out:

■ its class slot value is equal to or is a super-class of an incoming event

■ the severity of the incoming event is in the range defined by its low_severity
and high_severity slots

■ its site_list slot is either the empty list or contains the value of the mc_location
slot of the incoming event

■ its reg_exp_str slot is the empty string or contains a regular expression that
matches the msg slot of the incoming event

This data filter policy mechanism is inactive by default. To enable it, you must set the
EM_KB_OPTIONS.dfilter_enabled record slot value to YES.

mc_deprecated_notification.mrl
The notify_using_dynamic_policy rule implements an optional notification
mechanism based on DEPRECATED_NOTIFICATION_POLICY data instances. With this
rule, you can dynamically define notification actions by creating instances of
DEPRECATED_NOTIFICATION_POLICY. When a new event comes in, if there is an
instance of DEPRECATED_NOTIFICATION_POLICY that meets the following criteria, a
notification is executed:

■ its class slot value is equal to or a super-class of an incoming event

■ the severity of the incoming event is in the range defined by its low_severity
and high_severity slots

Appendix D Default rule sets 315


mc_deprecated_propagation.mrl

■ its site_list slot value is an empty list or it contains the value of the
mc_location slot of the incoming event

■ its schedule_name slot value is an empty string or its value corresponds to the
schedule_name key slot value of a DEPRECATED_SCHEDULE, and if this latter case
occurs:

— If the sched_invert slot value is NO and the schedule_name value occurs in the
active schedule list ($MC_DEPRECATED_SCHEDULES.active_schedule_list)

or

— If the sched_invert slot value is YES and the schedule_name value is in the
inactive schedule list
($MC_DEPRECATED_SCHEDULES.inactive_schedule_list)

This rule is evaluated only once when the event arrives. Therefore, if an event does
not match when it enters a cell, it will never be notified even if later its severity is
altered so that it matches a DEPRECATED_NOTIFICATION_POLICY instance.

Two notification types are possible: you can send an e-mail or page someone. In case
of e-mail, format the address_list slot of the DEPRECATED_NOTIFICATION_POLICY
instance as EMAIL:<e-mail_address>. In case of a pager notification, format the
address_list slot of the DEPRECATED_NOTIFICATION_POLICY instance as
PAGER:<pager number>.

This data notification policy mechanism is disabled by default. To enable it, set the
EM_KB_OPTIONS.dnotification_enabled record slot to YES. Furthermore, to fully
implement the notification facility, you must adapt the default mc_sendmail and
mc_pager scripts provided in the default distribution (in the EM/kb/bin subtree) to
match the specific environment where the BMC Impact Manager is installed.

mc_deprecated_propagation.mrl
Rule to_policyBasedPropagation implements an optional propagation mechanism
based on DEPRECATED_PROPAGATION_POLICY data instances. With this rule, you can
dynamically define propagation by creating instances of
DEPRECATED_PROPAGATION_POLICY. When a new event comes in and whenever the
severity of an event is changed if there is an instance of
DEPRECATED_PROPAGATION_POLICY such that

■ its class slot value is equal to or a super-class of an incoming event

■ the severity of the incoming event is in the interval defined by its low_severity
and high_severity slots and

316 BMC Impact Solutions: Knowledge Base Development Reference Guide


mc_deprecated_schedules.mrl

■ its site_list slot value is the empty list or contains the value of the mc_location
slot of the incoming event and

■ its schedule_name slot is an empty string or corresponds to the schedule_name


key slot value of a DEPRECATED_SCHEDULE and:

— If the sched_invert slot value is NO and schedule_name value appears in the


active schedule list ($MC_DEPRECATED_SCHEDULES.active_schedule_list)

or

— If the sched_invert slot value is YES and schedule_name value appears in the
inactive schedule list
($MC_DEPRECATED_SCHEDULES.inactive_schedule_list) this event is
forwarded to the destination(s) specified in the policy instance

Three slots in the DEPRECATED_PROPAGATION_POLICY specify the destination cell(s):

■ the dest_cell slot that is either empty or contains one cell name

■ the one_of_dest_cells slot that is either empty or contains a list of cells to which
the event may be sent

■ the all_dest_cells slot that is either empty or contains a list of cell names to
which the event will be propagated

At least one of these slots must contain a value for a propagation to occur.

This data propagation policy mechanism is inactive by default. To enable it, you must
set the EM_KB_OPTIONS.dpropagation_enabled record slot value to YES.

mc_deprecated_schedules.mrl
The schedule mechanism implements schedules. A schedule is a set of weekly
repeated, periods of time. Each schedule is represented by a SCHEDULE data instance
in which a period of time for each day of the week is defined. For more information
about the DEPRECATED_SCHEDULE data class, see the
EM/kb/classes/mc_deprecated_kb_data.baroc file that contains its definition.

The list of currently active/inactive schedules is stored in the global record


MC_DEPRECATED_SCHEDULES. These lists are used by other rule sets such as
notification and propagation. For more information on the
MC_DEPRECATED_SCHEDULES global record, see the
EM/kb/records/mc_rec_deprecated_schedules.baroc file that contains its
definition.

Appendix D Default rule sets 317


mc_intevt.mrl

The active or inactive list of schedules is maintained at every


$MC_DEPRECATED_SCHEDULES.refresh_period MC_CELL_TICK occurrence. By
default, the $MC_DEPRECATED_SCHEDULES.refresh_period value is set to 1 and an
MC_CELL_TICK is generated every 10 minutes (based on a property value setting of
CellTickInterval=600 in the mcell.conf file).

The purpose of the rules in mc_deprecated_schedules.mrl is to maintain these lists.


These rules include

Rule name Description


reset_schedules_record resets the active and inactive schedule lists at the end of the
refresh period
check_all_schedules analyzes each DEPRECATED_SCHEDULE data instance to
determine whether it contains the current time and adds it to
the active or inactive list accordingly at the end of the refresh
period
reset_tick_count resets the tick counter for the next period

mc_intevt.mrl
This file contains the rules that apply only to events that are generated internally by
BMC IM. The rules are of the following types:

■ rules that increment the repeat_count slot of the prior duplicate event and then
drop the newer event. They include

Rule name Applies to internal event class


RepeatTicks MC_CELL_TICK
RepeatDBClean MC_CELL_DB_CLEANUP
StbldStart MC_CELL_STATBLD_START
StbldStop MC_CELL_STATBLD_STOP

■ rules that close old events. They include

Rule name Class of the new event Class of old events to close Conditions
CloseStart MC_CELL_START MC_CELL_START duplicates
CloseStop MC_CELL_STOP MC_CELL_STOP duplicates
UpdateConnect MC_CELL_DISCONNECT MC_CELL_ALLOWED_CONNECT client_location
slots equality
CloseHBFail MC_CELL_HEARTBEAT_ON MC_CELL_HEARTBEAT_FAILURE cell slots equality

318 BMC Impact Solutions: Knowledge Base Development Reference Guide


mc_mccs.mrl

■ The UpdateActionResults rule that sets the severity and status of internal events.
This rule automatically closes an internal event whose exit slot value is 0 and it
sets the severity to MINOR when an internal event’s exit slot value is greater than 0.

mc_mccs.mrl
This file contains two types of rules that apply to events generated by BMC Impact
Manager. The rules are of the following types:

■ rules that increment the repeat_count slot of the prior duplicate event and then
drop the newer event; they include

Rule name Applies to class


RepeatMCCSStart MC_MCCS_START
RepeatMCCSSyncBackup MC_MCCS_SYNC_BACKUP
RepeatMCCSSyncPrimary MC_MCCS_SYNC_PRIMARY

■ rules that close old events; they include

Rule name Class of the new event Class of old events to close Conditions
CloseMCCSStop MC_MCCS_START MC_MCCS_STOP mccs_location slots
equality
CloseMCCSStart MC_MCCS_STOP MC_MCCS_START mccs_location slots
equality
UpdateMCCSSynca MC_MCCS_SYNC_BACKUP MC_MCCS_SYNC_BACKUP $NEW.msg ==
'Synchronization
ended'$OLD.msg ==
'Synchronization began'
a UpdateMCCSSync closes both new and old events when its conditions are satisfied.

mc_startup.mrl
This file contains only the exec_script_at_cell_startup rule that executes the
external startup_script when the cell starts. By default this rule is inactive. To
enable it, you must set the $EM_KB_OPTIONS.startup_script_enabled record slot
value to YES. For more information about the execute primitive, see Appendix B,
“Master Rule Language (MRL) reference.”

Appendix D Default rule sets 319


mcxp.mrl

mcxp.mrl
This file contains the rules defined to support the BMC Impact Integration for
PATROL. For more information, see the BMC Impact Integration for PATROL
Installation and Configuration Guide.

Service impact management rules


The service impact management rule set specifies how raw events relate to service
model components. The cell receives the raw event data and processes it based on the
rules in its Knowledge Base. Through these rules, the status of service model
components can be influenced by the severity value of the raw events originating in a
specific resource. The status of service model components also can be influenced by
the status of other service model components. Status propagation mechanisms that
relate to these relationships are internalized in the cell and do not involve the rule set.
The core service model rule set governs the following activities:

■ associating raw events to components


■ electing associated raw events
■ attaching associated and elected raw events to components

Table 224 lists the MRL files that contain the default service management rule
definitions for BMC Impact Manager.

Table 224 Service Management MRL rule definition files


File name Page
mc_sm_associate.mrl 321
mc_sm_attach.mrl 321
mc_sm_elect.mrl 321
mc_sm_maintenance.mrl 321
mc_sm_shadow.mrl 322
mc_sm_slm.mrl 323
mc_sm_start.mrl 323

For more information about the service model rule sets, see BMC Impact Solutions:
General Administration.

320 BMC Impact Solutions: Knowledge Base Development Reference Guide


mc_sm_associate.mrl

mc_sm_associate.mrl
The mc_sm_associate.mrl file contains a series of Refine rules that accommodate the
way in which events are associated with service components. For information on how
event association works, see BMC Impact Solutions: General Administration.

mc_sm_attach.mrl
These rules use primitives that trigger internal actions, including automatic status
computation for the related component, and impact status propagation from that
component to its dependent component in a recursive process.

Only raw events that are associated with a component and are elected can be
manipulated by these rules. Components with which a raw event can be associated
are either ones that already exist or ones that have been created automatically by a
rule.

Rule name Description


attach_detach_event attaches new events which have just been associated and elected
update_component updates the context for a previously attached event whose
severity value has changed

mc_sm_elect.mrl
This file contains only the elect_any_associated_event rule that sets the
mc_smc_impact flag to 1 for any event associated with a component. When set to 1,
the mc_smc_impact flag indicates that the raw event is elected to participate in the
status computation of the component.

mc_sm_maintenance.mrl
The rules contained in the mc_sm_maintenance.mrl file are a complement to the status
control mechanism that supports the maintenance mode within the cell.

These rules are controlled by the following slots

■ maintenance_enabled
■ maint_filter_new_events

Appendix D Default rule sets 321


mc_sm_shadow.mrl

Rule name Description


drop_new_events_if_maint_mode_says_so filters out any incoming event that has been attached to a
(NOPASS) component
set_maintenance_mode changes the maintenance mode for a component when
the value of the maintenance_mode slot for an event is
changed
eliminate_dup_maintenance_event removes duplicate events received during the
maintenance mode

mc_sm_shadow.mrl
The mc_sm_shadow.mrl rule file is system reserved.

The rules in mc_sm_shadow.mrl support the registering, unregistering, update, and


deletion of shadow components.

Rule name Description


handle_shadow_requests processes and MC_SM_SHADOW_REQUEST event
coming from another cell
generate_shadow_requests_failure catches any MC_SM_SHADOW_REQUEST event that
did not obtain a component match in the
handle_shadow_requests rule and generates an
MC_SM_SHADOW_REQUEST_ERROR event
drop_ack_shadow_requests_failure drops all Acknowledged MC_SM_SHADOW_REQUEST
events
propa_state_change_to_shadow_cells propagates any new SMC_STATE_CHANGE event to
all the cells hosting a related shadow component
update_shadow_component updates the status of a local shadow component on
receipt of an MC_SM_SHADOW_UPDATE event
referencing the component logical ID
delete_shadow_component marks a local shadow component for deletion on
receipt of a MC_SM_SHADOW_DELETE event
referencing the component logical ID
delete_shadow_component_failure indicates shadow component to be removed was not
found
attach_status_change_to_shadow_component attaches to a local shadow component an
SMC_STATE_CHANGE event coming from the cell
hosting its master component
handle_shadow_request_failure handles a MC_SM_SHADOW_REQUEST_ERROR event
coming from the cell supposedly hosting the master
component for one of the local shadow components
and marks the later as invalid

322 BMC Impact Solutions: Knowledge Base Development Reference Guide


mc_sm_slm.mrl

mc_sm_slm.mrl
The mc_sm_slm.mrl rule file is system reserved.

mc_sm_start.mrl
The rules in mc_sm_start.mrl control how events are processed when a cell is started
using the mcell -id command.

Rule name Description


close_old_smc_state_change automatically closes the old SMC_STATE_CHANGE
events at cell startup when the cell is started by the
mcell -id command string
reattach_events reattaches the events to their components at cell
startup, when the cell is started by the mcell -id
command

Appendix D Default rule sets 323


mc_sm_start.mrl

324 BMC Impact Solutions: Knowledge Base Development Reference Guide


Appendix

E
E Policy and selector syntax
This appendix presents the following topics:

Event policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326


Event selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Format of event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . 328
How a rule for a policy type is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Appendix E Policy and selector syntax 325


Event policies

Event policies
An event policy provides a mechanism to perform actions against events, much like
rules. However, unlike rules, event policies are created using the policy editors
available from the Administration tab of the BMC Impact Explorer. For instructions
for using these editors and information about out-of-the-box policies, see the
“Implementing event management policies” chapter of the BMC Impact Solutions:
General 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 67.

Figure 67 Policy class syntax


MC_DATA_CLASS: policy_class_name ISA POLICY
DEFINES
{
slot_name: ECF class_name;
slot_name: QUERY class_name;
slot_name: data_type [default=value];
...
}
END

The policy entry defines the actual event selection criteria and data values to be used in
the rule. The syntax for a policy entry is shown in Figure 68.

Figure 68 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

326 BMC Impact Solutions: Knowledge Base Development Reference Guide


Event selectors

The syntax for a policy contained in a rule is shown in Figure 69.

Figure 69 Policy in a rule syntax


RuleType RuleName :
using_policy
{
policy_class_name ($Variable)
where [expression op expression,
...,
expression op expression]
}
END

Event selectors
An event selector, a required component of an event policy, provides a mechanism to
select one or more events to which an event policy can apply. Rather than specifying
an event upon which to perform an action, such as in a rule, a selector allows the
specification of a list of event selection criteria, known as an Event Condition Formula
(ECF). When an incoming event meets any of the specified event selection criteria, the
cell applies the event policy to the event.

The syntax for a selector class is shown in Figure 70.

Figure 70 Selector class syntax


MC_DATA_CLASS: SELECTOR
DEFINES
{
name: STRING;
description: STRING;
based_on: STRING, default=”EVENT”;
ecfs: LIST_OF ECF;
};
END

The syntax for a selector entry is shown in Figure 71.

Figure 71 Selector entry syntax


SELECTOR;
name=string_value;
description=string_value;
based_on=BASE_EVENT_CLASS_NAME;
ecfs=[“EVENT_CLASS_NAME [where clause]”, . . .];
END

Appendix E Policy and selector syntax 327


Event processing rules for policy types

Event processing rules for policy types


This 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:

<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

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).

328 BMC Impact Solutions: 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:

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

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.

Appendix E Policy and selector syntax 329


How a rule for a policy type is processed

330 BMC Impact Solutions: Knowledge Base Development Reference Guide


Appendix

F
F Environment variables
The installation process creates or updates environment variables used by BMC
Impact Solutions.

This appendix presents the following topics:

Microsoft Windows environment variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332


Recreating environment variables on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
UNIX environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Recreating environment variables on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Appendix F Environment variables 331


Microsoft Windows environment variables

Microsoft Windows environment variables


Table 225 lists the Windows environment variables for BMC Impact Solutions.

Table 225 Microsoft Windows environment variables


Environment variable Full path name Default directory
BMC_PORTAL_KIT_HOME %BMC_PORTAL_KIT_HOME% C:\BMCSoftware\BMCPortalKit\

defines the path to BMC Impact


Portal configuration files and
executable files
DATASTORE_HOME %DATASTORE_HOME% C:\BMCSoftware\Datastore

defines the path to the BMC


Datastore files
MCELL_HOME %MCELL_HOME% C:\Program Files\BMC
Software\MasterCell\server
defines the path to BMC Impact
Manager configuration files and
executable files

Recreating environment variables on Windows


An executable is available for backward compatibility and the rare occasion when the
environment variables must be recreated on the same system or a different system.

To recreate the environment variables, run the following script:

..\system32\drivers\etc\mcell\setup_env.bat

332 BMC Impact Solutions: Knowledge Base Development Reference Guide


UNIX environment variables

UNIX environment variables


Table 226 lists the UNIX environment variables for BMC Impact Solutions.

Table 226 UNIX environment variables


Environment variable Full path name Default directory
BMC_PORTAL_KIT_HOME $BMC_PORTAL_KIT_HOME /opt/bmc/BMCPortalKit

defines the path to BMC Impact Portal configuration


files and executable files
DATASTORE_HOME $DATASTORE_HOME /opt/bmc/Datastore

defines the path to the BMC Datastore files


MCELL_HOME $MCELL_HOME /opt/mcell

defines the path to BMC Impact Manager


configuration files and executable files

Recreating environment variables on UNIX


An executable is available for backward compatibility and the rare occasion when the
environment variables must be recreated on the same system or a different system.

To recreate the environment variables, run one of the following scripts:

. /etc/mcell/mcadapter/setup_env.sh
source /etc/mcell/mcadapter/setup_env.csh

Appendix F Environment variables 333


Recreating environment variables on UNIX

334 BMC Impact Solutions: Knowledge Base Development Reference Guide


Appendix

G
G Common Event Model
This appendix describes the different property groupings of the Common Event
Model (CEM), version 1.1.00. It presents the following topics:

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Versioning support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Internationalization compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Mapping quick reference: CEM to BAROC (CORE_EVENT). . . . . . . . . . . . . . . . 338
Guidelines for applying CEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Associating events with configuration items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Root cause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Adding attributes vs. adding generic slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Cross-launching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Event synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Free-format text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
CEM property groupings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Source component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Reporter component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Situation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Metric properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Overview
A Common Event Model (CEM) enables a consistent definition of an event. This
definition specifies the format and the data, both of which each event should contain.
The event should contain the same format and data, regardless of its originating
source.

By mapping all event sources to CEM definitions, you significantly reduce the
overhead of managing and maintaining an event management solution.

Appendix G Common Event Model 335


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

TIP
Events do not always contain all the information that CEM requires. In these instances, you
can “enrich” the event by adding contextual information to it. For example, if a raw event
does not contain a specific slot, you can still add slot-related information to the event through
a data-enrichment process.

BMC intends to make its integrations compatible with the Common Event Model.
BMC recommends that customers building any new integrations be consistent with
the Common Event Model described below.

The Common Event Model (CEM), version 1.1.00, defines the event fields and
formats for the BMC_BaseEvent class, a super class that contains the BMC Impact
Manager cell’s CORE_EVENT class. 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 227 on page 337:

336 BMC Impact Solutions: Knowledge Base Development Reference Guide


Versioning support

Table 227 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.

CEM 1.1.00 supports the following data types:

Table 228 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

Versioning support
CEM 1.1.00 uses the EventModelVersion field (mc_event_model_version slot) to
indicate the class version of the CEM that the event management system uses. If BMC
Impact Manager implements the same CEM version number, of course there is no
compatibility issue. If BMC Impact Manager implements a later CEM version, it
translates the event to the most recent CEM format.

Appendix G Common Event Model 337


Internationalization compatibility

Internationalization compatibility
The CEM 1.1.00 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.

Table 229 CEM to BAROC: Metadata


Required or
CEM property BAROC slot optional New to CORE_EVENT in 7.1?
EventModelVersion mc_event_model_version required yes
EventClass CLASS required no
EventId mc_ueid required no
Status status optional no
ReportTime mc_incident_report_time optional yes
EventToCIAssociationType mc_smc_impact optional no
Timeout mc_timeout optional no
Notes mc_notes optional no
PropagationHistory mc_history required no
RelationSource mc_relation_source required no
Owner mc_owner optional no
Account mc_account optional yes

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 230 CEM to BAROC: source information (part 1 of 2)


CEM property BAROC Slot Required or optional New to CORE_EVENT in 7.1?
ResourceId (source) mc_tool_id optional no
ReconciliationIdentity mc_smc_id recommended no
Alias mc_smc_alias recommended no
ComponentHost mc_host required no
ComponentHostAddress mc_host_address required no
Location mc_location optional no
ComponentURI mc_object_uri optional yes

338 BMC Impact Solutions: Knowledge Base Development Reference Guide


Mapping quick reference: CEM to BAROC (CORE_EVENT)

Table 230 CEM to BAROC: source information (part 2 of 2)


CEM property BAROC Slot Required or optional New to CORE_EVENT in 7.1?
ComponentCaption mc_object recommended no
ComponentType mc_object_class recommended no
ComponentOwner mc_object_owner optional yes

BMC recommends that you use ReconciliationIdentity (mc_smc_id) and Alias


(mc_smc_alias) because they make it easier to track configuration items.

Table 231 CEM to BAROC: reporter information


CEM property BAROC Slot Required or optional New to CORE_EVENT in 7.1?
ResourceId (reporter) mc_tool_id optional no
ComponentHostAddress mc_tool_address required yes
ComponentURI mc_tool_uri optional yes
ComponentCaption mc_tool required no
ComponentType mc_tool_class optional no
EventTime mc_tool_time required yes
EventType mc_tool_rule optional no
EventId mc_tool_key required no
EventSeverity mc_tool_sev optional no
EventSuggestion mc_tool_suggestion optional yes

Table 232 CEM to BAROC: situation information


CEM property BAROC Slot Required or optional New to CORE_EVENT in 7.1?
SituationCategory mc_event_category required The slot is not new, but the
enumeration values are.
See Table 269 on page 353
for more information.
SituationTime mc_incident_time required no
Priority mc_priority optional no
Severity severity required no
Message msg recommended no
Application mc_service optional no
LongMessage mc_long_msg optional no
RepeatCount repeat_count optional no

Appendix G Common Event Model 339


Guidelines for applying CEM

Table 233 CEM to Baroc: metric information


CEM property Baroc Slot Required or optional New to CORE_EVENT in 7.1?
MetricName mc_parameter optional no
MetricValue mc_parameter_value optional no
MetricValueUnit mc_parameter_unit optional yes
MetricThreshold mc_parameter_threshold optional yes

Guidelines for applying CEM


This 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:

1. 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.

2. 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.

340 BMC Impact Solutions: Knowledge Base Development Reference Guide


Root cause

Status computation
You can enable the CEM event to be included in the status computation of the
component represented by the component instance (CI). This process is known as
attaching the event to the CI. To do so, define the
EventInformation::EventToCIAssociationType parameter value appropriately. See
Table 234 on page 341 for a listing of the values.

Table 234 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

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.

Appendix G Common Event Model 341


Cross-launching

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.

NOTE
BMC recommends that you also look at using federated links to perform cross-launching in
the BMC Atrium CMDB. See your BMC Atrium CMDB documentation.

Event synchronization
To synchronize events with a third-party management system, you need to identify
the

■ 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 groupings


This section lists and defines the parameters of the different CEM property
groupings. Each CEM property corresponds to a specific CORE_EVENT slot.

342 BMC Impact Solutions: Knowledge Base Development Reference Guide


General properties

General properties
The general property group contains metadata information about the event.

Table 235 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

Table 236 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 237 EventClass (required)


Property name EventClass
BAROC name CLASS
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
Description be written for the designated event provider.
Data type String
Format Event_ClassName
Example BMC_MVEvent

Table 238 EventId (required) (part 1 of 2)


Property name EventId
BAROC name mc_ueid
globally unique identifier of the event. If the mc_ueid is not defined, then it is
Description automatically generated by the first cell that receives the event.
Data type String

Appendix G Common Event Model 343


General properties

Table 238 EventId (required) (part 2 of 2)


<ProductPrefix><separator><mc_tool_id><separator><mc_tool_key>

Format You can choose which <separator> to use.


Example BPM:BPMPrimary:12345abcd

Table 239 Status (optional)


Property name Status
BAROC name mc_status
Description a specified listing of distinct object states. The default status value is OPEN.
ENUMERATION. The values are

■ OPEN
■ ACK
■ ASSIGNED
■ CLOSED
Data type ■ BLACKOUT
Format Enumeration
Example OPEN

Table 240 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 241 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
Comment this.
Comment that.
Example Comment the other.

344 BMC Impact Solutions: Knowledge Base Development Reference Guide


General properties

Table 242 EventToCIAssociationType (optional)


Property name EventToCIAssociationType
BAROC name mc_smc_impact
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
Description must attach the event to the configuration item to affect its status computation.
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
Data type ■ 2 - the event is not attached to a configuration item
Format integer
Example 0

Table 243 PropagationHistory (required)


Property name PropagationHistory
BAROC name mc_history
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
Description receive the synchronized events back from the cell.
Data type LIST_OF string
Format <gateway_name>:0
Example [BiiOVO1:0]

PropagationHistory is required only if the provider wants to receive its synchronized


events back from the cell.

Table 244 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
<ProductPrefix><separator><mc_tool_id><separator><mc_tool_key>

Format You can choose which <separator> to use.


Example BPM:BPMPrimary:12345abcd

RelationSource is required if the consumer object wants to send or receive updates.

Appendix G Common Event Model 345


Source component properties

Table 245 Owner (optional)


Property name Owner
BAROC name mc_owner
Description current user assigned to the event
Data type string
Format text
Example Pablo

Table 246 Account (optional)


Property name Account
BAROC name mc_account
identification of the account associated with the event. (This slot does not support
Description multitenancy.)
Data type String
Format text
Example Account1

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 247 ResourceId (optional)


Property name ResourceId
BAROC name [for future development]
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
Description reconciliation ID or the alias.
Data type string
Format GUID
Example SJSC_GICT0002.j17rul.00004

Table 248 ReconciliationIdentity (recommended) (part 1 of 2)


Property name ReconciliationIdentity
BAROC name mc_smc_id

346 BMC Impact Solutions: Knowledge Base Development Reference Guide


Source component properties

Table 248 ReconciliationIdentity (recommended) (part 2 of 2)


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
Description be the reconciliation Id value generated by the BMC Atrium CMDB.
Data type string
Format ReconciliationId
Example OS-838310E3AEF4168FC895B883ADC8F7

Table 249 Alias (recommended)


Property name Alias
BAROC name mc_smc_alias
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
Description providers supply this value with the component’s alias value.
Data type String
Format <ProductPrefix>:<GUID>
Example BPM:838310E3AEF4168FC895B883ADC8F7

Table 250 ComponentHost (required)


Property name ComponentHost
BAROC name mc_host
Fully-qualified host name of the system on which the problem occurred. The
Description ComponentHost is required in the ComponentHostAddress is not specified.
Data type String
Format fully qualified domain name
Example opensource.adprod.bmc.com

Table 251 ComponentHostAddress (required)


Property name ComponentHostAddress
BAROC name mc_host_address
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
Description ComponentHost property is not specified.
Data type String
Format IP address/type
Example 192.168.0.100

Appendix G Common Event Model 347


Source component properties

Table 252 Location (optional)


Property name Location
BAROC name mc_location
location at which the source component resides. This slot provides additional
Description contextual information for the event.
Data type String
Format Text
Example SJ1-DC1

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 253 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 254 ComponentCaption (recommended)


Property name ComponentCaption
BAROC name mc_object
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
Description available as a property of the CI data element in SIM.
Data type string
Format text; or the in the CDM, the name format
hou-ex-04.adprod.bmc.com
Example 192.168.0.100:Microsoft Exchange Server

Table 255 ComponentType (recommended) (part 1 of 2)


Property name ComponentType
BAROC name mc_object_class

348 BMC Impact Solutions: Knowledge Base Development Reference Guide


Reporter component properties

Table 255 ComponentType (recommended) (part 2 of 2)


Description identifies the class name of the source component
Data type string
CDM class name. If the CDM class name is unknown, you can use a user-defined
Format categorization of the source component.
Example BMC_ComputerSystem

Table 256 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

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


BMC Impact Manager 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. BMC Impact Manager uses the following optional slots to record event
monitoring information.

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.

Appendix G Common Event Model 349


Reporter component properties

Table 257 Slots for event monitoring information


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
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.

Slots that begin with the mc_origin prefix follow the same format as slots that begin
with mc_tool.

Table 258 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 259 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

Component address properties for reporting


These are component address elements for the reporting component:

Table 260 ComponentURI (optional) (part 1 of 2)


Property name ComponentURI
BAROC name mc_tool_uri
Description address that can be used to cross-launch to the reporter component

350 BMC Impact Solutions: Knowledge Base Development Reference Guide


Reporter component properties

Table 260 ComponentURI (optional) (part 2 of 2)


Data type string
Format URI
Example http://192.168.175.149/ews/index.htm

Table 261 ComponentCaption (required)


Property name ComponentCaption
BAROC name mc_tool
Description object that reports the event
Data type string
Format text
Example HPVOInst1

Table 262 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 263 EventTime (required)


Property name EventTime
BAROC name mc_tool_time
time that the reporter component received the event. This is the reporter time
Description translated into epoch time.
Data type integer
Format coordinated universal time (UTC)
Example 1110637098173

Table 264 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

Appendix G Common Event Model 351


Reporter component properties

Table 265 EventId (required)


Property name EventType
BAROC name mc_tool_key
unique identifier of the event in the Reporter. This identifier is usually the event
Description id assigned to the event by the system that detected the event.
Data type string
Format text
Example 3eb61c54-0806-71db-0009-8948e4720000

Table 266 EventSeverity (optional)


Property name EventSeverity
BAROC name mc_tool_sev
the severity level as defined by the reported component. This severity level does
Description not map to the BEM or BMC SIM severity levels.
Data type string
Format text
Example critical

Table 267 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

352 BMC Impact Solutions: 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 268 SituationCategory (required)


Property name SituationCategory
BAROC name mc_event_category
the Information Technology Infrastructure Library (ITIL) process that the event
Description represents
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
Data type ■ SERVICE_DESK_MANAGEMENT
Format ENUMERATION
Example SLA

Table 269 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.

Appendix G Common Event Model 353


Situation properties

Table 269 Situation category (mc_event_category) values (part 2 of 3)


ITIL category Description
SERVICE_CONTINUITY_ events relating to the Service Continuity Management process. The
MANAGEMENT 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

354 BMC Impact Solutions: Knowledge Base Development Reference Guide


Situation properties

Table 269 Situation category (mc_event_category) values (part 3 of 3)


ITIL category Description
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 270 SituationTime (required)


Property name SituationTime
BAROC name mc_incident_time
time when the event occurred, translated into epoch time to accommodate BMC
Impact Manager requirements

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-
Description related information is as optimal as possible.
Data type integer
Format coordinated universal time (UTC)
Example 1110637098173

Table 271 Priority (optional)


Property name Priority
BAROC name mc_priority
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

Description PRIORITY_1 is the highest priority.


Data type ENUMERATION (MC_PRIORITY)
Format Enumeration
Example PRIORITY_1

Appendix G Common Event Model 355


Situation properties

Table 272 Severity (required)


Property name Severity
BAROC name mc_severity
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
Description ■ CRITICAL
Data type ENUMERATION (MC_SEVERITY)
Format Enumeration
Example Major

Table 273 Message (recommended)


Property name Message
BAROC name mc_message
descriptive text that is part of an event. BMC recommends a terse description of
Description the event content.
Data type string
Format text (Unicode)
Example This component is down.

Table 274 Application (optional)


Property name Application
BAROC name mc_service or mc_application
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
Description would be typically set by “enrichment.”
Data type string
Format text
Example OracleListener

356 BMC Impact Solutions: Knowledge Base Development Reference Guide


Metric properties

Table 275 LongMessage (optional)


Property name LongMessage
BAROC name mc_long_message
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
Description rules.
Data type string
Format text (Unicode)
Example this event is enriched

Table 276 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

Metric properties
Metric properties are optional. However, if you do use the metric definition, you
must include all related metric properties.

Table 277 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 278 MetricValue (optional)


Property name MetricValue
BAROC name mc_parameter_value
Description value of the metric
Data type string
Format Unicode text
Example 80

Appendix G Common Event Model 357


Metric properties

Table 279 MetricValueUnit (optional)


Property name MetricValueUnit
BAROC name mc_parameter_unit
Description unit description of the metric
Data type string
Format Unicode text
Example %

Table 280 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

358 BMC Impact Solutions: 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

Glossary
A
Abstract phase
The event-processing phase in which Abstract rules are evaluated and, if conditions are met,
abstraction events are generated. See also abstraction event.

Abstract rule
An event-processing rule that creates an abstraction event from one or more raw events. See also
abstraction event.

abstracted event
An event that contributes to the creation of an abstraction event. The abstracted event is the
basis for inferring that some condition exists. For example, if a critical subprocess of an
application is down, the application is down. See also abstraction event.

abstraction event
A conceptual or summary event based on other events that are occurring. You cannot
understand the context of an abstraction event by its details. To understand its context, you
must view the relationships between the abstraction event and the events that triggered its
creation in the BMC Impact Explorer Events tab, Relationships window. See also abstracted
event.

Acknowledge
The event operation action that acknowledges the existence of an event. See also local action.

Acknowledged status
The event status that results from an Acknowledge event operation action; it means that an
operator has acknowledged the event's existence.

action
1. Generally, a procedure that is invoked to produce a specific result. It can be a script or a call to
an executable that is invoked automatically in response to an event, or it can be a manual
intervention. Actions can be scheduled or immediately invoked locally or remotely.

2. In BMC Impact Manager, an executable that can be run by a cell. Actions are called in an
Execute rule. Users can request the execution of actions in the BMC Impact Explorer. See also
local action and non-local action.

Glossary 359
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

adapter
A background process that audits data from various sources, evaluates it for specific conditions,
and creates the corresponding events. Adapters also transform event data into the format
understood by BMC Impact Manager.

adapter instance
An instance of an adapter that is defined in the adapter configuration file. The definition is
given a name and specifies an adapter type, such as a log file adapter.

adapter map file


A text file that defines the translation of a message between one event format and another. It is
also known as a .map file.

Administrative View
The BMC Impact Explorer user interface for cell administration. Administrative users can start,
pause, stop, and reconfigure a cell by using this interface. They can also make changes to a cell’s
dynamic data tables. You access this view by clicking the Administration tab in BMC Impact
Explorer.

administrator
The person responsible for administrative tasks within the product.

alias
See service component alias.

annotated data point


A specially marked point on a parameter graph that provides detailed information about a
parameter at a particular moment. The associated data is accessed by double-clicking the data
point, which is represented by a user-specified character.

API
See Application Program Interface (API).

Application Program Interface (API)


A set of externalized functions that allow interaction with an application.

asset
An object instance in the BMC Atrium Configuration Management Database (BMC Atrium
CMDB). There are two types of assets in BMC Atrium CMDB: non-service components, such as
desks and other non-IT physical assets, and service components that participate in the delivery
of enterprise services.

asset inventory
The list of all physical and logical assets that have an identifiable value to the organization or
against which threats and vulnerabilities can be identified and quantified as part of risk
assessment.

360 BMC Impact Solutions: 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

Assign To
The event operation action that assigns the responsibility for an event to an individual.

Assigned status
The event status that indicates that the specified operator is responsible for the event. It results
from the Assign To or the Take Ownership event operation actions.

attribute
A characteristic or property of an object, such as a common-data-model service-model
component class. An attribute may contain a value.

automation
In BMC Impact Explorer, operator responses that have been programmed to occur
automatically when an event is received.

B
BAROC language
Basic Recorder of Objects in C. A structured language used to create and modify class definitions.
A class definition is similar to a structure in the C programming language. The elements in a
BAROC class are called slots.

base class
In programming, a root superclass, a class from which all other classes of its type are derived.

base priority
A static priority value that is combined with the component's current status to determine the
final self-priority value. Typically, the base priority determines the highest self-priority that a
component will reach when its status become Unavailable.

blackout schedule
A schedule that determines when one or more components will be automatically placed in a
blackout state.

BMC Atrium CMDB Common Data Model (BMC Atrium CMDB CDM)
An extensible schema that provides a unified representation of configuration items and their
relationships to each other. It is used to store asset data (such as hardware information, service
management information, and people information) and to provide a mechanism for linking that
information to provide a complete view of how all assets are connected and can affect each
other.

BMC Atrium CMDB Reconciliation Engine


The BMC Atrium CMDB application used to merge data from multiple sources, such as
topology discovery and configuration discovery, into a consistent dataset.

Glossary 361
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

BMC Atrium Configuration Management Database (BMC Atrium CMDB)


The database application that is the common datastore for asset, configuration management,
and service model data in BMC Business Service Management products. It enables BMC
products to share IT management and monitoring data and perform service management.

BMC Desktop Status Indicator (BMC DSI)


An icon that appears in the desktop system tray of a computer to show the current status of an
object being monitored by BMC Impact Portal. To view the status page of the monitored object,
you double-click the icon.

BMC Event Manager (BMC EM)


A real-time event management product license package that provides event management,
including event collection, correlation, enrichment, and integration. It enables IT operations
staff to focus the proper resources on resolving the most critical events.

BMC EM
See BMC Event Manager (BMC EM).

BMC IDG
See BMC Impact Database Gateway (BMC IDG).

BMC IEA
See BMC Impact Event Adapters (BMC IEA).

BMC IELA
See BMC Impact Event Log Adapter for Windows (BMC IELA).

BMC Impact Database Gateway (BMC IDG)


The interface that enables BMC Impact Manager events to be exported to a relational database.

BMC Impact Event Adapters (BMC IEA)


The adapters that collect log file information, convert it to BMC Impact events, and send the
events to designated BMC Impact Manager instances.

BMC Impact Event Log Adapter for Windows (BMC IELA)


The native Windows platform executable that audits Windows event logs. It runs as a Windows
service and checks for new event log records.

BMC Impact Explorer (BMC IX)


The console with which you can connect to BMC Impact Manager instances, examine the events
stored in them, and perform event and service management activities.

BMC Impact Explorer Server


Obsolete term. See BMC Impact Portal.

362 BMC Impact Solutions: 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

BMC Impact Integration product (BMC II product)


An interface that enables the synchronized flow of events and data between a BMC Impact
Manager instance and another BMC Software product or a specific third-party product.

BMC Impact Manager (BMC IM)


The BMC Impact product that provides automated event and service impact management. It
runs as a service on supported Windows platforms and as a daemon on UNIX platforms, and
can be distributed throughout the networked enterprise and connected in various topologies to
support IT goals.

BMC Impact Manager instance


An installation of the BMC Impact Manager product on a host computer. Compare with cell.

BMC Impact Publishing Server


The BMC Impact Portal service or daemon that obtains the service model from BMC Atrium
CMDB and publishes (distributes) it to the designated service impact management cell or cells.

BMC Impact Portal


The BMC Portal module that you use to monitor the status of business services and their
components.

BMC Impact Reporting


The BMC Impact Solutions component that you use to create and view long-term reports.

BMC Impact Service Model Editor


A graphical editor that you use to develop, maintain, and extend the service model that is stored
in the BMC Atrium Configuration Management Database (BMC Atrium CMDB).

BMC Impact Web Console (BMC IWC)


Obsolete term. See BMC Impact Portal.

BMC IWC
Obsolete term. See BMC Impact Portal.

BMC IX
See BMC Impact Explorer (BMC IX).

BMC IXS
Obsolete term. See BMC Portal.

BMC Portal
A BMC product that consists of the BMC Portal Server (infrastructure) and console modules,
each of which deliver specific Business Service Management (BSM) functionality. The BMC
Impact Portal and BMC Performance Manager Portal are examples of console modules.

BMC Reporting Foundation


The base component on which BMC Software reporting systems and solutions are built.

Glossary 363
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

BMC Service Impact Manager (BMC SIM)


A real-time service impact management product license package that provides technologies for
both service impact and event management. BMC SIM identifies related applications and the
underlying systems and databases of any software or infrastructure component and ties
systems-level monitoring to the supported business services, enabling IT personnel to respond
quickly to problems that threaten the delivery of business services.

BMC SIM
See BMC Service Impact Manager (BMC SIM).

BMC_System class
In the BMC Atrium CMDB Common Data Model, the parent class for all system information. In
this class tree, classes representing computer systems, mainframes, application systems, and
virtual systems are defined.

built-in action
An automated, predefined action performed by a system.

business function
A group of business processes that make up a specific function, such as customer support.

business objects
An object defined in the BMC Impact Service Model Editor, published to a BMC Impact
Manager instance, and monitored in BMC Impact Portal. Business objects contribute business
service data for use in status indicators and reports.

business process
A series of related business activities that operate to achieve one or more business objectives in a
measurable way. Typical business processes include receiving orders, marketing services,
delivering services, distributing products, invoicing for services, and accounting for money
received. A business process rarely operates in isolation. It depends on other business processes,
and other business processes, in turn, rely on it. A business process usually relies on several
business functions for support, such as IT and Personnel.

business process decomposition


The identification and cataloging of the business activities and IT resources that combine to
make up a business process. The result of business decomposition is a business process model.

business service
A service that is identifiable by business representatives and supports explicit business
processes that have a clear link to the business’s value chain. Most business services have an
easily identifiable senior business representative, are composed of a number of specific
applications, and rely on the functioning of infrastructure services. For example, the provision
of all logistic components underpinning the sale of consumer goods is a business service. See
also service.

364 BMC Impact Solutions: 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

Business Service Management (BSM)


A dynamic method for connecting key business services to the IT systems that manage them.
BSM enables users to understand and predict how technology changes will affect their business,
and how changes in the business affect the IT infrastructure.

C
cause event
In a sequence of events, the event that is identified as the cause of the other events. See also effect
event.

CDM
See BMC Atrium CMDB Common Data Model (BMC Atrium CMDB CDM).

cell
The event processing engine that collects, processes, and stores events within a BMC Impact
Manager instance. Each cell uses the information in its associated Knowledge Base to identify
the types of events to accept and how to process and distribute them.

child collector
A collector contained within another collector. See also event collector.

class
1. A data storage element. In database terms, it relates to a table in a database or a form in the
Remedy AR System.

2. In BMC Impact Manager, a BAROC-language data structure that defines a type of object used
in BMC Impact Manager. A BAROC class is made up of data fields, called slots, that define its
properties.

3. In BMC Impact Portal: see object class.

CLI command
A command that is issued on the OS command line for automation or immediate execution. For
a complete list of CLI commands, see BMC Impact Solutions: Administration. See also command-
line interface (CLI).

Close
The event operation action that closes an event. If the event was assigned to the current user,
Close sets the status to Closed and shows an Operator Closed entry in the operation history.
Otherwise, Close sets the status to Closed and shows an Override Closed entry in the operation
history.

Closed status
The event status that results from a Close event operation action.

Glossary 365
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

CMDB
See BMC Atrium Configuration Management Database (BMC Atrium CMDB).

collector
See event collector.

collector rule
See event collector rule.

collector set
See event collector set.

command-line interface (CLI)


A user interface in which you issue commands one at a time on a command line for automation
or immediate execution. In BMC Impact Manager, you use the CLI in conjunction with a
graphical user interface (GUI) to operate the product.

component
A logical or physical asset that is represented in BMC Atrium CMDB. There are two types of
assets represented in BMC Atrium CMDB: non-service components, such as desks and other
non-IT physical assets, and service components that participate in the delivery of business
services. See also service component.

component instance
A named component that represents an actual IT resource. See also service component.

component pool
A reference to all of the logical and physical assets that participate in the delivery of enterprise
services and can be part of the service model. The component pool includes both assets that are
part of the service model and assets that are not. See also object and component.

component relationship
See service component relationship.

component type
In the Service Model Editor, an icon with an editable template that represents a specific common
data model component class. A user can select a component type and edit its template to create
a new instance of the component class.

computed priority
See priority.

configuration management database (CMDB)


See BMC Atrium Configuration Management Database (BMC Atrium CMDB).

366 BMC Impact Solutions: 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

console
One of the following commonly BMC Impact Manager product GUIs: BMC Impact Portal, BMC
Impact Explorer, BMC Impact Reporting Console, and Service Model Editor.

console local action


An action taken from a console and that is executed on the console host computer.

consolidation node
A BMC Impact Manager instance that can receive and process events originating from other
systems on the network.

consumer
In a service model component relationship, the component that uses a service provided by
another component, the provider. See also provider.

core competency
Capabilities that collectively account for all business activities within a business enterprise, such
as planning and developing products.

CORE_DATA class
The base class for all BMC Impact Manager BAROC data classes. It is the parent class for all
customized data classes.

CORE_EVENT class
The base class for all BMC Impact Manager event classes. It is the parent class for all customized
event classes.

Correlate phase
The event-processing phase in which the Correlate rules are evaluated to determine whether
any events have a cause-and-effect relationship. See also Correlate rule.

Correlate rule
An event-processing rule that establishes the cause-and-effect relationship between two events.
Correlate rules represent a one-to-one relationship.

correlation
1. The process of identifying a cause-and-effect relationship between two events from one or
more sources for the purpose of identifying a root cause.

2. The cause and effect relationship itself.

3. A type of policy.

Glossary 367
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

D
data class
A BAROC class that is a child of the base data class, CORE_DATA, and that defines a type of data.
Users can create their own data classes.

datastore
A central place in which an aggregation of data is kept and maintained in an organized way.

Decline Ownership
The event operation action that indicates that the assigned operator does not accept
responsibility for an event. Decline Ownership clears the owner’s name, sets the status back to
Acknowledged, and shows a Declined entry in the operation history.

default status view type


In the BMC Impact Portal, one of the view types available from the Status tab.

Delete phase
The event-processing phase in which Delete rules are evaluated and actions are taken to ensure
that data integrity is maintained when an event is deleted from the event repository during the
cleanup process.

Delete rule
An event-processing rule that is used to clean up obsolete information when an event is deleted
from the repository. Delete rules are evaluated when an event is deleted and they take actions to
ensure that data integrity is maintained.

destination
One end of a relationship. In the case of an impact relationship, it is the end associated with the
consumer of events.

draft service model


A working version of the service model that can contain both published and unpublished
elements.

duplicate event
A subsequent occurrence of an event that has already been received, such as the second or later
notification that a component is down. An event that has matching values for all the slots
defined with the dup_detect=yes facet in the event class definition. You can use Regulate rules
to detect and count duplicate events. See also facet.

368 BMC Impact Solutions: 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

During Schedule
Time periods in which a component has a higher service demand and higher importance than in
the off-schedule time period. In a During Schedule time period, the component is typically
assigned a higher priority value and downtime cost than during an off-schedule time period.

For example, if a high service demand occurs during 9:00 AM and 5:00 PM, you can create a
During Schedule timeframe for that time period. See also off-schedule time and Exceptions
Within During Schedule.

During Schedule cost


The outage cost (per second) related to the component when the outage occurs within the
During Schedule timeframe.

dynamic collector
A special type of collector that, in response to events, can add or remove event collectors from
the cell during runtime.

dynamic data
Contextual reference data that is stored in a table in the event repository (mcdb) and that is
updated during runtime if the context has changed. Administrators can use and manipulate
dynamic data in the BMC Impact Explorer Administration View.

E
ECF
See Event Condition Formula (ECF).

effect event
In a sequence of events, the event that is identified as an effect of a cause event. See also cause
event.

elected event
See impact event.

encryption key
The seed encryption key. If the destination product has a key value, all clients must encrypt
their communications using the same key value.

enrichment
1. The process of adding to or modifying the original event data to enhance it for problem
management, service management, correlation, automation, notification, or reporting functions.

2. A type of policy.

Glossary 369
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

escalation
1. The process of referring a problem up the chain of command.

2. A type of policy.

escalation procedure
The particular steps defined for performing escalation. For example, you might specify that
operations personnel would be notified within 5 minutes of a problem occurrence, a manager
would learn of it after 15 minutes, and a director after 1 hour (if the problem still exists).

event
In a BMC Impact environment, a structured message passed to and from cells. Each event is an
instance of an event class.

Event Adapters
See BMC Impact Event Adapters (BMC IEA).

event class
1. A BAROC class that is a child of the base event class, CORE_EVENT, and that defines a type of
event.

2. A category of events that you can create as a child of the base event class, CORE_EVENT,
according to how you want the events to be handled by an event manager and what actions you
want to be taken when the event occurs. Event classes may be inherited from parent objects,
depending on the specific product. Event classes are inherited from parent objects in BMC
Impact Manager.

event collector
An event grouping whose content is defined by its collector rule. Event collectors are displayed
in the BMC Impact Explorer and are defined in the BMC Impact Manager Knowledge Base. See
also event collector rule.

event collector rule


A type of rule in the Knowledge Base that defines how events from a cell are organized and
presented in the BMC Impact Explorer. Collector rules are written in Master Rule Language
(MRL).

event collector set


A group of event collectors, organized in a parent-child hierarchy, that results from progressive
filtering of the incoming events that match the top-level (parent event collector) criteria. A
collector set organizes the events for display in the BMC Impact Explorer.

Event Condition Formula (ECF)


The section of an MRL rule definition that specifies the conditions that an incoming event must
meet to trigger evaluation of the rule during processing. For example: APP_MISSING_PROCESSES
where [hostname: == ‘red1’,sub_origin: contains ‘System’] is an ECF. See Master
Rule Language (MRL).

370 BMC Impact Solutions: 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

event datastore
An archive of generated event data.

event group
A grouping of collectors that depicts the relationship of events through the hierarchy of the
navigation tree. Each level of the collector set is shown as a node under the event group. The
parent level of an event group represents all of the events associated with the collectors. An
event list is associated with the lowest level nodes of an event group. The parent level of an
event group is associated with an image view.

event list
1. A tabular listing of events.

2. In BMC Impact Explorer, you can access the event list from the Events tab.

Event Log Adapter for Windows


See BMC Impact Event Log Adapter for Windows (BMC IELA).

event management
The collection and correlation of events across an enterprise to enable IT operations to focus the
proper resources on the most critical events.

event management policy


One of several generic rule types that perform actions against events that meet selection criteria
specified in an associated event selector. Unlike manually written rules, event policies are
defined interactively using the Event Management Policy Editor in the BMC Impact Explorer.
See also user-defined policy.

event operation history


The tabular display of the operation actions taken against an event in BMC Impact Explorer.
You can access the event operation history from the Operations History tab of the Event Details
pane on the Events tab in BMC Impact Explorer.

event operations
Commands issued by operators to respond to events and correct the problems that the events
represent. Operators perform these commands from an event list in BMC Impact Explorer.

event processor
See cell.

event propagation
The act of forwarding events and maintaining their synchronization among multiple BMC
Impact Manager instances (cells).

Glossary 371
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

event repository
1. An archive of generated event data.

2. In BMC Impact Manager instances (cells), the storage facility (mcdb) in which event
information is stored.

event selection criteria


The syntax of an event selector that specifies the conditions that an incoming event must meet to
trigger selection of the event for rule evaluation during each phase of event processing. You can
specify event selection criteria through the BMC Impact Explorer GUI. An MRL Event
Condition Formula (ECF) also contains event selection criteria. An event selector contains one or
more event selection criteria.

event selector
The filtering mechanism associated with an event policy that selects the events against which
the event policy performs actions. An event selector contains one or more event selection
criteria. Event selectors are defined interactively by using the BMC Impact Explorer. An event
policy can use one or more event selectors.

event source
The monitored IT resource from which source event data is collected, such as an operating
system or application log file.

event timeout
An event timeout policy changes an event status to closed after a specified period of time
elapses.

Events View
The BMC Impact Explorer user interface for viewing and manipulating event data. See also
Services View and Administration View.

Exceptions Within During Schedule


Time periods in a service schedule that are exceptions to the During Schedule timeframe, and in
which a component has a lower service demand and lower importance than in the During
Schedule time period. For example, if you have a During Schedule timeframe of 9:00 AM to 5:00
PM, you can specify the period between 12:00 PM and 1:00 PM as an Exception Within During
Schedule timeframe. The time between 12:00 and 1:00 is treated as Off schedule time, and a
lower priority is associated with the component in that time. See also During Schedule and off-
schedule time.

Exceptions Within During Schedule cost


The outage cost (per second) related to the component when the outage occurs within the
Exceptions Within During Schedule timeframe.

Execute phase
The event-processing phase in which Execute rules are evaluated, and, if conditions are met,
specified actions are performed.

372 BMC Impact Solutions: 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

Execute rule
An event-processing rule that performs actions when an attribute (slot) value changes in the
event repository. Execute rules are evaluated during the Execute phase of event processing.
Often, the resulting actions are internal actions, but you can use the execute primitive in a rule
to call an external executable.

expression
A combination of operators, operands (constants, variables, functions, and primitives), and
conditions that represents a value or a relationship between values.

F
facet
A specific attribute of a BAROC class slot (field) that either controls the values that the slot can
have or controls aspects of a class instance's processing.

field
See attribute.

Filter phase
The event-processing phase in which Filter rules are evaluated to determine which events need
additional processing or are unneeded and can be discarded.

Filter rule
An event-processing rule that determines whether a specific type of event should be passed as it
is, subjected to further processing, or discarded during the Filter phase.

function
Code that executes an operation in a cell and returns a value. A function can be used as an
expression within a rule or a policy and in alias formulas. See also primitive.

G
gateway
See BMC Impact Integration product (BMC II product).

gateway.export file
A special file that controls the propagation and synchronization of events to a BMC Impact
Manager Integration product. The file is in the $MCELL_HOME/etc/ directory on UNIX
platforms and in the %MCELL_HOME\etc\ directory on Windows platforms.

global record
A special BAROC class instance that defines a persistent global variable. When a cell starts, it
creates one instance of each global record defined in the Knowledge Base and restores any
existing values. Global record definitions are stored in the record subdirectory of the cell
Knowledge Base. You can get and set global record values in MRL rules or by using the BMC
Impact Manager CLI mgetrec and msetrec commands.

Glossary 373
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

global slot order


In BMC Impact Explorer, a set of slots (attributes), in a particular order, that is associated with a
filter and is shared among users.

global timeframe
A timeframe that is created in the Service Model Editor and stored in BMC Atrium CMDB. A
global timeframe is usable from within the BMC Impact Service Model Editor and the BMC
Impact Explorer and is available to all cells within an environment. See also local timeframe.

group
A logical or an arbitrary collection of user-defined objects that may or may not have measurable
relationships and may or may not have summary data associated with them.

H
heartbeat
1. A periodic message sent between communicating objects to inform each object that the other
is still active and accessible.

2. In BMC Impact Manager, a dynamic data object sent by a cell to monitor other cells to verify
that they remain active and accessible.

heartbeat interval
The time between heartbeats; the period of the heartbeat.

highest value function


A calculation method that is used to determine impacts priority

I
image view
A graphical and hierarchical display that depicts a business view. You can create image view
objects or elements to represent managed systems (tools), geographic locations, operators, time,
severity levels, categories, and so forth.

impact
An assessed measure of the effect that an incident, fault, or other change will or may have on
business operations or service levels.

impact event
An event whose status is used in computing the status of its associated service component. By
default, the status of each event associated with a service component is used to compute its
status. However, you can exclude events.

374 BMC Impact Solutions: 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

impact production dataset


Instances of an environment that are effectively published to the environment’s impact
managers. The following example is an impact dataset:

BMC.IMPACT.PROD: the impact production dataset associated with the BMC Impact Service
Model Editor

impact propagation
The effect of an impact to a providing service component (provider) on the service components
that use its services (consumers) as defined by an impact relationship. See also impact
relationship.

impact relationship
A relationship between two service components in a service infrastructure in which a consumer
component depends on a provider component to deliver some needed resource to it. A change
in status of the provider affects (has an impact on) the status of the consumer component.

impacted state
The object state that indicates that an object’s functioning is impaired.

impacts priority
The priority of a component based on the self-priorities of components that this component
impacts. So that the remediation process can be aligned with business needs, the computed
priority for each causal component is based upon impacts priority.

The value is the result of the combined priorities of all the other components that are impacted
when the component goes down. The value is dynamic and changes as the self-priorities of the
impacted components change.

import dataset
A dataset that contains objects imported to BMC Atrium CMDB from an external data source
such as BMC Topology Discovery.

inactive relationship
A relationship between two components in a service infrastructure in which there is no impact
to the consumer component. An inactive relationship indicates that the two components are
connected logically and are represented visually as “linked.” See also impact relationship.

in-model
Qualifies a service component as being part of a service model. By default, new components in
BMC Atrium CMDB do not belong to any service model. To change a component to in-model,
you will typically use the BMC Impact Service Model Editor. Impact relationships get
automatically set to in-model when their related components are in-model. Only those that are
in-model can be published to a production cell.

included timeframes
A set of timeframes that are included in the service schedule.

Glossary 375
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
A value that is used by an MRL rule to sort the slot information for an event or data object.

informational alert
An alert of relatively low importance, such as a message about a routine state change. See also
severity.

infrastructure element
An addressable object that can be monitored, such as a managed system in PATROL.

instance
1. A specific object with specific attributes or characteristics that distinguish it from other items
(members) of its class or type.

2. In BMC Impact Manager, an object that has specific attribute values and that was created
using a class definition.

integration product
See BMC Impact Integration product (BMC II product).

interface class
A BAROC class that defines the programming interface used by an MRL rule primitive, such as
get_external, to return data from an external program. At cell startup, an interface class is
loaded into memory. The cell invokes the executable defined in an argument of the primitive.
The executable’s value is returned by the interface.

internal base class


A BAROC internal class that defines the required structure for the base class from which a
group of BMC Impact Manager classes is derived.

internal event
An event that is created by the cell during event processing. An internal event is processed in
the same way as an incoming event. All internal events are processed before any new, incoming
external events are processed.

Internet Protocol (IP) adapter


An adapter that collects and translates events from a Telnet, UDP, or TCP data source.

IP adapter
See Internet Protocol (IP) adapter.

IT component
See BMC_System class.

376 BMC Impact Solutions: 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

K
key slot
A slot whose value is compared during searches.

Knowledge Base (KB)


A collection of information that forms the intelligence of a BMC Impact Manager instance and
enables it to process events and perform service impact management activities. This information
includes event class definitions, service component definitions, record definitions, interface
definitions, collector definitions, data associations, and processing rules.

L
local action
An executable that you can run directly from the BMC Impact Manager. Local actions are
written in XML and are stored in the OS-specific subdirectory of the bin directory of the BMC
Impact Manager cell Knowledge Base.

local timeframe
A timeframe that is created in the BMC Impact Explorer. A local timeframe is stored in a single
cell and is available to the event management policies within the cell. See also global timeframe.

logical component
A non-physical object that represents something that does not exist physically in the IT
infrastructure such as a service, geography, organization, or user group.

M
macro
An executable used in .map files to manipulate the fields used for event translation.

manifest.kb
A central locator file that specifies the locations of the directories that make up a Knowledge
Base. The manifest.kb file is used by the compiler to load the Knowledge Base sources files for
compilation.

map
See image view.

masking
The process of combining an overlay dataset with a standard dataset to obtain a view in which
the standard dataset objects are overlaid or masked by any modified copy contained in the
overlay dataset.

Glossary 377
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

Master Rule Language (MRL)


A compact, declarative language used to define rules and collectors for processing and
organizing events in BMC Impact Manager. Uncompiled rule and collector source files have a
.mrl file extension.

mccomp
The BMC Impact Manager rules compiler. Rules are written in the Master Rule Language
(MRL). The platform-independent compiler converts them to byte code that the cell can read
and process.

mcdb
See event repository.

mcell.conf file
The configuration file that contains configuration options for a BMC Impact Manager instance
(cell). It is in the $MCELL_HOME/etc/ directory on UNIX platforms and in the
%MCELL_HOME%\etc\ directory on supported Windows platforms.

mcell.dir file
The file that lists the cells to which a BMC Impact Solutions product or component can connect
and communicate. The information in each cell includes its name, its encryption key, and its
host name and port number. This file is in the $MCELL_HOME/etc/ directory on UNIX platforms
and in the %MCELL_HOME%\etc\ directory on supported Windows platforms.

mcell.modify file
The file that lists the slots that affect the mc_modification_date slot. When a specified slot is
modified, the time stamp of the modification is reset in the mc_modification_date slot, so that
slot is listed in mcell.modify.

mcell.propagate file
The configuration file that specifies the slot values that are synchronized during event
propagation between BMC Impact Manager instances (cells). It is in the $MCELL_HOME/etc/
directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory on supported
Windows platforms.

mcell.trace file
The configuration file that specifies the trace information about a BMC Impact Manager (cell)
that should be recorded and the location to which it is written. It is in $MCELL_HOME/etc/
directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory on supported
Windows platforms.

mclient.conf file
The configuration file that specifies the configurations for the BMC Impact Manager CLI
commands. It is in the $MCELL_HOME/etc/ directory on UNIX platforms and in the
%MCELL_HOME%\etc\ directory on supported Windows platforms.

378 BMC Impact Solutions: 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

mclient.trace file
The configuration file that specifies the trace information that should be collected for the BMC
Impact Manager CLI commands and the location to which it should be written. This file is in the
$MCELL_HOME/etc/ directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory
on supported Windows platforms.

mcontrol command
The CLI command that sends control commands to a BMC Impact Manager instance (cell).

mc_udid
See universal data identifier (mc_udid).

mean time between failures (MTBF)


The average elapsed time from the point at which an IT service object is made available until the
next occurrence of failure in the same service object.

mean time between system/service incidents (MTBSI)


The average elapsed time between the occurrence of a system or service failure and the next
failure in the same system or service.

mean time to repair (MTTR)


The average elapsed time from the occurrence of an incident to restoration of the service.

metaclass
See internal base class.

MetaCollector
A virtual collector that contains a group of event collectors from multiple BMC Impact Manager
instances. It exists only in the BMC Impact Explorer. You can customize it to suit your
organizational needs.

module
A product that plugs into the BMC Portal.

MTBF
See mean time between failures (MTBF).

MTBSI
See mean time between system/service incidents (MTBSI).

MTTR
See mean time to repair (MTTR).

N
navigation tree
See navigation tree view.

Glossary 379
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

navigation tree view


1. A hierarchical display of the objects and user-defined groups and views.

2. In BMC Impact Explorer, a hierarchical view of defined objects and groups. An object can be a
filter, rule, or event. The groups are arranged to show relationship and dependency between the
managed systems. The navigation tree view appears in the left pane.

3. In the BMC Portal, a hierarchical display of groups defined in a view.

New phase
The event-processing phase in which New rules are evaluated to determine which events in the
repository should be updated with new information from new incoming events.

New rule
An event processing rule that is evaluated during the New event processing phase, and can
update events stored in the repository (mcdb) with fresh information from new incoming
events.

nod