You are on page 1of 278

BMC Impact Solutions Knowledge Base Development Reference Guide

Supporting
BMC Impact Manager 7.3
February 2009

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 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA Telephone 713 918 8800 or 800 841 2031 Fax 713 918 8000

Outside United States and Canada


Telephone (01) 713 918 8800 Fax (01) 713 918 8000

Copyright 2005-2009 BMC Software, Inc. BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. AIX and IBM are registered trademarks of International Business Machines Corporation in the United States, other countries, or both. ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office, and is used here by BMC Software, Inc., under license from and with the permission of OGC. Linux is the registered trademark of Linus Torvalds. Oracle is a registered trademark of Oracle Corporation. Sun, Java, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc., in the U.S. and several other countries. UNIX is the registered trademark of The Open Group in the US and other countries. 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
s s s s s s s s

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

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

s s s

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

BMC Impact Solutions Knowledge Base Development User Guide Update

Contents
Chapter 1 BAROC language fundamentals 17 18 18 18 19 20 21 21 22 23 24 27 28 29 29 29 30 31 32 34 35 41 41 42 43 43 43 44 47 47 48 48 51 BAROC language syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BAROC language symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use of quotation marks in the BAROC language . . . . . . . . . . . . . . . . . . . . . . . . . . . Class definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Metaclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Slot data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Universal event and data identifier slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Slot facets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Internal enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class definition examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class instance definition syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class instance definition example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global record definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global record definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading and compiling BAROC modifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Event and data classes

BMC Impact Manager class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CORE_EVENT base event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EVENT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CELL_CONTROL event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CORE_DATA base class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_SM_DATA data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CALENDARING data class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BEM_MATCH_TABLE data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POLICY data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SELECTOR data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cell information class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deprecated slots and their replacements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 3 Master Rule Language (MRL) reference

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Integer data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Enumeration data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52


Contents 5

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Condition operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Condition operators to test ordering conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Condition operators to test range conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Condition operators to test match conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Condition operators to test conditions on IP addresses . . . . . . . . . . . . . . . . . . . . . . 64 Condition operators to test class hierarchy conditions . . . . . . . . . . . . . . . . . . . . . . 67 Expression operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 MRL functions and primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Primitives and functions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Action-related primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Value type conversion primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Mathematical functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Enumeration operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 String manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Time stamp functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 List operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Match table lookup primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Object slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Specific slot manipulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Object relation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Operation environment inquiry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Propagation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Service model inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 License key functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Time frame operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Object creation and deletion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Specific rule-based functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Chapter 4 Event rules and syntax 193

Refine rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Refine rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Refine rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Refine rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Refine rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Filter rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Filter rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Filter rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Filter rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Filter rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Regulate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Regulate rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Forms of the Regulate rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Regulate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Regulate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Regulate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 New rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 New rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
6 BMC Impact Solutions Knowledge Base Development Reference Guide

New rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . New rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abstract rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abstract rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abstract rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execute rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execute rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Threshold rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Threshold rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Threshold rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Propagate rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Propagate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Propagate rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Propagate rules examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timer rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timer rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timer rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timer rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timer rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delete rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delete rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delete rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delete rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 5 Default rule sets

208 208 211 212 213 214 215 216 217 217 219 219 221 221 222 223 224 224 224 225 226 226 226 227 227 228 228 228 229 230 230 230 231 232 232 232 232 233 233 234 234 234 235 235 236 236 236 237
7

Event management rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bii4p.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . im_internal.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ips.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_intevt.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_mccs.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_startup.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mcxp.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service impact management rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_associate.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_attach.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_elect.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_maintenance.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_shadow.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_slm.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents

mc_sm_start.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Chapter 6 Policy and selector syntax 239

Event policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Event selectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Event processing rules for policy types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 Format of event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . 242 How a rule for a policy type is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 Chapter 7 Common Event Model 245

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Versioning support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Internationalization compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Mapping quick reference: CEM to BAROC (CORE_EVENT) . . . . . . . . . . . . . . . . 248 Guidelines for applying CEM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Associating events with configuration items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Root cause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Adding attributes vs. adding generic slots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Cross-launching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Event synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Free-format text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 CEM property groupings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Source component properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Reporter component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 Situation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Metric properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 Index 269

BMC Impact Solutions Knowledge Base Development Reference Guide

Figures
Enumeration definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Class hierarchy definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Superclass definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Subclass definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Data class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Interface class definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 CORE_EVENT class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 CORE_DATA class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Permitted integer combinations in rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Refine rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Refine rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Refine rule ECF syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Refine rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Filter rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Filter rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Event condition formula in a filter rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Filter rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Regulate rule syntax form 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Regulate rule syntax Form 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Regulate rule syntax to send a custom event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Regulate rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 regulate rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Regulate rule example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Regulate rule example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Abstract rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Abstract rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Correlate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Correlate rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 Correlate rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 When clause in an Execute rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 Execute rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Execute rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Threshold rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Propagate rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Timer rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Figures 9

Timer rule example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Timer rule example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Delete rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 Delete rule example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 Policy class syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Policy entry syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Policy in a rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Selector class syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Selector entry syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

10

BMC Impact Solutions Knowledge Base Development Reference Guide

Tables
BAROC syntax symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Core and metaclass event and data classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Slot facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Knowledge Base class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CORE_EVENT base class slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CELL_CONTROL slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CORE_DATA slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BEM_MATCH_TABLE class attribute (slot) definitions . . . . . . . . . . . . . . . . . . . . . . . . POLICY slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SELECTOR slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CELL_INFO slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deprecated slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deprecated slot substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ==/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . !=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . </2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . <=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . >/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . >=/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . between/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . within/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . outside/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . contains/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . contained_in/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . contains_one_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . has_prefix/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . has_suffix/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . matches/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ip_smaller_or_equals/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ip_greater_or_equals/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ip_matches/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ip_matched_by/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . superclass_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subclass_of/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Alphabetical list of primitives and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . action_requestor/1 syntax argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . action_requestor/2 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . action_requestor/3 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tables

18 20 22 32 35 41 43 44 47 47 48 49 49 52 53 55 56 56 57 57 58 58 59 59 60 61 61 62 62 63 64 65 66 67 67 68 70 77 78 78
11

action_return/2 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 admin_execute/5 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 admin_execute/5 syntax arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 perform/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 perform/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 execute/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 confirm_external/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 get_external/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 inttostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 int_to_hex/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 int_to_hex/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 realtostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 pointertostring/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 string/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 stringtoint/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 stringtoreal/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 stringtopointer/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 int/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 trunc/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 round/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 real/2 or float/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 code/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 char/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 max/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 min/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 sign/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 abs/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 sqrt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 exp/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 pow/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 log/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 log10/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 sin/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 cos/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 tan/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 asin/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 acos/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 atan/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 atan2/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 gcd/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 random/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 incr/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 incr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 incr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 incr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 incr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 incr/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 decr/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 decr/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

12

BMC Impact Solutions Knowledge Base Development Reference Guide

decr2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decr/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decr/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . concat/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strlen/2 and len/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tolowercase/2 and lower/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . touppercase/2 and upper/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strpart/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strnpart/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strextract/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . substring/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . substring/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strip/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strip/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Possible values for the $POS argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strip/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Possible values for the $POS argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strtolist/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strmatch/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . match_regex/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . match_regex/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . match_regex/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sprintf/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mapslots/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mapslots/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_stamp/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_stamp_to_cim/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_stamp_to_str/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_stamp_to_str/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_extract/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . str_to_time_stamp/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listlen/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listgetelt/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listmember/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listdelete/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listappend/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listdisjoint/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listintersect/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listunion/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listsubtract/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listremdup/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listwalk/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . add_to_list/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rem_from_list/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . find_match/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . find_match_entry/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . apply_match_entry/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_list_slotvalues/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

110 111 112 112 113 113 114 115 116 116 117 118 118 119 119 120 120 121 122 122 124 125 127 128 128 129 130 131 132 132 133 134 135 136 136 137 137 138 138 139 140 140 141 141 142 142 145 146 147

Tables

13

set_list_slotvalues/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 class_path/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 reset_default/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 ntadd/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 ntcnt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 ntget/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 ntset/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 opadd/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 opadd/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 opcnt/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 opget/7 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 opget/6 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 opget_time/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 opget_author/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 opget_action/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 opget_args/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 opset/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 opset/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 relate/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 unrelate/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 cellinfo/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 cellcontrol/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 kbversion/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 kbversion/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 get_env/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 send_to/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 send_to/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 send_to_ext/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 smcomps/5 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 key_version/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 key_verify/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 key_verify/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 tf_active/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 tf_active/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 tf_udid_active/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 tf_udid_active/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 tf_current_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 tf_current_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 tf_current_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 tf_current_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 tf_current_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 tf_current_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 tf_prev_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 tf_prev_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 tf_prev_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 tf_prev_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 tf_prev_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 tf_prev_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 tf_next_start/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

14

BMC Impact Solutions Knowledge Base Development Reference Guide

