bmc impact integration developerâ€™s kit c api developer guide

www.bmc.com

BMC Impact Integration Developer’s Kit C APIDeveloper Guide

Supporting

BMC Impact Integration Developer’s Kit v.7.1

January 2008

Contacting BMC Software

You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.

United States and Canada

Address BMC SOFTWARE INC2101 CITYWEST BLVDHOUSTON TX 77042-2827 USA

Telephone 713 918 8800 or800 841 2031

Fax 713 918 8000

Outside United States and Canada

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

© Copyright 2003–2008 BMC Software, Inc.

BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners.

AIX and IBM are registered trademarks of International Business Machines Corporation.

Linux is the registered trademark of Linus Torvalds.

Oracle is a registered trademark of Oracle Corporation.

Java, Solaris, JRE, and Sun are trademarks or registered trademarks of Sun Microsystems, Inc., in the U.S. and several other countries.

UNIX is a registered trademark of The Open Group.

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 legendU.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA. Any contract notices should be sent to this address.

http://www.bmc.com

Customer support

You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or e-mail. To expedite your inquiry, see “Before contacting BMC.”

Support website

You can obtain technical support from BMC 24 hours a day, 7 days a week at http://www.bmc.com/support_home. From this website, you can

■ read overviews about support services and programs that BMC offers■ find the most current information about BMC products■ search a database for issues similar to yours and possible solutions■ order or download product documentation■ download products and maintenance■ report an issue or ask a question■ subscribe to receive proactive e-mail alerts when new product notices are released■ find worldwide BMC support center locations and contact information, including e-mail addresses, fax numbers, and

telephone numbers

Support by telephone or e-mail

In the United States and Canada, if you need technical support and do not have access to the web, call 800 537 1813 or send an e-mail message to [email protected]. (In the subject line, enter SupID:<yourSupportContractID>, such as SupID:12345). Outside the United States and Canada, contact your local support center for assistance.

Before contacting BMC

Have the following information available so that Customer Support can begin working on your issue immediately:

■ product information

— product name— product version (release number)— license number and password (trial or permanent)

■ operating system and environment information

— machine type— operating system type, version, and service pack or other maintenance level such as PUT or PTF— system hardware configuration— serial numbers— related software (database, application, and communication) including type, version, and service pack or

maintenance level

■ sequence of events leading to the issue

■ commands and options that you used

■ messages received (and the time and date that you received them)

— product error messages— messages from the operating system, such as file system full— messages from related software

3

http://www.bmc.com/support_home

mailto:[email protected]

License key and password information

If you have questions about your license key or password, contact BMC as follows:

■ (USA or Canada) Contact the Order Services Password Team at 800 841 2031, or send an e-mail message to [email protected].

■ (Europe, the Middle East, and Africa) Fax your questions to EMEA Contracts Administration at +31 20 354 8702, or send an e-mail message to [email protected].

■ (Asia-Pacific) Contact your BMC sales representative or your local BMC office.

4 BMC Impact Integration Developer’s Kit C API Developer Guide



ContentsChapter 1 Introduction 23

BMC Impact Integration Developer’s Kit overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Introduction to the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26License agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Support overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Intended audience for the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 2 Installing the BMC II C APIs 29

Reviewing Pre-Installation information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30System requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Tested compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Other requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Installing the BMC II C APIs in a development environment . . . . . . . . . . . . . . . . . . . 31Installing the BMC II C APIs on Microsoft Windows computers . . . . . . . . . . . . . 31Installing the BMC II C APIs on UNIX or Linux computers. . . . . . . . . . . . . . . . . . 33bmciiapi_7_1 directory structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Configuration and runtime files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Post-installation tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Setting the library path (UNIX and Linux only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Uninstalling the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 3 Configuration Basics 43

Background information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44BMC II C APIs basic configuration files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Configuration file directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46BMC II configuration utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

C APIs configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Editing parameter values in the IIDK.conf file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Editing the integrationName.trace File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Editing the integration mcell.dir File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Enabling BMC Impact Manager instances to connect to an integration . . . . . . . . 66

How to configure high availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66How to extend the configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Contents 5

Configuration Parameter Definition file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67CPD Generation Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Customizing the configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

How to customize the configuration package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72iidk.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Customizing the BMC II configuration utility GUI . . . . . . . . . . . . . . . . . . . . . . . . . 73Appending basic configuration parameters to your custom configuration file . . 75Localizing the BMC II configuration utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Packaging the BMC II configuration utility with your custom files. . . . . . . . . . . . 77

Chapter 4 Implementation Basics 79

Key terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Client and server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Modifies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Slots and metaslots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Client and server operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Library initialization and termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Translation and selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Autoreconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Propagation rules and propagation policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Chapter 5 General Programming Topics 89

Important general programming topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Including the header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90BMC Impact Manager classes and the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . 90Common Event Model compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Allocating and freeing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Changes to configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Message identification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Encryption key matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Registering modify requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Inserting additional slots in a Modify message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94bmcii_modifySlotValueList() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Language support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Deprecated functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Sample project code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Simple client project code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Simple query project code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Simple server project code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Sample component queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Sample class definition queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132


Chapter 6 Startup, Shutdown, and Configuration 143

Starting and stopping the integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Starting the integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Stopping the Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Initialization and termination functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147bmcii_init() (deprecated) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147bmcii_init2() (deprecated) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Best practices guideline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148bmcii_init3() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148bmcii_term() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Information functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154bmcii_connectionInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154bmcii_errorText() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154bmcii_localText() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155bmcii_Ltrace(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155bmcii_version() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Configuration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156bmcii_get_bool() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157bmcii_get_dir() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157bmcii_get_file(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157bmcii_get_num() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158bmcii_get_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Chapter 7 Server Mode 159

Server setup and use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Server mode functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

bmcii_setupServer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161bmcii_startServer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161bmcii_stopServer(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Chapter 8 Connections and Tracing 163

Directory functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164bmcii_getDirectoryInfoByName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164bmcii_getFirstDirectoryInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164bmcii_getNextDirectoryInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Connections and buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Connection intervals and connection acceptance . . . . . . . . . . . . . . . . . . . . . . . . . . 165Background receive thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Connection autoreconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Heartbeats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Maximum number of open outgoing connections . . . . . . . . . . . . . . . . . . . . . . . . . 168

Connection functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168bmcii_connect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168bmcii_disconnect(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Tracing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171bmcii_Ltrace(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Contents 7

bmcii_trace() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172bmcii_Ltrace_register() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Chapter 9 Message Construction 175

Creating and managing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Message format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Message identification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Message helper functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Message creation and deletion functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

bmcii_clearMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181bmcii_copyMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181bmcii_createMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181bmcii_freeMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182bmcii_getMessageType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182bmcii_setMessageType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Slot manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183bmcii_freeString(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184bmcii_freeStringList() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184bmcii_getSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184bmcii_messageGetBaroc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184bmcii_messageSetBaroc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185bmcii_removeSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185bmcii_removeSlotValueListItem(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185bmcii_setSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185bmcii_setSlotValueList() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186bmcii_setSlotValuesByArray() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Slot iteration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186bmcii_getFirstSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187bmcii_getNextSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Metadata functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188bmcii_getFirstMetaSlotValue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188bmcii_getNextMetaSlotValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189bmcii_getMetaSlotValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189bmcii_removeMetaSlotValue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189bmcii_setMetaSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Message information functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190bmcii_dumpMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190bmcii_getSlotCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Chapter 10 Sending and Receiving Messages and Replies 191

Sending and receiving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Sending messages and replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

bmcii_send() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Receiving messages and replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Client and server modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Receive functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Changes from previous release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194


bmcii_getFromQueue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195bmcii_freeRecv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195bmcii_RecvAll (deprecated). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195bmcii_recvAndGetFromQueue (deprecated) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196bmcii_startRecvThread() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196bmcii_stopRecvThread(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Register state change functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197bmcii_registerStateChange() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Workaround: multiple clients and state change events. . . . . . . . . . . . . . . . . . . . . 198bmcii_unregisterStateChange() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200bmcii_registerAnswer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201bmcii_registerCancel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202bmcii_registerClientConnectDisconnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202bmcii_registerConnectStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202bmcii_registerError(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203bmcii_registerModify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203bmcii_registerNewMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Implementing bmcii_getFromQueue() and callbacks . . . . . . . . . . . . . . . . . . . . . . . . . 204Function call sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Chapter 11 Queries 209

Managing queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Query characteristics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Query function call order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Query connection management functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213bmcii_closeQuery() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213bmcii_initQueryConnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214bmcii_termQueryConnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Query results functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214bmcii_freeQueryResults(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215bmcii_getQueryReply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215bmcii_retrieveQueryResults() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215bmcii_retrieveQueryResultsCB(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Query data helper functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216bmcii_queryData(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217bmcii_queryDataByHandles() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217bmcii_queryDataByMcudid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Query event helper functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217bmcii_queryEvents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218bmcii_queryEventsByCollector() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218bmcii_queryEventsByDate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219bmcii_queryEventsByHandles() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219bmcii_queryEventsByMcueid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Query service model component helper functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Querying across multiple cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221bmcii_queryComponentsByStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223bmcii_queryComponentsByCondition() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225bmcii_getComponentId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Contents 9

bmcii_queryComponentEvents(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Use case example of service model queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227bmcii_queryComponentStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228bmcii_queryComponent(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230bmcii_queryModelImpact() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230bmcii_queryModelCause() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231bmcii_queryModelPossibleRootCauses() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Class definition queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233bmcii_queryClassDefinitions(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236bmcii_getClassDefQueryReply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237bmcii_getClassNode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238bmcii_getClassDefByName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239bmcii_getSlotDefInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240bmcii_freeQuerySlotsHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241bmcii_closeQueryClassDef() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Service component status and mode functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242bmcii_setManualStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243bmcii_setMaintenanceMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Chapter 12 Translation and Selection 245

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246Translating events and data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

How translation works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Map files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Translation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263bmcii_loadMapSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264bmcii_translate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264bmcii_unloadMapSet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264bmcii_listMaps() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264bmcii_getMapInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265bmcii_getMapSetInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265bmcii_registerFunction() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Selecting messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Message selectors and subselectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266How message selection works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Message selector set files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Selection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282bmcii_listSelectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283bmcii_loadSelectorSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283bmcii_matchSelector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283bmcii_matchSelectorSet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284bmcii_matchSelectorSetAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284bmcii_matchSelectorSet2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285bmcii_matchSelectorSetAll2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285bmcii_unloadSelectorSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285bmcii_enableSelector(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286bmcii_getSelectorInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286bmcii_getSelectorSetInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286


bmcii_registerFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Chapter 13 Testing the Integration 289

Before running the tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290Verifying trace functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Verifying the library version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Testing connectivity and sending messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Testing message reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Chapter 14 Deploying the Integration 299

General deployment issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Where to install an integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Running multiple integration instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Configuration directory and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Additional information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Enabling BMC Impact Manager instances to connect to an integration . . . . . . . . . . 302Deploying multiple integration instances on the same computer . . . . . . . . . . . . . . . 303

Assigning an instance name, encryption code, and port number to an integration303

Running multiple integration instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Appendix A Defines, Typedefs, Structures, and Slot Definitions 307

Defines, typedefs, structures, and enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Defines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Structures and enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319EVENT root class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320DATA root class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Appendix B Working with the configuration utility 327

About the configuration utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Launching the configuration utility GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Updating configuration parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Editing message selector files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Modifying selector header values and selector criteria . . . . . . . . . . . . . . . . . . . . . 333Adding a message selector header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Deleting a selector header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Editing map files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Modifying map header values and map criteria . . . . . . . . . . . . . . . . . . . . . . . . . . 336Adding a map header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Deleting a map header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Editing the mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Adding a new cell or gateway entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Modifying a cell or gateway entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Commenting out an entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Deleting an entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Contents 11

Importing files and directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Backing up a configuration directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Viewing log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

Appendix C Common Event Model 345

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345Versioning support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347I18N compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Mapping quick reference: CEM to Baroc (CORE_EVENT) . . . . . . . . . . . . . . . . . . 348

Guidelines for applying CEM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Associating events with configuration items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Root cause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Adding attributes vs. adding generic slots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Cross-launching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Event synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Free-format text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

CEM property groupings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Source component properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Reporter component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359Situation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363Metric properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

Appendix D Error Codes 369

BMC II C API errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370BMC II C API errors listed by error code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370BMC II C API errors listed alphabetically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

BMC II C API informational messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385Informational messages listed by code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386Informational messages listed alphabetically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Core communications errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386Core communication errors listed by error code. . . . . . . . . . . . . . . . . . . . . . . . . . . 386Core communications errors listed alphabetically . . . . . . . . . . . . . . . . . . . . . . . . . 388Reportable error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392

Appendix E Gateway Configuration 393

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394Communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Contents parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Format parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397Variable reference allowance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399Parameter examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

Native BMC Impact Manager propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400TEC gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400


Glossary 401

Index 435

Contents 13

FiguresBasic Integration Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Sample Trace Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63BMC Impact Manager Definition Format for a Single Integration Instance . . . . . . . 65BMC Impact Manager Definition for Multiple Integration Instances . . . . . . . . . . . . . 65Sample mcell.dir File Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Sample CPD file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68CPD Generation Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70BMC Impact Integration configuration utility GUI (editable properties) . . . . . . . . . 74Custom configuration file with appended IIDK.conf file . . . . . . . . . . . . . . . . . . . . . . . 76Example of localized runBIIConfigUtil.bat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Example of localized runBIIConfigUtil.sh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Client and Server Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84mc_ueid and mc_udid ID Format for a Named Integration Instance . . . . . . . . . . . . . 92mc_ueid and mc_udid ID Format for an Unnamed Integration Instance . . . . . . . . . 92bmcii_connect Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Header information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Initializing the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Creating a message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Establishing a connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Sending a message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Receiving a reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Disconnecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Terminating the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Header information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Initializing the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Initializing the queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Calling the query: by date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Calling the query: by event handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Calling the query: by mc_ueid ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Calling the query: by event collector name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Getting query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Outputting query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Freeing query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Closing the query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Closing all queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Terminating the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Header information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Initializing the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Setting up the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Starting the receiving process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Figures 15

Receiving connections and events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Stopping the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Terminating the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Header information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Main declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Getting input parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Initializing the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Initializing the queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Calling the query functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Getting query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Outputting the query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Freeing the query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Closing the query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Closing all queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Terminating the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Header information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Main declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Getting initial input parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Initializing the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Initializing the queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Querying classes and slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Closing the query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Closing all queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Terminating the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141bmcii_trace(): Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173bmcii_Ltrace_register Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173BAROC message format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Receive thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Callback Definition Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Collector Name Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Collector Query Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Function call example: service model queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Call sequence: class definition queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Map file hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Sample Map Set Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252Sample Map Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253bmcii_registerFunction() process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Structure of message selector set file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273bmcii_registerFunction() process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287BMC Impact Manager Definition Format for a Single Integration Instance . . . . . . . 302BMC Impact Manager Definition Format for Multiple Integration Instances . . . . . 302BMC Impact Manager Definition Format 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304BMC Impact Manager Definition Format 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304Configuration utility GUI: initial view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329Sample configuration file in GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330Sample message selector file in GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Sample map file in GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335


Sample mcell.dir file in GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

Figures 17

TablesSupported operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Tested Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31BMC II C APIs Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Runtime and Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Shared Objects and Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Basic configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Configuration-related directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46IIDK.conf and Example.conf file configuration parameters . . . . . . . . . . . . . . . . . . . . . 49XML elements that support configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67File paths for locale files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Locale directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Trace parameter types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Code samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Initialization and termination functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Input arguments: bmcii_init3() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Configuration File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Information functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Output parameters: bmcii_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Configuration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Server Mode Functions by Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Directory functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Connection Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Tracing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Predefined Metaslots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Message Functions by Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Slot manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Slot iteration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Metadata Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Message Functions by Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Input arguments: bmcii_registerStateChange() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198SIM_NOTIFICATION_REGISTRY message class: required slots . . . . . . . . . . . . . . . 199Input arguments: bmcii_unregisterStateChange() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Callback functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Query connection management functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Query Results Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Query Data Helper Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Query Event Helper Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Service model query functions and default slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Tables 19

MC_SM_COMPONENT_STATUS values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Input arguments:bmcii_queryComponentsByStatus() . . . . . . . . . . . . . . . . . . . . . . . . 224Input arguments: bmcii_queryComponentsByCondition() . . . . . . . . . . . . . . . . . . . . 225Input arguments: bmcii_queryComponentsByEvents() . . . . . . . . . . . . . . . . . . . . . . . 227Computed component statuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Input arguments: bmcii_queryComponentStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Input arguments: bmcii_queryComponent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Input arguments: bmcii_queryModelImpact() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Input arguments: bmcii_queryModelCause() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232Input arguments: bmcii_queryModelPossibleRootCauses() . . . . . . . . . . . . . . . . . . . . 233Main class definition queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Input arguments: bmcii_setManualStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Input arguments: bmcii_setMaintenanceMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244Map Set Header Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251Map Header Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Map File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255Operators for $IF and $ElseIf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260General map operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262Keyword descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Translation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Message selector set header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271Message selector header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Message selector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274Message selector operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Keyword descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Selection Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282BMC II C APIs’ Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308BMCII_MESSAGE_TYPE Structure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310bmcii_BufferMode Enumeration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311bmcii_DirectoryInformation Structure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 311BmciiRecvTypes Structure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Bmcii_ReplyError Structure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Bmcii_ReplyCancel Structure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315BmciiAnsValue Structure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Bmcii_ReplySuccess Structure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316bmcii_ConnectNotify Structure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Bmciistatus Enumeration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318BMCII_ORDER Enumeration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319EVENT Class Slot Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320DATA Class Slot Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325BMC II configuration utility: editable files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Configuration file types and corresponding log file . . . . . . . . . . . . . . . . . . . . . . . . . . 343Property groupings: BMC_BaseEvent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347CEM to Baroc: Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348CEM to Baroc: source information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348CEM to Baroc: reporter information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349CEM to Baroc: situation information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349


CEM to Baroc: metric information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350EventInformation::EventToCIAssociationType parameter values . . . . . . . . . . . . . . 351ReportTime (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353EventModelVersion (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353EventClass (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353EventId (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Status (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354Timeout (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354Notes (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354EventToCIAssociationType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355PropagationHistory (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355RelationSource (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Owner (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Account (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356ResourceId (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356ReconciliationIdentity (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Alias (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357ComponentHost (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357ComponentHostAddress (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Location (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358ComponentURI (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358ComponentCaption (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358ComponentType (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358ComponentOwner (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359Slots for event monitoring information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360ResourceId (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360ComponentHostAddress (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360ComponentURI (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360ComponentCaption (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361ComponentType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361EventTime (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361EventType (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361EventId (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362EventSeverity (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362EventSuggestion (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362SituationCategory (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363Situation category (mc_event_category) values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363SituationTime (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365Priority (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365Severity (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366Message (recommended) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366Application (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366LongMessage (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367RepeatCount (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367MetricName (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367MetricValue (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367MetricValueUnit (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368MetricThreshold (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368BMC II C API Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Tables 21

Messages listed by code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386Core Communications Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387Predefined Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394Text Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Variable References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399


C h a p t e r 1
1 Introduction
This chapter presents the following topics:

BMC Impact Integration Developer’s Kit overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Introduction to the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26License agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Support overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Intended audience for the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 1 Introduction 23

BMC Impact Integration Developer’s Kit overview

BMC Impact Integration Developer’s Kit overview

The BMC Impact Integration Developer’s Kit (BMC II Developer’s Kit) enables developers to build applications that integrate with BMC Impact Manager events and data.

The BMC II Developer’s Kit includes:

■ C APIs—a toolkit that provides functions to interact with the BMC Impact Manager product and its components. This API can be used in C or C++ environments. These APIs offer developers the ability to quickly integrate and set up the bidirectional flow of events and data between their applications and the BMC Impact Manager product.

■ Web Services Interface—an open-standards Web services interface with which to implement loosely coupled BMC Impact Manager integrations, to build Web Services integrations that utilize BMC Impact Manager data, and to remotely access a BMC Impact Manager network through standard Web protocols.

These APIs offer developers the ability to quickly integrate and share events and data with the BMC Impact Manager product or to display BMC Impact Integration information in Web-based applications.

Introduction to the BMC II C APIsThe BMC II Developer’s Kit includes both BMC II C APIs and Web Services APIs. This book discusses the BMC II C APIs.

For more information on the web services APIs, see the BMC Impact Integration Developer’s Kit Web Services Server Reference Guide and the BMC Impact Integration Developer’s Kit Web Services Server Developer Guide.

The BMC II C APIs enable an integration to

■ send events and data to BMC Impact Managers and receive responses ■ perform queries on events and data■ perform queries on service model components and class definitions

An integration is an application that use the BMC II C APIs to enable an external or third-party application to access BMC Impact Manager event management, data management, and service model functions.


Features

The BMC II C APIs are designed to be flexible. Multiple API function calls can be combined to perform complex tasks. Most programming tasks can be performed in a variety of ways, enabling you to program as you prefer.

The BMC II C APIs are efficient and optimized. The BMC II C API is the interface with the fastest access to the BMC Impact Manager network.

Features

The BMC II C APIs provide the following features:

■ Enable your integration to send new events or modify existing events

■ Enable your integration to create data instances or modify existing instances

■ Enable your integration to receive events from a BMC Impact Manager instance

■ Easy manipulation of events and data that does not require developer knowledge about the BMC Impact Manager message format (BAROC)

■ Event translation functions that enable your integration to map a third-party event type to a BMC Impact event

■ Selector functions that enable your integration to select events and data according to criteria specified in an editable text file

■ Functions that access BMC Impact Manager directory information, which describes the BMC Impact Manager environment

■ Support for querying BMC Impact Manager instances for events and data based on criteria supplied by the integration

■ Query functions that retrieve service model component information from service models that have been published to a SIM cell

■ Query functions that retrieve class and slot definitions from classes that have been loaded in the Knowledge Base of a SIM cell

■ Robustness in a multithreaded environment

■ Event buffering that provides guaranteed message delivery

■ Capability to reconnect automatically with a dropped connection

■ Support for high availability


Architecture

Architecture

The integration that you build using the BMC II C APIs operates as a conduit between a third-party application and your BMC Impact Manager network.

Figure 1 Basic Integration Connectivity

The integration can act as a client, initiating connections with BMC Impact Manager instances. The integration can receive replies from a BMC Impact Manager instance to the messages that it sends

You can program the integration to act as a server or as a client-server. In server mode, the integration can accept connection requests from BMC Impact Manager instances, enabling it to receive messages or modification messages. In client-server mode, the integration initiates and accepts connection requests.

For more information about client and server modes, see “Client and server operation” on page 83 and Chapter 7, “Server Mode.”

License agreement

Using the BMC II C APIs requires that you accept the BMC Software - SDK License Agreement, a copy of which is contained at the back of this guide.


Support overview

Support overviewYou request the BMC Impact Integration Developer’s Kit through the BMC Developer Network site at http://developer.bmc.com. The kit is classified under the BMC Infrastructure Management developer center.

To obtain general support information, such as finding out how to extend the tools in the kit and develop integration applications, you can go to the BMC Developer Connection. It provides developers with moderated peer support and offers a free, supportive Web site where you can get answers to your questions about developing integrations with the BMC Impact Manager product. For more information on joining, go to the BMC Developer Connection Web site at http://devcon.bmc.com/.

If you have found a bug in the toolkit or an error in the documentation, please report it to BMC Customer Support. (See the Customer Support contact information in the front matter of this guide just after the title page.)

Intended audience for the BMC II C APIsThe audience of the BMC II C APIs is experienced developers who are knowledgeable about C programming and how BMC Impact Manager functions.

The programmer must understand what BMC Impact Manager does, how it transfers data from one BMC Impact Manager instance to another, and how this data is processed by the BMC Impact Manager instance.

NOTE At the time of publication, BMC intends to eventually migrate the content of the BMC Developer Connection website to the BMC Developer Network website at http://developer.bmc.com.


http://developer.bmc.com

http://devcon.bmc.com



Intended audience for the BMC II C APIs


C h a p t e r 2
2 Installing the BMC II C APIs

Reviewing Pre-Installation information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30System requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Tested compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Installing the BMC II C APIs in a development environment . . . . . . . . . . . . . . . . . . . 31Installing the BMC II C APIs on Microsoft Windows computers . . . . . . . . . . . . . 31Installing the BMC II C APIs on UNIX or Linux computers. . . . . . . . . . . . . . . . . . 33bmciiapi_7_1 directory structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Configuration and runtime files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Post-installation tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Setting the library path (UNIX and Linux only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Uninstalling the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41


Reviewing Pre-Installation information

Reviewing Pre-Installation informationApplications that use the BMC II C APIs must be developed and run on computers which use supported operating systems and compilers. Ensure that the computers in your BMC Impact Manager environment meet these requirements.

System requirements

The BMC II C APIs are supported on the following systems:

BMC IM support matrix

Table 2 lists the versions and features of BMC Impact Manager (BMC IM) that the BMC II C APIs support. Versions 5.1 and later provide language support for Simplified Chinese, Traditional Chinese, Korean, and Japanese languages.

Tested compilers

The BMC II C APIs were tested and verified using the compilers listed in Table 3. However, you should be any to use any compiler with the BMC II C APIs.

Table 1 Supported operating systems

Operating system Version or Service pack

Windows 2003 Server, 32-bit SP1

Red Hat Enterprise Linux® Advanced Server (Intel, 32-bit)

3.0, 4.0

SUSE Linux Enterprise Server (Intel, 32-bit) 9.0, 10.0

Sun™ Solaris™ (SPARC) 9, 10

IBM® AIX® (POWER) 5.2, 5.3

HP-UX (PA-RISC) 11i, v1, v2

Table 2 BMC IM support matrix

BMC IM version Event and data exchange Service model queries Language support

5.1 Yes Yes Yes

5.1.01 Yes Yes Yes

7.0.x Yes Yes Yes

7.1 Yes Yes Yes


Other requirements

Other requirements

You will need Acrobat Reader to view the PDF versions of the guide, and a web browser that supports frames to view the HTML version of the BMC Impact Integration Developer’s Kit C API Reference Guide.

Installing the BMC II C APIs in a development environment

Installation on a computer running UNIX or Linux is described on page 33.

Installing the BMC II C APIs on Microsoft Windows computers

By default, the BMC II C APIs installation installs the BMC II C APIs in the C:\Program Files\BMC Software\Impact\bmciiapi_7_1 directory.

1 Access the login page of the BMC Developer Network (BMCDN) website at http://developer.bmc.com.

2 After you log in, from the main menu choose Developer Centers => Infrastructure Management.

You can navigate to the web page where you can download the toolkit or toolkit component that you want. Refer to the release notes of the C API component for the latest download instructions.

The MS Windows downloadable file is IIAPI_71_win.EXE.

Table 3 Tested Compilers

Platform Compiler

Microsoft Windows Microsoft Visual Studio, version 6.0

All supported UNIX® and Linux versions

GNU Compiler Collection (GCC) versions 3.2 and 3.3 (in 32-bit mode)

NOTE For information about deploying your integration application and the BMC II C APIs in a production environment, see Chapter 14, “Deploying the Integration.”


https://webapps.bmc.com/epd/


Installing the BMC II C APIs on Microsoft Windows computers

3 After you download the file package, double-click IIAPI_71_win.EXE to launch the installation.

The InstallShield Wizard is opened, and the Welcome screen is displayed.

4 Click Next. The BMC Software—SDK License Agreement is displayed. For the text of this agreement, see the back matter in this guide.

5 Read the license agreement, and click the check box to indicate that you accept the terms. Click Next.

The Choose Destination Location screen is displayed.

If you do not accept the license agreement, click No to exit the installation.

6 Click Next to install the BMC II C APIs to the default location (C:\Program Files\BMC Software\Impact\bmciiapi_7_1) or click Browse to specify an alternate location.

The Start Copying Files screen is displayed.

7 Click Next.

The Setup Status screen is displayed while the files are copied to the Impact directory.

When the copy procedure is complete, the Setup Status screen closes and the InstallShield Wizard Complete screen is displayed.

8 Click Finish.

File installation is complete.

Where to go from here

You must configure the BMC II C APIs before using the APIs to build an integration.

Task Reference

“Post-installation tasks” page 40


Installing the BMC II C APIs on UNIX or Linux computers


1 Access the login page of the BMC Developer Network (BMCDN) website at http://developer.bmc.com.

2 After you log in, from the main menu choose Developer Centers => Infrastructure Management.

You are taken to the web page where you can download the toolkit or toolkit component that you want. Refer to the release notes of the C API component for the latest download instructions.

The UNIX or Linux downloadable file is IIDK_71_unix.tar.gz.

3 After you unpack the tarred file in the current working directory, navigate to the subdirectory to locate the installation script IIAPIINST, and enter the following command:

./IIAPIINST

The following text is displayed:

Welcome to the BMC Impact Integration API

This will install version 7.1Note: A full BMC Impact Integration APIinstallation requires about 12,546 K of space.

Press 'Enter' to continue

4 Press Enter.

The BMC Software—SDK License Agreement is displayed. For the text of this agreement, see the back matter in this guide.

NOTE Refer to the release notes of the C API component for the download instructions.

NOTE Press < at any time to return to the previous screen.


https://webapps.bmc.com/epd/



5 Press Enter to scroll through the agreement. Type accept and press Enter to accept the agreement.

The following prompt is displayed:

Where do you want to install the BMC Impact Integration API?

Enter the directory name:Current value ('Enter' to accept): /opt/mcellValue (or < for back):

6 Press Enter to install the BMC II C APIs in the default directory (/opt/mcell) or enter a different directory path and press Enter.

The following information is displayed:

Installation directory is:

install_directory

Available disk space: space_in_KB K

7 Press Enter. The following information is displayed:

Installation Settings:

Platform: platform_name

Target Directory: install_directory

Installing: BMC Impact Integration API

Estimated disk space required: 12,546 K

Space available on target: space_in_KB K

Do you wish to continue with the installation?

Enter 'y' for 'yes' or 'n' for 'no'.Response (or < for back):

8 Type y and press Enter to install the files.

TIP If you elect to install in the /opt/mcell directory path and a BMC Impact Manager instance is already installed, you may need to have root privileges to write to these directories.


bmciiapi_7_1 directory structure

Where to go from here

You must configure the BMC II C APIs before using them to build an integration

bmciiapi_7_1 directory structure

Table 4 lists the directories that are created when the installation package is installed.

NOTE The directory structure that is created is described in “bmciiapi_7_1 directory structure” on page 35. Installed files are described in “Configuration and runtime files” on page 36.

Task Reference

“Post-installation tasks” page 40

Table 4 BMC II C APIs Directory Structure

Directories Comments

Common

bmciiapi_7_1 BMC II C APIs directory

bmciiapi_7_1\config contains the following configuration files:

■ example.conf■ example.trace■ example.selector■ example.map■ mcell.dir■ recvfilterin.selector■ recvfilterout.selector■ sendfilterin.selector■ sendfilterout.selector

bmciiapi_7_1\config\locale contains I18N locale information which you can access through the following files:

■ default.load■ example.properties■ idkmsg.properties■ imgwmsg.properties

bmciiapi_7_1\config_utility contains the executable and configuration files for the end-user BMC Impact Integration configuration utility


Configuration and runtime files


Table 5 lists configuration and runtime files that are necessary for using the APIs.

bmciiapi_7_1\cpd_generation contains the executable and configuration files for the CPD utility that enables you, as a developer, to customize the configuration utility

bmciiapi_7_1\docs contains the BMC II C API Reference Guide HTML files

bmciiapi_7_1\examples contains code examples for client, server, and queries

bmciiapi_7_1\headers contains the API header files

bmciiapi_7_1\lib contains the platform-specific libraries directory

Windows

bmciiapi_7_1\lib\Win32 contains the bmciiapi.dll and bmciiapi.lib library files

UNIX

bmciiapi_7_1\lib\solaris_sparc contains the libiiapi.so.7.1.0 shared object file

bmciiapi_7_1\lib\aix_ppc contains the libiiapi.a shared object file

bmciiapi_7_1\lib\hpux11_parisc contains the libiiapi.sl shared object file

Before running the toolkit, make sure that you have executable permission on this file (chmod 755, for example). This is especially true if you have copied your installation to another directory.

bmciiapi_7_1\lib\linux_386 contains the libiiapi.so.7.1 shared object file

Table 4 BMC II C APIs Directory Structure

Directories Comments



Table 5 Runtime and Configuration Files (part 1 of 3)

File Name Description Location

bmciiapi.dll dynamic library on Microsoft Windows

Place the file in either of these locations:

■ your integration working directory

■ a directory that is included in the PATH on the integration host computer

bmciiapi.lib helper static library on Microsoft Windows

This file is used only in the development environment. Place it in the development integration source directory.

bmciiapi.lib is not distributed with the integration application.

libiiapi.so.7.1 shared object on Solaris and Linux

Do one of the following:

■ Create a soft link to the libiiapi.so.7.1 file in your working directory.

■ Link the libiiapi.so.7.1 file into a library directory included in the LD_LIBRARY_PATH or include the libiiapi.so file directory in the LD_LIBRARY_PATH.

libiiapi.a shared object on AIX Do one of the following:

■ Place the file in your integration working directory.

■ Link the libiiapi.a file into a directory included in the LIBPATH or include the libiiapi.a file directory in the LIBPATH.

libiiapi.sl shared object on HP-UX Do one of the following:

■ Place the file in your integration working directory.

■ Link the libiiapi.sl file into a directory included in the SHLIB_PATH or include the libiiapi.sl file directory in the SHLIB_PATH.



mcell.dir stores information about how to connect to a BMC Impact Manager instance or another integration, including the host name, port number, and encryption key. When a BMC Impact Manager instance name is given during a connection attempt, the Developer’s Kit looks for the name in this file.

This file is also used:

■ when the BMC Impact Manager instance connects to an integration

■ to store connection information about the integration, if it is in server mode.

You can share a single mcell.dir file with an BMC IM instance and your integration. Use the configuration parameter ServerDirectoryName in the IIDK.conf or your custom integrationName.conf file. (See “C APIs configuration parameters” on page 48 for more information.)

■ When a BMC Impact Manager instance is installed on the integration host, place the mcell.dir file in the MCELL_HOME/etc/ (or MCELL_HOME\etc\) directory.

■ When a BMC Impact Manager instance is not installed on the integration host, place the mcell.dir file in the integration configuration directory.

Note: When maintaining two mcell.dir files, ensure that any changes to a BMC Impact Manager instance or integration that is referenced in both files is updated in both.

example.conf API configuration file that you can use as a reference file

Place the file in your integration working directory. See Chapter 3, “Configuration Basics,” for more information about developing a configuration file and editing configuration parameters.





integrationName.trace file for configuring API trace capabilities

Place the file in your integration working directory.

uniqueid.dat file that stores unique ID values

The APIs require unique IDs in the following circumstances:

■ If the APIs create an mc_ueid ID for a message, the BMC II C APIs use the unique ID value as part of the message and then increment the unique ID value and store it in the file.

■ If the integration provides a message with its mc_ueid ID, the unique ID value stored in uniqueid.dat is used in the message handle returned by the bmcii_createMessage function.

Notes:

■ After a unique ID value is used, the APIs increment the value in the uniqueid.dat file by 1 automatically.

■ Do not modify the contents of the uniqueid.dat file.

The uniqueid.dat file is not installed with the BMC II C APIs. The BMC II C APIs create the file when it is required to store the current unique ID values.

The file is created in the integration_home\log directory.




Post-installation tasks

Post-installation tasksAfter you install the BMC C APIs, you should define certain environment variables.

Setting the library path (UNIX and Linux only)

If you are installing the BMC II C APIs on computers running UNIX or Linux, you should set the library path variable. Each version of UNIX uses a different library file and path. The files and paths are described in Table 6.

The shared object must be available to the integration process during startup in the current working directory or in the path.

Table 6 Shared Objects and Paths

Library Shared Object Path

libiiapi.so.7.1 For Solaris and Linux. Do one of the following:

■ Place the libiiapi.so.7.1 file in your integration working directory. Set the LD_LIBRARY_PATH to include “.”.

■ The libiiapi.so.7.1 file from a library directory included in the LD_LIBRARY_PATH or include the libiiapi.so.3.0 file directory in the LD_LIBRARY_PATH.

Note: You need to create a link called libiiapi.so to reference libiiapi.so.7.1 to enable versioning for future library versions.

libiiapi.a For AIX. Do one of the following:

■ Place the libiiapi.a file in your integration working directory. Set the LIBPATH to include “.”.

■ Link the libiiapi.a file from a library directory included in the LIBPATH or include the libiiapi.a file directory in the LIBPATH.

libiiapi.sl For HP-UX. Do one of the following:

■ Place the libiiapi.sl file in your integration working directory. Set the SHLIB_PATH to include “.”.

■ Link the libiiapi.sl file from a library directory included in the SHLIB_PATH or include the libiiapi.sl file directory in the SHLIB_PATH.


Uninstalling the BMC II C APIs


To uninstall the BMC II C APIs from a Microsoft Windows computer

1 Choose Start => Settings => Control Panel.

The Control Panel dialog box is displayed.

2 Double-click the Add/Remove Programs icon.

The Add/Remove Programs dialog box is displayed.

3 Select BMC Integration API, and click Change/Remove.

A confirmation dialog box is displayed.

4 Click OK to uninstall the BMC II C APIs.

An Uninstalling Files screen is displayed while the files are being deleted. When the file deletion procedure is complete, the Maintenance Complete screen is displayed.

NOTE The procedure for uninstalling the BMC II C APIs package from a computer running UNIX or Linux begins on page 42.



5 Click Finish to exit the uninstall utility.

To Uninstall the BMC II C APIs from a UNIX or Linux Computer

1 Log on as the user that installed the BMC II C APIs.

2 Navigate to the bmciiapi_7_1 directory’s parent directory.

3 Run the following command:

bmciiapi_7_1/IIAPIUNINST

The following text is displayed:

BMC Software, Inc. Uninstallation Script

Copyright (c) 2007, BMC Software, Inc. All Rights Reserved

This script will uninstall BMC Impact Integration API

Continue with uninstall?

Enter 'y' for 'yes' or 'n' for 'no'.

4 Type y and press Enter to uninstall the files.


C h a p t e r 3
3 Configuration Basics

Background information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44BMC II C APIs basic configuration files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Configuration file directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46BMC II configuration utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

C APIs configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Editing parameter values in the IIDK.conf file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Editing the integrationName.trace File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Editing the integration mcell.dir File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Enabling BMC Impact Manager instances to connect to an integration . . . . . . . . 66

How to configure high availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66How to extend the configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Configuration Parameter Definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67CPD Generation Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Customizing the configuration parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

How to customize the configuration package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72iidk.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Customizing the BMC II configuration utility GUI . . . . . . . . . . . . . . . . . . . . . . . . . 73Appending basic configuration parameters to your custom configuration file. . 75Localizing the BMC II configuration utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Packaging the BMC II configuration utility with your custom files . . . . . . . . . . . 77


Background information

Background informationThe BMC II C APIs supply several files that you can configure for different purposes. Table 7 lists some of them.

As you develop your integration application, you can

■ use the default configuration settings of the BMC II C APIs■ modify the default values of the BMC II C APIs’ configuration parameters■ extend the configuration parameters by adding new parameters■ customize the look and feel of the BMC Impact Integration (BMC II) Configuration

Utility

BMC II C APIs basic configuration files

Table 8 lists and briefly describes the basic configuration files that this chapter discusses.

Table 7 Configuration files

File name Description

mcell.dir directory file that stores information about a BMC Impact Manager instance or another integration application to which you have connected

example.trace configuration file that you use to configure the trace function in the BMC II C APIs

IIDK.confexample.conf

configuration file that contains the parameter configuration options for the BMC II C APIs

message selector files files for filtering events into or out of the integration application

map files files for translating event contents from one format to another

NOTE Message selector and map files are discussed in Chapter 12, “Translation and Selection.” They address the more advanced features of the BMC II Developer’s Kit: message filtering and translation.


BMC II C APIs basic configuration files

Table 8 Basic configuration files (part 1 of 2)


IIDK.confexample.conf

text files that contain the following information:

■ parameters that specify whether the tracing facility is used, where the trace parameters file is located, where the default log file that is created is located, and how that log file is maintained

■ parameters that determine how the APIs operate■ additional parameters required by your integration (not

by the APIs)

Use the example.conf as a reference file only.

Use the IIDK.conf as a template file to edit parameter values of the default classes and parameters. Then you can rename the file using your integration’s name, as in integrationName.conf. By default, the IIDK.conf is associated with an underlying XML file that defines its attributes.

Use the BMC Impact Integration configuration utility (BMC II configuration utility) to edit the configuration parameter values of the IIDK.conf file.

Integration.conf As an integration developer, you can customize and extend the default configuration classes and parameters by modifying and adding to the XML syntax of the underlying definition file.

Use the Integration.conf as a template file to create a customized configuration file with unique classes and parameters. Edit the Integration.conf in the Configuration Parameter Definition Generation Utility (CPD Generation Utility).

Note: The intergration.conf is distinguished from the IIDK.conf insofar as you edit the integration.conf to add new parameters and classes to the configuration file. You edit the IIDK.conf file only to modify the values of the default parameters.

example.trace a text file that determines how the BMC II C APIs perform debug tracing and other logging tasks

Use an editor to modify the .trace file.


Configuration file directories

Configuration file directories

The BMC II Developer’s Kit installation package consists of three configuration-related directories, listed in Table 9.

mcell.dir a text file that lists the identifying information for all BMC Impact Manager instances (cells) and integration servers to which your implementation can connect and communicate. It is used to look up a BMC Impact Manager instance or integration server name and to determine its host, port, and encryption key.

Any integration, including all integration instances, must be specified in the mcell.dir file of the cell to which it connects.

Use the BMC II configuration utility to edit the mcell.dir file.

NOTE The location and operation of the configuration, trace, and mcell.dir files are affected by parameters that you specify when you initialize the BMC II C APIs. Before creating an integration, see “bmcii_init3()” on page 148.

Table 9 Configuration-related directories

Directory name Contents description

config ■ example.conf■ example.trace■ mcell.dir■ example.map■ example.selector and other selector files■ message catalogs in the locale subdirectory

Package the config directory and its contents with your customer-facing integration application.

Table 8 Basic configuration files (part 2 of 2)



BMC II configuration utility

In the BMC II Developer’s Kit, the config_utility and cpd_generation directories make up the BMC II configuration utility package.

BMC II configuration utility

The BMC II configuration utility is a Java™-based GUI editor. As a developer, you and your integration users can use the BMC II configuration utility to edit the following files:

■ IIDK.conf or your custom integrationName.conf file■ mcell.dir

■ message selector filesThe BMC II C APIs ship with an example.selector file that you can use as a template for creating your own selectors and selector files using the BMC II configuration utility. The BMC II C APIs also include four supplemental selector files that you can use for filtering by setting the Enable parameter equal to TRUE. They are:■ recvfilterin.selector

■ recvfilterout.selector

■ sendfilterin.selector

■ sendfilterout.selector

■ map file

config_utility ■ BMC II configuration utility executable■ IIDK.conf■ copies of the map and selector files■ iidk.properities in the iidk subdirectory■ message catalogs in the resource subdirectory

Package the config_utility directory and its contents with your customer-facing integration application

cpd_generation ■ CPD Generation Utility executable■ Integration.conf■ IntegrationSampleCpd.xml■ copies of certain files contained in the config_utility

directory

Do not package the cpd_generation directory and its contents with your customer-facing integration application. This is a developer-only directory where you can customize your integration’s configuration file. Copy your modified files to the appropriate subdirectory of the config_utility directory.

Table 9 Configuration-related directories

Directory name Contents description


C APIs configuration parameters

The BMC II C APIs ship with an example.map file that you can use as a template for creating your own mapping criteria using the BMC II configuration utility.

Its executables and supporting files are found in the following file path:

■ %installDirectory%\bmciiapi_7_1\config_utility

■ $installDirectory/bmciiapi_7_1/config_utility

The BMC II configuration utility lets you and your customers modify

■ values and attributes of the selector and map files■ values in the mcell.dir file■ parameter values in the IIDK.conf or your custom integrationName.conf file

See Appendix B, “Working with the configuration utility,”for user-centered instructions on using the configuration utility as an editing tool.

To customize and extend a .conf file by adding, modifying, or deleting classes and parameters, use the CPD Generation Utility. See “CPD Generation Utility” on page 69 for more information.

C APIs configuration parametersThe BMC II C APIs supply predefined configuration parameters that you and your integration end users can apply to your integration application. You and your end users can use the default values or modify the default values to accommodate the integration application. You and your end users can modify the configuration parameter values through the BMC II configuration utility (or through a text editor).

Table 10 on page 49 describes the predefined configuration parameters and their default values. The BMC II C APIs provide two files that contain these configuration parameters: IIDK.conf and example.conf.

The example.conf file is considered a reference file. Use the IIDK.conf to modify configuration parameter values.

NOTE The reference file example.conf does not contain the IntegrationCPDFilePath parameter.



Table 10 IIDK.conf and Example.conf file configuration parameters (part 1 of 11)

Group Parameter Description

Impact Manager Instances

ServerDirectoryName path and name of the directory file (default file name: mcell.dir). Required.

BMC Software recommends that you store the mcell.dir file in the integration’s working directory or in the $MCELL_HOME/etc directory.

Notes:

■ The mcell.dir file contains a list of all BMC Impact Manager instances to which the integration can connect.

■ The integration can use the mcell.dir file supplied with the integration, or it can use the mcell.dir file of a BMC Impact Manager instance that is already installed on the same host. For more information, see “Selecting an mcell.dir file to use with the integration” on page 64.

CPD File Path IntegrationCPDFilePath File path to a unique XML file that defines new or updated classes and parameters for this configuration file

You cannot edit this parameter in the BMC II configuration utility. It should be generated automatically by the CPD Generation Utility.

The default is blank. The IIDK.conf file is linked by default to the IIDKCpdFile.xml file.



Connection Manager

ClientSourceIP static IP address that your integration can use when it is acting as a client (sending events). Optional.

ClientSourcePort port that your integration can use when it is acting as a client (sending events). Optional.

ConnectionSetupTimeOut maximum time, in seconds, that a CLI command attempts to establish a connection to a cell

If the connection with the cell cannot be completely established within this time frame, the command aborts.

Default: 10 seconds

Notes:

■ If the cell is busy with a database cleanup, it may be impossible to connect the CLI with the default values. A database cleanup has a duration limit defined by the EventDBCleanupDurationLimit option, with a default value of 30 seconds. With a default ConnectionSetupTimeOut of 10 seconds, the connection cannot be established within the first 20 seconds of a cleanup.

■ EventDBCleanupDurationLimit is described in BMC Impact Solutions: Administration.

ConnectionPortRange specifies the range of ports to use for outgoing connections

For a cell, this applies to forward propagation. It is the port used on the client side (or on the propagating cell side). This is useful only to pass the event through firewalls with high restrictions. Most firewall configurations ignore source port information but require destination port information.

However, firewall configuration usually can restrict the source ports as well.

The default is (empty).





Connection Manager, continued

ConnectionPortReuse indicates whether or not the ports specified in ConnectionPortRange should be reused as much as possible

By default, the cell or CLI tries to reuse ports from the specified range, in the given order. When ConnectionPortReuse=No, for every new connection within the same session, the next free port from the specified range is used. Only when it reaches the end of the range will it restart at the beginning of the range.

Default=Yes

ServerAllInterfaces specifies whether a newly-created server binds to all available interfaces. Optional.

Valid values:

■ YES or ON – binds (Default)■ NO or OFF – does not bind to all available

interfaces

You use this parameter whenever you run the BMC II C APIs as a service. When running a as service, you bind to a specific IP address where you receive all network traffic. If you have multiple Ethernet cards, you can say you want to bind to the same port on all of the Ethernet cards (interfaces). Alternatively, you can bind to a specific interface by binding to a specific IP address.

Note: For more information about binding and the ServerAllInterfaces cell configuration parameter, see BMC Impact Solutions: Administration.

Encryption indicates whether communications are encrypted

Valid values:

■ No■ Yes (Default)





Heartbeats

[This parameter applies to 5.1.01 and later cell connections.]

HeartBeatInterval integer that indicates the number of milliseconds between heartbeats. The default value is 30, 000 (1000 milliseconds = 1 second). The minimum value is 1000. The configuration file does not define a maximum value.

EnableHeartBeats a Boolean indicator that determines whether the integration component uses the heartbeat signal. Valid values are

■ true/false■ yes/no

The entries are not case sensitive.

Message Propagation

MessageBufferKeepSent time, in seconds, to keep sent messages buffered while waiting for an answer

Default: 300 seconds

MessageBufferKeepWait time, in seconds, that messages are retained in the buffer while waiting for the connection to be established

Default: 3600 seconds (one hour)

MessageBufferSize maximum number of messages that can be stored in the message buffer. Optional.

Default: 2000 messages

MessageBufferReconnectInterval period of time, in seconds, between attempts to connect to a BMC Impact Manager instance. Optional.

Default: 600 seconds

Notes:

■ The value of this parameter cannot be less than 60 seconds.

■ When a connection is established, the integration sends buffered messages that are designated for the BMC Impact Manager instance with which the connection is established.

For more information, see “Connection intervals and connection acceptance” on page 165.

MessageBufferResendCount number of times to resend unanswered messages

Default: 1





Persistency Buffer Manager

PersistencyEnabled enables persistency, which specifies additional buffering parameters when the buffer mode is Default

Valid values:

■ No (Default)■ Yes

Note: Though this parameter is disabled by default, you should enable it.

PersistencyLevel buffer mode used when the Default buffering mode is specified. This parameter is enabled only when the PersistencyEnabled parameter value is Yes. Optional.

Valid values:

■ None (Default)■ Low ■ High

Note: These values are case-sensitive and should be entered as shown here.

PersistencyFileName name of the file in which the buffered messages are stored

Default: log_directory\imgw-integrationName.dat

Notes:

■ The contents of the file are not deleted when the integration terminates unexpectedly.

■ You should add this parameter to the .conf file and set the value to No

PersistencyCleanupSizeThreshold

threshold size, in bytes, of the persistency file that activates garbage collection

PersistencyCleanupGarbageThreshold

threshold size, as a percentage of file size, of the persistency file that activates garbage collection

The default is 40 percent.





Persistency Buffer Manager (cont.)

PersistencyDisconnectRemovesMessages

indicates whether messages written to the persistency file are deleted when the integration disconnects intentionally from an Impact Manager instance

Valid values:

■ No■ Yes (default)

Receive buffer KeepRecvPersisted Boolean indicator that determines whether a message file persists when the associated message is removed from the message queue

Valid values are


The entries are not case sensitive. The default value is true or yes, indicating that the persistent file that contains a copy of the message remains after the message is removed from the queue.

When the integration is running in server mode and receives an incoming message (an event or a modify), it saves a copy of the message to a file. By default, the integration does not delete the message file until the integration calls the bmcii_freeMessage() function. If you set the KeepRecvPersisted parameter value to false or no, the integration deletes the message file when the message is removed from the queue.

ReceiveBufferDir the directory where receive buffer resides. The default is the log_directory

EnableRecvPersist Boolean indicator that shows whether the message file persists in the incoming buffer. The default is false, meaning that the message file is not persisted in the incoming buffer.

DropAcks Boolean indicator (true/false, yes/no) that tells the receive buffer to retain or drop acknowledgments. The default is true. When the DropAcks is set to true, the integration application does not receive replies indicating that the request is a success. However, the integration application still receives cancellation notices and error messages.





Receive Buffer (continued)

RecvBufferSize number value that restricts the number of

■ events■ acknowledgements■ error messages■ cancellation notifications■ status notifications■ connection notifications

that are stored in their respective buffers and that are received from a cell (propagation), an mposter command, or another integration.

These items are stored in two separate buffers. Incoming events and modifies are stored in one buffer file on the disk, while incoming error messages and notifications are stored in memory only, not on disk. The events and modifies are persisted in a single message files (see RecvBufferGarbage). The other items are not persisted in message files.

The default buffer size is 20,000, with a maximum of 500,000. If you set the value to 0, then the maximum value 500,000 is set as the buffer size.

This restriction does not apply to the send or outgoing buffer.

RecvBufferGarbage specifies the maximum number of events and modifies that the single event file, which buffers all incoming events, can reach before events and modifies that are marked-for-deletion are removed from the file. The default value is 10,000.

To illustrate, let’s say the RevcBufferGarbage value is set equal to its default value 10,000. As the RevcBufferGarbage event file reaches 10,000, you have deleted 3000 events, which means that 3000 events in the file have been marked-for-deletion. When the event file reaches 10,000 events, the 3000 marked-for-deletion events are purged from the file. The file then grows until it reaches the maximum size again, at which time the events that are marked-for-deletion are removed.





Trace Parameters Trace Boolean indicator that says whether tracing is enabled. Optional.

Valid values:

■ YES or ON– enable tracing■ NO or OFF – disable tracing (Default)

TraceSrc when displaying a trace message, specifies whether to display the source code file name and line number where trace message originated. Optional.

Valid values are:

■ YES or ON – display file name and line number

■ NO or OFF – no display of file name and line number

Note: Depending on the location of the trace message, the source may be in the integration or the Developer’s Kit code.

TraceTime Boolean indicator that says whether the date and time are appended to the trace file. The default value is YES. Valid values are

■ YES or ON – date and time are appended to the trace value

■ NO or OFF – date and time are not appended

TraceConfigFileName path and file name for the integrationName.trace file. Required, if Trace=YES.

The procedure for creating this file is described in “Editing the integrationName.trace File” on page 61.

TraceDefaultFileName default destination file to which trace messages are redirected from stderr, when the integration runs as a daemon or a service. Required, if Trace=YES.

TraceFileSize maximum size, in KB, of the trace messages file. Optional.

Valid values:

■ 0 - No limit■ n - size of file in KB

Note: BMC Software recommends that the value of this parameter be no less than 500 KB.





Trace Parameters(continued)

TraceFileHistory number of trace files to be kept in history. Each file numbered sequentially. Optional.

Valid values:

■ 0 – No files kept. (Default)■ n - number of files to keep

TraceFileAppend when the integration is restarted, specifies whether to append new trace messages to the existing message trace file. Optional.

Valid values:

■ YES or ON – appends new messages to the existing trace message file (Default)

■ NO or OFF - empties the current trace message file

Troubleshooting UseMemWatch Boolean indicator that activates a debug behaviors which determines whether the integration is passing bad data to the BMC II C APIs

Valid values are


The default value is false or no.

If you enable the UseMemWatch parameter, the BMC II C APIs maintain a list of valid memory that contains strings, string lists, messages, and replies. Any memory objects that the BMC II C APIs create and pass back to the integration are tracked and verified.

You can view any errors in the integration’s trace log.

The memory list created by the BMC II C APIs does not validate string values that are created by an integration.

DumpIncoming Boolean indicator that tells the integration whether to add incoming events to the trace file. The default is false.





Performance MinClientSleep For an integration that is defined as a client, this is a string value that determines the absolute minimum time for which the receive thread pauses during its processing.

The valid values are

■ 0 to 2000 milliseconds under Windows■ 1 to 2000 milliseconds on UNIX platforms

The default value is ten milliseconds on both platforms.

Note: If your client sends a large number of events in a continuous stream, you can consider increasing the MinClientSleep value so that the client can use more time to send events and the BMC IM cell can keep pace with the event processing.

MinSleep For an integration that is in server mode, this is a string value that determines the absolute minimum time for which the receive thread pauses during its processing.

The valid values are

■ 0 to 2000 milliseconds under Windows; default value is 0

■ 1 to 2000 milliseconds on UNIX platforms; default value is 1

MaxSleep string value that determines the upper range of the receive thread’s pause time

The valid values range from any value greater than the MinClientSleep or MinSleep value to 2000 milliseconds. The default value is 500 milliseconds.





Performance(continued)

MinQueryTimeout integer that specifies the absolute minimum time in milliseconds that the integration waits for a query result before it times out. The timeout period measures the time between responses from the cell. The default value is 2000 milliseconds (2 seconds).

For example, your query call requests 100 results. You receive the first 50 results without a delay equal to or greater than 2 seconds. However, you do not receive the next result within two seconds. Your integration then times out.

You can override this configuration parameter value in the query function bmcii_retrieveQueryResults by specifying a timeout value greater than the minimum specified by the MinQueryTimeout parameter. If the value is the same or lower, it is ignored.

Miscellaneous UniqueIDFile overrides the default name and/or location of the uniqueID.dat file. Optional.

Notes:

■ The default location is the workingDirectory/log/instance_name/uniqueID.dat. The location and name of this file can be overridden.

■ To use this parameter, the integration must have permission to write to the uniqueID.dat file.

■ The value of this parameter in this file increments by one (1) before a new ID is assigned.

LocaleConfigFileName directory path for I18N where the catalog files and .load file are located. The default is under the ./locale/path. This parameter is required.




Editing parameter values in the IIDK.conf file

Editing parameter values in the IIDK.conf file

Follow this procedure to modify the default parameter values to accommodate your integration requirements.

1 Launch the BMC II configuration utility using the appropriate executable file for your operating system:

■ %installDirectory%\bmciiapi_7_1\config_utility\runBIIConfigUtil.bat

■ $installDirectory/bmciiapi_7_1/cpd_generation/runBIIConfigUtil.sh

2 Choose File => Open. In the Open dialog box, navigate to the conf subdirectory, and choose IIDK.conf. Click Open.

3 Refer to Table 10 on page 49, and change parameter values accordingly.

4 Click Apply.

5 Choose File => Save As.

You can save the file under its current name or assign it a different name. If you give it a different name, you must change the iidkConfFile property setting in the iidk.properties file to the new name. See the guidelines under “iidk.properties file” on page 72 for more information.

6 Start or restart the integration (if it is already running) to initialize the changes. See the procedure in “Starting and stopping the integration” on page 144.

7 Grant the account under which the integration will run read access to the IIDK.conf file or your custom integrationName.conf file.

NOTE If you intend to run multiple integration instances on a single computer, review the information in “Deploying multiple integration instances on the same computer” on page 303 before performing this procedure.

NOTE You can use %H to specify the installation directory if the configuration utility is installed in the home directory, or %C to specify the installation directory if the configuration utility is installed in the configuration directory. If you do not include one of these or a relative path, the current working directory will be used.

For more information about path value variables, see BMC Impact Solutions: Administration.


Trace configuration file

Trace configuration fileThe trace functions are the logging facilities provided by the BMC II C APIs. Some internal errors or messages are sent through the trace functions.

If the integration application is running in the foreground, trace messages are written to standard output. If the integration is running in the background as Windows service or a UNIX daemon, then trace messages are written to the destination log that the configuration parameter TraceDefaultFileName (see Table 10 on page 49) has defined.

The naming convention for the trace configuration file is integrationName.trace. You can edit the file with any editor.

Configure trace functionality as you would in a BMC Impact Manager instance.

To set up tracing, modify

■ the trace parameters in the IIDK.conf or your custom integrationName.conf file. For more information, see “Editing parameter values in the IIDK.conf file” on page 60.

■ the trace configuration file. For more information, see the following task.

For more information, see BMC Impact Solutions: General Administration.

Editing the integrationName.trace File

Use the following procedure to edit the file that determines how the BMC II C APIs perform debug tracing.

TIP If you overrode the default location or name of the UniqueID.dat file, described in Table 10 on page 49, grant the integration write access to the file.


Editing the integrationName.trace File

To Edit the integrationName.trace File

1 Copy the example.trace file from the bmciiapi_7_1\config directory to the configuration directory of your integration.

2 In a text editor, open example.trace.

For a sample file, see Figure 2 on page 63.

3 Modify the file according to the instructions in the BMC Impact Solutions: General Administration guide.

4 Save the file using the integrationName.trace naming convention.

5 Grant the integration account read access to the integrationName.trace file.

6 Ensure that the TraceConfigFileName parameter in the IIDK.conf or your integrationName.conf file points to the location in which you saved the integrationName.trace file.


NOTE You can use the following substitution parameters in the .trace file.:

%H – home directory%C – configuration directory%L – Integration log file directory%T – Integration temporary file directory%P – Integration name%N – Instance name

For more information about path value variables, see the BMC Impact Solutions: Administration guide.


Mcell.dir file

Modifying the integrationName.trace File after Startup

If you modify integrationName.trace file after the integration is running, you must stop and restart the integration to make the configuration changes go into effect.

For procedures for starting and stopping the integration, see Chapter 6, “Startup, Shutdown, and Configuration.”

Mcell.dir fileThe mcell.dir file is a text file that lists the identifying information for all BMC Impact Manager instances (cells) and integration servers to which your implementation can connect and communicate. It is used to look up a BMC Impact Manager instance or integration server name and to determine its host, port, and encryption key.

Any integration, including all integration instances, must be specified in the mcell.dir file of the cell to which it connects.

Figure 2 Sample Trace Configuration File

# Trace configuration file## Configuration:# This configuration mentions the destination for trace # messages on a module/level basis. # Each configuration line overrides any possible previous # settings. ## Format of a configuration line:# Module Level Destination# Where# Module = name of module (see list 'Module' below)# Level = message level (see list 'Level' below)# Destination = destination file name or predefined value # (see list 'Destination' below)# A wildcard can be specified for Module and for Level :# ALL or *

ALL ALL stderrSERVICE ALL noSYNCH ALL noMESSAGES ALL no


Editing the integration mcell.dir File


You edit the mcell.dir file using the BMC II configuration utility. See Appendix B, “Working with the configuration utility,” for the procedures.

Selecting an mcell.dir file to use with the integration

■ If the integration is installed on a computer on which no BMC Impact Manager instance is installed, modify the sample mcell.dir file installed with the BMC II C APIs.

■ If the integration is installed on a computer on which a BMC Impact Manager instance is installed, specify that the integration use the mcell.dir file belonging to the BMC Impact Manager instance by specifying the existing mcell.dir file and path in the ServerDirectoryName parameter of the IIDK.conf or your integrationName.conf file. For more information, see “Editing parameter values in the IIDK.conf file” on page 60.

If you intend to use the settings in that mcell.dir file without further modification, skip the “To Edit the mcell.dir file in the integration home directory” procedure.

■ If you intend to run multiple integration instances on a single computer, review the information in “Deploying multiple integration instances on the same computer” on page 303 before performing the “Editing parameter values in the IIDK.conf file” on page 60 procedure.

Integration servers

An integration can connect to the BMC Impact Manager instances and integration server that are defined in its mcell.dir file.

Other BMC Impact Manager instances in the network can connect with the integration only if the integration is defined in their mcell.dir files.



The mcell.dir file is a text file. You can edit it with any text editor.

To Edit the mcell.dir file in the integration home directory

1 Copy the sample mcell.dir file from the bmciiapi_7_1\config directory to the configuration directory of your integration.

2 In the configuration utility, open mcell.dir. See Appendix B, “Working with the configuration utility,”for the procedures.

3 If the integration is running as a server, add the integration to the file, defining it as a cell. Use the format described in Figure 4 if the integration is running as a single instance on a computer. Use the format described in Figure 3 when creating entries for multiple instances of an integration that are running on a single computer.

NOTE The BMC Impact Manager instance checks mcell.dir to see if the message destination is defined as a gateway before propagating an event. If the destination is a gateway, the BMC Impact Manager instance finds the file associated with the gateway and builds the message in the specified format.

A gateway is specified in the mcell.dir file with the keyword, gateway, and the gateway file name.

A gateway file enables you to provide non-default event content and format information. Although you can specify that your integration is a gateway and require that a cell use the gateway file, it is not encouraged. Any changes to the format can cause unexpected behavior in the BMC II C APIs. For more information about using gateway files, see the BMC Impact Solutions: General Administration guide.

For more information about gateways, see Appendix E, “Gateway Configuration,” and BMC Impact Solutions: Knowledge Base Development.


Figure 3 BMC Impact Manager Definition Format for a Single Integration Instance

cell <integrationname>_<integrationhostname> <encryption_code> <integrationhostname>:<port>

Figure 4 BMC Impact Manager Definition for Multiple Integration Instances

cell <integrationname>_<instancename> <encryption_code> <integrationhostname>:<port>


Enabling BMC Impact Manager instances to connect to an integration

Figure 5 lists some sample mcell.dir entries.

4 Add the BMC Impact Manager instances that you want the integration to communicate with to the file, defining them as cells.

5 Save and close the mcell.dir file.


To enable BMC Impact Manager instances to communicate with your integration, you must add a cell definition for the integration to their mcell.dir files. This procedure is described in “Enabling BMC Impact Manager instances to connect to an integration” on page 302.

How to configure high availabilityVersion 7.1 of the BMC II C APIs support the high availability feature of the cell, meaning that you increase the availability of a cell in case a failure occurs. When a cell is defined for high availability, it has a primary and a secondary server, both with the same name. In the mcell.dir file of each server, the format of the definition looks as follows:

CellName is the name of the cell created on both servers. host1:port1 is the host name and port number of the primary server, and host2:port2 is the host name and port number of the secondary server.

NOTE For more information about assigning names to integration instances, see “Assigning an instance name, encryption code, and port number to an integration” on page 303.

Figure 5 Sample mcell.dir File Entries

cell digdug mc digdughost:999cell integ4_integ4host mc5 integ4host:990

cell CellName mc host1:port1 host2:port2


How to extend the configuration parameters

Refer to the BMC Impact Solutions: General Administration guide for specific instructions on how to configure a high availability cell. (Restart your integration whenever you modify the mcell.dir of a cell to which it is connected.)

When an integration is connected to a primary server of a high availability pair, it remains connected until the primary server fails. Then the integration automatically switches to the secondary server, maintaining the connection with the cell. When the secondary server goes into standby mode, the integration automatically switches back to the primary server. While trying to connect to a primary or secondary server, the integration buffers events in its persist.dat file.

How to extend the configuration parametersThe BMC II C APIs provide a utility that lets you extend the default configuration parameters by adding new ones to accommodate your integration needs. After you add these parameters to your custom configuration file, you can edit their values through the BMC II configuration utility.

Configuration Parameter Definition file

The BMC II C APIs supply a common Configuration Parameter Definition (CPD) XML file (IntegrationSampleCpd.xml) that allows you to define new parameters and group them into classes. You define each parameter by name, type, default value, description, and value ranges.

Table 11 on page 67 describes the elements of the IntegrationSampleCpd.xml file.

Table 11 XML elements that support configuration file (part 1 of 2)

Element Description

<General> contains the stanza that defines the general attributes of the integration application and its configuration file

<Integration_Name> the name of the integration application

<File_Type> defines the file as a configuration file. Enter Conf as a placeholder value.

<Config_File_Path> absolute or relative path to the configuration file

<Version> internal version number (for tracking purposes)

<Description> string description of the configuration file or of its modifications

<Class> contains the stanza that defines the class and parameter information that make up the configuration file’s contents. Each CPD file can have multiple classes, each class with multiple parameters.


Configuration Parameter Definition file

Figure 6 depicts the XML format of a sample CPD file.

Figure 6 Sample CPD file format

You can use the sample Integration.conf file, built from a CPD XML file, as a template from which to create a custom configuration file.

<Class_Name> name of the class. Required

<Description> description of the class. Optional

<Parameter> contains the parameter definition. Each class can have multiple parameters.

<Name> name of the parameter. Required

<Type> data type of the parameter. Required. The selections are

■ string■ Boolean■ integer■ file

<Default> default value assigned to this parameter. Required

<Description> description of the parameter. Optional

<Values> range of values associated with this parameter. Optional

<Min> minimum value. Optional

<Max> maximum value. Optional

<?xml version="1.0" standalone="yes"?><root> <General> <Integration_Name>IntegrationConnectTeam</Integration_Name> <File_Type>conf</File_Type> <Config_File_Path>Integration.conf</Config_File_Path> <Version>1.2.03</Version> <Description>These are newly created files</Description> </General> < <Class> <Class_Name>IntegrationClass</Class_Name> <Description>Description</Description> <Parameter> <Name>newParameter</Name> <Type>Integer</Type> <Default>50</Default> <Description>New Parameter</Description> <Values>10,20,50,100</Values> <Min></Min> <Max></Max> </Parameter> </Class></root>

Table 11 XML elements that support configuration file (part 2 of 2)

Element Description

CPD Generation Utility

CPD Generation Utility

Like the BMC II configuration utility, the CPD (Configuration Parameter Definition) Generation Utility is a Java-based GUI editor. However, it is designed to be used only by developers to generate XML files that define the classes and parameters of a customized configuration (.conf) file. You can create a unique configuration file with its own classes and parameters and its corresponding unique XML definitions file for each integration instance that you run.

Its executable and supporting files are found in the following file path:

■ %installDirectory%\bmciiapi_7_1\cpd_generation

■ $installDirectory/bmciiapi_7_1/cpd_generation

Customizing the configuration parameters

Build your custom configuration file using the Integration.conf file as a template.

Open the integration.conf in the CPD Generation Utility. In the CPD Generation Utility, you can add, delete, or modify

■ classes■ parameters within each class

After you complete your modifications, you save the file as a specified XML file, which the CPD Generation Utility builds based on the modifications you have made to the integration.conf file. This XML file is automatically linked to the integration.conf. The CPD Generation Utility writes the file path of the XML file as the value of the IntegrationCPDFilePath property in the Integration.conf text file, as in this example:

After the XML file is generated and the link with the configuration file is made, you can open the integration.conf file in the BMC II configuration utility and save the integration.conf file under a different name.

IntegrationCPDFilePath=C:/Program Files/BMC Software/MasterCell/bmciiapi_7_1/cpd_generation/conf/testIntegration.xml



To customize a configuration file

1 Launch the CPD Generation Utility using the appropriate executable for your operating system:

■ %installDirectory%\bmciiapi_7_1\cpd_generation\runCPDgenenUtil.bat

■ $installDirectory/bmciiapi_7_1/cpd_generation/runCPDGenenUtil.sh

2 From the tool bar, choose File => New => Integration CPD File.

3 In the New dialog box, navigate to the following directory:

■ %installDirectory%\bmciiapi_7_1\cpd_generation\conf

■ $installDirectory/bmciiapi_7_1/cpd_generation/conf

4 Open the Integration.conf file.

Figure 7 on page 70 depicts an example CPD Generation Utility with an open Integration.conf file.

Figure 7 CPD Generation Utility

5 Using the Integration.conf as a template, add, modify, or delete classes and parameters. Refer to Table 11 on page 67 for a description and a listing of required and optional values.



6 Click the General Information tab, and enter values in the Integration Name, Version, and Description text boxes.

7 Click the Preview tab to view the elements of the XML file that you are generating. They should reflect the classes and parameters that you have entered in the GUI.

8 Choose File => Save.

9 In the New dialog box, choose the conf subdirectory in the Save In drop-down box, and choose CPD Files (.xml) in the Files of Type drop-down box.

10 Enter a name for the XML file that will support the configuration, and click Save.

11 Choose File => Close to close the Integration.conf file.

12 Navigate to the conf directory, where you should see the XML file that you just created.

13 Open the XML file in an editor. Verify that the

■ <Config_File_Path> element points to the Integration.conf file■ classes and parameters that you entered in the GUI are written in the XML file

14 Close the XML file, and open the Integration.conf file in an editor. Verify that the

■ IntegrationCPDFilePath parameter points to the file path of the XML file you just created

■ the parameters that you entered in the GUI are written in the .conf file

15 Close the Integration.conf file, and launch the BMC II configuration utility.

16 Choose File => Open. In the Open dialog box, navigate to the conf subdirectory where the Integration.conf that you updated is stored. Open the Integration.conf in the BMC II configuration utility.

17 Choose File => Save As, and enter a unique name that is specific to your integration application for the Integration.conf.

18 Click Save.

19 Choose File => Close to close the Integration.conf file in the BMC II configuration utility.

TIP Both the configuration file and its supporting CPD XML file should be saved in the conf subdirectory.


How to customize the configuration package

20 Open the CPD XML file that you created in an editor.

21 In the <Config_File_Path> element, change the name of the .conf file in the path name from Integration.conf to its new name that you just entered.

22 Save the CPD XML file, and close it.

23 To test the link between the configuration and CPD XML files, open the new configuration file again in the BMC II configuration utility. It should display without error.

How to customize the configuration packageCustomizing the configuration package can involve

■ updating the BMC II configuration utility GUI

■ appending the basic configuration parameters to your custom configuration file

■ implementing localization

■ packaging your custom configuration files with the BMC II configuration utility and its supporting files in the config_utility directory

iidk.properties file

The iidk.properties file controls

■ aspects of the BMC II configuration utility’s GUI (logos, images, titles, and other text strings)

■ the link between the default XML file and the configuration file

Edit the iidk.properties in an editor to customize the BMC II configuration utility GUI and to append the default configuration classes and parameters to your customized configuration file.

You can find the iidk.properties file under

■ %installDirectory%\bmciiapi_7_1\cpd_generation\iidk

■ $installDirectory/bmciiapi_7_1/cpd_generation/iidk


Customizing the BMC II configuration utility GUI

You can modify the values of properties such as productName, title, and bmcImageLogoImage to accommodate the look and feel of your customized configuration utility.

You can point the iidkConfFile property to a specified configuration file. This association appends the basic classes and parameters of the IIDK.conf file (or your renamed configuration file) to the specified configuration file.

Guidelines on editing the iidk.properties file

■ The file paths to the gif images are relative to the BMC II C APIs’ working directory.

■ You manually enter the version numbers; they are not autogenerated.

■ The javaVersionStr of the About Dialog refers to JRE™ 1.4.2_04. This is the base JRE version. The configuration utility is compatible with JRE 1.4.2_07. It has not been tested against later versions of the JRE.

■ For your changes to take effect, start or restart the BMC II configuration utility.


By modifying the values in the iidk.properties file, you can change the images and the text of the BMC II configuration utility GUI to accommodate your custom configuration. You can also change the proprietary and versioning information in the About dialog box.

You can edit the following properties for text strings and images in the BMC II configuration GUI:

■ title■ bmcConfLogoImage■ toolBarLogoImage■ bmcImageLogoImage

When linking to a specify image file, remember to use a file path that is relative to the working directory of the BMC II C APIs.

WARNING Do not modify the iidkCPDFile and iiDKcpdFileName properties.



Figure 8 on page 74 depicts which aspect of the GUI that each property represents.

Figure 8 BMC Impact Integration configuration utility GUI (editable properties)

You can edit text strings in the About dialog box, including the following properties:

■ productName■ integrationVersionStr■ versionNumberStr■ helpFilePathStr (if a help file exists)■ webSiteStr■ buildNumberStr

To edit the iidk.properties file

1 Open the iidk.properties file in an editor. If you want to see your changes immediately in the BMC II configuration utility, open the iidk.properties file that is located in the iidk folder in the config_utility subdirectory.

2 Make your changes; then save and close the file.


Appending basic configuration parameters to your custom configuration file

3 Start or restart the BMC II configuration utility to initialize the changes.

Appending basic configuration parameters to your custom configuration file

In the iidk.properties file, the iidkConfFile property defines which .conf file is associated with the BMC II C APIs’ basic configuration parameter definitions. The default value is IIDK.conf (iidkConfFile = IIDK.conf). When you open the IIDK.conf file in the BMC II configuration utility, it automatically loads the basic configuration parameters of the BMC II C APIs.

If you set the iidkConfFile property equal to the name of your custom configuration file, you can append the basic configuration parameters (see Table 10 on page 49) to your custom configuration file. The contents of the IIDK.conf file are not written to your custom configuration file, but are linked to it. When you open your custom configuration file in the BMC II configuration utility, you see both the basic parameters and your custom parameters.

Before you begin

Ensure that your custom configuration file is not open in either the BMC II configuration utility or the CPD Generation Utility GUI.

1 Locate the iidk.properties file in the iidk folder of the config_utility subdirectory, and open it in an editor.

2 Go to the iidkConfFile property, which, by default, is set equal to IIDK.conf.

3 Delete IIDK.conf, and enter the name of your custom configuration file.

(Remember that both the .conf file and its supporting .xml file should be in the same conf folder.)

4 Save and close the iidk.properties file.

5 Start or restart the BMC II configuration utility.

6 Choose File => Open, and navigate to the conf folder where your custom configuration file is stored. Select your custom configuration file, and click Open.

NOTE If you edit the iidk.properties file in the iidk folder of the cpd_generation subdirectory, copy it over the iidk.properties in the config_utility subdirectory before you launch the BMC II configuration utility (Step 5).


Localizing the BMC II configuration utility

When it opens in the BMC II configuration utility GUI, it should contain the classes and parameters that are defined in the IIDK.conf file along with its unique classes and parameters. See Figure 9 on page 76 for an example.

Figure 9 Custom configuration file with appended IIDK.conf file

In this example, the custom configuration file, testtest.conf, contains the full range of predefined parameter classes of the IIDK.conf as well as its unique parameter classes IntegrationClass and Anewtestclass.

7 Click the Preview tab, and you see that the contents of your custom configuration file have not changed.

8 Close your file and exit the BMC II configuration utility.

Localizing the BMC II configuration utility

To localize the BMC II configuration utility, you create locale files from the iidk.properties and messages.properties files. You can find these files in the following paths:


Packaging the BMC II configuration utility with your custom files

After you create the locale files for the respective .properties files, you should rename them as follows:

■ iidk_localeCode.properties

■ Messages_localeCode.properties

where localeCode designates the language that you intend to use.

Next, you modify the startup script of the runBIIConfigUtil.bat or runBIIConfigUtil.sh file by appending the localeCode at the end of the script.

For example, if you localize the BMC II configuration utility in French, create the following locale files:

■ iidk_fr.properties

■ Messages_fr.properties

Then modify the runBIIConfigUtil.bat and runBIIConfigUtil.sh scripts as follows:


When developing your custom configuration file, you should be editing your files in the cpd_generation subdirectory. When you are satisfied with your customizations, copy your files over to the config_utility subdirectory.

Table 12 File paths for locale files

File File path

iidk.properties ■ %installDirectory%\bmciiapi_7_1\cpd_generation\iidk■ $installDirectory/bmciiapi_7_1/cpd_generation/iidk

Messages.properties ■ %installDirectory%\bmciiapi_7_1\cpd_generation\resources■ $installDirectory/bmciiapi_7_1/cpd_generation/resources

Figure 10 Example of localized runBIIConfigUtil.bat

java -classpath .;BIIConfigurationUtility.jar;LookandFeel\BMCCommonUILF.jar;LookandFeel\looks-1.2.2.jar com.BMC.BIIConfigurationUtility.main.BIIConfigurationUtility fr

Figure 11 Example of localized runBIIConfigUtil.sh

java -classpath .:BIIConfigurationUtility.jar:LookandFeel/BMCCommonUILF.jar:LookandFeel/looks-1.2.2.jar com. BMC.BIIConfigurationUtility.main.BIIConfigurationUtility fr



Package only the config_utility subdirectory with your integration application. Do not ship the CPD Generation Utility or the cpd_generation subdirectory.


C h a p t e r 4
4 Implementation Basics

Key terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Client and server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Modifies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Slots and metaslots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Client and server operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Library initialization and termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Translation and selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Autoreconnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Propagation rules and propagation policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86


Key terms

This chapter describes a number of BMC II Developer’s Kit concepts that are required to understand how to create a BMC Impact Manager integration.

Key termsTo build an integration successfully, you must be familiar with what events, data, and messages are, how they are constructed, and how they are used. The most important BMC Impact Manager terms are defined on this page. For more information about these terms and others, see the “Glossary,” and other books in the BMC Impact Manager documentation set.

Class

A class is a BAROC-language data structure that defines a type of object and content used in BMC Impact Manager. A class is made up of fields, called slots, that define its properties.

Client and server

In BMC Impact Manager terms, a client is a cell, a BMC Impact Manager instance, or an integration that sends event and data messages to other cells, BMC Impact Manager instances, or integrations. A server receives event and data messages from other cells, BMC Impact Manager instances, or integrations and can process these messages and pass them on to other cells, BMC Impact Manager instances, or integrations, or to a third-party application.

Client and Server modes are described in “Client and server operation” on page 83.

Data

Data is a shorthand reference for dynamic data. It refers to contextual reference data that is stored in a table in the repository (mcdb) and that can be updated during runtime. Administrators can use and manipulate dynamic data in the BMC Impact Manager Administration View.

The data class is a BAROC class that is a child of the base event class, DATA, and that defines a type of data. All data classes must be defined in the Knowledge Base.


Event

Data objects cannot be received because they cannot be propagated from a BMC Impact Manager instance.

Data instances are identified by the data_handle and the mc_udid ID. For more information, see “Message identification” on page 91.

Through an integration, your external or third party application can create, modify, delete, and query values contained in the BMC Impact Manager dynamic data tables. The BMC II Developer’s Kit also provides helper functions that format commands and retrieve information about the BMC Impact Manager network.

Data objects are discussed in Chapter 10, “Sending and Receiving Messages and Replies.”

For more information, see the BMC Impact Solutions: Knowledge Base Development guide.

Event

An event is a structured message passed to and from cells in a BMC Impact environment. It is an instance of an event class.

Events are identified in a BMC Impact Manager instance by the event_handle slot in the event and the mc_ueid ID.

Through an integration, your external or third party application can send, query, modify, and receive events. The BMC II Developer’s Kit provides the ability to select events and map third-party event formats to the BMC Impact Manager format.

Events are discussed in Chapter 10, “Sending and Receiving Messages and Replies.”

For more information, see the BMC Impact Solutions: Knowledge Base Development guide.

Messages

A message is a container for slot-value pairs and metaslot-value pairs. A message can contain

■ event, data, or service component instances■ modifies■ query results


Modifies

Use the functions described in Chapter 9, “Message Construction,” to create, modify and delete messages and the slots (attributes) that a message contains.

Modifies

A modify is a message notifying that an event has changed and requires updating. A modify includes the slot-value pairs that changed in the original event instance.

A modify can be sent in either of two directions:

■ An event instance that was sent to the integration from a BMC Impact Manager instance has been changed in the integration. The integration must send a modify message to the originating BMC Impact Manager instance to inform it to update the contents of its copy of the event. When a BMC Impact Manager instance sends a message, it automatically registers a request for modify messages with the integration.

■ An event instance that was propagated to a BMC Impact Manager instance from the integration is changed. The BMC Impact Manager instance will send a modify message to the integration if the integration registered a request for modify messages with the BMC Impact Manager instance.

For information about registering modify message requests in BMC Impact Manager instances, see “Registering modify requests” on page 94.

Slots and metaslots

A slot is an attribute in a BAROC class definition. A class definition consists of one or more slots. Each slot has a data type and can have specific attributes, called facets, that can control the values that the slot can have or control aspects of a class instance’s processing. A class that is a subclass to another class inherits all the slots of the parent class.

NOTE The modify does not apply to data objects.


Client and server operation

Metaslots are another type of message slots. Metaslots contain metadata, which specify how a message is processed, can contain a regular slot value (such as message type), or can act as a container for information that you want to include with the message. The metadata stored in metaslots in a message remains in the integration where it was specified. Metaslots and their values are not passed along with the message when it is sent to its destination. BMC Impact Manager instances do not handle metaslots.

There are a number of predefined metaslots. You can also create metaslots that conform to your requirements.

For more information about metaslots, see “Metadata” on page 178.

Client and server operationUsing the BMC II Developer’s Kit, you can run your integration in either of the following modes:

■ Client – can initiate a connection with a target BMC Impact Manager instance or integration

■ Server – can listen for and accept connections from other BMC Impact Manager instances and integrations

■ Client and server – can act simultaneously as both a client and a server

When acting only as a client or as a client and server, the integration can only receive replies from BMC Impact Manager instances and integrations with which the integration has already initiated a connection. The integration can also send events and data, modify messages, send queries, and receive query results.

However, to receive connection requests, events, and modify messages from a BMC Impact Manager instance with which the integration has not already initiated a connection, you must start server mode operation. For more information, see Chapter 7, “Server Mode.”

Integration behavior as a client and a server are illustrated in Figure 12 on page 84.


Library initialization and termination

Figure 12 Client and Server Behavior

Library initialization and terminationBefore the integration can access any BMC II Developer’s Kit functions, you must have registered for the appropriate callback functions. Once you have registered, you can call initialization functions to retrieve configuration data, allocate memory, and set up the trace facility.

For information about initialization, see Chapter 6, “Startup, Shutdown, and Configuration.”

NOTE If the initialization fails, you should not attempt to call the BMC II C APIs functions unless you receive the message BMCII_ALREADY_INITED.


Translation and selection

Translation and selectionThis section describes two ways that you can manipulate messages in your integration.

Translation

Mapping translates the content of the events. BMC Impact Manager instances cannot understand (process) events that originate in external (third-party) applications until those events are translated into a BMC Impact Manager class that the cell uses. A message that is sent from a BMC Impact Manager instance to a third-party application must be translated from the BMC Impact Manager format to the data type required by the third-party application.

For example, if an external source sends a message with a field called hard_drive, but the BMC Impact Manager class refers to the same entity as storage, mapping is required to enable both sides of the communication to understand the content of the message.

Translation is performed according to criteria that you specify in a map file. Map files are organized into sets that your integration calls.

Map files are external to the integration. You or the customer can modify map files to suit your environment.

Selection

Selection is a feature that enables you to specify criteria for matching messages to selection criteria that you provide. You can use selection for a variety of purposes, including filtering in messages, filtering out messages, choosing destinations for a message, or choosing a mapping to use for translation.

Translation and Selecting are discussed further in Chapter 12, “Translation and Selection.”


Queries

QueriesThe BMC II Developer’s Kit query functions enable the integration to use a number of queries to obtain events, data, component information, or class definitions from one or more BMC Impact Manager instances. The various queries provide different types of criteria for specifying which messages to obtain. Messages that match a query are sent from the BMC Impact Manager instance to the integration that initiated the query. Messages received as the result of a query can undergo processing in the integration or their contents can be forwarded as new messages to the supported third-party product.

You can launch queries to retrieve service model component information of service model components that have been published to the cell. You can also query class definitions of classes that are loaded in the KB of the specified cell.

For more information, see Chapter 11, “Queries.”

AutoreconnectIf the bmcii_connect function is unable to connect the integration to a BMC Impact Manager instance, it will attempt periodically to connect with the Impact Manager. The default interval between attempts is 600 seconds.

To set a non-default interval, add the MessageBufferReconnectInterval parameter to your custom integrationName.conf configuration file and specify a satisfactory interval, in seconds. The value that you specify can be no less than 60 seconds. For more information about MessageBufferReconnectInterval and other buffer configuration parameters, see “Uninstalling the BMC II C APIs” on page 41.

You can discard messages that are sent to a BMC Impact Manager instance to which no connection has been established (no buffering), or the integration can buffer the messages until a connection is made.

For more information about buffering, see “Buffering” on page 166.

Propagation rules and propagation policiesA BMC Impact Manager instance stores propagation rules in its Knowledge Base. A propagation rule provides instructions that describe the conditions under which the following occurs:


Propagation rules and propagation policies

■ certain events are sent from a BMC Impact Manager instance to an integration server

■ the integration server process the event or forwards the event

Propagation rules are part of a BMC Impact Manager instance’s Knowledge Base. These rules are used during the last stage of cell event processing. During this phase, each event is examined to see if it matches the where criteria of the rule. If it matches, the event is sent to the listed destination(s). If the destination is not available, the event is placed in the propagation buffer until the destination is available.

You can also define propagation policies that determine which events are propagated from the cell. For more information about propagation policies, see the BMC Impact Solutions: Administration guide.

Parameters that determine the behavior of the propagation buffer can be included in the custom integrationName.conf file. These parameters are described in Table 10 on page 49.

A BMC Impact Manager instance must have a propagation rule defined to send events to your integration. If you want your integration to receive events from a BMC Impact Manager instance, create the appropriate rules in that BMC Impact Manager instance Knowledge Base and set your integration to server mode. For more information about server mode, see Chapter 7, “Server Mode.”

The following is a sample propagation rule:

Rules are written in the Master Rule Language (MRL) format. For information about propagation rules and Master Rule Language, see BMC Impact Solutions: Knowledge Base Development.

propagate to_somegateway:EVENT ($EV) where[$EV.CLASS within [SMC_STATE_CHANGE,SM_SLA_EVENT] ]to somegatewaywhen $EV.status != CLOSED

END


Propagation rules and propagation policies


C h a p t e r 5
5 General Programming Topics
The first part of this chapter describes topics that are important to the programming of your integration. The second part of the chapter presents sample code for various integration operations.


Important general programming topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Including the header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90BMC Impact Manager classes and the BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . 90Common Event Model compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Allocating and freeing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Changes to configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Message identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Encryption key matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Registering modify requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Inserting additional slots in a Modify message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94bmcii_modifySlotValueList() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Language support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Deprecated functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Sample project code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Simple client project code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Simple query project code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Simple server project code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Sample component queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Sample class definition queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132


Important general programming topics

Important general programming topicsThe topics discussed in this section are general topics that are significant enough to warrant special attention and are general enough that they do not apply to only one phase of integration programming (such as initialization or debugging).

Including the header

To build an integration with the BMC II C APIs, the integration must include the BMC II C APIs’ header file iiapi.h. This header contains all of the necessary declarations and definitions for the BMC II C APIs. The header is designed for inclusion in a C environment. If it is included in a C++ integration, you might need to use an extern declaration such as:

Do not modify the iiapi.h file. Make your modifications in the integration-specific header files.

BMC Impact Manager classes and the BMC II C APIs

The BMC II C APIs do not verify slot membership in classes or the existence of a class. As a result, the BMC II C APIs will send any event, regardless of its validity.

Class and slot verification is performed by BMC Impact Manager instances, which may reject messages containing invalid class and slot definitions.

For the best results, ensure that the message classes sent from your integration are consistent with the classes defined in the BMC Impact Manager instance to which the message is sent.

extern “C”{#include “iiapi.h”}


Common Event Model compatibility

Common Event Model compatibility

To make your integration compatible with the Common Event Model (CEM) 1.1.00 format, first review Appendix C, “Common Event Model,” to gain an understanding of the required and optional slots. You will need to include the required slots when defining the objects and events of your integration. Next, you should decide which of the optional slots to include.

Allocating and freeing objects

Some of the BMC II C APIs’ functions allocate resources for storing strings and other information. It is your responsibility to free any resources that were allocated by a function by calling the appropriate IIDK API function that frees the resources.

For example, you create a message by calling the bmcii_createMessage() function. When the integration is done using the message, you must free the message resources by calling the bmcii_freeMessage() function. Do not use the bmcii_freeMessage() function directly on any memory that the developer’s kit allocates. Each type of returned item has its appropriate function.

Changes to configuration files

If you modify any of the following files, you must stop and restart your integration so that the changes will go into effect:

■ mcell.dir (of the integration)■ IIDK.conf or your custom integrationName.conf

■ integrationName.trace

For procedures for starting and stopping the integration, see Chapter 6, “Startup, Shutdown, and Configuration.”

Message identification

Event messages are identified by either of two ID slots, an mc_ueid ID or an event handle. Data messages are identified by either of two slots, an mc_udid ID or a data handle.



mc_ueid ID and mc_udid ID

The mc_ueid ID is a unique ID that is assigned to an event (message) in a BMC Impact Manager instance. The mc_udid ID is a unique ID that is assigned to a data message in a BMC Impact Manager instance. Once either ID is assigned, it remains with the message until it is destroyed.

If your integration does not assign a message an mc_ueid or mc_udid ID automatically, the IIDK APIs assign the mc_ueid or mc_udid ID to the message.

If the integration has an instance name, the mc_ueid ID and the mc_udid ID are expressed in the format displayed in Figure 13.

If the integration does not have an instance name, the mc_ueid ID and the mc_udid ID are expressed in the format displayed in Figure 14.

Event and data handles

A handle is a numeric ID assigned by a BMC Impact Manager instance. The event handle, which is unique within the BMC Impact Manager instance, is used by the BMC Impact Manager instance when processing functions that affect the message.

The message loses its handle when it is propagated to another BMC Impact Manager instance. Each cell that receives the event will assign its own event handle.

Figure 13 mc_ueid and mc_udid ID Format for a Named Integration Instance

<integrationName>_<instance_name>.<time_t>.<unique_num_ID>

Figure 14 mc_ueid and mc_udid ID Format for an Unnamed Integration Instance

<integrationName>_<host_name>.<time_t>.<unique_num_ID>

NOTE You can include a colon (:) or a forward slash (/) in a mc_ueid ID or mc_udid ID. This may be useful when specifying a hostname.

The <host_name> parameter is the name of the system on which the integration is running.

The <time_t> parameter used in the mc_ueid and mc_udid IDs refers to time_t, the number of seconds since January 1, 1970, represented in Base-36.

The <unique_num_ID> parameter used in the mc_ueid and mc_udid IDs is a unique number that is generated by the BMC II C APIs, stored in the UniqueID.dat file, and incremented by the APIs each time that a unique ID is required.


Encryption key matching

UniqueID.dat file

The UniqueID.dat file is created by the BMC II C APIs after the integration is initialized for the first time. This file stores the current unique numerical ID that is used in both the mc_ueid ID and the event handle.

The BMC II C APIs increment the Unique ID value in the file by 1 before the value is used.

Encryption key matching

Each integration and BMC Impact Manager instance is assigned an alphanumeric encryption key. The default key is mc. The encryption key can be any combination of letters and numbers up to 160 characters long.

When an integration tries to connect to a BMC Impact Manager instance it needs the proper key for that destination. A BMC Impact Manager instance needs the proper key to connect to any integration operating in server mode.

The server’s encryption key is included in the identifying data about that recipient listed in the mcell.dir file. When the sending application queries to the mcell.dir file for information about the message recipient, it obtains the required encryption key, as well the recipient’s hostname, port, and so on.

For example, Integration PEAR is establishing a connection with BMC Impact Manager instance APPLE as a prerequisite for sending an event message to APPLE. When APPLE is specified for *szServerName in the bmcii_connect function call (Figure 15), the integration obtains the following information about the APPLE BMC Impact Manager instance from the mcell.dir file:

cell APPLE mc5 APPLEhost:990

where:

■ BMC Impact Manager instance name=APPLE

■ Encryption key=mc5

■ hostname=APPLEhost

■ Port=990

Figure 15 bmcii_connect Function

bmcii_result bmcii_connect(BMCII_SEC_TOKEN SecToken, BMCII_STR *szServerName, unsigned short usBufferType,BMCII_CNC *cnc)


Registering modify requests

Registering modify requests

A BMC Impact Manger instance keeps a list of all destinations to which an event has been propagated and the source of the event. The instance can be informed by the mcell.propagate file which slots, when changed, should trigger a modify message to be sent to the destinations and/or the source. This modify message should contain the mc_ueid and the slots that have been modified.

If the integration sends an event to the IM and if it wants to be notified of any updates, then it should set the mc_history slot with the proper information.

BMC Impact Manager instances register automatically to receive modifies. You must specify that your integration register to receive modifies. Registration is on a per-message basis.

To register a modify request for a message, you must specify the following value in the message mc_history slot:

servername:0

where servername is the name that is used by your server in the bmcii_setupServer() function.

The 0 indicates that you want the mc_ueid to be sent with the modify. Otherwise, if you use another number, the Impact Manger instance sends the modify with an event_handle with the specified number.

Best practices guideline

As a best practices guideline, enter servername:0 to use the mc_ueid with the modify.

The mc_history slot is a LIST_OF slot. Use the bmcii_setSlotValueList() function to set the slot value. If mc_history contains one or more values, set the servername:0 value as the last value in the index. Otherwise, servername:0 must be the only value in the mc_history slot.

Inserting additional slots in a Modify message

1 Change the cell entry in the mcell.dir file of the destination cell from cell to gateway.integrationName, as in

cellintegrationName_hostNamemchostName:portNumber


bmcii_modifySlotValueList()

integrationName is a variable for which you substitute the name of your integration application.

2 Copy the gateway.example file from the BMC II Developer’s Kit installation directory to the $MCELL_HOME/etc or %MCELL_HOME%\etc directory of the destination cell.

3 Rename the gateway.example file to gateway.integrationName.

4 Edit the slots.mod parameter of the renamed gateway.integrationName file by assigning the slot name to the list of arguments. For example:

If the slot name is not in the

■ EVENT class for BMC Impact Manager versions 3.5 or earlier■ CORE_EVENT class for BMC Impact Manager versions 4.1 or later

then you need to prefix the slot name with the class name and a period.

5 Restart the BMC Impact Manager instance (cell).

You can refer to Appendix E, “Gateway Configuration,”for more information about the gateway file.

bmcii_modifySlotValueList()

Use the bmcii_modifySlotValueList() function with a modify message you intend to send to a cell. You can manipulate slot values in a LIST_OF structure. You can append, insert, or delete values of slots in the LIST_OF structure.

For example, you can define an event with a slot called numbers. The slot contains the values 2, 3, 7, and 9 (2,3,7,9). Using the bmcii_modifySlotValueList() function, you append the value 11 to the end of the list, insert 5 after 3, and delete 2. The resulting modify message would contain a numbers slot with the following values: (3, 5, 7, 9, 11). You can use this function to append notes to the mc_notes slot of the EVENT class without overriding the slot.

gateway.integrationNameintegrationName_hostNamemchostName:portNumber

slots.mod=[mc_ueid,slotName,$MODS]


Language support

You can use the ModifyType parameter with the bmcii_modifySlotValueList() function, using the following values:

■ BMCII_REPLACE which replaces the provided value for any existing values■ BMCII_APPEND which appends the value at the end of list■ BMCII_INSERT which inserts the provided value at the index■ BMCII_DELETE which deletes any values that match the provided value

The function declaration is as follows:

Language support

BMC II Developer’s Kit 3.0 provides language support for integration applications.

The BMC II Developer’s Kit relies on UTF-8 encoding to enable localization in non-English languages. To be localized in a non-English language, your integration application must pass all parameters to the developer’s kit in UTF-8 encoded strings.

NOTE The bmcii_modifySlotValueList() function is compatible with BMC Impact Manager 7.x or higher. It is not possible for this function to check the destination type, so the error will be the return value from the BMC Impact Manager.

bmcii_result bmcii_modifySlotValueList(BMCII_MESSAGE pMessage, BMCII_STR *szSlotName, BMCII_STR *szSlotValue, ModifyType Type, unsigned int iIndex);

NOTE If you add new notes to the mc_notes slot, new notes are inserted in the beginning of the list rather than at the end. Each note consists of 3 values:

1. time (time_t in hex format)

2. user making the note,

3. comment.

If you insert less than all three values, the notes are inconsistent.

TIP BMC Impact Manager 5.1 supports multiple languages. The previous versions do not. If you wish to localize event messages in your integration application, you must use a version 5.1 or later BMC IM cell.


Language support

The BMC II Developer’s Kit 3.0 distribution package includes a locale subdirectory, which is installed under the %installationDirectory%\config or $installationDirectory/config path. The locale subdirectory contains a loader file and two catalog files, all of which are listed and described in Table 13 on page 97.

The three main components of the BMC II C APIs that you can localize are

■ error strings generated by the integration■ trace strings to capture debug information■ event strings, provided that you connect with a version 5.1 (or later) BMC IM cell

and localize the event messages

When localizing strings in non-English languages, you should ensure that the following files are UTF-8 encoded:

■ mcell.dir ■ IIDK.conf or your custom integrationName.conf

■ mcell.group

■ integrationName.trace

■ all message catalog files in the locale subdirectory

NOTE If you intend to use English language strings only, you can continue using ASCII encoding.

Table 13 Locale directory contents


default.load sample loader file that contains the names of the catalog files that will be loaded for the integration application. Enter each catalog file name on a separate line, and do not include the file name extension.

When you create your properties file for your integration, you add the name of the file (without the extension) to the .load file as well. The entries in the loader file should look as follows:

integrationNameiidkmsgimgwmsg

iidkmsg. properties contains the English language version of the integration’s standard error message strings that you can localize

imgwmsg.properties contains the English language version of the trace message strings used by the BMC IM cell


Language support

Functions to use

The BMC II C APIs use the following four functions with localized strings:

■ bmcii_Ltrace_register()■ bmcii_Ltrace()■ bmcii_errorText()■ bmcii_LocalText()

Localization functions

The developer’s kit provides the function bmcii_LocalText() to provide a way for the integration to localize strings. The strings are stored in any of the .properties files. Each .properties file contains a unique message key followed by an equals sign (=) and then the localized string. When you pass a message key to the bmcii_LocalText() function, it looks up the key and returns the localized version of the string. It returns the string most appropriate for the locale setting of the application.

Localizing event messages

To use localized content in event messages, you must use version 5.1 or later of BMC Impact Manager and ensure that the event message strings of your integration application are in UTF-8 encoding.

To enable your integration to use any of the localization functions, you must first configure the locale directory.

By default, your integration should have the locale directory as a subdirectory of the %Home% or $Home directory or as a subdirectory of the config directory. You can specify the location of the locale directory by setting the LocaleConfigFileName parameter in the IIDK.conf or your custom integrationName.conf file equal to the full path and file name of the .load file in the locale directory.

To send localized events you simply need to define the slot as a UTF-8 encoded string and send it. You do not have to use the locale files to send localized events.

Localizing error messages

The bmcii_errorText() function (see “bmcii_errorText()” on page 154) has been updated to provide a pointer to locale-specific error strings that describe return codes.

The bmcii_errorText() function takes as input the return code numeral. It then searches the message catalog in the locale directory for the corresponding English string and message key in the iidkmsg.properties catalog.


Language support

The bmcii_localText() function calls the locale-specific message catalogs. It takes as input the message key and returns the localized string.

Localizing trace messages

If you want to have localized trace output for your integration, then you must create the non-English trace message catalogs and save them in the %installationDirectory%\config\locale or $installationDirectory/config/locale directory path.

The bmcii_LtraceRegister() function associates a source code file name with a module name. The module name becomes part of the trace message in the trace log. In this way, each trace message is associated with a specific file name.

Call the bmcii_LtraceRegister() function before you call the bmcii_Ltrace() function in each source file that uses the bmcii_Ltrace() function. You should also call bmcii_LtraceRegister() before making any calls to the bmcii_Ltrace() functions.

The bmcii_Ltrace() outputs the trace text in the designated non-English local language. It takes as input the message key, the trace level, and TR_AT parameter types.

Trace parameter types

When building your localized string, you enter the following trace parameter types to designate the parameter types in your string.

NOTE A message key can be any unique string. The format for the message keys of trace messages is shown below:

■ the prefix BMC■ followed by a hyphen (-)■ a three-character program ID that identifies the integration application (IDK)■ a three-integer ID that specifies the file (000)■ the three-integer error code (102)■ a single-character entry that identifies the severity level of the message (E)

Example: BMC-IDK000102E

Table 14 Trace parameter types

Parameter type Description

TR_ARG_END indicates the end of the parameter set

TR_ARG_BOOL indicates that the following parameter is a Boolean type


Language support

Converting trace functions to localized trace functions

You can use the existing bmcii_trace() and bmcii_trace_register() functions as templates from which to create bmcii_Ltrace() and bmcii_Ltrace_register() functions to handle localized strings.

Before you begin

Use the default locale subdirectory (%installationDirectory%\config\locale) or create one of your own in the installation path of your integration. Alternatively, you can use the locale subdirectory of the BMC Impact Manager instance, located at $MCELL_HOME\etc\locale.

Ensure that you have a .properties file in the locale subdirectory with the name of your integration: integrationName.properties. This file consists of English message keys as described under “Localizing error messages” on page 98.

Ensure that the locale directory contains a .load file with the name of your integration: integrationName.load. Or you can use the default.load file name. The default.load file can contain the name of the integration. It should also contain the following file names:

1 Modify the bmcii_init() function and rename it as bmcii_init3(). Include an input argument for the integration name. For example,

Change

BMCII_STR *szIntegrationName

TR_ARG_UINT indicates that the following parameter is an unsigned integer type

TR_ARG_INIT indicates that the following parameter is an integer type

TR_ARG_REAL indicates that the following parameter is a floating point data type

TR_ARG_STR indicates that the following parameter is a string data type

TR_ARG_KEY indicates that the following term is a keyword

integrationNameiidkmsgimgwmsgmcellmsglangmsg

Table 14 Trace parameter types

Parameter type Description


Language support

to

BMCII_STR *IWS

2 Add the input argument that tells whether the BMC II Developer’s Kit should change the current working directory to the specified home directory. For example, to maintain the current working directory and not change to the home directory, enter

INIT_NO_CHANGEDIR

To allow the change to the home directory, enter

INIT_FLAG_NONE

3 Open the IIDK.conf or your custom integrationName.conf file, and change the following entry to point to your integrationName.load in the locale subdirectory.

4 Step through your code, changing the bmcii_trace_register() function entries to bmcii_Ltrace_register. Add the module number that your message key uses as input argument. For example:

Change

bmcii_trace_register(“COMMUNICATIONS”, TR_ID);

to

bmcii_LTrace_register(“COMMUNICATIONS”, 999, TR_ID);

where 999 is the module number used by the message key in the integrationName.properties file. The module number must be unique among all the source files.

5 Step through your code again, this time changing the bmcii_trace() function entries to bmcii_Ltrace() function entries. Substitute the error message number and the appropriate trace parameter type for the error message text. For example:

Change

bmcii_trace (TR_VERBOSE, “This is an error with a string %s and a number %d”, szMsg, iNum);

to

#LocaleConfigFileName=installationDirectory/config/locale/integrationName.load


Deprecated functions

bmcii_Ltrace (TR_VERBOSE, 117, TR_ARG_STR, szMsg, TR_ARG_INT, iNum, TR_AT_END);

The corresponding entry in the integrationName.properties file might look as follows, assuming that the integration application is Web Services (IWS), the module number is 999, and the message type is V:

BMC-IWS999117V=This is an error with string {0} and a number {1}

where values are substituted for {0} and {1}.

Deprecated functions

Specific BMC II C API functions were deprecated in previous releases. These include

■ bmcii_init()■ bmcii_init2()■ bmcii_RecvAll()■ bmcii_recvAndGetFromQueue()

These functions are included in this package, but they generate no effects. In some cases, newer versions of the functions have been added. They are noted by an incremental numeric suffix attached to the function name: for example, bmcii_init3().

Sample project codeThe BMC II C APIs’ installation includes five sample projects that you can run.

TIP Best practices guideline. Leave the string as a comment above the trace message to make it easier to read your source code: for example

// “This is an error with a string %s and a number %d”

Table 15 Code samples

Folder name Description

simpleclient builds a simple client and sends a message to a BMC Impact Manager cell

simplequery executes simple queries


Simple client project code

You can find these code samples in subdirectories of the bmciiapi_7_1\examples directory.

Before running the projects, you must perform some preparatory steps to prepare the runtime environment. These steps are described in the readme.txt file in each project subdirectory.


The simple client project builds an integration that performs the following functions:

■ Initializing the BMC II C APIs (Figure 17 on page 104)■ Creating a message (Figure 18 on page 105)■ Establishing a connection (Figure 19 on page 106)■ Sending a message (Figure 20 on page 106)■ Receiving a reply (Figure 21 on page 107)■ Disconnecting (Figure 22 on page 109)■ Terminating the BMC II C APIs (Figure 23 on page 110)

simpleserver builds a simple server that accepts connections and events

classDefQuery executes queries that retrieve static class definition information from a BMC Impact Manger instance

compQuery executes queries that retrieve dynamic service component information about components that have been published to a BMC Impact Manager instance

Table 15 Code samples

Folder name Description



Figure 16 Header information

#include <stdio.h>#include <string.h>#include <time.h>#include "iiapi.h"

int main (int argc, char argv[]){intiResult;// used to catch function results// used for the messageBMCII_MESSAGEpEvent; // the container for the messagecharszClassName[MAX_CLASS_NAME];// the class name of the eventcharszSlotName[64];// the name of the slotcharszSlotValue[256];// slot can be 64k but for this we will start out small// used for the connectionBMCII_CNCcnc = 0; // the connection handlecharszIM[100]; // the name of the impact manager to connect// used for the sendchar*szUID; // the Unique ID of the Message. Used for sending modificationsunsigned longulMsgHandle; //the number identifying sent message. Use it to match a reply// used for the recvintiCount; // for receiving 2 repliesvoid*pReply; //the reply from the Impact Mangerbmcii_ReplySuccess*pAnswer; // used for casting is it is a good answerbmcii_ReplyError*pError; // used for casting if there was an errorbmcii_ReplyCancel*pCancel; // used if the operation was canceledbmcii_ConnectNotify*pConnectionNotify; // used for connection statuscharszInitMsg[500];// space for a pre messagecharszStatus[20]; // used to display the status of a connectionintiType; // the type of replyBMCII_CNCReturnedCnc; // the cnc that the reply ,Message, or Notify came from

Figure 17 Initializing the BMC II C APIs

iResult = bmcii_init3(".",// use the current directory with "simpleclient",// the name of the integrationNULL,// no instance name since only one example will run at a time"ISC",// an abreviation for the integration used for trace"simpleclient.conf",// the name of the configuration file (found in the homedir)"TraceFileHistory=0",// Override the config setting. \n is the delimiter"Trace=yes\nTraceFileSize=0",// sets a default values for config. \n is the delimiterBMCII_FALSE,// run in the foregroundINIT_FLAG_NONE);// flags: do not change the directory

if(iResult){printf("Error %d init\n", iResult);return iResult;}

bmcii_Ltrace_register("SIMPLE_SEND", 1, TR_ID); // register for trace messages



Figure 18 Creating a message

iResult = bmcii_createMessage(&pEvent);if(iResult){// BMC-ISC001001E=Error {0} creating eventbmcii_Ltrace(TR_FATAL, 1, TR_ARG_INT, iResult, TR_ARG_END);return iResult;}else{// BMC-ISC001002V=Message creation successfulbmcii_Ltrace(TR_VERBOSE, 2, TR_ARG_END);}

// get the message informationprintf("Please enter the class name <EVENT> :");gets(szClassName);if(strlen(szClassName) == 0){strcpy(szClassName, "EVENT");}

// set the class name and hard code it to be a new eventiResult = bmcii_setMessageType(pEvent, szClassName, MSG_TYPE_NEW_EVENT);if(iResult){// BMC-ISC001003E=Error {0} setting the class {1}bmcii_Ltrace(TR_FATAL, 3 , TR_ARG_INT, iResult , TR_ARG_STR, szClassName, TR_ARG_END);return iResult;}

// ask for the slot names and valueswhile(1){printf("\nPlease enter a slot name or \'F\' when finished:");gets(szSlotName);if((strcmp(szSlotName, "F") == 0) || (strcmp(szSlotName, "f") == 0))break;printf("\nPlease enter a slot value:");gets(szSlotValue);

iResult = bmcii_setSlotValue(pEvent, szSlotName, szSlotValue);if(iResult){// BMC-ISC001004E=Error {0} setting the slot {1} with value {2}bmcii_Ltrace(TR_FATAL, 4, TR_ARG_INT, iResult, TR_ARG_STR, szSlotName, TR_ARG_STR, szSlotValue, TR_ARG_END);return iResult;}}//end while messages to send

// BMC-ISC001005V=The contents of the message are:bmcii_Ltrace(TR_VERBOSE, 5, TR_ARG_END);bmcii_dumpMessage(pEvent); // show the contents of the message



Figure 19 Establishing a connection

// ask for the Impact Manager to connect toprintf("\nPlease enter the name of an Impact Manager\nor the connection string in the form of @host:port#key :");gets(szIM);

iResult = bmcii_connect(SEC_TOKEN_NONE, szIM, BMCII_BUFFER_MODE_LOW, &cnc);if(iResult){// BMC-ISC001006E=Error {0} connecting to IM {1}bmcii_Ltrace(TR_FATAL, 6, TR_ARG_INT, iResult, TR_ARG_STR, szIM, TR_ARG_END);return iResult;}elseprintf("Connection successful\n");

Figure 20 Sending a message

if(iResult){// BMC-ISC001007E=Failed to send event: {0}bmcii_Ltrace(TR_FATAL, 7, TR_ARG_INT, iResult, TR_ARG_END);return iResult;}printf("Sent with uid=%s and Msghandle=%lu\n", szUID, ulMsgHandle);

// free the szUID since we do not need it for modifiesbmcii_freeString(&szUID);



Figure 21 Receiving a reply (part 1 of 3)

// get two items. The first is the connection status, the second is the // answerfor(iCount = 0; iCount < 2; iCount++){

iResult = bmcii_getFromQueue(cnc, &pReply, &iType, 5000, &ReturnedCnc); if(iResult){if(iResult == BMCII_NOT_FOUND){// BMC-ISC001008V=Nothing receivedbmcii_Ltrace(TR_VERBOSE, 8, TR_ARG_END);printf("Nothing received\n");}else{// BMC-ISC001009E=Error receiving {0}bmcii_Ltrace(TR_FATAL, 9, TR_ARG_INT, iResult, TR_ARG_END);return iResult;}}//end if iResultelse{switch(iType){case BMCII_REPLY_LAST:case BMCII_REPLY_PARTIAL:pAnswer = (bmcii_ReplySuccess*)pReply;

// make a messagesprintf(szInitMsg, "Received answer for connection %lu. MessageID %lu", pAnswer->cnc, pAnswer->ulMsgid);switch(pAnswer->ans_val_type){case BMCII_VAL_TYPE_BOOL:if(pAnswer->ans_val_data.bmcii_bool)printf("%s Result Type Bool = True\n", szInitMsg);elseprintf("%s Result Type Bool = False\n", szInitMsg);break;case BMCII_VAL_TYPE_ULONG:printf("%s Result Type ULONG = %lu\n", szInitMsg, pAnswer->ans_val_data.bmcii_ulong);break;case BMCII_VAL_TYPE_INT:printf("%s Result Type INT = %d\n", szInitMsg, pAnswer->ans_val_data.bmcii_int);break;case BMCII_VAL_TYPE_STR:printf("%s Result Type string = %s\n", szInitMsg, pAnswer->ans_val_data.bmcii_str);break;}//end switch data typebreak;



case BMCII_REPLY_ERROR:pError = (bmcii_ReplyError*)pReply;

if(pError->szErrorText)printf("Received Error for connection %lu. MessageID %lu. Error %s\n", pError->cnc, pError->ulMsgid, pError->szErrorText);break;case BMCII_REPLY_CANCEL:pCancel = (bmcii_ReplyCancel*)pReply;

printf("Received Cancel on connection %lu. MessageID %lu.\n", pCancel->cnc, pCancel->ulMsgid);break;case BMCII_CONNECT_STATUS_NOTIFY:pConnectionNotify = (bmcii_ConnectNotify*)pReply;




switch(pConnectionNotify->Status){case BMCII_CNC_STATUS_DOWN:strcpy(szStatus, "Down");break;case BMCII_CNC_STATUS_OPEN:strcpy(szStatus, "Open");break;case BMCII_CNC_STATUS_FAIL:strcpy(szStatus, "Failed");break;default:strcpy(szStatus, "Unknown");break;}//end switch

if(pConnectionNotify->szRemoteLoc){printf("client connection %s cnc %lu ID %lu IM %s Host %s:%hu",szStatus, pConnectionNotify->cnc, pConnectionNotify->ulMsgid,pConnectionNotify->szRemoteName, pConnectionNotify->szRemoteLoc,pConnectionNotify->usRemotePort);}else{printf("client connection established cnc %lu ID %lu IM %s ",szStatus,pConnectionNotify->cnc, pConnectionNotify->ulMsgid,pConnectionNotify->szRemoteName);}break;default:break;}//end switch

// release the replybmcii_freeRecv(&pReply);

}//end else we have a reply}//end for 2 times

// free the messagebmcii_freeMessage(&pEvent);

Figure 22 Disconnecting

iResult = bmcii_disconnect(&cnc, 1);if(iResult){// BMC-ISC001010E=Error {0} disconnecting from digdugbmcii_Ltrace(TR_VERBOSE, 10, TR_ARG_INT, iResult, TR_ARG_END);return iResult;}elseprintf("Disconnected\n");



Simple query project code


The simple query project builds an integration that performs the following functions:

■ Initializing the BMC II C APIs (Figure 25 on page 111)■ Initializing the queries (Figure 26 on page 112)■ Calling the query: by date (Figure 27 on page 112)■ Calling the query: by event handle (Figure 28 on page 113)■ Calling the query: by mc_ueid ID (Figure 29 on page 113)■ Calling the query: by event collector name (Figure 30 on page 114)■ Getting query results (Figure 31 on page 115)■ Outputting query results (Figure 32 on page 115)■ Freeing query results (Figure 33 on page 116)■ Closing the query (Figure 34 on page 116)■ Closing all queries (Figure 35 on page 116)■ Terminating the BMC II C APIs (Figure 36 on page 116)

Figure 23 Terminating the BMC II C APIs

bmcii_term();

return 0;}//end main for simple send





int main (int argc, char argv[]){intiResult;// used to catch function results// used for the query initcharszIM[100]; // the name of the impact manager to connectBMCII_QUERYHANDLEQueryHandle; // the handle for all queries to a specified Impact ManagerBMCII_RESULT_HANDLEResultHandle; // used to retrieve query results// used in the querycharszClassList[100] = ""; // a comma seperated list of classes for the querytime_tstartTime = 0; // the start time for the query by date exampletime_tendTime = 0; // the end time for the query by date exampleintiStartHandle = 0; // the start event handle used for query by handleintiEndHandle = 0;// the end event handle used for query by handlecharszCollectorName[100] = "";// the name of a collector for the query by collector// used to get resultsBMCII_MESSAGE_LISTMessages;intiResultCount;intiReturnedResults;// used for outputintiCount;char*pEvent;


iResult = bmcii_init3(".",// use the current directory with "simplequery",// the name of the integrationNULL,// no instance name since only one example will run at a time"ISQ",// an abreviation for the integration used for trace"simplequery.conf",// the name of the configuration file (found in the homedir)NULL,// Not overriding anythingNULL,// Not setting any defaultsBMCII_FALSE,// run in the foregroundINIT_FLAG_NONE);// flags: do not change the directoryif(iResult){printf("Error %d init\n", iResult);return iResult;}

bmcii_Ltrace_register("SIMPLE_QUERY", 1, TR_ID); // register for trace messages



Figure 26 Initializing the queries

// ask for the Impact Manager to connect toprintf("\nPlease enter the name of an Impact Manager\nor the connection string in the form of @host:port#key [default]:");gets(szIM);if(strlen(szIM) == 0)strcpy(szIM, "default");

// initialize querying with an Impact ManageriResult = bmcii_initQueryConnect(SEC_TOKEN_NONE, szIM, &QueryHandle);if(iResult){bmcii_trace(TR_FATAL, "Error %d initializing the query", iResult);bmcii_term();return iResult;}

Figure 27 Calling the query: by date

// Query by date

// get the current timetime(&endTime);startTime = 0;//endTime - 60000; // last 10 hoursstrcpy(szClassList, "EVENT");

iResult = bmcii_queryEventsByDate(QueryHandle, // the query handle returned from bmcii_initQueryConnectstartTime, // the start time for the selectionendTime, // the end time for the selectionszClassList, // the comma separated list of classesSORT_ASC, // Ascending order&ResultHandle); // the result handle to be filled inif(iResult){bmcii_trace(TR_FATAL, "Error %d initializing the query", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}



Figure 28 Calling the query: by event handle

// Query by event handle

strcpy(szClassList, "MC_CELL_CONTROL");iStartHandle = 0;iEndHandle = 30;

iResult = bmcii_queryEventsByHandles(QueryHandle, // the query handle returned from bmcii_queryEventsByHandleiStartHandle, // the start handle for the selectioniEndHandle, // the end handle for the selectionszClassList, // the comma separated list of classesSORT_DESC, // Ascending order&ResultHandle); // the result handle to be filled inif(iResult){bmcii_trace(TR_FATAL, "Error %d initializing the query", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

Figure 29 Calling the query: by mc_ueid ID

// Query an event by the mc_ueid

/*strcpy(szClassList, "EVENT");

iResult = bmcii_queryEventByMcueid(QueryHandle, // the query handle returned from bmcii_queryEventsByHandle"test.test_digdug.000039", // the start handle for the selectionszClassList, // the comma separated list of classes&ResultHandle); // the result handle to be filled inif(iResult){bmcii_trace(TR_FATAL, "Error %d initializing the query", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}*/



Figure 30 Calling the query: by event collector name

// Query by event collector name/*

strcpy(szClassList, "EVENT");strcpy(szCollectorName, "self");

iResult = bmcii_queryEventsByCollector(QueryHandle, // the query handle returned from bmcii_queryEventsByHandleszCollectorName, // the name of the collectorszClassList, // the comma separated list of classesSORT_NONE, // Ascending order&ResultHandle); // the result handle to be filled inif(iResult){bmcii_trace(TR_FATAL, "Error %d initializing the query", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

*/



Figure 31 Getting query results

// see if the query was successfuldo{iResult = bmcii_getQueryReply(ResultHandle, // the result handle from the query1000, // timeout in milliseconds &iResultCount); // the number of results that are returned}while(iResult == BMCII_NO_RESULT_YET);if(iResult){bmcii_trace(TR_FATAL, "Error %d with query see trace file", iResult);bmcii_closeQuery(&ResultHandle);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

if(iResultCount > 0){

// retrieve the results from the Impact ManageriResult = bmcii_retrieveQueryResults(ResultHandle, // the result handle from the query1000, // timeout in milliseconds 1, // the first result message to getiResultCount % 5, // the last result message to get&Messages, // the list of result Messages&iReturnedResults); // the number of results that are returnedif(iResult){bmcii_trace(TR_FATAL, "Error %d retrieving results from Impact Manager", iResult);bmcii_closeQuery(&ResultHandle);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

Figure 32 Outputting query results

for(iCount = 0; iCount < iReturnedResults; iCount++){bmcii_messageGetBaroc(Messages[iCount], &pEvent);bmcii_trace(TR_VERBOSE, "Query Result %d : %s", iCount + 1, pEvent);bmcii_freeString(&pEvent);} //end for all the events returned



Figure 33 Freeing query results

iResult = bmcii_freeQueryResults(&Messages);if(iResult){bmcii_trace(TR_FATAL, "Error %d freeing results", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

}//end if there was results

Figure 34 Closing the query

iResult = bmcii_closeQuery(&ResultHandle);if(iResult){bmcii_trace(TR_FATAL, "Error %d closing query", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

Figure 35 Closing all queries

iResult = bmcii_termQueryConnect(&QueryHandle);if(iResult){bmcii_trace(TR_FATAL, "Error %d termination the query", iResult);bmcii_term();return iResult;}


bmcii_term();



Simple server project code


The simple server project builds an integration that performs the following functions:

■ Initializing the BMC II C APIs (Figure 38 on page 118)■ Setting up the server (Figure 39 on page 118)■ Starting the receiving process (Figure 40 on page 118)■ Receiving connections and events (Figure 41 on page 119)■ Stopping the server (Figure 42 on page 120)■ Terminating the BMC II C APIs (Figure 43 on page 121)



int main (int argc, char argv[]){intiResult;// used to catch function results// used for the servercharszServerName[MAX_CLASS_NAME];// the name of the server to lookup in mcell.dir// used for the connectionBMCII_CNCcnc = 0; // the connection handle// used for the recvintiType; // the type of replyBMCII_CNCRecvcnc; // the cnc that the Message, or Notify came fromintiCount; // used to loop through receivesvoid*pResult; // a void pointer to receive the resultbmcii_ConnectNotify*pConnectionNotify; // a notification of change in connectionBMCII_MESSAGEpMessage; // the char*pEventMsg;




iResult = bmcii_init3(".",// use the current directory with "simpleserver",// the name of the integrationNULL,// no instance name since only one example will run at a time"ISS",// an abreviation for the integration used for trace"simpleserver.conf",// the name of the configuration file (found in the homedir)NULL,// Not overriding anything"TraceFileHistory=0",// Override the config setting.\n is the delimiter"Trace=yes",// sets a default values for config. \n is the delimiterBMCII_TRUE,// run in the background and send the trace info to a fileBMCII_FALSE, // run in the foregroundINIT_FLAG_NONE);// flags: do not change the directoryif(iResult){printf("Error %d init\n", iResult);return iResult;}

bmcii_Ltrace_register("SIMPLE_SERVER", 1, TR_ID); // register for trace messages

Figure 39 Setting up the server

printf("Please enter the server name [Default: simpleserver] :");gets(szServerName);if(strlen(szServerName) == 0){strcpy(szServerName, "simpleserver");}

// bind to the port specified in the mcell.diriResult = bmcii_setupServer(szServerName);if(iResult){bmcii_trace(TR_VERBOSE, "Error %d setting up server", iResult);return iResult;}

printf("\nServer %s is Running\n", szServerName);bmcii_trace(TR_VERBOSE, "Server %s is Running", szServerName);

Figure 40 Starting the receiving process

// start the serveriResult = bmcii_startServer();if(iResult){bmcii_trace(TR_VERBOSE, "Error %d setting up server", iResult);return iResult;}



Figure 41 Receiving connections and events (part 1 of 2)

for(iCount = 0; iCount < 145; iCount++){iResult = bmcii_getFromQueue(0, // receive from any connection&pResult, // A pointer to a result&iType, // the type of result returned10000, // the timeout in milliseconds&Recvcnc); // the connection that item came fromif(iResult){if(iResult == BMCII_NOT_FOUND){printf(".\n");bmcii_trace(TR_VERBOSE, "Nothing received");}elsebmcii_trace(TR_VERBOSE, "Error receiving %d", iResult);}else{// we have somethingswitch(iType){case BMCII_RECVD_MESSAGE:pMessage = (BMCII_MESSAGE) pResult;iResult = bmcii_messageGetBaroc(pMessage, &pEventMsg);if(iResult){bmcii_trace(TR_VERBOSE, "Error %d getting baroc event", iResult);return iResult;}bmcii_trace(TR_VERBOSE, "Received message on connection Text : %s ", pEventMsg);printf("Received message on connection Text : \n%s \n", pEventMsg);bmcii_freeString(&pEventMsg);break;

case BMCII_RECVD_MODIFY:pMessage = (BMCII_MESSAGE) pResult;iResult = bmcii_messageGetBaroc(pMessage, &pEventMsg);if(iResult){bmcii_trace(TR_VERBOSE, "Error %d getting baroc event", iResult);return iResult;}bmcii_trace(TR_VERBOSE, "Received message on connection Text : %s ", pEventMsg);printf("Received message on connection Text : \n%s \n", pEventMsg);bmcii_freeString(&pEventMsg);break;



case BMCII_CONNECT_NOTIFY:pConnectionNotify = (bmcii_ConnectNotify*)pResult;

if(pConnectionNotify->Status == BMCII_CNC_STATUS_SYNCH)break; // we don't care until it is up

if(pConnectionNotify->szRemoteLoc){bmcii_trace(TR_VERBOSE, "Received new connection notification. Connection %lu. MessageID %lu. Cell %s Host %s Port %hu",pConnectionNotify->cnc, pConnectionNotify->ulMsgid, pConnectionNotify->szRemoteName, pConnectionNotify->szRemoteLoc, pConnectionNotify->usRemotePort);printf("Received new connection notification. Connection %lu. MessageID %lu. Cell %s Host %s Port %hu\n",pConnectionNotify->cnc, pConnectionNotify->ulMsgid, pConnectionNotify->szRemoteName, pConnectionNotify->szRemoteLoc, pConnectionNotify->usRemotePort);}break;case BMCII_DISCONNECT_NOTIFY:pConnectionNotify = (bmcii_ConnectNotify*)pResult;if(pConnectionNotify->szRemoteLoc){bmcii_trace(TR_VERBOSE, "Received disconnect notification. Connection %lu. MessageID %lu. Cell %s Host %s Port %hu",pConnectionNotify->cnc, pConnectionNotify->ulMsgid, pConnectionNotify->szRemoteName, pConnectionNotify->szRemoteLoc, pConnectionNotify->usRemotePort);printf("Received disconnect notification. Connection %lu. MessageID %lu. Cell %s Host %s Port %hu\n", pConnectionNotify->cnc, pConnectionNotify->ulMsgid, pConnectionNotify->szRemoteName, pConnectionNotify->szRemoteLoc, pConnectionNotify->usRemotePort);}break;

default:bmcii_trace(TR_VERBOSE, "Unknown Message Received??? : %d", iType);break;}//end switch

bmcii_freeRecv(&pResult); // free all received items}//end good recv}//end for x number of times

Figure 42 Stopping the server

// stop the serveriResult = bmcii_stopServer();if(iResult){bmcii_trace(TR_VERBOSE, "Error %d setting up server\n", iResult);return iResult;}

Figure 41 Receiving connections and events (part 2 of 2)


Sample component queries


The component queries demo project shows how to execute queries against service components that have been published in a BMC IM cell. It includes the following functions:

■ Main declaration (Figure 45 on page 123)■ Getting input parameters (Figure 46 on page 124)■ Initializing the BMC II C APIs (Figure 47 on page 125)■ Initializing the queries (Figure 48 on page 125)■ Calling the query functions (Figure 49 on page 126)■ Getting query results (Figure 50 on page 130)■ Outputting the query results (Figure 51 on page 130)■ Freeing the query results (Figure 52 on page 131)■ Closing the query (Figure 53 on page 131)■ Closing all queries (Figure 54 on page 131)■ Terminating the BMC II C APIs (Figure 55 on page 131)


bmcii_term();





#include <string.h>#include <stdio.h>#include <stdlib.h>#include <sys/types.h>#include <time.h>#include "iiapi.h"

*/void usage(void){ // now print out our specific arguments printf("Usage: \n");printf("compQuery [-cell cellName -mcellHome home -mode queryMode [options] -h ] \n" );printf(" queryMode 1: queryComponentsByStatus. \n");printf(" options: [-low lStatus -high hStatus -class baseClass -subC 1/0 -slots [slotList] ]\n");printf(" queryMode 2: queryComponentsByCondition. \n");printf(" options: [-condition conditions -slots [slotList] ]\n");printf(" queryMode 3: queryComponent. \n");printf(" options: [-cid compId ]\n");printf(" queryMode 4: queryComponentStatus. \n");printf(" options: [-cid compId ]\n");printf(" queryMode 5: queryModelImpact. \n");printf(" options: [-cid compId -slots [slotList] ]\n");printf(" queryMode 6: queryModelCause. \n");printf(" options: [-cid compId -slots [slotList] ]\n");printf(" queryMode 7: queryRootCauses. \n");printf(" options: [-cid compId -trueCause 1/0 -slots [slotList] ]\n");printf("\n");printf(" Example: compQuery -mode 1 -class BMC_BaseElement -subC 1 -slots OwnerName,self_status \n");}/*



Figure 45 Main declaration

*/int main (int argc, char *argv[]){intiResult; // used to catch function results// variables used for initintiMajor, iMinor, iBuildNum;charszBuildDate[100];charszLibInfo[100];

charszCellName[64]; // the name of the impact manager to connectcharszHome[512];// home diretorychar defaultCell[] = "nt13a";

BMCII_QUERYHANDLEQueryHandle; // the handle for all queries to a specified Impact Manager BMCII_RESULT_HANDLEResultHandle; // used to retrieve query results

// variables used in queryint iQueryMode = 2; char szLowestStatus[64];char szHighestStatus[64];char szBaseClass[512];char szConditions[2048];char szSlots[512];char szCompId[512];bool bSubclasses = true;bool bPossible = true;int iFlag;

// initialize the variables used in queryszCellName[0]='\0';szLowestStatus[0]='\0';szHighestStatus[0]='\0';szBaseClass[0]='\0';szSlots[0]='\0';szCompId[0] = '\0';// default szHomestrcpy(szHome, ".");// default conditionsprintf(szConditions,"%s" , "status: >= MINOR AND (CLASS: == BMC_Application OR CLASS: == BMC_ApplicationSystem)");



Figure 46 Getting input parameters

for (int i = 1; i < argc; i++) {if (strcmp(argv[i], "-h") == 0) {usage();exit(0);} else if ( ( strcmp(argv[i], "-cell") == 0) && (i + 1 < argc) )strcpy(szCellName , argv[++i]);else if ( ( strcmp(argv[i], "-mcellHome") == 0) && (i + 1< argc) )strcpy(szHome,argv[++i]);else if ( (strcmp(argv[i], "-mode") == 0) && (i + 1< argc) )iQueryMode = atoi(argv[++i]);else if ( (strcmp(argv[i], "-low") == 0) )strcpy(szLowestStatus,argv[++i]);else if ( (strcmp(argv[i], "-high") == 0) )strcpy(szHighestStatus,argv[++i]);else if ( (strcmp(argv[i], "-class") == 0) )strcpy(szBaseClass,argv[++i]);else if ( (strcmp(argv[i], "-slots") == 0) )strcpy(szSlots,argv[++i]);else if ((strcmp(argv[i], "-cid") == 0) )strcpy(szCompId, argv[++i]);else if ( (strcmp(argv[i], "-subC") == 0) ){iFlag = atoi(argv[++i]);bSubclasses = iFlag==1? true:false;}else if ( (strcmp(argv[i], "-trueCause") == 0) ){iFlag = atoi(argv[++i]);bPossible = iFlag==1? true:false;}else{usage();exit(0);

}}

if ( szCellName[0] == '\0')strcpy(szCellName, defaultCell);

printf("TestQuery started. McellHome: %s MCell: %s\n\n", szHome,szCellName);




iResult = bmcii_init3(szHome,// nome directory, "componentsQuery",// the name of the integration"compQuery",// Instance Name "compQuery.conf", // the name of the configuration file (found in the homedir) NULL,// Not overridding anything BMCII_FALSE,// run in the foreground INIT_FLAG_NONE);// flags: do not change the directory

if(iResult){printf("Error %d in bmcii_init\n", iResult);return iResult;}

bmcii_trace_register("COMP_QUERY",TR_ID);// register for trace messages

// get the lib version (not nessicary but helpful)iResult = bmcii_version(&iMajor, &iMinor, &iBuildNum, szBuildDate, szLibInfo);

if(iResult){printf("Error %d getting version information\n", iResult);return iResult;}else{ bmcii_trace(TR_VERBOSE,"Using version %d.%d build number %d built on %s with lib verion %s\n", iMajor, iMinor, iBuildNum, szBuildDate, szLibInfo);}


bmcii_trace(TR_VERBOSE, "InitQueryConnect to cell %s\n", szCellName);

iResult = bmcii_initQueryConnect(SEC_TOKEN_NONE, //stub, IgnoredszCellName, // name of the Impact Manager to connect&QueryHandle); // OUT, handle to the connection

if(iResult){bmcii_trace(TR_FATAL, "Error %d initilizing the query\n", iResult);bmcii_term();return iResult;}



Figure 49 Calling the query functions

switch (iQueryMode){case 1:////////////////////////////////////////////////////////bmcii_queryComponentsByStatus/////////////////////////////////////////////////////

printf("call bmcii_queryComponentsByStatus()\n");iResult = bmcii_queryComponentsByStatus(QueryHandle,// the query handle reurned from bmcii_initQueryConnectszLowestStatus, // lowest bound of statusszHighestStatus, //highest bound of statusszBaseClass,// base class the query select frombSubclasses,// do you want query through sub-classszSlots,// additional slots to be returned&ResultHandle); // OUT, the handle to the result setif(iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_queryComponentsByStatus\n", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

break;case 2:////////////////////////////////////////////////////////bmcii_queryComponentsByCondition/////////////////////////////////////////////////////

printf("call bmcii_queryComponentsByCondition()\n");iResult = bmcii_queryComponentsByCondition(QueryHandle,// the query handle reurned from bmcii_initQueryConnectszConditions,// specify the selection criteria in where clauseszSlots,// additional slots to be returned&ResultHandle); // OUT, the handle to the result setif(iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_queryComponentsByCondition\n", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

break;



case 3:////////////////////////////////////////////////////////bmcii_queryComponent/////////////////////////////////////////////////////

printf("call bmcii_queryComponent()\n");iResult = bmcii_queryComponent(QueryHandle,// the query handle reurned from bmcii_initQueryConnectszCompId,// the id which uniquely identifies the component object to be queried.&ResultHandle); // OUT, the handle to the result setif(iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_queryComponent\n", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

break;case 4:////////////////////////////////////////////////////////bmcii_queryComponentStatus/////////////////////////////////////////////////////

printf("call bmcii_queryComponentStatus()\n");iResult = bmcii_queryComponentStatus(QueryHandle,// the query handle reurned from bmcii_initQueryConnectszCompId,// the id which uniquely identifies the component object to be queried.&ResultHandle); // OUT, the handle to the result setif(iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_queryComponentStatus\n", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

break;




case 5:////////////////////////////////////////////////////////bmcii_queryModelImpact/////////////////////////////////////////////////////

printf("call bmcii_queryModelImpact()\n");iResult = bmcii_queryModelImpact(QueryHandle,// the query handle reurned from bmcii_initQueryConnectszCompId,// the id which uniquely identifies the component object to be queried.szSlots,// additional slots to be returned&ResultHandle); // OUT, the handle to the result setif(iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_queryModelImpact\n", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

break;




case 6:////////////////////////////////////////////////////////bmcii_queryModelImpact/////////////////////////////////////////////////////

printf("call bmcii_queryModelCause()\n");iResult = bmcii_queryModelCause(QueryHandle,// the query handle reurned from bmcii_initQueryConnectszCompId,// the id which uniquely identifies the component object to be queried.szSlots,// additional slots to be returned&ResultHandle); // OUT, the handle to the result setif(iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_queryModelCause\n", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

break;case 7:////////////////////////////////////////////////////////bmcii_queryModelPossibleRootCauses/////////////////////////////////////////////////////

printf("call bmcii_queryModelPossibleRootCauses()\n");iResult = bmcii_queryModelPossibleRootCauses(QueryHandle,// the query handle reurned from bmcii_initQueryConnectszCompId,// the id which uniquely identifies the component object to be queried.szSlots,// additional slots to be returnedbPossible,// bool for true or possible impact&ResultHandle); // OUT, the handle to the result setif(iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_queryModelPossibleRootCauses\n", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

break;default:printf("Not a valid query model\n");break;}




Figure 50 Getting query results

unsigned longiResultCount=0;intiReturnedResults=0;BMCII_MESSAGE_LISTMessages;intiCount;char*pEvent;

// see if the query was successfuldo{iResult = bmcii_getQueryReply(ResultHandle, // the result handle from the query1000, // timeout in milliseconds &iResultCount); // the number of results that are returned}while(iResult == BMCII_NO_RESULT_YET);

if(iResult){bmcii_trace(TR_FATAL, "Error %d with query see trace file", iResult);bmcii_closeQuery(&ResultHandle);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

if(iResultCount > 0){// retieve the results from the Impact ManageriResult = bmcii_retrieveQueryResults(ResultHandle, // the result handle from the query1000, // timeout in milliseconds 1, // the first result message to getiResultCount , // the last result message to get&Messages, // the list of result Messages&iReturnedResults); // the number of results that are returnedif(iResult){bmcii_trace(TR_FATAL, "Error %d retrieving results from Impact Manager", iResult);bmcii_closeQuery(&ResultHandle);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}

Figure 51 Outputting the query results

for(iCount = 0; iCount < iReturnedResults; iCount++){bmcii_messageGetBaroc(Messages[iCount], &pEvent);bmcii_trace(TR_VERBOSE, "Query Result %d : %s", iCount + 1, pEvent);printf("%s",pEvent);bmcii_freeString(&pEvent);}



Figure 52 Freeing the query results

if (iCount >0)iResult = bmcii_freeQueryResults(&Messages);if(iResult){bmcii_trace(TR_FATAL, "Error %d freeing results", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}}//end if there was results


iResult = bmcii_closeQuery(&ResultHandle);if(iResult){bmcii_trace(TR_FATAL, "Error %d closeing query", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}


iResult = bmcii_termQueryConnect(&QueryHandle);if(iResult){bmcii_trace(TR_FATAL, "Error %d terminatin the query\n", iResult);bmcii_term();return iResult;}


bmcii_term();printf("\n\ntestServer succeed!\n");

return 0;}// end of main


Sample class definition queries


The class definition queries demo project shows how to execute queries against classes and their slots as defined in a BMC IM cell. It includes the following functions:

■ Main declaration (Figure 57 on page 136)■ Getting initial input parameters (Figure 58 on page 137)■ Initializing the BMC II C APIs (Figure 59 on page 138)■ Initializing the queries (Figure 60 on page 138)■ Querying classes and slots (Figure 61 on page 138)■ Closing the query (Figure 62 on page 141)■ Closing all queries (Figure 63 on page 141)■ Terminating the BMC II C APIs (Figure 64 on page 141)



Figure 56 Header information (part 1 of 3)

#include <string.h>#include <stdio.h>#include <stdlib.h>#include <sys/types.h>#include <time.h>#include "iiapi.h"

/*============================================= Function to retrieve slot definistion=============================================*/int getSlotInfo(SLOT_DEFS_HANDLE pSlots, int index, int indent){bmcii_resultiResult;BMCII_STR*szSlotName;BMCII_STR*szSlotType;BMCII_STR*szSlotRep;BMCII_STR*szSlotFlags;BMCII_STR*szDefaultValues;int i;///retrieve the slot info//

iResult = bmcii_getSlotDefInfo(pSlots, //slot result list handle returned from bmcii_getClassNode or bmcii_getClassDefByNameindex,// index in slot list on which the details requested&szSlotName,// OUT,name of the slot&szSlotType,// OUT,type of the slot: &szSlotRep,// OUT,slot representation type,&szSlotFlags,// OUT,Flags contain Boolean facets of the slot.&szDefaultValues// OUT,default value;if (iResult){printf("Error %d with with query getSlotInfo see trace file. Error Message:%s", iResult, bmcii_errorText(iResult));bmcii_trace(TR_FATAL, "Error %d with query getSlotInfo see trace file Error Message:%s \n", iResult, bmcii_errorText(iResult));return iResult;

}// // print leading indents and slot infofor (i = 0; i < (indent); i++) printf( " ");printf( " SlotName: %s Type: %s Rep: %s Flags: %s DefValue: %s\n",szSlotName, szSlotType, szSlotRep, szSlotFlags,szDefaultValues);

return BMCII_SUCCESS;}

/*



Recursively retrieve class def infor and print out the result=============================================*/int walkClassDefTree(CLASS_DEF_HANDLE pClassList, int index, int indent){bmcii_resultiResult;BMCII_STR*szClassName;intiChildCount;CLASS_DEF_HANDLEpChildClasses;intiSlotCount;SLOT_DEFS_HANDLEpSlotHandle;inti;///// retrieve class node info ///

iResult = bmcii_getClassNode(pClassList,//class def handle returned from bmcii_getClassDefQueryReply()index,// index in class def list on which the information requested&szClassName,// OUT, name of the requested class&iChildCount,// OUT, number of child classes&pChildClasses, // OUT, a handle points to the child class list&iSlotCount,// OUT, number of slots for the requested class&pSlotHandle// OUT, a handle point to the slots list);if (iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_getClassNode see trace file Error Message:%s \n", iResult, bmcii_errorText(iResult));return iResult;}

// print leading class indents and class node infofor (i = 0; i < indent; i++) printf( " ");printf("ClassName: %sNum Slots: %d Num Children %d\n", szClassName, iSlotCount, iChildCount);

// retrieve slot definitionsfor (i = 0; i < iSlotCount; i++){iResult = getSlotInfo(pSlotHandle, i, indent);if (iResult){bmcii_trace(TR_FATAL, "Error %d with query walkClassDefTree see trace file Error Message:%s \n", iResult, bmcii_errorText(iResult));return iResult;}}




/// finish using of slots info. Release the slotHandle resource///

iResult = bmcii_freeQuerySlotsHandle(&pSlotHandle);if (iResult){bmcii_trace(TR_FATAL, "Error %d with query walkClassDefTree see trace file Error Message:%s \n", iResult, bmcii_errorText(iResult));return iResult;}

indent++;

// recursively retrieve children classfor (i = 0; i < iChildCount; i++){iResult = walkClassDefTree(pChildClasses, i, indent);if (iResult){bmcii_trace(TR_FATAL, "Error %d with query walkClassDefTree see trace file", iResult);return iResult;}}return BMCII_SUCCESS;}//end of walkClassDefTree

/**/void usage(void){ printf( "Usage: testQueryClasses [-cell cellName -mcellHome home -mode queryMode (0:eventClass 1:dataClass ) -baseClass baseClass -className className -h ] \n" );printf( "baseClass: specify the base class of the class hierarchy \n");printf( "className: get complete info for this class (bmcii_getClassDefByName)\n");

}/*




Figure 57 Main declaration

*/int main (int argc, char *argv[]){intiResult;// variables used for initintiMajor, iMinor, iBuildNum;charszBuildDate[100];charszLibInfo[100];

charszCellName[64];// the name of the impact manager to connectcharszHome[512];// home diretory

// variables used in querybmcii_ClassDefQueryModequeryMode;//query mode. 0:EVENT_CLASSES,1:DATA_CLASSESchar szBaseClass[128];//specify the base class of the class hierarchycharszClassName[128];//class Name used to test bmcii_getClassDefByNameBMCII_QUERYHANDLEQueryHandle;//the handle for all quesrys to a specified Impact Manager // initialize the variables used in querychar defaultCell[] = "nt13a";queryMode = BMCII_DATA_CLASSES;szCellName[0]='\0';szClassName[0] = '\0';szBaseClass[0] = '\0';strcpy(szHome, ".");



Figure 58 Getting initial input parameters

for (int i = 1; i < argc; i++) {if (strcmp(argv[i], "-h") == 0) {usage();exit(0);} else if ( ( strcmp(argv[i], "-cell") == 0) && (i + 1 < argc) )strcpy(szCellName , argv[++i]);else if ( ( strcmp(argv[i], "-mcellHome") == 0) && (i + 1< argc) )strcpy(szHome,argv[++i]);else if ( (strcmp(argv[i], "-mode") == 0) && (i + 1< argc) )queryMode = (bmcii_ClassDefQueryMode)atoi(argv[++i]);else if ( (strcmp(argv[i], "-baseClass") == 0) && (i + 1< argc) )strcpy(szBaseClass, argv[++i]);else if ( (strcmp(argv[i], "-className") == 0) && (i + 1< argc) )strcpy(szClassName, argv[++i]);}

if (queryMode < BMCII_EVENT_CLASSES || queryMode > BMCII_DATA_CLASSES){printf("Invalid queryMode. please input 0:EVENT_CLASSES,1:DATA_CLASSES, \n");exit(0);}if ( szCellName[0] == '\0')strcpy(szCellName, defaultCell);

printf("ClassDefQuery started. McellHome: %s MCell: %s baseClass: %s className %s\n\n", szHome,szCellName, szBaseClass, szClassName);




iResult = bmcii_init3(szHome,// nome directory, "classDefQuery",// the name of the integration"classDefQuery",// Instance Name"classDefQuery.conf", // the name of the configuration file (found in the homedir) NULL,// Not overridding anything BMCII_FALSE,// run in the foregroundINIT_FLAG_NONE);// flags: do not change the directory

if(iResult){printf("Error %d in bmcii_init\n", iResult);return iResult;}

bmcii_trace_register("COMP_QUERY",TR_ID);// register for trace messages

// get the lib version (not nessicary but helpful)iResult = bmcii_version(&iMajor, &iMinor, &iBuildNum, szBuildDate, szLibInfo);

if(iResult){printf("Error %d getting version information\n", iResult);return iResult;}else{ bmcii_trace(TR_VERBOSE,"Using version %d.%d build number %d built on %s with lib verion %s\n", iMajor, iMinor, iBuildNum, szBuildDate, szLibInfo);}


bmcii_trace(TR_VERBOSE, "InitQueryConnect to cell %s\n", szCellName);

iResult = bmcii_initQueryConnect(SEC_TOKEN_NONE, //stub, IgnoredszCellName, // name of the Impact Manager to connect&QueryHandle); // OUT, handle to the connection

if(iResult){bmcii_trace(TR_FATAL, "Error %d initilizing the query\n", iResult);bmcii_term();return iResult;}

Figure 61 Querying classes and slots (part 1 of 3)

BMCII_CLASSDEF_RESULTResultHandle;// used to retrieve query resultsCLASS_DEF_HANDLEClassDefHandle;intindent = 0;intiMySlotCount;SLOT_DEFS_HANDLEpMySlotsHandle;



/// bmcii_queryClassDefinitions ///

printf("Call bmcii_queryClassDefinitions. baseClass: %s\n", szBaseClass);iResult = bmcii_queryClassDefinitions(QueryHandle, // the query handle reurned from bmcii_initQueryConnectqueryMode, // query mode, bmcii_ClassQueryModeszBaseClass, //base class the query retrieved from.&ResultHandle); // handle for the result setif(iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_queryClassDefinitions\n", iResult);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}/// get query reply ///

do{iResult = bmcii_getClassDefQueryReply(ResultHandle,// the result handle from the query1000,// timeout in milliseconds &ClassDefHandle // a handle points to top of the class def tree); }while(iResult == BMCII_NO_RESULT_YET);

if(iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_getClassDefQueryReply. Error Message:%s\n", iResult, bmcii_errorText(iResult));bmcii_closeQueryClassDef(&ResultHandle);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}




/// Retrieve the class definition data ///

if (szClassName == NULL || strlen(szClassName) <1){ // no className specified. Let's walk through and print the class hierarchyiResult = walkClassDefTree(ClassDefHandle, 0, indent);if (iResult){printf("Error %d with with query testQueryClasses. Error Message:%s", iResult, bmcii_errorText(iResult));

bmcii_trace(TR_FATAL, "Error %d with query testQueryClasses see trace file Error Message:%s\n", iResult, bmcii_errorText(iResult));bmcii_closeQueryClassDef(&ResultHandle);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}} else{// get the specific class definition onlyiResult = bmcii_getClassDefByName(ResultHandle, //class def handle returned from bmcii_queryClassDefinitions()szClassName, // name of specified class&iMySlotCount, //OUT, number of slots retured for this class&pMySlotsHandle // OUT, point to slots result handle);if(iResult){printf("Error %d with getClassDefByName. Error Message:%s", iResult, bmcii_errorText(iResult));bmcii_trace(TR_FATAL, "Error %d getClassDefByName Error Message:%s\n", iResult, bmcii_errorText(iResult));bmcii_closeQueryClassDef(&ResultHandle);bmcii_termQueryConnect(&QueryHandle);bmcii_term();return iResult;}// Print out slot info for the giving classprintf("\n\n Start Dump Slot Info for class: %s. Number of slots: %d\n", szClassName, iMySlotCount);for (int i = 0; i < iMySlotCount; i++){// retrieve slot definitionsiResult = getSlotInfo(pMySlotsHandle, i, 2);if (iResult){printf("Error %d in getSlotInfo. Error Message:%s", iResult, bmcii_errorText(iResult));bmcii_trace(TR_FATAL, "Error %d in getSlotInfo Error Message:%s\n", iResult, bmcii_errorText(iResult));break;}}

// finish using of pMySlotsHandle info. Release the slotHandle resourceiResult = bmcii_freeQuerySlotsHandle(&pMySlotsHandle);



if (iResult){bmcii_trace(TR_FATAL, "Error %d in bmcii_freeQuerySlotsHandle Error Message:%s\n", iResult, bmcii_errorText(iResult));}

}



iResult = bmcii_closeQueryClassDef(&ResultHandle);if(iResult){bmcii_trace(TR_FATAL, "Error %d closeing query Error Message:%s\n", iResult, bmcii_errorText(iResult));bmcii_termQueryConnect(&QueryHandle);bmcii_term();

return iResult;}


iResult = bmcii_termQueryConnect(&QueryHandle);if(iResult){bmcii_trace(TR_FATAL, "Error %d terminatin the query\n", iResult);bmcii_term();return iResult;}


bmcii_term();printf("\n\ntestServer succeed!\n");

return 0;}


C h a p t e r 6
6 Startup, Shutdown, and Configuration
The functions described in this chapter start and stop the BMC II C APIs and determine the way in which the APIs operate.


Starting and stopping the integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Starting the integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Stopping the Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Initialization and termination functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147bmcii_init() (deprecated) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147bmcii_init2() (deprecated) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Best practices guideline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148bmcii_init3() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148bmcii_term() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Information functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154bmcii_connectionInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154bmcii_errorText() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154bmcii_localText() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155bmcii_Ltrace(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155bmcii_version() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Configuration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156bmcii_get_bool() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157bmcii_get_dir() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157bmcii_get_file(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157bmcii_get_num() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158bmcii_get_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158


Starting and stopping the integration

Starting and stopping the integrationUse the procedures described in this section to start and stop your integration.

Starting the integration

The steps that are required and the order in which the steps are performed varies, depending on how the integration is used.

The procedures are

■ “To Start a client-mode integration” on page 144■ “To Start a server-mode integration” on page 145■ “To Start a Client-Server Integration” on page 145■ “To Start a Query Connection Integration” on page 146

To Start a client-mode integration

1 Optional. Call any callback registration functions that you want to use.

2 Call the bmcii_init3() function to start the BMC II C APIs and load API and trace configuration information.

3 Optional. If you stored any integration configuration parameters in the IIDK.conf or your custom integrationName.conf file, call the appropriate configuration functions to obtain configuration information for your integration.

4 Optional. Load maps and message selector sets.

5 Call the bmcii_connect() function to establish connections to BMC Impact Manager instances.

6 Create and send messages as required.

7 If callbacks are not used, call the bmcii_getFromQueue() function to process the acknowledgements, errors, and connection notifications from the BMC Impact Manager instance.

NOTE HP-UX users. Make sure that you have execute permission on the libiiapi.sl file before you try to start the integration. To change permissions and enable execute permission, use the chmod 755 command on the libiiapi.sl file.


Starting the integration

To Start a server-mode integration





5 Call the bmcii_setupServer() function to enable the integration to listen for incoming connection requests from BMC Impact Manager instances and other integrations.

6 Call the bmcii_startServer() function to start the server process.


8 Process the received messages.

To Start a Client-Server Integration





5 Call the bmcii_setupServer() function to enable the integration to listen for incoming connection requests from BMC Impact Manager instances and other integrations.

6 Call the bmcii_startServer() function to start the server process.

7 Call the bmcii_connect() function to establish connections to BMC Impact Manager instances.

8 Create and send messages as required.


Stopping the Integration


To Start a Query Connection Integration





5 Call the bmcii_initQueryConnect() function to open the query connection.

6 Send queries.

7 Call the bmcii_getQueryReply() function to receive replies.

8 Call the bmcii_retrieveQueryResults() function to retrieve the query results.

9 Call the bmcii_freeQueryResults() function to free query resources.

Stopping the Integration

Stop the integration correctly to ensure that you will not lose any information between the integration and BMC Impact Manager instances in your network.

To Stop the Integration

1 Call the bmcii_stopServer() function to stop the server mode (if the integration is running as a server) and to quit your integration. All incoming and outgoing connections are disconnected.

NOTE Call the bmcii_stopServer() function only just before shutting down your integration application. Do not insert bmcii_stopServer() and bmcii_startServer() calls in your code unless you intend to disconnect from all connections.


Initialization and termination functions

2 For integrations running in client or client-server mode, call the bmcii_disconnect() function for each connection that was opened.

3 For integrations running queries, call the bmcii_closeQuery() function for each query connection that was opened.

4 For integrations running queries, call bmcii_termQueryConnect() to terminate the query connection process.

5 Call the bmcii_term() function to terminate the BMC II C APIs, close any remaining connections, and free any remaining allocated resources.

Initialization and termination functionsBefore the integration can access any of the functions of the BMC II C APIs, you must call the initialization function bmcii_init3(). This function retrieves configuration and trace parameters, allocates memory, and sets up the trace facility. It also loads the following default selector files:

■ recvfilterin.selector■ recfilterout.selector■ sendfilterin.selector■ sendfilterout.selector

When you are done using the BMC II C APIs, call the bmcii_term() function to perform general cleanup of memory, connections, and resources in the integration.

Table 16 lists the functions that control how the BMC II C APIs are initialized and terminated and provide information about the BMC II C APIs.

bmcii_init() (deprecated)

The bmcii_init() function was deprecated in the 2.1 version of the BMC II Software Developer’s Kit. If you call the bmcii_init() function, it calls the bmcii_init3() function.

Table 16 Initialization and termination functions

Function Name Described on

bmcii_init (deprecated) page 147

bmcii_init2 (deprecated) page 148

bmcii_init3 page 148

bmcii_term page 153


bmcii_init2() (deprecated)

bmcii_init2() (deprecated)

The bmcii_init2() is deprecated in the 2.2 version of BMC II Software Developer’s Kit. If you call bmcii_init2(), it calls the bmcii_init3() function.


Use the bmcii_init3() function to initialize the BMC II C APIs.

bmcii_init3()

Call the bmcii_init3() function once before you call any other BMC II C API function calls. If you do not call bmcii_init3(), all subsequent calls will fail.

The bmcii_init3() function

■ reads the configuration and trace files■ sets global parameters■ builds structures, allocates memory, and initializes the BMC II C APIs■ starts a receive thread running in the background■ starts the BMC II C API tracing■ loads the default message selector files ■ changes the current working directory to the home directory during initialization

or maintains the current directory as the working directory

Its declaration looks as follows:

When you call the bmcii_init3() function, you pass it the following arguments:

bmcii_result bmcii_init3(BMCII_STR *szHomeDir, BMCII_STR *szIntegrationName, BMCII_STR *szInstanceName, BMCII_STR *szProgramID, BMCII_STR *szConfigFile, BMCII_STR *szOverrides,BMCII_STR*szDefaults,BMCII_BOOL bisServer, unsigned int uiFlags);


bmcii_init3()

Table 17 Input arguments: bmcii_init3()

Argument Description

szHomeDir string description that specifies the home directory of the integration application. You should specify an absolute path that contains the root directory. If you do not specify a home directory, the root directory of the system drive is used.

Note: For demonstration purposes, ‘.’ is used in place of an actual home directory. During implementation, you must use an absolute path for the home directory.

szIntegrationName string description containing the name of the integration application. The IntegrationName value must not contain an underscore (_).

szInstanceName string description containing the name of the integration instance when more than one instance of the integration application is running. The InstanceName value must be unique, and it must not contain an underscore (_). If no InstanceName value is specified, the host name where the instance is running is used.

szProgramID string description containing a three-character abbreviation of the IntegrationName value. Register this ID with BMC Software to maintain its uniqueness.

szConfigFile string that defines the path and file name of the configuration file. If you do not specify a path but only the configuration file name, then the current working directory is used. If you do not specify a configuration file name, then the default value is $homeDirectory/etc/hostName or instanceName. (If you do not specify a home directory, then the root directory is used.)

To disable the configuration file, enter ““ here.

szOverrides in a string separated by new lines \n, specifies that the indicated configuration value is overridden at runtime

szDefaults in a string separated by new lines \n, specifies that default values can be used for configuration parameters if the parameter value is missing

bisServer Boolean indicator that shows whether the integration is running in the foreground or, if set to True, in the background as service or daemon

uiFlags unsigned integer. Values are INIT_FLAG_NONE or INIT_NO_CHANGEDIR. The default value is INIT_FLAG_NONE.

INIT_FLAG_NONE: indicates that the current working directory will revert to the Home directory during initialization.

INIT_NO_CHANGEDIR: indicates that the current working directory will not be changed during initialization.


bmcii_init3()


You should register for any callback function that you wish to use before you call bmcii_init3(). For example, if you are receiving events and you use callbacks, you should register bmcii_registerNewMessage() before you call bmcii_init3(). If you are receiving modifications, register bmcii_registerModify() before you call bmcii_init3(). See “Callbacks” on page 200 for more information about callbacks.

Running the BMC II C APIs in the background or foreground

The bmcii_init3() function parameter, isServer, indicates whether the integration runs as a background process or a foreground process. When the isServer value is true (BMCII_TRUE), this indicates to the BMC II C APIs that the integration runs as a background process; when the value is false (BMCII_FALSE), this indicates to the BMC II C APIs that the integration runs as a foreground process.

The output of trace messages and the location of the integration working directory can be affected by whether the BMC II C APIs run in the background or the foreground.

Trace output

When the integration runs as a background process, trace output is sent to the default log file.

When the integration runs as a foreground process, trace output is sent to standard output.

Working directory designation

When the integration runs as a background process, the BMC II C APIs change the current working directory of the integration to the home directory, unless you have used the INIT_FLAG_NONE function to prevent the working directory from being changed.

When the integration runs as a foreground process, the current working directory is not changed.

NOTE Do not register the custom callback function bmcii_registerFunction() before the bmcii_init3() function. The bmcii_registerFunction() returns selector and mapping information, not events, queries, or modifications.


bmcii_init3()

Single and multiple integration instances

You can run a single instance of your integration on a single computer or you can run two or more instances of your integration on the same computer.

Single instance

If you are running only one integration on a computer, specify NULL as the value for the szInstanceName parameter. The BMC II C APIs will insert the host name for instance name.

The BMC II C APIs use the host name for the instance name in mc_ueid IDs and mc_udid IDs.

For more information, see “Message identification” on page 91.

Multiple instances

To run multiple integration instances on the same computer, start the integration multiple times. Each time, call the bmcii_init3() function with a unique instance name.

Instance names must be unique and repeatable and they must not contain underscores (_). Usually the customer assigns a name to each instance, with the name indicating the purpose of the instance. A process identifier (PID) is not repeatable and should not be used.

Each instance of an integration can use a different set of configuration parameters.

To use an instance-specific set of configuration parameters, place the instance-specific configuration file in a subdirectory under the integration’s configuration directory. Name the subdirectory with the instance name. For example, if the configuration directory is c:\im\config and the instance name is security, then the special configuration file for that instance is placed in the c:\im\config\security directory. For more information, see “Deploying multiple integration instances on the same computer” on page 303.

NOTE In the mcell.dir files, you list integrations in server mode as integrationname_instancename.


bmcii_init3()

Directories

If you are using any of the following files, they must be located in the configuration directory unless you specify otherwise in the IIDK.conf or your custom integrationName.conf file:

■ mcell.dir

■ IIDK.conf or your custom integrationName.conf file■ integrationName.trace

The location of the configuration file directory is influenced by two factors:

■ whether you specify an instance name in the bmcii_init3 function■ the value specified for the ConfigFile parameter, in which you specify the .conf file

being used to configure the BMC II C APIs

Table 18 describes how various combinations of these two parameters affect your integration.

NOTE To see which directories the BMC II C APIs use as the configuration and home directories, enable VERBOSE tracing and then check the trace file.

NOTE You can specify the following values for the ConfigFile parameter:

--the full path to the .conf file and its name--the name of the .conf file, only (no path included)--NULL


bmcii_term()

bmcii_term()

The bmcii_term() function stops the BMC II C APIs, frees any remaining allocated resources, and closes any remaining open connections.

Table 18 Configuration File Location

ConfigFile Parameter Value No Instance Name Specified Instance Name Specified

Full Path and Name

When a full path and file name are specified for the parameter, use the specified file name as the configuration file name and the specified directory as the configuration directory.

When a full path and file name are specified for the parameter, the configuration directory is specified_path\instance_name.

If the \instance_name subdirectory does not exist or if the configuration file is missing from that directory, the BMC II C APIs search specified_path\ for the configuration file.

Name When only a file name is specified for ConfigFile, that file name is accepted, but the current working directory acts as the configuration directory. Configuration files must be placed in the working directory.

When only a file name is specified for ConfigFile, that file name is accepted.

The working_dir\instance_name directory acts as the configuration directory.

If the \instance_name subdirectory does not exist or if the configuration file is missing from that directory, the BMC II C APIs search the current working directory for the configuration file.

NULL When the ConfigFile value is NULL, the integration uses home_dir\etc as the configuration directory.

Note: The BMC II C APIs operate using default settings, only.

When the ConfigFile value is NULL, the integration uses home_dir\etc\instance_name as the configuration directory.

If the \instance_name subdirectory does not exist or if the configuration file is missing from that directory, the BMC II C APIs search home_dir\etc\ for the configuration file.

Note: The BMC II C APIs operate using default settings, only.

NOTE Before calling the bmcii_term() function, BMC Software recommends that you call the

■ bmcii_disconnect function for each open connection ■ various resource-freeing functions, such as bmcii_freeMessage()■ bmcii_stopServer function (if running in server mode).


Information functions

Information functionsUse the information functions to obtain the connection status, descriptions of errors, and the version of the loaded BMC II C APIs’ library. Table 19 lists the functions.

bmcii_connectionInfo()

The bmcii_connectionInfo() function obtains the current status of a connection between the integration and a specified BMC Impact Manager instance or another integration. It also obtains information about the send and recv buffers.

The connection status and buffer information are returned to the integration as a bmcii_connectNotify structure. For more information about this structure, see “bmcii_ConnectNotify” on page 316.

This function differs from the bmcii_registerConnectStatus() function. The bmcii_connectionInfo() function notifies the integration of the connection status and buffer state when the function is called. The bmcii_registerConnectStatus() function registers for a callback function that notifies the integration when connection status or buffer state changes. For more information, see “bmcii_registerConnectStatus()” on page 202.

bmcii_errorText()

The bmcii_errorText() function returns a pointer to a static text message associated with the specified error code. After you have the pointer, you can display the text message.

The static text error descriptions are coded into the BMC II C APIs’ libraries.

The bmcii_errorText() supports multiple language compliance inasmuch as it can return a pointer to locale-specific message catalogs. The strings are UTF-8 encoded.

Table 19 Information functions


bmcii_connectionInfo() page 154

bmcii_errorText() page 154

bmcii_localText() page 155

bmcii_Ltrace() page 155

bmcii_version() page 155


bmcii_localText()

bmcii_localText()

The bmcii_localText() function supplies the integration with the ability to use properties files. The integration passes the specified key and returns a pointer to an appropriate localized version of a string. The versions of the string are kept in the properties file in the locale subdirectory.

The key that you provide must be unique and in alphanumeric format.

You can pass multiple arguments to the bmcii_localText() function much as you can with the bmcii_Ltrace() function.

bmcii_Ltrace()

Use the bmcii_Ltrace() function to localize the trace messages. See “Localizing trace messages” on page 99 for more information.

bmcii_version()

The bmcii_version() function returns the version of the loaded BMC II C APIs’ .dll file or shared object. These files are described in “Installing the BMC II C APIs in a development environment” on page 31.

Unlike the other C API function calls, the bmcii_version() function does not need to be initialized before it’s called. In other words, you do not need to call bmcii_init3() before calling bmcii_version(). The bmcii_version() function contains the following output parameters:

Table 20 Output parameters: bmcii_version (part 1 of 2)

Output parameter Description

iMajor major version of the API library (usually reserved for interface changes)

iMinor minor version of the API library

iBuild build number for the library


Configuration functions

Configuration functionsThe IIDK.conf or your custom integrationName.conf file contains parameters that are used by the BMC II C APIs. However, you can also store configuration information required by your integration in this file.

You may find it convenient to group additional parameters used by the integration (but not by the BMC II C APIs) in the same file.

Use the configuration functions listed in Table 21 and described on the following pages to obtain the values of those integration parameters.

szBuildDate date that the library was built

szLibInfo returns information about the core library, such as the version number, build date, and language information

Example:

Release:7.0.00 Build Number:10321050 Build Date: 1-Feb-2007 Locale Language:English Locale Country:United States Locale Variant: Locale Encoding:1252 Locale Internal:English_United States.65001

NOTE Do not modify the strings that these functions return. The strings are pointers to a static copy in memory of the returned value.

Table 21 Configuration functions

Configuration Function Name Described on

bmcii_get_bool() page 157

bmcii_get_dir() page 157

bmcii_get_file() page 157

bmcii_get_num() page 158

bmcii_get_string() page 158

Table 20 Output parameters: bmcii_version (part 2 of 2)

Output parameter Description


bmcii_get_bool()

bmcii_get_bool()

The bmcii_get_bool() function returns a returns a boolean value from the parameter specified by the szName argument.

This function returns BMCII_TRUE or BMCII_FALSE, although it understands the following valid configuration file values:

■ TRUE/FALSE

■ YES/NO

■ ON/OFF

■ ENABLE/DISABLE

bmcii_get_dir()

The bmcii_get_dir() function returns a static string that contains a directory name value from the parameter specified by the szName argument.

bmcii_get_file()

The bmcii_get_file() function returns a static string that contains a file name value from the parameter specified by the szName argument.

NOTE The function always returns path values using forward slashes (/) on both Windows and UNIX platforms.

Do not modify the value directly.

NOTE The function always returns path values using forward slashes (/) on both Windows and UNIX platforms.

Do not modify the value directly.


bmcii_get_num()

bmcii_get_num()

The bmcii_get_num() function returns an integer value from the parameter specified by the szName argument.

bmcii_get_string()

The bmcii_get_string() function returns a static string that contains a text string value from the parameter specified by the szName argument.

NOTE Do not modify the value directly.


C h a p t e r 7
7 Server Mode
To receive events and modify messages and accept connection requests, the integration must be in server mode.


Server setup and use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Server mode functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

bmcii_setupServer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161bmcii_startServer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161bmcii_stopServer(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

NOTE If BMC Impact Manager instances and other integrations will not be connecting to your integration to send it events and modify messages, it is unnecessary to enable server mode.


Server setup and use

Server setup and use An integration can operate in the following modes:

■ Client – can initiate a connection with a target BMC Impact Manager instance or integration

■ Server – can listen for and accept connections from other BMC Impact Manager instances and integrations

■ Client and Server – can act simultaneously as both a client and a server

Server mode enables the integration to receive connection requests from BMC Impact Manager instances and integrations with which it has not initiated a connection.

Enabling server mode also makes it possible for your integration to receive event and modify messages. To receive events from a BMC Impact Manager instance, you must define propagation rules or a propagation policy that specifies the conditions under which messages are sent to your integration. For more information about propagation rules, see “Propagation rules and propagation policies” on page 86 and the BMC Impact Solutions: Administration guide.


Server mode functions

Server mode functionsServer mode is managed using the functions listed in Table 22.

bmcii_setupServer()

The bmcii_setupServer() function enables the integration to listen for incoming connection requests from BMC Impact Manager instances and other integrations.

Use the @host:port#key format to specify your integration in the szServerName parameter of the bmcii_setupServer() function.

If you do not use the @host:port#key format as the server name, the bmcii_setupServer() function examines the local mcell.dir file for connection data about the integration, which is named in the call with the szServerName parameter. After the information is obtained, the function creates a socket and binds the integration to it.

Listening for connection requests does not start until the integration calls the bmcii_startServer() function, described on page 161.

The integration listens on the port number specified in @host:port#key or the integration definition in the mcell.dir file.

bmcii_startServer()

The bmcii_startServer() function listens for incoming connection requests and incoming messages on established connections.

The integration listens on the port number specified with the bmcii_setupServer() function.

To stop listening, call the bmcii_stopServer() function, described on page 162.

Table 22 Server Mode Functions by Type

Purpose Function Name Described on

Server Setup and Use

bmcii_setupServer() page 161

bmcii_startServer() page 161

bmcii_stopServer() page 162


bmcii_stopServer()

bmcii_stopServer()

The bmcii_stopServer() function causes the integration to stop listening for incoming connection request and disconnects the integration from all incoming and outgoing connections. Call the bmcii_stopServer() function at termination time to shut down the integration application.


C h a p t e r 8
8 Connections and Tracing
The programming guidelines and functions required to connect an integration to cells in the BMC Impact Manager network and to disconnect from them are described in this chapter.

Tracing guidelines and functions are also described.


Directory functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164bmcii_getDirectoryInfoByName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164bmcii_getFirstDirectoryInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164bmcii_getNextDirectoryInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Connections and buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Connection intervals and connection acceptance . . . . . . . . . . . . . . . . . . . . . . . . . . 165Background receive thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Connection autoreconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Heartbeats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Maximum number of open outgoing connections . . . . . . . . . . . . . . . . . . . . . . . . . 168

Connection functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168bmcii_connect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168bmcii_disconnect(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Tracing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171bmcii_Ltrace(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171bmcii_trace() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172bmcii_Ltrace_register() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173


Directory functions

Directory functionsThe BMC Impact Manager directory functions access the information in the local mcell.dir file. This is the mcell.dir file specified in the iidk.conf or your custom integrationName.conf file.

Cell identification information (hostname, port number, and so on), is listed in the local mcell.dir file. You can access this information using the BMC II C APIs’ directory functions.

The directory functions are exposed for your convenience. You do not need to use them to establish a connection with another BMC Impact Manager instance or another integration. they are used internally by other BMC II C APIs’ functions, such as bmcii_connect().

bmcii_getDirectoryInfoByName()

The bmcii_getDirectoryInfoByName() function obtains information from the local mcell.dir file about the BMC Impact Manager instance (cell) that is specified in the call by name.

The integration must allocate the bmcii_DirectoryInformation structure and set the lVersion field value to CURRENT_DIRECTORY_VERSION. The bmcii_getDirectoryInfoByName() function fills in the data.

bmcii_getFirstDirectoryInfo()

The bmcii_getFirstDirectoryInfo() function obtains the first BMC Impact Manager instance (cell) information entry from the local mcell.dir file.

The integration must allocate the bmcii_DirectoryInformation structure and set the lVersion field value to CURRENT_DIRECTORY_VERSION. The bmcii_getFirstDirectoryInfo() function fills in the data.

Table 23 Directory functions

Function Described on

bmcii_getDirectoryInfoByName() page 164

bmcii_getFirstDirectoryInfo() page 164

bmcii_getNextDirectoryInfo() page 165


bmcii_getNextDirectoryInfo()

bmcii_getNextDirectoryInfo()

The bmcii_getFirstDirectoryInfo() function iterates through the BMC Impact Manager instance (cell) information entries in the local mcell.dir file to obtain the entry subsequent to the last entry that was obtained. The function stops when it returns BMCII_NO_MORE.

Connections and buffersThe bmcii_connect() function establishes a connection between an integration and a BMC Impact Manager instance or another integration.

To identify the target of the connection request, the bmcii_connect() function determines whether the value of the ServerName parameter that is supplied in the function is in the @host:port#key format or is specified as a server name. If it is a server name, the function examines the mcell.dir file for the host name, port number, and encryption key associated with that server name.

The bmcii_disconnect() function breaks the connection and frees internal resources that bmcii_connect() used. For each message that was sent and has not received a reply, a cancel reply message is added to the queue.

Connection intervals and connection acceptance

This section describes important issues regarding how the integration receives connections.

Background receive thread

The bmcii_init3() function starts a background receive thread The receive thread runs constantly but is optimized to use resources only as needed. This thread enables the integration to receive incoming connection requests and messages regularly in the background. All received messages and connection notifications are added to the message queue.

If a callback has been registered, the callback thread retrieves the item from the queue and calls the appropriate callback function. The use of the additional thread negates the impact of a slow callback function on the performance of the receive thread.

See “Receiving messages and replies” on page 193 for more information.


Connection autoreconnect

Connection autoreconnect

The BMC II C APIs separate the client connections so that integration does not need to keep track of the connection state. When a connection is unexpectedly lost or a destination is unavailable, the BMC II C APIs buffer events transparently. The BMC II C APIs periodically try to reconnect to the destination. Once the connection is established, they send all buffered events in the order in which they were stored.

The interval period for reconnection is by default 10 minutes, but you can specify a non-default interval period by setting the MessageBufferReconnectInterval parameter in the IIDK.conf or your custom integrationName.conf configuration file.

Heartbeats

If your integration is connecting with a version 5.1.01 or later version of the BMC IM cell, then upon connection the BMC II C APIs register with the cell for a heartbeat and begin to send heartbeats at the default intervals (see HeartbeatInterval parameter in Table 10 on page 49). If the 5.1.01 or later cell misses a heartbeat, it issues a warning message. If it continues to miss heartbeats, it issues another warning and then a critical message.

From your client integration, you can see that the connection is down through a status change notification. You can get the notification by calling the getFromQueue() function or by registering for a callback.

Buffering

The BMC II C APIs support two types of buffering: memory buffer and persistent buffer. The memory buffer is the main buffer. You can define its size and indicate whether you want to buffer a specific event. The persistent buffer controls the copying of the memory buffer to the file system. It can have settings of none, default, low, or high.

Messages that are sent to a destination to which no connection has been established can be discarded (no buffering) or buffered until the destination becomes available. The different buffering modes offer varying degrees of protection for the message in the event of a shutdown or a crash.

The buffering can be set for several levels for the integration:

■ The global default for all connections is set in the IIDK.conf or your custom integrationName.conf file. For more information, see Table 10 on page 49.


Buffering

■ Settings that override the global default are specified using the bmcii_connect() function. For more information, see “Persistent buffering modes” on page 167.

■ Settings for a single message, overriding global defaults and settings specified for the connection, are specified by adding the META_BUFFER_MODE metaslot to the message. META_BUFFER_MODE values are listed in Table 26 on page 179.

Use the bmcii_connect() function to specify the type of buffering used when making a connection attempt. All messages sent for the duration that the connection is established are buffered the same way.

Persistent buffering modes

There are four buffering modes available for the persistence of buffered messages to the file system. They are expressed in the bmcii_BufferMode enumeration:

■ BMCII_BUFFER_MODE_NONE-Buffered events are not persisted to the file system. Messages are persisted only in memory and will be lost if the integration shuts down or terminates unexpectedly.

■ BMCII_BUFFER_MODE_HIGH–always saves the message as a file on the integration host computer before it is sent, regardless of whether the message is subsequently buffered. The BMC II C APIs remove the message from the file after it is sent successfully.

■ BMCII_BUFFER_MODE_LOW–saves the message to a file on the integration host computer if the message is buffered to memory. The BMC II C APIs remove the message from the file after it is sent successfully.

■ BMCII_BUFFER_MODE_DEFAULT–sets the buffering mode to the value specified for the connection by the PersistencyLevel parameter in the in the IIDK.conf or your custom integrationName.conf file. This setting enables you to specify a buffering mode that is specific to the message, not the connection.

Memory buffer

By default, the memory buffer holds 2000 messages. To specify a different value, you must set a value for the MessageBufferSize parameter in the IIDK.conf or your custom integrationName.conf file.

NOTE If the PersistencyEnabled parameter in the IIDK.conf or your custom integrationName.conf file is set to NO, messages are not saved to a file. They are buffered in memory only.


Maximum number of open outgoing connections

When the buffer is full, any subsequent messages that arrive are discarded, unless the message contains the META_BLOCK_FOR_BUFFER=TRUE metaslot. You can use the metaslot META_FAIL_IF_UNCONNECTED to turn off buffering for a specific event. To obtain information on the current state of the buffer, call the bmcii_connectionInfo function.

For more information about metaslots, see “Metadata” on page 178. For more information about the configuration file, see Chapter 3, “Configuration Basics.”

Maximum number of open outgoing connections

Your integration application is limited to a maximum number of 100 open outgoing connections per session to one or more BMC IM cells. The number of incoming connections is not limited.

Connection functionsThe connection functions enable the integration to establish and end connections that the integration initiates with BMC Impact Manager instances and other integrations.

Table 24 lists the connection functions.

bmcii_connect()

The integration calls the bmcii_connect() function to initiate a connection to a BMC Impact Manager instance or other integration server specified in the function call. The BMC Impact Manager instance must be listed in the mcell.dir file specified in the IIDK.conf or your custom integrationName.conf file.

If the required BMC Impact Manager instance is not listed in the specified mcell.dir file, the host, port, and encryption key can be specified in the bmcii_connect function call as a string: @hostname:port#key, where hostname can be the hostname or an IP address.

Table 24 Connection Functions


bmcii_connect() page 168

bmcii_disconnect() page 170


bmcii_connect()

If no immediate errors are encountered, a connection handle (BMCII_CNC) is created and returned to the integration. Any functions requiring this connection will use the connection handle.


Connections take time and resources to establish. BMC recommends that you keep connections open and reuse them, unless you expect that events will be sent less often than once every 15 minutes.

The integration is notified when the connection attempt is successful through a connection status notification. To determine the connection status at any time, call the bmcii_connectionInfo() function. To obtain an update when the connection status changes, register a callback with the bmcii_registerConnectStatus() function.

For more information, see “Connection intervals and connection acceptance” on page 165, “bmcii_connectionInfo()” on page 154, and “bmcii_registerClientConnectDisconnect()” on page 202.

The default interval between connection attempts is 600 seconds.

To modify the reconnection attempt interval, include the MessageBufferReconnectInterval parameter in the IIDK.conf or your custom integrationName.conf configuration file with the required value. For more information, see Chapter 3, “Configuration Basics.”.

Buffering

In the bmcii_connect() function, you specify whether messages sent using the connection that you are establishing are buffered and how they are buffered. For more information about buffering, see “Buffering” on page 166.

NOTE Successful completion of the bmcii_connect() function call does not ensure that a connection has been established with the intended destination. If no connection is established, connection attempts are made periodically in the background.

NOTE Establishing multiple connections to the same destination generally has no performance benefit and indeed may be detrimental to the integration’s performance.


bmcii_disconnect()

Encryption

The encryption key specified by the integration in the bmcii_connect() function call must be identical to the one used by the BMC Impact Manager instance or integration server to which the integration is connecting. The encryption key for each integration and BMC Impact Manager instance is listed in their entries in their mcell.dir file.

For more information, see “Encryption key matching” on page 93.

bmcii_disconnect()

The bmcii_disconnect() function closes the connection between the integration and the BMC Impact Manager instance.

If the connection was open using memory-only buffering, any buffered events or data will be discarded. If the connection was opened using persistent buffers, buffered events and data are saved in a file.

NOTE The SecToken is parameter of the bmcii_connect() function is not in use currently. It may be used as a placeholder for a future version of the BMC II C APIs.

WARNING If the PersistencyDisconnectRemovesMessages parameter of the IIDK.conf or your custom integrationName.conf file is set to Yes, messages written to a file are erased when the integration is shut down correctly. BMC Software recommends that you set this parameter to No.


Tracing functions

Tracing functionsTracing is the logging facility that the BMC II C APIs use to log errors and progress. The functionality is exposed to the integration developer as an extra service. Through the use of the integration configuration file and the trace configuration file the user has complete control of the output for tracing. For example, you can specify that all fatal errors are written to a separate log file. For a complete description of using the tracing logs, see the BMC Impact Solutions: General Administration guide.

You have two options for setting up the trace facility. The first is to use the bmcii_trace() function, which only logs the arguments given to it. The other option is to use bmcii_Ltrace(), which looks up the main string from properties files and saves a localized version of the message. The BMC II C APIs use the bmcii_Ltrace() for all of its trace messages.

Table 25 lists the tracing functions.

bmcii_Ltrace()

Use the bmcii_Ltrace() function to output a localized message to the trace logs or to the console.

Its first input argument is the trace level. A severity level is assigned to each message. The severity levels are TR_FATAL, TR_ERROR, TR_WARNING, TR_INFO, TR_VERBOSE, and TR_NONE. These severity levels are actually macros that contain the current name for the module (provided by bmcii_Ltrace_register), the source file name, the line number, and the severity level.

The use of macros simplifies the use of the bmcii_Ltrace() function.

NOTE The tracing functions use macros for arguments. The macros are resolved to multiple parameters. BMC recommends that you use the macros.

Table 25 Tracing functions

Function Described on

bmcii_Ltrace() page 171

bmcii_trace() page 172

bmcii_Ltrace_register() page 173


bmcii_trace()

The second input argument is the message number. The number indicates a unique messages for the specific source module. The combination of message number, module number (from bmcii_Ltrace_register), and the integration abbreviation is used to find the message key. The message key is used with the locale setting to look up the proper format string in the properties file.

A variable number of input parameters follow this number. Each parameter must be preceded by a data type indicator such as one of the following:

■ TR_ARG_BOOL■ TR_ARG_UINT■ TR_ARG_INT■ TR_ARG_REAL■ TR_ARG_STR

The last argument must be TR_ARG_END.

bmcii_trace()

The bmcii_trace() function is used to output a message to the trace logs or to the console. The bmcii_trace() function performs logging according to the parameters supplied in the IIDK.conf or your custom integrationName.conf and integrationName.trace files.

With each message, a severity level is assigned. The severities can be TR_FATAL, TR_ERROR, TR_WARNING, TR_INFO, TR_VERBOSE, or TR_NONE. These severity levels are actually macros that contain the current name for the module (provided by bmcii_Ltrace_register), the source file name, the line number, and the severity level.

The use of the macros simplifies the use of the bmcii_trace() function.

The second parameter is the formatter string. This string uses the same formatters as the printf function. As with the printf function, the remaining values are variable in number and data type.

The bmcii_trace() function performs logging according to the parameters supplied in the IIDK.conf or your custom integrationName.conf and integrationName.trace files.

EXAMPLE // "Error %d connecting to Impact Manager %s. : %d"bmcii_Ltrace(TR_VERBOSE, 27,TR_ARG_INT,iResult,TR_ARG_STR,szServer,TR_ARG_END);


bmcii_Ltrace_register()

Example


The bmcii_Ltrace_register() function associates a source code file name with a module name and a module number. The module name will be part of the trace message in the trace log.

The first input parameter is the name that will be output in the trace logs. This name can also be used in the trace configuration file to separate the trace messages from this source file from other trace messages. The second input parameter is a number that designates the source file. The bmcii_Ltrace() function uses this number to complete the key. This number must be unique for all of the integration source files. The third input parameter is the ID that is associated with the name and number. This parameter must always be TR_ID for the function to work properly.

NOTE You must call the bmcii_Ltrace_register() function to associate a source code file name to a trace name before you call the bmcii_trace() function.

Figure 65 bmcii_trace(): Code Example

bmcii_trace(TR_FATAL, "The file %s is locked, unable to open. Error %d", szFileName, iResult);

NOTE The bmcii_trace_register() function has been deprecated. You should no longer use it. It is included in the BMC II C API package for backwards compatibility only.

NOTE You must call the bmcii_Ltrace_register() function to associate a source code file name to a trace name before you call bmcii_Ltrace().

Figure 66 bmcii_Ltrace_register Code Example

bmcii_Ltrace_register("STARTUP", 1, TR_ID);


C h a p t e r 9
9 Message Construction

Creating and managing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Message format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Message identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Message helper functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Message creation and deletion functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

bmcii_clearMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181bmcii_copyMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181bmcii_createMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181bmcii_freeMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182bmcii_getMessageType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182bmcii_setMessageType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Slot manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183bmcii_freeString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184bmcii_freeStringList() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184bmcii_getSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184bmcii_messageGetBaroc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184bmcii_messageSetBaroc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185bmcii_removeSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185bmcii_removeSlotValueListItem() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185bmcii_setSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185bmcii_setSlotValueList() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186bmcii_setSlotValuesByArray(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Slot iteration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186bmcii_getFirstSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187bmcii_getNextSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Metadata functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188bmcii_getFirstMetaSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188bmcii_getNextMetaSlotValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189bmcii_getMetaSlotValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189bmcii_removeMetaSlotValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189bmcii_setMetaSlotValue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Message information functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190bmcii_dumpMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190


Creating and managing messages

bmcii_getSlotCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Creating and managing messagesA message is the container for events, data, and query results that are sent between your integration application and a BMC Impact Manager instance or another integration.

Message format

Messages are composed of a class name that describes the class of the message, its type, and a series of slots (attributes and values) that comprise the content of the message. The class and a message type are required. The class and message type can be set in metaslots or by using the bmcii_setMessageType() function. For more information about metaslots, see “Metadata” on page 178.


Event messages are identified by an mc_ueid ID. Data messages are identified by an mc_udid ID. These strings are stored in slots. For more information, see “Message identification” on page 91.

Message helper functions

The message helper functions are used to hide formatting of events and data. They provide the ability to manage the information in an easy to manage and access format. The storage mechanism is internal to the BMC II C APIs and should not be modified directly. An integration should use the message functions or translation to manipulate the message information. For more information about mapping, see “Translating events and data” on page 247.

All values that are placed in a message are in string format. Therefore any data types other than strings must be converted before adding them to a message.

NOTE A class is not required for a modify message.


Message helper functions

Special information, such as a message type (new event, modify event, data) can be set using key words and metaslots.

All message functions support UTF-8 encoded strings and they return UTF-8 encoded strings.

Creating a message

Messages are created by several functions. The main way an integration can create a message is with the bmcii_createMessage() function. The bmcii_createMessage() function will create a new message and initialize its values. The integration is responsible for releasing the message when it is finished with it.

Building a message

There are several functions to add new slots to a message and to define information about a message. Functions are available that manipulate the contents of regular slots and slots that are of the LIST_OF data type. For regular slots, the functions require only the slot name and the value associated with it. For slots that are of the LIST_OF type, the functions require the slot name, the value, and the index where the value will be placed. The class and the type of message can be set through the use of the regular slot setting functions or metaslots by using key words for the slot name.

Retrieving slots from a message

The value of slots can be retrieved in two ways. The values can be directly retrieved by using functions that use the slot name to find the value. The values can also be found by iterating through all of the slot value pairs that are defined in a message. The values of slots that are defined with the keyword LIST_OF can be retrieved as an array of string values.

The functions that retrieve a value from the message allocate a list of strings that contain copies of the values. If the slot is a regular slot, not a LIST_OF, the array contains one string. It the slot is defined as a LIST_OF, it allocate strings and inserts them into the array that is returned. When the integration is done using the list of strings, call the bmcii_freeStringList() function to release the allocated memory.

Formats

Messages can be set by passing in a BAROC-formatted event or data to a set function. The function will parse the format and organize it. Any parsing errors are reported.

The bmcii_messageGetBaroc() function allocates a string large enough to return a copy of a BAROC-formatted string. When the integration is finished with the string it must call the bmcii_freeString() function to free resources.


Metadata

Clearing and freeing messages

A message can be reused by using the clear message functions. This function releases all memory allocated for storing the slots by removing all slots from the message, including metaslots. It will then reset all metadata for the message to their defaults. The message can then be reused.

Any message that is not being used by the integration process can be freed by using the free message function. This function will release all memory allocated for storing the slots and the message metadata information.

MetadataRegular message slots are included in the content sent to the destination as an integral part of the message. Metadata is in a message as metaslots. These metaslots are not sent to the message destination. The metaslots hold information about the message and how to handle the message, and act as storage for integration-defined information.

You create and maintain metaslots and their values using specialized functions. These functions are listed under the MetaData heading in Table 27 on page 181.

There are a number of predefined metaslots. You can create additional metaslots, also. These slots can be used to store information in any message that you require that you do not want to pass to the message destination. Table 26 lists the predefined metaslots.

WARNING Do not use the standard C free or delete function on a message because it results in a memory leak. Use the appropriate BMC II C API function instead: for example, bmcii_freeString().


Metadata

Table 26 Predefined Metaslots (part 1 of 2)

Metaslot Name Valid Values

META_BLOCK_FOR_BUFFER retains a message in memory when the message buffer is full. Normally, messages are discarded when the target BMC Impact Manager instance is not available and the buffer is full.

Valid values:

■ TRUE – enabled■ FALSE – disabled

META_BUFFER_MODE overrides the current buffer setting for the connection when a message containing the specified slot occurs

Valid values:

■ META_VALUE_BUFFER_DEFAULT■ META_VALUE_BUFFER_HIGH■ META_VALUE_BUFFER_LOW■ META_VALUE_BUFFER_NONE

For more information about these values, see “Buffering” on page 166.

META_CLASS_NAME specifies the class of an event or data message

META_DATA_HANDLE specifies a data handle for the data message in which the slot is included. The data handle can be used if the integration needs to use the mod_data message type (to identify which message is to be modified).

Valid values: data_handle

META_EVENT_HANDLE specifies an event_handle for the event message in which the slot is included. The event handle is needed if the integration needs to use the mod_data message type (to identify which message is to be modified).

Valid values: event_handle

META_FAIL_IF_UNCONNECTED

overrides buffer settings to discard the message if the target BMC Impact Manager instance is unavailable (causing the message send to fail). For example, you can use this slot to prevent heartbeat messages from being buffered.

Valid values:

■ TRUE – no buffering■ FALSE – disabled


Metadata

META_MSG_TYPE specifies the type of the message.

Valid values:

■ META_VAL_MSG_MOD_DATA■ META_VAL_MSG_MOD_EVENT■ META_VAL_MSG_NEW_DATA■ META_VAL_MSG_NEW_EVENT■ META_VAL_MSG_NONE■ META_VAL_MSG_OVERWRITE_DATA■ META_VAL_MSG_DELETE_EVEN■ META_VAL_MSG_DELETE_DATA

Notes:

■ A message type is required for all messages.■ You can use this slot in place of “bmcii_setMessageType()”.■ For more information about message types, see

“BMCII_MESSAGE_TYPE” on page 309.

META_SOURCE_CNC the connection handle representing the connection between the integration and the BMC Impact Manager instance through which the message was received.

Note: The integration must be in server mode to see this slot.

Table 26 Predefined Metaslots (part 2 of 2)

Metaslot Name Valid Values


Message creation and deletion functions

Message creation and deletion functionsThe message creation and deletion are used for the most basic tasks in creating, copying, and deleting messages and freeing resources.

Message functions are described in Table 27.

bmcii_clearMessage()

The bmcii_clearMessage() function releases all memory used to store the event or data content, and then reinitializes the message to its original state. The reinitialized message contains the same slots as it did before the values were cleared out.

After a message is cleared, it can be reused without any corruption from its previous message content.

bmcii_copyMessage()

The bmcii_copyMessage() function creates a message identical to the existing message specified in the function.

bmcii_createMessage()

The create message function creates and initializes the memory needed to store an event or data message. The format of the storage for the message is internal and should not be modified directly.

When you are done with the message, you have two options:

Table 27 Message Functions by Type


bmcii_clearMessage() page 181

bmcii_copyMessage() page 181

bmcii_createMessage() page 181

bmcii_freeMessage() page 182

bmcii_getMessageType() page 182

bmcii_setMessageType() page 183


bmcii_freeMessage()

■ release the message memory by calling the bmcii_freeMessage() function

■ clear the message while enabling the message to be reused, by calling the bmcii_clearMessage() function. This function reinitializes the message and releases previous slot values.

bmcii_freeMessage()

The free message function first clears any current values in the message then releases the memory for the message. The pointer to the message is invalid after this function called and should be discarded. Any message returned from a function call can be freed with bmcii_freeMessage().

bmcii_getMessageType()

The bmcii_getMessageType() function returns the current message type and class name for the specified message. A message can be one of the following types:

■ MSG_TYPE_NONE = 0,■ MSG_TYPE_NEW_EVENT■ MSG_TYPE_MOD_EVENT■ MSG_TYPE_NEW_DATA,■ MSG_TYPE_OVERWRITE_DATA■ MSG_TYPE_MOD_DATA■ MSG_TYPE_QUERY■ META_VAL_MSG_DELETE_EVEN■ META_VAL_MSG_DELETE_DATA

The BMC II C APIs return a copy of the class name. When you are finished with the string, release it with the bmcii_freeString() function.

NOTE The BMC II C APIs do not verify that the message type is appropriate to the contents of the message.

WARNING Changing the class name in the string does not change the class name in the message and may cause a buffer overrun.


bmcii_setMessageType()

bmcii_setMessageType()

The bmcii_setMessageType() function sets the message type and class name for a message.

The available message types are:

■ MSG_TYPE_NONE■ MSG_TYPE_NEW_EVENT■ MSG_TYPE_MOD_EVENT■ MSG_TYPE_NEW_DATA■ MSG_TYPE_OVERWRITE_DATA■ MSG_TYPE_MOD_DATA■ MSG_TYPE_QUERY■ META_VAL_MSG_DELETE_EVEN■ META_VAL_MSG_DELETE_DATA

For more information about message types, see “BMCII_MESSAGE_TYPE” on page 309.

Slot manipulation functionsSlot manipulation functions get and set regular slot values and free the resources used to store those values.

Table 28 lists the slot manipulation functions.

Table 28 Slot manipulation functions


bmcii_freeString() page 184

bmcii_freeStringList() page 184

bmcii_getSlotValue() page 184

bmcii_messageGetBaroc() page 184

bmcii_messageSetBaroc() page 185

bmcii_removeSlotValue() page 185

bmcii_removeSlotValueListItem() page 185

bmcii_setSlotValue() page 185

bmcii_setSlotValueList() page 186

bmcii_setSlotValuesbyArray() page 186


bmcii_freeString()

bmcii_freeString()

The bmcii_freeString() function frees resources allocated for a string returned when using functions such as bmcii_messageGetBaroc() or bmcii_getMessageType().

bmcii_freeStringList()

This function frees allocated resources used for a returned array of strings. Freeing the array in any other manner may cause memory leaks.

bmcii_getSlotValue()

The bmcii_getSlotValue() function copies the value of a slot.

The BMC II C APIs return a copy of the value(s) for the specified slot. If the slot is a regular slot (not a LIST_OF), the array contains a single string. If the slot is a LIST_OF it returns an array of strings with copies of the values. When the integration is finished using the results, call the bmcii_freeStringList() function to free the values’ resources.

bmcii_messageGetBaroc()

The bmcii_messageGetBaroc() function creates a BAROC-formatted message from the slots, allocates a string for it, and returns the new string. When the integration is finished with the BAROC string, call the bmcii_freeString() function to release allocated memory.

WARNING Changing the value of the string does not change the value in the message and may cause a buffer overrun.



bmcii_messageSetBaroc()

bmcii_messageSetBaroc()

The bmcii_messageSetBaroc() function parses a BAROC-formatted string and sets the values in a message.

All contents of the message are cleared before the parsing the BAROC string. The BAROC format is defined in the BMC Impact Solutions: Knowledge Base Development guide. The BAROC string is not changed by the function.

Figure 67 illustrates the structure of a BAROC message. A sample message is displayed after the figure.

bmcii_removeSlotValue()

The bmcii_removeSlotValue() function removes the slot from a message. Memory used to store the slot and its value is released.

bmcii_removeSlotValueListItem()

This function removes a single value from a slot value of type LIST_OF. If the index exceeds the number of values in the value an error is returned and no action is performed.

bmcii_setSlotValue()

The bmcii_setSlotValue() function adds a specified slot and value to a message. If the specified slot already exists, the current value is replaced by the value specified in the function.

All values are represented as strings. You must convert any boolean, short, int, long, or other data type to string type before using the value in the APIs.

Figure 67 BAROC message format

CLASSNAME;slot1_name=value;slot2_name=value;slot3_name=value;END

EXAMPLE EVENT;severity=WARNING;time=12:00;hostname=$COMPUTER_NAME;END


bmcii_setSlotValueList()

bmcii_setSlotValueList()

The bmcii_setSlotValueList() function sets the value of a slot of data type LIST_OF.

For the function call to succeed, you must specify the slot name and the exact location of the string. The index is zero based, meaning the first value is at index 0.

■ If the index is set to 0 then the bmcii_setSlotValueList() function inserts the value into the first position in the values list.

■ If the value of the index exceeds the number of values in the slot list, it adds the value at the end of the list.

■ If the index value is within the item count, the value is set at the specified index point, unless a value already exists at that point. The function places the value before the existing value. Otherwise, if the value already exists, it replaces the existing value with the new value at that index.

bmcii_setSlotValuesByArray()

The bmcii_setSlotValuesByArray() function is used to set multiple slots in one function call. The integration passes in an array of slot names and an array of slot values. The number and order of the slots and values must match.

Slot iteration functionsThe slot iteration functions enable the integration to get values from slots with a LIST_OF data type.

NOTE The BMC II C APIs do not verify whether a slot that you are adding is appropriate to the message’s event or data class. This examination is performed when the message arrives to the BMC Impact Manager instance.

NOTE The value may not necessarily be added. If a value exists at the index, it will be replaced instead of inserted. It might be replacing an existing LIST_OF item.


bmcii_getFirstSlotValue()

Table 29 lists the slot iteration functions.

bmcii_getFirstSlotValue()

The bmcii_getFirstSlotValue() and bmcii_getNextSlotValue() functions are used to step though the slots in a message. The order is not guaranteed.

The BMC II C APIs allocate a string and copy the slot name into the string. The BMC II C APIs then create an array of strings for the value. If the slot is a regular slot (not a LIST_OF), the array contains string. When the integration is finished using the results, call the bmcii_free string() function to free the slot name resources and the bmcii_freeStringList() function to free the values’ resources.

bmcii_getNextSlotValue()

The bmcii_getNextSlotValue() function gets the next slot name and value(s) in the message. If there are no more messages, it returns BMCII_NO_MORE to indicate that there are no more slots to examine. See bmcii_getFirstSlotValue() above for more information.

WARNING Changing the value of the string obtained by an iterator function does not change the value in the message and may cause a buffer overrun.

NOTE The current position of the iterator is stored in the message. In multithreaded applications, ensure that two iterator functions are not iterating through the same message at the same time.

Table 29 Slot iteration functions


bmcii_getFirstSlotValue() page 187

bmcii_getNextSlotValue() page 187


Metadata functions

Metadata functionsMetadata functions are used to get and set the contents of metaslots and to remove them from messages. Metaslots are discussed in “Metadata” on page 178.

Table 30 lists the metadata functions.

bmcii_getFirstMetaSlotValue()

The bmcii_getFirstMetaSlotValue() and bmcii_getNextMetaSlotValue() functions are used to iterate though the defined metaslots in a message and obtain metaslot values. The order is not guaranteed.

The BMC II C APIs allocate strings and makes copies of the name and the value in MetaSlotName and MetaValue. Release the strings using the bmcii_freeString() function.

Table 30 Metadata Functions


bmcii_getFirstMetaSlotValue() page 188

bmcii_getNextMetaSlotValue() page 189

bmcii_getMetaSlotValue() page 189

bmcii_removeMetaSlot() page 189

bmcii_setMetaSlotValue() page 190




bmcii_getNextMetaSlotValue

bmcii_getNextMetaSlotValue

The bmcii_getFirstMetaSlotValue() and bmcii_getNextMetaSlotValue() functions are used to step though the metaslots in a message and obtain metaslot values. The order is not guaranteed.

The BMC II C APIs allocate strings and makes copies of the name and the value in MetaSlotName and MetaSlotValue. Release the strings using the bmcii_freeString() function.

After all metaslots are stepped through, the BMC II C APIs return BMCII_NO_MORE.

bmcii_getMetaSlotValue

The bmcii_getMetaSlotValue() function obtains the value of the specified metaslot from a message.

The BMC II C APIs allocate strings and make copies of the name and the value in MetaSlotName and MetaSlotValue. Release the strings using the bmcii_freeString() function.

bmcii_removeMetaSlotValue()

The bmcii_removeMetaSlotValue() function removes the specified metaslot from a message. Memory used to store the slot and its value is released.





bmcii_setMetaSlotValue()

bmcii_setMetaSlotValue()

The bmcii_setMetaSlotValue() function adds a specified metaslot and value to a message. If the specified slot already exists, the current value is replaced by the value specified in the function.

All values are represented as strings. You must convert any boolean, short, int, long, or other data type to string type before using the value in the APIs.

An integration can insert its own metaslot into a message. The information will be kept with the message and not interfere with normal operations. The metaslot and its value are not sent when the message is sent.

Message information functionsMessage information functions obtain various types of information about a message.

Table 31 lists the message information functions.

bmcii_dumpMessage()

The dumpMessage() function takes a BMCII_MESSAGE and dumps a description of the contents into the trace file.

bmcii_getSlotCount()

The bmcii_getSlotCount() function returns the number of slots in the message.

The returned value does not include the class name, metaslots, or any other key words.

Table 31 Message Functions by Type


bmcii_dumpMessage() page 190

bmcii_getSlotCount() page 190


C h a p t e r 10
10 Sending and Receiving Messages and Replies

Sending and receiving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Sending messages and replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

bmcii_send() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Receiving messages and replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Client and server modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Receive functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Changes from previous release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194bmcii_getFromQueue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195bmcii_freeRecv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195bmcii_RecvAll (deprecated). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195bmcii_recvAndGetFromQueue (deprecated) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196bmcii_startRecvThread() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196bmcii_stopRecvThread(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Register state change functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197bmcii_registerStateChange() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197bmcii_unregisterStateChange() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200bmcii_registerAnswer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201bmcii_registerCancel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202bmcii_registerClientConnectDisconnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202bmcii_registerConnectStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202bmcii_registerError(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203bmcii_registerModify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203bmcii_registerNewMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Implementing bmcii_getFromQueue() and callbacks . . . . . . . . . . . . . . . . . . . . . . . . . 204Function call sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204


Sending and receiving

Sending and receivingSending and receiving messages and replies is the primary task of the BMC II C APIs.

To send messages, the BMC II C APIs use a single send function, bmcii_send().

To receive messages, you can register callback functions, call the bmcii_getFromQueue() function independent of any callbacks, or combine callback functions with the bmcii_getFromQueue() function. Using any of these methods, you can choose to receive messages in client, server, or client-server mode.

Sending messages and repliesThe BMC II C APIs use one function only for sending messages, bmcii_send(). For more information, see “bmcii_send()” on page 193.

When the BMC II C APIs try to send a message to a BMC Impact Manager instance, one of the following can occur:

■ If the connection to the BMC Impact Manager instance is up, the message is sent and a successful result is returned. A success does not mean that the BMC Impact Manager instance has accepted the message. If the BMC Impact Manager instance has accepted the message, it sends a reply to the integration acknowledging acceptance.

■ If the connection to the BMC Impact Manager instance is down, the BMC II C APIs buffer the message in memory and send the message when the connection is up.

When an message is sent, a message handle is returned. Use this message handle to associate the sent message with the reply from the BMC Impact Manager instance. A destination can send a reply success or a reply error.

Messages that are buffered in memory can be saved in a persistent buffer. This prevents data loss due to the integration crashing and makes the message contents available between sessions. For more information, see “Buffering” on page 166.

NOTE For the BMC II C APIs, messages include events, modifies, and dynamic data. Replies include acknowledgments, errors, and cancels. The BMC II C APIs also send and receive connection notifications and receive state changes.


bmcii_send()

bmcii_send()

The bmcii_send() function sends a message to a connected BMC Impact Manager instance. If the BMC Impact Manager instance is not available and buffering is turned on, the BMC II C APIs will buffer the event until the BMC Impact Manager instance is available. If the buffer is exceeded, an error is returned, and the message is not buffered.

The bmcii_send() function returns a message handle, which can be used to associate the sent message with the reply that will be sent from the receiving BMC Impact Manager instance.

If the integration has not set an ID for the message (mc_ueid ID for events, mc_udid ID for data objects), the BMC II C APIs create one. A copy of the ID is returned to the integration. The integration can use returned ID to send modifications. When the integration is finished using the ID, you can release it using the bmcii_freeString() function.

All messages must have a message type. New events or data objects must have class names. Modify messages for data objects must have a data handle.

Receiving messages and repliesThe bmcii_init3() function starts a background receive thread. The receive thread gets the messages and other requested information from all BMC Impact Manager connections simultaneously. The receive thread places the information in the general queue or the callback queue. The specified callback or the bmcii_getFromQueue() function retrieves the requested data from the appropriate queue. Figure 68 depicts this process.

Figure 68 Receive thread


Client and server modes

The receive thread stops when you call the bmcii_term() function.

Client and server modes

When running an integration in client mode, you can receive replies from connected BMC IM instances and other connected integration applications.

When running an integration in server mode, you can choose to receive

■ status change notifications■ connection notifications■ message modifications

And when running under client-server mode, you can receive all forms of messages, replies, requests, and notifications.

Receive functionsThe main receive functions are

■ bmcii_getFromQueue()■ bmcii_freeRecv()

Changes from previous release

The bmcii_RecvAll() and bmcii_recvAndGetFromQueue() functions have been deprecated but are still available. The bmcii_startRecvThread() and bmcii_stopRecvThread() functions are still available, but you call them in different contexts instead of using them to start and stop the main receiving thread.

NOTE The BMC II C APIs use POSIX thread libraries on UNIX and Linux platforms and Win32 thread libraries on Windows platforms.


bmcii_getFromQueue()

bmcii_getFromQueue()

The bmcii_getFromQueue() function retrieves messages, status changes, modifications, or connection notifications, all of which the receive thread process places in the internal queue. You can specify that this function retrieve items from a specific connection. The bmcii_getFromQueue() function retrieves messages, replies, status changes, and so forth that match the specified connection handle which it passes as an input argument.

When calling the bmcii_getFromQueue() function, you can choose not to be notified of acknowledgments, but you should always check for errors in the return. You can stop receiving acknowledgements by setting the DropAcks parameter in the IIDK.conf or your custom integrationName.conf file to True. The BMC II C APIs discard the acknowledgements before they are placed in the internal queue.

If 0 is passed as the value of the connection handle, then the function retrieves the first item that is available in the queue. If nothing is available, the function waits until one arrives or until the timeout period, expressed in milliseconds, expires. After the bmcii_getFromQueue() function completes the processing of the message, the BMC II C APIs must call the bmcii_freeRecv() function.

bmcii_freeRecv()

The bmcii_freeRecv() function frees resources that are allocated by the receive functions.

Call this function when the integration is finished using a structure returned from a receive function or a callback. You can free the following items using bmcii_freeRecv():

■ received messages■ bmcii_ReplySuccess■ bmcii_ReplyError■ bmcii_ReplyCancel■ bmcii_ConnectNotify

bmcii_RecvAll (deprecated)

If you have implemented this function in your code to receive message and replies, remove it. The receive thread now handles the messages and replies. In version 2.1 or later, this function sleeps for one-half of the time specified in its input parameter.


bmcii_recvAndGetFromQueue (deprecated)

bmcii_recvAndGetFromQueue (deprecated)

If you have implemented this function in your code to receive messages and replies, you should replace it with the bmcii_getFromQueue() function. In version 2.1 or later, the bmcii_recvAndGetFromQueue() function calls the bmcii_getFromQueue() function. It is included only to support backwards compatibility.

bmcii_startRecvThread()

Because the bmcii_init3() function automatically starts a background receive thread that runs continuously, you no longer have to use the bmcii_startRecvThread() function to start the thread to receive messages. However, you can use the bmcii_startRecvThread() function in conjunction with the bmcii_stopRecvThread() function to receive messages on an intermittent basis for testing or other purposes.

The bmcii_startRecvThread() function starts a background thread that receives messages and replies and accepts connection requests in a continuous loop.

The received information is placed in one of the internal queues. Retrieve it using the bmcii_getFromQueue() function or a callback. If a callback function has been registered for the message, notification, or reply it will be called immediately.

The thread started by this function is stopped by calling the bmcii_stopRecvThread() function, described in “bmcii_stopRecvThread()” on page 196.

bmcii_stopRecvThread()

The bmcii_stopRecvThread() function stops the receive thread, whether it was started by the bmcii_init3() function or the bmcii_startRecvThread() function. You can call this function to stop receiving new events, replies, connection requests, and so forth without disconnecting from a BMC IM instance or terminating a session.

NOTE This function is primarily used for backward compatibility.

NOTE

Yo

You do not have to call the bmcii_stopRecvThread() function. The bmcii_term() shuts down the receive thread when it is called.


Register state change functions

Register state change functionsYou can call a registration function to enable the integration to receive state change events from the specified cell. This function creates a data instance in the BMC SIM cell. This data instance registers your integration with the SIM cell and enables your integration to receive notifications from the cell. When a component changes state, the SIM cell connects to the registered integration and sends a state change notification.

You can also unregister your registration ID to stop receiving state change events.

bmcii_registerStateChange()

Use this function in an integration that is in server mode.

Call the bmcii_registerStateChange() function to register your integration to receive state change events.


When you call the bmcii_registerStateChange() function, you pass it the following arguments:

NOTE If your integration application exits without unregistering—bmcii_unregisterStateChange()—the registration ID or if it terminates unexpectedly, then register state change record remains on the cell. In this case, use the BMC Impact Explorer GUI to clean up the state change record.

bmcii_result bmcii_registerStateChange(BMCII_CNC cnc, BMCII_STR *szServerName, STATE_CHANGE_TYPE eType, BMCII_STR **szRegistrationID);


Workaround: multiple clients and state change events


If in your environment multiple clients are requesting state change events from the same SIM cell or cells, you must send your registration request by defining and sending a separate data message. Do not use the bmciiws_registerStateChange operation.

When formulating your message, you specify values for the following slots in the SIM_NOTIFICATION_REGISTRY class:

Table 32 Input arguments: bmcii_registerStateChange()


cnc unsigned long handle that references a connection to a BMC IM cell or to an integration. In this usage, it references a connection to a SIM cell.

szServerName a zero terminated string type that specifies the name of the integration application server that will be receiving the state change events. The value that you enter here is the same as the one you use in the bmcii_setupServer() function.

The name of the integration application server must be specified in the mcell.dir file of the cell you are connected to. You can declare the integration application server as a cell or as a gateway in the mcell.dir, but the most straightforward approach is to declare it as a cell.

eType specifies the type of state change event to be received. The choices are

■ COMPONENT_CHANGE = 1■ COMPONENT_DELETE = 2■ RELATIONSHIP_CHANGE = 4■ RELATIONSHIP_DELETE = 8■ SC_ALL = 15

You can use the conditional AND operator && to combine two types: for example

RELATIONSHIP_CHANGE && RELATIONSHIP_DELETE

szRegistrationID ID that is assigned to this registration request



Table 33 SIM_NOTIFICATION_REGISTRY message class: required slots

Slot Description

client_data only applies to version 7 or later of BMC Service Impact Manager. Specifies a unique name for this registration call.

clients denotes the value assigned to the WSCELL entry specifying the BMC II Web Services Server instance

requested_notifications indicates the type of service component state change that you want to receive. You can specify one or more of the following values:

■ COMPONENT_CHANGE■ COMPONENT_DELETE■ RELATIONSHIP_CHANGE■ RELATIONSHIP_DELETE

notification_mode indicates the notification mode

notifications_at_registration Boolean indicate that says whether a notification is sent upon registration

asset_filters a LIST_OF type that specifies the service components about which you want to receive state change events

//create a registration for state change events

/* * Create the data */::imapi::Event *event = new ::imapi::Event();event->NameValue_element = new ::imapi::NameValueArray(1);

event->NameValue_element->array[0] = new ::imapi::NameValue();event->NameValue_element->array[0]->name = "client_data";event->NameValue_element->array[0]->value = new ::imapi::Value();event->NameValue_element->array[0]->value->what = ::imapi::Value::tString_value;event->NameValue_element->array[0]->value->string_value = "example_register";event->NameValue_element->array[0]->value_type = ::imapi::DataType::STRING;

event->NameValue_element->array[1] = new ::imapi::NameValue();event->NameValue_element->array[1]->name = "clients";event->NameValue_element->array[1]->value = new ::imapi::Value();event->NameValue_element->array[1]->value->what = ::imapi::Value::tString_value;event->NameValue_element->array[1]->value->string_value = "[example_Server_name]";event->NameValue_element->array[1]->value_type = ::imapi::DataType::STRING;

//repeat the name-value definitions for each required slot


bmcii_unregisterStateChange()

bmcii_unregisterStateChange()

Call the bmcii_unregisterStateChange() function to remove the registration ID assigned to the registration request, effectively stopping your integration from receiving state change events.


When you call the bmcii_unregisterStateChange() function, you pass it the following arguments:

CallbacksCallback registration is accomplished by choosing the item that triggers a callback, such a new message, and by passing in the function to be called. Callback registrations are global to the integration and not specific per connection. Before the integration can access any BMC II C APIs’ functions, you must have registered for the appropriate callback functions.

The callback functions provide an alternate method for obtaining information from the integration.

You can use the same callback function in multiple registrations. In each registration, the callback function must distinguish among the different incoming items to process.

Table 35 lists the callback functions.

bmcii_result bmcii_unregisterStateChange (BMCII_CNC cnc, BMCII_STR **szRegistrationID);

Table 34 Input arguments: bmcii_unregisterStateChange()


cnc unsigned long handle that references a connection to a BMC IM cell or to an integration. In this usage, it references a connection to a SIM cell.

szRegistrationID ID that is assigned to this registration request

Figure 69 Callback Definition Structure

typedef int (*BMCII_CALLBACK_FUCNTION)(BMCII_CNC cnc, void *pResult, int iType);


bmcii_registerAnswer()

bmcii_registerAnswer()

The bmcii_registerAnswer() function registers a specified function to notify the integration of the arrival of successful replies. A reply is a response from a BMC Impact Manager instance to a message sent by the integration.

If the reply was for an event message that was accepted by the BMC Impact Manager instance, it will contain an event handle assigned by the BMC Impact Manager instance. If the event handle is 0, the BMC Impact Manager instance received the event, but has rejected it.

If the reply was for a data object message that was accepted by the BMC Impact Manager instance, it will contain a data handle assigned by the BMC Impact Manager instance. If the data handle is 0, the BMC Impact Manager instance received the data object, but has rejected it.

A bmcii_replySuccess structure is passed to the callback function for processing. The callback function is called in either of two circumstances:

■ when the Receive function is being processed and the reply is available■ immediately if the receive thread is enabled

NOTE An additional callback function, bmcii_retrieveQueryResultsCB(), is described on page 216. bmcii_retrieveQueryResultsCB() calls a function that retrieves query results.

Table 35 Callback functions


bmcii_registerAnswer() page 201

bmcii_registerCancel() page 202

bmcii_registerClientConnectDisconnect() page 202

bmcii_registerConnectStatus() page 202

bmcii_registerError() page 203

bmcii_registerModify() page 203

bmcii_registerNewMessage() page 204

NOTE Release the bmcii_replySuccess structure that is passed into the callback function by calling the bmcii_freeRecv() function.


bmcii_registerCancel()

bmcii_registerCancel()

The bmcii_registerCancel() function registers a specified function to notify the integration of the arrival of a reply cancellation notice. A cancellation notice is sent if the connection between the integration and the target BMC Impact Manager instance is broken or closed while the integration waits for a reply to a message it sent. A reply is a response from a BMC Impact Manager instance to a message sent by the integration.

The callback function is called when the bmcii_disconnect() function is called or if the connection is broken.

A bmcii_ReplyCancel structure is passed to the callback function for processing.

bmcii_registerClientConnectDisconnect()

The bmcii_registerClientConnectDisconnect() function registers a specified function as a callback function to notify the integration when a client connects to or disconnects from the integration (when it is operating as a server). The function specified in the bmcii_registerClientConnectDisconnect() function is called immediately when the connection attempt is successful.

bmcii_registerConnectStatus()

The bmcii_registerConnectStatus() function registers a specified function as a callback function to notify the integration of changes in the status of a connection initiated by the integration, using the bmcii_connect() function. If one of the receive function calls is in progress or if a receive thread is started, the function specified in bmcii_registerConnectStatus() is called immediately when the connection status changes.

NOTE Release the bmcii_ReplyCancel structure that is passed into the callback function by calling the bmcii_freeRecv() function.

NOTE Release the bmcii_ConnectNotify structure that is passed by calling the bmcii_freeRecv() function.


bmcii_registerError()

If the connection is broken, any messages that have been sent are buffered until the connection is restored (if buffering is on). For more information about buffering, see “Buffering” on page 166.

This function differs from the bmcii_connectionInfo() function. The bmcii_registerConnectStatus() function registers a callback function that notifies the integration when connection status changes. The bmcii_connectionInfo() function informs the integration of the connection status when the function is called. For more information, see “bmcii_connectionInfo()” on page 154.

bmcii_registerError()

The bmcii_registerError() function registers a specified function to notify the integration of the arrival of error replies. A reply is a response from a BMC Impact Manager instance to a message sent by the integration.

A bmcii_ReplyError structure, containing a list of reported errors, is passed to the callback function for processing.

bmcii_registerModify

The bmcii_registerModify() function registers a specified function as a callback function to notify the integration about incoming modify messages originating from connected BMC Impact Manager instances.

To receive modify messages, the integration must be in server mode.

NOTE Release the bmcii_ConnectNotify structure that is passed by calling the bmcii_freeRecv() function.

NOTE Release the bmcii_ReplyError structure that is passed by calling the bmcii_freeRecv() function.

NOTE Call the bmcii_freeRecv() function to release the modify message.


bmcii_registerNewMessage()

bmcii_registerNewMessage()

The bmcii_registerNewMessage function() registers a specified function as a callback function to process a new message that has been received from a BMC Impact Manager instance or other integration.

The new message is passed to the callback function for processing. The callback function is called immediately if a receive thread is running.

Implementing bmcii_getFromQueue() and callbacks

You determine which function or functions to use based on the following:

■ what your integration is meant to do■ whether you are using callbacks

You can use the bmcii_getFromQueue() function with or without callbacks. You can register a callback for each type of reply that the integration will receive, or you can register a callback to retrieve only a certain type of reply while a receive function retrieves all other replies.

The combinations of bmcii_getFromQueue() functions and callback functions and the order in which each function is called are shown in “Function call sequences” on page 204.

Function call sequences

The following lists detail the function call sequences when the integration is running under client and server modes.

NOTE Call the bmcii_freeRecv() function to release the message.

NOTE Register all callback functions that you want to use soon after the integration is started and before you begin to process messages.



Client mode with bmcii_getFromQueue()

1. bmcii_init3()

2. bmcii_connect()

3. bmcii_send()

4. bmcii_getFromQueue()

5. Repeat bmcii_send() and bmcii_getFromQueue() as needed.

6. bmcii_disconnect()

7. bmcii_term()

Client mode with callbacks

1. Register the callback or callbacks for the function(s) you want to call.

2. bmcii_init3()

3. bmcii_connect()

4. bmcii_send()

5. Repeat bmcii_send() as needed.


7. bmcii_term()

Client mode with bmcii_getFromQueue() and callbacks


2. bmcii_init3()

3. bmcii_connect()

4. bmcii_send()


6. Repeat bmcii_send() and bmcii_getFromQueue() as needed.




8. bmcii_term()

Server mode with bmcii_getFromQueue()

1. bmcii_init3()

2. bmcii_setupServer()

3. bmcii_startServer()


5. Repeat bmcii_getFromQueue() as needed.

6. bmcii_stopServer()

7. bmcii_term()

Server mode with callbacks


2. bmcii_init3()



5. Process incoming events.


7. bmcii_term()

Server mode with bmcii_getFromQueue() and callbacks


2. bmcii_init3()






6. Repeat bmcii_getFromQueue() as needed.


8. bmcii_term()


C h a p t e r 11
11 Queries

Managing queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Query characteristics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Query function call order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Query connection management functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213bmcii_closeQuery() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213bmcii_initQueryConnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214bmcii_termQueryConnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Query results functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214bmcii_freeQueryResults(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215bmcii_getQueryReply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215bmcii_retrieveQueryResults() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215bmcii_retrieveQueryResultsCB(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Query data helper functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216bmcii_queryData(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217bmcii_queryDataByHandles() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217bmcii_queryDataByMcudid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Query event helper functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217bmcii_queryEvents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218bmcii_queryEventsByCollector() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218bmcii_queryEventsByDate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219bmcii_queryEventsByHandles() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219bmcii_queryEventsByMcueid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Query service model component helper functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Querying across multiple cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221bmcii_queryComponentsByStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223bmcii_queryComponentsByCondition() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225bmcii_getComponentId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226bmcii_queryComponentEvents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Use case example of service model queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227bmcii_queryComponentStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228bmcii_queryComponent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230bmcii_queryModelImpact() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230bmcii_queryModelCause(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231bmcii_queryModelPossibleRootCauses() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232


Class definition queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233bmcii_queryClassDefinitions(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236bmcii_getClassDefQueryReply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237bmcii_getClassNode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238bmcii_getClassDefByName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239bmcii_getSlotDefInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240bmcii_freeQuerySlotsHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241bmcii_closeQueryClassDef() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Service component status and mode functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242bmcii_setManualStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243bmcii_setMaintenanceMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244


Managing queries

Managing queriesUse queries to

■ get copies of events and data objects from a BMC Impact Manager instance■ return component information about service model component instances that have

been published to one or multiple cells■ retrieve event, data, or service model class definitions from a specific BMC IM

instance

A query contains criteria that specify which events, data objects, or service model components are to be retrieved.

The query function is mode-independent. The integration can perform queries when running as a client, a server, or both.

Query characteristics

To perform a query, the integration must call the bmcii_initQueryConnect() function to establish a special query connection with the BMC Impact Manager instance that it is querying. A connection established using the bmcii_connect() function cannot be used for queries. Therefore:

■ To query a BMC Impact Manager instance, you must establish a query connection using the bmcii_initQueryConnect() function, even if the integration is already connected to the BMC Impact Manager instance using a connection established with the bmcii_connect() function.

■ You can establish a query connection with a BMC Impact Manager instance with which no bmcii_connect connection is currently established.

The query process has the following characteristics:

■ The integration must call the query functions in the correct order. This order is described in “Query function call order” on page 212. For code examples, see “Simple query project code” on page 110.

■ The bmcii_initQueryConnection() and bmcii_termQueryConnection() functions start and close the query connection, respectively.

■ You must open a query connection to the BMC Impact Manager instance that you want to query. You can open query connections to multiple BMC Impact Manager cells simultaneously.


Query function call order

■ Most query results are returned in the form of message lists (BMCII_MESSAGE_LIST array). Call the message and slot manipulation functions to retrieve the values from the message lists.

■ If you use the bmcii_retrieveQueryResults() function to retrieve query results, call the bmcii_freeQueryResults() function to free all events and data object resources.

■ If you use the bmcii_retrieveQueryResultsCB() function to retrieve query results, call the bmcii_freeRecv() function to release the messages passed to the callback function.

■ When all events or data specified in a query have been retrieved, end the query using the bmcii_closeQuery() function.

■ Guaranteed delivery does not apply to the query functions. If the query connection established by the bmcii_initQueryConnect() function is dropped, then you must reconnect and resend the query.

■ Your integration application is limited to a maximum number of 100 open outgoing connections per session to one or more BMC IM cells.

Query function call order

Perform query functions in the following order:

1. Call the bmcii_initQueryConnect() function to establish a query connection with a specific BMC Impact Manager instance.

2. Call the query functions required to perform the queries that you want—for example, bmcii_queryEventsByHandles() or bmcii_queryEventsByMcueid().

3. Call the bmcii_getQueryReply() function to receive the count of results for the query.

4. Call the bmcii_retrieveQueryResults() function to retrieve results you specify from within the received query results.

5. Call the bmcii_closeQuery() function to end the query.

NOTE The bmcii_getQueryReply() function has a timeout value. You may need to call the function more than once to receive the expected replies.


Query connection management functions

6. Call the message and slot manipulation functions to retrieve the values of the returned results.

7. Process the retrieved results as you require.

8. Call the bmcii_freeQueryResults() function to free resources used to store the retrieved query results.

9. Repeat Steps 2 through 8 to perform other queries.

10. Call the bmcii_termQueryConnect() function to close the query connection with the BMC Impact Manager instance.

Query connection management functionsThe query connection management functions initialize, open, and close the connection used to transmit queries from the integration to a BMC Impact Manager instance.

Table 36 lists query connection management functions.

bmcii_closeQuery()

The bmcii_closeQuery() function ends a query and frees resources in the BMC Impact Manager instance to which the query was directed. This function does not close the query connection.

Call this function after the integration has retrieved the results of a query. You can process the results after closing the query.

Table 36 Query connection management functions


bmcii_closeQuery() page 213

bmcii_initQueryConnect() page 214

bmcii_termQueryConnect() page 214


bmcii_initQueryConnect()

bmcii_initQueryConnect()

The bmcii_initQueryConnect() function establishes a connection to the specified BMC Impact Manager instance. This connection is used to transmit queries from the integration to the BMC Impact Manager instance and replies from the BMC Impact Manager instance to the integration.

The connection is closed by calling the bmcii_termQueryConnection() function. For more information, see “bmcii_termQueryConnect()” on page 214.

When a query connection has been established, you can send a query to the connected BMC Impact Manager instance. When that query is completed and closed, you can send another query.

If the bmcii_initQueryConnect() function fails because the destination BMC IM instance is not available, the integration must continue to call the function until it succeeds. If the connection is dropped at any time during query operations, then the integration must reconnect and resend queries.

An integration can maintain open connections to several BMC Impact Manager instances simultaneously.

The integration cannot send queries using a connection established with the bmcii_connect function. However, you can maintain an open bmcii_connect connection and an open bmcii_initQueryConnect query connection simultaneously to a BMC Impact Manager instance.

bmcii_termQueryConnect()

The bmcii_termQueryConnect() function closes a connection established by calling the bmcii_initQueryConnection() function. For more information, see “bmcii_initQueryConnect()” on page 214.

Query results functionsThe query results functions get the number of query results returned from the query and retrieve the information that is returned.

Table 37 lists the functions used to return query results.


bmcii_freeQueryResults()

bmcii_freeQueryResults()

The bmcii_freeQueryResults() function frees the resources used to process and store retrieved events and data.

bmcii_getQueryReply()

The bmcii_getQueryReply() function examines the BMC Impact Manager instance’s reply to a query and determines

■ whether the query was successful■ the number of results returned

bmcii_retrieveQueryResults()

The bmcii_retrieveQueryResults() function retrieves some or all of the results that are returned for a query. The function passes the result handle, a timeout value, and the first through last results in the group of results that you want to retrieve to the BMC II Developer’s Kit. The message results are returned as a BMCII_MESSAGE_LIST array. The results begin with the index value 0 and continue through the specified ResultCount value.

Because there may be a great many results returned for a query, the bmcii_retrieveQueryResults() function has a timeout feature. You can use this timeout feature to override the minimum timeout period specified by the MinQueryTimeout configuration parameter (see Table 10 on page 49). If only a portion of the results are retrieved when the function times out, call the function again and specify that it retrieve the remaining results.

When the integration is finished with the returned results, call the bmcii_freeQueryResults() function to free resources.

Table 37 Query Results Functions


bmcii_freeQueryResults() page 215

bmcii_getQueryReply() page 215

bmcii_retrieveQueryResults() page 215

bmcii_retrieveQueryResultsCB() page 216


bmcii_retrieveQueryResultsCB()

If you prefer to work with callbacks, use the bmcii_retrieveQueryResultsCB() function to retrieve the query results, instead of the bmcii_retrieveQueryResults() function.

bmcii_retrieveQueryResultsCB()

The bmcii_retrieveQueryResultsCB() function calls a function to retrieve some or all of the results that are returned for a query.

For each message returned from the query, the designated callback function must be called.

When the integration is finished with each message, call the bmcii_freeRecv() function to release resources.

For more information about callbacks, see “Receiving messages and replies” on page 193.

Query data helper functionsThe query data helper functions are the functions used to specify the query criteria for querying data objects.

Table 39 lists the query data helper functions.

NOTE The supplemental query data helper functions(_ByHandles, _ByMcudid) are provided as convenience functions. If they do not return the necessary results, use the bmcii_queryData() or bmcii_queryEvents() function.

Table 38 Query Data Helper Functions


bmcii_queryData() page 217

bmcii_queryDataByHandles() page 217

bmcii_queryDataByMcudid() page 217


bmcii_queryData()

bmcii_queryData()

The bmcii_queryData() function accepts a query string to query for data and sends that string to the target BMC Impact Manager instance. The string contains query criteria, such as the class, slots, and slot order for which you want to query.

Use this function to create very specific data queries.

At this time, only data select queries are allowed. Any other type of query will be rejected. For more information about query formats, see BMC Impact Solutions: Knowledge Base Development.

bmcii_queryDataByHandles()

The bmcii_queryDataByHandles() function creates and sends a query to select data objects with data_handles in a specified range.

bmcii_queryDataByMcudid()

The bmcii_queryDataByMcudid() function creates and sends a query to select a single data object with the specified mc_udid ID.

For more information about the mc_udid ID, see “Message identification” on page 91.

Query event helper functionsThe query event helper functions are the functions used to specify the query criteria for querying events.

Table 39 lists the query event helper functions.

NOTE The query event helper functions are provided as convenience functions. If they do not return the necessary results, use the bmcii_queryData() or bmcii_queryEvents() function.


bmcii_queryEvents()

See also “bmcii_queryComponentEvents()” on page 226 for querying events associated with service model components.

bmcii_queryEvents()

The bmcii_queryEvents() function accepts a query string to query for events and sends that string to the target BMC Impact Manager instance. The string contains query criteria, such as the class, slots, and slot order for which you want to query.

Use this function to create very specific events queries.

At this time, select is the only type of query that is allowed. Any other query type will be rejected. For more information about query formats, see BMC Impact Solutions: Knowledge Base Development.

bmcii_queryEventsByCollector()

The bmcii_queryEventsByCollector() function selects all events that are stored in the specified collector. A collector is an event grouping whose content is defined by a BMC Impact Manager collector rule. Events are associated with a collector by a rule in a collector file.

Collector names are specified using the syntax in Figure 70. The collector specification must always end with a plus sign (+). Specify the collector name by either "name.subname.subname+" or with the collector OID, such as "1.2.1". A wild card can be used for dynamic collectors, as in "By location.*.Adaptors+".

Table 39 Query Event Helper Functions


bmcii_queryEvents() page 218

bmcii_queryEventsByCollector() page 218

bmcii_queryEventsByDate() page 219

bmcii_queryEventsByHandles() page 219

bmcii_queryEventsByMcueid() page 219

Figure 70 Collector Name Syntax

collector_name.subcollector_name | *.subcollector_name | *. .....+


bmcii_queryEventsByDate()

Example

Figure 71 Collector Query Example

To query the CPU-1 collector shown in, specify the collector using the following statement: 'By Location'.Unknown.qantpv13.PATROL.CPU+

bmcii_queryEventsByDate()

The bmcii_queryEventsByDate() function selects events that were sent on a day that falls within the specified range. Dates are expressed using the time_t time format. time_t is the number of seconds since January 1, 1970, represented in Base-36.

bmcii_queryEventsByHandles()

The bmcii_queryEventsByHandles() function creates and sends a query to select events with event handles in a specified range.

bmcii_queryEventsByMcueid()

The bmcii_queryEventsByMcueid() function creates and sends a query to select a single event with the specified mc_ueid ID.

For more information about the mc_ueid ID, see “Message identification” on page 91.

NOTE In the example, the By Location collector name is enclosed in single quotes (‘ ‘) because the collector name includes a space. Do not enclose collector names without spaces in quotes.


Query service model component helper functions

Query service model component helper functions

Use these functions to retrieve information about service model components that have been published to one or more SIM cells. These queries return service model information that is stored in the SIM cell (in memory and in files under the $MCELL_HOME/log/cellName or %MCELL_HOME%\log\cellName directory).

Each query function passes a handle to the active query connection, and each query function returns a handle to the result set.

With the exception of the bmcii_queryComponentEvents() function, each query function returns by default one or more slots. Table 40 on page 220 lists the query functions and their default slots that they return.

NOTE These queries return information about service model components. They do not return information about relationships between or among these components.

Table 40 Service model query functions and default slot

Service model query function(s) Default slots that are returned

bmcii_queryComponentsByStatus()bmcii_queryComponentsByCondition()

mc_udidstatusCLASSnameHomeCellcomponent_scopeHomeCell

bmcii_queryComponentStatus() mc_udidstatusself_statuscomputed_statusimpact_statusmanual_status

bmcii_queryComponent() all the slots for the specified component

bmcii_queryModelImpact()bmcii_queryModelCause()bmcii_queryModelPossibleRootCauses()

mc_udidstatusNameHomeCellshadow_cells

bmcii_getComponentId() mc_udid

bmcii_queryComponentEvents() n/a


Querying across multiple cells

Using the szSlots parameter, you can specify that these functions return an additional slot or slots aside from the default slots.


The following query functions can retrieve component information from service models that have been published across multiple SIM cells:

■ bmcii_queryModelImpact(), page 230■ bmcii_queryModelCause(), page 231■ bmcii_queryModelPossibleRootCauses(), page 232■ bmcii_queryComponentsByStatus(), page 223■ bmcii_queryComponentsByCondition(), page 225

As a best practice, you should enter all SIM cells that you intend to query in the mcell.dir file of the integration (see Table 5 on page 37 for a description of the mcell.dir file).

Each of these queries requires that you specify the initial SIM cell to which you wish to connect. Specify the cell in the bmcii_initQueryConnect() function. (See “bmcii_initQueryConnect()” on page 214 for more information.)

The bmcii_queryModelImpact(), bmcii_queryModelCause(), and bmcii_queryModelPossibleRootCauses() functions handle the queries somewhat differently from the bmcii_queryComponentsByStatus() and bmcii_queryComponentsByCondition() functions.

For the bmcii_queryModelImpact(), bmcii_queryModelCause(), and bmcii_queryModelPossibleRootCauses() functions, you also specify the component ID from which the query will start. The component ID must reside on the specified SIM cell; otherwise, the query does not return any results.

The functions bmcii_queryModelImpact(), bmcii_queryModelCause(), and bmcii_queryModelPossibleRootCauses() functions perform their queries as follows. After the query connects with the SIM cell and locates the component ID, it starts to search for components that are impacts, causes, or possible root causes. When it encounters a shadow component that points to another component of the model on a different cell, the query recursively searches the new cell, beginning with the shadowed component. If it encounters another shadow component that points to a

NOTE The HomeCell slot contains the name of the cell or cells where the returned component or components reside.



third cell, the query recursively searches the third cell, again beginning with its shadow component. It continues the recursive search until it has completed the service model. The query returns the components that match the criteria (impacts, causes, or possible root causes).

The bmcii_queryComponentsByStatus() and bmcii_queryComponentsByCondition() functions do not require a component ID. They retrieve components by matching status (for example, BLACKOUT, WARNING, IMPACTED, and so forth) or by matching condition (as specified by the Master Rule Language or MRL clauses). Because they do not require a component ID, which is unique to a particular service model, these queries can traverse multiple service models that reside on the initial SIM cell.

The bmcii_queryComponentsByStatus() and bmcii_queryComponentsByCondition() functions complete the query as follows. They start the query with the initial SIM cell specified in the bmcii_initQueryConnect() function. They search the components of the service model or models that reside on the initial SIM cell. If any of the models has shadow components pointing to other cells, then the queries continue to traverse the models that extend to other cells, beginning with the respective shadowed components.

The bmcii_queryComponentsByStatus() and bmcii_queryComponentsByCondition() functions cannot query a separate service model on a SIM cell other than the one specified in the bmcii_initQueryConnect() function. For example, if in your environment you have two SIM cells, each with its own service model: that is, cell A has service model 1 and cell B has service model 2. In this case, the functions can search only the service model on the cell specified in the bmcii_initQueryConnect() function. They cannot extend the search to the separate service model on the other cell.

Each query returns all matching components in a single return. The queries do not include shadow components in the returned components.

You can experience performance issues when querying a large number of components that have been published across multiple cells.

NOTE It is a best practice to include all SIM cells in the mcell.dir of your integration. However, if the SIM cell containing the specified component ID is not in the integration’s mcell.dir, the query nonetheless still tries to connect to the cell using the encryption key value used in the initial connection. If the encryption value in the mcell.dir of the target cell matches that of the integration’s mcell.dir, then the connection is made.


bmcii_queryComponentsByStatus()


The bmcii_queryComponentsByStatus() function retrieves an array of service model components that

■ have MC_SM_COMPONENT_STATUS values which match, are less than or equal to, or are greater than or equal to the specified status parameters; and

■ belong to the specified base class or subclass

If the service model extends to multiple cells, this query can use the model’s shadow components to traverse the model across multiple cells.


The bmcii_queryComponentsByStatus() function takes MC_SM_COMPONENT_STATUS string values as input parameters szLowest and szHighest to determine the range of values to retrieve. MC_SM_COMPONENT_STATUS is a enumeration declaration that assigns the following zero terminated string (sz) type values as service model component statuses. Each status is assigned a numerical weight.

When entering your input parameter values, specify the case-sensitive literal string value, such as BLACKOUT, UNKNOWN, OK, and so forth. Do not enter the assigned numerical weight as an input parameter.

bmcii_result bmcii_queryComponentsByStatus(BMCII_QUERYHANDLE QueryHandle, BMCII_STR *szLowestStatus, BMCII_STR *szHighestStatus, BMCII_STR *szBaseClass, BMCII_BOOL bSubclasses, BMCII_STR *szSlots, BMCII_RESULT_HANDLE *ResultHandle);

Table 41 MC_SM_COMPONENT_STATUS values

Assigned numerical weight Service model component status (string type)

1 NONE

10 BLACKOUT

20 UNKNOWN

30 OK

40 INFO

50 WARNING

60 MINOR

70 IMPACTED

80 UNAVAILABLE



When you call the bmcii_queryComponentsByStatus() function, you pass it the following arguments:

It returns a result handle that is assigned to the set of status, class, and slot values that you have retrieved.

Table 42 Input arguments:bmcii_queryComponentsByStatus()


QueryHandle the temporary integer assigned to the active query connection opened by the bmcii_initQueryConnect() function

szLowestStatus a zero terminated string type value that indicates the lowest MC_SM_COMPONENT_STATUS value to be selected

If you enter only a value for the szLowestStatus, the call selects statuses that are equal to or greater than the lowest status.

szHighestStatus a zero terminated string type value that indicates the highest MC_SM_COMPONENT_STATUS value to be selected

If you enter only a value for the szHighestStatus, the call selects statuses that are equal to or less than the indicated highest value.

If you specify a range by entering values for both szLowestStatus and szHighestStatus, then the call selects status values that are equal to or greater than the lowest status and equal to or less than the highest status.

For example, if you specify that szLowestStatus is equal to UNKNOWN and szHighestStatus is equal to MINOR, then the call selects components with statuses UNKNOWN, OK, INFO, WARNING, and MINOR.

szBaseClase a zero terminated string type that indicates the base class to be selected. Its default is BMC_BaseElement.

bSubclasses a Boolean indicator that, when set equal to true, selects subclasses of the designated base class. If bSubclasses is set equal to false, then the selection is restricted to the base class.

szSlots a zero terminated string type that indicates the additional slot or slots for which the query will return values. If left empty, the query returns values for the slots mc_udid, status, CLASS, Name, HomeCell, component_scope, and HomeCell.


bmcii_queryComponentsByCondition()

bmcii_queryComponentsByCondition()

The bmcii_queryComponentsByCondition() function retrieves an array of service model components that match the special Master Rule Language (MRL) conditions. These conditions follow the syntax and conventions of the MRL where-clause selection criteria. The criteria are a logical combination of expressions that define the slots associated with the component.



An example of a value containing the where-clause selection criteria for the *szConditions parameter is shown in the following figure:

When you call the bmcii_queryComponentsByCondition() function, you pass it the following arguments:

NOTE See BMC Impact Solutions: Knowledge Base Development for more information about the Master Rule Language and the where-clause selection criteria.

bmcii_result bmcii_queryComponentsByCondition(BMCII_QUERYHANDLE QueryHandle, BMCII_STR *szConditions, BMCII_STR *szSlots, BMCII_RESULT_HANDLE *ResultHandle);

“status: >= MINOR AND (Department: == ‘Human Resource’ OR Department:==Accounting)”

Table 43 Input arguments: bmcii_queryComponentsByCondition() (part 1 of 2)




bmcii_getComponentId()

It returns a result handle that is assigned to the set of where-clause selection criteria and slot values that you have retrieved.

bmcii_getComponentId()

The bmcii_getComponentId function() retrieves the universal data ID (mc_udid) from the specified message that the bmcii_retrieveQueryResults() function returns.

Its declaration is as follows:

As an input parameter, this function passes a pointer (pMessage) to the BMCII_MESSAGE structure, which the bmcii_retrieveQueryResults() function returns. The bmcii_retrieveQueryResults() function returns the message results as a BMCII_MESSAGE_LIST array. Each BMCII_MESSAGE in this array contains slots for a component. The bmcii_getComponentId() returns the szCompID, which is the mc_udid of the specified component.

bmcii_queryComponentEvents()

Call the bmcii_queryComponentEvents() function to return direct and impact events associated with a specific component. You have the option of requesting to retrieve impact events only.


szConditions a zero terminated string type value that specifies the selection criteria in a where clause following Master Rule Language syntax and conventions.

Note: MRL syntax is case sensitive. Refer to BMC Impact Solutions: Knowledge Base Development for guidelines on using MRL.

szSlots a zero terminated string type that indicates the additional slot or slots for which the query will return values. If left empty, the query returns values for the slots mc_udid, status, CLASS, Name, HomeCell, component_scope, and HomeCell.

bmcii_result bmcii_getComponentId(BMCII_MESSAGE pMessage, BMCII_STR *szCompID);

Table 43 Input arguments: bmcii_queryComponentsByCondition() (part 2 of 2)



Use case example of service model queries

When you call the bmcii_queryComponentEvents() function, you pass it the following arguments:

It returns a result handle that is assigned to the set of events that you have retrieved.

Use case example of service model queries

This section provides a use case example of calling the service model query functions. Though you can call the service model query functions in any order, you must have a component ID before calling any of the following functions:

■ bmcii_queryComponentStatus()■ bmcii_queryComponent()■ bmcii_queryModelImpact()■ bmcii_queryModelCause()■ bmcii_queryModelPossibleRootCauses()

Call the bmcii_queryComponentsByStatus() or bmcii_queryComponentsByCondition() function to retrieve component data information. Then call the bmcii_getComponentID() function to retrieve the component ID, which you use as an input parameter in the all of the listed functions.

You can also obtain a component ID by accessing the Class Manager Console or the Service Model Editor to retrieve the ID of a published component.

bmcii_result bmcii_queryComponentEvents(BMCII_QUERYHANDLE QueryHandle, BMCII_STR *szComponId, BMCII_BOOL bOnlyImpacted, BMCII_RESULT_HANDLE *pResultHandle);

Table 44 Input arguments: bmcii_queryComponentsByEvents()



szCompId a zero terminated string type that contains the universal data ID (mc_udid) of the component object. Retrieve the szCompID by calling the bmcii_getComponentId() function.

bOnlyImpacted Boolean indicator that, if set to true, restricts the returned objects to impact events only. Otherwise, you retrieve both direct and impact events.


bmcii_queryComponentStatus()

The bmcii_queryComponentStatus() function returns a computed status from a specific component. The bmcii_queryComponent() function returns complete component information for a specific component.

The following functions traverse the class hierarchy of the service model structure to find impacts (consumers), causes (providers), and the possible root cause of a specific component’s status.

■ bmcii_queryModelImpact()■ bmcii_queryModelCause()■ bmcii_queryModelPossibleRootCauses()

Figure 72 on page 228 illustrates a use case example of using the service model query functions. You can call the query functions in any order.

Figure 72 Function call example: service model queries


The bmcii_queryComponentStatus() function retrieves a component’s status, as defined by its computed component status: status, self_status, computed_status, impact_status, and manual_status.



Table 45 on page 229 summarizes these computed statuses. See the BMC Impact Solutions: Administration guide for a more complete description of the component statuses.


When you call the bmcii_queryComponentStatus() function, you pass it the following arguments:

Table 45 Computed component statuses

Computed status Description

status main status of the component, which is equal to its computed_status unless the manual_status is defined

self_status status computed from the severities of direct events associated with the component

computed_status status of the component as computed from its self_status value and from its impact_status value, both of which assessing the impact of direct events and propagated statuses. The two status values are consolidated by a function, which generates a computed_status.

impact_status status values propagated by inbound relationships

manual_status user-determined status of the component, which overrides the main status

bmcii_result bmcii_queryComponentStatus(BMCII_QUERYHANDLE QueryHandle, BMCII_STR *szCompID, BMCII_RESULT_HANDLE *ResultHandle);

Table 46 Input arguments: bmcii_queryComponentStatus()



szCompID a zero terminated string type that contains the universal data ID (mc_udid) of the component object. Retrieve the szCompID by calling the bmcii_getComponentId() function.


bmcii_queryComponent()

It returns a result handle that is assigned to the computed status value or values that you have retrieved. The default slots that it returns are

■ mc_udid

■ status

■ self_status

■ computed_status

■ impact_status

■ manual_status

bmcii_queryComponent()

The bmcii_queryComponent() function retrieves the component data attributes of a specified component object.


When you call the bmcii_queryComponent() function, you pass it the following arguments:

It returns all slot definitions for this component and a result handle that is assigned to the complete set of component data information that you have retrieved.

bmcii_queryModelImpact()

The bmcii_queryModelImpact() function retrieves possible consumer components of the specified component. Consumer components are the components that can receive the impacts of the specified component.

bmcii_result bmcii_queryComponent(BMCII_QUERYHANDLE QueryHandle, BMCII_STR *szCompID, BMCII_RESULT_HANDLE *ResultHandle);

Table 47 Input arguments: bmcii_queryComponent()





bmcii_queryModelCause()



When you call the bmcii_queryModelImpact() function, you pass it the following arguments:

It returns a result handle that is assigned to the component ID and slot values that are returned.

bmcii_queryModelCause()

The bmcii_queryModelCause() function retrieves possible provider components of the specified component. These are the components that may be the cause of the specified component’s status.



bmcii_result bmcii_queryModelImpact(BMCII_QUERYHANDLE QueryHandle, BMCII_STR *szCompID, BMCII_STR *szSlots, BMCII_RESULT_HANDLE *ResultHandle);

Table 48 Input arguments: bmcii_queryModelImpact()




szSlots a zero terminated string type that indicates the additional slot or slots for which the query will return values. If left empty, the query returns values for the slots mc_udid, status, Name, HomeCell, and shadow_cells.

bmcii_result bmcii_queryModelCause(BMCII_QUERYHANDLE QueryHandle, BMCII_STR *szCompID, BMCII_STR *szSlots, BMCII_RESULT_HANDLE *ResultHandle);


bmcii_queryModelPossibleRootCauses()

When you call the bmcii_queryModelCause() function, you pass it the following arguments:

It returns a result handle that is assigned to the component ID and slot values that are returned.

bmcii_queryModelPossibleRootCauses()

Using a Possible input parameter, the bmcii_queryModelPossibleRootCauses() function retrieves a component or components that have either an immediate, direct relationship with the specified component or that have statuses which were propagated to the component.



When you call the bmcii_queryModelPossibleRootCauses() function, you pass it the following arguments:

Table 49 Input arguments: bmcii_queryModelCause()





bmcii_result bmcii_queryModelPossibleRootCauses(BMCII_QUERYHANDLE QueryHandle, BMCII_STR *szCompID, BMCII_STR *szSlots, BMCII_BOOL bPossible, BMCII_RESULT_HANDLE *ResultHandle);


Class definition queries

It returns a result handle that is assigned to the component ID and slot values that are returned as possible root cause components.

Class definition queriesUsing a series of recursive class definition query functions, you can query the classes that are loaded in the KB of an BMC IM cell. These queries retrieve static data, class definitions that are contained within the BMC IM cell’s directories. (To query service model components, see “Query service model component helper functions” on page 220.)

These queries retrieve the class definition information stored in the BAROC files under the $MCELL_HOME/etc/cellName/kb/classes or the %MCELL_HOME%\etc\cellName\kb\classes directory.

Table 50 Input arguments: bmcii_queryModelPossibleRootCauses()





bPossible Boolean indicator that traverses the provider components of the specified component. If set equal to True, it returns:

Possible Related Problems: restricts the search to components with immediate, direct relationships to the specified component.

If set equal to False, it returns:

Causal Components: extends the search beyond the immediate, direct relationships to include components whose statuses were propagated to the specified component to cause the impact.

See also the BMC Impact Explorer GUI, specifically the Causes tab in the Service Component detail pane.



You can choose from among a range of queries. You can retrieve the entire class hierarchy, including subclasses and slot definitions for each class. You can retrieve only event, data, or service model (SM) classes. Or you can retrieve specified slot definitions of a single, selected class.

Table 51 identifies the main query functions that you call when retrieving class and slot definitions from a cell.

Figure 73 on page 235 depicts the sequence in which you call these query functions.

NOTE You can use the BMC IM CLI command mclassinfo to retrieve class and slot information from a BMC IM cell. See the BMC Impact Solutions: Administration guide for more information. You can also use the Class Manager Console to view classes and definitions in the BMC Atrium Configuration Management Database.

Table 51 Main class definition queries

Query function General description

bmcii_queryClassDefinitions() sends a query to retrieve class definitions and respective subclasses of the EVENT, DATA, or SM class

bmcii_getClassDefQueryReply() returns the results of the bmcii_queryClassDefinitions() function and builds an internal tree structure with a pointer to the top-level class

bmcii_getClassNode() using a class definition handle, retrieves definition data (number of slots, subclasses) of a specified class

bmcii_getClassDefByName() using a result handle that is assigned to a set of class definitions, retrieves a class definition and slot information for a specified class

bmcii_getSlotDefInfo() using a slot definition handle, retrieves detailed information about a specific slot: slot name, slot type, slot representation type, and so forth

bmcii_freeQuerySlotsHandle() releases the memory space occupied by the SlotsHandle pointer which the bmcii_retrieveClassNode() function returns

bmcii_closeQueryClassDef() removes the cached class definitions and releases all resources being accessed by the retrieval functions



Figure 73 Call sequence: class definition queries

Call the bmcii_initQueryConnect() function first to establish the query connection with the specified BMC IM cell. Next, call the bmcii_queryClassDefinitions() and bmcii_getClassDefQueryReply() functions to

■ retrieve class definitions and subclasses of the specified class type: EVENT or DATA.

■ get the results of the bmcii_queryClassDefinitions() function and to build an internal tree structure

Then you can call the bmcii_getClassNode() function recursively to walk through the class tree structure until you locate a specified class. After retrieving the class information, you can recursively call the bmcii_getSlotDefInfo() function to obtain detailed information about specific slots contained in the class definition.

Alternatively, you can call the bmcii_getClassDefByName() function to get the specified class and slot definition data directly, without walking through the tree structure. After retrieving the class and slot information, you can recursively call the bmcii_getSlotDefInfo() function.


bmcii_queryClassDefinitions()

Use the bmcii_freeQuerySlotsHandle() function to release the memory resources used by the slots handle pointer retrieved by the bmcii_getClassNode() function and used by the bmcii_getSlotDefInfo() function. Call the bmcii_freeQuerySlotsHandle() function when you no longer need the slots handle.

Finally, call bmcii_closeQueryClassDef() function to release all resources and then call bmcii_termQueryConnect() to end the query connection.

bmcii_queryClassDefinitions()

The bmcii_queryClassDefinitions() function sends the initial query that retrieves the class definition (and subclasses) of the specified EVENT or DATA class that is already loaded in the BMC Impact Manager instance. In effect, the bmcii_queryClassDefinitions() function retrieves the class hierarchy of the specified class.


When you call the bmcii_queryClassDefinitions() function, you pass it the following arguments:

NOTE You can call the bmcii_getClassNode() function recursively. Within the bmcii_getClassNode() function, you can call the following functions repeatedly:

■ bmcii_getClassDefByName() ■ bmcii_getSlotDefInfo() ■ bmcii_freeQuerySlotsHandle()

bmcii_result bmcii_queryClassDefinitions(BMCII_QUERYHANDLE QueryHandle, bmcii_ClassDefQueryMode queryMode, *baseClass, BMCII_CLASSDEF_RESULT *ResultHandle);




bmcii_getClassDefQueryReply()

The type definition for bmcii_ClassDefQueryMode is as follows:

It returns a result handle that is assigned to the set of class definitions that you have retrieved. This result handle serves as an input argument to the next function in the sequence, bmcii_getClassDefQueryReply(), and to the bmcii_getClassDefByName() function.

bmcii_getClassDefQueryReply()

The bmcii_getClassDefQueryReply() function checks whether the BMC IM instance has processed the initial query—bmcii_queryClassDefinitions()—and has returned the results. If the initial query has returned the results, then the bmcii_getClassDefQueryReply() function parses the results and builds the internal tree structure for the class and slot definitions. It returns a handle that points to the top class of the tree structure.


When you call the bmcii_getClassDefQueryReply() function, you pass it the following arguments:

queryMode the value returned by an internal call to the bmcii_ClassDefQueryMode enumeration data type. This value indicates which set of class definitions and respective subclasses are being queried: BMCII_EVENT_CLASSES or BMCII_DATA_CLASSES.

baseClass a pointer to the base class at which the query starts. If you specify NULL, the query returns the top class specified by the bmcii_ClassDefQueryMode: CORE_DATA or CORE_EVENT.

typedef enum bmcii_ClassDefQueryMode{ BMCII_EVENT_CLASSES, /* EVENT and its subclasses*/ BMCII_DATA_CLASSES, /* DATA and its subclasses*/} bmcii_ClassDefQueryMode;

bmcii_result bmcii_getClassDefQueryReply(BMCII_CLASSDEF_RESULT ResultHandle, unsigned long ulTimeout, CLASS_DEF_HANDLE *ClassDefHandle);



bmcii_getClassNode()

The bmcii_getClassDefQueryReply() function returns a pointer to the class definition handle (*ClassDefHandle). The class definition handle specifies the top level of the class definition tree. The class definition tree looks similar to the following excerpt taken from the event class structure:

Class: CORE_EVENT Class: EVENT Class: MC_CELL_EVENT Class: MC_CELL_PARSE_ERROR Class: MC_CELL_UNDEFINED_CLASS Class: MC_CELL_PROCESS_ERROR Class: MC_UPDATE_EVENT Class: MC_SMC_ROOT Class: MC_SMC_EVENT Class: MC_SM_SHADOW_REQUEST Class: MC_SM_SHADOW_HIP_REPORT Class: MC_SM_SHADOW_REQUEST_ERROR Class: MC_SM_SHADOW_UPDATE Class: MC_SM_SHADOW_DELETE Class: SMC_MAINTENANCE

You can pass the class definition handle to other functions. Using the class definition handle, you can call a series of recursive query functions to retrieve all the class definitions through the bmcii_getClassNode() function. Or you can request information for a selected class by calling the bmcii_getClassDefByName() function.

bmcii_getClassNode()

The bmcii_getClassNode() function retrieves detailed information about a selected class from the class tree hierarchy the bmcii_getClassDefQueryReply() function returns. You can call the bmcii_getClassNode() function recursively to walk through the nodes in the class tree. Its declaration is as follows:


ResultHandle the temporary integer assigned to the result set that the bmcii_initQueryClassDefinitions() function returns

ulTimeout the timeout period (unsigned, long) in milliseconds. This is the maximum time that the user wants to wait before receiving a reply.

bmcii_result bmcii_getClassNode(CLASS_DEF_HANDLE ClassDefHandle, unsigned long index, BMCII_STR **psClassName, int *iChildCount, CLASS_DEF_HANDLE *ChildClasses, int *iSlotCount, SLOT_DEFS_HANDLE *SlotsHandle);


bmcii_getClassDefByName()

When you call the bmcii_getClassNode() function, you pass it the following arguments:

The bmcii_getClassNode() function parses the class definition tree of the ClassDefHandle to retrieve the class indicated by the index.

The bmcii_getClassNode() function returns the following values:

You can use the ChildClasses handle to retrieve the child classes in the list recursively. You can use the SlotsHandle parameter in the bmcii_getSlotDefInfo() function to retrieve details about each slot of the selected class.

bmcii_getClassDefByName()

The bmcii_getClassDefByName() function retrieves a specified class definition and corresponding slot information for a selected class, without walking through the class tree hierarchy. In addition to slot information for the selected class, it also retrieves the slots inherited from its base classes.



ClassDefHandle the temporary integer assigned to the class definition tree that the bmcii_getClassDefQueryReply() function or a previous iteration of the bmcii_getClassNode() function returns

index the integer (unsigned, long) that indicates which class the function will retrieve.

Return value Description

**pcClassName a pointer to the class name (BMCII_STR string type) of the class it has retrieved

*iChildCount a pointer to the number (integer type) of child classes that the selected class definition has

*ChildClasses a pointer to the handle assigned to the list of child classes

*iSlotCount a pointer to the number of slots contained in the selected class that has been retrieved

*SlotsHandle a pointer to the handle assigned to the slot structure

bmcii_result bmcii_getClassDefByName(BMCII_CLASSDEF_RESULT ResultHandle, BMCII_STR **szClassName, int *iSlotCount, SLOT_DEFS_HANDLE *SlotsHandle);


bmcii_getSlotDefInfo()

When you call the bmcii_getClassDefByName() function, you pass it the following arguments:

The function returns the a pointer to the number of slots in the specified class (*iSlotCount) and a pointer assigned to the slot structure (*SlotsHandle). You can use the SlotsHandle parameter in the bmcii_getSlotDefInfo() function to retrieve details about each slot of the selected class.

bmcii_getSlotDefInfo()

The bmcii_getSlotDefInfo() retrieves detailed information about the slots in the selected class or classes. Its declaration is as follows:

When you call the bmcii_getSlotDefInfo() function, you pass it the following arguments:

The bmcii_getSlotDefInfo() function parses the slot structure to retrieve the slot indicated by the index. It then returns the following slot parameters, all of which are string types:


ResultHandle the temporary integer assigned to the result set that the bmcii_initQueryClassDefinitions() function returns

*szClassName zero terminated string that specifies the name of the class to be retrieved

bmcii_result bmcii_getSlotDefInfo(SLOT_DEFS_HANDLE slotsHandle, unsigned long index, BMCII_STR **psSlotName, BMCII_STR **psSlotType, BMCII_STR **psSlotRep, BMCII_STR **psSlotFlags, BMCII_STR **psSdefaultValue);


SlotsHandle the temporary integer assigned to the copy of the slot structure returned by the bmcii_retrieveClassNode() function

index the integer (unsigned, long) that indicates which slot the function will retrieve.


bmcii_freeQuerySlotsHandle()

bmcii_freeQuerySlotsHandle()

The bmcii_freeQuerySlotHandle() releases the memory space occupied by the slot definition structure, which is referenced by the SlotsHandle pointer returned by the bmcii_retrieveClassNode() function. You are responsible for calling the bmcii_freeQuerySlotsHandle() function to release the memory.

When you call the bmcii_freeQuerySlotHandle() function, you pass it the SlotsHandle argument. The function declaration is as follows:

Return value Description

**psSlotName name of the slot in the selected class

**psSlotType indicates the type of value that the slot contains. The value can be a single entry or a list-of entry. It can be one of the following types:

■ STRING■ REAL■ POINTER■ INTEGER■ EnumTypeName

*psSlotRep slot representation type that indicate what the slot type represents. Possible values include date and class. If the slot representation type is not specified, it is represented by an asterisk (*).

*psSlotFlags a Boolean indicator that indicates whether the slot has certain attributes. An uppercase character means that the attribute is true and does apply to the slot. A lower case character means that it is false and does not apply to the slot. The values are

■ r|R = read-only■ k|K = key■ p|P = parse■ d|D = dup_detect■ h|H = hidden

**psSdefaultValue a pointer to the default value, if any, assigned to the selected slot

bmcii_result bmcii_freeQuerySlotsHandle(SLOT_DEFS_HANDLE *SlotsHandle);


bmcii_closeQueryClassDef()

bmcii_closeQueryClassDef()

Call the bmcii_closeQueryClassDef() to remove cached data, release all memory resources, and to close the class query sequence. When you call the bmcii_closeQueryClassDef() function, you pass it the handle that points to the result set which the bmcii_queryClassDefinitions() function returns. Its declaration is as follows:

After you call the bmcii_closeQueryClassDef() function, you call the bmcii_termQueryConnect() function to terminate the query connection.

Service component status and mode functionsUse these functions after you have established a query connection to manipulate the status and maintenance modes of service model components (objects in the MC_SM_COMPONENT class).

Use the bmcii_setManualStatus() function to set a manual status on a service model component. The manual status that you assign the service model component does not override any computed status, but is used as another value in the overall calculation of the component’s status.

Use the bmcii_setMaintenanceMode() function to

■ indicate that the selected service model component is in maintenance and will be ignoring events

■ assign it a status

You can also use each function to clear the status that each has set.

bmcii_result bmcii_closeQueryClassDef(BMCII_CLASSDEF_RESULT *ResultHandle);


bmcii_setManualStatus()

bmcii_setManualStatus()

Use the bmcii_setManualStatus() function after establishing a query connection to set and clear any of the following statuses on a selected service component:

■ Blackout■ Unknown■ OK■ Information■ Warning■ Minor Impact■ Impacted■ Unavailable


When you call the bmcii_setManualStatus() function, you pass it the following arguments:

bmcii_result bmcii_setMaintenanceMode(BMCII_QUERYHANDLE QueryHandle, BMCII_STR *szCompId, BMCII_BOOL bSet, BMCII_STR *szStatus, BMCII_STR *szComment);

Table 52 Input arguments: bmcii_setManualStatus()



szCompId a zero terminated string type that contains the universal data ID (mc_udid) of the component object

bSet Boolean indicator that shows whether manual status is enabled for this component ID. It must be set to True to enable you to change its status manually. Change bSet to False to clear the manual status.

szStatus string description of the manual status to be set

szComment string description containing the reason for setting or removing the manual status


bmcii_setMaintenanceMode()

bmcii_setMaintenanceMode()

Use the bmcii_setMaintenanceMode() function after you establish a query connection to place a selected service component in maintenance, indicating that it will be dropping events, and to assign a status mode to it while it is undergoing maintenance. You can assign any of the following statuses:

■ Blackout■ Unknown■ OK■ Information■ Warning■ Minor Impact■ Impacted■ Unavailable


When you call the bmcii_setMaintenanceMode() function, you pass it the following arguments:

bmcii_result bmcii_setMaintenanceMode(BMCII_QUERYHANDLE QueryHandle, BMCII_STR *szCompId, BMCII_BOOL bSet, BMCII_STR *szMode, BMCII_STR *szComment);

Table 53 Input arguments: bmcii_setMaintenanceMode()



szCompId a zero terminated string type that contains the universal data ID (mc_udid) of the component object

bSet Boolean indicator that shows whether maintenance mode is enabled for this component ID. It must be set to True to place the component into maintenance. Change bSet to False to remove the component from maintenance mode.

szMode string description of the status assigned to this component while it is in maintenance mode

szComment string description containing the reason for setting or removing the component into or from maintenance mode


C h a p t e r 12
12 Translation and Selection

Translating events and data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247How translation works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Map files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Translation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263bmcii_loadMapSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264bmcii_translate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264bmcii_unloadMapSet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264bmcii_listMaps() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264bmcii_getMapInfo(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265bmcii_getMapSetInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265bmcii_registerFunction() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Selecting messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266How message selection works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Message selector set files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Supplemental message selector files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Selection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282bmcii_listSelectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283bmcii_loadSelectorSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283bmcii_matchSelector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283bmcii_matchSelectorSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284bmcii_matchSelectorSetAll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284bmcii_matchSelectorSet2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285bmcii_matchSelectorSetAll2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285bmcii_unloadSelectorSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285bmcii_enableSelector() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286bmcii_getSelectorInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286bmcii_getSelectorSetInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286bmcii_registerFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286


Overview

OverviewTranslation and message selection are two unique processes:

■ Mapping provides the BMC II C APIs with instructions for translating data that originates in an external (third-party) product or a BMC Impact Manager instance to a message format that another BMC Impact Manager instance can read and use.

■ Selection enables the APIs to determine if a message matches a set of criteria. The selected message can be manipulated, filtered, or used to trigger an action, as specified by the integration developer.

Although they are distinct activities, translation and selection share some characteristics:

■ Maps and message selectors are both stored as text files that are created by the integration developer and modified in the field.

■ You can use maps and message selectors together to determine the proper translation of a message then to translate it.

■ Maps and message selectors share common functions, and their file formats are very similar.

Because of these common characteristics, these two features are described together in this chapter.


Translating events and data

Translating events and dataApplications that are not part of BMC Impact Manager, including both third-party products and most BMC Software products, store data in formats different from the BAROC code format that BMC Impact Manager uses.

To enable a BMC Impact Manager instance to interpret data from these “external” applications, the event must be formatted as a BMC Impact Manager message and may require translation into terms that are familiar to the BMC Impact Manager instance. The reverse is also true: messages originating in a BMC Impact Manager instance may also require translation so that the data they contain can be processed by an external application or another BMC Impact Manager instance.

Translation affects message content, not message format.

Event translation is required in the following situations:

■ When an application that is not part of the BMC Impact Manager environment sends information to a BMC Impact Manager instance as an event or data message

■ When a BMC Impact Manager instance sends an event message to an application that is not part of the BMC Impact Manager network

■ When an event or data message that includes content that requires special modification is passed between two BMC Impact Manager instances

How translation works

The translation function takes a source message composed of event data and creates a new destination message whose content (slot names and values) is based on the content of the original message and the map used in the translation.

Translation creates a new message with new class and slot content. That slot content may or may not have a direct relationship with specific slots and values that were in the source message.

The content of the new message is described in on page 253.

Selecting the appropriate map

The instructions for how the translation is performed are contained in a map. Multiple maps are ordered in map sets. Map sets are stored in text files that the integration loads. Each map set can contain a unique instruction set.


How translation works

Maps are specified by name. Each map in the map set must have a unique name.

It is common to use a message selector function to determine the proper map to use for translation. For more information about message selectors, see “Selecting messages” on page 266.

The order of operations

In the first order of operations, a message that originates in an external application is translated. The integration sends the resultant message to a BMC Impact Manager instance.

In the second order of operations, a message originates in a BMC Impact Manager instance and is translated into content that an external application can use.

External application to BMC Impact Manager instance

1 The integration loads required map sets using the bmcii_loadMapSet function.

2 Optional. If you are using message selectors to determine which maps to use to translate, the integration loads the appropriate message selector set using bmcii_loadSelectorSet.

3 Data originating in a third-party application (for example, XML) must be parsed by the integration and inserted into a message through the message-building functions described in Chapter 9, “Message Construction.”

4 Optional. The integration calls the bmcii_matchSelectorSet2() function to determine which map to use to translate the event. The data parameter should contain the name of the map that will be used for translation.

5 The integration calls the bmcii_translate function to translate the message.

A new message (the destination message) is built based on the criteria specified in the selected map.

6 Send the new message to a BMC Impact Manager instance.

7 When the integration is finished with a loaded map and message selector sets, it calls the bmcii_unloadMapSet and bmcii_unloadSelectorSet functions to delete the map set and message selector set handles and free memory.


Map files

BMC Impact Manager instance to external application

1 The integration loads required map sets using the bmcii_loadMapSet function.

2 Optional. If you are using message selectors to determine which maps to use to translate, the integration loads the appropriate message selector set using bmcii_loadSelectorSet().

3 A message originates in a BMC Impact Manager instance.

4 Optional. The integration calls the bmcii_matchSelectorSet2() function to determine which map to use to translate the event. The data parameter should contain the name of the map that will be used for translation.

5 The integration calls the bmcii_translate function to translate the message:

A new message (the destination message) is built based on the criteria specified in the selected map.

6 After the new message arrives in the integration, the integration must reformat the content of the message into a format that the external application uses.

7 The message content is passed to the external application.

8 When the integration is finished with a loaded map set and message selector set, it calls the bmcii_unloadMapSet and bmcii_unloadSelectorSet functions to delete the map set and message selector set handles and free memory.

Map files

Map files are text files that are created and modified through the BMC II configuration utility by the developer or an authorized end user. The BMC II C APIs are installed with a sample map file that you can use as a template. The sample map file is located in the bmciiapi_7_1\config directory.

Use maps to do the following:

■ specify the slots and slot values that will be included in the destination message■ copy slots from the source message to the destination message■ specify new or empty values for copied slots■ delete slots■ nest additional maps within a map, using the $domap function

The following topics describe the map files that you can create.


Map files

Characteristics

Map files have the following characteristics:

■ Map files contents are not case sensitive.

■ The contents of a map file comprise a map set. The map set can contain one or more maps. However, a map file can contain only one map set.

■ The naming convention for map set files is mapset_name.map.

■ Map file syntax is checked when the map file is loaded. If the map file contains problematic syntax, the bmcii_loadMapSet function will fail.

■ Each map set must be assigned a Map Set Name.

■ Each map in a map set must be assigned a MapName that is unique within the map set.

Format

Map files must contain header information that describes the map set and each individual map. Figure 74 depicts the information structure of the map file.

Figure 74 Map file hierarchy

A single map set header, described in “Map set header” on page 251, must precede all maps in the map set.


Map files

A map header, described in “Map Header” on page 252, must precede each map in the map set.

Map content is described in “Map criteria” on page 253.

Map set header

The map set header provides the set of maps in the file with identifying information and indicates whether the map set is enabled for use. A single map set header must precede all maps in the map set.

Table 54 describes the required and optional map set header parameters that precede the maps in the set.

Table 54 Map Set Header Contents (part 1 of 2)

Parameter Description Inclusion

MapSetName= name of the map set

Note: The MapSetName can be seen in the trace file. Use this functionality to debug problems with a specific map set.

Required

Version= version of the map set, specified manually by the developer or integration end-user

Optional

FormatVersion= indicates which version of the BMC II C APIs is required to translate this file

Depending on its contents, a map file created in version 2.1 or later of the BMC II Developer’s Kit may not be backwards compatible with an earlier version of the toolkit.

Required

ChangeDate= date when the file last changed, specified manually by the developer or integration end-user

Optional


Map files

Map Header

A map header provides the each map in the file with identifying information, indicates how some map features will be implemented, and indicates whether the map is enabled for use. A map header must precede each map in the map set.

Table 55 describes the required and optional map header parameters that precede each map.

Description= free-text description of the map set Optional

Enable= specifies whether the map set (and ALL maps in it) are enabled for use

Valid values:


Note: If you specify a disabled map set in a bmcii_translate function call, the BMC II C APIs do not translate the message and the BMCII_MAP_DISABLED return code is sent to the integration.

This return code does not necessarily describe an error, since disabling an entire map set is supported. If you disabled the map set intentionally, no response is necessary. If the map set was disabled unintentionally, reload the map set file and rerun the bmcii_translate function.

Required

Figure 75 Sample Map Set Header

MapSetName=TestingVersion=9FormatVersion=2ChangeDate=August 14, 2005Description=This file contains the event map examplesEnable=true

Table 54 Map Set Header Contents (part 2 of 2)



Map files

Map criteria

Each line of text in a map contains a class or slot specification that will be included in the destination message that the translation process builds.

Table 55 Map Header Contents


MapName= name of the map. Used by the BMC II C APIs to identify the map that will be used in translation

This name must be unique within the map set.

Required

Description= free-text description of the map Optional

CopySource= indicates that the content (slots) of the source message is copied into the destination message before any translation is performed

Valid values:

■ TRUE – copies the source message slots into the destination message

■ FALSE – does not copy the source message slots into the destination message (default)

After the content is copied from the source message to the destination message, it can then be translated.

Optional

Enable= specifies whether the map is enabled for use

Valid values:


Required

Figure 76 Sample Map Header

MapName=ACCT_MAPCopySource=FALSEDescription=This map translates Unicenter events to IM eventsEnable=true


Map files

Format issues

■ With the exception of the $domap function, all map entries are stated as an equation. The left side of the equation is the name of a slot that will appear in the destination message. An equals sign (=) separates the slot name from the value it will receive, which is to the right of the =.

■ Map criteria follow the map header and are enclosed in curly brackets ({ })

■ Each line in a map contains only one map criterion.

■ Explicit text must be enclosed in double-quotes (" ").

■ The # symbol is used to comment out the rest of a line in a file. This symbol can be used to alter map functions, as well as conceal developer comments. When a line in a map is commented out, the translation function ignores it.

Do not comment out whole maps or map sets. Set the Enable parameter of the map set header or the map header to FALSE to disable the map set or map.

Slot values can include:

■ static text■ functions■ empty values

Map file functions are described in Table 56.


Map files

Table 56 Map File Functions (part 1 of 5)

Function Description

$HostName specifies host name of the computer on which the translation program is running. This function can be inserted in the new message as a slot value: for example, hostName=$HostName.

$Lookup processes a lookup table between source message slot values and destination message slot values. The results of this function are inserted in the new message as a slot value.

During processing, the $Lookup function retrieves the value of the source slot. It looks up the value in the table listed below and find its equivalent. The equivalent is assigned to the slot listed on the left.

In the map, the values table must follow immediately after the $Lookup line.

Example:

severity=$Lookup(slot.SEVERITY)

{

INFO->INFOWARNING->WARNINGERROR->MAJORFAILURE->DOWNSUCCESS->OKUNKNOWN->UNKNOWN

}

The map-to pointer -> is used exclusively with the $Lookup function. The map-to pointer -> indicates that the value on the left maps to the value on the right. In the above example, if the slot SEVERITY contains ERROR, the result set of the slot SEVERITY would be MAJOR.

$ClassName class name of the source message. This function can also be inserted in the new message as a slot value to set the class value of a destination event.

Examples:

slot.imclass=$ClassName$ClassName="EVENT"

Note: $ClassName is the only function that can be specified on the left side of the operators in the map set file.


Map files

$TimeT returns the number of seconds since January 1, 1970 as a number.

Example:

mc_date=$TimeT

$format similar to printf, uses %s to insert values into a string, expands \t and \n.

Note: %s is the only formatter available for $format.

Example:

mc_origin=$format("%s:%s", slot.p_agent, slot.p_agent_port);

$LocalTime enables you to specify the local time using the same format parameters as strftime

Example:

time=LocalTime("%I:%M:S%p")

$GmtTime enables you to specify GMT time using the same format format as strftime

Example:

time=$GmtTime("%I:%M:S%p)

$subString extracts specified components of a string

Example:

msg=$subString(slot.test, 0, 20)

where the first parameter (slot.test in the example) is the slot or string to divide; the second parameter (0 in example) is the index of the first character to include; and the third parameter (20 in example) is the number of characters to include.

$ToLower converts all of the characters in a string to lowercase

Example:

mc_host=$ToLower(slot.hostname)

$ToUpper converts all of the characters in a string to upper case

Example:

mc_domain=$ToUpper(slot.domain)




Map files

$domap specifies an additional map that can be called from within another map. Use this function as a single criterion (line) in the map.

Example:

gmttime=$GmtTime("%I:%M:%S:%p") $domap=EVENT_MAPmc_date=$TimeT

After the gmttime slot is mapped with the $GmtTime value in the new map, the $domap function indicates that the EVENT_MAP map is now used. After this map is applied, the BMC II C APIs return to the original map to process the next slot definition, mcdate=$TimeT.

$PrePendList inserts a value at the beginning of a slot list

Example: $PrePendList (slot.history, slot.servername)

where the first parameter (slot.history in the example) is the slot to be assigned and the second parameter (slot.servername) is the value that is prepended to the list.

$AppendList inserts a value at the end of a slot list

Example: $AppendList(slot.history, slot.servername)

where the first parameter (slot.history in the example) is the slot to be assigned and the second parameter (slot.servername) is the value that is appended to the list.

$InsertList inserts a value in the middle of a slot list

Example: $InsertList (slot.history, slot.servername, 2)

where the first parameter (slot.history in the example) is the slot to be assigned, the second parameter (slot.servername) is the value that is inserted into the list, and the third parameter (2) is the location where the value is inserted.

The thirst is the location to insert the value.

$GetListValue retrieves the value at a specified location in a slot list

Example: note=GetListValue(slot.notes, 3)

where the first parameter (slot.notes in the example) is the slot to be examined from the source message and the second parameter (3) is the index of the value to be retrieved.




Map files

$IpFromName performs a domain name server (DNS) lookup for the host name associated with the specified IP address

Example: IP=$IpFromName("hostname.domain")

$HostFromIp performs a DNS lookup for the IP address associated with the specified host name

Example: mc_host=$HostFromIp(slot.srcIP)

$If starts a logical if expression with a condition.

Example:

$if(slot.count > 10)

severity = "CRITCAL"

$endif

If the condition is true, then it executes a specified statement. If the condition is false, then the if processing either continues with the next option or it stops if there are no other options.

The if expression uses the same syntax and functions as selectors. See “Message selector set files” on page 268 for more on selector syntax.

$ElseIf starts the first expression and condition of an optional elseif stanza that is part of a larger if statement block

Example:

$if(slot.count > 5)

severity = "CRITICAL"

$elsif(slot.count > 5)

severity = "WARNING"

$endif

The elseif expression is evaluated when the initial if condition is false. If the elseif condition is evaluated as true, then the elseif statement is executed, and the processing of the if statement block is complete. If the elseif condition is false, then the if processing continues with the next option or it stops if there are no other options.




Map files

Table 57 on page 260 describes the valid mapping operators for $If and $ElseIf expressions.

$Else starts an optional else statement that is part of a larger if statement block

Example:

$if(slot.count > 5)

severity = "CRITICAL"

$elsif(slot.count > 5)

severity = "WARNING"

#else

severity = "NORMAL"

$endif

The else statement is executed if the previous elseif and if conditions are evaluated as false. The if processing then stops.

$EndIf the required end statement that ends the execution of the if statement block

$SlotPresent specifies a slot name that must appear in the $IF statement block that is being examined for the condition to be met

Example:

$If($SlotPresent(slot.severity)=TRUE) . . .

$SlotMissing specifies a slot name that must not appear in the $IF statement block that is being examined for the condition to be met

Example:

$If($SlotMissing(slot.severity)=TRUE) . . .




Map files

Table 57 Operators for $IF and $ElseIf (part 1 of 2)

Operators Description

= for a match, the result to the left of the equals ( = ) operator must equal the result to the right of the operator

Example: $Slot.Test = “EVENTS”

!= for a match, the result to the left of the not equals ( != ) operator must not equal the result to the right of the operator.

In the map file, this operator is valid only in IF statement blocks.

Example: $If($ClassName!="EVENT")

=~ regular expression operator

If the value that is being evaluated by the map contains the specified parameter and parameter value, a match is made.


Example:

$IF(slot.severity=~"MAJ*.")

!=~ regular expression operator


If the specified parameter does not equal the specified parameter value, then a match is made.

Example:

$IF(slot.severity!=~"MAJ*.")

> specifies a greater-than comparison and used exclusively with numerical relationships


Example:

$If(slot.test>11) slot.test=11


Map files

Table 58 on page 262 describes the general map operators.

>= specifies a greater-than or equal to comparison and used exclusively with numerical relationships


Example:

$IF(slot.Test>=11) slot.test=11

< specifies a less-than comparison and used exclusively with numerical relationships


Example:

$IF(slot.Test<11)slot.test=11

<= specifies a less-than or equal to comparison and used exclusively with numerical relationships

Example:


$IF(slot.Text<=11)slot.test=11

Table 57 Operators for $IF and $ElseIf (part 2 of 2)



Map files

Table 59 describes event mapping keywords that are prefixed to specific slots to indicate their function: metadata, readable value, or default value. Remember to include the trailing dot (.) or colon (:) when adding the keyword.

Table 58 General map operators

Operator Description



-> a "map-to" pointer that maps the attribute value of a slot or field in one message format to the attribute value of slot or field in another message format. Used exclusively with the $Lookup function to map the status strings in one message format to equivalent statuses in another message format

Example:

severity=$Lookup(slot.SEVERITY)

{##Definition of PATROL LEM severity string: {OK, Info, Warning, Minor, Major, Critical, Disconnected, Unknown}

##Definition of IM Severity:{UNKNOWN, OK, INFO, WARNING, MINOR, MAJOR, CRITICAL, DOWN}

OK->OKinfo->INFOWarning->WARNINGMinor->MINORMajor->MAJORCritical->CRITICALDisconnected->CRITICALUnreachable->CRITICALUnknown->UNKNOWNOffline->INFO}

In the above example, the severity statuses of one message format (PATROL LEM) are mapped to the severity statuses of another message format.


Translation functions

Translation functionsUse the translation functions to load map sets, translate events, and register custom map functions.

Table 60 lists the translation functions.

Table 59 Keyword descriptions

Keyword Description

metaslot. designates a slot as a metaslot, which means a slot that provides information about the message. The keyword, followed by a dot, is prefixed to the slot name that it designates.

Example: metaslot.class_name="EVENT"

slot. designates a readable slot value in regular expressions

slot.msg=~"event from slot.host"

The BMC II C APIs return the value of host before forwarding the regular expression to the expression library.

default: specifies a default slot value in the event that a slot is not in the message

The following example specifies a default value for the slot origin if the message does not contain an origin slot.

default3=slot.origin default:unknown

Table 60 Translation Functions


bmcii_loadMapSet page 264

bmcii_translate page 264

bmcii_unloadMapSet page 264

bmcii_listMaps page 264

bmcii_getMapInfo page 265

bmcii_getMapSetInfo page 265

bmcii_registerFunction page 265


bmcii_loadMapSet

bmcii_loadMapSet

The bmcii_loadMapSet function loads the specified map set file and assigns a handle to represent the loaded map set.

When the map set is loaded, a handle that represents the map set is returned. The integration application uses this handle for translation tasks, in place of the map set.

bmcii_translate

The bmcii_translate function reads a source message and creates a new message whose class and slot content are determined by a map. The map is chosen from the loaded map set.

By default the source message's message type is copied to the destination. The message type can be overridden.

bmcii_unloadMapSet()

The bmcii_unloadMapSet function() deletes the handle of the specified map set and frees the memory that was allocated for that handle.

The map set handle is not valid after this function is called. Discard it.

bmcii_listMaps()

The bmcii_listMaps function() returns the names of the maps (MapNames) in the specified map file.

NOTE Map file syntax is checked when the map file is loaded. If the map file contains problematic syntax, the bmcii_loadMapSet function will fail.


bmcii_getMapInfo()

bmcii_getMapInfo()

The bmcii_getMapInfo function() retrieves header information about a specific map in a map set.

bmcii_getMapSetInfo()

The bmcii_getMapSetInfo function() returns header information about an entire map set.

bmcii_registerFunction()

The bmcii_registerFunction() calls and loads custom functions that you as a developer have created.

Use the bmcii_registerFunction() to add custom functions to a map file. When the function is encountered in the map file during a translate call, the BMC II C APIs call the custom function with all of the required information. The callback function must call bmcii_setFunctionResult() to set the result of the custom function. The result can be any string.

Figure 77 depicts how the bmcii_registerFunction() passes the callback to the custom function.

Figure 77 bmcii_registerFunction() process flow


Selecting messages

Selecting messagesSelection is a mechanism for identifying messages that match criteria that are specified in text files loaded by the integration. Messages are compared against message selectors. Selected messages are then manipulated in any way that the integration developer chooses.

For example, you can program the integration application to:

■ Categorize or filter messages

■ Block the passage of a specific message to the BMC Impact Manager instance

■ Find the name of a translation map based on the message selector criteria

■ Send an e-mail message when the selected message is received from a BMC Impact Manager instance

■ Anything else that you, as a developer, want your integration application to do with messages

The message selector criteria is stored in a text file (integrationName.selector, for example) that you can edit in the configuration utility.

Message selectors and subselectors

The selector functions scan through the selectors in the selector set file in the order that they are listed. It is possible to designate a selector as a subselector to avoid this scan. The selector functions do not examine a subselector directly. Subselectors are only examined when a $doselector() function is used.

NOTE Message selectors in the BMC II Developer’s Kit are distinct from selectors that used in the BMC Impact Manager.

NOTE Implementing and using the message selector file is optional. The message selector file is not a required component of an integration.


How message selection works

For example, suppose the bmcii_matchSelectorSetAll() function is called with selectors A, B, and C. The function checks all three selectors. If selectors A and B call selector C with the $doselector() function, then bmcii_matchSelectorSetAll() calls A(c) and B(c) and then selector C. To avoid this scan, selector C is designated as a subselector. Then the bmcii_matchSelectorSetAll() function results scans selectors A(c) and B(c).

How message selection works

An integration application loads a message selector set (selector set file) by calling the bmcii_loadSelectorSet function. When the message selector set is loaded, the function returns a handle that represents the message selector set.

By calling the bmcii_matchSelector function, bmcii_matchSelectorSet function, or the bmcii_matchSelectorSetAll function, the integration compares each message with the criteria in a message selector set or in an individual message selector.

The message selection function scans for slot and function values that are specified in the message selectors.

The message selection comparison is performed in a linear fashion: message selector set files are read from beginning to end and are processed in the order that they were called. The integration application scans the message selectors for a match. Scanning stops when a match is found or when all specified message selectors have been scanned without a resulting match.

The result of each line is a Boolean true or false. If a false is encountered and it is not followed by an OR, the entire message selector fails

When the integration is finished using the message selector or selector set, the integration calls the bmcii_unloadSelectorSet() function to clear the memory that is reserved for the message selector set handle.

NOTE The message selection functions do not call message subselectors directly. Instead, message subselectors are called by the internal message selection function $doselector to further define message selector criteria.


Message selector set files


Message selector set files are text files that are created and modified by the developer or an end user through the BMC II configuration utility. The BMC II C APIs are installed with a sample selector set file that you can use as a template. The sample message selector set file is located in the bmciiapi_7_1\config directory.

The following topics describe the structure and content of message selector set files.

Characteristics

Message selector set files have the following characteristics:

■ Message selector set file criteria are not case sensitive.

■ The naming convention for message selector set files is selectorsetName.selector.

■ Message selector set file syntax is checked when the message selector set file is loaded. If the message selector set file contains problematic syntax, the bmcii_loadSelectorSet function will fail.

■ The contents of a message selector set file comprise a message selector set. The message selector set can contain one or more message selectors. However, a message selector set file can contain only one message selector set.

■ Each message selector in a message selector set must have a unique name. However, different message selector sets can have message selectors with identical names.

■ When a message selector set file is called by the bmcii_matchSelectorSet function, it is scanned from beginning to end, except for message subselectors. The selection process for the message stops the first time that a parameter in a message selector is matched to a parameter value in a message. Once a match is made, the remaining message selectors in a set are ignored.

If the bmcii_matchSelectorSetAll() function is called, the function continues to scan, collecting the names of all matching selectors.

■ Because the message selector sets are scanned from beginning to end, the order of message selectors in a set and lines within a message selector are important to optimizing the matching process.

■ The $doselector function allows you to include message selectors and subselectors within a selector set. Message selectors and subselectors further refine the selector criteria.

■ The $doselector function invokes message subselectors.



■ The relationship between the criteria described in successive lines of a single stanza in a message selector is AND, unless otherwise indicated.

■ The message selector file supports the logical operators OR, AND, &&, and ||.

■ A message selector set can contain multiple stanzas of message selector criteria, nested one level deep. These multiple stanzas of message selector criteria are referred to as message selector groups. The logical relation between the groups can be expressed through an AND, OR, &&, or || connector.

■ Each line in a message selector contains only one message selector criterion.

■ The message selector file supports the following comparison operators

■ greater-than (>)■ greater-than or equal to (>=)■ less-than (<)■ less-than or equal to (<=)

The message selector file supports these comparison operators for numerals only.

■ The message selector file supports the metaslot feature, which enables you to include information about the message. For example, you can use the metaslot to indicate the source of a message. You specify a metaslot by using the keyword metaslot, followed by a dot (.), to prefix the slot name: metaslot.classname=”EVENT”.

■ The message selector file supports required slots. A required slot keyword determines the required slot or slots in the message selector criteria. The message must have the specific required slot for it to match the message selector criteria.

The required slot keyword consists of the term reqdslot, followed by a dot (.), both of which you add as a prefix to the specific slot name: for example, reqdslot.msg=”TEXT”. To illustrate, if the message selector criteria specified that the slot msg is required (reqdslot.msg=”TEXT”), then a message that did not have the slot msg would fail the matching test.

The reqdslot keyword overrides the FailOnMissingSlot parameter when the latter is set equal to FALSE. That is, a message that does not have the designated required slot fails to meet the message selector criteria.

When the FailOnMissingSlot parameter is set equal to TRUE, the BMC II C APIs ignore the reqdslot keyword when they process the message to determine whether it meets the message selector criteria.



■ You can use the full range of regular expressions as values for message selector criteria. You can include any slots within the regular expression. The BMC II C APIs return the values of the slots at runtime. Within a regular expression, you can specify a slot with the keyword slot, followed by a dot (.): slot.host. The BMC II C APIs will return the value of host before sending the regular expression to the library.

Format

Figure 78 on page 270 depicts the structure of the message selector set file.

Figure 78 Structure of message selector set file

Message selector set files must contain header information that describes the message selector set. The header information consists of

■ message selector set headers, described in “Message selector set header” on page 270

■ message selector headers, described in “Message selector header” on page 272

Message selector criteria are described in “Message selector criteria” on page 273.

Message selector set header

The message selector set header provides the entire set of message selectors in the file with identifying information and indicates whether the message selector set is enabled for use. A single message selector set header must precede all message selectors and their selector groups in the message selector set.



Table 61 describes the required and optional message selector set header parameters that precede the message selectors in a set.

Table 61 Message selector set header contents


SelectorSetName= name of the message selector set

Note: The SelectorSetName can be seen in the Trace file. Use this functionality to debug problems with a specific message selector set.

Required

FormatVersion= minimum version of the BMC II C APIs required to run the message selector using this file

Version 2 at a minimum must be used for this release.

Optional

Version= version number of the message selector set file, specified manually by the developer or integration end-user

Optional

ChangeDate= date when the file last changed, specified manually by the developer or integration end-user

Optional

Description= free-text description of the entire message selector set

Optional

Enable= specifies whether the message selector set (and all message selectors in it) are enabled for use

Valid values:


Required

Data= a free text string that is returned with a call to the bmcii_matchSelectorSet2() or bmcii_matchSelectorSetAll2() function. The data string can contain anything that the integration needs, such as a map name or a destination.

Optional

Figure 79 Sample message selector set header

SelectorSetName=testselectorFormatVersion=2Version=2.2ChangeDate=August 14, 2006Description=This file contains the event selector testsEnable=TRUEData=Mapevent2IM



Message selector header

A message selector header

■ provides each set of message selector criteria in the file with identifying information

■ indicates how some message selector features will be implemented■ indicates whether the specific message selector criteria, including any message

selector groups included within it, are enabled for use

A message selector header must precede each collection of message selector criteria in the message selector set.

Table 62 describes the required and optional message selector header parameters that precede each message selector.

Table 62 Message selector header contents (part 1 of 2)


SelectorName= name of the message selector, used by the BMC II C APIs to identify the message selector that will be used in selection

The name must be unique within the message selector set.

Required

Description= free-text description of the message selector Optional

FailOnMissingSlot= indicates whether the match for the message selector fails if a slot specified in the message selector criteria is missing from the message

Valid values:

■ TRUE – the match for the message selector fails if a slot specified in the message selector is missing from the message

■ FALSE – missing slots cause the line to be ignored

If the message that is being examined does not include any of the slots that are being tested by the message selector, the comparison will never result in a match. This is true even when the parameter statement is FailOnMissingSlot=false.

If you use the reqdslot keyword in the message selector criteria, it is in effect only when FailOnMissingSlot is set equal to false.

Optional.



Message selector criteria

Each message selector in a message selector set is constructed of successive lines of comparison criteria. Each criterion is composed of a comparison expressed as an equation. Equation operators are listed in Table 64.

Each line contains one criterion with an AND relationship implied between lines (unless otherwise indicated).

In addition, the message selector can consist of multiple groups of comparison criteria, each group related to the other through an AND, OR, ||, or && connector.

Format issues

Messages selector functions, which are internal to the message selector file, are described in Table 63. Operators are described in Table 64.

■ Each message selector in a set is enclosed in curly braces ({ }).

■ Message selector groups within a message selector are nested one level deep and also enclosed in curly braces. Do not nest message selector groups more than one level deep.

■ To the right of the operator is a slot, static text, or a function. On the left is a slot, regular expression, static text, or a function.

IsSubSelector Indicates whether the message selector can be called only by the $doselector() function. Valid values are true or false.

Optional

Enable= specifies whether the message selector is enabled for use

Valid values:


Required

Figure 80 Sample message selector set header

SelectorName=EVENT_SELECTORDescription=Selectors for all events of class EVENTFailOnMissingSlot=falseIsSubSelector=trueEnable=TRUE

Table 62 Message selector header contents (part 2 of 2)




■ Explicit text that is used as a matching criterion must be enclosed in double-quotes (" ").

■ If a criterion fails but has an OR relationship with the following criterion, and that criterion is a match, then that criterion pair is a match.

■ The message selector functions scan each successive selector group in a message selector until it finds a match. Once they find a match, they stop searching.

■ The # symbol is used to comment out the rest of a line in a file. This symbol can be used to alter message selector functions, as well as conceal developer comments. When a line in a message selector is commented out, the selection function ignores it.

Do not comment out whole message selectors or selector sets. Instead, set the Enable parameter of the message selector set header or the message selector header to FALSE to disable the message selector set or selector.

EXAMPLE The $functionName resolves a specified function and compares the results of that operation to a slot in the message: for example,

$ClassName = "SECURITY_ALERT"

The $ClassName function returns the class name of the message. The returned value is compared to the value to the right of the operator (in this case, the class name, SECURITY_ALERT). If the message class name is SECURITY_ALERT, then the test is successful.

Table 63 Message selector functions (part 1 of 4)


$HostName specifies the host name of the computer on which the message selection program is running: for example, $HostName="MYCOMPUTER".

This function can also be inserted in the new message as a slot value: for example, "MYCOMPUTER"=$HostName. .

$ClassName class name of the source message. This function can also be inserted in the new message as a slot value to set the class value of a destination event.

Examples:

slot.imclass=$ClassName$ClassName="EVENT"



slot.slotname compares the value of slot.slotname in the message with the value specified to the right of the operator.

When the slot and the value are both present in the message, the criterion is considered a match.

Example: slot.severity = “Critical”

$doselector calls additional message selectors or subselectors, either or both of which can be linked to or included with an overarching message selector

$doselector is used as a single criterion in the message selector or subselector.

$ClassName!="EVENTS"$doselector(security_sel)slot.status != "OPEN"

The message selector examines the message class to determine whether it is “EVENTS.” Then, the function tests the entire selector security_sel to determine if it matches. If it does match, then it is considered to be TRUE. If that comparison is completed successfully (all criteria matching), the comparison process continues processing using the original message selector.

Example of $doselector calling a subselector:

SelectorName=SELECTOR_ONEDescription=does some quick checks then calls the sub selectorFailOnMissingSlot=falseEnable=TRUE{slot.host="bob"$doselector(SELECTOR_SUB)}

SelectorName=SELECTOR_SUBDescription=makes sure it is not a test eventFailOnMissingSlot=falseEnable=TRUE{slot.msg!="This is a test"$Class!="EVENT"}

Note: For a message to be considered a match to a message selector, it must match all the criteria of the message selector, including the criteria of message selectors or subselectors called by the $doselector function.





$slotPresent specifies a slot name that must appear in the message that is being examined for the criterion to be a match

Example:

$SlotPresent(slot.severity)

Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered.

$slotMissing specifies a slot name that must not appear in the message that is being examined for the criterion to be a match

Example:

$SlotPresent(slot.severity)

Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered.

$TimeT returns the number of seconds since January 1, 1970 in number format.

Examples:

mc_date=$TimeTSlot.mc_date=$TimeT

$Format similar to printf, uses %s to insert values into a string, expands \t and \n.

Note: %s is the only formatter available for $format.

Examples:

mc_origin=$format("%s:%s", slot.p_agent, slot.p_agent_port)$format("%s:%s", slot.p_agent, slot.p_agent_port)=mc_origin.

$LocalTime enables you to specify the local time using the same format parameters as strftime

Examples:

time=LocalTime("%I:%M:S%p")Slot.time=LocalTime("%I:%M:S%p")

$GmtTime enables you to specify GMT time using the same format as strftime

Examples:

time=$GmtTime("%I:%M:S%p)Slot.time=$GmtTime("%I:%M:S%p")





Table 64 describes the operators that can be used for comparison in a message selector set file.

$subString extracts specified components of a string

Example:

msg=$subString(slot.test, 0, 20)

where the first parameter (slot.test in the example) is the slot or string to divide; the second parameter (0 in example) is the index of the first character to include; and the third parameter (20 in example) is the number of characters to include.

$ToLower converts all of the characters in a string to lowercase

Example:

mc_host=$ToLower(slot.hostname)

$ToUpper converts all of the characters in a string to upper case

Example:

mc_domain=$ToUpper(slot.domain)

$GetListValue retrieves the value at a specified location in a slot list

Example: note=GetListValue(slot.notes, 3)

where the first parameter (slot.notes in the example) is the slot to be examined from the source message and the second parameter (3) is the index of the value to be retrieved.

$IpFromName performs a domain name server (DNS) lookup for the host name associated with the specified IP address

Example: IP=$IpFromName("hostname.domain")

$HostFromIp performs a DNS lookup for the IP address associated with the specified host name

Example: mc_host=$HostFromIp(slot.srcIP)





Table 64 Message selector operators (part 1 of 3)




!= for a match, the result to the left of the not equals ( != ) operator must not equal the result to the right of the operator

Example: $ClassName!="EVENT"

=~ regular expression operator

If the message that is being evaluated by the message selector contains the specified parameter and parameter value, a match is made.

Example:

slot.severity=~"MAJ*."

The message selector file supports multiple regular expression operators and keywords.

!=~ regular expression operator

If the regular expression fails to match, then the entire line succeeds. If the regular expression matches the value, then the line fails.

Example:

slot.severity!=~"MAJ~."

||OR

symbol and literal string, both of which specify an OR relationship between successive lines of message selector criteria or between successive message selector groups

Example: OR relationship between successive lines of criteria$HostName = “data301”||$HostName = “data400”

By default, AND relationships exist between successive lines of message selector criteria.



&&AND

symbol and literal string, both of which specify an AND relationship between successive lines of message selector criteria or between successive message selector groups

Example: AND relationship between message selector groups

{slot.Test=”EVENTS”slot.mc_host=”EVENTS”}AND{slot.Test=”EVENTS2”slot.mc_host=”EVENTS2”}

By default, AND relationships exist between successive lines of message selector criteria.

{ } indicates groups of alternate message selector criteria within an individual message selector. A group can be nested one level deep.

Example:

{

{slot.Test=”EVENTS”slot.mc_host=”EVENTS”}AND{slot.Test=”EVENTS2”slot.mc_host=”EVENTS2”}

}

> specifies a greater-than comparison. Used exclusively with numerical relationships

Example:

slot.Test>10

>= specifies a greater-than or equal to comparison. Used exclusively with numerical relationships

Example:

slot.Test>=11





Table 65 on page 280 describes message selector keywords that are prefixed to specific slots to indicate their function: metadata, required, or readable value. Remember to include the trailing dot (.) when prefixing the keyword to the slot name.

< specifies a less-than comparison. Used exclusively with numerical relationships

Example:

slot.Test<12

<= specifies a less-than or equal to comparison. Used exclusively with numerical relationships

Example:

slot.Text<=11

Table 65 Keyword descriptions

Keyword Description

metaslot. designates a slot as a metaslot, which means a slot that provides information about the message. The keyword, followed by a dot, is prefixed to the slot name that it designates.

Example:

metaslot.class_name="EVENT"

reqdslot. designates a slot as a required slot. If the FailOnMissingSlot parameter is set equal to FALSE and if the message does not contain the specified required slot, it will not pass the message selector criteria. If the FailOnMissingSlot parameter is set equal to TRUE, then the BMC II C APIs ignore the reqdslot indicator.

Example:

reqdslot.msg="TEST"

slot. designates a readable slot value in regular expressions

slot.msg=~"event from slot.host"

The BMC II C APIs return the value of host before forwarding the regular expression to the expression library.




Supplemental message selector files

Supplemental message selector files

The bmcii_init3() function loads these four supplemental message selector files, each serving a different filtering purpose for incoming and outgoing events:

■ recvfilterin.selector■ recvfilterout.selector■ sendfilterin.selector■ sendfilterout.selector

These supplemental message selector files are stored under %installDirectory%\bmciiapi_7_1\config or $installDirectory/bmciiapi_7_1/config. By default, the filters contained in these files are turned off. Use the BMC Impact Integration Configuration Utility to enable them.

Incoming and outgoing events that are sent or received by the integration application are first scanned by the filters in these message selector files. If the incoming events are not rejected by the supplemental message selector files, then they are scanned by the filters in the integration’s message selector file.

Table 66 Supplemental message selector files

Direction Message selector file Description

Incoming events

recvfilterin.selector specifies the message selector criteria for accepting incoming events. If the incoming event does not match the message selector criteria, it is rejected automatically.

recvfilterout.selector specifies the message selector criteria for rejecting incoming messages. If the incoming event does not match the message selector criteria, it is passed on to be scanned by the message selector criteria in the integration’s selector file.

Outgoing events

sendfilterin.selector specifies the message selector criteria for approving and passing on outgoing events. If the outgoing event does not match the message selector criteria, it is filtered out automatically.

sendfilterout.selector specifies the message selector criteria for rejecting outgoing events. If the outgoing event does not match the message selector criteria, it is passed to its destination.


Selection functions

Incoming events

If the incoming event is accepted by the supplemental message selector file(s) and the integration’s message selector file, then it is either

■ placed in an event queue; or ■ inserted as a parameter in a callback if the function registered for a callback

If the incoming event is rejected, you can read a notification in the integrationName.trace file.

Outgoing events

Before an outgoing event is inserted in the bmcii_send() function, it must pass the supplemental message selector(s) and the integration’s message selector criteria. After it passes both sets of criteria, it is forwarded to its destination.

If the outgoing message is not sent, the bmcii_send() function returns one of these error codes:

■ BMCII_FILTERED_OUT, if the event matches the criteria in the sendfilterout.selector

■ BMCII_NOT_FILTERED_IN, if the event does not match the criteria in sendfilterin.selector

Selection functionsUse the selection functions to load message selector sets and select messages.

Table 67 lists the selection functions.

Table 67 Selection Functions (part 1 of 2)


bmcii_listSelectors() page 283

bmcii_loadSelectorSet() page 283

bmcii_matchSelector() page 283

bmcii_matchSelectorSet() page 284

bmcii_matchSelectorSetAll() page 284

bmcii_matchSelectorSet2() page 285

bmcii_matchSelectorSetAll2() page 285

bmcii_unloadSelectorSet() page 285


bmcii_listSelectors

bmcii_listSelectors

The bmcii_listSelectors function returns the names of the message selectors in the specified message selector set.

bmcii_loadSelectorSet

The bmcii_loadSelectorSet function loads a message selector set (or sets) that the developer specifies in the call. For the call to succeed, it must include the required message selector set file name and message selector set name. The integration application must load a message selector set to use the message selectors it contains.

When the message selector set is loaded, a handle that represents the message selector set is returned. The integration application uses this handle for selection tasks, in place of the message selector set.

bmcii_matchSelector

The bmcii_matchSelector function specifies a single message selector from a loaded message selector set and compares the message that is being selected with the criteria in the message selectors.

The bmcii_matchSelector function performs matching with only one message selector. To match using two message selectors (but not a whole message selector set), you must call the bmcii_matchSelector function once for each message selector that you want to use.

bmcii_enableSelector page 286

bmcii_getSelectorInfo page 286

bmcii_getSelectorSetInfo page 286

bmcii_registerFunction page 286

NOTE Message selector set file syntax is checked when the message selector set file is loaded. If the message selector set file contains problematic syntax, the bmcii_loadSelectorSet function will fail.

Table 67 Selection Functions (part 2 of 2)



bmcii_matchSelectorSet

The single selector can contain $doselector() statements, which call other message selectors or subselectors.

bmcii_matchSelectorSet

The bmcii_matchSelectorSet function specifies a loaded message selector set and compares the message that is being examined with all of the message selectors in the set, excluding subselectors.

The first time a match to a message selector within the set is made, the name of that message selector is returned and the selection process stops. (See “bmcii_matchSelectorSet2” on page 285 for a variation of this function.)

bmcii_matchSelectorSetAll

The bmcii_matchSelectorSetAll function specifies a loaded message selector set and compares the message that is being examined with all of the message selectors in the set.

The selection process continues until the message has been compared to all message selectors within the message selector set, excluding subselectors. The bmcii_matchSelectorSetAll function returns the names of all matching message selectors. (See “bmcii_matchSelectorSetAll2” on page 285 for a variation of this function.)

NOTE The parent message selector set must be loaded, using the bmcii_loadSelectorSet function, before any message selectors in the set can be specified in a bmcii_matchSelectorSet call.

bmcii_result bmcii_matchSelectorSet(SELECTOR_SET_HANDLE pSelectorSetHandle, BMCII_MESSAGE pMessage, BMCII_BOOL *bFoundMatch, BMCII_STR **szMatchedSelector);

NOTE You must load a message selector set, using the bmcii_loadSelectorSet function, before you can specify it in a bmcii_matchSelectorSet call.

bmcii_result bmcii_matchSelectorSetAll(SELECTOR_SET_HANDLE pSelectorSetHandle, BMCII_MESSAGE pMessage, BMCII_STR_LIST *szMatchedSelectors, int *iSelectorCount);


bmcii_matchSelectorSet2

bmcii_matchSelectorSet2

The bmcii_matchSelectorSet2() function is identical to the bmcii_matchSelectorSet() function, except that it includes a new output parameter, called szMatchedData.

szMatchedData is a string description, which you can associate with the message selector set name, further defining the purpose of the message selector that you are using. For example, you can specify a target cell, a filter name, or a map name as the value of the szMatchedData. By entering a descriptive value in the szMatchedData parameter, you did not need to elaborate the purpose of the selector set by using an awkward naming convention to associate an action with the message selector name. The purpose of the data string is left to the developer.

bmcii_matchSelectorSetAll2

The bmcii_matchSelectorSetAll2() function is identical to the bmcii_matchSelectorSetAll(), except that it includes a szMatchedDatas output parameter, which serves the same purpose as the szMatchedData parameter in the bmcii_matchSelectorSet2.

For each message selector name, you can associate a Data value with each message selector to distinguish the purpose of each one.

bmcii_unloadSelectorSet

Calling the bmcii_unloadSelectorSet function frees the integration memory used to store the message selector set handle.

bmcii_result bmcii_matchSelectorSet2(SELECTOR_SET_HANDLEpSelectorSetHandle, BMCII_MESSAGE pMessage, BMCII_BOOL *bFoundMatch, BMCII_STR **szMatchedSelector,BMCII_STR **szMatchedData);

NOTE You should continue to use unique names for each message selector set.

bmcii_result bmcii_matchSelectorSetAll2(SELECTOR_SET_HANDLEpSelectorSetHandle, BMCII_MESSAGE pMessage, BMCII_STR_LIST*szMatchedSelectors, BMCII_STR_LIST *szMatchedDatas, int*iSelectorCount);


bmcii_enableSelector()

The message selector set handle is not valid after this function is called. Discard it.

bmcii_enableSelector()

The bmcii_enableSelector() function takes as input

■ name of a message selector■ Boolean flag value to indicate if the message selector is enabled or disabled

Use the bmcii_enableSelector() function to disable a message selector temporarily. It does not change the value in the file. It changes it in memory only.

bmcii_getSelectorInfo()

The bmcii_getSelectorInfo() function retrieves header information about a specific message selector.

bmcii_getSelectorSetInfo

The bmcii_getSelectorSetInfo() function retrieves header information about an entire message selector set.

bmcii_registerFunction

The bmcii_registerFunction() calls and loads custom functions that you as an integration developer have created.

Use the bmcii_registerFunction() to add custom functions to a selector file. When the function is encountered in the selector file during a match-selector function call, the BMC II C APIs call the custom function with all of the required information. The callback function must call bmcii_setFunctionResult() to set the result of the custom function. The result must be "TRUE" or "FALSE".



Figure 81 depicts how the bmcii_registerFunction() passes the callback to the custom function.

Figure 81 bmcii_registerFunction() process flow


C h a p t e r 13
13 Testing the Integration
This chapter describes procedures that you can use to test whether your integration can perform basic operations using the BMC II C APIs. The following topics are discussed in the chapter:

Before running the tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290Verifying trace functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Verifying the library version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Testing connectivity and sending messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Testing message reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296


Before running the tests

The procedures described in this chapter test various aspects of the BMC II C APIs operation. Each procedure includes the following information:

■ the procedure objective■ the procedure■ troubleshooting tips

Before running the testsBefore you run the tests, enable the following facilities:

■ BMC Impact Manager instance availability. Ensure that one or more Impact Managers are running in your network. Configure your mcell.dir file, as described in “Editing the integration mcell.dir File” on page 64 to ensure that the integration has at least one BMC Impact Manager instance to which it can connect.

■ Tracing. Enable tracing of all BMC II C APIs’ functions, using the procedure described in “Verifying trace functionality” on page 291. You can examine the log file to verify the success of some of the tests described in this chapter.

■ Receiving. Enable whichever method you choose to receive messages. The success of some tests is determined by the content of the replies that are received.

NOTE When you are done with the tests described in this chapter, disable the logging setting that you set for the procedures in this chapter. The VERBOSE ALL ALL stderr trace setting generates large log files that may eventually fill the drive. Use this setting only when debugging your integration.


Verifying trace functionality

Verifying trace functionalityIn this test, you direct all tracing output messages to the standard error log file on the BMC Impact Manager console.

Objectives

■ to verify that the integrationName.trace file is formatted correctly and is being used by the integration

■ to log all output messages, which will aid you in analyzing the results of the other tests described in this chapter

■ for language support purposes, to ensure that you have included the locale subdirectory and the .load and catalog files

To verify trace functionality

1 Use a text editor to open the integrationName.conf configuration file.

2 Ensure that the following parameters and values are included in the file:

■ Trace=YES

■ TraceConfigFileName=integrationName.trace ■ TraceDefaultFileName=%T/trace.log (or any other valid file name)

3 Save and close the integrationName.conf configuration file.

4 If you made changes to the integrationName.conf file, stop and restart the integration to enable the new settings to take effect.

For procedures for stopping and restarting the integration, see “Starting and stopping the integration” on page 144.

5 Use a text editor to open the integrationName.trace trace configuration file.

NOTE By default, when the integration runs as a background process, trace output is sent to the default log file. When the integration runs as a foreground process, trace output is sent to standard output unless you have configured the integrationName.trace file otherwise.

NOTE For more information about the bmcii_setupServer() and bmcii_startServer() functions, see Chapter 7, “Server Mode.” For more information about language support and locale requirements, see “Language support” on page 96.


Verifying trace functionality

6 Using the # symbol, comment out any trace settings that are specified in the file.

7 Enter the following trace setting:

VERBOSE ALL ALL stderr

8 Save and close the file.

9 Stop and restart the integration to enable the new settings to take effect.

For procedures for stopping and restarting the integration, see “Starting and stopping the integration” on page 144.

10 Enable server mode in the integration by calling the bmcii_setupServer and bmcii_startServer functions.

11 Perform various BMC II C APIs’ functions (such as sending or receiving messages).

12 Examine the log file to ensure that the actions were recorded.

Troubleshooting

If the BMC II C APIs’ functions that you called were not recorded in the log file, verify the following:

■ that the integration has permission to write to the directory in which the trace file is stored

■ that the integration has permission to read the trace file and the integrationName.conf configuration file

■ that the hard drive that hosts the trace file has sufficient space

■ that the integration is running as server

If problems continue, contact BMC Software Support.

NOTE When you are done with the tests described in this chapter, disable the logging setting described in this procedure. The VERBOSE ALL ALL stderr trace setting generates too much network traffic and should be used only when debugging your integration.


Verifying the library version

Verifying the library versionThis procedure returns the version of the BMC II C APIs’ library that is currently available to the integration.

Since there is only one version of the BMC II C APIs available at this time, this test is not currently relevant. However, once later versions of the BMC II C APIs are available, you will want to ensure that the version that works with your integration is the one that is available to it.

Objective

The objective of this procedure is to determine which version of the BMC II C APIs is loaded.

To verify the BMC II C APIs’ library version

1 Call the bmcii_version() function. (See “bmcii_version()” on page 155 for more information.)

2 Examine the reply that is returned. Ensure that the specified version is appropriate to your integration.

Troubleshooting

If your integration will not operate with the loaded version of the BMC II C APIs, do one of the following:

■ obtain and load the appropriate version of the BMC II C APIs

■ update your integration to use the loaded BMC II C APIs version

TIP Add this procedure to the startup phase of your integration to ensure that it is using the appropriate version of the BMC II C APIs.


Testing connectivity and sending messages

Testing connectivity and sending messagesIn this test, you will send a simple event message to a target BMC Impact Manager instance. The BMC Impact Manager instance must be listed in the local mcell.dir file used by the integration.

Objectives

■ to send a message from the integration successfully

■ to ensure that the target BMC Impact Manager instance is defined correctly in the mcell.dir file

To Send a simple message

1 Ensure that the BMC Impact Manager instance to which you are sending the message is available.

2 From the integration, connect to the BMC Impact Manager instance.

3 Create the following message:

EVENT;message=test;END

4 Send the message to the BMC Impact Manager instance.

5 Use the Impact Explorer to determine whether the message arrived to the BMC Impact Manager instance.

Troubleshooting

Failed Test Send

Perform the following steps:

1 Ensure that the BMC Impact Manager instance to which you are sending the message is available.

2 Use the mposter utility to send a message to the same BMC Impact Manager instance. Ensure that mposter obtains connection information from the same mcell.dir file as did the integration.


Testing connectivity and sending messages

If using mposter to send the message succeeds but your integration has failed, there may be a problem with the integration. If it fails, ensure that the BMC Impact Manager instance definition in the mcell.dir file contains accurate information, formatted correctly. The mcell.dir entry format is described in “Editing the integration mcell.dir File” on page 64.

For more information about the mposter utility, see the BMC Impact Solutions: Administration guide.

Failed Send After Successful Test Send

If your integration sends test messages to a BMC Impact Manager instance successfully but fails to send its own messages successfully, the classes you are using in your messages may not be defined in the target BMC Impact Manager instance.

Determine which classes are defined in the target BMC Impact Manager instance. Send only messages that use the defined classes or define additional classes in the BMC Impact Manager instance.


Testing message reception

Testing message receptionIf your integration will be used in server mode, perform the following procedures to test its ability to receive messages.

Objectives

■ to establish whether the integration can receive messages

■ to test the @hostname:port#key format for identifying a message target

■ to test the accuracy of the integration entry in the mcell.dir file

To send a test message to an integration using the @hostname:port#key String

1 Use the mposter utility to send an event to the integration, using the @hostname:port#key string to identify the integration.

2 If the integration receives the event successfully, mposter will receive the following response from the integration:

Message #1 - Evtid = 1Connection to '<no_name>' is down.

3 Check the integration log file for errors.


EXAMPLE mposter -n @kilroy:9999#mc -a EVENT -m "test"

NOTE You can ignore the second line of this response. If the response was received by mposter, the integration received the event that was sent to it.



To send a test message to an integration using the mcell.dir file

1 Use the mposter utility to send an event to the integration. Instruct mposter to query the mcell.dir file for the integration’s connection information.

2 If the integration receives the event successfully, mposter will receive the following response from the integration:

Message #1 - Evtid = 1Connection to '<no_name>' is down.

3 Check the integration log file for errors.


Troubleshooting

■ If your integration does not receive the event, the integration definition in the mcell.dir file may contain inaccurate information or be formatted incorrectly. The mcell.dir entry format is described in “Editing the integration mcell.dir File” on page 64.

■ If your integration does not receive the event, the class of the event may not be defined in the integration.

Determine which classes are defined in the integration. Send only messages that use the defined classes or define additional classes in the integration.

EXAMPLE mposter -n integration -f c:\im\mcell.dir -a EVENT -m "Test2"

(The -f switch is optional. The mposter command automatically locates the mcell.dir file in the cell.

NOTE You can ignore the second line of this response. If the response was received by mposter, the integration received the event that was sent to it.


C h a p t e r 14
14 Deploying the Integration
This chapter describes factors that you must consider when deploying your integration.

General deployment issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Where to install an integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Running multiple integration instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Configuration directory and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Additional information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Enabling BMC Impact Manager instances to connect to an integration . . . . . . . . . . 302Deploying multiple integration instances on the same computer . . . . . . . . . . . . . . . 303

Assigning an instance name, encryption code, and port number to an integration 303

Running multiple integration instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304


General deployment issues

General deployment issuesYou can deploy your integration in any manner that you require.

Where to install an integration

You can deploy your integration as a single instance on a single computer or as multiple instances on one or more computers.

You can install an integration on any of the following computers:

■ its own computer■ on the computer that hosts the third-party application that the integration connects

to the BMC Impact Manager network■ on a computer that hosts a BMC Impact Manager instance

Running multiple integration instances

You can install multiple integration instances on your network in any of the following ways:

■ two or more separate integration instances, each on a different computer■ two or more instances of the same integration on a single computer■ multiple integration installations, some or all of which are running as multiple

instances

Running multiple integration instances as separate installations on different computers does not require any special planning. Each installation operates independently of the others.

NOTE If the integration runs as a server it must have a unique name in the mcell.dir file, regardless of whether other instances are running the same computer. The integration must be defined in the mcell.dir file using either the format in Figure 82 or the format in Figure 83 on page 302.

If you want separate integration installations to communicate, add the connectivity information for each installation to other installations’ mcell.dir files, just as you would to facilitate communication with a BMC Impact Manager instance.


Configuration directory and files

Running multiple integration instances on the same computer requires additional consideration. For more information, see “Deploying multiple integration instances on the same computer” on page 303.

Configuration directory and files

The values of parameters specified in the bmcii_init3() function that initializes the BMC II C APIs can affect which directories the BMC II C APIs use for a working directory and as a configuration directory. In addition, bmcii_init3() function parameters also determine how tracing is performed. To ensure that you store your configuration files (IIDK.conf or your custom integrationName.conf and integrationName.trace) in the correct directory and that you receive trace output where you expect to find it, see “bmcii_init3()” on page 148.

Additional information

■ Make sure that you have included the locale subdirectory and its .load file and message catalogs. See “Language support” on page 96 for more information.

■ When installed, the BMC II C APIs use a similar directory structure as a BMC Impact Manager instance.

■ When the bmcii_init3() function is called to start the BMC II C APIs for the first time, the function creates Log and Temp subdirectories under the integration_home directory.

■ If you are installing the integration on computers running UNIX or Linux, you must add the directory containing the library file to the appropriate library path. These paths are described in Table 6 on page 40.

■ If the integration is installed on a computer hosting a BMC Impact Manager instance with which the integration will communicate, it is recommended that the integration and the BMC Impact Manager instance use the same mcell.dir file. Otherwise, there is a chance that the integration may be configured to access the wrong mcell.dir file.

■ Installing the integration on a computer hosting a BMC Impact Manager instance with which the integration will communicate or on the same computer as the supported third-party application cuts down on network traffic and latency. However, this configuration increases CPU load on the host computer.




For a BMC Impact Manager instance to communicate with an integration, you must add a definition for that integration to the BMC Impact Manager instance’s mcell.dir file.

To edit the mcell.dir files of BMC Impact Manager instances that will connect with the integration

1 On the host computer of a BMC Impact Manager instance that will connect with the integration, use the BMC II configuration utility to open the mcell.dir file in the BMC Impact Manager instance configuration directory.

(Make sure that your IIDK.conf or custom integrationName.conf file references this particular mcell.dir file.)

2 Add the integration definition to the file, defining it as a cell. Use the format described in Figure 82 if the integration is running as a single instance on a computer. Use the format described in Figure 83 when creating entries for multiple instances of an integration that are running on a single computer.

3 Save and close the mcell.dir file.

4 Repeat this procedure for each BMC Impact Manager instance host that will propagate events or modify messages to the integration.

Figure 82 BMC Impact Manager Definition Format for a Single Integration Instance

cell <integrationname>_<integrationhostname> <encryption_code> <integrationhostname>:<port>

Figure 83 BMC Impact Manager Definition Format for Multiple Integration Instances

cell <integrationname>_<instancename> <encryption_code> <integrationhostname>:<port>

NOTE For more information about assigning names to integration instances, see “Assigning an instance name, encryption code, and port number to an integration” on page 303.


Deploying multiple integration instances on the same computer

Deploying multiple integration instances on the same computer

Generally, an integration uses only one integrationName.conf file, which is stored in the integration configuration directory. However multiple instances of an integration can run on a single computer.

There are three options for configuring the instances:

■ All instances can use the same configuration parameters

■ Each instance can run using unique parameters

■ Some instances can run using a default configuration while others run using unique configurations

Assigning an instance name, encryption code, and port number to an integration

Assigning an instance name to an integration is optional, when a single integration is running on a host computer. However, if more than on instance of an integration will run on a computer, each must have a unique instance name.

The instance name is used to identify the specific integration instance in the mcell.dir files of BMC Impact Manager instances that are enabled to connect to the integration instance.

Figure 84 shows an mcell.dir file entry for a single integration running on a computer, where the integration is called Rabbit, the host is Warren, the encryption code is mc and the port the integration uses is 555.

NOTE Each integration instance on a computer must use a unique encryption code and port.

Each integration instance must know its own instance name so that this name can be registered during initialization of the BMC II C APIs. Assigning instance names is discussed in “Assigning an instance name, encryption code, and port number to an integration” on page 303.

If the integration will be running as a server, it must have a unique name in the mcell.dir file.



Figure 85 shows mcell.dir file entries for two instances of an integration running on a computer.

The integration name is Pet. The host is House. The first instance is Cat. Cat uses encryption code mc5 and port 555. The second instance is Dog. Dog uses encryption code mc6 and port 556.

The BMC II C APIs do not provide a means for assigning an instance name to an integration. You can assign the instance name using any method you choose, although it is recommended that you pass in the instance name when starting the integration instance from the command line. For example:

mcell -n instancename


To run multiple integration instances, each using a unique configuration

1 Under the integration configuration directory, create an instance_name directory for each instance (config\instance_name).

2 Create an integrationName.conf file for each instance and save it to the appropriate config\instance_name directory.

For information about creating configuration files, see “Uninstalling the BMC II C APIs” on page 41.

3 Start the integration once for each instance that you want to run. Call the bmcii_init3() function once within each instance, specifying the appropriate InstanceName parameter value in the call each time.

Figure 84 BMC Impact Manager Definition Format 1

cell Rabbit_Warren mc Warren:555

Figure 85 BMC Impact Manager Definition Format 2

cell Pet_Cat mc5 House:555

cell Pet_Dog mc6 House:556



To Run Multiple Integration Instances Using the Same Configuration

1 Store the integrationName.conf file that the various instances will use in the config\ directory.


To Run Multiple Integration Instances Using Default and Non-Default Configurations

1 Store the default integrationName.conf file in the integration configuration directory.

2 Under the integration configuration directory, create an instance_name directory for each instance (config\instance_name) that will run using a non-default configuration file.

3 Create a non-default integrationName.conf file for each instance running with a non-default configuration and save it to the appropriate config\instance_name directory.



A p p e n d i x A
A Defines, Typedefs, Structures, and Slot Definitions
This appendix presents the following topics:

Defines, typedefs, structures, and enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Defines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Structures and enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Structures and enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Slot definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319EVENT root class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320DATA root class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325


Defines, typedefs, structures, and enumerations

Defines, typedefs, structures, and enumerations

This section describes the programming elements that are used in the BMC II C APIs.

Defines

Table 68 lists the data types that are defined for the BMC II C APIs.

Table 68 BMC II C APIs’ Data Type Definitions (part 1 of 2)

Data Type Type Description

bmcii_result int result returned by all BMC II C APIs’ functions

Valid values:

■ 0 – no error■ negative_value – error

For more information about errors, see Appendix D, “Error Codes.”

BMCII_CNC unsigned long

handle that references a connection to a BMC Impact Manager instance or an integration in server mode

Multiple BMCII_CNC handles can be valid at the same time.

BMCII_SEC_TOKEN

unsigned long

placeholder for future security implementations

Any function requiring this parameter will ignore its contents.

BMCII_MESSAGE void* pointer to a message that contains an event or data object

Only the proper BMC II C APIs’ message functions can manipulate a message.

SELECTOR_SET_HANDLE

void* handle that references a loaded message selector set

For more information about message selectors, see Chapter 12, “Translation and Selection.”

MAP_SET_HANDLE

void* handle that references a loaded map set.

For more information about maps, see Chapter 12, “Translation and Selection.”


Structures and enumerations


This section describes the structures used in the BMC II C APIs.

■ “Message types” on page 309■ “Receive types” on page 312■ “Reply types” on page 313■ “Query types” on page 319

Message types

Message types are enumerations used with messages.

BMCII_MESSAGE_TYPE

The types of messages used with the BMC II C APIs. The message type is set using the bmcii_setMessageType function and retrieved using the bmcii_getMessageType function or by specifying a value for the META_MSG_TYPE metaslot.For more information about the META_MSG_TYPE metaslot, see Table 26 on page 179.

BMCII_SELECTOR_DISABLED

int return code for the group of match message selector functions. It indicates that the message selector set or all selectors are disabled

BMCII_STR char data type for strings

Most BMC II C APIs’ functions require BMCII_STR *. Therefore, any string that can be cast as char * is an appropriate value.

MAX_EVENT_ID -- the recommended maximum length of an event ID

Default: 100 characters

MAX_CLASS_NAME

-- the recommended maximum length of a class name

Default: 100 characters.

Table 68 BMC II C APIs’ Data Type Definitions (part 2 of 2)

Data Type Type Description



Table 69 describes the elements of the BMCII_MESSAGE_TYPE enumeration.

bmcii_BufferMode

This enumeration contains information describing the buffer mode that is in operation.

Table 70 describes the elements of the bmcii_BufferMode enumeration.

typedef enum {MSG_TYPE_NONE = 0,MSG_TYPE_NEW_EVENT, MSG_TYPE_MOD_EVENT, MSG_TYPE_NEW_DATA, MSG_TYPE_OVERWRITE_DATAMSG_TYPE_MOD_DATA,MSG_TYPE_NEW_COMP_OBJ,}BMCII_MESSAGE_TYPE;

Table 69 BMCII_MESSAGE_TYPE Structure Parameters

Parameter Value Description

MSG_TYPE_NONE 0 empty message

MSG_TYPE_NEW_EVENT 1 message contains a new event object

MSG_TYPE_MOD_EVENT 2 message contains data for modifying an existing event object

MSG_TYPE_NEW_DATA 3 message contains a new data object

MSG_TYPE_OVERWRITE_DATA

4 message contains data for modifying an existing data object

Note: If the target data object message is missing from the BMC Impact Manager dynamic data tables, specifying MSG_TYPE_OVERWRITE_DATA creates a new data object in the BMC Impact Manager instance.

MSG_TYPE_MOD_DATA 5 message contains data for modifying an existing data object

MSG_TYPE_NEW_COMP_OBJ

message contains the service model component query result

typedef enum bmcii_BufferMode{BMCII_BUFFER_MODE_DEFAULT,BMCII_BUFFER_MODE_NONE,BMCII_BUFFER_MODE_LOW,BMCII_BUFFER_MODE_HIGH,

} bmcii_BufferMode;



Directory information types

Directory Information types provide structures that contain information about servers.

bmcii_DirectoryInformation

The bmcii_DirectoryInformation structure contains information about an integration server or BMC Impact Manager instance.

Table 71 describes the elements of the bmcii_DirectoryInformation structure.

Table 70 bmcii_BufferMode Enumeration Parameters

Parameter Description

BMCII_BUFFER_MODE_DEFAULT

sets the buffering mode to a value specified by the PersistencyLevel parameter in the integrationName.conf file. This setting enables you to specify a buffering mode that is specific to the message, not the connection.

BMCII_BUFFER_MODE_NONE

no buffering

BMCII_BUFFER_MODE_LOW

saves the message to a file on the integration host computer if the message is buffered

BMCII_BUFFER_MODE_HIGH

always saves the message as a file on the integration host computer before it is sent, regardless of whether the message is subsequently buffered

typedef struct {long lVersion; BMCII_STR szServerName[MAX_SERVER_NAME]; BMCII_STR szType[MAX_TYPE]; BMCII_STR szHost[MAX_HOSTNAME]; unsigned short usPort; BMCII_STR szEncryptionKey[MAX_ENCRYPTION]; unsigned long ulPlaceHolder; BMCII_SEC_TOKEN SecToken;} bmcii_DirectoryInformation;

Table 71 bmcii_DirectoryInformation Structure Parameters (part 1 of 2)

Parameter Member Description

long lVersion version of the structure

lVersion must be set to CURRENT_DIRECTORY_VERSION.

BMCII_STR szServerName[MAX_SERVER_NAME]

BMC Impact Manager instance or integration name



Receive types

The Receive types convey information about events and modifies that are received from a BMC Impact Manager instance.

BmciiRecvTypes

When calling the bmcii_getFromQueue() function or as part of a callback function, the returned result is one of several types. The BmciiRecvTypes enumeration communicates the type of result that is being returned from the call.

Table 72 describes the elements of the BmciiRecvTypes enumeration.

BMCII_STR szType[MAX_TYPE]

type of server

Valid values:

■ cell ■ gateway.gateway_type

BMCII_STR szHost[MAX_HOSTNAME]

hostname or IP address of the BMC Impact Manager instance or integration

unsigned short usPort port on which the server listens

BMCII_STR szEncryptionKey[MAX_ENCRYPTION]

encryption key used by the server

unsigned long ulPlaceHolder place holder used for iterating through the directory

BMCII_SEC_TOKEN SecToken security place holder

Note: Currently, this field is ignored.

typedef enum {BMCII_RECVD_NONE,BMCII_RECVD_MESSAGE,BMCII_REPLY_LAST,BMCII_REPLY_PARTIAL,BMCII_REPLY_ERROR,BMCII_REPLY_CANCEL,BMCII_CONNECT_NOTIFY,BMCII_DISCONNECT_NOTIFYBMCII_CONNECT_STATUS_NOTIFY

}BmciiRecvTypes;

Table 71 bmcii_DirectoryInformation Structure Parameters (part 2 of 2)




BmciiData

This union is used as part of the BmciiAnsValue structure which is used in the bmcii_ReplyError structure. The bmcii_ReplyError structure contains a list of error messages contained in BmciiAnsValue structures. The content and data type of the BmciiAnsValue is a variable. The BmciiData union is used to choose the proper data type for the content.

Reply types

bmcii_ReplyError

This structure is a message containing data about errors that are returned from a BMC Impact Manager instance or an integration.

Table 72 BmciiRecvTypes Structure Parameters


BMCII_RECVD_NONE indicates that the receive type has not been set

BMCII_RECVD_MESSAGE indicates that the Result is a message

BMCII_RECVD_MODIFY indicates that the Result is a modification of an existing message

BMCII_REPLY_LAST indicates that the Result is the final portion of a multi-part answer

BMCII_REPLY_PARTIAL indicates that the Result is the first or middle portion of a multi-part answer

BMCII_REPLY_ERROR indicates that the Result parameter value of a bmcii_GetFromqueue function is an error notification

BMCII_REPLY_CANCEL indicates that the Result is a cancel notification

BMCII_CONNECT_NOTIFY indicates that the Result is a connection notification

BMCII_DISCONNECT indicates that the Result is a disconnect notification

BMCII_CONNECT indicates that the Result notifies of a change in the status of the connection

typedef union {bool BMCII_BOOL;unsigned long bmcii_ulong;int bmcii_int;BMCII_STR *bmcii_str;BMCII_STR *bmcii_stream;} BmciiData;

typedef struct {BmciiRecvTypes RecvType;unsigned long ulMsgid;unsigned long ulData;



Table 73 describes the elements of the Bmcii_ReplyError structure.

bmcii_ReplyCancel

The BMC II C APIs keep track of each message that is sent out and associates the reply to the original message when it arrives. If either the bmcii_disconnect function or the bmcii_term function is called, the BMC II C APIs cancel the wait for the reply. Receiving this notification indicates that no reply has been received.

Table 74 describes the elements of the Bmcii_ReplyCancel structure.

BMCII_CNC cnc;unsigned long ulMsgHandle;unsigned long ans_err_code;unsigned long ans_err_argcnt;BMCII_STR *szErrorText;BmciiAnsValue **ans_err_arglst;} bmcii_ReplyError;

Table 73 Bmcii_ReplyError Structure Parameters


BmciiRecvTypes RecvType; type of structure: BMCII_REPLY_ERROR

unsigned long ulMsgid; answered message ID

unsigned long ulData; internal data

BMCII_CNC cnc; connection

unsigned long ulMsgHandle; handle to the message being answered

unsigned long ans_err_code; error code

unsigned long ans_err_argcnt;

error argument count

BMCII_STR *szErrorText; text description of the error

BmciiAnsValue **ans_err_arglst;

error argument list

typedef struct {BmciiRecvTypes RecvType; unsigned long ulMsgid;unsigned long ulData;BMCII_CNC cnc;unsigned long ulMsgHandle;} bmcii_ReplyCancel;



BmciiAnsValue

This structure contains error codes and a list of errors.

Table 75 describes the elements of the BmciiAnsValue structure.

BmciiDataTypes

This enumeration indicates the type of data stored in the BmciiAnsValue.ans_val_data field. Use the BmciiData union (page 313) to access the value.

Table 74 Bmcii_ReplyCancel Structure Parameters


BmciiRecvTypes RecvType; Type of structure: BMCII_REPLY_CANCEL





typedef struct {BmciiDataTypes ans_val_type;unsigned long ans_val_size;BmciiData ans_val_data;} BmciiAnsValue;

Table 75 BmciiAnsValue Structure Parameters


BmciiDataTypes ans_val_type; type of value (bool, str, or int)

unsigned long ans_val_size; value byte size

BmciiData ans_val_data; effective value data

typedef enum {BMCII_VAL_TYPE_BOOL, BMCII_VAL_TYPE_ULONG, BMCII_VAL_TYPE_INT,BMCII_VAL_TYPE_STR,BMCII_VAL_TYPE_STREAM,}BmciiDataTypes;



Bmcii_ReplySuccess

This structure contains an acknowledgment from a BMC Impact Manager instance or an integration that it accepted an event or data object.

Table 76 describes the elements of the Bmcii_ReplySuccess structure.

bmcii_ConnectNotify

This structure contains information that describes the connection that has been established between the integration and a BMC Impact Manager instance.

typedef struct {BmciiRecvTypes RecvType; unsigned long ulMsgid;unsigned long ulData;BMCII_CNC cnc;unsigned long ulMsgHandle;BmciiDataTypes ans_val_type;unsigned long ans_val_size;BmciiData ans_val_data;} bmcii_ReplySuccess;

Table 76 Bmcii_ReplySuccess Structure Parameters


BmciiRecvTypes RecvType; Type of structure

Valid values:

■ BMCII_REPLY_PARTIAL■ BMCII_REPLY_LAST





BmciiDataTypes ans_val_type; value type

unsigned long ans_val_size; value byte size

BmciiData ans_val_data; effective value data

typedef struct bmcii_ConnectNotify{BmciiRecvTypesRecvType;//Type of structure BMCII_CONNECT_NOTIFY||// BMCII_DISCONNECT_NOTIFY ||// BMCII_CONNECT_STATUS_NOTIFYunsigned longulMsgid;unsigned longulData;



Table 77 describes the elements of the bmcii_ConnectNotify structure.

BMCII_CNCcnc;unsigned shortusRemotePort;char*szRemoteLoc;char*szRemoteName;BmciiStatusStatus;unsigned longulRecvBufferLimit;unsigned longulRecvBufferEventsunsigned longulRecvBufferItems;unsigned longulProtocol;unsigned longulTimeDiff;unsigned longulWaitBufferCount;unsigned longulSendBufferCount;unsigned longulBufferSize;} bmcii_ConnectNotify;

Table 77 bmcii_ConnectNotify Structure Parameters (part 1 of 2)


BmciiRecvTypes RecvTyp; Type of structure:

■ BMCII_CONNECT_NOTIFY■ BMCII_DISCONNECT_NOTIFY■ BMCII_STATUS_NOTIFY




unsigned short usRemotePort; remote connection port

char *szRemoteLoc; location (IP) of the connected program

char *szRemoteName; name of the connected program

BmciiStatus Status; status of the specified connection

unsigned long ulProtocol; the protocol mechanism used for the connection with the remote host. This value is dependent on the version of BMC Impact Manager to which you are connecting.

Valid values are

■ 5 = BMC IM 3.2, 3.5■ 6 = BMC IM 4.1■ 7 = BMC IM 5.0

unsigned long ulTimeDiff; difference in seconds between the system clocks of the local and remote hosts. If the remote host resides on the local system, then the value is zero.



Bmciistatus

This enumeration contains information describing the status of the connection between the integration and another integration or a BMC Impact Manager instance.

Table 78 describes the elements of the Bmciistatus enumeration.

unsigned long ulWaitBufferCount; number of messages in the buffer waiting for an acknowledgment. The range of valid values is from zero to the actual buffer count.

unsigned long ulSendBufferCount; number of messages in the buffer waiting to be sent. The range of valid values is from zero to a maximum buffer count of 100.

unsigned long ulBufferSize; maximum number of messages that the main memory buffer can hold. The default value is 2000. You can configure this value through the MessageBufferSize parameter in the configuration file. See Table 10 on page 49 for more information.

unsigned long ulRecvBufferLimit; The limit of the global recv buffer

unsigned long ulRecvBufferEvents; The number of events and modifies in the global recv buffer

unsigned long ulRecvBufferItems; The number of non events in the global recv buffer

typedef enum BmciiStatus{BMCII_CNC_STATUS_DOWN,BMCII_CNC_STATUS_PEND,BMCII_CNC_STATUS_SYNCH,BMCII_CNC_STATUS_OPEN,BMCII_CNC_STATUS_FAIL

} BmciiStatus;

Table 78 Bmciistatus Enumeration Parameters (part 1 of 2)


BMCII_CNC_STATUS_DOWN

the connection is down

BMCII_CNC_STATUS_PEND

the connection process is in progress

BMCII_CNC_STATUS_SYNCH

the connection participants are synchronizing

Table 77 bmcii_ConnectNotify Structure Parameters (part 2 of 2)



Slot definitions

Query types

Query types are enumerations that are used to manipulate query criteria.

BMCII_ORDER

This enumeration contains information describing the query that is in operation.

Table 79 describes the elements of the BMCII_ORDER enumeration.

Slot definitionsThis section describes the slots that are defined for the root classes that the BMC II C APIs can process. These classes are:

■ “EVENT root class” on page 320■ “DATA root class” on page 325

For more information, see BMC Impact Solutions: Knowledge Base Development.

BMCII_CNC_STATUS_OPEN

the connection is established and synchronized

BMCII_CNC_STATUS_FAIL

the connection has been refused

typedef enum BMCII_ORDER{SORT_DESC=-1,SORT_NONE=0,SORT_ASC=1,

} BMCII_ORDER;

Table 79 BMCII_ORDER Enumeration Parameters


SORT_DESC indicates that query information is to be sorted in descending order

SORT_NONE indicates that query information is not to be sorted

SORT_ASC indicates that query information is to be sorted in ascending order

Table 78 Bmciistatus Enumeration Parameters (part 2 of 2)



EVENT root class

EVENT root class

EVENT is the root 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 mc_root_internal.baroc file, and extended in the mc_root_redef.baroc file. Table 80 lists the internal event slot definitions, together with an explanation for each slot.

NOTE The slot definitions are valid for version 5.1 of BMC Impact Manager. For any updates made for later versions, see BMC Impact Solutions: Knowledge Base Development.

Table 80 EVENT Class Slot Definitions (part 1 of 5)

Slot Definition Description

adapter_host STRING The name of the machine on which the adapter that sent the message resides.

administrator STRING Name of the entity that last modified the event, as user@host or package:rulename.

date STRING If empty when entering the cell, it is set as the textual format of date_reception, as defined with the DateFormat parameter.

date_reception INTEGER,

representation = date

Time stamp that is set by the adapter or gateway that sends the event. If not set by the source, on its arrival at a cell, its value is set to the value of incident_time. If there is no incident_time value, its value is set to the mc_arrival_time value.

duration INTEGER,

parse = no;

Elapsed time, in seconds, between the date_reception time and the time at which the event was closed.

event_handle INTEGER,

■ parse = no,■ read_only = yes

event identifier in the local cell.

hostname STRING Name of source machine, as a fully qualified domain name, if available.

Note: This slot is deprecated and may be removed in the future.

mc_abstracted LIST_OF INTEGER,

parse = no;

System reserved.

mc_abstraction LIST_OF INTEGER,

parse = no;

System reserved.


EVENT root class

mc_acl LIST_OF STRING,

parse = no;

A list of the additional roles that can access the event. Role ownership for the event is determined by adding roles defined in this slot to those roles defined on a collector that contains the event. event-level, role-based access is implemented in BMC Impact Explorer.

mc_action_count INTEGER Counter contains the number of programs run for this event.

mc_arrival_time INTEGER,

representation = date;

Time stamp at which the event arrived at the BMC 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.

mc_bad_slot_names LIST_OF STRING Names of slots with a parsing error.

mc_bad_slot_values LIST_OF STRING Corresponding values of slots with a parsing error.

mc_cause INTEGER,

parse = no;

System reserved.

mc_collectors LIST_OF STRING,

parse = no;

System reserved.

mc_client_address LIST_OF STRING,

parse = no;

The effective IP address of the client that sent the event. This slot replaces the former mc_origin slot.

mc_date_modification

INTEGER,


Time stamp of last modification of certain slots. The slots are those mentioned in mcell.modify.

mc_effects LIST_OF INTEGER,

parse = no;

System reserved.

mc_history LIST_OF STRING; System reserved.

mc_host STRING; Fully-qualified name of the host on which the problem occurred.

mc_host_address STRING; Typically, the network address corresponding to mc_host.

Technically, this slot can contain some other type of information in situations in which a host value is not meaningful.




EVENT root class

mc_host_class STRING; A type of host. This field is important to implementing generic actions, such as rebooting a machine on which a problem has occurred. In the background, a generic action can be translated into a specific action based on this field.

mc_incident_time INTEGER,


Time stamp corresponding to the time at which the incident causing the event occurred. Its value is zero (0) if the time unknown. This time stamp can be set by an adapter or a gateway.

mc_it_mgt_process STRING; ITIL process that is influenced by this event. Possible examples are: AVAILABILITY, SECURITY, CHANGE, PERFORMANCE, INCIDENT, SLM, CHANGE.

mc_local_reception_time

INTEGER,


Time stamp when the event arrived in the local component. It is never zero (0).

mc_location STRING; Location at which the managed object resides.

mc_modhist LIST_OF STRING; System reserved.

mc_notes LIST_OF STRING; A list of free text annotations added to the event. The contents of this slot is implementation-dependent. Rules or users should not rely on a particular value in this slot. To use this slot’s contents, you must use the appropriate access functions.

mc_object STRING; String that identifies the subcomponent that caused the event on the host. If this value cannot be derived from the original event, it should be acquired as part of event enrichment, possibly during the Refine event-processing phase.

mc_object_class STRING; String that identifies the class to which mc_object belongs.

mc_origin STRING; Event-management system that is as close as possible to the event source.

For example, PATROL agent -> BMC II for PATROL ->BMC EM. The mc_origin value would be the PATROL agent name. The mc_tool value would be string composing the PATROL agent name and its port.

This slot has been redefined. The former mc_origin slot is renamed to be mc_client_address slot.




EVENT root class

mc_origin_class STRING; Identifier that indicates the type of event-management system that originally issued the event. This slot may have the same value as the mc_tool_class slot.

mc_origin_key STRING; Unique key with which the originating event-management system enumerated the event.

In a two-tiered, event-management system, this might contain the same value as the mc_tool_key slot.

mc_origin_sev STRING; Severity value given by the mc_origin.

In a two-tiered, event-management system, this might contain the same value as the mc_tool_sev slot.

mc_parameter STRING; Name of the parameter that by going into alarm or by triggering a state change caused the event.

mc_parameter_value STRING; The actual value of the parameter that caused the event.

mc_propagations LIST_OF STRING,

parse = no;

System reserved.

mc_smc_causes LIST_OF STRING,

parse = no;

System reserved.

mc_smc_effects LIST_OF STRING,

parse = no;

System reserved.

mc_smc_id STRING System reserved.

mc_smc_impact INTEGER,

Default = 0;

System reserved.

mc_smc_type STRING; System reserved.

mc_tool STRING; Any value that can more closely identify the event provider (tool) within the specified mc_tool_class. A primary use of the field is to provide the information necessary to enable an external action to initiate communication with the event provider.

For example, If the mc_tool_class is PATROL, the mc_tool value should be a string composing the PATROL agent name and its port value so that an external action can trigger communication with it.




EVENT root class

mc_tool_class STRING; An identifier that indicates type of event provider (tool) that reported the event to the cell. Typically, each type of adapter has a specific mc_tool_class value; for example, SNMP. The identifying value, itself, is not important, but different tools should not use the same identifier. The cell does not enforce this constraint.

mc_tool_key STRING; Unique key with which the sending tool enumerated the event.

mc_tool_sev STRING; Severity value from the mc_tool. This value does not have to be the same as the severity assigned by BMC Impact Manager. For example, to the IT staff, a failed router is a critical alert. But, if there is a back-up router, the event is not critical from a service viewpoint.

mc_ueid STRING,

read_only = yes;

Universal event identifier.

msg STRING Text that describes the incident.

origin STRING IP address of source machine.


repeat_count INTEGER Number of times that the same event has been received.

severity SEVERITY,

default = WARNING

Severity of the event.

source STRING Name of the source entity where the event occurred.


status STATUS,

default=OPEN;

Status of the event.

sub_origin STRING Address of source component.


sub_source STRING Component of the source.





DATA root class

DATA root class

DATA is the root data class. Its core class definition is not visible in the Knowledge Base. It is possible, but not recommended, to redefine the DATA class in a Knowledge Base. Redefining the base DATA class results in a merge between the internal definition and the new definition of it in the Knowledge Base. Table 81 lists the internal event slot definitions, together with an explanation for each slot.

Table 81 DATA Class Slot Definitions


data_handle INTEGER,

■ parse = no,■ read_only = yes;

Data identifier in local cell

mc_udid STRING,

read_only = yes;

Universal Data ID

mc_creation_time INTEGER,

■ parse=no;■ read_only=yes,■ representation= date

Creation time

mc_modification_time

INTEGER,

■ parse=no;■ read_only=yes,■ representation= date

Modification time


DATA root class


A p p e n d i x B
B Working with the configuration utility
This appendix provides procedural guidelines that describe the BMC II configuration utility from an end user’s perspective. You can use these guidelines to prepare GUI-based procedures that you intend to deliver to your customers to help them work with your integration’s version of the configuration utility. You may also consider including the various sets of parameter descriptions contained in Table 10 on page 49 and in the map file and selector file tables in Chapter 12, “Translation and Selection.”

About the configuration utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Launching the configuration utility GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Updating configuration parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Editing message selector files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Modifying selector header values and selector criteria . . . . . . . . . . . . . . . . . . . . . 333Adding a message selector header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Deleting a selector header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Editing map files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Modifying map header values and map criteria . . . . . . . . . . . . . . . . . . . . . . . . . . 336Adding a map header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Deleting a map header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Editing the mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Adding a new cell or gateway entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Modifying a cell or gateway entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Commenting out an entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Deleting an entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Importing files and directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Backing up a configuration directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Viewing log files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343


About the configuration utility

About the configuration utilityThe configuration utility is a Java-based GUI from which you can edit the following integration application files:

Launching the configuration utility GUIDepending on your operating system, you launch the configuration utility by executing the batch file (Windows) or the script (UNIX platforms):

■ %installDirectory%\bmciiapi_7_1\config_utility\runBIIConfigUtil.bat

■ $installDirectory/bmciiapi_7_1/config_utility/runBIIConfigUtil.sh

When you first launch the configuration GUI, it displays an Open dialog box that displays the *.selector file(s) available in the conf subdirectory, as shown in Figure 86 on page 329.

Table 82 BMC II configuration utility: editable files


IIDK.conf or integrationName.conf

specifies the configuration parameter values that the integration application uses.

mcell.dir specifies information about cells or gateways to which an integration application connects and communicates

The cell or gateway can be a BMC IM instance or another integration.

message selector files including the supplemental selector files

■ recvfilterin.selector■ recvfilterout.selector■ sendfilterin.selector■ sendfilterout.selector

and the overall example.selector or integrationName.selector

message selector files that specify matching criteria which the integration application uses to specify the

■ incoming events that are filtered in or out■ outgoing events that are forwarded or filtered out of the

outgoing event queue

Note: Incoming and outgoing events must first be reviewed by the supplement selector files before they are forwarded to the main selector file used by the integration application.

example.map or integrationName.map

mapping file that translates the content of a message originating from one source to a format that the receiving source can process


Editing the configuration file

Figure 86 Configuration utility GUI: initial view

By clicking the Files of Type drop-down arrow, you can display the other file types: .conf files, .dir files, .map files, and all files. Then you can chooses the file you want to open.

Editing the configuration fileThe configuration .conf file consists of series of parameters that are grouped into classes. These parameters help to define how the integration application behaves. It defines attributes such as log tracing, persistency, and message buffering. An example configuration file as displayed in the GUI is shown in Figure 87 on page 330.


Editing the configuration file

Figure 87 Sample configuration file in GUI

The GUI contains two tabs:

■ Configuration

This view shows the different parameters of the configuration file according to class highlighted under the Parameter Classes heading on the left-hand side. You can select a parameter in the list and edit its value in the Value field. The other fields are read-only and cannot be changed.

■ Preview

This view shows the currently edited file as a text file, with all the updates performed under the Configuration view. You cannot edit the file in Preview mode.


Updating configuration parameter values

Updating configuration parameter values

1 Under Parameter Classes in the navigation area, select the parameter class of the parameter(s) you want to edit.

2 Highlight the specific parameter entry in the list.

3 Under Parameter Value, enter the new value in the Value field for the specific parameter, and click Apply.

To restore the default parameter value, click Default.

4 Choose File => Save to save the file under its current name. Choose File => Save As to save the file under a different name.

5 Restart the integration application by calling the appropriate function(s).

Editing message selector filesFigure 88 on page 332 depicts how a message selector file is displayed in the configuration utility GUI.


Editing message selector files

Figure 88 Sample message selector file in GUI


■ Selector Editor

This view shows the different editable components of the message selector file. You can select from among the different selector headers in the left-hand column, and then edit header values under the Header tab and/or modify selector criteria under the Conditions tab. You can also add new selector headers to the file, define their header values, and specify their selector criteria.

■ Selector Contents

This view shows the currently edited file as a text file, with all the updates performed under the Selector Editor view. You cannot edit the file in Selector Contents mode.


Modifying selector header values and selector criteria

Modifying selector header values and selector criteria

1 Under Selector List, highlight the selector header whose criteria you want to change.

2 Choose the Header tab under the Preview Selector File heading.

3 Highlight the header parameter whose value you want to change.

4 Under the Define Conditional heading, choose or enter the new value in the Value field.

5 To modify selector criteria associated with the selector header, click the Conditions tab. Otherwise, if you are modifying the header parameter values only, go to Step 8 when you are done.

6 Highlight the line that contains the criteria you want to change.

You can use the command buttons to the right of the criteria to

■ add new criterion (attribute, operator, and value) on a new line just below the highlighted line in the selector definition.

■ delete a selected line from the selector criteria definition■ move a selected criterion line up or down in the criteria definition■ add a new condition group definition enclosed within braces to the criteria

definition.

7 Under the Define Conditional heading, modify the attribute, operator, and the value.

You can select or enter the attribute name, the operator symbol, and the attribute value.

8 Click Apply.




Adding a message selector header

Adding a message selector header

1 In the navigation area, under Add Selector, enter the name of selector header you wish to add.

2 Enter descriptive text in the Description field. This description will display under the Header tab next to the Description parameter.

3 Click Add Selector. The selector header is added to the list under Selector List. Its header parameters are shown under Preview Selector File:

■ SelectorName=selectorName you entered in Step 1■ Data=null■ Description=stringDescription you entered in Step 2■ FailOnMissingSlot=True■ Enable=True

4 Click the Conditions tab, and add the message selector criteria under the Define Conditional heading. Select or enter attribute, operator, and value for each condition.

5 Add any comments in the Comment # field to clarify your entry.

6 To preview your change, click the Selector Contents tab.

7 To accept your changes, click Apply.

8 Choose File => Save to save the file under its current name. Or choose File => Save As to save the file under a different name.


Deleting a selector header

1 To delete a message selector header, including criteria, choose the message selector header name in the Selector List, and click Delete Selector.

2 Click Yes at the prompt dialog box.




Editing map files

Editing map filesFigure 89 depicts how a map file is displayed in the configuration utility GUI.

Figure 89 Sample map file in GUI


■ Map Editor

This view shows the different editable components of the map file. You can select from among the different map headers in the left-hand column, and then edit header values under the Header tab and/or modify mapping criteria under the Conditions tab. You can also add new mapping headers to the file, define their header values, and specify their mapping criteria.

■ Map Contents

This view shows the currently edited file as a text file, with all the updates performed under the Map Editor view. You cannot edit the file in Map Contents mode.


Modifying map header values and map criteria

Modifying map header values and map criteria

1 Under Map List, highlight the map header whose criteria you want to change.

2 Choose the Header tab under the Preview Map File heading.

3 Highlight the header parameter whose value you want to change.

4 Under the Define Conditional heading, choose or enter the new value in the Value field.

5 To modify map criteria associated with the map header, click the Conditions tab. Otherwise, if you are modifying the header parameter values only, go to Step 8 when you are done.

6 Highlight the line that contains the criteria you want to change.

You can use the command buttons to the right of the criteria to

■ add new criterion (attribute, operator, and value) on a new line just below a selected line in the map definition.

■ delete a selected line from the map criteria definition■ move a selected criterion line up or down in the criteria definition

7 To insert $if, $else if, or $else statements into the map criteria definition, click the corresponding command button below the criteria.

You can follow these guidelines:

■ You must insert the statements within the overall conditional definition enclosed by braces.

■ Insert $else if statements in rows between $if and $end if statements.■ Insert $else statements in rows between $if and $end if statements.


Adding a map header

8 Under the Define Conditional heading, modify the attribute, operator, and the value.

You can select or enter the attribute name, the operator symbol, and the attribute value.

9 Click Apply.



Adding a map header

1 In the left-hand pane, under Add Map, enter the name of map header you wish to add.

2 Enter descriptive text in the Description field. This description will display under the Header tab next to the Description parameter.

3 Click Add Map. The map header is added to the list under Map List. Its header parameters are shown under Preview Map File:

■ MapName=mapName you entered in Step 1■ Description=string description you entered in Step 2■ Enable=True

TIP To enter an $if logical expression, click the IF command button, and assign values to the string under the Attribute, Operator, and Value fields: for example, ($HostName=localHost). Then click Apply. The first part of the statement should read $if($HostName=localHost). Next, add the mapping condition between the curly braces, such as slot.severity=CRITICAL, and click Apply. The statement should now read:

{$if ($HostName)=localHost{slot.severity=CRITICAL}........}


Deleting a map header

4 Click the Conditions tab, insert the map criteria using $if, $else if, and $else statements as necessary. Then under the Define Conditional heading, select or enter attribute, operator, and value for each condition.

5 Add any comments in the Comment # field to clarify your entry.

6 To preview your change, click the Map Contents tab.

7 To accept your changes, click Apply.



Deleting a map header

1 To delete a map header, including criteria, choose the map header name in the Map List, and click Delete Map.

2 Click Yes at the prompt dialog box.



Editing the mcell.dir fileFigure 90 on page 339 depicts how an mcell.dir file is displayed in the configuration utility GUI.


Editing the mcell.dir file

Figure 90 Sample mcell.dir file in GUI


■ Directory File

This view shows the editable entries of the mcell.dir file. It allows you to comment out selected entries if your integration does not connect and communicate with them.

■ Preview

This view previews the currently saved file as a text file. You cannot edit the mcell.dir file while it is in preview mode.

Best practices guidelines

■ The integration application must be defined in the mcell.dir file of the cell or cells to which it is linked. BMC recommends that you define the integration as a cell.

■ When defining multiple instances of the same integration in an mcell.dir file, include an instance suffix with an underscore as part of the integration name. For example:


Adding a new cell or gateway entry

■ Ensure that the ServerDirectoryName parameter of the IIDK.conf or your custom integrationName.conf file contains the correct name and full path of the mcell.dir file.

Adding a new cell or gateway entry

1 Click Add.

The Entry Value fields are cleared.

2 Enter the values for the instance under Type, Name, EncryptionKey, Host, and Port.

3 Click Apply.



Modifying a cell or gateway entry

1 Highlight the cell or gateway entry that you want to modify.

2 Make your changes in the Entry Value fields: Type, Name, EncryptionKey, Host, and Port.

3 Click Apply.



cell integrationName_instanceName mc integrationHostName:port

NOTE If you enter a gateway as the Type value, be sure to use the format gateway.gatewayType, where gatewayType can specify the name of your integration application: for example, gateway.integrationName.


Commenting out an entry

Commenting out an entry

1 Highlight the cell or gateway entry.

2 Click Comment.



The integration application does not attempt to connect with the commented-out cell or integration instance.

5 Click Uncomment to restore connection to an entry. Then repeat steps 3 and 4.

Deleting an entry

1 Highlight the cell or gateway entry.

2 Click Delete.

3 Click Yes in the prompt dialog box.



Importing files and directory contentsUsing the configuration utility, you can import specified files of the types .conf, .dir, .map, and .selector into the currently opened directory. You can also import the contents of a specified directory into the currently opened directory.

If you import files of the same name into the current directory, you can overwrite existing files with the same name.


Backing up a configuration directory

To import files

1 Choose Tools => Import File.

2 In the Import File dialog box, enter the file path or click Browse to navigate to the file path.

3 Click OK.

A dialog box appears to remind that you might override your current files.

4 Click OK to continue.

To import directory contents

1 Choose Tools => Import Directory Contents.

2 In the Import Directory dialog box, enter the directory path or click Browse to navigate to the directory path.

3 Click OK.

A dialog box appears to remind that you might override your current files.

4 Click OK to continue.

Backing up a configuration directoryYou can back up the contents of your current configuration directory to a new directory. The backup creates a new directory with the same name as the original one.

1 Choose Tools => Backup Configuration Data.

2 In the Backup dialog box, enter a directory path or click Browse to navigate to the target directory.

3 Click OK.

A new directory is created at the specified location. It has the same name and file contents as the original.


Viewing log files

Viewing log filesThe configuration utility generates and maintains log files that record changes to the .conf, .map, and .selector files that it edits. Table 83 lists the configuration file types and the log file names.

1 Choose View => View Log Files.

2 In the Open dialog box, choose the log file, and click Open.

The text of the log noting the changes to the file is displayed in the View Log Files window.

3 Choose File => Exit to close the log and shut down the View Log Files window, or choose File => Close to close the current log.

You can choose File = Refresh to refresh the currently displayed log. You can choose File => Open to open another log file in the View Log Files window.

Table 83 Configuration file types and corresponding log file

Configuration file extension Log file name

.conf parameter.log

.map map.log

.selector selector.log


Viewing log files


A p p e n d i x C
C Common Event Model
This appendix describes the different property groupings of the Common Event Model (CEM), version 1.1.00. It presents the following topics:

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345Versioning support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347I18N compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Mapping quick reference: CEM to Baroc (CORE_EVENT). . . . . . . . . . . . . . . . . . 348

Guidelines for applying CEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Associating events with configuration items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Root cause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Adding attributes vs. adding generic slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Cross-launching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Event synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Free-format text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

CEM property groupings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Source component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Reporter component properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359Situation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363Metric properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

OverviewA Common Event Model (CEM) enables a consistent definition of an event. This definition specifies the format and the data, both of which each event should contain. The event should contain the same format and data, regardless of its originating source.

By mapping all event sources to CEM definitions, you significantly reduce the overhead of managing and maintaining an event management solution.


Overview

CEM definitions provide a single set of rules that work with all events. Because of the common set of rules, you can build and maintain integration clients more easily than if you had to customize event rules. An integration client that uses CEM definitions has the following advantages.

■ Reporting is standardized. A single report template work with any event, regardless of its source.

■ Event enrichment and correlation rules are simplified. For example, one enrichment rule works with any event that is CEM-compliant.

■ Slot names have common definition and uses.

■ You can easily map IT events with business impacts. The CEM event format consist of default and optional fields that let you specify

■ event type■ CEM version■ origin information■ domain information■ object information■ management processes such as availability, scheduling, and so forth■ parameters

BMC intends to make its integrations compatible with the Common Event Model. BMC recommends that customers building any new integrations be consistent with the Common Event Model described below.

The Common Event Model (CEM), version 1.1.00, defines the event fields and formats for the BMC_BaseEvent class, a super class that contains the BMC Impact Manager cell’s CORE_EVENT class. The BMC_BaseEvent class makes available to the CORE_EVENT subclass several new event-related attributes.

The super class BMC_BaseEvent organizes the event properties into the following groupings, as depicted in Table 84 on page 347:

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.


Versioning support

CEM 1.1.00 supports the following data types:

Versioning support

CEM 1.1.00 uses the EventModelVersion field (mc_event_model_version slot) to indicate the class version of the CEM that the event management system uses. If BMC Impact Manager implements the same CEM version number, of course there is no compatibility issue. If BMC Impact Manager implements a later CEM version, it translates the event to the most recent CEM format.

Table 84 Property groupings: BMC_BaseEvent class

Property group Description

General basic information about the event, including the event class, event Id, status, and so forth

Source component properties related to the component that is associated with the source of the event. These include the component host name and the host address.

Reporter component properties related to the component that has reported the event. This component is a required part of the event information if the source component and reporter component are different. If the reporter component properties are not included, it is assumed that the source and reporter components are the same.

The reportable properties include event time, event Id, and component host address.

Situation properties associated with detailed information about the event. These include its ITIL category, the time when the event occurred, and the severity level of the event.

Metrics an optional category. The properties include metric name, metric value, metric value unit, and metric threshold.

You must include all properties of the metric that you provide.

Table 85 Data types

Data types Description

INTEGER 32-bit signed value

REAL 64-bit real value

STRING UTF-8 string value with a maximum length of 65535 bytes

<ENUMNAME> enumeration

LIST_OF a collection of objects


I18N compatibility

I18N compatibility

The CEM 1.1.00 classes are compatible with internationalization requirements and provide language support. You should use Unicode encoding for all text.

Mapping quick reference: CEM to Baroc (CORE_EVENT)

The following tables list the mapping associations between CEM properties and their respective Baroc slots in the CORE_EVENT class.

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 86 CEM to Baroc: Metadata

CEM property Baroc slotRequired or optional New to CORE_EVENT in 7.1?

EventModelVersion mc_event_model_version required yes

EventClass CLASS required no

EventId mc_ueid required no

Status status optional no

ReportTime mc_incident_report_time optional yes

EventToCIAssociationType mc_smc_impact optional no

Timeout mc_timeout optional no

Notes mc_notes optional no

PropagationHistory mc_history required no

RelationSource mc_relation_source required no

Owner mc_owner optional no

Account mc_account optional yes

Table 87 CEM to Baroc: source information (part 1 of 2)

CEM property Baroc Slot Required or optional New to CORE_EVENT in 7.1?

ResourceId (source) mc_tool_id optional no

ReconciliationIdentity mc_smc_id recommended no

Alias mc_smc_alias recommended no

ComponentHost mc_host required no

ComponentHostAddress mc_host_address required no

Location mc_location optional no

ComponentURI mc_object_uri optional yes


Mapping quick reference: CEM to Baroc (CORE_EVENT)

BMC recommends that you use ReconciliationIdentity (mc_smc_id) and Alias (mc_smc_alias) because they make it easier to track configuration items.

ComponentCaption mc_object recommended no

ComponentType mc_object_class recommended no

ComponentOwner mc_object_owner optional yes

Table 88 CEM to Baroc: reporter information


ResourceId (reporter) mc_tool_id optional no

ComponentHostAddress mc_tool_address required yes

ComponentURI mc_tool_uri optional yes

ComponentCaption mc_tool required no

ComponentType mc_tool_class optional no

EventTime mc_tool_time required yes

EventType mc_tool_rule optional no

EventId mc_tool_key required no

EventSeverity mc_tool_sev optional no

EventSuggestion mc_tool_suggestion optional yes

Table 89 CEM to Baroc: situation information


SituationCategory mc_event_category required The slot is not new, but the enumeration values are. See Table 126 on page 363 for more information.

SituationTime mc_incident_time required no

Priority mc_priority optional no

Severity severity required no

Message msg recommended no

Application mc_service optional no

LongMessage mc_long_msg optional no

RepeatCount repeat_count optional no

Table 87 CEM to Baroc: source information (part 2 of 2)



Guidelines for applying CEM

Guidelines for applying CEMThis section provides some high-level guidelines for using CEM.

Associating events with configuration items

You can customize your CEM-enabled integration to create configuration item (CI) instances in the BMC Atrium CMDB that represent your integration’s service model components. If your CEM-enabled integration is going to create its unique configuration item (CI) instances in the BMC Atrium CMDB, then follow these guidelines:

■ Define your CI instances with as much detail as possible.

■ Extend the Common Data Model only when none of its classes can contain your component objects.

If your integration sends CEM events about a BMC Atrium CI, then the event description must identify the CI. You can chose one of two options:

1. Specify the BMC Atrium CMDB ReconciliationId assigned to the CI in the mc_smc_id slot of the event description. The association between event and CI is made automatically.

2. Use the SIM alias feature. Define an alias for a CI in its ComponentAlias field.

The format of the alias syntax consists of a prefix that identifies your integration application and a value that represents a CI. Ensure that the mc_smc_alias slot, which contains the alias, of your event description exactly matches the events you want to associate with the CI. Otherwise, you can create an alias by combining slot values of the event or events that you want to associate with the CI.

Table 90 CEM to Baroc: metric information


MetricName mc_parameter optional no

MetricValue mc_parameter_value optional no

MetricValueUnit mc_parameter_unit optional yes

MetricThreshold mc_parameter_threshold optional yes


Root cause

Status computation

You can enable the CEM event to be included in the status computation of the component represented by the CI. This process is known as attaching the event to the CI. To do so, define the EventInformation::EventToCIAssociationType parameter value appropriately. See Table 91 on page 351 for a listing of the values.

Root cause

The CEM base class does not store this information. However, you can either

■ add a root cause attribute in an extended class derived from the CDM

■ generate two corresponding events: one for the impacted component and another for the root cause component

BMC service impact management (SIM) best practice is to generate the two events. Both the impacted and root cause components should be defined in the same service model. When the SIM cell receives the event for the root cause component, it computes the status of the impacted component automatically.

Adding attributes vs. adding generic slots

Instead of adding generic slots to the CEM, BMC recommends that you add meaningful attributes to the extended classes that you have derived from CEM.

The problem with adding generic slots is that their semantics are not easily defined and standardized so that all applications understand the generic slots.

Table 91 EventInformation::EventToCIAssociationType parameter values

Value Description

0 MRL rules determine whether the event attaches to the CI

1 a default rule attaches this particular event to a CI

2 event does not impact the component status


Cross-launching

Cross-launching

CEM makes the cross-launching from one application to another easier. CEM uses the componentURI slot (mc_object_uri and mc_tool_uri) to specify the address used to cross-launch to the

■ component’s location■ reporter’s location (the component that reports the status of another)

When an application broadcasts it URI, it makes it possible for another application to access and cross-launch to it.

Event synchronization

To synchronize events with a third-party management system, you need to identify the

■ specific event management system that is the source of the event■ class that the event management system belongs to■ key inside the event

Free-format text

BMC recommends that you minimize free-format text because it makes pattern matching more difficult.

CEM property groupingsThis section lists and defines the parameters of the different CEM property groupings. Each CEM property corresponds to a specific CORE_EVENT slot.

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.


General properties

General properties

The general property group contains metadata information about the event.

Table 92 ReportTime (optional)

Property name ReportTime

BAROC name mc_incident_report_time

Description date and time when the event was reported by the reporting object

Data type integer

Format UTC

Example 1151651591

Table 93 EventModelVersion (required)

Property name EventModelVersion

BAROC name mc_event_model_version

Description version of the Common Event Model (CEM) that is used to instantiate the event

Data type string

Format xx, yy, zz

Example 1.1.00

Table 94 EventClass (required)

Property name EventClass

BAROC name CLASS

Description

event class name as defined by the CEM. Internally, this is the class name that is used to create the event. Each event provider should use its own value so that specific rules can be written for the designated event provider.

Data type String

Format Event_ClassName

Example BMC_MVEvent

Table 95 EventId (required) (part 1 of 2)

Property name EventId

BAROC name mc_ueid

Descriptionglobally unique identifier of the event. If the mc_ueid is not defined, then it is automatically generated by the first cell that receives the event.

Data type String


General properties

Format

<ProductPrefix><separator><mc_tool_id><separator><mc_tool_key>

You can choose which <separator> to use.

Example BPM:BPMPrimary:12345abcd

Table 96 Status (optional)

Property name Status

BAROC name mc_status

Description a specified listing of distinct object states. The default status value is OPEN.

Data type

ENUMERATION. The values are

■ OPEN■ ACK■ ASSIGNED■ CLOSED ■ BLACKOUT

Format Enumeration

Example OPEN

Table 97 Timeout (optional)

Property name Timeout

BAROC name mc_timeout

Description specified timeout period in seconds after which an event is automatically closed

Data type Integer

Format Integer

Example 300

Table 98 Notes (optional)

Property name Notes

BAROC name mc_notes

Description a list of free text annotations that are added to an event

Data type LIST_OF strings

Format Unicode text

Example

Comment this.Comment that.Comment the other.

Table 95 EventId (required) (part 2 of 2)


General properties

PropagationHistory is required only if the provider wants to receive its synchronized events back from the cell.

Table 99 EventToCIAssociationType (optional)

Property name EventToCIAssociationType

BAROC name mc_smc_impact

Description

indicates the impact type and whether this event is used in the status computation of the configuration item

By populating the mc_smc_alias, you can associate an event with a configuration item. However, the event may not affect the status computation of the configuration item. You must attach the event to the configuration item to affect its status computation.

Data type

integer. Valid values are

0 - rules determine whether the event is attached to a configuration item (default value)

1 - a predefined rule attaches this event to a configuration item

2 - the event is not attached to a configuration item

Format integer

Example 0

Table 100 PropagationHistory (required)

Property name PropagationHistory

BAROC name mc_history

Description

list of cells and the event Ids inside each cell through which the received event flowed before it reached the current cell. An event provider can define this slot so that it can receive the synchronized events back from the cell.

Data type LIST_OF string

Format <gateway_name>:0

Example [BiiOVO1:0]

Table 101 RelationSource (required)

Property name RelationSource

BAROC name mc_relation_source

Description contains the mc_ueid of the source event to which the current event is related

Data type string

Format

<ProductPrefix><separator><mc_tool_id><separator><mc_tool_key>

You can choose which <separator> to use.

Example BPM:BPMPrimary:12345abcd


Source component properties

RelationSource is required if the consumer object wants to send or receive updates.


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 102 Owner (optional)

Property name Owner

BAROC name mc_owner

Description current user assigned to the event

Data type string

Format text

Example Pablo

Table 103 Account (optional)

Property name Account

BAROC name mc_account

Descriptionidentification of the account associated with the event. (This slot does not support multitenancy.)

Data type String

Format text

Example Account1

Table 104 ResourceId (optional)

Property name ResourceId

BAROC name [for future development]

Description

unique identifier of the manageable resource on which the event has occurred. This id is different from the BMC Atrium CMDB Reconciliation Id or the alias.

Do not use the ResourceId to associate events with CIs. Instead use the reconciliation Id or the alias.

Data type string

Format GUID

Example SJSC_GICT0002.j17rul.00004

Table 105 ReconciliationIdentity (recommended) (part 1 of 2)

Property name ReconciliationIdentity

BAROC name mc_smc_id



Description

identifier of a manageable resource associated with an event and is used to associate the event with a configuration item. BMC recommends that this value be the reconciliation Id value generated by the BMC Atrium CMDB.

Data type string

Format ReconciliationId

Example OS-838310E3AEF4168FC895B883ADC8F7

Table 106 Alias (recommended)

Property name Alias

BAROC name mc_smc_alias

Description

identifier of a manageable resource associated with an event. BMC recommends that this value be taken from the alias defined in the BMC Atrium CMDB. This property helps to associate the event to the configuration item. Generally, event providers supply this value with the component’s alias value.

Data type String

Format <ProductPrefix>:<GUID>

Example BPM:838310E3AEF4168FC895B883ADC8F7

Table 107 ComponentHost (required)

Property name ComponentHost

BAROC name mc_host

DescriptionFully-qualified host name of the system on which the problem occurred. The ComponentHost is required in the ComponentHostAddress is not specified.

Data type String

Format fully qualified domain name

Example opensource.adprod.bmc.com

Table 108 ComponentHostAddress (required)

Property name ComponentHostAddress

BAROC name mc_host_address

Description

Network address for the host on which the problem occurred. It can be used to supplement the value of the ComponentHost property. The ComponentHostAddress is required if the ComponentHost property is not specified.

Data type String

Format IP address/type

Example 192.168.0.100

Table 105 ReconciliationIdentity (recommended) (part 2 of 2)



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 109 Location (optional)

Property name Location

BAROC name mc_location

Descriptionlocation at which the source component resides. This slot provides additional contextual information for the event.

Data type String

Format Text

Example SJ1-DC1

Table 110 ComponentURI (optional)

Property name ComponentURI

BAROC name mc_object_uri

Description the address that can be used to cross launch directly into a component

Data type String

Format URI

Example http://192.168.175.149/ews/index.htm

Table 111 ComponentCaption (recommended)

Property name ComponentCaption

BAROC name mc_object

Description

A text representation of the subcomponent of the host to which the event is related. This property is the equivalent of the Name attribute of BMC_BaseElement in the Common Data Model.

Note: If the BMC Atrium CMDB is populated correctly, the Name attribute is also available as a property of the CI data element in SIM.

Data type string

Format text; or the in the CDM, the name format

Examplehou-ex-04.adprod.bmc.com192.168.0.100:Microsoft Exchange Server

Table 112 ComponentType (recommended) (part 1 of 2)

Property name ComponentType

BAROC name mc_object_class


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.

Description identifies the class name of the source component

Data type string

FormatCDM class name. If the CDM class name is unknown, you can use a user-defined categorization of the source component.

Example BMC_ComputerSystem

Table 113 ComponentOwner (optional)

Property name ComponentOwner

BAROC name mc_object_owner

Description identifies the owner of the source component

Data type string

Format text

Example APAC_IT

NOTE Event providers, such BMC Performance Monitor, that are also registered in the BMC Atrium CMDB as components enhance the self-monitoring capabilities of the CEM-enabled solution.

Table 112 ComponentType (recommended) (part 2 of 2)



Slots that begin with the mc_origin prefix follow the same format as slots that begin with mc_tool.

Component address properties for reporting

These are component address elements for the reporting component:

Table 114 Slots for event monitoring information

Slot Description

mc_origin specifies the event management system that is “closest” to the source of the event and is deemed to have detected the event

mc_origin_address network IP address of the event management system

mc_origin_key unique identifier of the event in the event monitor component. It is often the same as the eventId of the event management system that detected the event

mc_origin_sev severity of the event defined by the event monitor component. The severity is internal to the component and does not map to CEM severity values.

Table 115 ResourceId (optional)

Property name ResourceId

BAROC name mc_tool_id

Description identifies a manageable resource (component) that reports an event

Data type string

Format text

Example BPMPrimary

Table 116 ComponentHostAddress (required)

Property name ComponentHostAddress

BAROC name mc_tool_address

Description network address of the reporter component

Data type string

Format IP address/text

Example 192.168.0.100

Table 117 ComponentURI (optional) (part 1 of 2)

Property name ComponentURI

BAROC name mc_tool_uri

Description address that can be used to cross-launch to the reporter component



Data type string

Format URI

Example http://192.168.175.149/ews/index.htm

Table 118 ComponentCaption (required)

Property name ComponentCaption

BAROC name mc_tool

Description object that reports the event

Data type string

Format text

Example HPVOInst1

Table 119 ComponentType (optional)

Property name ComponentType

BAROC name mc_tool_class

Description user-defined categorization of the object that reports the event

Data type string

Format text

Example BPM Portal Server

Table 120 EventTime (required)

Property name EventTime

BAROC name mc_tool_time

Descriptiontime that the reporter component received the event. This is the reporter time translated into epoch time.

Data type integer

Format coordinated universal time (UTC)

Example 1110637098173

Table 121 EventType (optional)

Property name EventType

BAROC name mc_tool_rule

Description condition that triggers the event

Data type string

Format text

Example CPU usage high

Table 117 ComponentURI (optional) (part 2 of 2)



Table 122 EventId (required)

Property name EventType

BAROC name mc_tool_key

Descriptionunique identifier of the event in the Reporter. This identifier is usually the event id assigned to the event by the system that detected the event.

Data type string

Format text

Example 3eb61c54-0806-71db-0009-8948e4720000

Table 123 EventSeverity (optional)

Property name EventSeverity

BAROC name mc_tool_sev

Descriptionthe severity level as defined by the reported component. This severity level does not map to the BEM or BMC SIM severity levels.

Data type string

Format text

Example critical

Table 124 EventSuggestion (optional)

Property name EventSuggestion

BAROC name mc_tool_suggestion

Description predefined text suggestion for solving the situation described by the event

Data type string

Format text

Example Expert advice in PATROL


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 125 SituationCategory (required)

Property name SituationCategory

BAROC name mc_event_category

Descriptionthe Information Technology Infrastructure Library (ITIL) process that the event represents

Data type

ENUMERATION (MC_EVENT_CATEGORY)

Possible values include

■ SLA_MANAGEMENT■ CAPACITY_MANAGEMENT■ SERVICE_CONTINUITY_MANAGEMENT■ AVAILABILITY_MANAGEMENT■ INCIDENT_MANAGEMENT■ CONFIGURATION_MANAGEMENT■ RELEASE_MANAGEMENT■ PROBLEM_MANAGEMENT■ CHANGE_MANAGEMENT■ OPERATIONS_MANAGEMENT■ SECURITY_MANAGEMENT■ FINANCIAL_MANAGEMENT■ SERVICE_DESK_MANAGEMENT

Format ENUMERATION

Example SLA

Table 126 Situation category (mc_event_category) values (part 1 of 3)

ITIL category Description

SLA_MANAGEMENT events relating to the Service Level Agreement Management process. The process covers planning, coordinating, drafting, agreeing, monitoring and reporting on SLAs, and the on-going review of service achievements to ensure that the required and cost-justifiable service quality is maintained and gradually improved.

CAPACITY_MANAGEMENT events relating to the Capacity Management process. The process is responsible for ensuring that the Capacity of the IT Infrastructure matches the evolving demands of the business in the most cost-effective and timely manner. All events that report something about capacity (for example, disk full) or performance (Transactions/sec) should be categorized as Capacity Management events.



SERVICE_CONTINUITY_MANAGEMENT

events relating to the Service Continuity Management process. The process covers supporting the overall Business Continuity Management process by ensuring that the required IT technical and services facilities (including computer systems, networks, applications, telecommunications, technical support and Service Desk) can be recovered within required, and agreed, business timescales.

AVAILABILITY_MANAGEMENT events relating to the Availability Management process. The process is about optimizing the capability of the IT Infrastructure, services and supporting organization to deliver a cost effective and sustained level of availability that enables the business to satisfy its business objectives. All events which report if a component is available or unavailable should be categorized as Availability Management events.

INCIDENT_MANAGEMENT events relating to the Incident Management process. The process is about restoring normal service operation as quickly as possible and minimize the adverse impact on business operations, thus ensuring that the best possible levels of service quality and availability are maintained

CONFIGURATION_MANAGEMENT events relating to the Configuration Management process. The process of identifying and defining Configuration Items in a system, recording and reporting the status of Configuration Items and Requests for Change, and verifying the completeness and correctness of Configuration Items.

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

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

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

OPERATIONS_MANAGEMENT events relating to the Operations Management process. The process is concerned not solely with the incidents reported by users, but with events generated by or recorded by the infrastructure.

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





FINANCIAL_MANAGEMENT The events relating to the Financial Management process. The process which deals with accounting for IT usage. It is used to plan, control and recover costs expended in providing the IT Service negotiated and agreed to in the SLA.

SERVICE_DESK_MANAGEMENT The events relating to the Service Desk Management process. The process to manage the Service Desk itself.

Table 127 SituationTime (required)

Property name SituationTime

BAROC name mc_incident_time

Description

time when the event occurred, translated into epoch time to accommodate BMC Impact Manager requirements

Internally the impact manager works with epoch time. Doing the translations over and over again when needed would have an impact of efficiency. Therefore we ask the providers to calculate once the epoch time, so processing of time-related information is as optimal as possible.

Data type integer

Format coordinated universal time (UTC)

Example 1110637098173

Table 128 Priority (optional)

Property name Priority

BAROC name mc_priority

Description

represents the importance of an event. This slot supports management functions requiring an event to be associated with a priority. Valid values in ascending order of significance are:

■ PRIORITY_5■ PRIORITY_4■ PRIORITY_3■ PRIORITY_2■ PRIORITY_1

PRIORITY_1 is the highest priority.

Data type ENUMERATION (MC_PRIORITY)

Format Enumeration

Example PRIORITY_1





Table 129 Severity (required)

Property name Severity

BAROC name mc_severity

Description

Represents the perceived severity of the status the event is describing with respect to the application that reports the event.

Current values

■ UNKNOWN■ OK■ INFO■ WARNING■ MINOR■ MAJOR■ CRITICAL

Data type ENUMERATION (MC_SEVERITY)

Format Enumeration

Example Major

Table 130 Message (recommended)

Property name Message

BAROC name mc_message

Descriptiondescriptive text that is part of an event. BMC recommends a terse description of the event content.

Data type string

Format text (Unicode)

Example This component is down.

Table 131 Application (optional)

Property name Application

BAROC name mc_service or mc_application

Description

service or application to which the event is related. Use this slot to add contextual information about the service or application to the event. The value of this slot would be typically set by “enrichment.”

Data type string

Format text

Example OracleListener


Metric properties

Metric properties

Metric properties are optional. However, if you do use the metric definition, you must include all related metric properties.

Table 132 LongMessage (optional)

Property name LongMessage

BAROC name mc_long_message

Description

descriptive text that is part of an event. BMC recommends that you use this slot to convey additional relevant information about the event. Do not include any MRL rules.

Data type string

Format text (Unicode)

Example this event is enriched

Table 133 RepeatCount (optional)

Property name RepeatCount

BAROC name mc_repeat_count

Description number of time that this incident described in the event has occurred

Data type integer

Format integer

Example 4

Table 134 MetricName (optional)

Property name MetricName

BAROC name mc_parameter

Description name of the metric parameter that went into alarm or that triggered the event

Data type string

Format Unicode text

Example HardDiskUsage

Table 135 MetricValue (optional)

Property name MetricValue

BAROC name mc_parameter_value

Description value of the metric

Data type string

Format Unicode text

Example 80


Metric properties

Table 136 MetricValueUnit (optional)

Property name MetricValueUnit

BAROC name mc_parameter_unit

Description unit description of the metric

Data type string

Format Unicode text

Example %

Table 137 MetricThreshold (optional)

Property name MetricThreshold

BAROC name mc_parameter_threshold

Description threshold value that was exceeded and result in the generation of the event

Data type string

Format Unicode text

Example 75


A p p e n d i x D
D Error Codes
This chapter provides a reference to the BMC II C API error codes.


BMC II C API errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370BMC II C API errors listed by error code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370BMC II C API errors listed alphabetically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

BMC II C API informational messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385Informational messages listed by code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386Informational messages listed alphabetically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Core communications errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386Core communication errors listed by error code . . . . . . . . . . . . . . . . . . . . . . . . . . 386Core communications errors listed alphabetically . . . . . . . . . . . . . . . . . . . . . . . . . 388Reportable error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392


BMC II C API errors

BMC II C API errorsErrors with the BMCII prefix relate to all aspects of the BMC II C API, apart from core communications. Core communication errors (that have the prefix, IM) are described in “Core communications errors” on page 386.

There are some BMCII errors with a purpose identical to certain IM errors. However, the integration generates only one error for an error-producing event. Which error will be generated is dependent on internal BMC II C API processes and cannot be determined prior to the generation of the error.

Errors are listed by error code and alphabetically (starting on page 373). The alphabetic listing includes a description of each error.

BMC II C API errors listed by error code

Table 138 lists BMC II C API errors, arranged by error code.

Table 138 BMC II C API Error Codes (part 1 of 3)

Error Code Error Name Described on

0 BMCII_SUCCESS page 384

-102 BMCII_BAD_MESSEGE page 375

-104 BMCII_BAD_MALLOC page 374

-105 BMCII_BAD_SLOT_NAME page 376

-106 BMCII_BAD_SLOT_VALUE page 376

-107 BMCII_MEMORY_CORRUPTED_START page 381

-108 BMCII_MEMORY_CORRUPTED_END page 381

-110 BMCII_NOT_FOUND page 383

-111 BMCII_BAD_HEAD page 374

-112 BMCII_BAD_CLASS_NAME page 373

-113 BMCII_INDEX_OUT_OF_RANGE page 379

-114 BMCII_ERROR_WRONG_SLOT_TYPE page 378

-115 BMCII_BAD_PARAMETER page 375

-116 BMCII_NEED_MORE_MEMORY page 382

-118 BMCII_END_DELIMITER page 377

-119 BMCII_ERR_MISSING_CONFIG page 378

-120 BMCII_ERR_BAD_FILE_OPEN page 377

-121 BMCII_BAD_CONFIG page 373

-122 BMCII_BAD_EVENT_CREATE page 374

-123 BMCII_BAD_HOST_PORT page 374



-124 BMCII_INVALID_SERVER_NAME page 380

-125 BMCII_ERR_LOST_CONNECT page 378

-130 BMCII_ERR_BAD_OBJECT_CREATE page 378

-131 BMCII_COMM_LOCK_NOT_INIT page 377

-132 BMCII_BAD_MESSAGE_TYPE page 375

-133 BMCII_BAD_SOCKETS_INIT page 376

-136 BMCII_ERR_BAD_FILE_NAME page 377

-137 BMCII_BAD_SELECTOR_HEADER page 376

-138 BMCII_BAD_SELECTOR_NAME page 376

-139 BMCII_NO_MORE page 382

-140 BMCII_BAD_SELECTOR_FILE_FORMAT page 375

-141 BMCII_UNKNOWN_FUNCTION page 385

-144 BMCII_BAD_MAP_FILE_FORMAT page 374

-145 BMCII_BAD_MAP_LINE page 374

-146 BMCII_BAD_SELECTOR_LINE page 376

-147 BMCII_BAD_MAP_HEADER page 374

-148 BMCII_BAD_MAP_NAME page 375

-149 BMCII_MESSAGE_CORRUPTED page 381

-150 BMCII_INVALID_FUNCTION_FORMAT page 380

-160 BMCII_UNKNOWN_SLOT_TYPE page 385

-161 BMCII_ALREADY_INITED page 373

-164 BMCII_FAILED_START_RECV page 378

-165 BMCII_ALREADY_RUNNING page 373

-166 BMCII_TIMED_OUT page 385

-169 BMCII_BAD_RECV_EVENT page 375

-170 BMCII_BAD_MUTEX page 375

-171 BMCII_MAPSET_DISABLED page 381

-172 BMCII_MAP_LOOP_DETECTED page 381

-173 BMCII_SELECTOR_LOOP_DETECTED page 384

-174 BMCII_INCOMPATIBLE_VERSION page 379

-175 BMCII_EMPTY_SLOT_NAME page 377

-177 BMCII_MUST_CALL_INIT page 382

-178 BMCII_NEED_LOCKS_FOR_THREAD page 382

-179 BMCII_UNKNOWN_TYPE page 385

-180 BMCII_MAP_DISABLED page 381

-181 BMCII_INVALID_CALL page 379

-182 BMCII_BAD_BAROC page 373

-184 BMCII_REGISTRATION_TIMED_OUT page 384





-185 BMCII_QUERY_REGISTRATION_FAILED page 383

-188 BMCII_NO_RESULT_YET page 382

-189 BMCII_BAD_PARSE page 375

-190 BMCII_REQUEST_OUT_OF_RANGE page 384

-191 BMCII_QUERY_ERROR page 383

-192 BMCII_QUERY_CONNECTION_DOWN page 383

-193 BMCII_ILLEGAL_QUERY page 379

-194 BMCII_EMPTY_MESSAGE page 377

-195 BMCII_FREED_NULL_POINTER page 379

-196 BMCII_CORRUPT_LIST page 377

-197 BMCII_TERM_CALLED page 384

-198 BMCII_MISSING_MOD_INFO page 382

-199 BMCII_INVALID_LEN page 380

-200 BMCII_UNKNOWN_CHARACTER_IN_HEX page 385

-201 BMCII_EMPTY_LIST page 377

-202 BMCII_INVALID_CONFIGFILE page 379

-203 BMCII_INVALID_HOMEDIR page 380

-204 BMCII_MISSING_REQUIRED_SLOT page 382

-205 BMCII_INVALID_IP_ADDRESS page 380

-206 BMCII_ILLEGAL_MAP_OPERATION page 379

-207 BMCII_INVALID_STRING_FORMAT page 381

-208 BMCII_NOT_VALID_MEMORY page 383

-209 BMCII_REGISTRATION_FAILED page 384

-210 BMCII_SELECTOR_DISABLED page 384

-211 BMCII_OPERATION_NOT_SUPPORTED page 383

-212 BMCII_ERROR_FROM_IM page 378

Service Model Object Query Error Codes

-240 BMCII_MISSING_UDID page 382

-241 BMCII_INVALID_QUERY_TYPE page 380

-242 BMCII_QUERY_FAILED page 383

-243 BMCII_INVALID_QUERY_RESULT page 380

-244 BMCII_INVALID_QUERY_PARAMETER page 380

-245 BMCII_SLOT_SIZE_NOT_MATCH page 384

Class Definition Query Error Codes

-280 BMCII_BAD_CLASSDEF_STREAM page 373

-281 BMCII_BAD_SLOT_DEFINITIONS page 376




BMC II C API errors listed alphabetically


Each BMC II C API error or informational message is listed alphabetically. Each message includes a description and prescriptive information, if any is available.

BMCII_ALREADY_INITED

Explanation: The bmcii_init(), bmcii_init(2), or bmcii_init3() function has been called after the BMC II C API has already been initialized.

User response: None. Calling bmcii_init(), bmcii_init(2), or bmcii_init3() more than once will not harm the integration (nor will it do anything positive, either).

BMCII_ALREADY_RUNNING

Explanation: The bmcii_startRecv function has been called after the Receive thread is already running.

User response: None. Calling bmcii_startRecv more than once will not affect Receive thread operation.

BMCII_BAD_BAROC

Explanation: The BAROC string that was passed to the BMC II C API using the bmcii_messageSetBaroc function is malformed and cannot be processed.

User response: Correct the BAROC string syntax.

BMCII_BAD_CLASSDEF_STREAM

Explanation: The query contains an invalid class definition data string.

User response: Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_BAD_CLASS_NAME

Explanation: The class name is missing from an event or data message. The message information may be intended for a new message or as an attempt to overwrite an existing message.

User response: Set the message class name using either the bmcii_setMessageType or the bmcii_setMetaSlotValue function. Using the bmcii_setMetaSlotValue function is recommended.

BMCII_BAD_CONFIG

Explanation: The parameter specified in a configuration function call (bmcii_get_bool, bmcii_get_dir, bmcii_get_file, bmcii_get_num, or bmcii_get_string) is missing from the integrationName.conf file, or the parameter name was specified incorrectly in the function call.



User response: Update the integrationName.conf file with the correct parameter name or fix the integration code where the configuration function is specified.

BMCII_BAD_EVENT_CREATE

Explanation: The BMC II C API is unable to create an event message.

User response: See the trace log for information.

BMCII_BAD_HEAD

Explanation: The header of a BAROC string that was passed to the BMC II C API using the bmcii_messageSetBaroc function is malformed or missing. The string cannot be converted into a message.

User response: Correct the BAROC string syntax.

BMCII_BAD_HOST_PORT

Explanation: The host and/or port specified in one of the following functions is invalid or malformed: bmcii_connect, bmcii_setupServer, or bmcii_initQueryConnect.

User response: Check the trace log to ensure that the host name and port number are formatted correctly in the function call code.

BMCII_BAD_MALLOC

Explanation: No memory is available to the BMC II C API.

User response: Free existing system memory or add memory.

BMCII_BAD_MAP_FILE_FORMAT

Explanation: There is an error in the specified map file.

User response: View the trace log for additional information. Correct the map file, if necessary. Rerun the function that called the map file.

BMCII_BAD_MAP_HEADER

Explanation: The header of one or more maps in the specified map file is missing or malformed.

User response: Correct the header in the map file and rerun the function that called the map file.

BMCII_BAD_MAP_LINE

Explanation: There is a syntax error in a line in the specified map file.

User response: View the trace log. It will specify the line that includes the error. Correct the map file. Rerun the function that called the map file.



BMCII_BAD_MAP_NAME

Explanation: The name of a map in the specified map file is missing or malformed.

User response: Correct the map name in the map file. Rerun the function that called the map file.

BMCII_BAD_MESSAGE_TYPE

Explanation: The message type specified in the message is not included in the message type enumeration.

User response: Ensure that the integration is using the correct version of the BMC II C API library. The specified message type may be supported by a version of the APIs that is not loaded.

BMCII_BAD_MUTEX

Explanation: A mutex internal to the BMC II C API is invalid.

User response: Check for a buffer overflow. Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_BAD_PARAMETER

Explanation: The integration called a function that included an invalid parameter.

User response: Check the integration code.

BMCII_BAD_PARSE

Explanation: The BMC II C API is unable to parse the reply from the BMC Impact Manager instance.

User response: View the trace log for additional information. Report the error to BMC Developer Connection. See “Support overview” on page 27.

User response:

BMCII_BAD_RECV_EVENT

Explanation: An internal event is invalid.

User response: Check for a buffer overflow. Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_BAD_SELECTOR_FILE_FORMAT

Explanation: The specified message selector set file contains an error.

User response: View the trace log for additional information. Correct the message selector set file. Rerun the function that called the message selector set file.



BMCII_BAD_SELECTOR_HEADER

Explanation: The header of one or more message selectors in the specified message selector set file is missing or malformed.

User response: Correct the header in the message selector set file and rerun the function that called the message selector set file.

BMCII_BAD_SELECTOR_LINE

Explanation: There is a syntax error in a line in the specified message selector set file.

User response: View the trace log. It will specify the line that includes the error. Correct the message selector set file. Rerun the function that called the message selector set file.

BMCII_BAD_SELECTOR_NAME

Explanation: The name of a message selector in the specified message selector set file is missing or malformed.

User response: Correct the message selector name in the message selector set file. Rerun the function that called the selector set file.

BMCII_BAD_SLOT_DEFINITIONS

Explanation: The query contains (or has returned) an invalid slot definition.


BMCII_BAD_SLOT_NAME

Explanation: The integration called a function that included a malformed or null slot name.

User response: Check and modify the integration code.

BMCII_BAD_SLOT_VALUE

Explanation: The message contains a slot with a null value or an empty string.


BMCII_BAD_SOCKETS_INIT

Explanation: Microsoft Windows only. Sockets are not initialized because the BMC II C API determines the socket library version. The version of Windows on the integration host is not supported.

User response: Verify that your integration is running only on computers that are supported by the loaded version of the BMC II C API. For a list of supported computers, see “System requirements” on page 30.



BMCII_COMM_LOCK_NOT_INIT

Explanation: Internal error.

User response: Ensure that the bmcii_init(), bmcii_init(2), or bmcii_init3() function was called correctly.

BMCII_CORRUPT_LIST

Explanation: An internal list is corrupt.

User response: Check the log for additional information. Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_EMPTY_LIST

Explanation: The list that is being searched is empty.

User response: Update the list.

BMCII_EMPTY_MESSAGE

Explanation: Internal error. The result buffer is corrupt.

User response: Check the log for more information. Remove the current receive buffer file described in the log file. A new file will be created.

BMCII_EMPTY_SLOT_NAME

Explanation: A slot name in the message is set with an empty string.


BMCII_END_DELIMITER

Explanation: A BAROC string that the integration is formatting as a message is missing an END statement.

User response: Verify the string format. Modify it, if necessary.

BMCII_ERR_BAD_FILE_NAME

Explanation: The bmcii_loadSelectorSet function specifies a null pointer or empty string for the message selector set file name. This error message can also apply to map set files specified with the bmcii_loadMapSet function.


BMCII_ERR_BAD_FILE_OPEN

Explanation: The specified map set file (or message selector set file) does not exist, or the integration does not have permission to access the specified file.



User response: Verify that the correct file name is specified in the integration code. Verify that the file exists in the location specified in the function call and that the file name is spelled correctly. Update the integration’s permissions for map and message selector set files.

BMCII_ERR_BAD_OBJECT_CREATE

Explanation: Internal error. The BMC II C API is unable to create a required object.

User response: Check for a buffer overflow and appropriate the required memory resources. Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_ERR_LOST_CONNECT

Explanation: The connection to the BMC Impact Manager instance was broken while the integration was sending a message.

User response: Disconnect from the BMC Impact Manager instance. Then, reestablish the connection and resend the message.

BMCII_ERR_MISSING_CONFIG

Explanation: The name and location of the mcell.dir file are not specified in the integrationName.conf configuration file.

User response: Check the integrationName.conf configuration file. Make any necessary corrections.

BMCII_ERROR_FROM_IM

Explanation: An error message has been received from the connected BMC IM instance.

User response: See the integrationName.trace file for more information.

BMCII_ERROR_WRONG_SLOT_TYPE



BMCII_FAILED_START_RECV

Explanation: The bmcii_startRecvThread function failed to create a new Receive thread.

User response: Check the logs and verify that the integration host computer supports POSIX or Windows native threads. Report the error to BMC Developer Connection. See “Support overview” on page 27.



BMCII_FREED_NULL_POINTER

Explanation: An internal list is corrupt.

User response: Check the log for additional information. Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_ILLEGAL_MAP_OPERATION

Explanation: The operation is not permitted in a map file.

User response: Try a different operation.

BMCII_ILLEGAL_QUERY

Explanation: The query is not supported by the loaded version of the BMC II C API.

User response: For valid query types, see the BMC II C API product documentation.

BMCII_INCOMPATIBLE_VERSION

Explanation: The version of the structure passed by the bmcii_getFirstDirectoryInfo or bmcii_getNextDirectoryInfo function is not supported by the BMC II C API library in use.

User response: Verify that the lVersion field is set properly before calling either function. Alternately, ensure that most current library version is being used by the BMC II C API.

BMCII_INDEX_OUT_OF_RANGE

Explanation: No more results are available in response to a request for the items in a list of values.

User response: This is not an error. Stop requesting additional values.

BMCII_INVALID_CALL

Explanation: Functions that must be called in a specific order were called out of order.

User response: Check the log and the integration code. Recall the functions in the correct order. For more information, refer to the function descriptions in this book or in the BMC Impact Integration Developer’s Kit C API Reference Guide.

BMCII_INVALID_CONFIGFILE

Explanation: The configuration file parameter of the bmcii_init(), bmcii_init(2), or bmcii_init3() function is invalid.

User response: Verify the configuration file parameter.



BMCII_INVALID_FUNCTION_FORMAT

Explanation: The map set (or message selector set) specifies a function that includes one or more invalid parameters.

User response: Modify the map set file or message selector set file to correct the problem.

BMCII_INVALID_HOMEDIR

Explanation: The home directory parameter of the bmcii_init(), bmcii_init(2), or bmcii_init3() function is invalid.

User response: See the release notes. Or report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_INVALID_IP_ADDRESS

Explanation: The function has passed an invalid IP address.

User response: Verify the IP address. Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_INVALID_LEN

Explanation: The length of the encrypted string is invalid.

User response: Verify the string length.

BMCII_INVALID_QUERY_PARAMETER

Explanation: The query parameter is invalid.

User response: Verify the parameter.

BMCII_INVALID_QUERY_RESULT

Explanation: The component query result is invalid—for example, it is not a valid count number.


BMCII_INVALID_QUERY_TYPE

Explanation: The query result contains an invalid query type.


BMCII_INVALID_SERVER_NAME

Explanation: The cell name specified in the bmcii_connect, bmcii_serverSetup, or bmcii_queryInitConnect function is invalid.



User response: Check cell name specified in the function and in the mcell.dir file.

BMCII_INVALID_STRING_FORMAT

Explanation: The string format is invalid.

User response: Verify the string format.

BMCII_MAP_DISABLED

Explanation: The map specified in the bmcii_translate function call is disabled.

User response: This is not an error. However, if the map was disabled unintentionally, enable it and rerun the bmcii_translate function.

BMCII_MAP_LOOP_DETECTED

Explanation: The $domap function is creating a loop in the map set.

User response: Correct the map set file to eliminate the loop.

BMCII_MAPSET_DISABLED

Explanation: The integration did not perform any translation operation because the specified map set was disabled. This error message does not necessarily describe an error, since disabling an entire map set is supported.

User response: If disabling the map set is intentional, no response is necessary. If the map set was disabled unintentionally, enable the map set and rerun the bmcii_translate function.

BMCII_MEMORY_CORRUPTED_END

Explanation: An internal structure is corrupt.

User response: Check for a buffer overflow and appropriate the required memory resources. Report the problem to BMC Software Customer Support.

BMCII_MEMORY_CORRUPTED_START

Explanation: An internal structure is corrupt.

User response: Check for a buffer overflow and appropriate the required memory resources. Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_MESSAGE_CORRUPTED

Explanation: The message that was passed to the BMC II C API is invalid or corrupt.

User response: Verify that the correct message was passed. Check for a buffer overflow. Report the error to BMC Developer Connection. See “Support overview” on page 27.



BMCII_MISSING_MOD_INFO

Explanation: The event modification that was sent did not include an mc_ueid ID or event handle to identify the event that was to be modified. The data modification that was sent did not include an mc_udid ID or data handle to identify the data object that was to be modified.

User response: Check the integration code to ensure that the required ID slots are included. Modify the message, if necessary.

BMCII_MISSING_REQUIRED_SLOT

Explanation: The function is missing a required slot.

User response: Verify the parameters.

BMCII_MISSING_UDID

Explanation: The component object does not contain an mc_udid slot.

User response: Verify the slots. Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_MUST_CALL_INIT

Explanation: The BMC II C API is not initialized. All function calls (except for bmcii_version) can be performed only after bmcii_init3() is called.

User response: Call the bmcii_init3() function and recall the failed function.

BMCII_NEED_LOCKS_FOR_THREAD

Explanation: The bmcii_start RecvThread function cannot create a thread because the UseLocks parameter is missing from the configuration file or is included but set to NO or OFF.

User response: Add the UseLocks parameter to the integrationName.conf configuration file and set it to ON. If UseLocks is already included in the file, change its value to ON.

BMCII_NEED_MORE_MEMORY

Explanation: Fatal error. Failure to allocate memory.

User response: Free existing system memory or add memory.

BMCII_NO_MORE

Explanation: There are no more items in the list.

User response: This is not an error. Stop calling the iterating function.

BMCII_NO_RESULT_YET

Explanation: A query result has not yet been returned.



User response: This is not an error. Recall bmcii_getQueryReply until the BMC Impact Manager instance returns a reply.

BMCII_NOT_VALID_MEMORY

Explanation: A memory usage error has occurred.


BMCII_NOT_FOUND

Explanation: The requested item (such as a slot) does not exist.

User response: Check the integration code to verify that the requested item exists and is spelled correctly in the code.

BMCII_OPERATION_NOT_SUPPORTED

Explanation: The BMC IM instance to which your integration is connected does not support this operation.

User response: Check the operation that you are attempting and verify the version of the cell. You may need to connect to a different cell.

BMCII_QUERY_CONNECTION_DOWN

Explanation: The query connection was broken during the processing of a query.

User response: Reestablish the query connection and recall the failed query.

BMCII_QUERY_ERROR

Explanation: The BMC Impact Manager instance returned an error.

User response: For more information, see the BMC Impact Manager instance and integration logs.

BMCII_QUERY_FAILED

Explanation: The query request has failed.

User response: Verify the function call sequence. Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_QUERY_REGISTRATION_FAILED

Explanation: Following an attempt to establish a query connection with a BMC Impact Manager instance using the bmcii_initQueryConnect function, the BMC Impact Manager instance returned an error and the connection failed.

User response: Check the log for more information.



BMCII_REGISTRATION_FAILED

Explanation: A connection has timed out.


BMCII_REGISTRATION_TIMED_OUT

Explanation: The attempt to establish a query connection has timed out while it waits for a query connection.


\BMCII_REQUEST_OUT_OF_RANGE

Explanation: The requested placeholder is not in the list.

User response: This is not an error. Stop calling the iterating function.

BMCII_SELECTOR_DISABLED

Explanation: A return code from the group match selection functions, it indicates that the message selector set or all message selectors are disabled.

User response: This is not necessarily an error, as you may have decided to disable the message selector set or message selectors. The integration component determines how to process this return code.

BMCII_SELECTOR_LOOP_DETECTED

Explanation: The $doselector function is creating a loop in the message selector set.

User response: Correct the message selector set file to eliminate the loop.

BMCII_SLOT_SIZE_NOT_MATCH

Explanation: The size of the slot name and the slot value do not match.


BMCII_SUCCESS

Explanation: The function call (specified by its return code) was successful. This is not an error. This code is returned for all successful function calls.

User response: None.

BMCII_TERM_CALLED

Explanation: The integration called a function after the BMC II C API was terminated.


BMC II C API informational messages

User response: Re-initialize the BMC II C API and recall the required function. Examine the integration code and correct any problems.

BMCII_TIMED_OUT

Explanation: The timeout period specified in the function expired before any results were returned.

User response: This is not an error. You can recall the function until the results are available.

BMCII_UNKNOWN_CHARACTER_IN_HEX

Explanation: The Hex-encoded string contains an illegal character.

User response: Verify the character string. Report the error to BMC Developer Connection. See “Support overview” on page 27.

BMCII_UNKNOWN_FUNCTION

Explanation: The loaded map set or message selector set file specifies a BMC II C API function not supplied by the BMC II C API library in use.

User response: Check the map set or message selector set file to ensure that the appropriate function is specified. Verify which version of the BMC II C API library is loaded to ensure compatibility.

BMCII_UNKNOWN_SLOT_TYPE



BMCII_UNKNOWN_TYPE

Explanation: The message type that is being passed to the message is unknown. This can happen when setting the message type with the bmcii_setMessageType function or setting META_MSG_TYPE using the bmcii_setMetaSlotValue function.

User response: In the integration code, check the parameter value being passed as the message type.

BMC II C API informational messagesThe following BMC II C API messages do not indicate errors. Instead, they are informational only.


Informational messages listed by code

Informational messages listed by code

Table 139 lists the informational messages by numerical code.

Informational messages listed alphabetically

This section lists the informational messages alphabetically. It explains the message and describes any user action that might be needed.

FILTER_OUT_MATCH

Explanation: The program did not find a match for the message in the filter-in message selector set. The message is discarded.

NO_FILTER_IN_MATCH

Explanation: The program found a match for the message in the filter-out message selector set. The message is discarded.

Core communications errorsErrors with the IM prefix are core communications errors in the BMC II C API. Errors that are related to other aspects of the BMC II C API are described in “BMC II C API errors” on page 370.

Errors are listed by error code and alphabetically (starting on page 388). The alphabetic listing includes a description of each error.

Core communication errors listed by error code

Table 140 lists BMC II C API core communications errors, arranged by error code.

Table 139 Messages listed by code

Code Message name Described on

-301 NO_FILTER_IN_MATCH page 386

-302 FILTER_OUT_MATCH page 386


Core communication errors listed by error code

Table 140 Core Communications Error Codes


0 IM_ERR_NONE page 391

1 IM_ERR_UNINITIALIZED page 392

2 IM_ERR_INIT_CONFIG page 389

3 IM_ERR_TRACE_CONFIG page 391

4 IM_ERR_INIT_COMM_OUT page 392

5 IM_ERR_INIT_COMM_IN page 389

6 IM_ERR_INIT_MSGS page 389

7 IM_GW_ERR_INIT_PERSIST page 392

8 IM_ERR_INIT_PORT_RANGE page 391

9 IM_ERR_INIT_CRYPT page 389

10 IM_ERR_NOTRANSPORT page 391

11 IM_ERR_NOENDPOINT page 391

12 IM_ERR_NOBIND page 390

13 IM_ERR_MEMFAULT page 390

14 IM_ERR_BAD_IP page 388

15 IM_ERR_BAD_LOCATION page 388

16 IM_ERR_NAME_LOOKUP page 390

17 IM_ERR_SVC_UP page 391

18 IM_ERR_SVC_DOWN page 391

19 IM_ERR_INVALID_CNC page 389

20 IM_ERR_INVALID_MSGTYPE page 389

21 IM_ERR_CONNECT page 388

22 IM_ERR_TIME_OUT page 391

23 IM_ERR_NOCONNECT page 391

24 IM_ERR_NOBUFFER page 390

25 IM_ERR_NOCONTACT page 390

26 IM_ERR_SEND page 391

27 IM_GW_ERR_INVALID_MSG page 392

28 IM_GW_ERR_FILEREAD page 392

29 IM_ERR_TRBADMOD page 392

30 IM_ERR_TRBADLVLSW page 392

31 IM_ERR_TRBADDEST page 392

32 IM_ERR_TRDUPMODDEF page 392


Core communications errors listed alphabetically


Each core communications error is listed alphabetically and includes a description of the error and prescriptive information, if any is available.

IM_ERR_BAD_IP

Explanation: The syntax of the IP address that was passed to the bmcii_connect(), bmcii_initQueryConnect(), or bmcii_setupServer() function is invalid.

User response: Verify the correct IP address of the target BMC Impact Manager instance, and ensure that the correct address is specified in your integration code.

IM_ERR_BAD_LOCATION

Explanation: The service location that was passed to the bmcii_connect(), bmcii_initQueryConnect(), or bmcii_setupServer() function is invalid.

User response: Verify the host name of the target BMC Impact Manager instance, and ensure that the correct name is specified in your integration code.

IM_ERR_CONNECT

Explanation: The integration’s attempt to connect to a BMC Impact Manager instance, using bmcii_connect() or bmcii_initQueryConnect(), failed. The integration will not retry to reconnect.

User response: Check that the destination is defined correctly in the mcell.dir file and that the requested server is on destination computer. For a query, disconnect and then call the bmcii_initQueryConnect() function again.

IM_ERR_INVALID_CNC

Explanation: The query connection handle is invalid.

User response: Try connecting again by calling the bmcii_initQueryConnect() function.

IM_ERR_INIT_COMM_IN

Explanation: Initialization of the inbound communication module in the BMC II C API failed.

User response: Stop and restart the integration.

IM_ERR_INIT_COMM_OUT

Explanation: Initialization of the outbound communication module in the BMC II C API failed.



User response: Stop and restart the integration. Ensure that no other application is using the requested port.

IM_ERR_INIT_CONFIG

Explanation: The configuration has failed to initialize. The integration configuration directory, the path to the .conf configuration file or the contents of the configuration file are invalid.

User response: Verify that all integration code references to the integration configuration directory and to the .conf file are correct. Verify that the .conf file does not contain any errors.

IM_ERR_INIT_CRYPT

Explanation: The encryption key has failed to initialize. The connection was made using an invalid encryption key.

User response: For information about using encryption, see “Encryption key matching” on page 93 and “Encryption” on page 170.

IM_ERR_INIT_MSGS

Explanation: The initialization of the message handling mechanism has failed.


IM_ERR_INIT_PORT_RANGE

Explanation: The connection port range has failed to initialize. The port range specified with the ConnectionPortRange parameter in the integrationName.conf file is invalid.

User response: Specify a port range that is valid for the host operating system. For more information about the ConnectionPortRange parameter, see Table 10 on page 49.

IM_ERR_INVALID_CNC

Explanation: The integration passed or received an invalid or closed connection handle. This error is displayed for connections initiated by the integration (acting in client mode) and connections directed to the integration (acting in server mode).

User response: Discard the connection handle that is currently in use: If the integration initiated the connection with the problematic handle, make a new connection attempt. A new handle is assigned. If the integration was acting as a server, continue listening for another connection request.

IM_ERR_INVALID_MSGTYPE

Explanation: The integration has passed an invalid message type.




IM_ERR_MEMFAULT

Explanation: The BMC II C API cannot allocate memory.

User response: Do one or both of the following: free resources or stop and restart the integration. Also, check the integration code for memory leaks.

IM_ERR_NAME_LOOKUP

Explanation: The host name lookup failed.

User response: Check the entries in the mcell.dir file and/or check that the DNS service is working correctly.

IM_ERR_NOBIND

Explanation: The integration cannot start server mode using the specified port number. The port is being used by another application or is privileged.

User response: Check whether the port is in use. If the port is in use, specify that the integration use a different port or stop the application that is currently using the port. If port use is privileged, specify that the integration use a different port or run the integration as privileged user.

IM_ERR_NOBUFFER

Explanation: The message buffer is full, an no buffers are available for the destination message.

User response: Increase the buffer size. Modify the value of the MessageBufferSize parameter in the integrationName.conf configuration file.

IM_ERR_NOCONNECT

Explanation: The integration sent a message containing the META_FAIL_IF_UNCONNECTED metaslot when no connection was established.

User response: None.

IM_ERR_NOCONTACT

Explanation: Currently, no connection is established to the message destination. The message will be buffered.

User response: Ensure the availability of the BMC Impact Manager instance or integration to which the message is directed.

IM_ERR_NOENDPOINT

Explanation: The service endpoint cannot be opened.




IM_ERR_NONE

Explanation: The function call, as specified by its return code, was successful.

User response: This is not an error. All successful function calls return this code.

IM_ERR_NOTRANSPORT

Explanation: The TCP/IP stack on the integration host is not available.

User response: Verify that the operating system recognizes the TCP/IP stack and that the appropriate adapters are available.

IM_ERR_SEND

Explanation: The connection attempt failed. This error is displayed for connections initiated by the integration (acting in client mode) and connections directed to the integration (acting in server mode).

User response: If the integration initiated the connection failed attempt, you can make an additional connection attempt. If the integration was acting as a server, continue listening for additional connection requests.

IM_ERR_SVC_DOWN

Explanation: The integration called the bmcii_stopServer function when server mode was not running.

User response: Check the integration code to determine why bmcii_stopServer was called two (or more) times.

IM_ERR_SVC_UP

Explanation: The integration called the bmcii_startServer when the integration was already in server mode.

User response: Check the integration code to determine why bmcii_startServer was called two (or more) times.

IM_ERR_TIME_OUT

Explanation: The timeout period expired for one of the functions that uses a timeout. This is a notice, not an error.

User response: None, unless you want to rerun the function that timed out.

IM_ERR_TRACE_CONFIG

Explanation: The trace configuration file has failed to initialize. The tracing configuration file (integrationName.trace) is missing, configured incorrectly, or described incorrectly in the integration code.


Reportable error codes

User response: Locate the file. Ensure that integration code includes the correct name and path to the file. Fix any errors that the file may contain.

Reportable error codes

Report any of the following error codes to the BMC Developer Connection Web site at http://devcon.bmc.com/:

■ IM_ERR_TRBADDEST■ IM_ERR_TRBADLVLSW■ IM_ERR_TRBADMOD■ IM_ERR_TRDUPMODDEF■ IM_ERR_UNINITIALIZED■ IM_GW_ERR_FILEREAD■ IM_GW_ERR_INIT_PERSIST■ IM_GW_ERR_INVALID_MSG

NOTE At the time of publication, BMC intends to eventually migrate the content of the BMC Developer Connection website to the BMC Developer Network website at http://developer.bmc.com.




http://devcon.bmc.com

A p p e n d i x E
E Gateway Configuration

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394Communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Contents parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Format parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397Variable reference allowance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399Parameter examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

Native BMC Impact Manager propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400TEC gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400


Introduction

IntroductionFor some integrations, it may be necessary to change the content of the messages sent to the integration from a BMC Impact Manager instance. Using a gateway configuration file, you can change the message content. You must copy the gateway file to all BMC Impact Manager instances that will be sending messages with modified content.

Gateway-specific message formats are described in a gateway configuration file. The location of this file for Gateway <Type> is determined from the BMC Impact Manager instance Gw<Type>ConfigFileName parameter. Its default value is %H/etc/gateway.<Type> where <Type> stands for the type of gateway.

Some example default parameter values for TEC and NetCool gateways follow:

■ GwTECConfigFileName=%H/etc/gateway.TEC, which means: $MCELL_HOME/etc/gateway.TEC

■ GwNetCoolConfigFileName=%H/etc/gateway.NetCool, which means: $MCELL_HOME/etc/gateway.NetCool

A gateway configuration file contains parameter settings in the form parameter=setting.

Parameters can be specified differently for new events and for event modifications. The parameter name must end with one of the following extensions:

■ .new – for new events■ .mod – for event modifications

Without the extension, the setting applies to both categories.

Parameters specify both the contents of a message and its format.

Table 141 lists parameters that can refer to predefined variables.

Table 141 Predefined Variables

Predefined Variable Parameter

$CLASS Class name

$CONTEXT Context* name (* See the Contexts descriptions below)

$DATE Date stamp

$TIME Time stamp

$MODNMS Names of modified slots (empty for 'new')

$GHANDLE Event ID in gateway


Introduction

* Contexts:

Table 142 lists text parameter values consisting of literal text, possibly mixed with references to variables and with escape sequences.

References to variables that are not followed by punctuation or space characters must be enclosed in curly brackets ({ }). For example, $NAMEabc is invalid; use ${NAME}abc instead.

$CNAME name of the BMC Impact Manager instance connecting to the gateway

$CHANDLE Event ID in a BMC Impact Manager instance

$VALUE (<slot>)Value of slot <slot>

$NAME Selected slot name (only for body parameter)

$VALUE Selected slot value (only for body parameter)

$MODS All modified slots (empty for 'new')

$ALL All slots (only for slots parameter)

$ALL (<cls>)All slots, but limited to class <cls> (only for slots parameter)

Permanent Event permanently in DB (until out-of-date)

Processed Discarded by rule processing

Regulated Discarded by regulation

Filtered Discarded by filter

Refined Discarded by refine

Received Discarded immediately

Table 142 Text Parameter Values

\s Space

\n Newline

\r Carriage-return

\t Tab

\0ddd Character code in octal (0, 1, 2 or 3 digits d)

\\ Backslash

Table 141 Predefined Variables

Predefined Variable Parameter


Communication parameters

Communication parameters

Contents parameters


protocol= Communication protocol to be used. Both categories (new event and modification) use the same protocol. The last one specified is used.

The range of values include

■ MCELL Number — Native BMC Impact Manager protocol, with Number indicating the Native BMC Impact Manager protocol level

■ EIF — Tivoli Enterprise Console EIF format

The default protocol value is MCELL.


cond= Defines the condition for slots to be included in the $ALL variable

The range of values includes

■ always — always include all slots

■ propagate — include if the slot is eligible for propagation: that is, it can be parsed and is a non-default value

The default values are indicated by

■ cond.new — propagate

■ cond.mod — always

drop=[] Lists slots that must be dropped from the $ALL and $MODS variables. The list consists of comma-separate slot names. Only real slot names are indicated.

The default value is drop = [ ].


Format parameters

Format parameters

add=[] lists additional new slot definitions. The list consists of comma-separated settings in the slotname=slotvalue format, where slotname is a name for a newly defined slot, and slotvalue determines the value of the new slot.

Slot values can be literal values, or they can be predefined variable values.

Additional slots are included in the $ALL variable. They are also included in the $MODS variable, except when their value refers to a real slot value. If their value refers to a real slot value, then they are included only if the indicated slot is modified.

The default value is add=[].

slots=[] lists slots whose values must be included in the message. The list consists of comma-separated slot names. You can specify standard class defined slots and additional defined slots.

Non-base class slots must be prefixed with <ClassName>:. Base class slots can also be prefixed with <ClassName>:. In the latter instance, the slot will be included only if the event object is of the indicated class.

You can use variables in place of real slot names. The order determines the order of slots in the message.

The default value is slots=[].

modify=[] lists slots whose modifications result in a message. Modifications of slots that are not included in this list are ignored. In an empty list, any slot modifications result in a message. The list consists of comma-separated slot names. Only real slot names can be modified. The modify=[] parameter applies only to modifications. The default is modify.mod=[].


init= message initialization sequence. This is a text value with references to variables.

Default=init=.

body= message body, that is applied to each slot included in the message. This is a text value with references to variables.

Default=body=.

term= message termination sequence. This is a text value with references to variables.

Default=term=.



Format parameters

separator= slot separator sequence to be inserted between two body units. It is a text value with references to variables.

Default=<empty>.

quotable= characters that lead to an item in quotation marks that appear in a slot value. This is a text value with references to variables.

The default is standard MRL quotation rules.

openquote= opening quotation mark character to use for values that must be quoted. This consists of a single character text value.

Default= ‘

closequote= closing quotation mark character to user for values that must be quoted. It consists of a single character text value. If no value is supplied, it is the same as the openquote value.

Default= ‘

escapequote= indicates quotation character within a quoted value. It consists of a single character text value.

Default= ‘



Variable reference allowance

Variable reference allowanceVariable references are allowed as listed in the matrix in Table 143.

Table 143 Variable References

add slots init body term

$CLASS + + + + +

$CONTEXT + + + + +

$DATE + + + + +

$TIME + + + + +

$MODNMS + - + - +

$GHANDLE + + + - +

$CNAME + + + - +

$CHANDLE + + + - +

$VALUE() + - + - +

$NAME - - - + -

$VALUE - - - + -

$MODS - + - - -

$ALL - + - - -

$ALL() - + - - -


Parameter examples

Parameter examples

Native BMC Impact Manager propagation

TEC gateway

cond.new=propagatecond.mod=alwaysslots.new=[$ALL]slots.mod=[$MODS]init.new=$CLASS;\ninit.mod=modify $GHANDLE;\nbody=\t$NAME=$VALUE;\nterm=END\nopenquote='closequote='escapequote='

protocol=EIFcond.new=propagatecond.mod=alwaysdrop=[mc_history,date_reception,status]add.new=[mcgw_ghandle=$GHANDLE, mcgw_cname=$CNAME, mcgw_chandle=$CHANDLE, mcgw_status=$VALUE(status)]add.mod=[mcgw_ghandle=$GHANDLE, mcgw_status=$VALUE(status), mcgw_modifs=$MODNMS]slots.new=[$ALL]slots.mod=[$MODS]init=$CLASS;\nbody=\t$NAME=$VALUE;\nterm=END\n


A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Glossary

AAbstract phase

The event-processing phase in which Abstract rules are evaluated and, if conditions are met, abstraction events are generated. See also abstraction event.

Abstract ruleAn event-processing rule that creates an abstraction event from one or more raw events. See also abstraction event.

abstracted eventAn event that contributes to the creation of an abstraction event. The abstracted event is the basis for inferring that some condition exists. For example, if a critical subprocess of an application is down, the application is down. See also abstraction event.

abstraction eventA conceptual or summary event based on other events that are occurring. You cannot understand the context of an abstraction event by its details. To understand its context, you must view the relationships between the abstraction event and the events that triggered its creation in the BMC Impact Explorer Events tab, Relationships window. See also abstracted event.

AcknowledgeThe event operation action that acknowledges the existence of an event. See also local action.

Acknowledged statusThe event status that results from an Acknowledge event operation action; it means that an operator has acknowledged the event's existence.

action1. Generally, a procedure that is invoked to produce a specific result. It can be a script or a call to an executable that is invoked automatically in response to an event, or it can be a manual intervention. Actions can be scheduled or immediately invoked locally or remotely.

2. In BMC Impact Manager, an executable that can be run by a cell. Actions are called in an Execute rule. Users can request the execution of actions in the BMC Impact Explorer. See also local action and non-local action.

Glossary 401


adapterA background process that audits data from various sources, evaluates it for specific conditions, and creates the corresponding events. Adapters also transform event data into the format understood by BMC Impact Manager.

adapter instanceAn instance of an adapter that is defined in the adapter configuration file. The definition is given a name and specifies an adapter type, such as a log file adapter.

adapter map fileA text file that defines the translation of a message between one event format and another. It is also known as a .map file.

Administrative ViewThe BMC Impact Explorer user interface for cell administration. Administrative users can start, pause, stop, and reconfigure a cell by using this interface. They can also make changes to a cell’s dynamic data tables. You access this view by clicking the Administration tab in BMC Impact Explorer.

administratorThe person responsible for administrative tasks within the product.

aliasSee service component alias.

annotated data pointA specially marked point on a parameter graph that provides detailed information about a parameter at a particular moment. The associated data is accessed by double-clicking the data point, which is represented by a user-specified character.

API See Application Program Interface (API).

Application Program Interface (API) A set of externalized functions that allow interaction with an application.

assetAn object instance in the BMC Atrium Configuration Management Database (BMC Atrium CMDB). There are two types of assets in the BMC Atrium CMDB: non-service components, such as desks and other non-IT physical assets, and service components that participate in the delivery of enterprise services.

asset inventoryThe list of all physical and logical assets that have an identifiable value to the organization or against which threats and vulnerabilities can be identified and quantified as part of risk assessment.



Assign To The event operation action that assigns the responsibility for an event to an individual.

Assigned statusThe event status that indicates that the specified operator is responsible for the event. It results from the Assign To or the Take Ownership event operation actions.

attributeA characteristic or property of an object, such as a common-data-model service-model component class. An attribute may contain a value.

automationIn BMC Impact Explorer, operator responses that have been programmed to occur automatically when an event is received.

BBAROC language

Basic Recorder of Objects in C. A structured language used to create and modify class definitions. A class definition is similar to a structure in the C programming language. The elements in a BAROC class are called slots.

base class In programming, a root superclass, a class from which all other classes of its type are derived.

base priorityA static priority value that is combined with the component's current status to determine the final self-priority value. Typically, the base priority determines the highest self-priority that a component will reach when its status become Unavailable.

blackout scheduleA schedule that determines when one or more components will be automatically placed in a blackout state.

BMC Atrium CMDB Common Data Model (BMC Atrium CMDB CDM)An extensible schema that provides a unified representation of configuration items and their relationships to each other. It is used to store asset data (such as hardware information, service management information, and people information) and to provide a mechanism for linking that information to provide a complete view of how all assets are connected and can affect each other.

BMC Atrium CMDB Reconciliation EngineThe BMC Atrium CMDB application used to merge data from multiple sources, such as topology discovery and configuration discovery, into a consistent dataset.

Glossary 403


BMC Atrium Configuration Management Database (BMC Atrium CMDB)The database application that is the common datastore for asset, configuration management, and service model data in BMC Business Service Management products. It enables BMC products to share IT management and monitoring data and perform service management.

BMC Desktop Status Indicator (BMC DSI)An icon that appears in the desktop system tray of a computer to show the current status of an object being monitored by BMC Impact Portal. To view the status page of the monitored object, you double-click the icon.

BMC Event Manager (BMC EM)A real-time event management product license package that provides event management, including event collection, correlation, enrichment, and integration. It enables IT operations staff to focus the proper resources on resolving the most critical events.

BMC EMSee BMC Event Manager (BMC EM).

BMC IDG See BMC Impact Database Gateway (BMC IDG).

BMC IEA See BMC Impact Event Adapters (BMC IEA).

BMC IELA See BMC Impact Event Log Adapter for Windows (BMC IELA).

BMC Impact Database Gateway (BMC IDG)The interface that enables BMC Impact Manager events to be exported to a relational database.

BMC Impact Event Adapters (BMC IEA)The adapters that collect log file information, convert it to BMC Impact events, and send the events to designated BMC Impact Manager instances.

BMC Impact Event Log Adapter for Windows (BMC IELA)The native Windows platform executable that audits Windows event logs. It runs as a Windows service and checks for new event log records.

BMC Impact Explorer (BMC IX)The console with which you can connect to BMC Impact Manager instances, examine the events stored in them, and perform event and service management activities.

BMC Impact Explorer ServerObsolete term. See BMC Impact Portal.



BMC Impact Integration product (BMC II product) An interface that enables the synchronized flow of events and data between a BMC Impact Manager instance and another BMC Software product or a specific third-party product.

BMC Impact Manager (BMC IM)The BMC Impact product that provides automated event and service impact management. It runs as a service on supported Windows platforms and as a daemon on UNIX platforms, and can be distributed throughout the networked enterprise and connected in various topologies to support IT goals.

BMC Impact Manager instanceAn installation of the BMC Impact Manager product on a host computer. Compare with cell.

BMC Impact Publishing ServerThe BMC Impact Portal service or daemon that obtains the service model from the BMC Atrium CMDB and publishes (distributes) it to the designated service impact management cell or cells.

BMC Impact PortalThe BMC Portal module that you use to monitor the status of business services and their components.

BMC Impact ReportingThe BMC Impact Solutions component that you use to create and view long-term reports.

BMC Impact Service Model EditorA graphical editor that you use to develop, maintain, and extend the service model that is stored in the BMC Atrium Configuration Management Database (BMC Atrium CMDB).

BMC Impact Web Console (BMC IWC)Obsolete term. See BMC Impact Portal.

BMC IWCObsolete term. See BMC Impact Portal.

BMC IX See BMC Impact Explorer (BMC IX).

BMC IXSObsolete term. See BMC Portal.

BMC PortalA BMC product that consists of the BMC Portal Server (infrastructure) and console modules, each of which deliver specific Business Service Management (BSM) functionality. The BMC Impact Portal and BMC Performance Manager Portal are examples of console modules.

BMC Reporting FoundationThe base component on which BMC Software reporting systems and solutions are built.

Glossary 405


BMC Service Impact Manager (BMC SIM)A real-time service impact management product license package that provides technologies for both service impact and event management. BMC SIM identifies related applications and the underlying systems and databases of any software or infrastructure component and ties systems-level monitoring to the supported business services, enabling IT personnel to respond quickly to problems that threaten the delivery of business services.

BMC SIMSee BMC Service Impact Manager (BMC SIM).

BMC_System classIn the BMC Atrium CMDB Common Data Model, the parent class for all system information. In this class tree, classes representing computer systems, mainframes, application systems, and virtual systems are defined.

built-in actionAn automated, predefined action performed by a system.

business functionA group of business processes that make up a specific function, such as customer support.

business objectsAn object defined in the BMC Impact Service Model Editor, published to a BMC Impact Manager instance, and monitored in BMC Impact Portal. Business objects contribute business service data for use in status indicators and reports.

business processA series of related business activities that operate to achieve one or more business objectives in a measurable way. Typical business processes include receiving orders, marketing services, delivering services, distributing products, invoicing for services, and accounting for money received. A business process rarely operates in isolation. It depends on other business processes, and other business processes, in turn, rely on it. A business process usually relies on several business functions for support, such as IT and Personnel.

business process decompositionThe identification and cataloging of the business activities and IT resources that combine to make up a business process. The result of business decomposition is a business process model.

business serviceA service that is identifiable by business representatives and supports explicit business processes that have a clear link to the business’s value chain. Most business services have an easily identifiable senior business representative, are composed of a number of specific applications, and rely on the functioning of infrastructure services. For example, the provision of all logistic components underpinning the sale of consumer goods is a business service. See also service.



Business Service Management (BSM)A dynamic method for connecting key business services to the IT systems that manage them. BSM enables users to understand and predict how technology changes will affect their business, and how changes in the business affect the IT infrastructure.

Ccause event

In a sequence of events, the event that is identified as the cause of the other events. See also effect event.

CDMSee BMC Atrium CMDB Common Data Model (BMC Atrium CMDB CDM).

cellThe event processing engine that collects, processes, and stores events within a BMC Impact Manager instance. Each cell uses the information in its associated Knowledge Base to identify the types of events to accept and how to process and distribute them.

child collectorA collector contained within another collector. See also event collector.

class1. A data storage element. In database terms, it relates to a table in a database or a form in the Remedy AR System.

2. In BMC Impact Manager, a BAROC-language data structure that defines a type of object used in BMC Impact Manager. A BAROC class is made up of data fields, called slots, that define its properties.

3. In BMC Impact Portal: see object class.

CLI commandA command that is issued on the OS command line for automation or immediate execution. For a complete list of CLI commands, see BMC Impact Solutions: Administration. See also command line interface (CLI).

CloseThe event operation action that closes an event. If the event was assigned to the current user, Close sets the status to Closed and shows an Operator Closed entry in the operation history. Otherwise, Close sets the status to Closed and shows an Override Closed entry in the operation history.

Closed statusThe event status that results from a Close event operation action.

Glossary 407


CMDB See BMC Atrium Configuration Management Database (BMC Atrium CMDB).

collector See event collector.

collector rule See event collector rule.

collector set See event collector set.

command line interface (CLI)A user interface in which you issue commands one at a time on a command line for automation or immediate execution. In BMC Impact Manager, you use the CLI in conjunction with a graphical user interface (GUI) to operate the product.

componentA logical or physical asset that is represented in the BMC Atrium CMDB. There are two types of assets represented in the BMC Atrium CMDB: non-service components, such as desks and other non-IT physical assets, and service components that participate in the delivery of business services. See also service component.

component instanceA named component that represents an actual IT resource. See also service component.

component poolA reference to all of the logical and physical assets that participate in the delivery of enterprise services and can be part of the service model. The component pool includes both assets that are part of the service model and assets that are not. See also object and component.

component relationship See service component relationship.

component typeIn the Service Model Editor, an icon with an editable template that represents a specific common data model component class. A user can select a component type and edit its template to create a new instance of the component class.

computed prioritySee priority.

configuration management database (CMDB) See BMC Atrium Configuration Management Database (BMC Atrium CMDB).



consoleOne of the following commonly BMC Impact Manager product GUIs: BMC Impact Portal, BMC Impact Explorer, BMC Impact Reporting Console, and Service Model Editor.

console local actionAn action taken from a console and that is executed on the console host computer.

consolidation nodeA BMC Impact Manager instance that can receive and process events originating from other systems on the network.

consumerIn a service model component relationship, the component that uses a service provided by another component, the provider. See also provider.

core competencyCapabilities that collectively account for all business activities within a business enterprise, such as planning and developing products.

CORE_DATA classThe base class for all BMC Impact Manager BAROC data classes. It is the parent class for all customized data classes.

CORE_EVENT classThe base class for all BMC Impact Manager event classes. It is the parent class for all customized event classes.

Correlate phaseThe event-processing phase in which the Correlate rules are evaluated to determine whether any events have a cause-and-effect relationship. See also Correlate rule.

Correlate ruleAn event-processing rule that establishes the cause-and-effect relationship between two events. Correlate rules represent a one-to-one relationship.

correlation1. The process of identifying a cause-and-effect relationship between two events from one or more sources for the purpose of identifying a root cause.

2. The cause and effect relationship itself.

3. A type of policy.

Glossary 409


Ddata class

A BAROC class that is a child of the base data class, CORE_DATA, and that defines a type of data. Users can create their own data classes.

datastoreA central place in which an aggregation of data is kept and maintained in an organized way.

Decline OwnershipThe event operation action that indicates that the assigned operator does not accept responsibility for an event. Decline Ownership clears the owner’s name, sets the status back to Acknowledged, and shows a Declined entry in the operation history.

default status view typeIn the BMC Impact Portal, one of the view types available from the Status tab.

Delete phaseThe event-processing phase in which Delete rules are evaluated and actions are taken to ensure that data integrity is maintained when an event is deleted from the event repository during the cleanup process.

Delete ruleAn event-processing rule that is used to clean up obsolete information when an event is deleted from the repository. Delete rules are evaluated when an event is deleted and they take actions to ensure that data integrity is maintained.

destinationOne end of a relationship. In the case of an impact relationship, it is the end associated with the consumer of events.

draft service modelA working version of the service model that can contain both published and unpublished elements.

duplicate eventA subsequent occurrence of an event that has already been received, such as the second or later notification that a component is down. An event that has matching values for all the slots defined with the dup_detect=yes facet in the event class definition. You can use Regulate rules to detect and count duplicate events. See also facet.

During ScheduleTime periods in which a component has a higher service demand and higher importance than in the off-schedule time period. In a During Schedule time period, the component is typically assigned a higher priority value and downtime cost than during an off-schedule time period.



For example, if a high service demand occurs during 9:00 AM and 5:00 PM, you can create a During Schedule timeframe for that time period. See also off-schedule time and Exceptions Within During Schedule.

During Schedule costThe outage cost (per second) related to the component when the outage occurs within the During Schedule timeframe.

dynamic collectorA special type of collector that, in response to events, can add or remove event collectors from the cell during runtime.

dynamic dataContextual reference data that is stored in a table in the event repository (mcdb) and that is updated during runtime if the context has changed. Administrators can use and manipulate dynamic data in the BMC Impact Explorer Administration View.

EECF

See Event Condition Formula (ECF).

effect eventIn a sequence of events, the event that is identified as an effect of a cause event. See also cause event.

elected event See impact event.

encryption keyThe seed encryption key. If the destination product has a key value, all clients must encrypt their communications using the same key value.

enrichment1. The process of adding to or modifying the original event data to enhance it for problem management, service management, correlation, automation, notification, or reporting functions.


escalation1. The process of referring a problem up the chain of command.


Glossary 411


escalation procedureThe particular steps defined for performing escalation. For example, you might specify that operations personnel would be notified within 5 minutes of a problem occurrence, a manager would learn of it after 15 minutes, and a director after 1 hour (if the problem still exists).

eventIn a BMC Impact environment, a structured message passed to and from cells. Each event is an instance of an event class.

Event Adapters See BMC Impact Event Adapters (BMC IEA).

event class1. A BAROC class that is a child of the base event class, CORE_EVENT, and that defines a type of event.

2. A category of events that you can create as a child of the base event class, CORE_EVENT, according to how you want the events to be handled by an event manager and what actions you want to be taken when the event occurs. Event classes may be inherited from parent objects, depending on the specific product. Event classes are inherited from parent objects in BMC Impact Manager.

event collectorAn event grouping whose content is defined by its collector rule. Event collectors are displayed in the BMC Impact Explorer and are defined in the BMC Impact Manager Knowledge Base. See also event collector rule.

event collector ruleA type of rule in the Knowledge Base that defines how events from a cell are organized and presented in the BMC Impact Explorer. Collector rules are written in Master Rule Language (MRL).

event collector setA group of event collectors, organized in a parent-child hierarchy, that results from progressive filtering of the incoming events that match the top-level (parent event collector) criteria. A collector set organizes the events for display in the BMC Impact Explorer.

Event Condition Formula (ECF)The section of an MRL rule definition that specifies the conditions that an incoming event must meet to trigger evaluation of the rule during processing. For example: APP_MISSING_PROCESSES where [hostname: == ‘red1’,sub_origin: contains ‘System’] is an ECF. See Master Rule Language (MRL).

event datastoreAn archive of generated event data.



event group A grouping of collectors that depicts the relationship of events through the hierarchy of the navigation tree. Each level of the collector set is shown as a node under the event group. The parent level of an event group represents all of the events associated with the collectors. An event list is associated with the lowest level nodes of an event group. The parent level of an event group is associated with an image view.

event list1. A tabular listing of events.

2. In BMC Impact Explorer, you can access the event list from the Events tab.

Event Log Adapter for Windows See BMC Impact Event Log Adapter for Windows (BMC IELA).

event managementThe collection and correlation of events across an enterprise to enable IT operations to focus the proper resources on the most critical events.

event management policyOne of several generic rule types that perform actions against events that meet selection criteria specified in an associated event selector. Unlike manually written rules, event policies are defined interactively using the Event Management Policy Editor in the BMC Impact Explorer. See also user-defined policy.

event operation historyThe tabular display of the operation actions taken against an event in BMC Impact Explorer. You can access the event operation history from the Operations History tab of the Event Details pane on the Events tab in BMC Impact Explorer.

event operationsCommands issued by operators to respond to events and correct the problems that the events represent. Operators perform these commands from an event list in BMC Impact Explorer.

event processor See cell.

event propagationThe act of forwarding events and maintaining their synchronization among multiple BMC Impact Manager instances (cells).

event repository1. An archive of generated event data.

2. In BMC Impact Manager instances (cells), the storage facility (mcdb) in which event information is stored.

Glossary 413


event selection criteriaThe syntax of an event selector that specifies the conditions that an incoming event must meet to trigger selection of the event for rule evaluation during each phase of event processing. You can specify event selection criteria through the BMC Impact Explorer GUI. An MRL Event Condition Formula (ECF) also contains event selection criteria. An event selector contains one or more event selection criteria.

event selectorThe filtering mechanism associated with an event policy that selects the events against which the event policy performs actions. An event selector contains one or more event selection criteria. Event selectors are defined interactively by using the BMC Impact Explorer. An event policy can use one or more event selectors.

event sourceThe monitored IT resource from which source event data is collected, such as an operating system or application log file.

event timeoutAn event timeout policy changes an event status to closed after a specified period of time elapses.

Events ViewThe BMC Impact Explorer user interface for viewing and manipulating event data. See also Services View and Administration View.

Exceptions Within During ScheduleTime periods in a service schedule that are exceptions to the During Schedule timeframe, and in which a component has a lower service demand and lower importance than in the During Schedule time period. For example, if you have a During Schedule timeframe of 9:00 AM to 5:00 PM, you can specify the period between 12:00 PM and 1:00 PM as an Exception Within During Schedule timeframe. The time between 12:00 and 1:00 is treated as Off schedule time, and a lower priority is associated with the component in that time. See also During Schedule and off-schedule time.

Exceptions Within During Schedule costThe outage cost (per second) related to the component when the outage occurs within the Exceptions Within During Schedule timeframe.

Execute phaseThe event-processing phase in which Execute rules are evaluated, and, if conditions are met, specified actions are performed.

Execute ruleAn event-processing rule that performs actions when an attribute (slot) value changes in the event repository. Execute rules are evaluated during the Execute phase of event processing. Often, the resulting actions are internal actions, but you can use the execute primitive in a rule to call an external executable.



expressionA combination of operators, operands (constants, variables, functions, and primitives), and conditions that represents a value or a relationship between values.

Ffacet

A specific attribute of a BAROC class slot (field) that either controls the values that the slot can have or controls aspects of a class instance's processing.

field See attribute.

Filter phaseThe event-processing phase in which Filter rules are evaluated to determine which events need additional processing or are unneeded and can be discarded.

Filter ruleAn event-processing rule that determines whether a specific type of event should be passed as it is, subjected to further processing, or discarded during the Filter phase.

functionCode that executes an operation in a cell and returns a value. A function can be used as an expression within a rule or a policy and in alias formulas. See also primitive.

Ggateway

See BMC Impact Integration product (BMC II product).

gateway.export fileA special file that controls the propagation and synchronization of events to a BMC Impact Manager Integration product. The file is in the $MCELL_HOME/etc/ directory on UNIX platforms and in the %MCELL_HOME\etc\ directory on Windows platforms.

global recordA special BAROC class instance that defines a persistent global variable. When a cell starts, it creates one instance of each global record defined in the Knowledge Base and restores any existing values. Global record definitions are stored in the record subdirectory of the cell Knowledge Base. You can get and set global record values in MRL rules or by using the BMC Impact Manager CLI mgetrec and msetrec commands.

global slot orderIn BMC Impact Explorer, a set of slots (attributes), in a particular order, that is associated with a filter and is shared among users.

Glossary 415


global timeframeA timeframe that is created in the Service Model Editor and stored in the BMC Atrium CMDB. A global timeframe is usable from within the BMC Impact Service Model Editor and the BMC Impact Explorer and is available to all cells within an environment. See also local timeframe.

groupA logical or an arbitrary collection of user-defined objects that may or may not have measurable relationships and may or may not have summary data associated with them.

Hheartbeat

1. A periodic message sent between communicating objects to inform each object that the other is still active and accessible.

2. In BMC Impact Manager, a dynamic data object sent by a cell to monitor other cells to verify that they remain active and accessible.

heartbeat intervalThe time between heartbeats; the period of the heartbeat.

highest value functionA calculation method that is used to determine impacts priority

Iimage view

A graphical and hierarchical display that depicts a business view. You can create image view objects or elements to represent managed systems (tools), geographic locations, operators, time, severity levels, categories, and so forth.

impactAn assessed measure of the effect that an incident, fault, or other change will or may have on business operations or service levels.

impact eventAn event whose status is used in computing the status of its associated service component. By default, the status of each event associated with a service component is used to compute its status. However, you can exclude events.

impact production datasetInstances of an environment that are effectively published to the environment’s impact managers. The following example is an impact dataset:

BMC.IMPACT.PROD: the impact production dataset associated with the BMC Impact Service Model Editor



impact propagationThe effect of an impact to a providing service component (provider) on the service components that use its services (consumers) as defined by an impact relationship. See also impact relationship.

impact relationshipA relationship between two service components in a service infrastructure in which a consumer component depends on a provider component to deliver some needed resource to it. A change in status of the provider affects (has an impact on) the status of the consumer component.

impacted stateThe object state that indicates that an object’s functioning is impaired.

impacts priorityThe priority of a component based on the self-priorities of components that this component impacts. So that the remediation process can be aligned with business needs, the computed priority for each causal component is based upon impacts priority.

The value is the result of the combined priorities of all the other components that are impacted when the component goes down. The value is dynamic and changes as the self-priorities of the impacted components change.

import datasetA dataset that contains objects imported to the BMC Atrium CMDB from an external data source such as BMC Topology Discovery.

inactive relationshipA relationship between two components in a service infrastructure in which there is no impact to the consumer component. An inactive relationship indicates that the two components are connected logically and are represented visually as “linked.” See also impact relationship.

in-modelQualifies a service component as being part of a service model. By default, new components in the BMC Atrium CMDB do not belong to any service model. To change a component to in-model, you will typically use the BMC Impact Service Model Editor. Impact relationships get automatically set to in-model when their related components are in-model. Only those that are in-model can be published to a production cell.

included timeframesA set of timeframes that are included in the service schedule.

indexA value that is used by an MRL rule to sort the slot information for an event or data object.

informational alertAn alert of relatively low importance, such as a message about a routine state change. See also severity.

Glossary 417


infrastructure elementAn addressable object that can be monitored, such as a managed system in PATROL.

instance1. A specific object with specific attributes or characteristics that distinguish it from other items (members) of its class or type.

2. In BMC Impact Manager, an object that has specific attribute values and that was created using a class definition.

integration product See BMC Impact Integration product (BMC II product).

interface classA BAROC class that defines the programming interface used by an MRL rule primitive, such as get_external, to return data from an external program. At cell startup, an interface class is loaded into memory. The cell invokes the executable defined in an argument of the primitive. The executable’s value is returned by the interface.

internal base class A BAROC internal class that defines the required structure for the base class from which a group of BMC Impact Manager classes is derived.

internal eventAn event that is created by the cell during event processing. An internal event is processed in the same way as an incoming event. All internal events are processed before any new, incoming external events are processed.

Internet Protocol (IP) adapterAn adapter that collects and translates events from a Telnet, UDP, or TCP data source.

IP adapter See Internet Protocol (IP) adapter.

IT component See BMC_System class.

Kkey slot

A slot whose value is compared during searches.

Knowledge Base (KB)A collection of information that forms the intelligence of a BMC Impact Manager instance and enables it to process events and perform service impact management activities. This information includes event class definitions, service component definitions, record definitions, interface definitions, collector definitions, data associations, and processing rules.



Llocal action

An executable that you can run directly from the BMC Impact Manager. Local actions are written in XML and are stored in the OS-specific subdirectory of the bin directory of the BMC Impact Manager cell Knowledge Base.

local timeframeA timeframe that is created in the BMC Impact Explorer. A local timeframe is stored in a single cell and is available to the event management policies within the cell. See also global timeframe.

logical componentA non-physical object that represents something that does not exist physically in the IT infrastructure such as a service, geography, organization, or user group.

Mmacro

An executable used in .map files to manipulate the fields used for event translation.

manifest.kbA central locator file that specifies the locations of the directories that make up a Knowledge Base. The manifest.kb file is used by the compiler to load the Knowledge Base sources files for compilation.

map See image view.

maskingThe process of combining an overlay dataset with a standard dataset to obtain a view in which the standard dataset objects are overlaid or masked by any modified copy contained in the overlay dataset.

Master Rule Language (MRL)A compact, declarative language used to define rules and collectors for processing and organizing events in BMC Impact Manager. Uncompiled rule and collector source files have a .mrl file extension.

mccompThe BMC Impact Manager rules compiler. Rules are written in the Master Rule Language (MRL). The platform-independent compiler converts them to byte code that the cell can read and process.

mcdb See event repository.

Glossary 419


mcell.conf fileThe configuration file that contains configuration options for a BMC Impact Manager instance (cell). It is in the $MCELL_HOME/etc/ directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms.

mcell.dir fileThe file that lists the cells to which a BMC Impact Solutions product or component can connect and communicate. The information in each cell includes its name, its encryption key, and its host name and port number. This file is in the $MCELL_HOME/etc/ directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms.

mcell.modify fileThe file that lists the slots that affect the mc_modification_date slot. When a specified slot is modified, the time stamp of the modification is reset in the mc_modification_date slot, so that slot is listed in mcell.modify.

mcell.propagate fileThe configuration file that specifies the slot values that are synchronized during event propagation between BMC Impact Manager instances (cells). It is in the $MCELL_HOME/etc/ directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms.

mcell.trace fileThe configuration file that specifies the trace information about a BMC Impact Manager (cell) that should be recorded and the location to which it is written. It is in $MCELL_HOME/etc/ directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms.

mclient.conf fileThe configuration file that specifies the configurations for the BMC Impact Manager CLI commands. It is in the $MCELL_HOME/etc/ directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms.

mclient.trace fileThe configuration file that specifies the trace information that should be collected for the BMC Impact Manager CLI commands and the location to which it should be written. This file is in the $MCELL_HOME/etc/ directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms.

mcontrol commandThe CLI command that sends control commands to a BMC Impact Manager instance (cell).

mc_udidSee universal data identifier (mc_udid).



mean time between failures (MTBF)The average elapsed time from the point at which an IT service object is made available until the next occurrence of failure in the same service object.

mean time between system/service incidents (MTBSI)The average elapsed time between the occurrence of a system or service failure and the next failure in the same system or service.

mean time to repair (MTTR)The average elapsed time from the occurrence of an incident to restoration of the service.

metaclass See internal base class.

MetaCollectorA virtual collector that contains a group of event collectors from multiple BMC Impact Manager instances. It exists only in the BMC Impact Explorer. You can customize it to suit your organizational needs.

moduleA product that plugs into the BMC Portal.

MTBF See mean time between failures (MTBF).

MTBSI See mean time between system/service incidents (MTBSI).

MTTR See mean time to repair (MTTR).

Nnavigation tree

See navigation tree view.

navigation tree view1. A hierarchical display of the objects and user-defined groups and views.

2. In BMC Impact Explorer, a hierarchical view of defined objects and groups. An object can be a filter, rule, or event. The groups are arranged to show relationship and dependency between the managed systems. The navigation tree view appears in the left pane.

3. In the BMC Portal, a hierarchical display of groups defined in a view.

Glossary 421


New phaseThe event-processing phase in which New rules are evaluated to determine which events in the repository should be updated with new information from new incoming events.

New ruleAn event processing rule that is evaluated during the New event processing phase, and can update events stored in the repository (mcdb) with fresh information from new incoming events.

nodeA BMC Impact Manager instance that can receive only events originating on the local host system.

non-local actionA user-initiated action that does not execute on the user console host computer.

non-service componentA logical or physical asset defined in the BMC Atrium CMDB that does not participate in the delivery of business services, such as a desk or other non-IT physical asset. A non-service component is not visible within the BMC Impact Service Model Editor.

normalizationThe process of homogenizing event data into a common event format so that a standard set of event data is collected and reported regardless of the event source.

not-in-modelA service component that exists as a logical or physical asset in the BMC Atrium CMDB but is not currently part of the service model. A not-in-model service component is visible within the BMC Impact Service Model Editor component pool.

notification1. A message, either detailed or concise, that contains information about a condition that triggered an alert state on a monitored element. An email message or SNMP trap that is sent when the program detects a problem that triggers an alert.


null relationshipSee inactive relationship.



Oobject

1. An item that can be inserted into a dashboard. For example, a chart, link, or Active-X control.

2. A generic term for anything that is displayed in the user interface.

See class.

object classIn BMC Impact Solutions, a data structure that defines a type of object. An object class can be a BAROC-language data structure in a BMC Impact Manager cell Knowledge Base or a Common Data Model (CDM) data structure in the BMC Configuration Management Database. A class is made up of data fields, called attributes (slots) that define its properties. See also event class and object.

object linkingIn BMC Portal, the ability to associate two objects that are the same IT asset or resource but that occur in different console modules, and manage them as one object.

off-schedule timeTime periods in which the component has a lower service demand, a lower priority, and lower downtime cost than in the During Schedule time periods. Off-schedule time includes any time that is not defined in the service schedule. Exceptions Within During Schedule time periods are treated as off-schedule time when determining base priority. See also service schedule, Exceptions Within During Schedule, and During Schedule.

open eventAn event that may require action. An open event may have a status of Open, Acknowledged, Assigned, or Blackout.

Open statusThe event status that indicates that the event has not been examined, or that neither an operator nor an automated process has been assigned responsibility for the event.

Pparent event collector

A event collector that contains child collectors to form an event collector set.

permissionA rule associated with an object to control which users, groups, and roles can access the object and in what manner. A permission gives the user a specific type of access to the object (for example, read permission or write permission). See right.

phase, rule See rule phase.

Glossary 423


policy See event management policy.

policy class A BAROC class that is a child of the base data class POLICY and that defines a type of policy.

policy instanceA specific implementation of any of the types of event management policies. For example, you could have an instance of a blackout policy that defined blackout periods for holidays and another instance of the same policy that defined blackout periods for monthly maintenance.

portA number that designates a specific communication channel in TCP/IP networking. Ports are identified by numbers. BMC Impact Manager communicates using the ports specified during installation.

portalThe access point for web-based management tools. The portal houses applications installed by a user and communicates with remotely monitored systems. See also BMC Portal.

presentation nameA descriptive name or label that you can designate to appear instead of a specific internal slot name or class name in the user interface screens. You define presentation names in resource files.

primitiveSimilar to a function, code that executes an operation in a cell and returns a value; can be used as an instruction, or as a function if contained in a Boolean expression.

priorityAn attribute indicating the precedence or scale of importance of an event.

priority propagatorA component that is configured to propagate its priority to its causal components.

production cellA BMC EM or BMC SIM cell that service operators and service managers use to monitor the events and services associated with IT resources in real time.

production viewA read-only view in the BMC Impact Service Model Editor that displays some of the components and relationships contained in the production dataset (the visibility can be constrained by user permissions). Each BMC Impact Service Model Editor user can have several of these views. BMC Impact Service Model Editor users can dynamically convert a production view into a sandbox View. See also sandbox and sandbox View.



promotionA user-initiated action in BMC Impact Service Model Editor that assists in reconciling objects (such as components, relationships, and management data) from a sandbox dataset to the production dataset.

Propagate phaseThe event-processing rule phase in which Propagate rules are evaluated to determine the events to be forwarded to another cell or to a BMC Impact Integration product.

propagate policy A type of policy that forwards events to other cells in the managed domain. A propagate policy is evaluated during the Propagate phase of event processing.

propagate priorityWhen a component forwards its self-priority to its causal components.

Propagate ruleAn event-processing rule that is used to forward events to other cells in the managed domain. Propagate rules are evaluated during the Propagate phase of event processing.

propagated eventAn event that is forwarded from one cell to another cell or to a BMC Impact Integration product during the Propagate phase of event processing.

providerA logical or physical asset that delivers services or provides resources that are used by other service components in the delivery of business services.

publish environmentAn environment that consists of a production dataset, an impact production dataset, and one or more test or production cells that are published.

published-modified componentA service component that has been modified since its service model was published (distributed) to BMC Impact Manager instances.

published componentA service component that is currently part of the published service model that has been distributed to BMC Impact Manager instances.

publishingThe automated or user-initiated action performed by the BMC Impact Publishing Server in which components, relationships, and management data from the production dataset are published to one or several production or test cells.

publishing serverSee BMC Impact Publishing Server.

Glossary 425


published service modelA service model that is currently distributed to BMC Impact Manager instances (cells). It contains only published elements.

RReconciliation Engine

See BMC Atrium CMDB Reconciliation Engine.

record See global record.

recurrence1. The characteristic of occurring more than once.

2. The type of policy that handles recurrent events. See also recurrent event.

recurrent eventAn event that occurs more than one time. Both scheduled and unscheduled events can be recurrent events: a monitored hardware device could experience multiple voltage spikes within a single polling cycle, and a reminder notification could be scheduled to be sent periodically until acknowledgment is received. See also duplicate event.

Refine phaseThe first phase of event processing, in which Refine rules are evaluated to validate incoming events and, if necessary, collect additional data needed before further event processing can occur.

Refine ruleA rule evaluated during the first phase of event processing to validate an incoming event and, if necessary, to collect any additional data needed before further processing can occur.

regular expressionSometimes referred to as “regex,” regular expressions are used in pattern matching and substitution operators. A simple regular expression is a sequence or pattern of characters that is matched against a text string when performing search and replacement functions.

Regulate phaseThe event-processing phase in which Regulate rules are evaluated and, if true, collect duplicate events for a time period and, if a specified threshold of duplicates is reached, passes an event to the next processing phase.

Regulate ruleAn event-processing rule that processes duplicate events or events that occur with a specified frequency. With a Regulate rule, you can create a new event based on the detection of repetitive or frequent events. See also Regulate phase.



related eventThe event that was generated by a source event. A related event can also be the source of other related events.

relationA logical association that expresses the relevance of one event to another.

relation definitionThe BAROC data instance that defines a relation.

remote action A user-initiated action that does not execute on the user console host computer; an executable that can be run by a cell. Remote actions are written in the Master Rule Language (MRL) and are stored in the OS-specific subdirectory of the bin directory of the Knowledge Base.

ReopenThe event operation action that reopens an event that is in the Closed state. Reopen sets the status to Open and shows a Reopen entry in the operation history.

repository See event repository.

restricted objectA dynamically created object that contributes to service status, but which the user does not have permission to view.

rightAn authorization entitling a user to perform a certain action. Rights apply to a whole application or to specific objects of a certain type.

root cause analysisThe process of monitoring events and correlating event data to identify the true cause of a problem.

ruleA conditional statement written in MRL and that, if determined to be true, executes actions. Cell event processing occurs in phases with the cell comparing each event to the series of rules associated with that phase. Each phase’s rules are evaluated one by one before the event is passed to the next phase. The order in which rules are evaluated during a particular phase is based on the order in which the rules were loaded.

rule engine See cell.

rule phaseA specific stage of event processing. Event processing compromises a combination of sequential phases and nonsequential phases, each with a corresponding rule type.

Glossary 427


rule typeThe designation that identifies a rule as being in a specific phase of event processing. The cell executes rules within the context of the associated event-processing phase and in the order in which the rules were loaded from the rule file.

Ssandbox

An overlay dataset associated with the production dataset. The overlay dataset provides a view of the underlying production dataset masked by changes made by the user in the overlay dataset.

sandbox ViewIn the BMC Impact Service Model Editor, a personal work area for designing and developing a service model.

saved stateThe state of a BMC Impact Manager instance (cell) as determined by the StateBuilder utility, statbld.exe. The StateBuilder utility periodically consolidates the data in the transactions file (xact) to produce the “saved state” of the product instance. This information is stored in the event repository (mcdb) and the state is reloaded when BMC Impact Manager restarts.

scheduleSee service schedule.

SDK See Software Development Kit (SDK).

selector See event selector.

selector class A BAROC class that is a child of the base data class SELECTOR and that defines a type of event selector.

self-priorityThe result of mapping the base priority value for a component with its status value.

send to testA user-initiated action in the BMC Impact Service Model Editor in which objects (such as components and relationships) are copied from a sandbox View to a test dataset. The copy captures both sandbox objects and production objects to reproduce a consistent model or submodel in the test environment.



serviceAn integrated composite of several components, such as management processes, hardware, software, facilities, and people, that delivers something of value to satisfy a management need or objective.

service catalogA list of IT services that identifies the physical and logical assets that help provide a service. The data collected in the service catalog can be used to form a configuration management database.

service componentA logical or physical resource that participates in the delivery of services. A service component is any class that is a subclass of the BMC_BaseElement class in the BMC Atrium CMDB or the cell Knowledge Base.

service component aliasA name that is assigned to a service component instance and used in associating an event type with the component instance. You add an alias to a service component instance’s definition in the Service Model Editor. A service component instance can have several different aliases to enable different event types to be associated with it.

service component relationshipIn a service model, the association of two service components in which one component, the provider, delivers some resource or service to the consuming component or components. See also provider and consumer.

Service Impact Management (SIM)A technique for managing the impact of IT events on the company’s core business services to ensure their delivery. See also BMC Service Impact Manager (BMC SIM).

service modelAn extensible system for defining the various resources that combine to deliver business services, for modeling their behaviors and functional relationships, and for managing the delivery of the resulting services. In Service Impact Management, the map of how IT components relate to the business processes that they support. All IT events and service issues are analyzed against the service model to determine the root cause of problems and to report on service impacts.

service scheduleA set of timeframes that includes During Schedule timeframes, Exceptions Within the During Schedule timeframes, and the priority values and downtime costs for a component associated with each timeframe.

Services ViewThe BMC Impact Explorer user interface for viewing service-model components and their relationships and for viewing and managing the events that affect service availability.

Glossary 429


Set PriorityThe event operation action that escalates or de-escalates an event. Set Priority sets the events priority to the specified values and shows a Priority Set entry in the operation history.

severityAn indication of the seriousness of an event.

severity-to-status mapping tableOne of the two tables that relate event severity and service component status. It is used by the cell to map the severity of an impact event to a status value to be used in the computation of the associated service component's status. See also status-to-severity mapping table.

slotAn field in a BAROC class definition. A class definition consists of one or more slots. Each slot has a data type and can have specific attributes, called facets, that can control the values that the slot can have or other aspects of a class instance’s processing. A subclass inherits all the slots of the parent class. See also attribute.

slot facet See facet.

SM See service model.

SNMP adapterAn adapter that listens at a port for SNMP traps. It evaluates the traps and formats them based on the configured event mapping. If the event-mapping conditions are satisfied, it sends the event to the cell.

SNMP Adapter Configuration ManagerA component of the BMC Impact Event Adapters that converts Management Information Base (MIB) data into BMC Impact Manager class data.

Software Development Kit (SDK)A set of procedures and tools with which you can develop a type of application.

source dataThe information that enters the BMC Impact Manager system from another entity and that will be transformed into an event in the system.

source eventThe event that generates a related event.

statbld.conf fileThe configuration file for the StateBuilder utility. It is in the $MCELL_HOME/etc/ directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms.



statbld.trace fileThe configuration file that specifies the trace information to be collected for the StateBuilder utility and where it should be written. It is in the $MCELL_HOME/etc/ directory on UNIX platforms and in the %MCELL_HOME%\etc\ directory on supported Windows platforms.

state change eventA generated event type that records changes in a component’s status. State change events never participate in component status computation.

StateBuilder utilityThe utility, statbld.exe, that periodically consolidates the data in a cell’s transactions file (xact) and writes the “saved state” of the cell to the repository (mcdb).

status1. For events, an indication of the event’s management. Possible values are Open, Closed, Acknowledged, Assigned, and Blackout.

2. For service components, an indication of the relative availability of an IT resource. Possible values are OK, Unknown, Blackout, Information, Warning, Minor Impact, Impacted, and Unavailable.

status-to-severity mapping tableThe status-to-severity map is used by the cell to map the main status of a component to the severity of a history event.

status computation modelA model that determines the status of a consumer service component when a change in the status of its provider service component occurs.

status propagationThe effect that a change in status of a provider component has on the status of its consumer components.

STATUS_PROPAGATION tableA dynamic data table that defines the different pairs of service component types whose instances can have a relationship and the status propagation model to be used for each relationship.

store and forwardA mechanism that ensures that if an event cannot reach its destination, it is saved in a file and sent when a viable connection to the destination becomes available.

stored eventAn event that has been processed by the cell and stored in its event repository. Only stored events can be returned by queries and displayed in BMC Impact Explorer, returned by the mquery CLI command, or referenced by the Using and Update clauses of an MRL rule.

Glossary 431


superclassA hierarchically superior event or data class. A class that is derived from another class inherits part of its attributes (slots) from its superclass.

suppression1. The intentional exclusion of an event or a type of event.

2. The type of policy that governs event suppression.

syslog adapter An adapter that collects information from the log file generated by the UNIX daemon syslogd. The syslog adapter reads syslogd events and formats and sends them to the cell.

TTake Ownership

The event operation action that assigns the current user as the event’s owner, sets the event status as Assigned, and shows an entry of Taken in the operation history.

targetThe entity designated to receive events from an adapter, an event generator, or a BMC Impact Manager instance. Also, a cell whose content currently is displayed in a BMC Impact Explorer dialog box.

test cellA cell, distinct from a production cell, in which to test an in-development service model. A test cell is either a BMC EM cell used to develop and test event management data, rules, policies, actions, and collectors, or a BMC SIM cell used to develop, test, and publish service models.

test datasetA dataset that is used to relay objects from a sandbox View to a test cell. Each BMC Impact Service Model Editor user has a dedicated test dataset. A test dataset combines with a test cell to make a user test environment. The following example is a test dataset:

BMC.IMPACT.Joe.TEST.1: the impact dataset containing instances that are effectively published to the impact manager of Joe’s Test environment

threshold1. In BMC Impact Manager, the point beyond which the value of a facet, slot, or other attribute can trigger an alert.


Threshold ruleA rule that executes if the number of events exceeds the specified number within a particular timeframe.



TIME_FRAME classA BAROC class that is a child of the base data class TIME_FRAME and that defines a type of timeframe.

TIME_ZONE classA BAROC class that is a child of the base data class TIME_ZONE and that defines a type of time zone.

timeframe1. User-defined blocks of time that can be added to a service schedule. Timeframes are added to the service schedule as During Schedule timeframes or Exceptions Within During Schedule timeframes. Any unassigned time is considered Off schedule. See also During Schedule, Exceptions Within During Schedule, and off-schedule time.

2. The specification for the period during which an event management policy instance is in effect.

Timer phaseThe event-processing phase in which Timer rules for the delayed execution of another rule type are evaluated. This phase spans the New, Abstract, Correlate, and Execute phases of event processing.

Timer ruleAn event-processing rule that triggers the delayed execution of another type of rule.

Timer trigger See Timer rule.

tree See navigation tree view.

Uunknown object

An object whose status cannot be determined because of a connectivity failure.

universal data identifier (mc_udid)A unique, system-generated value used to identify a specific service component instance. Each service component must have a value for the mc_udid attribute (slot). One use of the universal data identifier is in associating aliases to a service component instance.

unpublished componentA service component that is currently part of the service model but that has not been published (distributed) to BMC Impact Manager instances.

Glossary 433


user-defined policyA type of policy that a service manager or operations manager can define to perform specialized event processing; not available through any BMC Impact Explorer built-in policy. See also event management policy

Using clause An MRL rule clause that is used primarily to retrieve data instances for a dynamic rule, but can also be used to retrieve instances of past events.

VView

In the Service Model editor, the centralized area where you begin to build and maintain a service model. Each View is unique to a user account. Multiple users can have different Views into the same service model. You can save Views for later reuse.

Wweighted function

A calculation method that is used to determine impacts priority.

When clauseA part of MRL rule syntax for Abstract, Correlate, Execute, Propagate, and Timer rules. Events must first meet the selection criteria in the rule before the When clause is evaluated. Changes to slot values cause When clauses to be re-evaluated.

wildcardA type of pattern matching that uses the asterisk character (*) to represent any number of different characters, and the question mark character (?) to represent a single unknown character. See also regular expression.

workspaceSee View.



Index

Symbols$ClassName function 255, 274$domap function 257$doselector function

description 275loop error 384

$Format function 276$function_name function 274$GmtTime function 256, 276$HostName function 255, 274$LocalTime function 256, 276$Lookup function 255$slotMissing function 276$slotPresent function 276$TimeT function 256, 276%C substitution parameter 62%H substitution parameter 62%L substitution parameter 62%N path value variable 62%P substitution parameter 62%s 256, 276%T substitution parameter 62@hostname

port#keytesting 296

@hostname string 168

Aallocating

memory 181resources 91

architecture of the BMC II C APIs 26availability, ensuring 294

Bbackground process 150

receive thread 165BAROC

END statement, missing 377formatting messages as strings 184formatting strings as messages 185message format 185reporting parsing errors 177

string, malformed 374BMC Developer Connection

description 27joining 27, 392

BMC II C APIs.dll file version 155.so file version 155architecture 26background process 150client and server modes 160configuration files 36configuring 45defines 308deploying 300directory structure 301features 25foreground process 150home directory structure 35initializing 84initializing, error 382installation 31integration testing 289introduction 24key terms 80library files 37logging facility troubleshooting 292multiple integration instances 303restarting 91runtime files 36server and client modes 83structures and enumerations 309terminating 84trace configuration file description 39verifying classes and slots 90

BMC II C APIs, running as a foreground or background process 150

BMC Impact Integration (BMC II) Configuration Utility 47customizing GUI 73features 47message selectors 47packaging with custom files 77

BMC Impact Manageravailability, verifying 294definition formats 65encryption key, description 93identifying with @hostname string 168

Index 435


integration installed on same host 301messages, retaining when unavailable 179name, invalid 380not available 179query, returning error 383

BMC Software, contacting 2BMCII_BUFFER_MODE_DEFAULT buffer mode 167BMCII_BUFFER_MODE_LOW buffer mode 167bmcii_BufferMode enumeration 310bmcii_clearMessage function 181, 182bmcii_closeQuery function 213BMCII_CNC data type

description 308using 169

bmcii_connect functioncell name, invalid 380description 168stopping 170

bmcii_connectionInfo function 154bmcii_ConnectNotify structure

description 316releasing 202, 203

bmcii_copyMessage function 181bmcii_createMessage function 181bmcii_DirectoryInformation structure 311bmcii_disconnect function

calling 146description 170

bmcii_dumpMessage function 190bmcii_errorText function 98, 154bmcii_freeMessage function 182bmcii_freeQueryResults function 215bmcii_freeRecv function

calling 203, 204description 195

bmcii_freeString function 184bmcii_freeStringList function 184bmcii_get_bool function 157bmcii_get_dir function 157bmcii_get_file function 157bmcii_get_num function 158bmcii_get_string function 158bmcii_getDirectoryInfoByName function 164bmcii_getFirstDirectoryInfo function

description 164error 379

bmcii_getFirstMetaSlotValue function 188bmcii_getFirstSlotValue function 184, 187bmcii_getMessageType function 182bmcii_getMetaSlotValue function 189bmcii_getNextDirectoryInfo function

error 379bmcii_getNextMetaSlotValue function 189bmcii_getQueryReply function 215bmcii_getSlotCount function 190bmcii_getSlotValue function 184bmcii_init function

436 BMC Impact Integration Developer’s Kit C API Dev

creates Log and Temp directories 301error calling 377with bmcii_initQueryConnect function 214

bmcii_init2 function 148bmcii_init2 function input arguments 148bmcii_init3() function input arguments 149bmcii_initQueryConnect function

cell name, invalid 380description 214failure 383with bmcii_init function 214

bmcii_listSelectors function 283bmcii_loadMapSet function

description 264failure 250file name error 377

bmcii_loadSelectorSet functiondescription 283failure 268, 283file name error 377

bmcii_Ltrace function 100bmcii_Ltrace_register function 100bmcii_matchSelector function 283bmcii_matchSelectorSet function 284bmcii_matchSelectorSetAll function 284BMCII_MESSAGE data type 308BMCII_MESSAGE_LIST array 215BMCII_MESSAGE_TYPE enumeration 309bmcii_messageGetBaroc function 184bmcii_messageSetBaroc function 185BMCII_ORDER enumeration 319bmcii_queryData function 217bmcii_queryDataByHandles function 217bmcii_queryDataByMcudid function 217bmcii_queryEventByHandles function 219bmcii_queryEvents function 218bmcii_queryEventsByCollector function 218bmcii_queryEventsByDate function 219bmcii_queryEventsByMcueid function 219bmcii_registerAnswer function

description 201bmcii_registerCancel function 202bmcii_registerClientConnectDisconnect function 202bmcii_registerConnectStatus function 202bmcii_registerError function 203bmcii_registerModify function 203bmcii_registerNewMessage function 204bmcii_registerStateChange function 197bmcii_removeMetaSlotValue function 189bmcii_removeSlotValue function 185bmcii_removeSlotValueListItem function 185bmcii_ReplyCancel structure

description 314passing 202releasing 202

bmcii_ReplyError structure 313Bmcii_ReplySuccess structure

eloper Guide


description 316passing during receive function 201

bmcii_ReplySuccess structurereleasing 201

bmcii_result data type 308bmcii_retrieveQueryResults function 215bmcii_retrieveQueryResultsCB function 216BMCII_SEC_ TOKEN data type 308bmcii_send function 193bmcii_setMessageType function

description 183specifying unknown message type 385

bmcii_setMetaSlotValue functiondescription 190message type, unknown 385

bmcii_setSlotValue function 185bmcii_setSlotValueList function 186bmcii_setupServer function

description 161invalid cell name 380

bmcii_startRecvThread functiondescription 196

bmcii_startServer functiondescription 161error 391

bmcii_stopServer functiondescription 162error 391

BMCII_STR data type 309bmcii_term function

calling 146description 153

bmcii_termQueryConnect function 214bmcii_trace function 100, 172bmcii_trace_register 100bmcii_trace_register function 100, 173bmcii_translate function 264bmcii_unloadMapSet function 264bmcii_unloadSelectorSet function 285bmcii_unregisterStateChange function 200bmcii_version function 155BmciiAnsValue structure 315bmciiapi directory structure 35bmciiapi.dll file

description 37version 155

bmciiapi.lib filedescription 37

bmciiapi.so fileversion 155

bmciiapi_1_1 directory 31BmciiData union 313BmciiDataTypes enumeration 315BmciiRecvTypes enumeration 312Bmciistatus enumeration 318buffering

BMCII_BUFFER_MODE_DEFAULT mode 167

BMCII_BUFFER_MODE_LOW mode 167BMCII_ORDER enumeration 319buffer, maximum size 52corrupt buffer error 377description 166error return 193full buffer error 390introduction 86message buffer 167MessageBufferReconnectInterval parameter 52MessageBufferSize parameter 52messages 390messages, retaining when buffer full 179overflow 375, 378, 381reconnect interval 52settings, overriding with META_BUFFER_MODE 179settings, overriding with

META_FAIL_IF_UNCONNECTED 179size 184

Ccallbacks

bmcii_registerAnswer function 201bmcii_registerCancel function 202bmcii_registerClientConnectDisconnect function 202bmcii_registerConnectStatus function 202bmcii_registerError function 203bmcii_registerModify function 203bmcii_registerNewMessage function 204bmcii_retrieveQueryResultsCB function 216definition structure 200description 192registering 204which to use 204

callingbmcii_disconnect 146bmcii_term 146error in function order 379success 384

cellsdefining as gateways 65invalid name error 380

ChangeDate parametermap set header 251message selector set header 271

characteristicsmaps and map files 250smessage selectors and message selector set files 268

classesdefinition 80definition errors 297missing class name 373recommended classname length 309specifying in translation maps 255, 274specifying with a metaslot 179

Index 437


verifying 90clearing messages 178clearing the bmcii_clearMessage function 181client mode

description 160introduction 80, 83starting 144

client-server mode, starting an integration 145ClientSourceIP configuration parameter 50ClientSourcePort configuration parameter 50closing

queries 213query 212

codesimple client sample 103simple query sample 110

collectorsbmcii_queryEventsByCollector example 219bmcii_queryEventsByCollector syntax 218using to query events 218

Common Event Model 91Common Event Model (CEM)

adding attributes 351associating events with CIs 350BMC_BaseEvent class 346component address elements 360component address properties 358CORE_EVENT class 346data types 347description 345event reporting 359event synchronization 352general properties 353I18N 348ITIL processes 363mapping to Baroc 348mapping to CORE_EVENT 348mc_event_category 363mc_event_category values 363metric properties 367property groupings 347reporter component properties 359root cause 351situation properties 363source component properties 356versioning 347

communicationinbound module error 388outbound module error 388

compilers, supported versions 30config directory 46, 268config_utility directory 47configurating

localizing custom .conf files 76configuration files

appending IIDK.conf contents 75


BMC Impact Integration (BMC II) Configuration Utility 47

customizing 69, 72directories 46editing 45example.conf 45IIDK.conf 45Integration.conf 45MessageBufferSize parameter 167modifying 91multiple files, using 303packaging custom .conf files 77parameters 49substitution parameters 62TraceConfigFileName parameter 56

Configuration Parameter Definition (CPD) Generation Utility

customizing configuration files 69features 69Integration.conf 68

configuringBMC II C APIs configuration file, editing 45BMC Impact Integration (BMC II) Configuration

Utility 47configuration directory location 152configuration file parameters 49customized .conf files 69functions 156gateways 394IIDK.conf 49Integration.conf 68integration_name.conf file 38IntegrationCPDFilePath parameter 49mcell.dir file 64multiple integration instances 303packaging custom files 77Trace parameter 56TraceConfigFileName parameter 56TraceDefaultFileName parameter 56TraceFileAppend parameter 57TraceFileHistory parameter 57TraceFileSize parameter 56TraceSrc parameter 56tracing 61, 172

connectingbmcii_connect function description 168bmcii_ConnectNotify notification structure 316bmcii_registerClientConnectDisconnect function 202connections, accepting 165connections, configuring 64for queries 211from Impact Managers 302identifying recipient 164intervals 165maximum reconnect interval 52notification via callback 202

eloper Guide


recipient, specifying with bmcii_getDirectoryInfoByName 164

recipient, specifying with bmcii_getFirstDirectoryInfo 164

status structure 318testing 294to Impact Managers 65troubleshooting 294using the @hostname

port#key string 168ConnectionPortRange configuration parameter

description 50error 389

ConnectionPortReuse configuration parameter 51connections

accepting, error 391broken 202, 378communication connection versus query connection

211destination availability error 390determining status 202failure 388failure due to META_FAIL_IF_UNCONNECTED

metaslot 390for queries 211handle, specifying with META_SOURCE_CNC 180initializing for queries 214invalid handle 389listening for requests 161notification of success 202query, broken 383requesting, error 391TCP/IP not available 391terminating query 214testing functionality 294

ConnectionSetupTimeOut configuration parameter 50contexts 395copying messages 181CopySource map header parameter 253cpd_generation directory 47creating

bmcii_createMessage 181buffer file 377Log and Temp directories 301messages 177specific data queries 217specific event queries 218

customer support 3

Ddata class

definition 81querying by handles 217querying by mc_udid ID 217querying objects 217

slot definitions 325data handle

description 92for rejected object 201format 92missing 382specifying with a metaslot 179use in querying 217zero value 201

data typesBMCII_CNC 308BMCII_MESSAGE 308bmcii_result 308BMCII_SEC_TOKEN 308BMCII_STR 309definitions 308MAP_SET_HANDLE 308MAX_CLASS_NAME 309MAX_EVENT_ID 309SELECTOR_SET_HANDLE 308

datetime_t, using in event queries 219using to query events 219

debuggingbmcii_trace function 172testing tracing 291

defines 308defining

BMC Impact Manager instances 65callback function 200cells as gateways 65slots 319

definitionsclass 80data 81event 81message 81modifies 82slot 82time_t 92

deletingmetaslot values 189slot list values 185slot values 185the BMC II C APIs directory on Unix 42

deployingadding library to path 301integration on BMC Impact Manager instance host

301introduction 300multiple integration instances 300procedures for multiple integration instances 303

Description parameterin map header 253in map set header 252in message selector header 272in message selector set header 271

Index 439


determiningBMC II C APIs version 155which directories are for configuration and home 152

disconnectingbmcii_registerClientConnectDisconnect function 202notification via callback 202procedure 146using bmcii_disconnect 170

dumping message descriptions 190

Eediting

configuration file 45mcell.dir file 65trace configuration file 62

embeddingmessage selectors 268, 275translation maps 257

Enable parameterin map header 253in map set header 252in message selector header 273in message selector set header 271

enabling server mode 160encryption

bmcii_connect function 170description 93Encryption parameter 51invalid key error 389key 93

Encryption configuration parameter 51enumerations

bmcii_BufferMode 310BMCII_MESSAGE_TYPE 309BMCII_ORDER 319BmciiDataTypes 315BmciiRecvTypes 312Bmciistatus 318message types 309

errors$doselector function loop 384BAROC END statement, missing 377BAROC string, malformed 374Basic C API errors 370BMC II C APIs, initializing 382bmcii_errorText function 154bmcii_startServer function 391bmcii_stopServer function 391BmciiAnsValue structure 315buffer full 390buffering 193cell name, invalid 380class name, missing 373communications errors 386connection attempt, failure 388, 390


connection, broken 378ConnectionPortRange parameter 389connections, requesting and accepting 391corrupt buffer 377data handle, missing 382destination, not available 390encryption key, invalid 389error codes, lists 370event handle, missing 382event message, creating 374file, opening 377function call order, bad 379function parameter, invalid 375functions, called after termination 384host name, invalid or incorrect 374, 388inbound communication module 388internal event, invalid 375IP address, invalid 388library version support 385map header, bad or missing 374map name, missing or bad 375map set file name 377map set file syntax 374map set loop 381map set parameters, invalid 380map set, disabled 381map, disabled 381mc_ueid or mc_udid ID, missing 382mcell.dir file, cannot find 378memory allocation 382, 390memory, insufficient 374message modification 382message selector header, bad or missing 376message selector name, missing or bad 376message selector set file name 377message selector set file syntax 375, 376message selector set loop 384message selector set parameters, invalid 380message type, bad 375message type, unknown 385message, invalid or corrupt 381META_FAIL_IF_UNCONNECTED metaslot 390mutex, invalid 375no error 391object, creating 378outbound communication module 388parameter missing from function 373parsing 177path, invalid or misspelled 389placeholder, missing 384port access 390port range 389port, invalid or incorrect 374queries, error return 383query connection attempt, failure 383query connection, broken 383query, unsupported 379

eloper Guide


receive thread, starting 378, 382reporting 177response parsing 375returned messages 154server mode, starting 391server mode, stopping 391severity levels 172slot name, bad 376slot value, bad 376structure, unsupported 379success message 384TCP/IP availability 391timeout expiration 385, 391trace configuration file 391trace functionality, testing 291tracing 171UseLocks setting 382

event classdefinition 81error 375querying by collector name 218querying by date 219querying by handles 219querying by mc_ueid ID 219querying events 218slot definitions 320unable to create message 374

event handledescription 92for rejected message 201format 92missing 382specifying with a metaslot 179use in querying 219zero value 201

example.conf 45example.trace file 62examples

bmcii_queryEventsByCollector syntax 219gateway parameters 400simple client code 103simple query code 110

FFailOnMissingSlot message selector header parameter 272failure

BMCII_CNC_STATUS_FAIL 319calling bmcii_initQueryConnect function 383connection 388connection attempts 86error codes reference 369function 382map set, loading 250, 264matching 272memory, allocating 382

message selector set, loading 268, 283query connection attempt 383router 324selection 272sending messages 179, 294, 295starting receive thread 378

features of the BMC II C APIs 25foreground process 150formatting

%, using in message selectors 256, 276BAROC strings as messages 185error in map set file 374error in message selector set file 375hiding in messages 176message selectors and message selector sets 270messages as BAROC strings 184missing Baroc END statement error 377trace file 291

FormatVersion parameterin map set header 251in message selector set header 271

freeingbmcii_freeMessage function 182bmcii_freeString function 184bmcii_freeStringList function 184memory 390messages 178query results 212resources 91, 146resources allocated by receive functions 195string list memory 184string memory 184

functions$ClassName 255, 274$domap 257$doselector 275$Format 276$function_name 274$GmtTime 256, 276$HostName 255, 274$LocalTime 256, 276$Lookup 255$slotMissing 276$slotPresent 276$TimeT 256, 276bmcii_clearMessage 181bmcii_closeQuery 213bmcii_connect 168bmcii_connectionInfo 154bmcii_copyMessage 181bmcii_createMessage 181bmcii_disconnect 170bmcii_dumpMessage 190bmcii_errorText 98, 154bmcii_freeMessage 182bmcii_freeQueryResults 215bmcii_freeRecv 195

Index 441


bmcii_freeString 184bmcii_freeStringList 184bmcii_get_bool 157bmcii_get_dir 157bmcii_get_file 157bmcii_get_num 158bmcii_get_string 158bmcii_getDirectoryInfoByName 164bmcii_getFirstDirectoryInfo 164bmcii_getFirstMetaSlotValue 188bmcii_getMessageType 182bmcii_getMetaSlotValue 184, 187, 189bmcii_getNextMetaSlotValue 189bmcii_getQueryReply 215bmcii_getSlotCount 190bmcii_getSlotValue 184bmcii_init2 148bmcii_initQueryConnect 214bmcii_listSelectors 283bmcii_loadMapSet 264bmcii_loadSelectorSet 283bmcii_Ltrace 100bmcii_Ltrace_register 100bmcii_matchSelector 283bmcii_matchSelectorSet 284bmcii_matchSelectorSetAll 284bmcii_messageGetBaroc 184bmcii_messageSetBaroc 185bmcii_queryData 217bmcii_queryDataByHandles 217bmcii_queryDataByMcudid 217bmcii_queryEventByHandles 219bmcii_queryEvents 218bmcii_queryEventsByCollector 218bmcii_queryEventsByDate 219bmcii_queryEventsByMcueid 219bmcii_registerAnswer 201bmcii_registerCancel 202bmcii_registerClientConnectDisconnect 202bmcii_registerConnectStatus 202bmcii_registerError 203bmcii_registerModify 203bmcii_registerNewMessage 204bmcii_registerStateChange 197bmcii_removeMetaSlotValue 189bmcii_removeSlotValue 185bmcii_removeSlotValueListItem 185bmcii_retrieveQueryResults 215bmcii_retrieveQueryResultsCB 216bmcii_send function 193bmcii_setMessageType 183bmcii_setMetaSlotValue 190bmcii_setSlotValue 185bmcii_setSlotValueList 186bmcii_setupServer 161bmcii_startRecvThread 196bmcii_startServer 161


bmcii_stopServer 162bmcii_term 153bmcii_termQueryConnect 214bmcii_trace 100, 172bmcii_trace_register 173bmcii_translate 264bmcii_unloadMapSet 264bmcii_unloadSelectorSet 285bmcii_unregisterStateChange 200bmcii_version 155call order error 379call order for queries 212callbacks 192calling after BMC II C APIs termination 384directory 164for configuration 156helpers for messages 176in message selectors 273in translation maps 254invalid parameter error 375iterators 184, 185, 186, 187, 188, 189list of query functions 213, 215, 216, 218message functions list 181server mode 161slot.slotname 275timeout expiration error 385, 391

Ggateways

as message destinations 65communication parameters 396configuration 394configuration variable reference 399contents parameters 396contexts 395format parameters 397gateway files 65predefined variables 394

gettingmessage type 182query replies 215slot count 190

Hhandles

message selector handles 267header file, inclusion 90high availability 66host name

error 388invalid or incorrect 374specifying in translation map 255, 274

eloper Guide


II18N

message key 99I18N support

functions 98locale directory 97localizing messages 97, 98localizing trace functions 100message catalogs 97UTF-8 encoding 96

identifyingconnection recipients 164messages 176missing ID 382

IIDK.conf 45appending to configuration file 75configuration parameters 49editing parameter values 60

iidk.propertiesappending IIDK.conf contents 75editing 74guidelines on editing 73iidkConfFile 75

index value 186initializing

error 382introduction 84memory 181multiple integration instances 303query connection 214sockets error 376

installationcompatible cells 30

installingbmciiapi directory structure 35integration and BMC Impact Manager instance on

same host 301multiple integration instances 300on Microsoft Windows 31on Unix and Linux computers 33pre-installation information 30prerequisistes 30system requirements 30where 300

instancesassigning an instance name 303configuration directory, relationship 153multiple integration instances 300where to install 300

integrationbinding to a socket 161configuration functions 156encryption key 93passing connection handle 180restarting 91running multiple instances 151

starting server mode 161status 154

Integration.conf 45, 68IntegrationCPDFilePath 69

integration_name.conf fileintegration configuration parameters, including 156missing information 378

integration_name.trace filedescription 39error 391location 152

IntegrationCPDFilePath 49integrations

deploying 300instances, installing 300multiple instances 300multiple instances, running 303names, assigning to multiple instances 303on BMC Impact Manager instance host 301starting 144stopping 146testing 289types 80

intervalsconnection 165

introduction to the C APIs 24invalidating a message pointer 182iterating

bmcii_getFirstMetaSlotValue function 188bmcii_getMetaSlotValue function 184, 187bmcii_getNextMetaSlotValue function 189functions 185, 186missing placeholder 384stopping 382, 384zero index value 186

Llibiiapi.a file

description 37location 40

libiiapi.sl filedescription 37location 40

libiiapi.so.1.0 filelocation 40

libiiapi.so.7.1 filedescription 37

librariesadding version check to startup 293bmciiapi.dll 37bmciiapi.lib (for Windows) 37libiiapi.a (for AIX) 37libiiapi.sl (for HP-UX) 37libiiapi.so.7.1 (for Solaris) 37path setup 40

Index 443


paths 301troubleshooting version problems 293verifying version 293wrong map or selector set support 385

LinuxBMC II C APIs installation procedure 33load library path setup 40

LIST_OF slot 177load library path setup 40loading

map sets and map set files 264message selector sets and message selector set files

283localization

custom .conf files 76functions 98I18N support 96locale directory 97LocaleConfigFile 59localizing trace functions 100message catalogs 97message key 99messages 97, 98trace parameter types 99UTF-8 encoding 96

Log directory creation 301logging

output messages 291server mode 290

lookup tables 255loops

$doselector function error 384error in map set 381error in message selector set 384

lVersion field 164, 379

Mmacros, resolving to parameters 171map set files

syntax error 374MAP_SET_ HANDLE data type 308MapName map header parameter 253maps

content 253description 247disabled 381file format 250header parameters 253header requirement 252header, bad or missing 374lookup tables 255map set header 251map set header parameters 251map set header requirement 251map sets, defined 250


map sets, disabled 381map sets, failure 264map sets, invalid parameters 380map sets, library support error 385map sets, loading 264map sets, loop error 381MAP_SET_HANDLE data type 308mapping introduction 85missing or bad name 375permitted functions list 255permitted slot values list 254sample header 253sample map set header 252set files, loading 264set files, name error 377set files, syntax error 374syntax error 374syntax rules 250what they do 249

mapset_name.map file 250MapSetName map set header parameter 251MAX_CLASS_ NAME data type 309MAX_EVENT_ID data type 309mc_history slot 94mc_udid ID

description 91format 91host name, instead of instance name 151missing 382use in querying 217

mc_ueid IDdescription 91format 91host name, instead of instance name 151missing 382recommended length 309use in querying 219

mcell.dir fileconfiguring 64defining BMC Impact Manager instances 65description 38editing 65error finding 378gateways as destinations 65location 38modifying 91multiple integration instances 300reading with bmcii_getDirectoryInfoByName 164selecting a BMC Impact Manager 164verify definition accuracy 294when integration and cell are on same computer 301

memoryallocating and freeing 91allocating, error 382, 390error, insufficient 374freeing 178freeing, from receive functions 195

eloper Guide


freeing, strings and string lists 184leaks 390releasing 182, 185, 189

message selectorheader sample 273headers requirement 272headers, bad or missing 376parameters, header 272

message selector set filessyntax error 376

message selectorscharacteristics 268content 273embedding 275embedding with $doselector 268file name, error 377file, characteristics 268file, loading and unloading 267file, loop error 384file, reading 267file, syntax error 375formatting 270handles 267listing 283message selector set header 270name 272name, missing or bad 376operators 260, 278parameters, set header 271SELECTOR_SET_HANDLE data type 308set header requirement 270set header sample 271sets, description 268sets, formatting 270sets, headers 270sets, invalid parameters 380sets, library support error 385sets, loading and unloading 267sets, loop error 384sets, naming 268slots, missing 272supplemental selector files 47syntax error 375syntax rules 268time, specifying settings 256, 276

message typeerror 375getting with bmcii_getMessageType 182list of values 182, 183setting 183specifying with metaslot 180unkown 385verifying 182

MessageBufferKeepSent configuration parameter 52MessageBufferKeepWait configuration parameter 52MessageBufferReconnectInterval configuration parameter

description 52

MessageBufferResendCount configuration parameter 52MessageBufferSize configuration parameter

description 52modifying 390seeting a value 167

messagesbad message type 375buffer, capacity 52buffering 168, 390class name, missing 373clearing 178connection handle, invalid 389copying 181corrupt buffer error 377creating 177creating, error 374data handle, specifying with metaslot 179definition 81discarding buffered messages 168enumeration that specifies type 309error when modifying 382event handle, specifying with metaslot 179freeing 178full buffer 390functions, list of 181getting message type with bmcii_getMessageType 182helper functions 176hiding internal formatting 176identifying 91, 176internal formatting, hiding 176invalid or corrupted 381invalidating a message pointer 182memory, freeing 182message type values, list of 182message type, setting with bmcii_setMessageType 183message type, unknown 385metaslot values, obtaining 188, 189metaslot values, removing 189overriding buffer settings 179reinitializing 181release modify 203releasing 204reusing 178, 181selection, introduction 266send failure 294send testing 294setting metaslot values with bmcii_setMetaSlotValue

190slot and slot list values, removing 185slot count 190slot list values, setting with bmcii_setSlotValueList

186slot types, supported 185slot values, obtaining 184, 187slot values, retrieving 177slot values, setting with bmcii_setSlotValue 185type, specifying with metaslot 180

Index 445


type, verifying 182when to translate 247

meta data 178META_BLOCK_FOR_BUFFER metaslot 168, 179META_BUFFER_MODE metaslot 179META_CLASS_NAME metaslot 179META_DATA_HANDLE metaslot 179META_EVENT_HANDLE metaslot 179META_FAIL_IF_ UNCONNECTED metaslot 179META_FAIL_IF_UNCONNECTED metaslot

error 390META_MSG_TYPE metaslot 180META_SOURCE_CNC metaslot 180metaslots

definition 83description 178list values, obtaining 188, 189message class, specifying 179META_BLOCK_FOR_BUFFER 168, 179META_BUFFER_MODE 179META_CLASS_NAME 179META_DATA_HANDLE 179META_EVENT_HANDLE 179META_FAIL_IF_UNCONNECTED 179META_MSG_TYPE 180META_SOURCE_CNC 180predefined slots, description 178predefined slots, list 179values, obtaining 189values, removing 189

Microsoft WindowsBMC II C APIs installation procedure 31

modesbuffering 167server and client 160

modifiesdefinition 82releasing 203

modifyingBMC II C APIs configuration file 60BMC II C APIs trace configuration file 63configuration files 91error 382metaslot values 190slot list values 186slot values 185

mposter utility 294, 296multithreading

warning about iterator functions 187, 188, 189mutex error 375

NNULL value 152


Ooperating systems, supported 30overriding buffering settings 179

Pparameters

$ALL 395$CHANDLE 395$CLASS 394$CNAME 395$CONTEXT 394$DATE 394$GHANDLE 394$MODNM 394$MODS 395$NAME 395$TIME 394$VALUE 395ChangeDate 251, 271ClientSourceIP 50ClientSourcePort 50configuration file 49ConnectionPortRange 50ConnectionPortReuse 51ConnectionSetupTimeOut 50CopySource 253Description 252, 253, 271, 272DropAcks 54DumpIncoming 57editing IIDK.conf 60Enable 252, 253, 271, 273EnableRecvPersist 54Encryption 51FailOnMissingSlot 272FormatVersion 251, 271gateway communication 396gateway contents 396gateway format 397gateway parameter examples 400IntegrationCPDFilePath 49, 69invalid in function 375invalid in map or message selector set 380KeepRecvPersisted 54LocaleConfigFile 59map set header 251MapName 253MapSetName 251MaxSleep 58message selector set header list 271MessageBufferKeepSent 52MessageBufferKeepWait 52MessageBufferReconnectInterval 52MessageBufferResendCount 52MessageBufferSize 52

eloper Guide


MinClientSleep 58MinSleep 58missing from function call 373null 152of map header 253PersistencyCleanupGarbageThreshold 53PersistencyCleanupSizeThreshold 53PersistencyDisconnectRemoveMessages 54PersistencyEnabled 53PersistencyFileName 53PersistencyLevel 53ReceiveBufferDir 54SelectorHeader 272SelectorSetName 271ServerAllInterfaces 51ServerDirectoryName 49substitution parameters 62time_t 92TraceConfigFileName 56TraceDefaultFileName 56TraceFileAppend 57TraceFileHistory 57TraceFileSize 56TraceSrc 56UniqueIdFile 59UseMemWatch 57Version 251, 271

parsing error 375paths, invalid or misspelled 389performance tuning 301PersistencyCleanupGarbageThreshold configuration

parameter 53PersistencyCleanupSizeThreshold configuration

parameter 53PersistencyDisconnectRemoveMessages configuration

parameter 54PersistencyDisconnectRemovesMessages parameter 170PersistencyEnabled configuration parameter 53PersistencyEnabled parameter 167PersistencyFileName configuration parameters 53PersistencyLevel configuration parameter

description 53placeholder missing 384ports

privilege error 390use by other applications 390value range, invalid 389value, invalid or incorrect 374

pre-installation information 30printf function 172, 256, 276procedures

client mode integration, starting 144client-server mode integration, starting 145deploying multiple integration instances 303editing .trace file 62editing mcell.dir file 65installing on Unix or Linux 33

integration testing 289integration, stopping 146library version, verifying 293load library, setting 40message , translating to a third-party format 249message, translating from a third-party format 248query integration, starting 146send, using @hostname

port#key 296send, using mcell.dir file definition 297server mode integration, starting 145simple message, sending 294trace functionality, verifying 291uninstalling on Unix 42uninstalling on Windows 41

product support 3propagation

MessageBufferKeepSent parameter 52MessageBufferKeepWait parameter 52MessageBufferReconnectInterval parameter 52MessageBufferResendCount parameter 52MessageBufferSize parameter 52parameters 87parameters list 52rules 87

Qqueries

characteristics 211closing 212connection, broken 383connection, failed attempt 383connection, initializing 214connections, multiple 211data queries, creating specific 217determining success 215event queries, creating specific 218functions, call order 212functions, list 213, 215, 216, 218introduction 86replies, returning 382results, number returned 215starting a query integration 146structures 319unsupported 379

queryingdata by handles 217data by mc_udid ID 217data objects 217events 218events by collector name 218events by date 219events by handles 219events by mc_ueid ID 219

queues

Index 447


messages, queueing with bmcii_startRecvThread 196

Rreceive functions

receive thread, starting 196which to use 204

receive thread 165bmcii_startRecvThread function 196cannot start 382error 378starting 196

receivingcontinuously 196corrupt buffer error 377freeing resources 195testing 296troubleshooting 297

registeringcallbacks 204replies 201

registering state changesfeatures 197registrationID 198state change event types 198

registrationID 198releasing

bmcii_ReplyCancel structure 202memory allocated for metaslot values 189memory, allocated for slot and slot list values 185messages 204modify messages 203

removingmetaslot values 189slot list values 185slot values 185

repliescallback cancellation notice 202cancelling 202parsing error 375registering 201to queries 382

reporting parsing errors 177resources

allocating and freeing 91freeing 146, 178freeing from receive functions 195memory, allocation error 382, 390memory, sufficiency error 374query results 215releasing 185, 189releasing with bmcii_freeMessage 182

restarting the integration 60, 63, 91results

not available 379, 382query, number returned 215


retrievingquery results 215

returningmessage selectors, list of 283query errors 383query replies 382

reusing messages 178router failure 324rules

maps 250message selectors 268

runtime files 36

Sselecting

description 266selection

how it works 267introduction 85message selector set handle 308missing slots 272reading files 267successful match 268uses 266

SELECTOR_SET_ HANDLE data type 308SelectorName message selector header parameter 272selectorset_name.message selector file 268SelectorSetName message selector set header parameter

271sending

bmcii_send 193failure 294messages 193simple message 294testing 294troubleshooting 294

server modebmcii_setupServer function 161bmcii_startServer function 161bmcii_startServer function error 391bmcii_stopServer function 162bmcii_stopServer function error 391definition 80description 160functions 161introduction 83listening for requests 161requirement for seeing META_SOURCE_CNC

metaslot 180setup and use 160starting 145, 161stopping 146, 162structures 311

ServerAllInterfaces configuration parameter 51ServerDirectoryName configuration parameter 49

eloper Guide


servername0 slot value 94

serversinvalid name error 380

settingload library path 40message type 183metaslot values 190overriding for buffers 179overriding, buffering 179slot and slot list values 186

severity levels 172slot.slotname function 275slots

count, getting 190DATA class definitions 325definitions 82, 319event class definitions 320in message selectors 273in translation maps 253list values, obtaining 184, 187list values, removing 185LIST_OF, description 177mc_history 94mc_udid 91mc_ueid 91META_BLOCK_FOR_BUFFER metaslot 168metaslots, description 178metaslots, list of predefined slots 179metaslots, predefined 178missing from message selectors 272name, bad 376name, containing empty string 377non-existent 383null 376selecting, by value 275slot value, bad 376supported in messages 185value, bad 376value, obtaining 184values, permitted in translation maps 254values, removing 185values, retrieving 177values, verifying 186verifying 90

sockets initialization error 376specifying

data handle, using metaslot 179default trace message destination file 56event handle, using metaslot 179instance name 303integration_name.trace file, path and alternate name 56message type with metaslot 180trace files, number to save 57trace files, size 56trace messages, appending new 57trace messages, origin 56

trace, enabling 56starting

integrations 144integrations, client mode 144integrations, client-server mode 145integrations, query mode 146integrations, server mode 145query connection 211receive thread 196server mode 161

statusbmcii_registerConnectStatus function 202Bmciistatus connection status structure 318reporting changes 154

stoppingBMC II C APIs 153integration 91, 146, 153iteration 382, 384query connection 211, 214server mode 146, 162

strftime 256, 276strings

BMCII_STR data type 309empty value in slot 377malformed Baroc 374

structuresbmcii_ConnectNotify 316bmcii_DirectoryInformation 311bmcii_ReplyCancel 314bmcii_ReplyError 313Bmcii_ReplySuccess 316BmciiAnsValue 315BmciiData union 313directory information types 311query types 319receive types 312reply types 313unsupported 379

substitution parameters 62support

compilers 30operating systems 30

support, customer 3syntax

bmcii_query EventsByCollector collector specification 218

error in message selector set file 376map files 250map header, bad or missing 374map set file error 374message selector header, bad or missing 376message selector set file 268message selector set file error 375slot name, bad 376slot value, bad 376verifying, in map sets 264

system requirements 30

Index 449


TTCP/IP

invalid IP address error 388stack not available 391

technical support 3Temp directory creation 301terminating

introduction 84query connection 214

terms, defined 80testing

connectivity 294integrations 289library version verification 293prerequisiste steps 290reception, message 296send, message 294trace functionality 291

third-party applications, description 247time

specifying in translation maps 256using in message selectors 256, 276

time_tcriterion for querying events 219description 92in map files 256in message IDs 92in message selector files 276

timeoutbmcii_retrieveQueryResults functions 215expiration error 385, 391for receiving query replies 212

tipsintegration deployment 301library version check 293

trace configuration filedescription 39modifying 91

Trace parameter 56trace parameter types 99TraceConfigFileName configuration parameter 56TraceConfigFileName parameter 56TraceDefaultFileName configuration parameter 56TraceFileAppend configuration parameter 57TraceFileHistory configuration parameter 57TraceFileSize configuration parameter 56TraceSrc configuration parameter 56TraceSrc parameter 56tracing

associating a source code file name 173bmcii_trace function 172bmcii_trace_register function 173configuring 61, 172description 171formatter string 172macros 171


message descriptions, dumping 190message severity levels 172output, where sent 150parameters in BMC II C APIs configuration files 56sample trace configuration file 63testing 291trace configuration file, editing 62TraceConfigFileName parameter 56TraceDefaultFileName parameter 56TraceFileAppend parameter 57TraceFileHistory parameter 57TraceFileSize parameter 56TraceSrc parameter 56VERBOSE ALL ALL stderr setting 290, 292

translationclass names, specifying 255, 274description 247embedding maps within maps 257host names, specifying 255, 274introduction 85lookup tables, using 255map set handle 308order of operations 248procedures 248selecting maps 247time, specifying 256what it does 247when necessary 247

troubleshootingBasic C API logging 292BMC Impact Manager instance availability 294connectivity 294library version loading 293message reception 297

UuniqueID.dat file 59, 93

description 39UniqueIDFile parameter 59

UniqueIdFile configuration parameter 59Unix

BMC II C APIs installation procedure 33load library path setup 40

UseLocks configuration parametersetting error 382

usingmposter utility 294substitution parameters 62

UTF-8 encoding 96

Vvalues

empty string error 377

eloper Guide


gateway text parameters 395host, invalid or incorrect 374NULL 152permitted in translation maps 254port, invalid or incorrect 374retrieving 177setting 177

variable reference for gateway configuration 399verifying

cell or BMC Impact Manager name 380class and slot validity 90connectivity 294integration operation 289IP address 388library version 293, 385map set syntax 264mcell.dir file definition accuracy 294message reception 296message type 182slot values 186trace file formatting 291trace functionality 291

Versionmap set header parameter 251message selector set header parameter 271

versionsbmciiapi.dll file 155bmciiapi.so file 155error in socket library 376

Wwarnings

class name, changing values 182PersistencyDisconnectRemovesMessages parameter

170strings, changing values 184, 187, 188, 189

working directoryspecifying, in bmcii_init function 150

XXML files

default elements 67IntegrationCPDFilePath 69templates 68

Index 451


eloper Guide

BMC SOFTWARE – SDK LICENSE AGREEMENT BY OPENING THE PACKAGE, INSTALLING, PRESSING “AGREE” OR “YES” OR USING THE BMC MODULES, THE ENTITY OR INDIVIDUALENTERING INTO THIS AGREEMENT AGREES TO BE BOUND BY THE FOLLOWING TERMS, IF YOU DO NOT AGREE WITH ANY OF THESE TERMS,DO NOT INSTALL OR USE THE BMC MODULES AND PROMPTLY RETURN THE BMC MODULES TO BMC. IF YOU REJECT THIS AGREEMENT YOUWILL NOT ACQUIRE ANY LICENSE TO USE THE BMC MODULES.

SCOPE OF AGREEMENT. This Agreement is between the entity or individual entering into this Agreement (“You”) and BMC Software, Inc. (“BMC”). ThisAgreement governs Your use of the BMC Modules, unless You agreed to a web-based license agreement with BMC when ordering the BMC Modules, inwhich case that web-based license agreement governs the use of the BMC Modules. As used herein, “Complementary Product” means any product of Youthat embeds or is dependent for execution upon a BMC Module.

LICENSE. BMC grants You a non-exclusive, non-transferable, personal license (“License”) for one person (the “Developer”) (a) to copy and operate the BMCModules for the sole purpose of designing, developing and testing Complementary Products, provided that You acknowledge and agree that the right ofembedding does not include a right of distribution, and (b) to copy and operate Complementary Products (including any BMC Modules embedded therein)solely for Your internal production purposes. You may not and agree not to: (i) copy the BMC Modules or the Complementary Products except as expresslypermitted in the immediately foregoing sentence, (ii) distribute, resell, rent or lease the BMC Modules or the Complementary Products, (iii) use the BMCModules for production purposes except as expressly permitted with respect to embedded BMC Modules in the immediately foregoing sentence, (iv)disassemble or reverse engineer any BMC Module, or decompile or otherwise attempt to derive any BMC Module source code from executable code, except tothe extent expressly permitted by applicable law despite this limitation, (v) release any information to any third parties on the functionality or performance ofthe BMC Modules without BMC's prior written consent, or (vi) provide a third party with the results of any functional evaluation, or benchmarking orperformance tests, without BMC's prior written approval. Additional usage restrictions may apply to certain third-party files or programs embedded in aBMC Module – applicable installation instructions or release notes may contain the relevant details. Notwithstanding anything in this Agreement to thecontrary, the licenses granted in this Agreement (A) do not grant You the right to use any BMC Module (such rights, if any, are granted under a separatelicense), (B) do not extend to any rights under any patents or patent applications under which BMC has any rights, and (C) do not extend to any use of theBMC Modules in combination with any product, service or software other than the Complementary Product for which it is registered and approved.

FEES. You agree to pay any shipping or handling fees associated with the BMC Modules. You are responsible for taxes, if any.

TERMINATION. This Agreement terminates automatically if You breach any of its terms. Either party may terminate this Agreement without cause on 30days prior written notice. Upon termination, You must uninstall the BMC Modules, and either certify their destruction or return them to BMC.

OWNERSHIP. BMC, or its affiliates or licensors, retains all right, title and interest in the BMC Modules and copies thereof, and any intellectual property,informational, industrial property and proprietary rights therein. BMC neither grants nor otherwise transfers any rights of ownership in the BMC Modules toYou. The BMC Modules are protected by applicable copyright, trade secret, patent and other intellectual and industrial property laws. As between You andBMC, You retain all right, title and interest in any intellectual property, information, industrial property and proprietary rights in the ComplementaryProducts, excluding and subject to those contained in the BMC Modules.

CONFIDENTIAL AND PROPRIETARY INFORMATION. The BMC Modules contain valuable confidential information and trade secrets of BMC. You maynot use the BMC Modules other than as specifically allowed under the license granted in this Agreement. You may not disclose the BMC Modules or any partthereof, to third parties, except that (i) You may disclose the BMC Modules or parts thereof to Developer if Developer has obligations of confidentiality whichare at least as protective of BMC’s confidential information and trade secrets as the provisions of this Agreement and if Developer’s use of the BMC Modulesis consistent with the terms of this Agreement, and (ii) if You use a Complementary Product internally for production purposes, You may disclose the BMCModules or parts thereof to its employees who are under obligations of confidentiality at least as protective of BMC’s confidential information and tradesecrets as the provisions of this Agreement, whose use of the BMC Modules is consistent with the terms of this Agreement, and who need to receive suchdisclosure in order to install, operate, support or maintain the Complementary BMC Modules. You agree to use all reasonable efforts to prevent theunauthorized use, copying, publication or dissemination of any BMC Module.

WARRANTY DISCLAIMER. THE BMC MODULES ARE PROVIDED “AS IS”, WITH ALL FAULTS. BMC, ITS AFFILIATES AND LICENSORSSPECIFICALLY DISCLAIM ALL WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND QUIET ENJOYMENT. BMC DOES NOT WARRANT THAT THE OPERATION OFTHE BMC MODULES OR THE COMPLEMENTARY PRODUCTS WILL BE UNINTERRUPTED, VIRUS OR ERROR FREE, OR THAT THERE ARE NODEFECTS.

LIMITS ON BMC’S LIABILITY. IN NO EVENT WILL BMC, ITS AFFILIATES OR LICENSORS, BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL,PUNITIVE OR CONSEQUENTIAL DAMAGES RELATING TO OR ARISING OUT OF THIS AGREEMENT, THE BMC MODULES AND/OR ANYCOMPLEMENTARY PRODUCT (INCLUDING WITHOUT LIMITATION LOST PROFITS, LOST COMPUTER USAGE TIME, AND DAMAGE OR LOSS OFUSE OF DATA), EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND IRRESPECTIVE OF ANY NEGLIGENCE OF BMC OR WHETHERSUCH DAMAGES RESULT FROM A CLAIM ARISING UNDER TORT OR CONTRACT LAW. BMC’S LIABILITY FOR DIRECT DAMAGES IS LIMITED TOTHE GREATER OF (I) THE AMOUNT PAID BY YOU FOR THE LICENSE TO THE BMC MODULE, IF ANY, AND (II) $1000.

VERIFICATION. If requested by BMC, You will deliver to BMC written certification relating to Your use of the BMC Modules and/or the ComplementaryProducts in compliance with the terms of this Agreement. BMC may audit Your use of the BMC Modules and/or Complementary Products to confirm suchcompliance.

EXPORT CONTROLS. You will cooperate with BMC as reasonably necessary to ensure compliance with the laws and regulations of the United States and allother relevant countries, relating to exports and re-exports (“Export Laws”). You may not import, export, re-export or transfer, directly or indirectly, includingvia remote access, any part of the BMC Modules, or any other BMC information or technology, in violation of any such laws and regulations, or without anywritten governmental authorization required under applicable Export Laws. Neither the BMC Modules nor the underlying information or technology may bedownloaded or otherwise provided or made available, either directly or indirectly, (i) into Cuba, Iran, Libya, Sudan or any other country subject to U.S. tradesanctions, to individuals or entities controlled by such countries, or to nationals or residents of such countries other than nationals who are lawfully admittedpermanent residents of countries not subject to such sanctions; or (ii) to anyone on the U.S. Treasury Department’s list of Specially Designated Nationals andblocked persons or the U.S. Commerce Department’s Table of Denial Orders. BY OPENING THE PACKAGE, INSTALLING, PRESSING “AGREE” OR “YES”OR USING THE BMC MODULES, YOU AGREE TO THE FOREGOING AND REPRESENT AND WARRANT THAT YOU ARE NOT LOCATED IN, UNDERTHE CONTOL OF, OR A NATIONAL OR RESIDENT OF ANY SUCH COUNTRY OR ON ANY SUCH LIST.

DISPUTE RESOLUTION AND GOVERNING LAW. ANY CONTROVERSY OR CLAIM ARISING OUT OF THIS AGREEMENT, OR THE BREACH HEREOF,WILL BE SETTLED BY ARBITRATION ADMINISTERED BY THE AMERICAN ARBITRATION ASSOCIATION UNDER ITS COMMERCIALARBITRATION RULES IN HOUSTON, TEXAS IN ENGLISH. THE ARBITRATOR MUST FILE ALL FINDINGS WITHIN 30 DAYS AFTER THE FINALARBITRATION HEARING. JUDGMENT ON ANY AWARD RENDERED BY THE ARBITRATOR MAY BE ENTERED IN ANY COURT HAVINGJURISDICTION THEREOF. NOTHING CONTAINED IN THIS SECTION WILL LIMIT BMC'S ABILITY TO SEEK EQUITABLE RELIEF IN ANY COURT.THE PARTIES WILL ARBITRATE DISPUTES IN CONFIDENCE. THIS AGREEMENT WILL BE GOVERNED BY THE SUBSTANTIVE LAWS OF THE STATEOF TEXAS. CHOICE OF LAW RULES OF ANY JURISDICTION AND THE UNITED NATIONS CONVENTION ON CONTRACTS FOR THEINTERNATIONAL SALE OF GOODS WILL NOT APPLY.

U.S. GOVERNMENT RESTRICTED RIGHTS. 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 227.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer isBMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.

MISCELLANEOUS TERMS. This Agreement constitutes the entire agreement between You and BMC relating to the matters covered hereby, and supersedesany prior or contemporaneous negotiations or agreements, whether oral or written, concerning the BMC Modules and any related subject matter. ThisAgreement may be modified only in a mutually signed, whether in writing or electronic, agreement between You and BMC. Neither Developer nor You mayassign this Agreement or any rights granted by this Agreement to a successor, except in the event of merger, consolidation, or sale of all or substantially all ofYour assets. Should any provision of this Agreement be invalid, or unenforceable, the remainder of the provisions will remain in effect. The parties haveagreed that this Agreement and the documents related thereto be drawn up in the English language. Les parties exigent que la présente convention ainsi queles documents qui s’y rattachent soient rédigés en anglais.

BY OPENING THE PACKAGE, INSTALLING, PRESSING “AGREE” OR “YES” OR USING THE BMC MODULES, YOU ACKNOWLEDGE AND AGREETHAT YOUR AUTHORIZED REPRESENTATIVE HAS READ THIS AGREEMENT AND THAT YOU INTEND TO BE BOUND HEREBY, AS IF YOURAUTHORIZED REPRESENTATIVE HAD SIGNED THIS AGREEMENT IN WRITING. THE INDIVIDUAL EXECUTING THIS AGREEMENT WARRANTSTHAT HE OR SHE HAS THE AUTHORITY TO ACCEPT THE TERMS OF THIS AGREEMENT FOR YOU AND ON HIS OR HER OWN BEHALF.

*86818**86818**86818**86818*

*86818*

bmc impact integration developerâ€™s kit c api developer guide

Documents