tf_prev_start/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_next_end/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_next_end/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_next_interval/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_next_interval/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_duration/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tf_duration/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . generate_event/2 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . new_data/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remove_data/1 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_timer/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_timer_at/3 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_timer_at/4 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rule syntax descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . f1 and f2 Filter rules event processing examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlate rule event examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Available environment variables in Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Management MRL rule definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Management MRL rule definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Property groupings: BMC_BaseEvent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM to BAROC: Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM to BAROC: source information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM to BAROC: reporter information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM to BAROC: situation information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM to BAROC: metric information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EventInformation::EventToCIAssociationType parameter values . . . . . . . . . . . . . . ReportTime (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EventModelVersion (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EventClass (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EventId (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Status (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timeout (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Notes (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EventToCIAssociationType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PropagationHistory (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RelationSource (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Owner (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Account (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ResourceId (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ReconciliationIdentity (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Alias (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ComponentHost (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ComponentHostAddress (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Location (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ComponentURI (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ComponentCaption (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ComponentType (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ComponentOwner (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

181 182 182 183 183 184 184 185 186 187 189 190 190 200 201 218 220 232 235 247 247 248 248 249 249 249 251 252 253 253 253 253 254 254 254 255 255 255 256 256 256 257 257 257 257 258 258 258 259

Tables

15

Slots for event monitoring information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 ResourceId (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 ComponentHostAddress (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 ComponentURI (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 ComponentCaption (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 ComponentType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 EventTime (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 EventType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 EventId (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 EventSeverity (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 EventSuggestion (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 SituationCategory (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Situation category (mc_event_category) values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 SituationTime (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Priority (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Severity (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Message (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Application (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 LongMessage (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 RepeatCount (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 MetricName (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 MetricValue (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 MetricValueUnit (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 MetricThreshold (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

16

BMC Impact Solutions Knowledge Base Development Reference Guide

Chapter

1
18 18 18 19 20 21 21 22 23 24 27 28 28 29 29 29 30

BAROC language fundamentals


This chapter presents the following topics: BAROC language syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BAROC language symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use of quotation marks in the BAROC language . . . . . . . . . . . . . . . . . . . . . . . . . . . Class definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Metaclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Slot data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Universal event and data identifier slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Slot facets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Internal enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class definition examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class instance definition syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class instance definition syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class instance definition example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global record definition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global record definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading and compiling BAROC modifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 1

BAROC language fundamentals

17

BAROC language syntax

BAROC language syntax


The following syntax rules apply to the BAROC language:
s

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 1 BAROC syntax symbols
Symbol Description or usage Angle brackets enclose an identifier that is a non-terminal symbol that is defined elsewhere in the language definition. A block enclosed in square brackets indicates it is an optional block. The brackets themselves are not language tokens. An asterisk indicates a possible repetition of the preceding block. A plus sign indicates one or more instances of the preceding block. 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.

Symbol name

angle brackets <> square brackets asterisk plus pound [] * + #

NOTE
All other symbols are tokens of the 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:

18

BMC Impact Solutions Knowledge Base Development Reference Guide

Class definition syntax

STRINGString values need to be quoted only when the value starts with a single quote ( ' ) or with a double quote ( " ). You do not need to quote a STRING value

containing a single quote ( ' ) within the value.


s

LIST_OF_STRINGString list items need to be quoted only when the value starts

with a single quote ( ' ) or with a double quote ( " ). Quotation marks must be used if the list includes a comma ( , ) or a bracket ( ] ) because these characters determine the end of string item.

Example
For the value 'this is a test', enter '''this is a test'''. The first double quote indicates that a quoted value is being entered. The first quote should be a double quotation mark because it is a quote character inside a quoted string value.

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

Chapter 1

BAROC language fundamentals

19

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

MC_EV_CLASS MC_DATA_CLASS MC_PUBLISH_DATA_CLASS MC_INTERFACE TEC_CLASS

NOTE
For Tivoli users: the T/EC (Tivoli Enterprise Console) metaclass definitions are built in the cell but their definition is reflected in the mc_root_internal.baroc file.

The syntax for defining event and data classes is essentially the same; however, their core classes and metaclasses differ: Table 2
Class type metaclass base class

Core and metaclass event and data classes


Event MC_EV_CLASS CORE_EVENT Data MC_DATA_CLASS CORE_DATA

20

BMC Impact Solutions Knowledge Base Development Reference Guide

Slot data types

For information about the default event and data class definitions, see Appendix 2, Event and data classes on page 31. 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:
s s s s

INTEGER32-bit signed value REAL64-bit real value STRINGstring, maximum 64 KB EnumNamean enumeration whose definition must appear before the slot

definition in the BAROC declaration file For further information about enumerations, see Enumerations on page 23.

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

Universal event and data identifier slots


The following slots provide unique identifiers for event and data instances:
s s

mc_ueid slotthe universal event identifier mc_udid slotthe universal data class identifier

Chapter 1

BAROC language fundamentals

21

Slot facets

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 instances processing or control the values that a slot can have. For example, the dup_detect facet indicates whether the slot participates in duplicate event detection. Table 3 on page 22 lists the facets available for slot definitions. Table 3
Facet default

Slot facets (part 1 of 2)


Description value assigned to the slot if no value is received from the incoming event If no default facet is specified, zero (0) is the default for an INTEGER and a REAL, the empty string for a STRING and the empty list for a LIST_OF.

22

BMC Impact Solutions Knowledge Base Development Reference Guide

Enumerations

Table 3
Facet

Slot facets (part 2 of 2)


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

dup_detect

hidden parse

flag indicating whether the slot is displayed in the console flag indicating whether the slot is protected against updates by incoming events If the slot value is set by the incoming event, the cell drops the value before processing the event. Slots managed by the system usually have their parse facet set to no.

read_only

flag indicating whether the slot is protected against modification by a command or a rule A slot whose read_only facet is set to yes cannot be modified by a command or a rule. However, the system can modify this slot.

key

allows data tables to be indexed by setting the key facet to yes for one or more slots of the data class definition. Keys must be unique, and if a key is set, the rule engine prevents creation of multiple instances with the same key. When the key facet is equal to yes, it implicitly means the slot is read-only.

representation

indicator specifying how the slot should be displayed by the console For example, a possible value is date.

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

ENUMERATION EnumName [NumVal SymbVal]* END

Chapter 1

BAROC language fundamentals

23

Internal enumerations

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

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

OPEN ACK ASSIGNED CLOSED BLACKOUT

SEVERITY enumeration
The SEVERITY enumeration lists the possible severity values for an event, as follows:
s s s s s s s

UNKNOWN OK INFO WARNING MINOR MAJOR CRITICAL

24

BMC Impact Solutions Knowledge Base Development Reference Guide

Internal enumerations

MC_PRIORITY enumeration
The MC_PRIORITY enumeration lists the possible priority values for an event, as follows. Also, the component attribute priority uses the MC_PRIORITY enumeration values.
s s s s s

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_ MANAGEMENT events relating to the Capacity Management process The process is responsible for ensuring that the capacity of the IT Infrastructure matches the evolving demands of the business in the most cost-effective and timely manner. All events that report on capacity (for example, diskFull) or performance (transactions/sec) are categorized as capacity events. SERVICE_ CONTINUITY_ MANAGEMENT events relating to the Service Continuity Management process The process supports the overall Business Continuity Management process by ensuring that the required IT technical and services facilities (including computer systems, networks, applications, telecommunications, technical support and Service Desk) can be recovered within the required, and agreed upon, business timescales. events relating to the Availability Management process The process supports optimizing the capability of the IT Infrastructure, services and supporting organization to deliver a cost effective and sustained level of availability that enables the business to satisfy its business objectives. All events which report if a component is available or unavailable should be categorized as availability events. INCIDENT_ MANAGEMENT events relating to the Incident Management process The process restores normal service operation as quickly as possible and minimizes the adverse impact on business operations, ensuring that the best possible levels of service quality and availability are maintained.

AVAILABILITY_ MANAGEMENT

Chapter 1

BAROC language fundamentals

25

Internal enumerations

Category CONFIGURATION_ MANAGEMENT

Description events relating to the Configuration Management process The process identifies and defines configuration items in a system, records and reports the status of configuration items and requests for change, and verifies the completeness and correctness of configuration items.

RELEASE_ MANAGEMENT

events relating to the Release Management process The process takes a holistic view of a change to an IT service and ensures that all aspects of release, both technical and non-technical, are considered together.

PROBLEM_ MANAGEMENT

events relating to the Problem Management process The goal of this process is to minimize the adverse impact on the business of incidents and problems that are caused by errors within the IT Infrastructure, and to prevent recurrence of incidents related to these errors. To achieve this goal, Problem Management seeks to get to the root cause of incidents and then initiates actions to improve or correct the situation.

CHANGE_ MANAGEMENT

events relating to the Change Management process This process controls changes to the infrastructure or any aspect of services in a controlled manner, enabling approved changes with minimum disruption.

OPERATIONS_ MANAGEMENT

events relating to the Operational Management process The process is not only concerned with the incidents reported by users, but also with events generated by or recorded by the infrastructure.

SECURITY_ MANAGEMENT

events relating to the Security Management process This process consists of activities that are carried out by Security Management itself or by activities that are controlled by Security Management. Events related to Identity Management as well as events reporting security breaches fall into this category.

FINANCIAL_ MANAGEMENT

events relating to the Financial Management process This process accounts for IT usage by planning, controlling and recovering costs expended by providing the IT services negotiated and agreed to in the SLA.

SERVICE_DESK_ MANAGEMENT

events relating to the Service Desk Management process This process manages the Service Desk.

26

BMC Impact Solutions Knowledge Base Development Reference Guide

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 2, the data class SEVERITY_BY_APP_DOWN assigns specific severities to the appropriate APP_DOWN events: Figure 2 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 3, the SECURITY_EVENT class inherits all of the slots of the EVENT class. Figure 3 Class hierarchy definition example

MC_EV_CLASS : SECURITY_EVENT ISA EVENT; END

In Figure 4, 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 4 Superclass definition example

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

Chapter 1

BAROC language fundamentals

27

Class instance definition syntax

In Figure 5, 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 5 Subclass definition example

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

In Figure 6, 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 6 Data class definition example

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

In Figure 7, the location class is an interface class with a single slot, site. Figure 7 Interface class definition example

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

Class instance definition syntax


Class; [Slot = SlotVal;] * END

28

BMC Impact Solutions Knowledge Base Development Reference Guide

Class instance definition example

The syntax elements are defined as follows:


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

Chapter 1

BAROC language fundamentals

29

Loading and compiling BAROC modifications

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

This form can be used in an expression, an assignment, or a primitive. For information about using global records in rules, see the BMC Impact Solutions Event Management Guide.

Loading and compiling BAROC modifications


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

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 the BMC Impact Solutions Getting Started Guide.

30

BMC Impact Solutions Knowledge Base Development Reference Guide

Chapter

2
32 34 35 41 41 42 43 43 43 44 47 47 48 48

Event and data classes


This chapter 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CORE_EVENT base event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EVENT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CELL_CONTROL event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CORE_DATA base class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_SM_DATA data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC_CALENDARING data class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BEM_MATCH_TABLE data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POLICY data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SELECTOR data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cell information class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deprecated slots and their replacements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2 Event and data classes

31

BMC Impact Manager class files

BMC Impact Manager class files


Table 4 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 4
File name

Default Knowledge Base class files (part 1 of 2)


Description Apache log file adapter class definitions data class for defining match tables For further information, see BEM_MATCH_TABLE data class on page 44.

apache.baroc bem_match_table.baroc

bii4p.baroc ea_event.baroc eventlog.baroc im_policies.baroc ips.baroc

BMC Impact Integration for PATROL 7 class definitions BMC Impact Integration for SmartDBA class definitions event log class definitions the data classes used internally for event management in a BMC Impact Manager event processor generates events for monitoring the BMC Impact Publishing Server To enable generation of Publishing Server monitoring events, see the BMC Impact Solutions Service Modeling and Publishing Guide.

mc_deprecated_filter.baroc mc_deprecated_kb_data.baroc mc_deprecated_notification.baroc mc_deprecated_propagation.baroc mc_evtdata_internal.baroc

FILTER_POLICY class definition deprecated data classes provided in the default KB and supported in the service model in prior releases deprecated notification policy classes for e-mail and paging deprecated event propagation classes BMC internal event and data class definitions Note: The mc_evtdata_internal.baroc file is distributed for information purposes only. Do not load this file into a Knowledge Base.

mc_root_internal.baroc

system core data and event classes Note: The mc_root_internal.baroc file is distributed for information purposes only. Do not load this file into a Knowledge Base.

32

BMC Impact Solutions Knowledge Base Development Reference Guide

BMC Impact Manager class files

Table 4
File name

Default Knowledge Base class files (part 2 of 2)


Description 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_root_redef.baroc

mc_sm_cost.baroc mc_sm_custom.baroc

MC_SM_COST class definition 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 mc_sm_maintenance.baroc mc_sm_notify.baroc mc_sm_object.baroc

SLOT_FORMULAS class definitions SM_MAINTENANCE class definitions client notification registry classes hierarchy with BMC_Base_Element and BMC_Impact subclasses This hierarchy reflects the CMDB CDM class hierarchy.

mc_sm_propagation.baroc mc_sm_root.baroc mc_sm_slm.baroc mc_tec_severity.baroc

MC_SM_PROPAGATION_POLICY class definitions defines the service management internal classes for the integration to the Remedy Service Level Management product enumeration definitions for Tivoli Enterprise Console compatibility Note: By default, the mc_tec_severity.baroc file is not loaded into the Knowledge Base.

mccs.baroc mcxa.baroc mcxp.baroc

defines the events that are generated internally by the Impact Administration Server classes that define mposter and mc-client, the adapter system, and the BMC Impact Event Adapters BMC Impact Integration for PATROL event class definitions and extensions. Note: This class file is for backward compatibility with previous BMC Impact Integration for PATROL releases.

patrol_em.baroc patrol_portal.baroc state_change.baroc

BMC II for PATROL EM integration PEM_EV event class definition BMC Performance Manager integration event class definitions contains the obsolete STATE_CHANGE_EVENT class definition. Note: This class file should be loaded only if the sce_compatibility.mrl rule set is used for backward compatibility with old rules.

Chapter 2 Event and data classes

33

Event class hierarchy

Event class hierarchy


The classes listed in Figure 8 presents the hierarchical relationship between CORE_EVENT and its subclasses. Only high-level classes and sub-classes are listed. Figure 8
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

CORE_EVENT class hierarchy

34

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 cellgenerated events are also populated as specified. Table 5
Slot adapter_host administrator date

CORE_EVENT base class slots (part 1 of 7)


Type STRING STRING STRING Description name of the host where the adapter that sent the event is running identification of the user that last modified the event, as user@host or package:rulename if empty, when entering the cell, it is set as textual format of data_reception, as defined with the parameter DateFormat timestamp as set by the source of the event If not set by the source, on its arrival at a cell, its value is set to the value of incident_time. If there is no incident_time value, its value is set to the mc_arrival_time value.

date_reception

INTEGER represenation = date

duration event_handle mc_abstracted mc_abstraction mc_account mc_acl mc_action_count mc_arrival_time

INTEGER, parse = no INTEGER parse = no LIST_OF INTEGER parse = no LIST_OF INTEGER parse = no STRING LIST OF STRING parse = no INTEGER parse = no

elapsed time, in seconds from event creation to the time the event was closed event identifier in the local cell system reserved system reserved identifies the account associated with the event. controls write and execute access to events when read access is provided by the collector number of actions performed on the event

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 parse = no

system reserved

Chapter 2 Event and data classes

35

CORE_EVENT base event class

Table 5
Slot

CORE_EVENT base class slots (part 2 of 7)


Type LIST_OF STRING Description 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_names

mc_bad_slot_values mc_cause mc_client_address mc_collectors mc_date_modification

LIST_OF STRING INTEGER parse = no STRING parse = no LIST_OF STRING

corresponding values of the bad slots system reserved network address of the host where the adapter that sent the event is running system reserved

INTEGER timestamp of last modification of certain slots representation = date The slots are those mentioned in mcell.modify. LIST_OF INTEGER parse = no MC_EVENT_CATEGORY system reserved high-level normalized category of the object the event represents based on an appropriate Information Technology Infrastructure Library (ITIL) core process denotes the version (<major_version>.<minor_version>.<service_vers ion>) of the event model that instantiates the event. The event model version is required for compatibility purposes. For example, 1.0.00 a list of tuples
s s

mc_effects mc_event_category

mc_event_model_version STRING

mc_event_relations

LIST_OF STRING 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 mc_host mc_host_address LIST_OF STRING STRING STRING system reserved fully-qualified name of the host on which the problem occurred 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.

36

BMC Impact Solutions Knowledge Base Development Reference Guide

CORE_EVENT base event class

Table 5
Slot

CORE_EVENT base class slots (part 3 of 7)


Type STRING Description 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_host_class

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 mc_modhist mc_notes STRING LIST_OF STRING LIST_OF STRING location at which the managed object resides system reserved list of free text annotations added to the event The contents of this slot is implementationdependent. Rules or users should not rely on a particular value in this slot. mc_notification_history LIST_OF STRING mc_object STRING indicates the status of the event with respect to the notification system over time subcomponent of the host to which the event is related For example, it could be the name of the disk on which the event is reporting the problem. 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 mc_object_uri STRING STRING identifies the owner of the source component address used to cross-launch directly to the component

Chapter 2 Event and data classes

37

CORE_EVENT base event class

Table 5
Slot

CORE_EVENT base class slots (part 4 of 7)


Type LIST_OF STRING STRING Description slot containing a list of operation history entries event management systems that is closest to the source of the event as possible For example, if an event originates from an agent, is forwarded to HP OpenView IT/Operations, and is then received by 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_operations mc_origin

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

mc_origin_key

STRING

unique key that the originating tool used to enumerate the event If this is only a two-layer implementation, mc_origin_key might have the same value as the mc_tool_key.

mc_origin_sev

STRING

severity as given by the mc_origin slot If this is only a two-layer implementation, mc_origin_sev might have the same value as mc_tool_sev.

mc_original_priority

MC_PRIORITY

records the original priority of the event upon insertion to the cell, which is needed to determine if an event has been escalated or deescalated records the original severity of the event to determine if the events severity has been modified current user assigned to the event name of the metric or property that went into alarm or that triggered the event actual value of the parameter threshold value that was crossed to cause the generation of the event unit description of the metric

mc_original_severity

SEVERITY

mc_owner mc_parameter mc_parameter_value mc_parameter_threshold mc_parameter_unit

STRING STRING STRING STRING STRING

38

BMC Impact Solutions Knowledge Base Development Reference Guide

CORE_EVENT base event class

Table 5
Slot

CORE_EVENT base class slots (part 5 of 7)


Type MC_PRIORITY default = PRIORITY_5 Description current priority of the event Possible values include s PRIORITY_5 (lowest priority) s PRIORITY_4 s PRIORITY_3 s PRIORITY_2 s PRIORITY_1 (highest priority)

mc_priority

mc_propagations mc_relation_source

LIST_OF STRING parse = no STRING

system reserved the mc_ueid of the source event to which this event is related This slot links a related event to its source event.

mc_service mc_smc_causes mc_smc_effects mc_smc_id mc_smc_impact mc_smc_priority

STRING LIST_OF STRING parse = no LIST_OF STRING parse = no STRING INTEGER default = 0 REAL parse = no

service related to the event obsolete obsolete event is attached to the SIM component with the specified identifier set to 1 if event has an impact on a SIM component prioritizes events with respect to their impact on the SIM model For every event attached to a SIM component, the mc_smc_priority slot for the event is set to the raw_impact_status of the SIM component if all of the following conditions hold true:
s

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 mc_timeout

STRING INTEGER

value is set to the class of the SIM component to which the event is attached event timeout in seconds

Chapter 2 Event and data classes

39

CORE_EVENT base event class

Table 5
Slot mc_tool

CORE_EVENT base class slots (part 6 of 7)


Type STRING Description 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 mc_tool_class

STRING STRING

the network address of the Reporter 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 mc_tool_rule mc_tool_sev mc_tool_suggestion

STRING STRING STRING STRING

unique key used by the sending tool to enumerate the event name of the adapter or integration mapping rule that generated the event severity as given by mc_tool the Reporters suggested solution to the problem posed by the event. This is similar to expert advice information that other applications provide. date and time (as a timestamp) when the event report was created. The ReportTime value must be read as using the time scale Coordinated Universal Time (UTC) unless a particular time zone or the value Z (Zulu time for UTC) is otherwise specified. the address used to cross-launch directly to the Reporter 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.

mc_tool_time

INTEGER

mc_tool_uri mc_ueid

STRING STRING

msg repeat_count

STRING INTEGER

text description of the event number of copies received from this event

40

BMC Impact Solutions Knowledge Base Development Reference Guide

EVENT class

Table 5
Slot severity status

CORE_EVENT base class slots (part 7 of 7)


Type SEVERITY default = WARNING STATUS default = OPEN Description severity value of the event status value of the event

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 6
Slot cell_name cell_location

MC_CELL_CONTROL slot definitions


Type STRING STRING Description name of the cell location information for the cell

Chapter 2 Event and data classes

41

Data class hierarchy

Data class hierarchy


The classes listed in Figure 9 presents the hierarchical relationship between CORE_DATA and its subclasses. Only high-level classes and subclasses are listed. Figure 9
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

CORE_DATA class hierarchy

SELECTOR

42

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 7

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

CORE_DATA slot definitions


Type INTEGER parse = no, read_only = yes STRING read_only = yes INTEGER parse = no, read_only = yes, representation = date INTEGER parse = no, read_only -= yes, representation = date Description data identifier for a local cell

data_handle

mc_udid mc_creation_time

universal data ID creation time

mc_modification_time

modification time

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

Chapter 2 Event and data classes

43

BEM_MATCH_TABLE data class

SCHEDULEthe 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)
s

TIME_FRAMEthe periods of time that the event policy is active TIME_ZONEthe time zone to use as a basis for time display, represented by a coordinated universal time (UTC) offset

For complete information about event policies and local timeframes, see the 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 8
Slot name tag input_match

BEM_MATCH_TABLE class attribute (slot) definitions


Type STRING STRING LIST_OF STRING Description a short description or name of the instance (optional) used to group instances in the match table into subsets according to the tag list of patterns For more information, see BEM_MATCH_TABLE pattern matching on page 45.

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 45 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 45 and BEM_MATCH_TABLE output_expressions references on page 45.

44

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 '*' <pattern> <pattern>* *<pattern> *<pattern>* Matches any string exact pattern strings with prefix pattern strings with suffix 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.

Chapter 2 Event and data classes

45

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

46

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 9
Slot name description enabled

POLICY slot definitions


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

For more information about policies, see Event policies on page 240.

SELECTOR data class


The SELECTOR class is a subclass of the base CORE_DATA class. Table 10 lists the slot definitions for the SELECTOR class and provides an explanation for each slot. Table 10
Slot based_on name description ecfs ecfs_descr

SELECTOR slot definitions


Definition STRING STRING STRING LIST_OF ECF LIST_OF STRING Description event class on which the event policy is based and to which the selector should apply unique name for the event selector; also the mechanism that provides a way to access the selector text description of the event selector 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 text description of the ECFs

For more information about selectors, see Event selectors on page 241.

Chapter 2 Event and data classes

47

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 11
Slot cell_name cell_description cell_release cell_build cell_date service_address service_port alternate_address alternate_port home_dir start_date platform ha_failover ha_duplicate ha_standby

MC_CELL_INFO slot definitions


Type STRING STRING STRING STRING STRING STRING INTEGER STRING INTEGER STRING INTEGER STRING Description name of the cell description of the cell, as specified in the CellDescription parameter indicates the release version of the cell program build number of the cell program build date of the cell program (in textual form) IP address of the cell service port number of the cell service IP address of the alternate cell server of a high availability cell port number of the alternate cell server of a high availability cell cell installation home directory timestamp of when the cell was last started platform on which the cell is running

MC_YESNO indicates that the cell is a high availability cell MC_YESNO indicates that the cell is secondary server of a high availability cell MC_YESNO indicates that cell is in standby mode

Deprecated slots and their replacements


Table 12 on page 49 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.

48

BMC Impact Solutions Knowledge Base Development Reference Guide

Deprecated slots and their replacements

Table 12
acl acl_name

Deprecated slots

Deprecated Slots

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 13 on page 49 lists the slots that can be substituted for a deprecated slot. Table 13 Deprecated slot substitution (part 1 of 2)
Slot substitution Description mc_host HomeCell Icon Name mc_host_address

Deprecated slot description hostname home_cell icon name origin

Chapter 2 Event and data classes

49

Deprecated slots and their replacements

Table 13

Deprecated slot substitution (part 2 of 2)


Slot substitution OwnerName PropagationModel State StatusModel ToolTipSlots mc_object mc_location component_scope The source and sub_source deprecated slots identify the adapter or software the event originates from. The following new slots allow a better identification of the adapter or software:
s s s s

Deprecated slot owner_name propagation_model state status_model tool_tip_slots sub_origin site scope source sub_source

mc_tool_class mc_tool mc_origin_class mc_origin

server_handle acl credibility msg_catalog msg_index num_actions mc_it_mgmt_process

There are no slots that can substitute information for these deprecated slots.

50

BMC Impact Solutions Knowledge Base Development Reference Guide

Chapter

Master Rule Language (MRL) reference


3

This chapter presents the following topics: Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Integer data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Enumeration data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Combination operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Condition operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Expression operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 MRL functions and primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Primitives and functions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Action-related primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Value type conversion primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Enumeration operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 String manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Time stamp functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 List operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Match table lookup primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Object slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Specific slot manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Object relation functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Operation environment inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Service model inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 License key functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Time frame operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Object creation and deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Specific rule-based functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Chapter 3 Master Rule Language (MRL) reference

51

Data types

Data types
Table 14 lists the types of data that can be stored by the cell. Table 14
INTEGER REAL POINTER STRING ENUM

Data types
Default value 0 0 0 (empty string) The first ordinal value that corresponds to the lowest numeric value. a whole number that does not have a fractional part numeric data in form of a decimal fraction a 32-bit value sequence of characters, words, or phrases list of values used as the range of a particular attribute type

Data type Description

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 10
pointer pointer pointer integer pointer pointer = = = = = =

Permitted integer combinations in rules


pointer + integer integer + pointer pointer - integer pointer - pointer max(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.

52

BMC Impact Solutions Knowledge Base Development Reference Guide

Operators

Operators
There are three kinds of operators:
s s s

combination operators, used to combine conditions condition operators, used to specify a condition for expressions expression operators, used in expressions

In the following sections, the description of each operator includes the allowed type(s) of each argument. The argument type is the expected type of the result of evaluating the actual expression passed as argument. The following argument types are used:
STRING INTEGER REAL ENUM ANY LIST_OF T an expression evaluating to a value of type STRING an expression evaluating to a value of type INTEGER an expression evaluating to a value of type REAL an expression evaluating to a value of an enumeration type any simple (non-list) value a list of elements of type T

Combination operators
Combination operators allow you to combine conditions in a logical expression. The result is a logical value. Combination operators can be used in where clauses. There are three logical combination operators, NOT, AND, and OR, listed in order of evaluation: Table 15
NOT c1 c1 AND c2 c1 OR c2

Logical combination operators


specifies logical negation. The expression evaluates to true if c1 evaluates to false. specifies logical conjunction. The expression evaluates to true if both c1 and c2 evaluate to true. specifies logical disjunction. The expression evaluates to true if either c1 or c2 evaluate to true or both c1 and c2 evaluate to true.

Operator syntax Description

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.

Chapter 3 Master Rule Language (MRL) reference

53

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

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 shortcut syntax is discouraged because it is less readable.

When a condition operator is used in a when operator, the argument to the left of the operator must be a slot reference. When the referenced slot changes, the when clause evaluation is triggered. When a condition operator is used in a timer_info clause, the argument to the left of the clause is the timer_info tag.

54

BMC Impact Solutions Knowledge Base Development Reference Guide

Condition operators to test ordering conditions

Condition operator example 1


when $E.status != OPEN

Condition operator example 2


timer_info: == EventTimeout

Condition operators to test ordering conditions


==/2 - equals/2 compare two values for equality
$EXPR1 == $EXPR2 $EXPR1 equals $EXPR2

Table 16
Argument $EXPR1 $EXPR2

==/2 arguments
Type
s s s s

Description expression to the left of the operator expression to the right of the operator

ANY LIST_OF ANY ANY LIST_OF ANY

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

Use

to test for the equality of two expressions $EXPR1 and $EXPR2.

Chapter 3 Master Rule Language (MRL) reference

55

Condition operators to test ordering conditions

==/2 - equals/2 example


$E.status == OPEN

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


$EXPR1 != $EXPR2 $EXPR1 not_equals $EXPR2

Table 17
Argument $EXPR1 $EXPR2

!=/2 arguments
Type
s s s s

Description expression to the left of the operator expression to the right of the operator

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

!=/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 18
Argument $EXPR1 $EXPR2

</2 arguments
Type ANY ANY Description expression to the left of the operator expression to the right of the operator

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

56

BMC Impact Solutions Knowledge Base Development Reference Guide

Condition operators to test ordering conditions

</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 19
Argument $EXPR1 $EXPR2

<=/2 arguments
Type ANY ANY Description expression to the left of the operator expression to the right of the operator

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

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


MAJOR <= $E.severity

>/2 - greater_than/2 determine if one value is greater than another value


$EXPR1 > $EXPR2 $EXPR1 greater_than $EXPR2

Table 20
Argument $EXPR1 $EXPR2

>/2 arguments
Type ANY ANY Description expression to the left of the operator expression to the right of the operator

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

Chapter 3 Master Rule Language (MRL) reference

57

Condition operators to test range conditions

>/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 21
Argument $EXPR1 $EXPR2

>=/2 arguments
Type ANY ANY Description expression to the left of the operator expression to the right of the operator

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

>=/2 - greater_or_equals/2 example


$E.severity >= MAJOR

Condition operators to test range conditions


between/2 determine if one value is between two other values
$EXPR1 between $EXPR2

Table 22
Argument $EXPR1 $EXPR2

between/2 arguments
Type ANY LIST_OF ANY Description expression to the left of the operator expression to the right of the operator

Use between/2 to determine if the value of expression $EXPR1 is between the two values of $EXPR2. The expression $EXPR2 must evaluate to a list of two values.

58

BMC Impact Solutions Knowledge Base Development Reference Guide

Condition operators to test range conditions

If $EXPR2 evaluates to [$VAL1,$VAL2], then the condition $EXPR1 between $EXPR2 is equivalent to: $VAL1 <= $EXPR1 AND $EXPR1 <= $VAL2.

between/2 example
$E.duration between [100,199]

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


$EXPR1 within $EXPR2

Table 23
Argument $EXPR1 $EXPR2

within/2 arguments
Type ANY LIST_OF ANY Description expression to the left of the operator expression to the right of the operator

Use within/2 to determine if the value of expression $EXPR1 is equal to one of the values of $EXPR2. The expression $EXPR2 must evaluate to a list of values.

within/2 example
$E.mc_host within [host1,host2,host3]

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


$EXPR1 outside $EXPR2

Table 24
Argument $EXPR1 $EXPR2

outside/2 arguments
Type ANY LIST_OF ANY Description expression to the left of the operator expression to the right of the operator

Use outside/2 to determine if the value of expression $EXPR1 is not equal to any of the values of $EXPR2. The expression $EXPR2 must evaluate to a list of values.

Chapter 3 Master Rule Language (MRL) reference

59

Condition operators to test match conditions

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 25
Argument $EXPR1 $EXPR2

contains/2 arguments
Type
s s s s s

Description expression to the left of the operator expression to the right of the operator

STRING LIST_OF ANY STRING LIST_OF STRING ANY

Use contains/2 to determine if the value of expression $EXPR1 contains the value of $EXPR2. There are three possible uses of this operator:
s

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.

60

BMC Impact Solutions Knowledge Base Development Reference Guide

Condition operators to test match conditions

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 26
Argument $EXPR1 $EXPR2

contained_in/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator

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

contained_in/2 example
Disk full contained_in $E.msg

contains_one_of/2 determine if one value contains one of a set of values


$EXPR1 contains_one_of $EXPR2

Table 27
Argument $EXPR1 $EXPR2

contains_one_of/2 arguments
Type STRING LIST_OF STRING Description expression to the left of the operator expression to the right of the operator

Use contains_one_of/2 to determine if the value of expression $EXPR1 has at least one of the values in the list $EXPR2 as a substring.

Chapter 3 Master Rule Language (MRL) reference

61

Condition operators to test match conditions

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 28
Argument $EXPR1 $EXPR2

has_prefix/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator

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

has_prefix/2 example
$E.mc_host has_prefix svc_

has_suffix/2 determine if one string has another string as suffix


$EXPR1 has_suffix $EXPR2

Table 29
Argument $EXPR1 $EXPR2

has_suffix/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator

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

62

BMC Impact Solutions Knowledge Base Development Reference Guide

Condition operators to test match conditions

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 30
Argument $EXPR1 $EXPR2

matches/2 arguments
Type
s s s

Description expression to the left of the operator expression to the right of the operator

STRING LIST_OF_STRING STRING

Use matches/2 to determine if the value of expression $EXPR1 matches the pattern $EXPR2. There are two possible uses of this operator:
s

$EXPR1 is a string: matches/2 tests if string $EXPR1 matches the pattern $EXPR2. $EXPR1 is a list of strings: matches/2 tests if at least one string element of $EXPR1 matches the pattern $EXPR2.

The pattern $EXPR2 consists of literal text and value substitutes. Literal text is matched literally. Space characters in the pattern are matched with any number of consecutive spaces. Non-printable or special characters can be specified in the text with escape sequences:
\\ \s \n \r \t \0ddd backslash space (single space) new line carriage return tab character code in octal

A substitute is preceded by a % sign, followed by a type indicator. Between the % and the type indicator, an optional * suppression modifier can be added.

Chapter 3 Master Rule Language (MRL) reference

63

Condition operators to test conditions on IP addresses

Possible substitutes are:


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

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

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

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 31
Argument $EXPR1 $EXPR2

ip_smaller_or_equals/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator

Use ip_smaller_or_equals/2 to determine if the value of expression $EXPR1 is an IP address that is less than or equal to the IP address value of $EXPR2.

64

BMC Impact Solutions Knowledge Base Development Reference Guide

Condition operators to test conditions on IP addresses

If either of the expressions do not evaluate to an IP address in dotted decimal notation, the operator condition fails. The IP addresses are compared as numbers.

ip_smaller_or_equals/2 example
$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.

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 32
Argument $EXPR1 $EXPR2

ip_greater_or_equals/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator

Use ip_greater_or_equals/2 to determine if the value of expression $EXPR1 is an IP address that is greater than or equal to the IP address value of $EXPR2. If either of the expressions do not evaluate to an IP address in dotted decimal notation, the operator condition fails. The IP addresses are compared as numbers.

ip_greater_or_equals/2 example
$E.mc_host_address ip_greater_or_equals 10.1.1.100

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

Chapter 3 Master Rule Language (MRL) reference

65

Condition operators to test conditions on IP addresses

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


$EXPR1 ip_matches $EXPR2

Table 33
Argument $EXPR1 $EXPR2

ip_matches/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator

Use ip_matches/2 to determine if the value of expression $EXPR1 is an IP address that matches the IP address pattern of $EXPR2. An IP address pattern is a sequence of four pattern components separated with dots that correspond to the four components of a dotted decimal IP address. Each component can be one of:

s s s

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.

66

BMC Impact Solutions Knowledge Base Development Reference Guide

> < *

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

Condition operators to test class hierarchy conditions

ip_matched_by/2 determine if an IP address matches an IP address pattern


$EXPR1 ip_matched_by $EXPR2

Table 34
Argument $EXPR1 $EXPR2

ip_matched_by/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator

Use ip_matched_by/2 to determine if the value of expression $EXPR2 is an IP address that matches the IP address pattern of $EXPR1. This is the reverse of ip_matches/2: the condition $EXPR1 ip_matched_by $EXPR2 is equivalent to $EXPR2 ip_matches $EXPR1.

ip_matched_by/2 example
10.1.1.* ip_matched_by $E.mc_host_address

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 35
Argument $EXPR1 $EXPR2

superclass_of/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator

Use superclass_of/2 to determine if the value of expression $EXPR1 is the name of a class that is a superclass of the class name that is the value of $EXPR2. For this operator each class is considered to be a superclass of itself.

Chapter 3 Master Rule Language (MRL) reference

67

Expression operators

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 36
Argument $EXPR1 $EXPR2

subclass_of/2 arguments
Type STRING STRING Description expression to the left of the operator expression to the right of the operator

Use subclass_of/2 to determine if the value of expression $EXPR1 is the name of a class that is a subclass the class name that is the value of $EXPR2. For this operator each class is considered to be a subclass of itself.

subclass_of/2 example
$E.CLASS subclass_of PATROL_EV

Expression operators
Expression operators are mainly arithmetic operators that take numeric values as arguments. There is also one expression operator that takes textual arguments. Results of expression operators are numeric or textual values. They can be reused as arguments in an expression. Logical operators take integer arguments that are interpreted as bit sets. The operation is performed on the bits and the result is interpreted as an integer value. The operators are listed in groups. All operators within the same group are evaluated at the same time, when they appear in an expression without parentheses. Operators from earlier groups are evaluated before operators from later groups.

Example of expression evaluation order


$E1 + $E2 * $E3

68

BMC Impact Solutions Knowledge Base Development Reference Guide

Expression operators

This expression is evaluated as ($E1+($E2*$E3)). The * is evaluated before the +, because the * is in the second group, while the + is in the third group.

Exponentiation and special division operators


Exponentiation and special division operators take two numeric arguments and produce a numeric result.
e1 ^ e2 e1 ** e2 e1 rem e2 e1 mod e2 Value of e1 to the power e2 Value of e1 to the power e2 Remainder of division of e1 by e2 Modulo of division of e1 by e2

Multiplicative operators
Multiplicative operators take two numeric arguments and produce a numeric result.
e1 * e2 e1 / e2 e1 // e2 e1 >> e2 e1 << e2 Value of e1 multiplied by e2 Value of e1 divided by e2 Integer division of e1 by e2 Bitwise right shift of e1 by e2 positions Bitwise left shift of e1 by e2 positions

Additive operators
Additive operators take two numeric arguments and produce a numeric result.
e1 + e2 e1 - e2 e1 /\ e2 e1 \/ e2 e1 xor e2 The sum of e1 and e2 Value of e1 subtracted by e2 Bitwise conjunction (AND) of e1 and e2 Bitwise inclusive disjunction (OR) of e1 and e2 Bitwise exclusive disjunction (XOR) of e1 and e2

Single numeral operators


These operators take a single numeric argument and produce a numeric result.
+ e1 - e1 \ e1 The value e1 The numeric negation of the value e1 The logical or bitwise negation (complement) of the value e1

Chapter 3 Master Rule Language (MRL) reference

69

MRL functions and primitives

Concatenation operator
The following operator takes two string arguments and produces a string result.
e1 || e2 Concatenation of string e1 with string e2

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 37 allows you to look up the location of the function and primitive descriptions alphabetically.

Table 37
abs/2 acos/2

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


Page 98 103 77 77 78 79 141 146 80 81 102 103 104 162 161 96 149 95 determine the absolute value of a numeric value return the arc cosine of a specified number retrieve the identification of the requestor of an action retrieve the user ID and password of the console user triggering the action retrieve the user ID and password of the console user, as well as the type of rule triggering the action terminate an internal action and return a value add an element at the beginning of a list slot obtain output values from a match table entry perform an action through remote execution on IAS perform an action through remote execution on IAS, providing IAS credentials return the arc sine of a specified number return the arc tangent of a specified number return the arc tangent of the ratio of two numbers perform a cell control command retrieve cell-specific information produce a string containing a single character with a specified numeric internal representation obtain the class hierarchy of a class retrieve the internal numeric representation of a character

Primitive/function name Description

action_requestor/1 action_requestor/2 action_requestor/3 action_return/2 add_to_list/2 apply_match_entry/4 admin_execute/5 admin_execute/7 asin/2 atan/2 atan2/3 cellcontrol/1 cellinfo/2 char/2 class_path/2 code/2

70

BMC Impact Solutions Knowledge Base Development Reference Guide

MRL functions and primitives

Table 37
concat/2

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


Page 113 85 101 109 110 concatenate a list of strings run an external program and wait for its termination to continue to process the current event return the cosine of an angle decrement an integer or enumeration slot by 1 decrement an integer or enumeration slot by a specified value

Primitive/function name Description confirm_external/2 cos/2 decr/1 decr/2 decr/2 and prev/2 decr/3 decr/3 decr/4 drop_new/0 execute/4 exp/2 find_match/5 find_match_entry/4 gcd/3 generate_event/2 get_env/2 get_external/4

return an integer or enumeration slot value decremented by 109 1 retrieve the value of an integer or enumeration slot decremented by a specified value decrement an integer or enumeration slot by a specified value within a given limit 111 111

return an integer or enumeration slot value decremented by 112 a specified value within a given limit drop a new event object run a program as an external process raise e (2.718281828...) to a specified power 187 84 99

find an entry in a match table and retrieve calculated values 142 from it find an entry in a match table return the greatest common divisor of two numbers generate a new event retrieve the value of an environment variable run an external program and wait for its termination to continue to process the current event, using data retrieved through an interface object retrieve a list of slots from one or more objects increment an integer or enumeration slot by 1 increment an integer or enumeration slot by a specified value 144 104 185 164 87

get_list_slotvalues/3 incr/1 incr/2 incr/2 and next/2 incr/3 incr/3 incr/4 int/2 int_to_hex/2

147 105 106

return an integer or enumeration slot value incremented by 1 106 return an integer or enumeration slot value incremented by a 107 specified value increment an integer or enumeration slot by a specified value within a specified limit retrieve the value of an integer or enumeration slot incremented by a given value within a specified limit truncate a numeric value to an integer value convert an integer value to a string containing its hexadecimal notation 108 108 93 89

Chapter 3 Master Rule Language (MRL) reference

71

MRL functions and primitives

Table 37

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


Page 89 88 163 170 170 169 137 136 137 convert an integer value to a string containing its hexadecimal notation in a specified field width convert an integer value to a string value retrieve Knowledge Base module version information validate and retrieve fields from a license key validate and retrieve fields from a license key retrieve the version from a license key concatenate two lists remove all occurrences of an element from a list verify that two lists do not have any common elements

Primitive/function name Description int_to_hex/3 inttostring/2 kbversion/1 kbversion/2 key_verify/2 key_verify/3 key_version/2 listappend/3 listdelete/3 listdisjoint/2 listgetelt/3 listintersect/3 listlen/2 listmember/2 listremdup/2 listsubtract/3 listunion/3 listwalk/2 log/2 log10/2 mapslots/3 mapslots/4 match_regex/3 match_regex/4 match_regex/5 max/3 min/3 new_data/3 ntadd/2 ntcnt/2 ntget/5 ntset/3 opadd/3 72

retrieve global Knowledge Base module version information 164

retrieve a list element located at a specified position within a 135 list determine the common elements of two lists determine the length of a list verify that an element is included in a list remove duplicate elements from a list remove the elements that occur in one list from another list determine the union of two lists execute instructions against each element in a list return the natural logarithm of a specified number return the decimal logarithm of a specified number format a series of expressions that refer to objects into a string format a series of expressions that refer to event and data objects into a string match a string with a regular expression match a string with a regular expression and retrieve all fields from it 138 135 136 140 139 139 140 100 100 129 128 124 125

match a string with a regular expression and retrieve a given 127 number of fields from it determine the maximum of two values determine the minimum of two values create a new data object add a note to an event count the notes attached to an event return the time stamp, author, and text of a note attached to an event modify the text of a note attached to an event add an operation to an event 96 97 186 150 150 151 151 153

BMC Impact Solutions Knowledge Base Development Reference Guide

MRL functions and primitives

Table 37
opadd/4 opcnt/2 opget/6 opget/7

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


Page 152 153 154 154 156 157 156 155 157 83 83 91 99 105 95 90 159 142 186 149 add a policy operation to an event count the operations of an event retrieve an operation of an event retrieve a policy operation of an event retrieve the action name of an operation of an event retrieve the argument list of an operation of an event retrieve the author of an operation of an event retrieve the time stamp of an operation of an event modify the policy name, action, and arguments of an operation of an event perform a specified action perform a specified action and return a value convert a pointer value to a string value raise a number to a specified power return a random integer that falls between two specified numbers convert a numeric value to a real value convert a real value to a string value establish the relation of an event to a source event remove the first occurrence of an element from a list slot delete a data object reset a slot to its default value

Primitive/function name Description

opget_action/3 opget_args/3 opget_author/3 opget_time/3 opset/4 opset/5 perform/3 perform/5 pointertostring/2 pow/3 random/3 real/2 and float/2 realtostring/2 relate/1 rem_from_list/2 remove_data/1 reset_default/1 round/2 send_to/2 send_to/3 send_to_ext/4 set_list_slotvalues/3 set_timer/3 set_timer_at/3 set_timer_at/4 sign/2 sin/2 smcomps/5 sprintf/3

modify the action and arguments of an operation of an event 158

convert a numeric value to an integer value by rounding the 94 number send an event to another cell or gateway send an event modification to another cell or gateway send an extended event to another cell or gateway assign values to a list of slots for one or more objects 165 165 166 148

set a timer on an event object that will expire after a specified 188 delay set a timer on an event object that will expire at a specified time set a timer on an event object that will expire at a specified time represented by a text string determine whether a numeric value is positive, negative, or zero return the sine of an angle search for certain Service Model components format a series of values into a string Chapter 3 Master Rule Language (MRL) reference 189 190 97 101 167 128 73

MRL functions and primitives

Table 37
sqrt/2

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


Page 98 134 117 91 92 93 92 119 119 120 113 determine the square root of a numeric value convert a string to a time stamp retrieve a string of a specified length that begins at a specified position within a larger string convert any non-list value to a string value convert a string value to an integer value convert a string value to a pointer value convert a string value to a real value strip leading and trailing blank spaces from a string remove blank spaces from specified parts of a string remove specified characters from specified parts of a string determine the length of a string

Primitive/function name Description str_to_time_stamp/3 strextract/4 string/2 stringtoint/2 stringtopointer/2 stringtoreal/2 strip/2 strip/3 strip/4 strlen/2 and len/2 strmatch/3 strnpart/4 strpart/3 strtolist/3 substring/3

match a string with a simple pattern and retrieve fields from 122 it determine the start position of a specified occurrence of a part of a string determine the starting position of a partial string within a larger string divide a string into parts at specified separators retrieve a string that begins at a specified position within a larger string and continues through the end of the larger string retrieve a substring of a specified length beginning at a specified offset return the tangent of an angle verify if one or more time frames are active verify if one or more time frames are active at a given time obtain the end time of the current active interval of a time frame 122 115 122 118

substring/4 tan/2 tf_active/1 tf_active/2 tf_current_end/2 tf_current_end/3 tf_current_interval/2 tf_current_interval/3 tf_current_start/2 tf_current_start/3 tf_duration/3

118 102 171 172 175

obtain the end time of the active interval of a time frame at a 175 specified time obtain the start and end time of the current active interval of 176 a time frame obtain the start and end time of the active interval of a time frame at a given time obtain the start time of the current active interval of a time frame 176 174

obtain the start time of the active interval of a time frame at a 174 specified time calculate the duration of all active intervals of a time frame from a specified start time to the current time 184

74

BMC Impact Solutions Knowledge Base Development Reference Guide

MRL functions and primitives

Table 37

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


Page 184 calculate the duration of all active intervals of a time frame during a specified time period

Primitive/function name Description tf_duration/4 tf_next_end/2 tf_next_end/3 tf_next_interval/2 tf_next_interval/3 tf_next_start/2 tf_next_start/3 tf_prev_end/2 tf_prev_end/3 tf_prev_interval/2 tf_prev_interval/3 tf_prev_start/2 tf_prev_start/3 tf_udid_active/1 tf_udid_active/2 time_extract/3 time_stamp/1 time_stamp_to_cim/2 time_stamp_to_str/2 time_stamp_to_str/3 tolowercase/2 and lower/2 touppercase/2 and upper/2 trunc/2 unrelate/1 unset_cause/0

obtain the end time of the next active interval of a time frame 181 obtain the end time of the next active interval of a time frame 182 at a specified time obtain the start and end time of the next active interval of a time frame obtain the start and end time of the next active interval of a time frame at a specified time obtain the start time of the next active interval of a time frame obtain the start time of the next active interval of a time frame at a given time obtain the end time of the previous active interval of a time frame obtain the end time of the previous active interval of a time frame at a given time obtain the start and end time of the previous active interval of a time frame obtain the start and end time of the previous active interval of a time frame at a specified time 182 183 180 181 178 179 179 180

obtain the start time of the previous active interval of a time 177 frame obtain the start time of the previous active interval of a time 177 frame at a given time verify if one or more time frames specified by mc_udid are active at the current time verify if one or more time frames specified by mc_udid are active at a specified time retrieve fields from a time stamp retrieve the current time 172 173 133 130

convert a time stamp to CIM (Common Information Model) 131 format convert a time stamp to the default DateFormat format convert a time stamp to a specified format convert a string to all lowercase characters convert a string to all uppercase characters truncate a real number to an integer (symmetric around 0) remove a relation of a related event to a source event break the cause-to-effect relationship from a correlate rule 132 131 114 115 94 160 188

Chapter 3 Master Rule Language (MRL) reference

75

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 INTEGER REAL POINTER ENUM OBJECT SLOTREF ANY LIST_OF T an expression evaluating to a value of type STRING an expression evaluating to a value of type INTEGER an expression evaluating to a value of type REAL an expression evaluating to a value of type POINTER an expression evaluating to a value of an enumeration type a reference to an event or data object a reference to a slot of an event, data or record object any simple (non-list) value 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).

76

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

action_requestor/1 syntax argument


Mode output Type STRING Description the user or rule that requested the action

$REQUESTOR

Use action_requestor/1 to retrieve the identification of the requestor of the action and return the identification in the $REQUESTOR argument. The requestor is either the user who performs the action from a console, or if the action is performed from a rule, the requestor is the name of the rule.

action_requestor/1 example
action AssignTo [Name:STRING($USER)] : EVENT($E) { action_requestor($REQUESTOR); $E.administrator = $REQUESTOR; $E.mc_owner = $USER; } END

In this example, the action AssignTo assigns a selected event to a named owner. The name of the owner is provided by the console user in the Name field of a dialog box, as specified in the action definition argument list. When the action is triggered, it retrieves the identification of the requestor and returns it in the $REQUESTOR variable. This value will be the ID of the console user and is assigned to the administrator slot of the event. 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) Chapter 3 Master Rule Language (MRL) reference 77

Action-related primitives

Table 39
$USER $PASSWD

action_requestor/2 syntax arguments


Type STRING STRING Description the requestor of the action the password of the requestor of the action output output

Argument Mode

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

action_requestor/2 example
action UserGetMetrics : EVENT($E) { action_requestor($USER,$PASSWD); admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES); } END

In this example, the action is designed to be used from a console. When the console user triggers the action, the action code first retrieves the user's identification in the $USER variable and the user's password in the $PASSWD variable. This information is passed on to the Administration server named ias1 to request a remote execution of the remote Administration server task GetMetrics on the selected event. No specific arguments are required for this remote task, so the second to last argument of admin_execute is an empty list ([]). The YES value for the last argument indicates that an MC_CELL_ACTION_RESULT event must be generated for this remote action.

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 40
Argument $USER

action_requestor/3 syntax arguments (part 1 of 2)


Mode output Type STRING Description the requestor of the action

78

BMC Impact Solutions Knowledge Base Development Reference Guide

Action-related primitives

Table 40
Argument $PASSWD

action_requestor/3 syntax arguments (part 2 of 2)


Mode output output Type STRING STRING Description the password of the requestor of the action the type of rule that performs the action. This string is empty if a user performs the action.

$RULETYPE

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

action_requestor/3 example
action UserGetMetrics : EVENT($E) { action_requestor($USER,$PASSWD,$RULETYPE); if ( $RULETYPE == '' ) then { admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES); } else { admin_execute(ias1,$E,GetMetrics,[],YES); } } END

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

action_return/2 terminate an internal action and return a value


action_return($CODE,$TEXT)

Chapter 3 Master Rule Language (MRL) reference

79

Action-related primitives

Table 41
$CODE $TEXT

action_return/2 syntax arguments


Type Description input input INTEGER specifies the numeric exit code to be returned when the action is terminated STRING specifies the text to be returned when the action is terminated

Argument Mode

Use action_return/2 to terminate an internal action and to return a value. The $CODE argument specifies the numeric exit code to be returned. The $TEXT argument specifies the text string to be returned. If the action is invoked from a rule using the perform/5 primitive, the $CODE and $TEXT values will be returned as the last two arguments of the perform/5 call. For more information about perform/5, see perform/5 perform a specified action and return a value on page 83.

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 42
Argument $NAME

admin_execute/5 syntax arguments (part 1 of 2)


Mode input Type STRING Description specifies the name of the remote execution agent (Impact Administration Server or other external framework such as a cell or gateway) specifies the object handle for the event or data on which the action is to be performed specifies the name of the action to be performed

$OBJECT $ACTION

input input

STRING STRING

80

BMC Impact Solutions Knowledge Base Development Reference Guide

Action-related primitives

Table 42
Argument $ARGS

admin_execute/5 syntax arguments (part 2 of 2)


Mode input Type Description LIST_OF ANY specifies a list of action arguments. Required arguments for the action specified in $ACTION must be of the correct type specified in the action definition and must be included in the $ARGS list.

$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) or other external framework using remote execution. The IAS or external framework must be defined in the DIRECTORY (mcell.dir), including the credentials to log in to it. The credentials must be provided as userid/password in the encryption key field. The action will be performed on IAS or the external framework using the credentials that are provided in the DIRECTORY.

admin_execute/5 example
action UserGetMetrics : EVENT($E) { admin_execute(ias1,$E,GetMetrics,[],YES); } END

In this example, the UserGetMetrics action retrieves metrics for an event from an Administration server. The action performs the GetMetrics remote task on the ias1 Administration server. Credentials are assumed to be provided in mcell.dir for this server.

admin_execute/7 perform an action through remote execution on IAS, providing IAS credentials
admin_execute($NAME,$USER,$PASSWD,$OBJECT,$ACTION,$ARGS,$ACTEVENT)

Chapter 3 Master Rule Language (MRL) reference

81

Action-related primitives

Table 43
Argument $NAME

admin_execute/5 syntax arguments


Mode input Type STRING Description specifies the name of the remote execution agent (Impact Administration Server or other external framework such as a cell or gateway) specifies the user name of the account for the IAS or other external framework specifies the password of the account for the IAS or other external framework specifies the object handle for the event or data on which the action is to be performed specifies the name of the remote action to be performed

$USER $PASSWD $OBJECT $ACTION $ARGS

input input input input input

STRING STRING STRING STRING

LIST_OF ANY specifies a list of action arguments. Required arguments for the action specified in $ACTION must be of the correct type specified in the action definition and must be included in the $ARGS list.

$ACTEVENT

input

BOOLEAN

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) or other external framework using remote execution, specifying the user name and password for the account for the remote action agent (IAS or other external framework). An action is executed through the remote action agent named NAME. The USER and PASSWD credentials are used to log in to the remote action agent. If ACTEVENT=YES an MC_CELL_ACTION_RESULT event is generated for the action. When the action is terminated, its output is stored in the action result event.

admin_execute/7 example
action UserGetMetrics : EVENT($E) { action_requestor($USER,$PASSWD); admin_execute(ias1,$USER,$PASSWD,$E,GetMetrics,[],YES); } END

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

82

BMC Impact Solutions Knowledge Base Development Reference Guide

Action-related primitives

This information is passed on to the Administration server named ias1 to request a remote execution of the remote Administration server task GetMetrics on the selected event. No specific arguments are required for this remote task, so the second to last argument of admin_execute is an empty list ([]). The YES value for the last argument indicates that an MC_CELL_ACTION_RESULT event must be generated for this remote action.

perform/3 perform a specified action


perform($OBJECT,$ACTION,$ARGS)

Table 44
Argument $OBJECT $ACTION $ARGS

perform/3 arguments
Mode input input input Type OBJECT STRING LIST_OF ANY Description specifies the object handle for the event or data on which the action is to be performed specifies the name of the action to be performed specifies a list of action arguments. Required arguments for the action specified in $ACTION must be of the correct type specified in the action definition and must be included in the $ARGS list.

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

perform/3 example
perform($E,AssignTo,[Operator1]);

perform/5 perform a specified action and return a value


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

Table 45
Argument $OBJECT $ACTION

perform/5 arguments
Mode input input Type OBJECT STRING Description specifies the object handle for the event or data on which the action is to be performed specifies the name of the action to be performed Chapter 3 Master Rule Language (MRL) reference 83

Action-related primitives

Table 45
Argument $ARGS

perform/5 arguments
Mode input Type Description LIST_OF ANY specifies a list of action arguments. Required arguments for the action specified in $ACTION must be of the correct type specified in the action definition and must be included in the $ARGS list.

$RETCODE output $RETTEXT output

INTEGER STRING

the numeric return code of the specified action the text string returned by the specified action

Use perform/5 to perform the action specified by the $ACTION argument on the event or data with the object handle specified in the $OBJECT argument and return a numeric return code in $RETCODE and a text string in $RETTEXT. Required arguments for the action must be provided in the $ARGS list. If the action returns through action_return/2, the return exit code and text value is determined by the return code and text string values defined in the perform/5 arguments. If the action does not return through the action_return/2 primitive or if it is an external action, the values 0 and the empty string will be returned. For more information on the action_return/2 primitive, see action_return/2 terminate an internal action and return a value on page 79.

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

execute/4 run a program as an external process


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

Table 46
Argument $EVENT $PROG

execute/4 arguments
Mode input input Type OBJECT STRING Description specifies the object handle for the event on which the action is to be performed specifies the name of the external program to be run

84

BMC Impact Solutions Knowledge Base Development Reference Guide

Action-related primitives

Table 46
Argument $ARGS

execute/4 arguments
Mode input Type Description LIST_OF ANY action argument list. Required arguments for the program must be provided in the $ARGS list. The arguments are passed to the external program as command line arguments.

$ACTEVT

input

STRING

YES|NO Indicates whether or not to generate an action event.

Use execute/4 to run the program specified in the 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 the BMC Impact Solutions Event Management Guide for more information about actions.). The execute/4 call terminates immediately when the external process has been set up, even if the program is not yet finished. The remainder of the rule is executed. The program is activated in an environment that contains all the slots of the event, using the slot name as the environment variable name. In addition, some systemdefined variables are available. See the BMC Impact Solutions Event Management Guide for more information about action execution variables. If the $ACTEVT argument is specified as YES, an MC_CELL_ACTION_RESULT event will be created. Upon termination of the program, the MC_CELL_ACTION_RESULT event will be updated with the result.

execute/4 example
execute($E,mc_modslot,[msg,Hello],NO);

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

confirm_external($PROG,$ARGS)

Chapter 3 Master Rule Language (MRL) reference

GORP$

85

Action-related primitives

Table 47
$PROG $ARGS

confirm_external/2 arguments
Type STRING LIST_OF ANY Description specifies the name of the external program to be run action argument list. Required arguments for the program must be provided in the $ARGS list. The arguments are passed to the external program as command line arguments. input input

Argument Mode

Use confirm_external/2 to run the program specified in the $PROG argument as an external process on the current event and wait for the program to terminate before continuing to process the current event. The program location is determined in the same manner as it is for actions. See the BMC Impact Solutions Event Management Guide for more information about actions. A call of confirm_external/2 suspends the processing of the current event. Upon termination of the program, processing of the current event is resumed. If the program is successful, 0 is returned as the exit status and the event passes through the remainder of the rules. If the program returns a non-zero exit status, the event is dropped and no other rules are applied to it. The program is activated in an environment that contains all the slots of the event, using the slot name as environment variable name. In addition, some system-defined variables are available. See the BMC Impact Solutions Event Management Guide for more information about action execution variables.

confirm_external/2 example
confirm_external(mc_ping,[]);

In this example, the mc_ping script performs a ping operation to the host specified in the mc_host_address slot of the event that is currently in the refine rule phase. No arguments are required for this script; therefore, the empty list functions as the second argument of the call. The script returns a 0 exit code if the ping succeeds. If the ping succeeds, the processing of the event will continue. If the ping fails, the event will be dropped.

86

BMC Impact Solutions Knowledge Base Development Reference Guide

Action-related primitives

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

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

Table 48
$PROG $ARGS

get_external/4 arguments
Type STRING Description specifies the name of the external program to be run input input

Argument Mode

LIST_OF ANY action argument list. Required arguments for the program must be provided in the $ARGS list. The arguments are passed to the external program as command line arguments.

$INTF $ANS

input

STRING

specifies the name of the interface class the data produced by the external program returned as an interface object

output OBJECT

Use get_external/4 to run the program specified in the $PROG argument as an external process on the current event and wait for the program to terminate before continuing to process the event. Upon successful return, the interface object specified by the $INTF argument is created that contains the data produced by the external program in the interface file. This object is available in the remainder of the rule, using the $ANS variable. The program location is determined in the same manner as it is for actions (See the BMC Impact Solutions Event Management Guide for more information about actions.). A call of get_external/4 suspends the processing of the current event. Upon termination of the program, processing of the current event is resumed. If the program is successful, 0 is returned as the exit status and the event passes through the remainder of the rules. If the program returns a non-zero exit status, the event is dropped and no other rules are applied to it. In addition, a file path is passed as extra first command line argument. The external program is assumed to produce an instance of the $INTF interface class in that file.

Chapter 3 Master Rule Language (MRL) reference

87

Value type conversion primitives

The program is activated in an environment that contains all the slots of the event, using the slot name as environment variable name. In addition, some system-defined variables are available. See the BMC Impact Solutions Event Management Guide for more information about action execution variables.

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)

88

BMC Impact Solutions Knowledge Base Development Reference Guide

Value type conversion primitives

Table 49
$INTVAL $STRVAL

inttostring/2 arguments
Type Description the resulting conversion string input INTEGER specifies the integer value to be converted to a string

Argument Mode

output STRING

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

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 50
$INTVAL $STRVAL

int_to_hex/2 arguments
Type INTEGER Description specifies the integer value to be converted to hexadecimal notation the hexadecimal notation of the integer returned as a string input

Argument Mode

output STRING

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

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

int_to_hex/3 convert an integer value to a string containing its hexadecimal notation in a specified field width
$STRVAL=int_to_hex($INTVAL,$FLDLEN)

Chapter 3 Master Rule Language (MRL) reference

89

Value type conversion primitives

Table 51
Argument $INTVAL $FLDLEN $STRVAL

int_to_hex/3 arguments
Mode input input output Type INTEGER INTEGER STRING Description specifies the integer value to be converted to hexadecimal notation specifies the desired resulting field width the hexadecimal notation of the integer returned as a string

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 52
Argument $REALVAL $STRVAL

realtostring/2 arguments
Mode input Type INTEGER Description specifies the real value to be converted to a string value the conversion result, returned as a string

output STRING

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

90

BMC Impact Solutions Knowledge Base Development Reference Guide

Value type conversion primitives

realtostring/2 example
$DEV = ( $AVERAGE_DURATION - real($E.duration) ) ^ 2; $E.msg = concat([Duration deviation=,realtostring($DEV)]);

pointertostring/2 convert a pointer value to a string value


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

Table 53
Argument $PTRVAL $STRVAL

pointertostring/2 arguments
Mode input output Type POINTER STRING Description specifies the pointer value to be converted to a string the conversion result, returned as a string

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 54
Argument $ANYVAL $STRVAL

string/2 arguments
Mode input output Type ANY STRING Description specifies any non-list value to be converted to a string the conversion result, returned as a string

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

Chapter 3 Master Rule Language (MRL) reference

91

Value type conversion primitives

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)

Table 55
Argument $STRVAL $INTVAL

stringtoint/2 arguments
Mode input output Type STRING INTEGER Description specifies the string value to be converted to an integer the conversion result, returned as an integer

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

stringtoint/2 example
$INTVAL = stringtoint($E.msg);

stringtoreal/2 convert a string value to a real value


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

Table 56
Argument $STRVAL $REALVAL

stringtoreal/2 arguments
Mode input output Type REAL Description the conversion result, returned as a real value STRING specifies the string value to be converted to an integer

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

92

BMC Impact Solutions Knowledge Base Development Reference Guide

Value type conversion primitives

stringtoreal/2 example
$REALVAL = stringtoreal($E.msg);

stringtopointer/2 convert a string value to a pointer value


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

Table 57
Argument $STRVAL $PTRVAL

stringtopointer/2 arguments
Mode input output Type STRING Description specifies the string value to be converted to an integer

POINTER the conversion result, returned as a pointer

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 58
Argument $NUMBER $INTVAL

int/2 arguments
Mode input Type Description INTEGER|REAL specifies the numeric (integer or real) value that is to be converted to an integer the conversion result, returned as an integer

output INTEGER

Use int/2 to convert the numeric value specified by the $NUMBER argument to an integer value returned in the $INTVAL argument. The conversion truncates the $NUMBER to the largest integer value that is smaller than or equal to it. The following statement is true for the truncation process: X: X-1 < int(X) X

Chapter 3 Master Rule Language (MRL) reference

93

Value type conversion primitives

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 59
Argument $NUMBER $INTVAL

trunc/2 arguments
Mode input Type Description INTEGER|REAL specifies the numeric (integer or real) value that is to be converted to an integer the conversion result, returned as an integer

output INTEGER

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 60
Argument $NUMBER $INTVAL

round/2 arguments
Mode input Type INTEGER|REAL Description specifies the numeric (integer or real) value that is to be converted to an integer the conversion result, returned as an integer

output INTEGER

94

BMC Impact Solutions Knowledge Base Development Reference Guide

Value type conversion primitives

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)

Table 61
Argument $NUMBER $REALVAL

real/2 or float/2 arguments


Mode input output Type Description INTEGER|REAL specifies the numeric (integer or real) value to be converted to a real (floating point) value 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 62
$STRVAL $INTVAL

code/2 arguments
Type STRING Description specifies the single character for which you want to return the numeric code input

Argument Mode

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.
Chapter 3 Master Rule Language (MRL) reference 95

Mathematical functions

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)

Table 63
Argument $INTVAL $STRVAL

char/2 arguments
Mode input output Type Description INTEGER specifies the integer character code for the single-character string STRING the single character represented by the integer character code, returned as a string

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

char/2 example
$E.msg = char($E.msg);

Mathematical functions
max/3 determine the maximum of two values
$MAXVAL=max($VAL1,$VAL2)

Table 64
Argument $VAL1 $VAL2 $MAXVAL

max/3 arguments
Mode input input output Type ANY ANY ANY Description specifies the first value to be compared specifies the second value to be compared to the first value returns the maximum value

96

BMC Impact Solutions Knowledge Base Development Reference Guide

Mathematical functions

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

min/3 determine the minimum of two values


$MINVAL=min($VAL1,$VAL2)
.

Table 65
Argument $VAL1 $VAL2 $MINVAL

min/3 arguments
Mode input input output Type ANY ANY ANY Description specifies the first value to be compared specifies the second value to be compared to the first value returns the minimum value

Use min/3 to determine the minimum of two values specified in the $VAL1 and $VAL2 arguments and return the result as $MINVAL. Both input values must be the same, simple (non-list) type.

min/3 example
$MIN_DURATION = min( $PREVIOUS_DURATION , $E.duration );

sign/2 determine whether a numeric value is positive, negative, or zero


$SIGN=sign($NUMBER)

Table 66
$NUMBER $SIGN

sign/2 arguments
Type INTEGER|REAL Description specifies the numeric (integer or real) value for which the sign is to be returned returns the sign of the number. Possible values include:
s s s

Argument Mode input

output INTEGER

-1 negative number 0 zero value 1 positive number

Chapter 3 Master Rule Language (MRL) reference

97

Mathematical functions

The sign/2 function returns the sign of the numeric value specified by the $NUMBER argument and returned as $SIGN.

NOTE
A real number that is not precisely 0 may still be displayed as 0.0 due to rounding errors or limited precision. The sign of such a real number will not be 0.

sign/2 example
$SIGN = sign( $AVERAGE_DURATION - real($E.duration) );

abs/2 determine the absolute value of a numeric value


$ABSVAL=abs($NUMBER)

Table 67
Argument $NUMBER $ABSVAL

abs/2 arguments
Mode input output Type INTEGER|REAL INTEGER|REAL Description specifies the numeric (integer or real) value for which the absolute value is to be returned returns the absolute value of the number

The abs/2 function returns the absolute value of the numeric value specified in the $NUMBER argument as $ABSVAL.

abs/2 example
$ABS = abs( $AVERAGE_DURATION - real($E.duration) );

sqrt/2 determine the square root of a numeric value


$RESULT=sqrt($NUMBER)

Table 68
Argument $NUMBER $RESULT

sqrt/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the numeric (integer or real) value for which the square root is to be returned returns the square root of the number

The sqrt/2 function returns the square root value of the numeric value specified by the $NUMBER argument as $RESULT.
98 BMC Impact Solutions Knowledge Base Development Reference Guide

Mathematical functions

sqrt/2 example
$SQRT = sqrt( ( $AVERAGE_DURATION - real($E.duration) ) ^ 2 );

$RESULT=exp($NUMBER)

Table 69
Argument $NUMBER $RESULT

exp/2 arguments
Mode input output Type REAL Description is to be raised returns raised to the specified number INTEGER|REAL specifies the power to which

The exp/2 function returns the number (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 70
Argument $NUMBER $POWER $RESULT

pow/3 arguments
Mode input input output Type INTEGER|REAL INTEGER|REAL REAL Description specifies the numeric (integer or real) value to be raised to the specified power specifies the power to which the numeric value is to be raised returns the number raised to the power

The pow/3 function raises the number specified in the $NUMBER argument to the power specified in the $POWER argument and returns the result in $RESULT.

NOTE
The exponentiation operator ^ can only be used with integer powers. For non-integer powers, pow/3 must be used.

Chapter 3 Master Rule Language (MRL) reference

exp/2 raise

(2.718281828...) to a specified power

99

Mathematical functions

pow/3 example
$POW = pow( $VAL , 3.14 );

log/2 return the natural logarithm of a specified number


$RESULT=log($NUMBER)

Table 71
Argument $NUMBER $RESULT

log/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the numeric (integer or real) value for which the natural logarithm is to be returned the natural logarithm of the number, returned as a real value

The log/2 function calculates the natural logarithm (base 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 72
Argument $NUMBER $RESULT

log10/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the numeric (integer or real) value for which the decimal logarithm is to be returned the natural logarithm of the number, returned as a real value

The log10/2 function returns the decimal logarithm (base 10) of the number specified by the $NUMBER argument in the $RESULTargument.

100

BMC Impact Solutions Knowledge Base Development Reference Guide

Mathematical functions

log10/2 example
$LOG = log10( $VAL );

sin/2 return the sine of an angle


$RESULT=sin($NUMBER)

Table 73
Argument $NUMBER $RESULT

sin/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the angle (expressed in radians) for which the sine is to be returned the sine of the angle, returned as a real value

The sin/2 function returns the sine of the angle specified in the $NUMBER argument in the $RESULT argument.

sin/2 example
$SIN = sin( $ANGLE );

cos/2 return the cosine of an angle


$RESULT=cos($NUMBER)

Table 74
Argument $NUMBER $RESULT

cos/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the angle (expressed in radians) for which the cosine is to be returned the cosine of the angle, returned as a real value

The cos/2 function returns the cosine of the angle specified in the $NUMBER argument in the $RESULT argument.

Chapter 3

Master Rule Language (MRL) reference

101

Mathematical functions

cos/2 example
$COS = cos( $ANGLE );

tan/2 return the tangent of an angle


$RESULT=tan($NUMBER)

Table 75
Argument $NUMBER $RESULT

tan/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the angle (expressed in radians) for which the tangent is to be returned the tangent of the angle, returned as a real value

The tan/2 function returns the tangent of the angle specified in the $NUMBER argument in the $RESULT argument.

tan/2 example
$TAN = tan( $ANGLE );

asin/2 return the arc sine of a specified number


$RESULT=asin($NUMBER)

Table 76
Argument $NUMBER $RESULT

asin/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the number for which the arc sine is to be returned angle for which the number $NUMBER is the arc sine (expressed in radians)

The asin/2 function returns the arc sine of the number specified in the $NUMBER argument in the $RESULT argument.

102

BMC Impact Solutions Knowledge Base Development Reference Guide

Mathematical functions

asin/2 example
$ANGLE = asin( $VAL );

acos/2 return the arc cosine of a specified number


$RESULT=acos($NUMBER)

Table 77
Argument $NUMBER $RESULT

acos/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the number for which the arc cosine is to be returned angle for which the number $NUMBER is the arc cosine (expressed in radians)

The acos/2 function returns the arc cosine of the number specified in the $NUMBER argument in the $RESULT argument.

acos/2 example
$ANGLE = acos( $VAL );

atan/2 return the arc tangent of a specified number


$RESULT=atan($NUMBER)

Table 78
Argument $NUMBER $RESULT

atan/2 arguments
Mode input output Type INTEGER|REAL REAL Description specifies the number for which the arc tangent is to be returned angle for which the number $NUMBER is the arc tangent (expressed in radians)

The atan/2 function returns the arc tangent of the number specified in the $NUMBER argument in the $RESULT argument.

Chapter 3

Master Rule Language (MRL) reference

103

Mathematical functions

atan/2 example
$ANGLE = atan( $VAL );

atan2/3 return the arc tangent of the ratio of two numbers


$RESULT=atan2($NUMBER1,$NUMBER2)

Table 79
Argument $NUMBER1 $NUMBER2 $RESULT

atan2/3 arguments
Mode input input output Type INTEGER|REAL INTEGER|REAL REAL Description specifies the first (integer or real) value of the ratio specifies the second (integer or real) value of the ratio angle for which the ratio of $NUMBER1 and $NUMBER2 is the arc tangent (expressed in radians)

The atan2/3 function returns the arc tangent of the ratio of $NUMBER1 and $NUMBER2 in the $RESULT argument.

atan2/3 example
$RIGHTANGLE = atan2( 1 , 0 );

gcd/3 return the greatest common divisor of two numbers


$RESULT=gcd($NUMBER1,$NUMBER2)

Table 80
Argument $NUMBER1 $NUMBER2 $RESULT

gcd/3 arguments
Mode input input output Type INTEGER INTEGER INTEGER Description specifies the first integer value of the two integers for which a common divisor is to be returned specifies the second integer value of the two integers for which a common divisor is to be returned the greatest common divisor of the two specified numbers

104

BMC Impact Solutions Knowledge Base Development Reference Guide

Enumeration operations

The gcd/3 function returns the greatest common divisor of $NUMBER1 and $NUMBER2 in $RESULT.

gcd/3 example
$GCD = gcd( $NUM1 , $NUM2 );

random/3 return a random integer that falls between two specified numbers
$RESULT=random($NUMBER1,$NUMBER2)

Table 81
Argument $NUMBER1 $NUMBER2 $RESULT

random/3 arguments
Mode input input Type INTEGER INTEGER Description first number in the range within which a random number is to be returned last number in the range within which a random number is to be returned a random number between both numbers

output INTEGER

The random/3 function returns a random integer number between the integer specified by the $NUMBER1 argument and the integer specified by the $NUMBER2 argument in $RESULT.

random/3 example
$RAND = random( $NUM1 , $NUM2 );

Enumeration operations
incr/1 increment an integer or enumeration slot by 1
incr($SLOT)

Table 82
$SLOT

incr/1 arguments
Type SLOTREF Description specifies an integer or enumeration slot to be incremented input

Argument Mode

Chapter 3

Master Rule Language (MRL) reference

105

Enumeration operations

Use incr/1 to increment the slot referenced in $SLOT by 1. For an enumeration, the slot is set to the next higher value. If there is no higher value, the slot value is not modified.

incr/1 example
incr( $E.mc_priority );

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 83
$SLOT

incr/2 arguments
Type SLOTREF Description specifies an integer or enumeration slot for which the incremented value is to be returned. The actual value of the slot is not incremented. input

Argument Mode

$VAL

output

INTEGER|ENUM

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)

106

BMC Impact Solutions Knowledge Base Development Reference Guide

Enumeration operations

Table 84
Argument $SLOT $INCR

incr/2 arguments
Mode input input Type SLOTREF INTEGER Description specifies an integer or enumeration slot to be incremented specifies the number by which the slot is to be incremented

Use incr/2 to increment the slot referenced in $SLOT by $INCR. For an enumeration, the slot is incremented by $INCR higher values. If there are not $INCR higher values, then the slot is incremented to the highest value available.

incr/2 example
incr( $E.mc_priority , 2 );

incr/3 return an integer or enumeration slot value incremented by a specified value


$VAL=incr($SLOT,$INCR)

Table 85
$SLOT

incr/3 arguments
Type SLOTREF Description specifies an integer or enumeration slot for which the incremented value is to be returned The actual slot value is not incremented. input

Argument Mode

$INCR $VAL

input output

INTEGER INTEGER|ENUM

specifies the number by which the slot value is to be incremented when it is returned in $VAL value of the slot incremented by $INCR

Use incr/3 to retrieve the value of the slot referenced in $SLOT incremented by $INCR in $VAL. For an enumeration, the slot value returned is incremented by $INCR higher values. If there are not $INCR higher values, then the slot value returned is incremented to the highest value available. The referenced slot itself is not modified.

Chapter 3

Master Rule Language (MRL) reference

107

Enumeration operations

incr/3 example
$NEWPRIO = incr( $E.mc_priority , 2 );

incr/3 increment an integer or enumeration slot by a specified value within a specified limit
incr($SLOT,$INCR,$LIMIT)

Table 86
$SLOT $INCR $LIMIT

incr/3 arguments
Type SLOTREF INTEGER Description specifies an integer or enumeration slot to be incremented specifies the number by which the slot is to be incremented input input input

Argument Mode

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 87
Argument $SLOT

incr/4 arguments
Mode input Type SLOTREF Description specifies an integer or enumeration slot for which the incremented value is to be returned The actual slot value is not incremented.

$INCR

input

INTEGER

specifies the number by which the slot value is to be incremented when it is returned in $VAL

108

BMC Impact Solutions Knowledge Base Development Reference Guide

Enumeration operations

Table 87
Argument $LIMIT $VAL

incr/4 arguments
Mode input output Type INTEGER|ENUM INTEGER|ENUM Description specifies the limit to which the slot value is to be incremented when it is returned in $VAL value of the slot incremented by $INCR

Use incr/4 to retrieve the value of the slot referenced in $SLOT incremented by $INCR, limited to the value $LIMIT in $VAL. For an enumeration, the slot value returned is incremented by $INCR higher values, limited to $LIMIT. The referenced slot itself is not modified.

incr/4 example
$NEWPRIO = incr( $E.mc_priority , 2 , PRIORITY_2 );

decr/1 decrement an integer or enumeration slot by 1


decr($SLOT)

Table 88
Argument $SLOT

decr/1 arguments
Mode input Type SLOTREF Description specifies an integer or enumeration slot to be decremented

Use decr/1 to decrement the slot referenced in $SLOT by 1. For an enumeration, the slot is set to the next lower value, or unmodified if there is no lower value.

decr/1 example
decr( $E.mc_priority );

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)

Chapter 3

Master Rule Language (MRL) reference

109

Enumeration operations

Table 89
Argument $SLOT

decr/2 arguments
Mode input Type SLOTREF Description specifies an integer or enumeration slot for which the decremented value is to be returned. The actual value of the slot is not decremented.

$VAL

output

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.

decr/2 example
$NEWPRIO = decr( $E.mc_priority );

decr/2 decrement an integer or enumeration slot by a specified value


decr($SLOT,$DECR)

Table 90
$SLOT $DECR

decr2 arguments
Description input SLOTREF specifies an integer or enumeration slot to be decremented input INTEGER specifies the number of values that the slot is to be decremented

Argument Mode Type

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.

110

BMC Impact Solutions Knowledge Base Development Reference Guide

Enumeration operations

decr2 example
decr( $E.mc_priority , 2 );

decr/3 retrieve the value of an integer or enumeration slot decremented by a specified value
$VAL=decr($SLOT,$DECR)

Table 91
$SLOT

decr/3 arguments
Type SLOTREF Description specifies an integer or enumeration slot for which the decremented value is to be returned. The actual value of the slot is not decremented. input

Argument Mode

$DECR $VAL

input output

INTEGER INTEGER|ENUM

specifies the number by which the slot value returned in $VAL is to be decremented value of the slot decremented by $DECR

Use decr/3 to retrieve the value of the slot referenced in $SLOT decremented by $DECR in $VAL. For an enumeration, the slot value is decremented to the $DECR next lower value. If there are not $DECR lower values, the slot value is decremented to the lowest value. The referenced slot itself is not modified.

decr/3 example
$NEWPRIO = decr( $E.mc_priority , 2 );

decr/3 decrement an integer or enumeration slot by a specified value within a given limit
decr($SLOT,$DECR,$LIMIT)

Chapter 3

Master Rule Language (MRL) reference

111

Enumeration operations

Table 92
Argument $SLOT $DECR $LIMIT

decr/3 arguments
Mode input input input Type SLOTREF INTEGER INTEGER|ENUM Description specifies an integer or enumeration slot to be decremented specifies the number by which the slot is to be decremented specifies the limit to which the slot value is to be decremented

Use decr/3 to decrement the slot referenced in $SLOT by $DECR, limited to the value $LIMIT. For an enumeration, the slot value is decremented to the $DECR next lower value, limited to $LIMIT.

decr/3 example
decr( $E.mc_priority , 2 , PRIORITY_4 );

decr/4 return an integer or enumeration slot value decremented by a specified value within a given limit
$VAL=decr($SLOT,$DECR,$LIMIT)

Table 93
$SLOT

decr/4 arguments
Type SLOTREF Description specifies an integer or enumeration slot for which the decremented value is to be returned. The actual value of the slot is not decremented. input

Argument Mode

$DECR $LIMIT $VAL

input input output

INTEGER INTEGER|ENUM INTEGER|ENUM

specifies the number by which the slot value returned in $VAL is to be decremented specifies the limit to which the slot value returned in $VAL is to be decremented value of the slot decremented by $DECR

Use decr/4 to return the value of the slot specified in $SLOT decremented by $DECR, limited to the value $LIMIT in $VAL. For an enumeration, the slot value returned is decremented to the $DECR next lower value, limited to $LIMIT. The referenced slot itself is not modified.

112

BMC Impact Solutions Knowledge Base Development Reference Guide

String manipulation

decr/4 example
$NEWPRIO = decr( $E.mc_priority , 2 , PRIORITY_4 );

String manipulation
concat/2 concatenate a list of strings
concat($STRLIST,$STR) $STR=concat($STRLIST)

Table 94
Argument $STRLIST $STR

concat/2 arguments
Mode input output Type LIST_OF STRING STRING Description list of strings to be concatenated 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);

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 95
Argument $STR $LEN

strlen/2 and len/2 arguments


Mode input output Type STRING INTEGER Description the string for which the length is to be returned string length in characters

Chapter 3

Master Rule Language (MRL) reference

113

String manipulation

Use strlen/2 to calculate the length of the string $STR and return the number of characters in the string in the $LEN argument.

NOTE
The number of characters in the string may differ from the number of bytes needed to store the string.

strlen/2 example
$MSGLEN = strlen($E.msg);

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)

Table 96
Argument $ORGSTR $NEWSTR

tolowercase/2 and lower/2 arguments


Mode input output Type STRING STRING Description specifies the string to be converted to lowercase 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.

114

BMC Impact Solutions Knowledge Base Development Reference Guide

String manipulation

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 97
Argument $ORGSTR $NEWSTR

touppercase/2 and upper/2 arguments


Mode input output Type STRING STRING Description specifies the string to be converted to uppercase 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);

strpart/3 determine the starting position of a partial string within a larger string
strpart($STR,$PART,$POS) $POS=strpart($STR,$PART)

Chapter 3

Master Rule Language (MRL) reference

115

String manipulation

Table 98
$STR $PART $POS

strpart/3 arguments
Type STRING STRING INTEGER Description specifies the base string within which you want to determine the starting position of another, partial, string specifies the partial string for which you are trying to determine the starting position within $STR starting position of the partial string within $STR input input output

Argument Mode

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)

Table 99
$STR

strnpart/4 arguments
Type STRING Description specifies the base string within which you want to determine the starting position of a specified reoccurrence of a another, partial, string specifies the partial string for which you are trying to determine the starting position after a specified number of occurrences within $STR 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 starting position of the partial string within $STR input

Argument Mode

$PART

input

STRING

$CNT

input

INTEGER

$POS

output

INTEGER

116

BMC Impact Solutions Knowledge Base Development Reference Guide

String manipulation

Use strnpart/4 to determine at what position in $STR the number of occurrences for the partial string $PART reaches $CNT number of occurrences. The position is returned in $POS. The first character of the string is counted as 1. If the partial string does not occur at least $CNT times in the base string, the value 0 is returned as position.

strnpart/4 example
$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 100 strextract/4 arguments


Argument $STR $POS $LEN $NEWSTR Mode input input input output Type STRING INTEGER INTEGER STRING Description specifies the base string within which you want to retrieve another, partial, string that starts at $POS specifies the starting position for the partial string that you want to return specifies the length (number of characters) of the partial string that you want to return 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.

Chapter 3

Master Rule Language (MRL) reference

117

String manipulation

strextract/4 example
strextract($YYYYMMDD,5,2,$MM);

substring/3 retrieve a string that begins at a specified position within a larger string and continues through the end of the larger string
$NEWSTR=substring($STR,$SKIP)

Table 101 substring/3 arguments


Argument $STR $SKIP $NEWSTR Mode input input output Type STRING INTEGER STRING Description specifies the base string within which you want to retrieve another, partial, string that starts after $SKIP specifies the number of characters to skip in the base string before $NEWSTR begins 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);

substring/4 retrieve a substring of a specified length beginning at a specified offset


$NEWSTR=substring($STR,$SKIP,$LEN)

Table 102 substring/4 arguments


Argument $STR $SKIP $LEN $NEWSTR Mode input input input output Type STRING Description specifies the base string within which you want to retrieve another, partial, string that starts after $SKIP

INTEGER specifies the number of characters to skip in the base string before $NEWSTR begins INTEGER specifies the length of $NEWSTR STRING retrieved string

118

BMC Impact Solutions Knowledge Base Development Reference Guide

String manipulation

Use substring/4 to retrieve part of the string $STR into $NEWSTR. The retrieved part of the string starts $SKIP characters from the start of $STR and is $LEN characters long.

substring/4 example
$MM = substring($YYYYMMDD,4,2);

strip/2 strip leading and trailing blank spaces from a string


$NEWSTR=strip($STR)

Table 103 strip/2 arguments


Argument $STR $NEWSTR Mode input output Type STRING STRING Description specifies the base string from which blank spaces at the beginning and end of the string are to be removed 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);

strip/3 remove blank spaces from specified parts of a string


$NEWSTR=strip($STR,$POS)

Table 104 strip/3 arguments


Argument $STR $POS $NEWSTR Mode input input output Type STRING Description specifies the base string from which blank spaces at a specified position are to be removed

INTEGER specifies the position within the base string from which blank spaces are to be removed STRING resulting string after the blank spaces have been removed

Use strip/3 to remove the blank spaces from position $POS within $STR and copy the resulting string into $NEWSTR.

Chapter 3

Master Rule Language (MRL) reference

119

String manipulation

The value of $POS determines the part or parts of the base string where the blank spaces are to be removed. Only the three least significant bits are considered, as shown: Table 105 Possible values for the $POS argument
$POS value 0 1 2 3 4 5 6 7 Binary value Impacted part of the string 000 001 010 011 100 101 110 111 none end middle middle + end beginning beginning + end beginning + middle beginning + middle + end

strip/3 example
$MSG = strip($E.msg,2);

strip/4 remove specified characters from specified parts of a string


$NEWSTR=strip($STR,$POS,$CHARS)

Table 106 strip/4 arguments


Argument $STR $POS $CHARS $NEWSTR Mode input input input output Type STRING Description specifies the base string from which specified characters are to be removed

INTEGER specifies the part(s) of the string from which specified characters are to be removed STRING STRING specifies the characters to be removed resulting string after the specified characters have been removed

Use strip/4 to make a copy of the string $STR in another string $NEWSTR with all characters from $CHARS stripped off from position $POS.

120

BMC Impact Solutions Knowledge Base Development Reference Guide

String manipulation

The value of $POS determines the part or parts of the base string where the blank spaces are to be removed. Only the three least significant bits are considered, as shown: Table 107 Possible values for the $POS argument
$POS value 0 1 2 3 4 5 6 7 Binary value Impacted part of the string 000 001 010 011 100 101 110 111 none end middle middle and end beginning beginning and end beginning and middle 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. For example, a string contains the following characters: # !!# #a bc #! d # e #!# The first character in the string up to, but not including, a is considered to be the beginning of the string. The part of the string starting from the space after the e through the last character in the string is considered to be the end of the string. The part of the string from the a through the e is considered to be the middle of the string.

strip/4 example
$MSG = strip($E.msg,6, #!);

The variable $MSG gets the contents of the msg slot of the event with all blank spaces, # and ! characters removed, except at the end of the string. Any trailing sequence of those three characters at the end of the slot value are retained.
Chapter 3 Master Rule Language (MRL) reference 121

String manipulation

If $E.msg has the value from this example, $MSG will get the value abcde # !# .

strtolist/3 divide a string into parts at specified separators


strtolist($STR,$SEP,$FLDS) $FLDS=strtolist($STR,$SEP)

Table 108 strtolist/3 arguments


Argument $STR $SEP $FLDS Mode input input output Type STRING STRING LIST_OF STRING Description specifies the string to be divided into fields specifies the separator(s) which separates the pieces of the string into fields retrieved fields

Use strtolist/3 to divide a string $STR into pieces, separated by any character from $SEP and collect the fields in $FLDS. The $FLDS argument can be specified as one variable that will get a list value or it can be specified as a list of as many variables as there are fields in the base string.

strtolist/3 example
strtolist(/usr/bin/mcell.exe,/.,$FLDS);

The input string will be divided into pieces that are separated with forward slash or dot characters. The variable $FLDS will be set to the list [usr,bin,mcell,exe].

strmatch/3 match a string with a simple pattern and retrieve fields from it
strmatch($STR,$PAT,$FLDS) $FLDS=strmatch($STR,$PAT)

Table 109 strmatch/3 arguments


Argument $STR $PAT $FLDS Mode input input output Type STRING STRING Description specifies the string with which the pattern is to be matched specifies the pattern to match with the string

LIST_OF STRING retrieved fields

122

BMC Impact Solutions Knowledge Base Development Reference Guide

String manipulation

Use strmatch/3 to match a string $STR with a pattern $PAT and retrieve fields from it in $FLDS. The pattern $PAT consists of literal text and value substitutes. Literal text is matched literally. Space characters in the pattern are matched with any number of consecutive spaces. Non-printable or special characters can be specified in the text with escape sequences:
\\ \s \n \r \t \0ddd backslash space (single space) new line carriage return tab character code in octal

A substitute is preceded by a % sign, followed by a type indicator. Between the % and the type indicator, an optional * suppression modifier can be added. The values corresponding to the substitutes are collected in the fields in $FLDS, in order of appearance. Suppressed substitutes are matched, but the values are not collected. Possible substitutes are:
%% %d %f %c %s literal match of % decimal integer number floating point real number single character string value

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

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

The $FLDS argument can be specified as one variable that will get a list value or it can be specified as a list of as many variables as there are fields specified in the pattern.

Chapter 3

Master Rule Language (MRL) reference

123

String manipulation

strmatch/3 example
strmatch(abc def 12,%s %d,[$FLD1,$FLD2]);

The pattern defines two fields, one string and one integer number, separated with spaces. The variable $FLD1 will get the value abc def and variable $FLD2 will get the value 12.
strmatch(Hi you there!,Hi %s!,$FLDS);

The pattern defines one string field, preceded by the text Hi and followed by an ! (exclamation point). The variable $FLDS will be set to a list containing the single string you there.
strmatch(Hi there,Hi %s!,$FLDS);

This call will fail because the pattern defines one string field, preceded by the text Hi and followed by an (exclamation point), but the input string does not contain an (exclamation point) at the end.
strmatch(a b c go,%s %s go,[$FLD1,$FLD2]);

The pattern defines two string fields, separated with spaces and followed by text. The variable $FLD1 will get the value a, because the first string substitute is followed by a space and a substitute which consumes the input up to the first space. The variable $FLD2 will get the value b c because its string substitute is followed by a space and a literal which consumes the input up to the matching literal.

match_regex/3 match a string with a regular expression


match_regex($STR,$REGEX,$OPTS)

Table 110
Argument $STR $REGEX $OPTS

match_regex/3 arguments
Mode input input input Type STRING STRING STRING Description specifies the string to be matched specifies the regular expression to match with the string specifies the options for how the regular expression engine operates

124

BMC Impact Solutions Knowledge Base Development Reference Guide

String manipulation

Use match_regex/3 to match a string $STR with regular expression $REGEX applying options specified in $OPTS.

NOTE
The regular expression $REGEX must be compliant with the Perl Compatible Regular Expression specification. For a specification, see http://perldoc.perl.org/perlre.html.

The value of the $OPTS argument can be either an empty string or a sequence of any of the following option indicators:
i m s x perform case insensitive string comparison multi-line mode a dot matches any character, including new line extended mode (see below)

In extended mode, blank space data characters in the pattern are ignored, except when they are escaped or inside a character class. Characters between an unescaped # outside a character class and the next new line character, inclusive, are also ignored. The call of match_regex/3 will succeed if the string matches the regular expression and fail otherwise.

match_regex/3 example
match_regex(2007 02 04 mcell: RULES: xyz, [0-9]* [0-9]* [0-9]* [^:]*: [^:]*: .*,);

The input string, which could be part of a trace, matches the regular expression.

match_regex/4 match a string with a regular expression and retrieve all fields from it
match_regex($STR,$REGEX,$OPTS,$FLDS) $FLDS=match_regex($STR,$REGEX,$OPTS)

Table 111
Argument $STR $REGEX

match_regex/4 arguments
Mode input input Type STRING STRING Description specifies the string to be matched specifies the regular expression to match to the string

Chapter 3

Master Rule Language (MRL) reference

125

String manipulation

Table 111
Argument $OPTS $FLDS

match_regex/4 arguments
Mode input output Type STRING LIST_OF STRING Description specifies the options for how the regular expression engine operates retrieved fields

Use match_regex/4 to match a string $STR with regular expression $REGEX applying options from $OPTS and to collect retrieved fields in $FLDS.

NOTE
The regular expression $REGEX must be compliant with the Perl Compatible Regular Expression specification. For a specification, see http://perldoc.perl.org/perlre.html.

The options argument can be either an empty string or a sequence of any of the following option indicators:
i m s x perform case insensitive string comparison multi-line mode a dot matches any character, including new line extended mode (see below)

The $FLDS argument can be specified as one variable that will get a list value, or it can be specified as a list of as many variables as there are fields in the regular expression.

match_regex/4 example
match_regex(2007 02 04 mcell: RULES: xyz, [0-9]* [0-9]* [0-9]* ([^:]*): ([^:]*): .*,,$FLDS);

The input string, which could be part of a trace, matches the regular expression. The two fields are collected in $FLDS as [mcell,RULES].

126

BMC Impact Solutions Knowledge Base Development Reference Guide

String manipulation

match_regex/5 match a string with a regular expression and retrieve a given number of fields from it
match_regex($STR,$REGEX,$OPTS,$FLDCNT,$FLDS) $FLDS=match_regex($STR,$REGEX,$OPTS,$FLDCNT)

Table 112
Argument $STR $REGEX $OPTS $FLDCNT $FLDS

match_regex/5 arguments
Mode input input input input output Type STRING STRING STRING INTEGER Description specifies the string to be matched specifies the regular expression to match to the string specifies the options for how the regular expression engine operates requested number of fields to be retrieved

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 m s x perform case insensitive string comparison multi-line mode a dot matches any character, including new line extended mode (see below)

The $FLDS argument can be specified as one variable that will get a list value, or it can be specified as a list of $FLDCNT variables.

match_regex/5 example
match_regex(2007 02 04 mcell: RULES: xyz, [0-9]* [0-9]* [0-9]* ([^:]*): ([^:]*): .*,,1,[$FLD]);

The input string, which could be part of a trace, matches the regular expression. There are two fields, but only the first one is collected in $FLD as mcell.

Chapter 3

Master Rule Language (MRL) reference

127

String manipulation

sprintf/3 format a series of values into a string


sprintf($STR,$FORMAT,$ARGS) $STR=sprintf($FORMAT,$ARGS)

Table 113
Argument $FORMAT $ARGS $STR

sprintf/3 arguments
Mode input input Type STRING Description specifies the format for the resulting string resulting string

LIST_OF ANY specifies the arguments to be printed as a string

output STRING

Use sprintf/3 to print a list of arguments specified in $ARGS into the $STR argument using the format specified in $FORMAT. The format specification for sprintf/3 is the same as for the C language sprintf() function.

WARNING
The arguments specified in $ARGS must be compliant with the specified format. Passing incompatible arguments can cause a crash of the cell.

sprintf/3 example
sprintf($E.msg,Event #%x,[$E.event_handle]);

The msg slot is set to the event number in hexadecimal notation (%x format).

mapslots/4 format a series of expressions that refer to event and data objects into a string
$STR=mapslots($OBJECTS,$FORMAT,$EXPRS)

Table 114
Argument $OBJECTS $FORMAT $EXPRS $STR

mapslots/4 arguments
Mode input input input output Type STRING STRING Description specifies the format to be applied resulting string LIST_OF OBJECT specifies the list of event or data objects LIST_OF STRING specifies the expressions to be evaluated

128

BMC Impact Solutions Knowledge Base Development Reference Guide

String manipulation

Use mapslots/4 to evaluate a list of expressions $EXPRS, referring to objects from $OBJECTS, and to format them into string $STR using format $FORMAT. The format specification for mapslots/4 is the same as for the C language sprintf() function. The expressions given in $EXPRS are compiled and evaluated at the moment the primitive is called, each time mapslots/4 is called. Within these expressions, the objects from $OBJECTS can be referenced as $1, $2,... for the first, second,... element of the object list. The values resulting from the evaluation of the expressions, have to be compliant with the specified format. Incompatible expression evaluation results, can cause a crash of the cell.

mapslots/4 example
$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.

mapslots/3 format a series of expressions that refer to objects into a string


$STR=mapslots($OBJECTS,$EXPRS)

Table 115
Argument $OBJECTS $EXPRS $STR

mapslots/3 arguments
Mode input input output Type LIST_OF OBJECT LIST_OF STRING STRING Description specifies the list of event or data objects specifies the format and expressions to be evaluated 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.

Chapter 3

Master Rule Language (MRL) reference

129

Time stamp functions

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.

Time stamp functions


time_stamp/1 retrieve the current time
time_stamp($TIME) $TIME=time_stamp()

Table 116
$TIME

time_stamp/1 arguments
Type INTEGER Description time stamp for the current time output

Argument Mode

Use time_stamp/1 to retrieve the current system time as a time stamp in $TIME.

130

BMC Impact Solutions Knowledge Base Development Reference Guide

Time stamp functions

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 117
$TIME $CIM

time_stamp_to_cim/2 arguments
Type INTEGER STRING Description specifies the time stamp to be converted time stamp in CIM format input output

Argument Mode

Use time_stamp_to_cim/2 to convert a time stamp given in $TIME to a string $CIM containing the time stamp in CIM (Common Information Model) format. The CIM format is YYYYMMDDhhmmssuuuuuu+zzz, where:
YYYY MM DD hh mm ss uuuuuu + zzz Year (including century) Month (1..12) Day of month (1..31) Hour (0..23) Minutes (0..59) Seconds (0..61) (value >59 in case of leap seconds) Micro-seconds (0..999999) Time zone offset direction from UTC (+ or -) Time zone offset from UTC in minutes

time_stamp_to_cim/2 example
$CIM = time_stamp_to_cim(time_stamp());

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)

Chapter 3

Master Rule Language (MRL) reference

131

Time stamp functions

Table 118
$TIME $FORMAT $STR

time_stamp_to_str/3 arguments
Type INTEGER STRING STRING Description specifies the time stamp to be converted specifies the format for the time stamp time stamp in specified format input input output

Argument Mode

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.

time_stamp_to_str/2 convert a time stamp to the format default


time_stamp_to_str($TIME,$STR) $STR=time_stamp_to_str($TIME)

Table 119
$TIME $STR

time_stamp_to_str/2 arguments
Type INTEGER STRING Description specifies the time stamp to be converted time stamp in the specified format input output

Argument Mode

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.

132

BMC Impact Solutions Knowledge Base Development Reference Guide

tamroFetaD

Time stamp functions

time_extract/3 retrieve fields from a time stamp


time_extract($TIME,$FLDS,$VALS) $VALS=time_extract($TIME,$FLDS)

Table 120 time_extract/3 arguments


Argument Mode $TIME $FLDS $VALS input input output Type INTEGER
s s s s

Description specifies the time stamp from which a field or list of fields are to be retrieved specifies the field or list of fields to be retrieved retrieved field value or list of retrieved field values

STRING LIST_OF STRING INTEGER LIST_OF INTEGER

Use time_extract/3 to retrieve one or more fields as specified in $FLDS from the time stamp $TIME into the $VALS argument. The time stamp is a time value in internal numeric form, similar to the
date_reception slot, or as retrieved from the time_stamp/1 primitive. The fields

retrieved from the time stamp reflect the local actual time zone of the system on which the cell is running. Time stamp fields are indicated by name. Available fields are:
date time year month day wday yday hour min sec Date part as an integer of the form YYYYMMDD Time part as an integer of the form HHMMSS Year (including century) Month (1..12) Day of month (1..31) Day of week (0..6, 0=Sunday) Day of year (1..366) Hour (0..23) Minutes (0..59) Seconds (0..61) (value >59 in case of leap seconds)

All returned field values are integer numbers. Note that the values for the date and time fields are also integers, structured in a fixed decimal format. A time value will not always have six significant digits. Times before 10:00:00 only have five significant decimal digits. The $VALS argument can be specified as one variable that will get the single requested field value or a list containing all requested field values. $VALS can also be specified as a list of as many variables as the number of requested fields.

Chapter 3

Master Rule Language (MRL) reference

133

Time stamp functions

time_extract/3 example
time_extract($E.date_reception,[date,time],[$DT,$TM]);

Variables $DT and $TM will contain the date and time of the time stamp, as integers, for the time the event was received. For instance, if the event was received on 6-Feb2007 at 9:15:20, $DT would be 20070206 and $TM would be 91520.

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)

Table 121 str_to_time_stamp/3 arguments


Argument Mode $STR $FORMAT $TIME input input output Type STRING STRING INTEGER Description specifies a time stamp represented as text specifies the format to which the time stamp is to be converted 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:
s

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.

134

BMC Impact Solutions Knowledge Base Development Reference Guide

List operations

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.

List operations
listlen/2 determine the length of a list
listlen($LIST,$LEN) $LEN=listlen($LIST)

Table 122 listlen/2 arguments


Argument Mode $LIST $LEN input output Type LIST_OF ANY INTEGER Description specifies the list for which the length is to be determined 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)

Chapter 3

Master Rule Language (MRL) reference

135

List operations

Table 123 listgetelt/3 arguments


Argument Mode $LIST $POS $ELEM input input Type Description LIST_OF ANY specifies the list from which the element in the specified location is to be retrieved INTEGER specifies of the position of requested element element at the specified position in list

output ANY

Use listgetelt/3 to retrieve the element at position $POS in list $LIST and return it into $ELEM. The first element in the list is numbered as 1.

listgetelt/3 example
$BAD_SLOT2=listgetelt($E.mc_bad_slot_names,2);

listmember/2 verify that an element is included in a list


listmember($LIST,$ELEM)

Table 124 listmember/2 arguments


Argument Mode $LIST $ELEM input input Type Description LIST_OF ANY specifies the list in which the presence of an element is to be verified 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)

136

BMC Impact Solutions Knowledge Base Development Reference Guide

List operations

Table 125 listdelete/3 arguments


Argument Mode $LIST1 $ELEM $LIST input input Type Description LIST_OF ANY specifies the list from which the element is to be removed ANY specifies the element to be removed

output LIST_OF ANY the list with the element removed from it

Use listdelete/3 to remove all occurrences of element $ELEM from list $LIST1 and place the resulting list into $LIST.

listdelete/3 example
$BAD_SLOTS=listdelete($E.mc_bad_slot_names,my_slot);

listappend/3 concatenate two lists


listappend($LIST1,$LIST2,$LIST) $LIST=listappend($LIST1,$LIST2)

Table 126 listappend/3 arguments


Argument Mode $LIST1 $LIST2 $LIST input input Type Description LIST_OF ANY specifies the first list to be concatenated LIST_OF ANY specifies the second list to be concatenated

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)

Chapter 3

Master Rule Language (MRL) reference

137

List operations

Table 127 listdisjoint/2 arguments


Argument Mode $LIST1 $LIST2 input input Type Description LIST_OF ANY specifies the first list to be compared 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.

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 128 listintersect/3 arguments


Argument Mode $LIST1 $LIST2 $LIST input input Type Description LIST_OF ANY specifies the first list to be compared LIST_OF ANY specifies the second list to be compared with the first 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.

138

BMC Impact Solutions Knowledge Base Development Reference Guide

List operations

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 129 listunion/3 arguments


Argument Mode $LIST1 $LIST2 $LIST input input Type Description LIST_OF ANY specifies the first list to be compared LIST_OF ANY specifies the second list to be compared with the first list

output LIST_OF ANY union of both lists

Use listunion/3 to construct a new list $LIST which is the union of lists $LIST1 and $LIST2. The union of $LIST1 and $LIST2 will include all the elements of both lists. If there are elements duplicated between the two lists, the duplicated elements will only be listed once in $LIST. If there are elements duplicated within a single list, those elements will be duplicated in the resulting list. For example, the union of these two lists:
$LIST1=[a,b,a,c] $LIST2=[b,d,e,e]

would be this list:


$LIST=[a,b,a,c,d,e,e]
s s s

$LISTcontains two a characters because $LIST1 has two a characters. $LISTcontains two e characters because $LIST2 has two e characters. $LISTcontains only one b because there is one b in $LIST1 and one b in $LIST2.

listunion/3 example
$MY_BAD_SLOTS=listunion($E.mc_bad_slot_names,[my_slot1,my_slot2]);

listsubtract/3 remove the elements that occur in one list from another list
listsubtract($LIST1,$LIST2,$LIST) $LIST=listsubtract($LIST1,$LIST2)

Chapter 3

Master Rule Language (MRL) reference

139

List operations

Table 130 listsubtract/3 arguments


Argument Mode $LIST1 $LIST2 $LIST input input output Type LIST_OF ANY LIST_OF ANY LIST_OF ANY Description specifies the list from which elements are to be removed specifies the list of elements that are to be removed from $LIST1 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]);

listremdup/2 remove duplicate elements from a list


listremdup($LIST1,$LIST) $LIST=listremdup($LIST1)

Table 131 listremdup/2 arguments


Argument Mode $LIST1 $LIST input output Type LIST_OF ANY LIST_OF ANY Description specifies the list from which duplicate elements are to be removed 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)

140

BMC Impact Solutions Knowledge Base Development Reference Guide

List operations

Table 132 listwalk/2 arguments


Argument Mode $LIST $ELEM input output Type Description LIST_OF ANY specifies the list for which each element is to be executed against 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.

add_to_list/2 add an element at the beginning of a list slot


add_to_list($ELEM,$LISTSLOT)

Table 133 add_to_list/2 arguments


Argument $ELEM $LISTSLOT Mode input input Type ANY SLOTREF Description specifies the element to add to the list 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.

Chapter 3

Master Rule Language (MRL) reference

141

Match table lookup primitives

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 134 rem_from_list/2 arguments


Argument $ELEM $LISTSLOT Mode input input Type ANY SLOTREF Description specifies the element to be removed from the list 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);

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 135 find_match/5 arguments


Argument $TBLNAME $TAG Mode input input Type STRING STRING Description specifies the class name of the match table specifies the tag to identify the requested part of the match table

142

BMC Impact Solutions Knowledge Base Development Reference Guide

Match table lookup primitives

Table 135 find_match/5 arguments


Argument $VALUES $OBJECTS $RESULTS Mode input input output Type LIST_OF STRING LIST_OF OBJECT LIST_OF STRING Description specifies the values to be matched as inputs specifies the objects to be used for evaluation of the output expressions 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:
s

A match for the nth element has precedence over a match for the n+1th element. If there are matches on the same element, the match operators are ordered, in decreasing precedence, as: equals, has_prefix, has_suffix, contains, any. If there are multiple has_prefix matches on the same element, the longest prefix takes precedence. If there are multiple has_suffix matches on the same element, the longest suffix takes precedence. If there are multiple contains matches on the same element, the longest string takes precedence. If there are multiple contains matches with same string length on the same element, the match closest to the beginning of the string takes precedence.

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.


Chapter 3 Master Rule Language (MRL) reference 143

Match table lookup primitives

During evaluation of the output expressions, instances from $OBJECTS can be referenced. These references are indicated as $1, $2,... in the output expression to refer to the first, second,... element of $OBJECTS. Each object passed in $OBJECTS must be an instance of the class specified at the same position in the slot ref_instances_classes of the matching entry.

find_match/5 example
In this example, there are several instances of BEM_MATCH_TABLE, including the following:
BEM_MATCH_TABLE; tag=t1; input_match=[<SERVICE>,<svc_>*]; ref_instances_classes=[EVENT,DATA]; output_expressions=[sprintf("Service %s (%s) changed to %s", [$1.mc_object,$2.description,$1.mc_parameter_value]),MINOR]; END

In this example, the KB contains data objects that provide a description of registered services. A rule that handles service-related events can look up the data object for the service, returned in $D in the following piece of code, while the event is referenced through $E.
find_match(BEM_MATCH_TABLE,t1,[$E.mc_object_class,$E.mc_object], [$E,$D],[$MSG,$SEV]); $E.msg = $MSG; $E.severity = $SEV;

If the mc_object_class of the event has the value SERVICE, and its mc_object starts with svc_, the call of find_match/5 will match with the BEM_MATCH_TABLE entry shown above. The event and data object references are passed through the fourth argument. They are referred to in the output expressions as $1 and $2 respectively. Evaluation of the two output expressions returns a message into $MSG and a severity in $SEV. The severity is a constant value. The message is produced by filling in some slots from the event (mc_object and mc_parameter_value) and the description slot of the data object in a message format.

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)

144

BMC Impact Solutions Knowledge Base Development Reference Guide

Match table lookup primitives

Table 136 find_match_entry/4 arguments


Argument $TBLNAME $TAG $VALUES $ENTRY Mode input input input output Type STRING STRING Description specifies the class name of the match table specifies the tag to identify the requested part of the match table matching entry

LIST_OF STRING specifies the values to be matched as inputs OBJECT

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

find_match_entry/4 example
In this example, there are several instances of BEM_MATCH_TABLE, including the following:
BEM_MATCH_TABLE; tag=t1; input_match=[<SERVICE>,<svc_>*]; ref_instances_classes=[EVENT,DATA]; output_expressions=[sprintf("Service %s (%s) changed to %s", [$1.mc_object,$2.description,$1.mc_parameter_value]),MINOR]; END

In this example, the KB contains data objects that provide a description of registered services. A rule that handles service-related events can look up the data object for the service, returned in $D in the following piece of code, while the event is referenced through $E.
$M = find_match_entry(BEM_MATCH_TABLE,t1, [$E.mc_object_class,$E.mc_object]);

This call will return a reference to the match table entry in $M.

Chapter 3

Master Rule Language (MRL) reference

145

Match table lookup primitives

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 137 apply_match_entry/4 arguments


Argument $ENTRY $VALUES $OBJECTS $RESULTS Mode input input input Type OBJECT LIST_OF OBJECT Description specifies the match table entry specifies the objects to be used for evaluation of output expressions

LIST_OF STRING specifies the values to be matched as inputs

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

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

146

BMC Impact Solutions Knowledge Base Development Reference Guide

Object slot manipulation

In this example, the KB contains data objects that provide a description of registered services. A rule that handles service-related events can look up the data object for the service, returned in $D in the following piece of code, while the event is referenced through $E.
$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)

Table 138 get_list_slotvalues/3 arguments


Argument Mode Type Description $OBJECTS input $SLOTS $VALUES input LIST_OF OBJECT specifies the list of objects from which a slot list is to be retrieved LIST_OF STRING specifies the list of slots to be retrieved from $OBJECTS resulting list of slot values

output LIST_OF_ STRING

Use get_list_slotvalues/3 to retrieve one or more of the slots specified in the $SLOTS list from the objects in $OBJECTS. The resulting slots are returned in the $VALUES list.

Chapter 3

Master Rule Language (MRL) reference

147

Object slot manipulation

The desired slots must be specified in $SLOTS by name, or by reference to an object and the slot name. A reference to a slot of an object has the form $n.SlotName, where n is the sequence number of the desired object in $OBJECTS. If the slot is only mentioned by name and no object reference, it is taken from the first object in the list.

get_list_slotvalues/3 example
$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 139 set_list_slotvalues/3 arguments


Argument $OBJECTS $SLOTS $VALUES Mode input input input Type LIST_OF OBJECT LIST_OF STRING LIST_OF ANY Description list of objects list of desired slots 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. 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.

148

BMC Impact Solutions Knowledge Base Development Reference Guide

Specific slot manipulation

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 140 class_path/2 arguments


Argument Mode $CLASS $PATH input Type STRING Description specifies the name of the class for which the hierarchy is to be determined

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

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)

Chapter 3

Master Rule Language (MRL) reference

149

Specific slot manipulation

Table 141 reset_default/1 arguments


Argument Mode $SLOT input Type SLOTREF Description 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 142 ntadd/2 arguments


Argument Mode $EVENT $SLOT input input Type OBJECT STRING Description specifies the event to which a note will be added 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);

ntcnt/2 count the notes attached to an event


ntcnt($EVENT,$COUNT)

Table 143 ntcnt/2 arguments


Argument Mode $EVENT $COUNT input output Type OBJECT INTEGER Description specifies the event for which notes are to be counted number of notes attached to event

150

BMC Impact Solutions Knowledge Base Development Reference Guide

Specific slot manipulation

Use ntcnt/2 to count the notes that are attached to event $EVENT, in $COUNT.

ntcnt/2 example
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 144 ntget/5 arguments


Argument $EVENT $SEQNR $TIME $AUTHOR $TEXT Mode input input output output output Type OBJECT Description specifies the event for which a note is to be retrieved

INTEGER specifies the sequence number of the desired note INTEGER time stamp of the note STRING STRING author of the note text of the note

Use ntget/5 to obtain the note at the $SEQNR position that is attached to event $EVENT. The time stamp is returned in $TIME, the author is returned in $AUTHOR, and the text of the note is returned in $TEXT. Notes are numbered, starting from 1 for the oldest note. The most recent note can be obtained by specifying 0 as sequence number $SEQNR. To determine the number of notes attached to an event, see ntcnt/2 count the notes attached to an event on page 150.

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)

Chapter 3

Master Rule Language (MRL) reference

151

Specific slot manipulation

Table 145 ntset/3 arguments


Argument Mode $EVENT $SEQNR $TEXT input input input Type OBJECT INTEGER STRING Description specifies the event for which the note text is to be modified specifies the sequence number of the desired note 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 146 opadd/4 arguments


Argument Mode $EVENT $POLICY $ACTION $ARGS input input input input Type OBJECT STRING STRING STRING Description specifies the event to which to add an operation specifies the policy name of the operation to be added specifies the action name of the operation specifies the arguments for operation action

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.
152 BMC Impact Solutions Knowledge Base Development Reference Guide

Specific slot manipulation

opadd/4 example
opadd($E,Policy1,Data Enrichment,);

opadd/3 add an operation to an event


opadd($EVENT,$ACTION,$ARGS)

Table 147 opadd/3 arguments


Argument Mode $EVENT $ACTION $ARGS input input input Type OBJECT STRING STRING Description specifies the event to which to add an operation specifies the action name of the operation 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)

Table 148 opcnt/2 arguments


Argument Mode $EVENT $COUNT input Type OBJECT Description specifies the event for which operations are to be counted

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.

Chapter 3

Master Rule Language (MRL) reference

153

Specific slot manipulation

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 149 opget/7 arguments


Argument Mode $EVENT $SEQNR $TIME $AUTHOR $POLICY $ACTION $ARGS input input output output output output output Type OBJECT INTEGER INTEGER STRING STRING STRING STRING Description specifies the event for which to retrieve an operation specifies the sequence number of the desired operation time stamp of the operation author of the operation policy name of the operation action name of the operation 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 153.

opget/7 example
opget($E,0,$TIME,$AUTHOR,$POLICY,$ACTION,$ARGS);

opget/6 retrieve an operation of an event


opget($EVENT,$SEQNR,$TIME,$AUTHOR,$ACTION,$ARGS)

154

BMC Impact Solutions Knowledge Base Development Reference Guide

Specific slot manipulation

Table 150 opget/6 arguments


Argument Mode $EVENT $SEQNR $TIME $AUTHOR $ACTION $ARGS input input output output output output Type OBJECT INTEGER INTEGER STRING STRING STRING Description specifies the event for which to retrieve an operation specifies the sequence number of the desired operation time stamp of the operation author of the operation action name of the operation 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 153.

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 151 opget_time/3 arguments


Argument Mode $EVENT $SEQNR $TIME input input output Type OBJECT INTEGER INTEGER Description specifies the event for which to retrieve an operation specifies the sequence number of the desired operation 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. Operations are numbered, starting from 1 for the oldest operation. The most recent operation can be obtained by indicating 0 as sequence number.

Chapter 3

Master Rule Language (MRL) reference

155

Specific slot manipulation

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 152 opget_author/3 arguments


Argument Mode $EVENT $SEQNR $AUTHOR input input output Type OBJECT INTEGER STRING Description specifies the event for which to retrieve an operation specifies the sequence number of the desired operation 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 153.

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 153 opget_action/3 arguments


Argument Mode $EVENT $SEQNR $ACTION input input output Type OBJECT INTEGER STRING Description specifies the event for which to retrieve an operation specifies the sequence number of the desired operation action name of the operation

Use opget_action/3 to obtain the action name of operation $SEQNR that is attached to event $EVENT and return the value in $ACTION.

156

BMC Impact Solutions Knowledge Base Development Reference Guide

Specific slot manipulation

Operations are numbered, starting from 1 for the oldest operation. The most recent operation can be obtained by indicating 0 as the sequence number $SEQNR. To determine the number of operations attached to an event, see opcnt/2 count the operations of an event on page 153.

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 154 opget_args/3 arguments


Argument Mode $EVENT $SEQNR $ARGS input input output Type OBJECT INTEGER STRING Description specifies the event for which to retrieve an operation specifies the sequence number of the desired operation 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 153.

opget_args/3 example
$ARGS=opget_args($E,0);

opset/5 modify the policy name, action, and arguments of an operation of an event
opset($EVENT,$SEQNR,$POLICY,$ACTION,$ARGS)

Chapter 3

Master Rule Language (MRL) reference

157

Specific slot manipulation

Table 155 opset/5 arguments


Argument Mode $EVENT $SEQNR $POLICY $ACTION $ARGS input input input input input Type OBJECT STRING STRING STRING Description specifies the event for which an operation is to be modified new policy name of the operation new action name of the operation new arguments for the operation action

INTEGER specifies the sequence number of the desired operation

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

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 156 opset/4 arguments


Argument Mode $EVENT $SEQNR $ACTION $ARGS input input input input Type OBJECT INTEGER STRING STRING Description specifies the event for which an operation is to be modified specifies the sequence number of the desired operation new action name of the operation new arguments for the operation action

158

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

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 157 relate/1 arguments


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

Chapter 3

Master Rule Language (MRL) reference

159

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 158 unrelate/1 arguments


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

160

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 159 cellinfo/2 arguments


Argument Mode $FIELD $INFO input Type STRING Description specifies the desired information item to be retrieved retrieved cell information

output STRING LIST_OF STRING

Chapter 3

Master Rule Language (MRL) reference

161

Operation environment inquiry

Use cellinfo/2 to obtain information item specified in $FIELD and return the information in $INFO. The following information fields are defined:
HomeDir HostName IPAddress Platform CellName CellRelease CellBuild CellDate Param LogDir Location TmpDir KBDir DirFile ConfigFile TraceDestination home directory of the cell name of the host machine on which cell is running IP address of the host machine on which cell is running platform identifier of the host machine on which cell is running name of the cell release version of the cell build number of this version of the cell build date of this version of the cell log directory of the cell temporary directory of the cell KB directory of the cell directory file (mcell.dir) of the cell configuration file of the cell list of defined trace destination files (of the type LIST_OF STRING) value of configuration parameter

IP address or port number of the cell service

cellinfo/2 example
$E.mc_host = cellinfo(HostName);

cellcontrol/1 perform a cell control command


cellcontrol($COMMAND)

Table 160 cellcontrol/1 arguments


Argument $COMMAND Mode input Type STRING Description control command to be performed

Use cellcontrol/1 to perform the control command specified in $COMMAND.

162

BMC Impact Solutions Knowledge Base Development Reference Guide

mara P

Operation environment inquiry

The following commands are defined:


stop shutdown standby pause start reload statbld terminate the cell normally terminate the cell as quickly as possible switch operation mode to standby switch operation mode to pause (no longer accepting new events) switch operation mode back to normal reload the cell configuration 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 161 kbversion/2 arguments


Argument $MODULE $VERSION Mode input output Type STRING STRING Description specifies identifier for the KB module 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.

Chapter 3

Master Rule Language (MRL) reference

163

Operation environment inquiry

kbversion/2 example
kbversion(TroubleTicketing,$VERSION);

kbversion/1 retrieve global Knowledge Base module version information


kbversion($VERSION) $VERSION=kbversion()

Table 162 kbversion/1 arguments


Argument $VERSION Mode output Type STRING Description 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 163 get_env/2 arguments


Argument Mode $ENVVAR $VALUE input output Type STRING STRING Description specifies the environment variable name for which the value is to be retrieved 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.

164

BMC Impact Solutions Knowledge Base Development Reference Guide

Propagation

get_env/2 example
$HOME = get_env(HOME);

Propagation
send_to/2 send an event to another cell or gateway
send_to($DEST,$EVENT)

Table 164 send_to/2 arguments


Argument Mode Type $DEST $EVENT input
s s

Description

STRING specifies a single destination or a list of possible LIST_OF STRING destinations for the event specifies the event to send

input OBJECT

Use send_to/2 to send event $EVENT to destination $DEST. The destination must be specified by name. If $DEST is a list of destination names, the event modification is sent to the first destination that can be reached. When sending an event with send_to/2, event modifications will not be propagated automatically, either forward or backward.

send_to/2 example
send_to([Cell2,Cell3],$E);

send_to/3 send an event modification to another cell or gateway


send_to($DEST,$EVENT,$SLOTS)

Table 165 send_to/3 arguments


Argument Mode $DEST $EVENT $SLOTS input input input Type
s s

Description

STRING specifies a single destination or a list of possible LIST_OF STRING destinations for the event specifies the event to send specifies a list of modified slots to send

OBJECT LIST_OF STRING

Chapter 3

Master Rule Language (MRL) reference

165

Propagation

Use send_to/3 to send modifications of slots $SLOTS of event $EVENT to destination $DEST. The destination must be specified by name. If $DEST is a list of destination names, the event is sent to the first destination that can be reached. Only the slots that are explicitly indicated will be sent to the destination, in the form of an event modification.

send_to/3 example
send_to([Cell2,Cell3],$E,[status,severity]);

send_to_ext/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 166 send_to_ext/4 arguments


Argument Mode $DEST $EVENT $SLOTS $VALS input input input input Type
s s

Description specifies a single destination or a list of possible destinations for the event specifies the event to send specifies a list of extended slot names to send specifies a list of extended slot values to send

STRING LIST_OF STRING

OBJECT LIST_OF STRING LIST_OF STRING

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.

166

BMC Impact Solutions Knowledge Base Development Reference Guide

Service model inquiry

When sending an event with send_to_ext/4, event modifications will not be propagated automatically, either forward or backward.

send_to_ext/4 example
send_to_ext([Cell2,Cell3],$E,[slot1,slot2],[value1,value2]);

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 167 smcomps/5 arguments


Argument $PARMNAMES $PARMVALS $COMPS1 $SHADOW $COMPS2 Mode input input output output output Type Description LIST_OF STRING list of parameter names LIST_OF STRING list of parameter values LIST_OF OBJECT list of primary search components LIST_OF OBJECT list of shadow components LIST_OF OBJECT list of secondary search components

Use the smcomps/5 primitive to return a list of pointers to the components that are in the impact path or the cause path of a selected component. Various parameters can be used to refine that list. The smcomps/5 primitive makes it possible to retrieve, manage and propagate a list of impacted components or causal components from within the rules of a Knowledge Base.

NOTE
You can also retrieve root causes using MC_SM_ROOT_CAUSE instead of smcomps.

Chapter 3

Master Rule Language (MRL) reference

167

Service model inquiry

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.

The two parameter liststhe $PARMNAMES list that contains only the names of the parameters and the $PARMVALS list that contains the values corresponding to the parameters named in $PARMNAMES in the same orderdetermines the search behavior. Available parameter names and possible values are:
comp dir impact events ext leaf type mc_udid of the focus Service Model component data object. Default value is 0; therefore you must enter a valid value for this parameter. where =cause and =impact. Default direction value is . where =true impact and =possible impact. Default impact type is .

where =True and =False. Default value is F (it is not requested that the components have attached events).

where =True and =False. Default value is F (extended search is not turned on). where =True and =False. Default value is F (leaf nodes are not required). component class name. Default is the BMC_BaseElement class.

The smcomps primitive retrieves components, starting with the focus component identified by comp, in direction specified by dir. The other parameters influence whether or not a component is included in the result, and whether or not the search is continued. A component is included if each of the following conditions hold:
s

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:


s

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

168

BMC Impact Solutions Knowledge Base Development Reference Guide

F F

T t c T T

F | T p | t i | c F | T F | T

License key functions

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. 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 168 key_version/2 arguments


Argument $KEY $VERSION Mode input output Type STRING Description specifies the license key

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.

Chapter 3

Master Rule Language (MRL) reference

169

License key functions

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.

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 169 key_verify/2 arguments


Argument Mode $KEY $FIELDS input output Type STRING LIST_OF STRING Description specifies the license key 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)

170

BMC Impact Solutions Knowledge Base Development Reference Guide

Time frame operations

Table 170 key_verify/3 arguments


Argument Mode $KEY $FIELDS $VALID input output output Type STRING INTEGER Description specifies the license key key validity (0=invalid, 1=valid)

LIST_OF STRING list of fields from key

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

tf_active/1 arguments
Mode input Type
s s s s

Description
s s s s

$TIMEFRAME

STRING LIST_OF STRING OBJECT LIST_OF OBJECT

time frame name list of time frame names time frame object list of time frame objects

Use tf_active/1 to determine whether the time frame(s) $TIMEFRAME is active at the current moment.

Chapter 3

Master Rule Language (MRL) reference

171

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 172 tf_active/2 arguments


Argument $TIMEFRAME Mode input Type
s s s s

Description
s s s s

STRING LIST_OF STRING OBJECT LIST_OF OBJECT

time frame name list of time frame names time frame object list of time frame objects

$TIME

input

INTEGER

time to check activity

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)

172

BMC Impact Solutions Knowledge Base Development Reference Guide

Time frame operations

Table 173 tf_udid_active/1 arguments


Argument $TIMEFRAME Mode input Type
s s

Description
s s

STRING LIST_OF STRING

time frame mc_udid 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 174
Argument

tf_udid_active/2 arguments
Mode input input Type
s s

Description
s s

$TIMEFRAME $TIME

STRING LIST_OF STRING

time frame mc_udid mc_udid list for multiple time frames

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.

Chapter 3

Master Rule Language (MRL) reference

173

Time frame operations

tf_udid_active/2 example
if ( tf_udid_active([TF.001,TF.002],$TIME) ) then ...

tf_current_start/2 obtain the start time of the current active interval of a time frame
tf_current_start($TIMEFRAME,$START) $START=tf_current_start($TIMEFRAME)

Table 175 tf_current_start/2 arguments


Argument $START Mode output Type OBJECT INTEGER Description specifies the time frame object start time of current active interval $TIMEFRAME input

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

tf_current_start/3 arguments
Mode input input output Type OBJECT Description specifies the time frame object

$TIMEFRAME $TIME $START

INTEGER specifies the time for the active interval INTEGER start time of active interval at given time

Use tf_current_start/3 to obtain the start time of the active interval at $TIME, of time frame $TIMEFRAME in $START. A 0 value is returned if the indicated time frame is not active at the given time.

174

BMC Impact Solutions Knowledge Base Development Reference Guide

Time frame operations

tf_current_start/3 example
$START = tf_current_start($TF,$TM);

tf_current_end/2 obtain the end time of the current active interval of a time frame
tf_current_end($TIMEFRAME,$END) $END=tf_current_end($TIMEFRAME)

Table 177 tf_current_end/2 arguments


Argument $TIMEFRAME $END Mode input output Type OBJECT INTEGER Description specifies the time frame object 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 178 tf_current_end/3 arguments


Argument $TIME $END Mode input output Type OBJECT INTEGER INTEGER Description specifies the time frame object specifies the time for the active interval end time of active interval at given time $TIMEFRAME input

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.

Chapter 3

Master Rule Language (MRL) reference

175

Time frame operations

tf_current_end/3 example
$END = tf_current_end($TF,$TM);

tf_current_interval/2 obtain the start and end time of the current active interval of a time frame
tf_current_interval($TIMEFRAME,$INTV) $INTV=tf_current_interval($TIMEFRAME)

Table 179 tf_current_interval/2 arguments


Argument $INTV Mode output Type OBJECT Description specifies the time frame object $TIMEFRAME input

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 180 tf_current_interval/3 arguments


Argument $TIME $INTV Mode input Type OBJECT INTEGER Description specifies the time frame object specifies the time for the active interval $TIMEFRAME input

output LIST_OF INTEGER start and end time of active interval at the specified time

176

BMC Impact Solutions Knowledge Base Development Reference Guide

Time frame operations

Use tf_current_interval/3 to obtain the start and end time of the active interval at $TIME of time frame $TIMEFRAME in $END. Argument $INTV of the primitive, has to be specified as a list of two variables. A [0,0] value is returned if the indicated time frame is not active at the given time.

tf_current_interval/3 example
tf_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 181 tf_prev_start/2 arguments


Argument $START Mode output Type OBJECT INTEGER Description specifies the time frame object start time of previous active interval $TIMEFRAME input

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)

Chapter 3

Master Rule Language (MRL) reference

177

Time frame operations

Table 182 tf_prev_start/3 arguments


Argument $TIME $START Mode input Type OBJECT Description specifies the time frame object $TIMEFRAME input

INTEGER specifies the time for the active interval

output INTEGER start time of previous active interval at the specified time

Use tf_prev_start/3 to obtain the start time of the previous active interval at $TIME, of time frame $TIMEFRAME in $START. A 0 value is returned if there is no previous active time frame at the given time.

tf_prev_start/3 example
$START = tf_prev_start($TF,$TM);

tf_prev_end/2 obtain the end time of the previous active interval of a time frame
tf_prev_end($TIMEFRAME,$END) $END=tf_prev_end($TIMEFRAME)

Table 183 tf_prev_end/2 arguments


Argument $TIMEFRAME $END Mode input output Type OBJECT INTEGER Description specifies the time frame object 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.

178

BMC Impact Solutions Knowledge Base Development Reference Guide

Time frame operations

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 184 tf_prev_end/3 arguments


Argument $TIMEFRAME $TIME $END Mode input input Type OBJECT Description specifies the time frame object

INTEGER specifies the time for the active interval

output INTEGER end time of previous active interval at the specified time

Use tf_prev_end/3 to obtain the end time of the previous active interval at $TIME, of time frame $TIMEFRAME in $END. A 0 value is returned if there is no previous active time frame at the given time.

tf_prev_end/3 example
$END = tf_prev_end($TF,$TM);

tf_prev_interval/2 obtain the start and end time of the previous active interval of a time frame
tf_prev_interval($TIMEFRAME,$INTV) $INTV=tf_prev_interval($TIMEFRAME)

Table 185 tf_prev_interval/2 arguments


Argument $INTV Mode Type OBJECT Description specifies the time frame object $TIMEFRAME input

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.

Chapter 3

Master Rule Language (MRL) reference

179

Time frame operations

Argument $INTV of the primitive, has to be specified as a list of two variables. A [0,0] value is returned if there is no previous active time frame.

tf_prev_interval/2 example
tf_prev_interval($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 186 tf_prev_interval/3 arguments


Argument $TIMEFRAME $TIME $INTV Mode input input Type OBJECT INTEGER Description specifies the time frame object specifies the time for the active interval start and end time of previous active interval at given time

output LIST_OF INTEGER

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)

180

BMC Impact Solutions Knowledge Base Development Reference Guide

Time frame operations

Table 187 tf_next_start/2 arguments


Argument $TIMEFRAME $START Mode input output Type OBJECT INTEGER Description specifies the time frame object 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)

Table 188 tf_prev_start/3 arguments


Argument $TIME $START Mode input output Type OBJECT INTEGER INTEGER Description specifies the time frame object specifies the time for the active interval start time of next active interval at given time $TIMEFRAME input

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)

Chapter 3

Master Rule Language (MRL) reference

181

Time frame operations

Table 189 tf_next_end/2 arguments


Argument $END Mode output Type OBJECT INTEGER Description specifies the time frame object end time of next active interval $TIMEFRAME input

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)

Table 190 tf_next_end/3 arguments


Argument $TIME $END Mode input output Type OBJECT INTEGER INTEGER Description specifies the time frame object specifies the time for the active interval end time of next active interval at the specified time $TIMEFRAME input

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)

182

BMC Impact Solutions Knowledge Base Development Reference Guide

Time frame operations

Table 191 tf_next_interval/2 arguments


Argument $TIMEFRAME $INTV Mode input Type OBJECT Description specifies the time frame object

output LIST_OF INTEGER start and end time of next active interval

Use tf_next_interval/2 to obtain the start and end time of the next active interval of time frame $TIMEFRAME in $INTV. Argument $INTV of the primitive, has to be specified as a list of two variables. A [0,0] value is returned if there is no next active time frame.

tf_next_interval/2 example
tf_next_interval($TF,[$START,$END]);

tf_next_interval/3 obtain the start and end time of the next active interval of a time frame at a specified time
tf_next_interval($TIMEFRAME,$TIME,$INTV) $INTV=tf_next_interval($TIMEFRAME,$TIME)

Table 192 tf_next_interval/3 arguments


Argument $TIMEFRAME $TIME $INTV Mode input input output Type OBJECT INTEGER Description specifies the time frame object specifies the time for the active interval

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.

Chapter 3

Master Rule Language (MRL) reference

183

Time frame operations

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 193 tf_duration/3 arguments


Argument $TIMEFRAME $START $DURATION Mode input input output Type OBJECT INTEGER INTEGER Description specifies the time frame object specifies the start of the period during which active interval duration is to be calculated total active interval duration from the time specified in $START until the current time

Use tf_duration/3 to calculate the total duration in $DURATION of all active intervals of time frame $TIMEFRAME over the period starting at $START and ending at the current time.

tf_duration/3 example
$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 194 tf_duration/4 arguments


Argument $START Mode input Type OBJECT INTEGER Description specifies the time frame object specifies the start of the period during which active interval duration is to be calculated $TIMEFRAME input

184

BMC Impact Solutions Knowledge Base Development Reference Guide

Object creation and deletion

Table 194 tf_duration/4 arguments


Argument $END $DURATION Mode input Type INTEGER Description specifies the end of the period during which active interval duration is to be calculated total active interval duration over the specified period

output INTEGER

Use tf_duration/4 to calculate the total duration in $DURATION, of all active intervals of time frame $TIMEFRAME over the period starting at $START and ending at $END.

tf_duration/4 example
$DURATION = tf_duration($TF,$TM0,$TM1);

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)

Table 195 generate_event/2 arguments


Argument Mode $CLASS $SLOTS input input Type STRING Description specifies the event class name

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.

Chapter 3

Master Rule Language (MRL) reference

185

Object creation and deletion

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 196 new_data/3 arguments


Argument Mode $CLASS $SLOTS $OBJECT input input output Type STRING OBJECT Description specifies the data class for the new object new data object

LIST_OF ANY specifies the list of slot settings for the new object

Use new_data/3 to generate a new data object $OBJECT of class $CLASS with slot settings as specified in $SLOTS. The value of the $SLOTS argument must be a list of elements of the form SlotName=Value. A handle for the new data object is returned in $OBJECT.

new_data/3 example
new_data($DATA,CUSTOM_DATA,[mc_udid=$ID,myslot=$VAL]);

remove_data/1 delete a data object


NOTE
This primitive cannot be used in refine, filter, regulate, or propagate rules.

remove_data($OBJECT)

186

BMC Impact Solutions Knowledge Base Development Reference Guide

Specific rule-based functions

Table 197 remove_data/1 arguments


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

Chapter 3

Master Rule Language (MRL) reference

187

Specific rule-based functions

drop_new/0 example
new RepeatTick: MC_CELL_TICK($E) updates duplicate($U) { $U.repeat_count = $U.repeat_count + 1; drop_new; } END

unset_cause/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)

188

BMC Impact Solutions Knowledge Base Development Reference Guide

Specific rule-based functions

Table 198 set_timer/3 arguments


Argument $OBJECT $DURATION $INFO Mode input input input Type OBJECT INTEGER STRING Description specifies the event object specifies the duration until timer expiration, in seconds 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. 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)

Chapter 3

Master Rule Language (MRL) reference

189

Specific rule-based functions

Table 199 set_timer_at/3 arguments


Argument Mode $OBJECT $TIME $INFO input input input Type OBJECT INTEGER STRING Description specifies the event object specifies the time stamp at which the timer will expire 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.

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 200 set_timer_at/4 arguments


Argument Mode $OBJECT $STR $FORMAT $INFO input input input input Type OBJECT STRING STRING STRING Description specifies the event object specifies the time stamp in textual representation at which the timer will expire specifies the format for the time stamp $STR 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.

190

BMC Impact Solutions Knowledge Base Development Reference Guide

Specific rule-based functions

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.

Chapter 3

Master Rule Language (MRL) reference

191

Specific rule-based functions

192

BMC Impact Solutions Knowledge Base Development Reference Guide

Chapter

4
195 195 196 197 197 198 199 199 200 201 202 202 202 203 204 204 206 207 208 208 211 212 213 214 215 216 217 217 219 219 221 221 222 223
193

Event rules and syntax


This chapter presents the following topics: Refine rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refine rule processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refine rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refine rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refine rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rule processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regulate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regulate rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Forms of the Regulate rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regulate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regulate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regulate rule examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . New rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . New rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . New rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . New rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abstract rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abstract rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abstract rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abstract rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlate rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execute rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execute rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execute rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execute rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Threshold rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Threshold rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 4 Event rules and syntax

Threshold rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Threshold rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Threshold rule examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Propagate rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Propagate rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Propagate rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Propagate rules examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Timer rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 Timer rule processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 Timer rule syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Timer rule primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Timer rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Delete rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Delete rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 Delete rule primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 Delete rule examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

194

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
s

s s

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 11 illustrates how a Refine rule processes incoming events. Figure 11 Refine rule processing
Incoming Event

Refine Rule (ECFs)

No Match

Match

event data is deleted

event data is retained

Chapter 4 Event rules and syntax

195

Refine rule syntax

Refine rule syntax


The syntax for the Refine rule is shown in Figure 12. Figure 12 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 the BMC Impact

Solutions Event Management Guide. Figure 13 shows the syntax of an event condition formula (ECF) definition for a Refine rule. Figure 13 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 the

BMC Impact Solutions Event Management Guide.

196

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
s

confirm_externalcalls a program to run on the cell and supplies all necessary

command-line arguments. If the primitive is successful the event continues to process, if it fails the event is dropped. For more information about the confirm_external primitive, see page 85.
s

get_externalruns 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 87. 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 76 for more information about rules and their assigned primitives.

Refine rule examples


In Figure 14, 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 14 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

Chapter 4 Event rules and syntax

197

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

PASSan event meets a defined condition passing to the next rule. NOPASSan event meets a defined condition and is dropped from the rule engine.

NOTE
To improve Filter rule processing, BMC Software recommends that you arrange Filter rules in an order of evaluation so that the rules that discard the most events occur first.

198

BMC Impact Solutions Knowledge Base Development Reference Guide

Filter rule processing

Filter rule processing


Figure 15 illustrates how a Filter rule processes an incoming event. Figure 15 Filter rule processing
Incoming Event

Filter Rule (ECFs)

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

# 1 2

Process description An incoming event is compared to the ECFs contained in the Filter rule. The event does not match any of the ECFs contained in the rule. a In NOPASS mode, the Filter rules forwards the event to the next Filter rule b In PASS mode, the Filter rule discards the event.

The event matches at least one of the ECFS contained in the rule. a In NOPASS mode, the Filter rule discards the event. b In PASS mode, the Filter rule forwards the event to the next Filter rule.

Filter rule syntax


Figure 16 shows the Filter rule syntax. Figure 16 Filter rule syntax

filter RuleName : PASS | NOPASS ECF ECF ... END

Chapter 4 Event rules and syntax

199

Filter rule primitives

Table 201 Filter rule syntax descriptions


filter RuleName keyword that specifies how the text in the rule is interpreted name of the rule Rule names should s be self-explanatory of their purpose s be unique across the Knowledge Base s contain only alphanumeric characters s utilize only the underscore character PASS | NOPASS ECF indicates what mode the Filter rule is using 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 17 is the syntax of an ECF definition included in a Filter rule. Figure 17 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 70 for more information about primitives.

200

BMC Impact Solutions Knowledge Base Development Reference Guide

Filter rule examples

Filter rule examples


In Figure 18 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 18 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 202 demonstrate how specific events are processed by the Filter rules f1 and f2 in the example in Figure 18. Table 202 f1 and f2 Filter rules event processing examples
Event Example LOGIN_SUCCESS; mc_host=clt1; severity=WARNING; END Filter Rule Process 1. The f1 filter discards the event because mc_host does not satisfy the condition. 2. The f2 filter discards the event because the event type is LOGIN_SUCCESS which matches the condition. 1. The f1 filter accepts the event because it is a The event is accepted for additional processing. login event. 2. The f2 filter accepts the event because its severity level is not INFO and it is not a successful login event. 1. The f1 filter discards the event because the The event is discarded. event does not originate from either the svr1 or svr2 host and is not a login event. 2. The f2 filter does not consider the event because it is discarded by the f1 filter. Result The event is discarded.

LOGIN_FAILURE; mc_host=clt1; severity=WARNING; END

SERVERS_LOGIN_ATTACK; mc_host=svr3; severity=CRITICAL; END

Chapter 4 Event rules and syntax

201

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

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.

202

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 righthand side of the equal sign can contain expressions.

In both forms, the Unless clause resets the time window. The time windows for the Hold and Unless clauses are sliding windows. After the Hold or Unless clause executes, all events in the window are dropped from consideration and the beginning point of the time window moves to the next event received for consideration. The time frame is specified in seconds, minutes, hours, or days.

Regulate rule syntax


The Regulate rule has two forms. Figure 19 shows the Form 1 Regulate rule syntax. Figure 19 Regulate rule syntax form 1

regulate RuleName : ECF hold #Events1 within TimeFrame2 send $FIRST | $LAST | $HISEV | $LOSEV [ unless #Events3 within TimeFrame4 close ] END

Figure 20 shows the Form 2 Regulate rule syntax. Figure 20 Regulate rule syntax Form 2

regulate RuleName : ECF hold #Events1 within TimeFrame2 send { Chapter 4 Event rules and syntax 203

Regulate rule primitives

Figure 20

Regulate rule syntax Form 2

ClassName ; SlotName = Value ; ... } [ unless #Events3 within TimeFrame4 close ] END

Figure 21 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 21 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 70 for more information about primitives.

Regulate rule examples


The purpose of the Regulate rule in Figure 22 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.

204

BMC Impact Solutions Knowledge Base Development Reference Guide

Regulate rule examples

Figure 22

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 23, 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 23 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 24 assumes that a dynamic data table has been designed and populated like the example. Figure 24 Regulate rule example 3

MC_DATA_CLASS : REGULATE_DATA ISA DATA DEFINES { rd_slot_str: STRING, key=yes; rd_slot_hold: INTEGER; rd_slot_hwithin: INTEGER; rd_slot_unless: INTEGER; rd_slot_uwithin: INTEGER; }; END

Chapter 4 Event rules and syntax

205

New rules

The Regulate rule in Figure 25 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 25 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:
s s s

displayed in the console returned by the MQUERY command referenced by Using or Update clauses in MRL

206

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.

Chapter 4 Event rules and syntax

207

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 208 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 187 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 76 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

208

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 updatedthe old value is replaced by the new one and the repeat_count is increasedand the new event is discarded. If a DISK_USED_PERCENTAGE event does not exist, the new event is not discarded. The new event enters the repository and is updated by subsequent duplicate events.

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.
Chapter 4 Event rules and syntax 209

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

210

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
s

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
s

mc_abstractions the abstracted from event, contains the list of abstraction, or high-level, events the low-level event generated mc_abstracted the abstract event, contains the list of abstracted from, or lowlevel, events that created the high-level event.

Chapter 4 Event rules and syntax

211

Abstract rule syntax

NOTE
Once an abstract event is created, the relationship cannot be removed.

Abstract rule syntax


Figure 26 is an example of the Abstract rule syntax. Figure 26 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 (Variable) ECF class of the original events, that is, those events abstracted from performs an implicit duplicate detection. For example, assume that there are no events at all in the system. When the first event is received that matches the from ECF, a new abstract event is generated. When a second arrives that would lead to the same abstract event, the rule engine checks whether a duplicate of the event exists. In this case, a duplicate exists, so the instance of the duplicate event is used in the remainder of the rule.

212

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

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 3, Master Rule Language (MRL) reference.

Chapter 4 Event rules and syntax

213

Abstract rule examples

Abstract rule examples


In Figure 27 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 events status is OPEN and decreases the count when the event closes. Figure 27 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

214

BMC Impact Solutions Knowledge Base Development Reference Guide

Correlate rules

In Figure 28, 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 28 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
s s

mc_cause slotcontains the reference to the cause event mc_effects slotcontains the list of the consequence events

NOTE
The relationship between correlated rules can be broken using the unset_cause primitive. For more information about the unset_cause primitive, see Correlate rule primitives on page 217.

Chapter 4 Event rules and syntax

215

Correlate rule syntax

Correlate rule syntax


Figure 29 is an example of the Correlate rule syntax. Figure 29 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

216

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 188 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 76 for more information about rules and assigned primitives.

Correlate rule examples


The Correlate rule example in Figure 30 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 30 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

Chapter 4 Event rules and syntax

217

Correlate rule examples

The Correlate rule example in Figure 31 includes multiple potential causes for a NFS server not responding. Figure 31 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 203 demonstrate how specific events are processed by the Correlate rule in Figure 31. Table 203 Correlate rule event examples
Example Event Event Cause The HOST_DOWN event is the cause. If an NFS_NO_RESP event and a HOST_DOWN event arrive within ten minutes of each other the cell correlates the two events. By placing the HOST_DOWN event in the first With clause, the Correlate rule considers the HOST_DOWN event to be the most likely cause of the NFS_NO_RESP event and builds a relationship between the two events, even if events match in another With clause. If the cell receives an NFS_NO_RESP event and a PROCESS_DOWN event The PROCESS_DOWN event is the within ten (10) minutes, and no HOST_DOWN event has entered the cell, cause. then the Correlate rule builds a relationship between the events.

218

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

perform actions on an event format an event message update a global record or slot value generate a new event

Execute rule syntax


Figure 32 is an example of the Execute rule syntax. Figure 32 Execute rule syntax

execute RuleName : ECF when Variable.SlotName { Call; Variable.SlotName = ... } when Variable.SlotName { Call; Variable.SlotName = ... } ... END

CondOperator Value

Value;

CondOperator Value

Value;

when

causes an action to occur and is executed if the ECF for the rule passes Note: The When clause in rule phases is reevaluated whenever a value changes for a slot, if the ECF condition is met. This means that if a rule phase subsequent to the Execute phase changes a slot value, and the ECF for the Execute rule passes, the When clause is re-evaluated for that event in the Execute rule phase.

Chapter 4 Event rules and syntax

219

Execute rule syntax

The When clause in an Execute rule can also be written as shown in Figure 33. This form of the When clause executes the action block when the value of the slot changes, regardless of what the change is. Figure 33 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 204 in the executable script or program. Table 204 Available environment variables in Execute rules
Variable CELL_BUILD CELL_DATE CELL_NAME CLASS HOME LOGNAME MCELL_HOME PKG_NAME REQUESTOR Description build number found in the About dialog box of the console date of the build name of the cell class of the event under analysis home directory of the requestor log file name home directory where the cell resides name of the rule package 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 SHELL SLOTS TERM WINDOWID name of rule that triggered the external action shell program list of slot names for the class terminal type (for UNIX only) window ID for the requested console

CELL_RELEASE release number for the cell, for example 1.1

All slots are passed in the environment in the form of variables (with the same names as their slot names) containing the slot values.

220

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 3, Master Rule Language (MRL) reference. You can use the following primitives to help set up an Execute rule:
s s s s s s

reset_defaultresets the default value for a slot that you specify generate_eventcreates a new event add_to_listadds a value to a specified slot rem_from_list--removes a value from a specified slot

set_timersets a timer to execute at a period of time in the future executeruns an executable file for a cell

Execute rule examples


The Execute rule in Figure 34 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 34 Execute rule example 1

execute Disk_Msg : DiskUsedPercentage ($DUP) when $DUP.status: equals OPEN { $V1 = round($DUP.value * 100) ; concat([$DUP.sub_origin, : , $V1, % of space used], $V2) ; $DUP.msg = $V2 ; } END

Chapter 4 Event rules and syntax

221

Threshold rules

In Figure 35 the Execute rule contains several When clauses for the APP_MISSING_PROCESSES event, illustrating how to use primitives such as generate_event or execute.
s

The first when clause executes upon receipt of an OPEN event. A new message is created with the concat primitive and a new event, APP_DOWN, is generated from the original event indicating the application is down. The second when clause fires to close the APP_MISSING_PROCESSES event when all processes for the application are running. The third when clause fires and generates a new event, APP_UP, indicating the application is up when the original event is CLOSED. In addition, an executable is fired that sends a sound to the system indicating the application is up again. Execute rule example 2

Figure 35

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.

222

BMC Impact Solutions Knowledge Base Development Reference Guide

Threshold rule processing

Threshold rule processing


Figure 36 shows how Threshold rule processing occurs. Figure 36 Threshold rule processing

Incoming Event

Duplicate Event?

Added to queue

New queue created

Matches Threshold?

rule is executed and the queue is deleted

event is retained in the queue

# 1 2 3 4 5 6

Process Description An incoming event is compared to determine if it is a duplicate of another event. The event is a duplicate event and is added to the existing queue. The event is not a duplicate event, a new queue is created. The event is compared against the rule to determine if a threshold is reached. If a threshold is reached, the code in the rule is executed and the queue is deleted. If a threshold is not reached, the event remains in the queue.

Chapter 4 Event rules and syntax

223

Threshold rule syntax

Threshold rule syntax


Figure 37 is an example of the Threshold rule syntax. Figure 37 Threshold rule syntax

threshold RuleName : ECF when NumberOfEvents within TimeFrame { Call; Variable.SlotName = Value ; } END

NumberOfEvents TimeFrame

maximum number of events allowed in the queue specified time frame in which the number of events is received

Threshold 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 3, Master Rule Language (MRL) reference.

Threshold rule examples


The Threshold rule in Figure 38 generates a TOO_MANY_AUTH_FAILS event when 10 SNMP_AUTHENTICATION_FAILURE events occur within 120 seconds. Figure 38 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

224

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

topropagates to one specific cell to allpropagates to all cells in the list to one_ofpropagates to only one cell in the list. Typically, cells are tried in turn.

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

mc_historycontains the list of cells, and the identification of the event inside

each cell, through which the event flowed before reaching the current cell.
s

mc_propagationscontains 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 eventspecific slot changes are propagated forward, while the status is propagated backward.

NOTE
How individual slots propagate is configured in the mcell.propagate file. For more information about how to use and set up the propagation configuration file, see the BMC Impact Solutions: General Administration.

Chapter 4 Event rules and syntax

225

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 70 for more information about primitives.

Propagate rules examples


The Propagate rule in Figure 39 sends all APP_DOWN events originating from a system in the IP address range of 172.16.23.* to server1, server2, and server3 when the status the status of the event is CRITICAL. The Propagate rule example in Figure 39 also sends APP_DOWN events, regardless of the event status, originating from a system in the IP address range of 172.16.23.[110] to server1. If server1 is unavailable, the event is propagated to server2. Figure 39 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

226

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

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.

Chapter 4 Event rules and syntax

227

Timer rule syntax

Timer rule syntax


Figure 40 is an example of the Timer rule syntax. Figure 40 Timer rule syntax

timer RuleName : ECF timer_info : RelationalOperator { Call ; Variable.SlotName = Value ; ... } timer_info : RelationalOperator { Call ; Variable.SlotName = Value ; ... } ... END

TimerTrigger1

TimerTrigger2

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 3, Master Rule Language (MRL) reference. The following primitives are not assigned to Timer rules, but can be used to help set up a timer
s s

set_timersets a timer to execute at a period of time in the future. set_timer_atsets a timer to execute on a specific date and time.

Timer rule examples


The Timer rule in Figure 41 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.

228

BMC Impact Solutions Knowledge Base Development Reference Guide

Delete rules

Figure 41

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

Chapter 4 Event rules and syntax

229

Delete rule syntax

Delete rule syntax


Figure 43 shows the Delete rule syntax. Figure 43 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 70 for more information about primitives.

Delete rule examples


The Delete rule in Figure 44 removes event data from a dynamic data table when an event is deleted. Figure 44 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

230

BMC Impact Solutions Knowledge Base Development Reference Guide

Chapter

5
232 232 232 232 233 233 234 234 234 235 235 236 236 236 237 238

Default rule sets


This chapter presents the following topics: Event management rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bii4p.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . im_internal.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ips.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_intevt.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_mccs.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_startup.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mcxp.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service impact management rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_associate.mrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_attach.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_elect.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_maintenance.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_shadow.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_slm.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mc_sm_start.mrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 5

Default rule sets

231

Event management rules

Event management rules


Table 205 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 205 Event Management MRL rule definition files


File name bii4p.mrl im_internal.mrl ips.mrl mc_intevt.mrl mc_mccs.mrl mc_startup.mrl mcxp.mrl Page 232 232 232 233 233 234 234

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.

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.

232

BMC Impact Solutions Knowledge Base Development Reference Guide

mc_intevt.mrl

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

rules that increment the repeat_count slot of the prior duplicate event and then drop the newer event. They include
Applies to internal event class MC_CELL_TICK MC_CELL_DB_CLEANUP MC_CELL_STATBLD_START MC_CELL_STATBLD_STOP

Rule name RepeatTicks RepeatDBClean StbldStart StbldStop

rules that close old events. They include


Class of the new event MC_CELL_START MC_CELL_STOP Class of old events to close MC_CELL_START MC_CELL_STOP MC_CELL_ALLOWED_CONNECT Conditions duplicates duplicates client_location slots equality

Rule name CloseStart CloseStop

UpdateConnect MC_CELL_DISCONNECT CloseHBFail

MC_CELL_HEARTBEAT_ON MC_CELL_HEARTBEAT_FAILURE cell slots equality

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 events 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:
s

rules that increment the repeat_count slot of the prior duplicate event and then drop the newer event; they include
Applies to class MC_MCCS_START MC_MCCS_SYNC_BACKUP MC_MCCS_SYNC_PRIMARY

Rule name RepeatMCCSStart RepeatMCCSSyncBackup RepeatMCCSSyncPrimary

Chapter 5

Default rule sets

233

mc_startup.mrl

rules that close old events; they include


Class of the new event MC_MCCS_START MC_MCCS_STOP Class of old events to close MC_MCCS_STOP MC_MCCS_START Conditions mccs_location slots equality mccs_location slots equality

Rule name CloseMCCSStop CloseMCCSStart UpdateMCCSSynca

MC_MCCS_SYNC_BACKUP MC_MCCS_SYNC_BACKUP $NEW.msg == 'Synchronization ended'$OLD.msg == 'Synchronization began'

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 3, Master Rule Language (MRL) reference.

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

234

BMC Impact Solutions Knowledge Base Development Reference Guide

mc_sm_associate.mrl

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

associating raw events to components electing associated raw events attaching associated and elected raw events to components

Table 206 lists the MRL files that contain the default service management rule definitions for BMC Impact Manager. Table 206 Service Management MRL rule definition files
File name mc_sm_associate.mrl mc_sm_attach.mrl mc_sm_elect.mrl mc_sm_maintenance.mrl mc_sm_shadow.mrl mc_sm_slm.mrl mc_sm_start.mrl Page 235 235 236 236 236 237 238

For more information about the service model rule sets, see BMC Impact Solutions: General Administration.

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.

Chapter 5

Default rule sets

235

mc_sm_elect.mrl

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 update_component Description updates the context for a previously attached event whose severity value has changed

attach_detach_event attaches new events which have just been associated and elected

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

maintenance_enabled maint_filter_new_events Description

Rule name

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 removes duplicate events received during the maintenance mode

eliminate_dup_maintenance_event

mc_sm_shadow.mrl
The mc_sm_shadow.mrl rule file is system reserved.

236

BMC Impact Solutions Knowledge Base Development Reference Guide

mc_sm_slm.mrl

The rules in mc_sm_shadow.mrl support the registering, unregistering, update, and deletion of shadow components.
Rule name handle_shadow_requests generate_shadow_requests_failure Description processes and MC_SM_SHADOW_REQUEST event coming from another cell 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 drops all Acknowledged MC_SM_SHADOW_REQUEST events propagates any new SMC_STATE_CHANGE event to all the cells hosting a related shadow component updates the status of a local shadow component on receipt of an MC_SM_SHADOW_UPDATE event referencing the component logical ID marks a local shadow component for deletion on receipt of a MC_SM_SHADOW_DELETE event referencing the component logical ID indicates shadow component to be removed was not found

drop_ack_shadow_requests_failure propa_state_change_to_shadow_cells update_shadow_component

delete_shadow_component

delete_shadow_component_failure

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

mc_sm_slm.mrl
The mc_sm_slm.mrl rule file is system reserved.

Chapter 5

Default rule sets

237

mc_sm_start.mrl

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

238

BMC Impact Solutions Knowledge Base Development Reference Guide

Chapter

6
240 241 242 242 242

Policy and selector syntax


This appendix presents the following topics: Event policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format of event processing rules for policy types . . . . . . . . . . . . . . . . . . . . . . . . . How a rule for a policy type is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6

Policy and selector syntax

239

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 45. Figure 45 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 46. Figure 46 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

240

BMC Impact Solutions Knowledge Base Development Reference Guide

Event selectors

The syntax for a policy contained in a rule is shown in Figure 47. Figure 47 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 48. Figure 48 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 49. Figure 49 Selector entry syntax

SELECTOR; name=string_value; description=string_value; based_on=BASE_EVENT_CLASS_NAME; ecfs=[EVENT_CLASS_NAME [where clause], . . .]; END

Chapter 6

Policy and selector syntax

241

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

242

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 except_timeframes active_global_timeframes except_global_timeframes selector_name selector_class selector_ecf ordinal }; END

: : : : : : : :

LIST_OF STRING; LIST_OF STRING; LIST_OF STRING; LIST_OF STRING; STRING; STRING; ECF EVENT; INTEGER, default=0;

2. The tf_active calls evaluate local timeframes for the policy. The tf_udid_active calls evaluate global timeframes for the policy. 3. The selector ECF selects the event to process. 4. The actions implement the policy and the opadd call adds an entry to the operations log of the event. You can view examples of rules for policy types in MCELL_HOME/kb/rules/im_internal.mrl.

Chapter 6

Policy and selector syntax

243

How a rule for a policy type is processed

244

BMC Impact Solutions Knowledge Base Development Reference Guide

Chapter

7
245 247 248 248 250 250 251 251 251 252 252 252 252 256 259 263 267

Common Event Model


This appendix describes the different property groupings of the Common Event Model (CEM). It presents the following topics: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Versioning support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Internationalization compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping quick reference: CEM to BAROC (CORE_EVENT). . . . . . . . . . . . . . . . Guidelines for applying CEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Associating events with configuration items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Root cause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding attributes vs. adding generic slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cross-launching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Free-format text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CEM property groupings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reporter component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Situation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Metric properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Overview
A Common Event Model (CEM) enables a consistent definition of an event. This definition specifies the format and the data, both of which each event should contain. The event should contain the same format and data, regardless of its originating source. By mapping all event sources to CEM definitions, you significantly reduce the overhead of managing and maintaining an event management solution.

Chapter 7

Common Event Model

245

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

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

event type CEM version origin information domain information object information management processes such as availability, scheduling, and so forth parameters

TIP
Events do not always contain all the information that CEM requires. In these instances, you can enrich the event by adding contextual information to it. For example, if a raw event does not contain a specific slot, you can still add slot-related information to the event through a data-enrichment process.

BMC intends to make its integrations compatible with the Common Event Model. BMC recommends that customers building any new integrations be consistent with the Common Event Model described below. The Common Event Model (CEM) defines the event fields and formats for the BMC_BaseEvent class, a super class that contains the BMC Impact Manager cells 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 207 on page 247:

246

BMC Impact Solutions Knowledge Base Development Reference Guide

Versioning support

Table 207 Property groupings: BMC_BaseEvent class


Property group General Source component Description basic information about the event, including the event class, event Id, status, and so forth 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. an optional category. The properties include metric name, metric value, metric value unit, and metric threshold. You must include all properties of the metric that you provide.

Metrics

CEM supports the following data types: Table 208 Data types
Data types INTEGER REAL STRING <ENUMNAME> LIST_OF Description 32-bit signed value 64-bit real value UTF-8 string value with a maximum length of 65535 bytes enumeration a collection of objects

Versioning support
CEM uses the EventModelVersion field (mc_event_model_version slot) to indicate the class version of the CEM that the event management system uses. If 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.

Chapter 7

Common Event Model

247

Internationalization compatibility

Internationalization compatibility
The CEM classes are compatible with internationalization requirements and provide language support. You should use Unicode encoding for all text.

Mapping quick reference: CEM to BAROC (CORE_EVENT)


The following tables list the mapping associations between CEM properties and their respective BAROC slots in the CORE_EVENT class. Table 209 CEM to BAROC: Metadata
CEM property EventModelVersion EventClass EventId Status ReportTime EventToCIAssociationType Timeout Notes PropagationHistory RelationSource Owner Account BAROC slot mc_event_model_version CLASS mc_ueid status mc_incident_report_time mc_smc_impact mc_timeout mc_notes mc_history mc_relation_source mc_owner mc_account Required or optional required required required optional optional optional optional optional required required optional optional

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 210 CEM to BAROC: source information (part 1 of 2)


CEM property ResourceId (source) ReconciliationIdentity Alias ComponentHost ComponentHostAddress Location ComponentURI ComponentCaption BAROC slot mc_tool_id mc_smc_id mc_smc_alias mc_host mc_host_address mc_location mc_object_uri mc_object Required or optional optional recommended recommended required required optional optional recommended

248

BMC Impact Solutions Knowledge Base Development Reference Guide

Mapping quick reference: CEM to BAROC (CORE_EVENT)

Table 210 CEM to BAROC: source information (part 2 of 2)


CEM property ComponentType ComponentOwner BAROC slot mc_object_class mc_object_owner Required or optional recommended optional

BMC recommends that you use ReconciliationIdentity (mc_smc_id) and Alias (mc_smc_alias) because they make it easier to track configuration items. Table 211 CEM to BAROC: reporter information
BAROC slot mc_tool_id mc_tool_address mc_tool_uri mc_tool mc_tool_class mc_tool_time mc_tool_rule mc_tool_key mc_tool_sev mc_tool_suggestion Required or optional optional required optional required optional required optional required optional optional

CEM property ResourceId (reporter) ComponentHostAddress ComponentURI ComponentCaption ComponentType EventTime EventType EventId EventSeverity EventSuggestion

Table 212 CEM to BAROC: situation information


CEM property SituationCategory SituationTime Priority Severity Message Application LongMessage RepeatCount BAROC slot mc_event_category mc_incident_time mc_priority severity msg mc_service mc_long_msg repeat_count Required or optional required required optional required recommended optional optional optional

Table 213 CEM to BAROC: metric information


CEM property MetricName MetricValue MetricValueUnit MetricThreshold BAROC slot mc_parameter mc_parameter_value mc_parameter_unit mc_parameter_threshold Required or optional optional optional optional optional

Chapter 7

Common Event Model

249

Guidelines for applying CEM

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 integrations 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:
s

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

Specify the BMC Atrium CMDB ReconciliationId assigned to the CI in the mc_smc_id slot of the event description. The association between event and CI is made automatically. Use the SIM alias feature. Define an alias for a CI in its ComponentAlias field. The format of the alias syntax consists of a prefix that identifies your integration application and a value that represents a CI. Ensure that the mc_smc_alias slot, which contains the alias, of your event description exactly matches the events you want to associate with the CI. Otherwise, you can create an alias by combining slot values of the event or events that you want to associate with the CI.

Status computation
You can enable the CEM event to be included in the status computation of the component represented by the 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 214 on page 251 for a listing of the values.

250

BMC Impact Solutions Knowledge Base Development Reference Guide

Root cause

Table 214 EventInformation::EventToCIAssociationType parameter values


Value 0 1 2 Description MRL rules determine whether the event attaches to the CI a default rule attaches this particular event to a CI event does not impact the component status

Root cause
The CEM base class does not store this information. However, you can either
s

add a root cause attribute in an extended class derived from the CDM generate two corresponding events: one for the impacted component and another for the root cause component

BMC service impact management (SIM) best practice is to generate the two events. Both the impacted and root cause components should be defined in the same service model. When the SIM cell receives the event for the root cause component, it computes the status of the impacted component automatically.

Adding attributes vs. adding generic slots


Instead of adding generic slots to the CEM, BMC recommends that you add meaningful attributes to the extended classes that you have derived from CEM. The problem with adding generic slots is that their semantics are not easily defined and standardized so that all applications understand the generic slots.

Cross-launching
CEM makes the cross-launching from one application to another easier. CEM uses the componentURI slot (mc_object_uri and mc_tool_uri) to specify the address used to cross-launch to the
s s

components location reporters location (the component that reports the status of another)

When an application broadcasts it URI, it makes it possible for another application to access and cross-launch to it.

Chapter 7

Common Event Model

251

Event synchronization

NOTE
BMC recommends that you also look at using federated links to perform cross-launching in the BMC Atrium CMDB. See your BMC Atrium CMDB documentation.

Event synchronization
To synchronize events with a third-party management system, you need to identify the
s s s

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.

General properties
The general property group contains metadata information about the event. Table 215 ReportTime (optional)
Property name BAROC name Description Data type Format Example ReportTime mc_incident_report_time date and time when the event was reported by the reporting object integer UTC 1151651591

252

BMC Impact Solutions Knowledge Base Development Reference Guide

General properties

Table 216 EventModelVersion (required)


Property name BAROC name Description Data type Format Example EventModelVersion mc_event_model_version version of the Common Event Model (CEM) that is used to instantiate the event string xx, yy, zz 1.1.00

Table 217

EventClass (required)
EventClass 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 be written for the designated event provider. String Event_ClassName BMC_MVEvent

Property name BAROC name

Description Data type Format Example

Table 218 EventId (required)


Property name BAROC name Description Data type EventId mc_ueid globally unique identifier of the event. If the mc_ueid is not defined, then it is automatically generated by the first cell that receives the event. String <ProductPrefix><separator><mc_tool_id><separator><mc_tool_key> Format Example You can choose which <separator> to use. BPM:BPMPrimary:12345abcd

Table 219 Status (optional)


Property name BAROC name Description Status mc_status a specified listing of distinct object states. The default status value is OPEN. ENUMERATION. The values are
s s s s

Data type

OPEN ACK ASSIGNED CLOSED BLACKOUT

Chapter 7

Common Event Model

253

General properties

Table 219 Status (optional)


Format Example Enumeration OPEN

Table 220 Timeout (optional)


Property name BAROC name Description Data type Format Example Timeout mc_timeout specified timeout period in seconds after which an event is automatically closed Integer Integer 300

Table 221 Notes (optional)


Property name BAROC name Description Data type Format Notes mc_notes a list of free text annotations that are added to an event LIST_OF strings Unicode text Comment this. Comment that. Comment the other.

Example

Table 222 EventToCIAssociationType (optional)


Property name BAROC name EventToCIAssociationType 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 must attach the event to the configuration item to affect its status computation. integer. Valid values are
s s

Description

Data type Format Example

0 - rules determine whether the event is attached to a configuration item (default value) 1 - a predefined rule attaches this event to a configuration item 2 - the event is not attached to a configuration item

integer 0

254

BMC Impact Solutions Knowledge Base Development Reference Guide

General properties

Table 223 PropagationHistory (required)


Property name BAROC name PropagationHistory 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 receive the synchronized events back from the cell. LIST_OF string <gateway_name>:0 [BiiOVO1:0] PropagationHistory is required only if the provider wants to receive its synchronized events back from the cell.

Description Data type Format Example

Table 224 RelationSource (required)


Property name BAROC name Description Data type RelationSource mc_relation_source contains the mc_ueid of the source event to which the current event is related string <ProductPrefix><separator><mc_tool_id><separator><mc_tool_key> Format Example You can choose which <separator> to use. BPM:BPMPrimary:12345abcd RelationSource is required if the consumer object wants to send or receive updates.

Table 225 Owner (optional)


Property name BAROC name Description Data type Format Example Owner mc_owner current user assigned to the event string text Pablo

Chapter 7

Common Event Model

255

Source component properties

Table 226 Account (optional)


Property name BAROC name Description Data type Format Example Account mc_account identification of the account associated with the event. (This slot does not support multi tenancy.) String text 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 227 ResourceId (optional)
Property name BAROC name ResourceId [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 reconciliation ID or the alias. string GUID SJSC_GICT0002.j17rul.00004

Description Data type Format Example

Table 228 ReconciliationIdentity (recommended)


Property name BAROC name ReconciliationIdentity mc_smc_id identifier of a manageable resource associated with an event and is used to associate the event with a configuration item. BMC recommends that this value be the reconciliation Id value generated by the BMC Atrium CMDB. string ReconciliationId OS-838310E3AEF4168FC895B883ADC8F7

Description Data type Format Example

256

BMC Impact Solutions Knowledge Base Development Reference Guide

Source component properties

Table 229 Alias (recommended)


Property name BAROC name Alias 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 providers supply this value with the components alias value. String <ProductPrefix>:<GUID> BPM:838310E3AEF4168FC895B883ADC8F7

Description Data type Format Example

Table 230 ComponentHost (required)


Property name BAROC name Description Data type Format Example ComponentHost mc_host Fully-qualified host name of the system on which the problem occurred. The ComponentHost is required in the ComponentHostAddress is not specified. String fully qualified domain name opensource.adprod.bmc.com

Table 231 ComponentHostAddress (required)


Property name BAROC name ComponentHostAddress 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 ComponentHost property is not specified. String IP address/type 192.168.0.100

Description Data type Format Example

Table 232 Location (optional)


Property name BAROC name Description Data type Format Example Location mc_location location at which the source component resides. This slot provides additional contextual information for the event. String Text SJ1-DC1

Chapter 7

Common Event Model

257

Source component properties

Component address properties


This is a subset of the source component properties. These slots designate the address of the source component. The component address properties can represent alternate addresses of the source component. Table 233 ComponentURI (optional)
Property name BAROC name Description Data type Format Example ComponentURI mc_object_uri the address that can be used to cross launch directly into a component String URI http://192.168.175.149/ews/index.htm

Table 234 ComponentCaption (recommended)


Property name BAROC name ComponentCaption 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 available as a property of the CI data element in SIM. string text; or the in the CDM, the name format hou-ex-04.adprod.bmc.com 192.168.0.100:Microsoft Exchange Server

Description Data type Format Example

Table 235 ComponentType (recommended)


Property name BAROC name Description Data type Format Example ComponentType mc_object_class identifies the class name of the source component string CDM class name. If the CDM class name is unknown, you can use a user-defined categorization of the source component. BMC_ComputerSystem

258

BMC Impact Solutions Knowledge Base Development Reference Guide

Reporter component properties

Table 236 ComponentOwner (optional)


Property name BAROC name Description Data type Format Example ComponentOwner mc_object_owner identifies the owner of the source component string text 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.

Table 237 Slots for event monitoring information (part 1 of 2)


Slot mc_origin mc_origin_address Description specifies the event management system that is closest to the source of the event and is deemed to have detected the event network IP address of the event management system

Chapter 7

Common Event Model

259

Reporter component properties

Table 237 Slots for event monitoring information (part 2 of 2)


Slot mc_origin_key Description 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 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.

mc_origin_sev

Slots that begin with the mc_origin prefix follow the same format as slots that begin with mc_tool. Table 238 ResourceId (optional)
Property name BAROC name Description Data type Format Example ResourceId mc_tool_id identifies a manageable resource (component) that reports an event string text BPMPrimary

Table 239 ComponentHostAddress (required)


Property name BAROC name Description Data type Format Example ComponentHostAddress mc_tool_address network address of the reporter component string IP address/text 192.168.0.100

Component address properties for reporting


These are component address elements for the reporting component: Table 240 ComponentURI (optional)
Property name BAROC name Description Data type Format Example ComponentURI mc_tool_uri address that can be used to cross-launch to the reporter component string URI http://192.168.175.149/ews/index.htm

260

BMC Impact Solutions Knowledge Base Development Reference Guide

Reporter component properties

Table 241 ComponentCaption (required)


Property name BAROC name Description Data type Format Example ComponentCaption mc_tool object that reports the event string text HPVOInst1

Table 242 ComponentType (optional)


Property name BAROC name Description Data type Format Example ComponentType mc_tool_class user-defined categorization of the object that reports the event string text BPM Portal Server

Table 243 EventTime (required)


Property name BAROC name Description Data type Format Example EventTime mc_tool_time time that the reporter component received the event. This is the reporter time translated into epoch time. integer coordinated universal time (UTC) 1110637098173

Table 244 EventType (optional)


Property name BAROC name Description Data type Format Example EventType mc_tool_rule condition that triggers the event string text CPU usage high

Chapter 7

Common Event Model

261

Reporter component properties

Table 245 EventId (required)


Property name BAROC name Description Data type Format Example EventType mc_tool_key unique identifier of the event in the Reporter. This identifier is usually the event id assigned to the event by the system that detected the event. string text 3eb61c54-0806-71db-0009-8948e4720000

Table 246 EventSeverity (optional)


Property name BAROC name Description Data type Format Example EventSeverity mc_tool_sev the severity level as defined by the reported component. This severity level does not map to the BEM or BMC SIM severity levels. string text critical

Table 247 EventSuggestion (optional)


Property name BAROC name Description Data type Format Example EventSuggestion mc_tool_suggestion predefined text suggestion for solving the situation described by the event string text Expert advice in PATROL

262

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 248 SituationCategory (required)
Property name BAROC name Description SituationCategory mc_event_category the Information Technology Infrastructure Library (ITIL) process that the event represents ENUMERATION (MC_EVENT_CATEGORY) Possible values include
s s s s s s s s s s s s

Data type Format Example

SLA_MANAGEMENT CAPACITY_MANAGEMENT SERVICE_CONTINUITY_MANAGEMENT AVAILABILITY_MANAGEMENT INCIDENT_MANAGEMENT CONFIGURATION_MANAGEMENT RELEASE_MANAGEMENT PROBLEM_MANAGEMENT CHANGE_MANAGEMENT OPERATIONS_MANAGEMENT SECURITY_MANAGEMENT FINANCIAL_MANAGEMENT SERVICE_DESK_MANAGEMENT

ENUMERATION SLA

Table 249 Situation category (mc_event_category) values (part 1 of 3)


ITIL category SLA_MANAGEMENT Description 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 costjustifiable service quality is maintained and gradually improved. 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 costeffective 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.

CAPACITY_MANAGEMENT

Chapter 7

Common Event Model

263

Situation properties

Table 249 Situation category (mc_event_category) values (part 2 of 3)


ITIL category SERVICE_CONTINUITY_ MANAGEMENT Description events relating to the Service Continuity Management process. The process covers supporting the overall Business Continuity Management process by ensuring that the required IT technical and services facilities (including computer systems, networks, applications, telecommunications, technical support and Service Desk) can be recovered within required, and agreed, business timescales. 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. 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 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. 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. 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. 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 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. 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

AVAILABILITY_MANAGEMENT

INCIDENT_MANAGEMENT

CONFIGURATION_MANAGEMENT

RELEASE_MANAGEMENT

PROBLEM_MANAGEMENT

CHANGE_MANAGEMENT

OPERATIONS_MANAGEMENT

SECURITY_MANAGEMENT

264

BMC Impact Solutions Knowledge Base Development Reference Guide

Situation properties

Table 249 Situation category (mc_event_category) values (part 3 of 3)


ITIL category FINANCIAL_MANAGEMENT Description 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. The events relating to the Service Desk Management process. The process to manage the Service Desk itself.

SERVICE_DESK_MANAGEMENT

Table 250 SituationTime (required)


Property name BAROC name SituationTime 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 timerelated information is as optimal as possible. integer coordinated universal time (UTC) 1110637098173

Description Data type Format Example

Table 251 Priority (optional)


Property name BAROC name Priority 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:
s s s s s

PRIORITY_5 PRIORITY_4 PRIORITY_3 PRIORITY_2 PRIORITY_1

Description Data type Format Example

PRIORITY_1 is the highest priority. ENUMERATION (MC_PRIORITY) Enumeration PRIORITY_1

Chapter 7

Common Event Model

265

Situation properties

Table 252 Severity (required)


Property name BAROC name Severity mc_severity Represents the perceived severity of the status the event is describing with respect to the application that reports the event. Current values
s s s s s s

Description Data type Format Example

UNKNOWN OK INFO WARNING MINOR MAJOR CRITICAL

ENUMERATION (MC_SEVERITY) Enumeration Major

Table 253 Message (recommended)


Property name BAROC name Description Data type Format Example Message mc_message descriptive text that is part of an event. BMC recommends a terse description of the event content. string text (Unicode) This component is down.

Table 254 Application (optional)


Property name BAROC name Application 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 would be typically set by enrichment. string text OracleListener

Description Data type Format Example

266

BMC Impact Solutions Knowledge Base Development Reference Guide

Metric properties

Table 255 LongMessage (optional)


Property name BAROC name LongMessage 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 rules. string text (Unicode) this event is enriched

Description Data type Format Example

Table 256 RepeatCount (optional)


Property name BAROC name Description Data type Format Example RepeatCount mc_repeat_count number of time that this incident described in the event has occurred integer integer 4

Metric properties
Metric properties are optional. However, if you do use the metric definition, you must include all related metric properties. Table 257 MetricName (optional)
Property name BAROC name Description Data type Format Example MetricName mc_parameter name of the metric parameter that went into alarm or that triggered the event string Unicode text HardDiskUsage

Table 258 MetricValue (optional)


Property name BAROC name Description Data type Format Example MetricValue mc_parameter_value value of the metric string Unicode text 80 Chapter 7 Common Event Model 267

Metric properties

Table 259 MetricValueUnit (optional)


Property name BAROC name Description Data type Format Example MetricValueUnit mc_parameter_unit unit description of the metric string Unicode text %

Table 260 MetricThreshold (optional)


Property name BAROC name Description Data type Format Example MetricThreshold mc_parameter_threshold threshold value that was exceeded and result in the generation of the event string Unicode text 75

268

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

Index
# , usage in BAROC 18 *, usage in BAROC 18 +, usage in BAROC 18 <>, usage in BAROC 18 BEM_MATCH_TABLE (continued) pattern matching 45 processing 45 bem_match_table.baroc file 32 bii4p.baroc file 32 bii4p.mrl files 232 BMC Impact Integration for PATROL 7 rules 232 BMC Impact Manager class files 32 BMC Impact Publishing Server rules 232 BMC Software, contacting 2 brackets usage in BAROC 18

A
Abstract rules described 211 examples 214 primitives 213 syntax 212 action-related primitives and functions 77 adapter_host slot 35 administrator slot 35 angle brackets, usage in BAROC 18 ANY argument type decribed 53, 76 apache.baroc file 32 argument types ANY 53, 76 ENUM 53, 76 for primitives and functions 53, 76 INTEGER 53, 76 LIST_OF 53, 76 OBJECT 76 POINTER 76 REAL 53, 76 SLOTREF 76 STRING 53, 76 asterisk (*), usage in BAROC 18

C
CELL_BUILD variable 220 CELL_DATE variable 220 cell_location slot 41 cell_name slot 41 CELL_NAME variable 220 CELL_RELEASE variable 220 class hierarchy 34 class instances defining 28 CLASS variable 220 classes CORE_DATA 42, 43 CORE_EVENT 34, 35 data hierarchy 42 defining 19 definition examples 27 files for 32 syntax for defining 19 Common Event Model (CEM) adding attributes 251 associating events with CIs 250 BMC_BaseEvent class 246 component address elements 260 component address properties 258 CORE_EVENT class 246 data types 247 description 245

B
BAROC asterisk 18 brackets 18 compiling and loading files 30 identifiers 18 language symbols 18 language syntax 18 base classes CORE_EVENT 20 based_on slot 47 BEM_MATCH_TABLE data class 44

Index

269

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
Common Event Model (continued) event reporting 259 event synchronization 252 general properties 252 I18N 248 ITIL processes 263 mapping to Baroc 248 mapping to CORE_EVENT 248 mc_event_category 263 mc_event_category values 263 metric properties 267 property groupings 247 reporter component properties 259 root cause 251 situation properties 263 source component properties 256 versioning 247 compiling BAROC 30 confirm_external() primitive in Refine rules 197 CORE_DATA class 20, 42, 43 CORE_EVENT base class 20, 35 CORE_EVENT class 34 Correlate rules described 215 examples 217 primitives 217 syntax 216 customer support 3 data types (continued) REAL 21, 52 SIMPLE 21 STRING 21, 52 Tivoli TEC 21 data_handle slot 43 date slot 35 date_reception slot 35 default facet, described 22 defining class instances 28 classes 19 classes, examples 27 global records 29 Delete rules described 229 examples 230 primitives 230 syntax 230 deprecated slots list of 49 substitution 49 description slot 47 dup_detect facet, described 23 duration slot 35 dynamic data creating New rule for 209

E
ea_event.baroc file 32 ecfs slot 47 ecfs_descr slot 47 enabled slot 47 ENUM argument type described 53, 76 enumerations internal 24 MC_EVENT_CATEGORY 25 MC_PRIORITY 25 SEVERITY 24 STATUS 24 syntax 23 EnumName data type 21 EVENT class 41 event classes CORE_EVENT 35 definition example 27, 28 EVENT 41 hierarchy 34 MC_CELL_CONTROL 41 metaclass 20 universal identifier 21 event management default rules 232

D
data classes BEM-MATCH_TABLE 44 CORE_DATA 20, 43 defining 19 definition example 28 hierarchy 42 MC_CALENDARING 43 MC_SM_DATA class 43 metaclass 20 POLICY 47 SCHEDULE 44 SELECTOR 47 TIME_FRAME 44 TIME_ZONE 44 universal identifier 21 data types described 52 ENUM 52 EnumName 21 INT32 21 INTEGER 21, 52 LIST_OF 21 POINTER 21, 52

270

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 policies described 240 generic rules 232 MC_CALENDARING data class 43 rules 242 syntax 240 event selectors described 241 event_handle slot 35 eventlog.baroc file 32 events defining classes 19 MC_EVENT_CATEGORY enumeration 25 MC_PRIORITY enumeration 25 SEVERITY enumeration 24 STATUS enumeration 24 Execute rules described 219 environment variables 220 examples 221 primitives 221 syntax 219 files (continued) mc_sm_custom.baroc 33 mc_sm_event_mapping.baroc 33 mc_sm_maintenance.baroc 33 mc_sm_maintenance.mrl 236 mc_sm_notifiy.baroc 33 mc_sm_object.baroc 33 mc_sm_propagation.baroc 33 mc_sm_root.baroc 33 mc_sm_shadow.mrl 236 mc_sm_slm.baroc 33 mc_sm_start.mrl 238 mc_startup.mrl 234 mc_tec_severity.baroc 33 mccs.baroc 33 mcxa.baroc 33 mcxp.baroc 33 mcxp.mrl 234 ms_sm_associate.mrl 235 ms_sm_slm.mrl 237 patrol_em.baroc 33 patrol_portal.baroc 33 state_change.baroc 33 filesbii4p.mrl 232 Filter rules described 198 examples 201 primitives 200 processing during phase 199 syntax 199 find_match() function and primitive creating BEM_MATCH_TABLE 44 functions and primitives argument types 53, 76 overview 76

F
facets default 22 described 22 dup_detect 23 hidden 23 key 23 parse 23 read_only 23 representation 23 files 236 apache.baroc 32 bem_match_table.baroc 32 bii4p.baroc 32 ea_event.baroc 32 eventlog.baroc 32 for classes 32 im_internal.mrl 232 im_policies.baroc 32 ips.baroc 32 loading BAROC 30 mc_deprecated_filter.baroc 32 mc_deprecated_kb_data.baroc 32 mc_deprecated_notification.baroc 32 mc_deprecated_propagation.baroc 32 mc_evtdata_internal.baroc 32 mc_intevt.mrl 233 mc_mccs.mrl 233 mc_root_internal.baroc 20, 32 mc_root_redef.baroc 33, 48 mc_sm_attach.mrl 235 mc_sm_cost.baroc 33

G
generic rule, creating 209 get_external() primitive in Refine rules 197 global records defining 29

H
hidden facet, described 23 HOME variable 220

I
identifiers, usage in BAROC 18 im_internal.mrl file 232 im_policies.baroc file 32 input_match slot 44

Index

271

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
instances defining 28 definition example 29 syntax for definitions 28 INT32 data type 21 INTEGER argument type described 53, 76 INTEGER data type 21 interface classes defining 19 definition example 28 metaclass 20 internal enumerations 24 ips.baroc file 32 mc_event_model_version slot 36 mc_event_relations slot 36 mc_evtdata_internal.baroc file 32 mc_history slot 36 mc_host slot 36 mc_host_address slot 36 mc_host_class slot 37 mc_incident_report_time slot 37 mc_incident_time slot 37 MC_INTERFACE metaclass 20 mc_intevt.mrl file 233 mc_local_reception_time slot 37 mc_location slot 37 mc_mccs.mrl file 233 mc_modhist slot 37 mc_modification_time slot 43 mc_notes slot 37 mc_notification_history slot 37 mc_object slot 37 mc_object_class slot 37 mc_object_owner slot 37 mc_object_uri slot 37 mc_operations slot 38 mc_origin slot 38 mc_origin_class slot 38 mc_origin_key slot 38 mc_origin_sev slot 38 mc_original_priority slot 38 mc_original_severity slot 38 mc_owner slot 38 mc_parameter slot 38 mc_parameter_threshold slot 38 mc_parameter_unit slot 38 mc_parameter_value slot 38 MC_PRIORITY enumeration 25 mc_priority slot 39 mc_propagations slot 39 MC_PUBLISH_DATA_CLASS metaclass 20 mc_relation_source slot 39 mc_root_internal.baroc file 20, 32 mc_root_redef.baroc file 33 mc_root_redef.baroc files 48 mc_service slot 39 mc_sm_associate.mrl file 235 mc_sm_attach.mrl file 235 mc_sm_cost.baroc file 33 mc_sm_custom.baroc file 33 MC_SM_DATA class 43 mc_sm_elect.mrl 236 mc_sm_elect.mrl file 236 mc_sm_event_mapping.baroc file 33 mc_sm_maintenance.baroc file 33 mc_sm_maintenance.mrl file 236 mc_sm_notify.baroc file 33 mc_sm_object.baroc file 33 mc_sm_propagation.baroc file 33 mc_sm_root.baroc file 33

K
key facet, described 23

L
LIST_OF argument type described 53, 76 LIST_OF data type 21 loading BAROC files 30 LOGNAME variable 220

M
mc_abstracted slot 35 mc_abstraction slot 35 mc_account slot 35 mc_acl slot 35 mc_action_count slot 35 mc_arrival_time slot 35 mc_associations slot 35 mc_bad_slot_names slot 36 mc_bad_slot_values slot 36 MC_CALENDARING class 43 mc_cause slot 36 MC_CELL_CONTROL class 41 mc_client_address slot 36 mc_collectors slot 36 mc_creation_time slot 43 MC_DATA_CLASS metaclass 20 mc_date_modification slot 36 mc_deprecated_filter.baroc file 32 mc_deprecated_kb_data.baroc file 32 mc_deprecated_notification.baroc file 32 mc_deprecated_propagation.baroc file 32 mc_effects slot 36 MC_EV_CLASS metaclass 20 MC_EVENT_CATEGORY enumeration 25 mc_event_category slot 36

272

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
mc_sm_shadow.mrl file 236 mc_sm_slm.baroc file 33 mc_sm_slm.mrl file 237 mc_sm_start.mrl file 238 mc_smc_causes slot 39 mc_smc_effects slot 39 mc_smc_id slot 39 mc_smc_impact slot 39 mc_smc_priority slot 39 mc_smc_type slot 39 mc_startup.mrl file 234 mc_tec_severity.baroc file 33 mc_timeout slot 39 mc_tool slot 40 mc_tool_address slot 40 mc_tool_class slot 40 mc_tool_key slot 40 mc_tool_rule slot 40 mc_tool_sev slot 40 mc_tool_suggestion slot 40 mc_tool_time slot 40 mc_tool_uri slot 40 mc_udid slot 22, 43 mc_ueid slot 22, 40 mccs.baroc file 33 MCELL_HOME environment variable 220 mcxa.baroc file 33 mcxp.baroc file 33 mcxp.mrl file 234 metaclasses described 20 MC_DATA_CLASS 20 MC_EV_CLASS 20 MC_INTERFACE 20 MC_PUBLISH_DATA_CLASS 20 TEC_CLASS 20 msg slot 40

P
parse facet, described 23 PASS mode 198 patrol_em.baroc file 33 patrol_portal.baroc file 33 pattern matching 45 PKG_NAME variable 220 plus sign (+), usage in BAROC 18 POINTER argument type described 76 POINTER data type 21 POLICY class described 47 syntax 240 pound sign (# ), usage in BAROC 18 primitives and functions action-related 77 argument types 53, 76 overview 76 product support 3 Propagate rules described 225 examples 226 primitives 226 syntax 226 publishing metaclass 20

R
read_only facet 23 REAL argument type described 53, 76 REAL data type 21 ref_instances_classes slot 44 Refine rules described 195 examples 197 primitives 197 processing during phase 195 syntax 196 Regulate rules described 202 examples 204 forms of 202 primitives 204 processing during phase 202 syntax 203 repeat_count slot 40 representation facet, described 23 REQUESTOR variable 220 RULE_NAME variable 220 rules event management 232 for event policies 242 for service impact management 234

N
name slot 44, 47 New rules creating for dynamic data 209 described 206 examples 208 primitives 208 syntax 207 NOPASS mode 198

O
OBJECT argument type described 76 output_expressions slot 44

Index

273

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

S
SCHEDULE data class 44 SELECTOR class described 47 syntax 241 selectors described 241 syntax 241 service impact management rules 234 service models publishing metaclass 20 SEVERITY enumeration 24 severity slot 41 SHELL variable 220 SIMPLE data type 21 slot facets, See facets SLOTREF argument type described 76 slots adapter_host 35 administrator 35 based_on 47 cell_location 41 cell_name 41 data_handle 43 date 35 date_reception 35 defining enumerations 23 deprecated 49 deprecated substitution 49 description 47 duration 35 ecfs 47 ecfs_descr 47 enabled 47 event_handle 35 input_match 44 mc_abstracted 35 mc_abstraction 35 mc_account 35 mc_acl 35 mc_action 35 mc_arrival time 35 mc_associations 35 mc_bad_slot_names 36 mc_bad_slot_value 36 mc_cause 36 mc_client_address 36 mc_collectors 36 mc_creation_time 43 mc_date_modification 36 mc_effects 36 mc_event_category 36 mc_event_model_version 36 mc_event_relations 36

slots (continued) mc_history 36 mc_host 36 mc_host_address 36 mc_host_class 37 mc_incident_report_time 37 mc_incident_time 37 mc_local_receptions_time 37 mc_location 37 mc_modhist 37 mc_modification_time 43 mc_notes 37 mc_notification_history 37 mc_object 37 mc_object_class 37 mc_object_owner 37 mc_object_uri 37 mc_operations 38 mc_orgin_key 38 mc_orginal_severity 38 mc_origin 38 mc_origin_class 38 mc_origin_sev 38 mc_original_priority 38 mc_owner 38 mc_parameter 38 mc_parameter_threshold 38 mc_parameter_unit 38 mc_parameter_value 38 mc_priority 39 mc_propagations 39 mc_relations_source 39 mc_service 39 mc_smc_causes 39 mc_smc_effects 39 mc_smc_id 39 mc_smc_impacts 39 mc_smc_priority 39 mc_smc_type 39 mc_timeout 39 mc_tool 40 mc_tool_address 40 mc_tool_class 40 mc_tool_key 40 mc_tool_rule 40 mc_tool_sev 40 mc_tool_suggestion 40 mc_tool_time 40 mc_tool_uri 40 mc_udid 43 mc_ueid 40 msg 40 name 44, 47 output_expressions 44 ref_instances_classes 44 repeat_count 40 severity 41

274

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
slots (continued) status 41 syntax for defining 19 tag 44 types of 21 SLOTS variable 220 state_change.baroc file 33 STATUS enumeration 24 status slot 41 STRING argument type described 53, 76 STRING data type 21 support, customer 3 symbols for BAROC language 18 syntax for BAROC language 18 for enumerations 23 for event policies 240 for Filter rules 199 for instance definitions 28 of class definitions 19 of selectors 241 unset_cause() primitive in Correlate rule 217

V
variables CELL_BUILD 220 CELL_DATE 220 CELL_NAME 220 CELL_RELEASE 220 CLASS 220 HOME 220 LOGNAME 220 MCELL_HOME 220 PKG_NAME 220 REQUESTOR 220 RULE_NAME 220 SHELL 220 SLOTS 220 TERM 220 WINDOWID 220

T
tag slot 44 TEC_CLASS metaclass 20 technical support 3 TERM variable 220 Threshold rules described 222 examples 224 primitives 224 processing during phase 223 syntax 224 TIME_FRAME data class 44 TIME_ZONE data class 44 timeframes data class 43 Timer rules described 227 examples 228 primitives 228 processing during phase 227 syntax 228 Tivoli TEC data type 21 metaclass 20

W
wildcards BEM_MATCH_TABLE 45 WINDOWID variable 220

U
universal identifiers for events and data 21 mc_udid 22 mc_ueid 22

Index

275

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

276

BMC Impact Solutions Knowledge Base Development Reference Guide

Notes

*02779* *02779* *02779* *02779*

*97720*