BMC Atrium CMDB 2.1.00
Developer’s Reference Guide
August 2007
www.bmc.com
Contacting BMC Software You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada Address
BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA
Telephone
713 918 8800 or 800 841 2031
Fax
(01) 713 918 8000
Fax
713 918 8000
Outside United States and Canada Telephone
(01) 713 918 8800
If you have comments or suggestions about this documentation, contact Information Development by email at
[email protected]. © Copyright 2005–2007 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. ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office. Linux is the registered trademark of Linus Torvalds in the U.S. and 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 Legend U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.
Customer Support You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer Support by telephone or email. To expedite your inquiry, please see “Before Contacting BMC Software.”
Support Website You can obtain technical support from BMC Software 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 Software offers. Find the most current information about BMC Software products. Search a database for problems similar to yours and possible solutions. Order or download product documentation. Report a problem or ask a question. Subscribe to receive email notices when new product versions are released. Find worldwide BMC Software support center locations and contact information, including email addresses, fax numbers, and telephone numbers.
Support by telephone or email 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 email message to
[email protected]. (In the Subject line, enter SupID:, such as SupID:12345.) Outside the United States and Canada, contact your local support center for assistance.
Before Contacting BMC Software 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 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 problem
■
Commands and options that you used
■
Messages received (and the time and date that you received them) — — —
Product error messages Messages from the operating system, such as file system full Messages from related software
Contents Preface
9
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 The New icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 BMC Atrium CMDB documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Section I Developing programs with the CMDB APIs Chapter 1
13
Introduction to the BMC Atrium CMDB APIs
15
BMC Atrium CMDB API overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Web services API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Java API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using API programming compared with the CMDB Console . . . . . . . . . . . . . . . . . . . When to use the API compared with the CMDB Console. . . . . . . . . . . . . . . . . . . . CMDB Console and API terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16 17 18 18 19 19 20
Chapter 2
21
Getting started
New in this release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . API compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Java API changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . API version requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C API package contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Library files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compiler information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Java API package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Library files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Version information for BMC Atrium CMDB API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migrating to the BMC Atrium CMDB from 1.1 to 2.0 API . . . . . . . . . . . . . . . . . . . . . .
Contents
22 22 23 23 24 24 25 26 27 27 27 28 28 28 29 29
5
Chapter 3
Programming common BMC Atrium CMDB tasks
31
Java program requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Working with configuration item classes and instances. . . . . . . . . . . . . . . . . . . . . . . . . 32 Creating a CI class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Creating attributes for your class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Creating a CI instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Working with relationship classes and instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Creating a relationship class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Creating a relationship between two CI instances . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Retrieving instance details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Chapter 4
BMC Atrium CMDB tools
41
Working with the cmdbdriver program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 From the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Using a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Using cmdbdriver on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Migrating data between BMC Atrium CMDB servers . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Logging in to the cmdbdriver program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Step 1—Exporting class data with cmdbdriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Step 2—Export instance data with cmdbdriver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Step 3—Import class definitions with cmdbdriver . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Step 4—Import instance data with cmdbdriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Step 5—Export reconciliation definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Step 6—Import reconciliation definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Known issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Using the extension loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 The extension loader directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Packaging and installing BMC Atrium CMDB extensions . . . . . . . . . . . . . . . . . . . 54 Verifying your installed extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Integrating the CI Relationship Viewer with other applications. . . . . . . . . . . . . . . . . . 63 Launching the CI Relationship Viewer from AR System applications . . . . . . . . . 64 Embedding the CI Relationship Viewer in AR System applications . . . . . . . . . . . 66 Launching the CI Relationship Viewer from non-AR System applications . . . . . 67 Configuring the CI Relationship Viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Working with filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Customizing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Creating CI Relationship Viewer events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Creating CMDB status alerts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Importing data with Integration Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Working with SQL views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Debugging BMC Atrium CMDB API programs using print.c routines . . . . . . . . . . . . 78
6
Developer’s Reference Guide
Section II API reference Chapter 5
79
C API functions and data structures
81
Related files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Data model functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Instance functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Bulk entry transaction functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Environment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 User interface component functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Import and Export functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Free functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Reconciliation Engine functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Federation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 Audit functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 Class structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 Attribute structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Instance structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 General purpose structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Export and import structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Graph query structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 User interface components structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Reconciliation Engine structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Federation structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Audit structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Chapter 6
Web services API operations and data structures
191
Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Instance data operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data model operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reconciliation Engine operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Federation operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Audit operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User interface component operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Utility operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Instance structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Graph query structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Attribute structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Utility structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User interface component structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reconciliation Engine structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Federation structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Audit structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
192 192 204 215 219 222 224 225 227 227 232 236 242 250 251 253 256 258
7
Appendix A
CI Relationship Viewer events
261
Events from AR System to CI Relationship Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Events from CI Relationship Viewer to AR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Appendix B
Using graph queries to find related CIs
265
Representing graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 The CMDBGraphQuery API function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
8
Glossary
275
Index
283
Developer’s Reference Guide
Preface The BMC Atrium CMDB Developer’s Reference Guide describes how to use the BMC Atrium Configuration Management Database (CMDB) C, Java, and web services APIs, and other BMC Atrium CMDB tools to program your BMC Atrium CMDB application and integrate it with other applications. This guide is divided into the following sections:
Developing programs with the BMC Atrium CMDB APIs—This section provides an introduction to the BMC Atrium CMDB API suite, provides instructions on how to program the BMC Atrium CMDB application using Java methods, and provides procedures for using other BMC Atrium CMDB tools.
API reference—This section provides descriptions of the C API functions, web services operations, and the data structures used by each function and operation. The BMC Atrium CMDB application runs on top of the BMC® Remedy® Action Request System® application (AR System®) and enables you to manage data about your IT environment.
Audience This guide is intended for application programmers. For more information about configuring the application, see the Installation and Configuration Guide.
The New icon Documentation for the BMC Atrium CMDB Developer’s Reference Guide contains a New icon that identifies features or products that are new or enhanced with version 2.1.00.
Preface 9
BMC Atrium CMDB 2.1.00
BMC Atrium CMDB documentation The following table lists the documentation available for BMC Atrium CMDB. Unless otherwise noted, softcopy documentation is available in the Docs directory of the product DVD and the Support site at http://www.bmc.com/support_home. Title
Document provides
Audience
Common Data Model Diagram
Hierarchical diagram of all classes in the Common Administrators Print and PDF Data Model (CDM) including unique attributes and applicable relationships
Concepts and Best Practices Guide
Information about CMDB concepts and best practices for planning your BMC Atrium CMDB implementation
Data Model Help
Description and details of superclasses, subclasses, Administrators HTML (product DVD attributes, and relationship classes for each class. only) Contains only information about the Common Data Model at first, but can be updated to include information about data model extensions you install.
Developer’s Reference Guide
Information about creating API programs, using C Administrators Print and PDF and web services API functions and data structures, and and a list of error messages programmers
Installation and Configuration Guide
Information about installing and configuring BMC Atrium CMDB, including permissions, class definitions, reconciliation, and federation
Administrators Print and PDF
Javadoc API Help
Information about Java classes, methods, and variables that integrate with BMC Atrium CMDB
Programmers
IT leaders and administrators
Format
Print and PDF
HTML (product DVD only)
Mapping Your Data to Mappings of common IT objects to the appropriate Administrators Spreadsheet, print and PDF class in which to store them, whether part of the BMC Atrium CMDB Classes Common Data Model or an extension. Also includes information about further categorizing instances using key attributes. Master Index
Combined index of all guides
Everyone
Print and PDF
Online Help
Help for using and configuring BMC Atrium CMDB, available by clicking Help in the product interface
Users and administrators
Product Help (available from Help links once installed)
Release Notes
Information about new features, open issues, and resolved issues
Everyone
Print and PDF
10
Developer’s Reference Guide
Related documentation
Title
Document provides
Audience
Format
Troubleshooting Guide
Information about resolving issues with BMC Atrium CMDB components, including API, filter, and console error messages and their solutions.
Administrators, Print and PDF programmers, and BMC Support personnel
User’s Guide
Information about using BMC Atrium CMDB, including searching for and comparing CIs and relationships, relating CIs, viewing history, and launching federated data
Users
Print and PDF
Related documentation The following table lists some documentation for related BMC products that might be of interest to BMC Atrium CMDB users. This documentation is available from the Support site at http://www.bmc.com/support_home. Title
Document provides
Audience
Format
BMC Atrium Integration Engine 7.1.00 User’s Guide
Information about how to establish a data transfer between third-party databases and BMC Atrium CMDB.
Administrators Print and PDF and developers
BMC Configuration Management Configuration Discovery Integration for CMDB 7.1 Implementation Guide
Information about the following: Transferring configuration data from BMC Configuration Management to BMC Atrium CMDB Normalizing discovered software configuration data with the BMC Definitive Software Library before transferring it to BMC Atrium CMDB.
Administrators Print and PDF and developers
BMC Foundation Discovery and BMC Topology Discovery Installation and Configuration Guide
Information about the configuration of a connection Administrators Print and PDF and developers between BMC Atrium CMDB and the discovery data store from BMC Foundation Discovery and BMC Topology Discovery.
BMC Foundation Discovery and BMC Topology Discovery User Guide
Information about the synchronization of the topology datastore with BMC Atrium CMDB.
Administrators Print and PDF and developers
BMC Remedy Action Information about AR System data structures, C Request System 7.1.00: API function calls, and OLE support. C API Reference
Administrators Print and PDF and programmers
BMC Remedy Action Information about configuring AR System servers Request System 7.1.00: and clients, localizing, importing and exporting Configuring data, and archiving data.
Administrators Print and PDF
Information about components necessary to build BMC Remedy Action Request System 7.1.00: applications in AR System, including applications, Form and Application fields, forms, and views. Objects
Developers
Print and PDF
Preface 11
BMC Atrium CMDB 2.1.00
Title
Document provides
Audience
Format
BMC Remedy Action Procedures for installing AR System Request System 7.1.00: Installing
Administrators Print and PDF
Information about the mid tier, including mid tier BMC Remedy Action Request System 7.1.00: installation and configuration, and web server configuration. Installing and Administering BMC Remedy Mid Tier
Administrators Print and PDF
Information about integrating AR System with Administrators Print and PDF BMC Remedy Action Request System 7.1.00: external systems using plug-ins and other products, and developers Integrating with Plug- including LDAP, OLE, and ARDBC. ins and Third-Party Products Definitive Software Library 7.1 Administrator’s Guide
12
Information about installing and configuring DSL, Administrators Print and PDF updating vendor data, and connecting DSL to BMC Configuration Management and AR System databases
Developer’s Reference Guide
Section
I
Developing programs with the CMDB APIs This section explains how to use the BMC Atrium CMDB tools, such as the cmdbdriver program and the extension loader, and how through programming, you can extend your application using the BMC Atrium CMDB APIs. This section is organized into the following chapters:
Chapter 1, “Introduction to the BMC Atrium CMDB APIs,” provides an overview of the BMC Atrium CMDB architecture and the BMC Atrium CMDB API suite, which includes a C API, Java API, and web services API. It also provides information about when to use API programming and when to use the BMC Atrium CMDB Console to perform the required tasks. Chapter 2, “Getting started,” provides information about the preparatory steps you must follow before you use the BMC Atrium CMDB API suite. Chapter 3, “Programming common BMC Atrium CMDB tasks,” provides Java code samples for a list of basic programming tasks that are performed most often in BMC Atrium CMDB API programs. Chapter 4, “BMC Atrium CMDB tools,” provides instructions for using the BMC Atrium CMDB tools, such as the cmdbdriver and extension loader.
Section I
Developing programs with the CMDB APIs
13
BMC Atrium CMDB 2.1.00
14
Developer’s Reference Guide
Chapter
1
Introduction to the BMC Atrium CMDB APIs This section provides an overview of BMC Atrium CMDB programming interface (API) suite. The following topics are provided:
BMC Atrium CMDB API overview (page 16) Using API programming compared with the CMDB Console (page 19)
Chapter 1 Introduction to the BMC Atrium CMDB APIs
15
BMC Atrium CMDB 2.1.00
BMC Atrium CMDB API overview The BMC Atrium CMDB provides an API suite that allows you, through programming, to work with class definitions, instance data, federation, reconciliation, audit and other functions. The BMC Atrium CMDB API suite is composed of the C, Java, and web services APIs. The C and Java APIs provide similar data structures and functions to encapsulate information and functionality. You can use either C or Java API depending on your application platform. The Web services API provides a set of platform-independent operations that communicate with your applications to retrieve and send data. Figure 1-1: BMC Atrium CMDB C and Java architecture AR System Applications Service Impact Manager CMDB Console BMC Remedy User
Web Client
Topology Discovery
CI Relationship Viewer BMC Remedy User
Web Service Clients .Net Client
AXIS Client
Web Client
CMDB Web Services API
BMC Remedy Mid Tier (CMDB API)
CMDB Java API
Reconciliation Engine
CMDB C API
AR System API
Action Request System BMC Atrium CMDB CDM Database
NOTE The arrows indicate the directions in which each program or process can initiate an API function. Data can flow in any direction. As shown in Figure 1-1, a BMC Atrium CMDB components, such as the CI Relationship Viewer and CMDB Console use the Java API to manipulate the CDM, whereas the external data consumers and data providers can communicate either using the web services API or Java API.
16
Developer’s Reference Guide
BMC Atrium CMDB API overview
This guide describes the C and web services APIs. For more information about the Java API, see the Javadoc API Help, which is located in the sdk/javadoc/cmdbapi/ subdirectory of your BMC Atrium CMDB installation directory. To access the Javadoc API Help, open the index.html file.
C API A BMC Atrium CMDB client can use the C API to create, modify, delete, and query the class definitions, instance data, federation, reconciliation, and other functions. The C API:
Contains data structures that store both simple and complex information. A simple data structure serves as the primary building block for a complex data structure.
Includes a set of Free functions that you can use to deallocate memory. Provides server-access information with every call in the control parameter of the function.
Features You can use the C API functions to perform the following operations:
Create, modify, and delete classes and instances. Retrieve CI and relationship information. Create log files in a format that is different from the standard reports.
Components The C API consists of a set of functions and data structures, most of which perform a specific database or data source operation. For example, you can use a function to retrieve information about a particular BMC Atrium CMDB class. Most of these C API functions accept one or more BMC Atrium CMDB C data structures as parameters that qualify the action to perform, such as type of class to create, qualification for an instance to retrieve or delete, or class name to modify. For more information about the C API functions and data structures, see Chapter 5, “C API functions and data structures.” The sdk/samples/driver subdirectory in your BMC Atrium CMDB installation directory contains the source code for the cmdbdriver program. This program provides a command-line interface for calling C API functions. The cmdbdriver program also includes print routines for every data structure in the API, making it a useful debugging tool. For more information about the print routines, see “Debugging BMC Atrium CMDB API programs using print.c routines” on page 78.
Chapter 1 Introduction to the BMC Atrium CMDB APIs
17
BMC Atrium CMDB 2.1.00
Web services API The BMC Atrium CMDB web services API, which conforms to SOAP and WSDL standards, provides a standard interface for interacting with BMC Atrium CMDB. You can use the web services API to integrate BMC Atrium CMDB data with other applications, for example, BMC Topology Discovery and BMC Foundation Discovery, BMC® Remedy® Change Management, or any other third-party application.
Features External web-based programs can communicate with BMC Atrium CMDB using the web services operations. The BMC Atrium CMDB web services operations are developed to assist the following communities:
BMC software partners—For developing integrated solutions with BMC Atrium CMDB.
Users—For developing programs that set up communication between BMC Atrium CMDB and other products running in the environment.
Components The BMC Atrium CMDB web services API consists of operations and data structures. Although the web services operations correspond to the BMC Atrium CMDB C API functions, they do not correspond one-to-one with the C API. The web services API data structures correspond to the classes in the Java API. For more information about the web services operations that are currently available, see Chapter 6, “Web services API operations and data structures.”
Java API The BMC Atrium CMDB Java API is a collection of Java classes and methods that provide the C API functionality in a Java development environment. Use the Java API if you write server-side web applications that you access through the Java Server page (JSP) or Java servlets web tier layer. The Java API provides an object model of BMC Atrium CMDB. You will find it easier to use the Java API if you are already familiar with the C API. For more information about the Java API, see the Javadoc API Help, which is located in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. To access the Javadoc API Help, open the index.html file.
18
Developer’s Reference Guide
Using API programming compared with the CMDB Console
Features The following list describes the Java API features:
The Java virtual machine (JVM) automatically deallocates objects that are created with the Java API.
In the Java API, server access information is encapsulated in an ARServerUser object. For more information about ARServerUser object, see BMC Remedy Action Request System 7.1.00: Integrating with Plug-ins and Third-Party Products.
The Java API has its own naming conventions.
Using API programming compared with the CMDB Console The primary reason to write your own API program is to satisfy specific business needs that you cannot meet with the CMDB Console. In addition, API programming gives you the flexibility to customize your application. However, API solutions are more complex to design, implement, and maintain. The CMDB Console provides an easy-to-use graphical user interface for performing BMC Atrium CMDB tasks, such as creating classes, CIs, and relationships, and viewing instance history. For more information about performing administrator tasks using the CMDB Console, such as using the Class Manager, Federation Manager, and, the Reconciliation Engine Manager, see the BMC Atrium CMDB 2.1.00 Installation and Configuration Guide. For more information about performing user tasks using the CMDB Console, such as viewing CI history, Viewing CI and relationship classes, and comparing instances, see the BMC Atrium CMDB 2.1.00 User’s Guide.
When to use the API compared with the CMDB Console Table 1-1 outlines the scenarios in which you should use APIs instead of the CMDB Console. Table 1-1: API Programming scenarios Requirement
Use API Programming? Use the CMDB Console?
You want to modify the CDM. You need to access multiple BMC Atrium CMDB components at the same time or integrate with programs or data outside the BMC Atrium CMDB.
Yes Yes
Chapter 1 Introduction to the BMC Atrium CMDB APIs
19
BMC Atrium CMDB 2.1.00
Requirement
Use API Programming? Use the CMDB Console?
You need to create, delete, or search for BMC Atrium CMDB classes.
Yes Yes
You need to perform complex operations that involve multiple objects. You need to create, delete, or search BMC Atrium CMDB relationships.
Yes
You need a two-way interface (or gateway) between the BMC Atrium CMDB and another application.
Yes
The values you want to specify for $PROCESS$ or the Run Process action exceed the size limitation of the command line.
Yes
CMDB Console and API terminology The CMDB Console and the APIs use different terms to see a specific task. Table 12 list these differences. Table 1-2: CMDB Console and API terminology
20
BMC Atrium CMDB term
API term
search
getList
create
create
modify
set
view/display
get
Developer’s Reference Guide
Chapter
2
Getting started
This section provides the information you need to know before you start using the BMC Atrium CMDB API suite. The following topics are provided:
New in this release (page 22) C API package contents (page 24) Java API package contents (page 27) Version information for BMC Atrium CMDB API (page 28) Sample source code (page 29) Migrating to the BMC Atrium CMDB from 1.1 to 2.0 API (page 29)
Chapter 2 Getting started
21
BMC Atrium CMDB 2.1.00
New in this release In BMC Atrium CMDB version 2.1.00, changes have been made to the APIs. This section provides the API compatibility information and explains these API changes. For more information about these changes, see the Overview page of your Javadoc Help.
API compatibility The following list explains the backward and forward compatibility of BMC Atrium CMDB 2.1.00:
If you developed 2.0.x clients that use version 2.0.x DLLs and libraries, they can continue to work with the 2.1 server.
If you use version 2.1.00 DLLs and libraries for your clients, you need to make appropriate changes to your code and recompile it. Table 2-1 provides a compatibility matrix for the AR System server and BMC Atrium CMDB. Table 2-1: BMC Atrium CMDB compatibility matrix AR System server
BMC Atrium CMDB server
BMC Atrium CMDB client
Supported
7.1.00
2.1.00
2.1.00
Yes
7.1.00
2.1.00
2.0.x
Yes
BMC Atrium CMDB backwards compatibility: older client and newer server.
7.1.00
2.0.x
2.1.00
No
BMC Atrium CMDB forward compatibility: newer client and older server.
7.1.00
2.0.1 patch x
2.0.1 patch x
Yes
AR System backwards compatibility.
7.1.00
2.0.1 patch x
2.0.1 patch x
Yes
AR System and BMC Atrium CMDB backwards compatibility. Preferably, upgrade to BMC Atrium CMDB 2.1 server.
7.1.00
2.0.0 patch x or 2.0.0 patch x or No earlier earlier
You must upgrade BMC Atrium CMDB server to version 2.1.00.
7.0.x or earlier
2.1.00
The Foundation piece has to be of a more recent version than the application. Upgrade the server before upgrading BMC Atrium CMDB.
22
Developer’s Reference Guide
Any
No
Remarks
New in this release
Java API changes In version 2.1.00, the following changes have been made to the Java API:
Package name changes—The package name has been changed from com.remedy.cmdb.api
to com.bmc.cmdb.api.
JRE version changes—With 2.1.00, the minimum JRE version required is 1.5.0_06 or greater. Java API changes—The AR System version 7.1.00 Java API is enhanced to use some of the features of Java, such as annotations, enumerations, and typedcollections. Therefore, the BMC Atrium CMDB Java API has also changed. For more information about these changes, see the Overview page of your Javadoc Help.
API version requirements In version 2.1.00, a new feature is developed that allows you to restrict older versions of BMC Atrium CMDB clients from connecting to a newer version of the server. To specify the minimum API version with which the server can communicate, you configure the Minimum-CMDB-API-Version parameter in the ar.cfg (Windows) or ar.conf (UNIX) file. The default value for this setting is configured to 3. For example, if you set Minimum-CMDB-API-Version to 4, clients prior to version 2.1.00 will not be able to communicate with the server. For more information about the ar.cfg or ar.conf configuration file, see BMC Remedy Action Request System 7.1.00 Configuring. Table 2-2 provides the BMC Atrium CMDB releases and their corresponding API versions. Table 2-2: BMC Atrium CMDB releases and corresponding versions BMC Atrium CMDB release
API version
BMC Atrium CMDB 2.1.00
4
BMC Atrium CMDB 2.0.x
3
Chapter 2 Getting started
23
BMC Atrium CMDB 2.1.00
C API package contents The C API package includes header files, library files, and source code for the cmdbdriver sample program. When you install the BMC Atrium CMDB application, the C API is also installed with the package.
Header files Table 2-3 displays the list of C API header files installed in the include directory: Table 2-3: C API Header files
24
File Name
Contents
ar.h
AR System API data type and structure definitions, size limits, and constant definitions.
cmdb.h
BMC Atrium CMDB C API data type and structure definitions, size limits, and constant definitions.
arerrno.h
Error code definitions.
arextern.h
External declarations for the API functions, specified with and without prototypes for use with standard C, ANSI C, or C++ compilers.
arfree.h
External declarations for the FreeAR functions. These functions recursively free all allocated memory associated with a particular data structure.
cmdbfree.h
External declarations for the FreeCMDB functions. These functions recursively free all allocated memory associated with a particular data structure.
arstruct.h
Core and reserved subclasses ID definitions, database separator characters, and labels for exporting structure definitions.
Developer’s Reference Guide
C API package contents
Library files You must have arcatalog_eng.dll in your path at runtime and make sure the lib directory contains the BMC Atrium CMDB C API library files listed in Table 2-4.
NOTE The SDK contains files that are not listed here. Those files are required for Java API or for working with the cmdbdriver program, but are not required to create a C API program. Table 2-4: C API library files Platform
Files
Windows
arapi71.dll arcatalog_eng.dll arjni71.dll arrpc71.dll arutiljni71.dll arutl71.dll cmdbapi21.dll cmdbjni21.dll icudt32.dll icudtbmc32.dll icuinbmc32.dll icuucbmc32.dll mfc71.dll msvcp71.dll msvcr71.dll rcmn71.dll
Solaris
libarjni71.so libarutiljni71.so libcmdbapi21.so libcmdbjni21.so libicudatabmc.so.32 libicui18nbmc.so.32 libicuucbmc.so.32 libjlicapi71.so
AIX
libarjni71.a libarutiljni71.a libcmdbjni21.a libcmdbapi21.a libicudatabmc32.a libicui18nbmc32.a libicuucbmc32.a libjlicapi71.a
Chapter 2 Getting started
25
BMC Atrium CMDB 2.1.00
Platform
Files
HP-UX
libicudatabmc.sl.32 libicui18nbmc.sl.32 libicuucbmc.sl.32 libarjni71.sl libarutiljni71.sl libcmdbapi21.sl libcmdbjni21.sl libjlicapi71.sl
Linux
libicudatabmc.so.32 libicui18nbmc.so.32 libicuucbmc.so.32 libarjni71.so libarutiljni71.so libcmdbapi21.so libcmdbjni21.so libjlicapi71.so
For Solaris and Linux: To load dynamic libraries, you need to include the -ldl link flag in the link command. For more information about linking and compiling your code, see the driver sample makefile in the sdk\samples\driver subdirectory of the BMC Atrium CMDB installation directory.
Compiler information Before you write C API programs, make sure that the following software programs are installed or configured on your system:
Microsoft Visual C++ version 7.0 or later Structure member alignment: 8
bytes
Set code generation to Multithreaded
(default) DLL, not DebugMultithreaded DLL. Where
other included libraries cause conflicts, add the project options to avoid using the Debug C runtime library. If your program references this library at runtime, memory management errors will occur when memory pointers are referenced by both the Debug and Release C runtime libraries.
/nodefaultlib:"MSVCRTD" to
ANSI standard C or C++ compiler (for UNIX)
IMPORTANT If you develop C++ clients that run on HP machines using the BMC Atrium CMDB C API, you need to compile your code with the __HPACC_THREAD_SAFE_RB_TREE flag enabled. This is because the libraries that the tree header file uses, which includes tree.cc, are not thread safe. For more information, see the following link: http://h21007.www2.hp.com/dspp/tech/tech_TechDocumentDetailPage_IDX/ 1,1701,7866,00.html.
26
Developer’s Reference Guide
Java API package contents
Link information Table 2-5 lists the libraries that your programs must use for linking to BMC Atrium CMDB. Table 2-5: Link files Platform
Links
Windows
cmdbapi21.dll arapi71.dll
Solaris, Linux
libcmdbapi21.so libarapi71.so
HP-UX
libcmdbapi21.sl libarapi71.sl
AIX
libcmdbapi21.a libarapi71.a
Java API package contents The Java API package includes several header files and library files. When you install the BMC Atrium CMDB application, the Java API is also installed with the package.
NOTE In version 2.1, the BMC Atrium CMDB Java API has changed as a result of modifications in the AR System Java API. For a list of affected CMDB Java classes, see the Javadoc API Help, which is located in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. To access the Javadoc API Help, open the index.html file.
Requirements To build and run a Java API program on either Windows or UNIX, you need the following environment components:
All C API libraries and DLLs, as listed in the “C API package contents” on page 24.
J2SE Software Development Kit (SDK), version 1.5.0_06 or higher. Windows dynamic link library (DLL) files or UNIX library files as listed in Table 2-4 on page 25.
Chapter 2 Getting started
27
BMC Atrium CMDB 2.1.00
Library files When you install BMC Atrium CMDB, a list of Java API library files are installed with the application. For more information about these library files, see the section “Installation and deployment” of the JavaAPI_Overview.html page of the Javadoc API Help.
Header files Table 2-6 lists the header files that are installed with the Java API. Table 2-6: Header files for the CMDB programs Header file name
Description
com.bmc.arsys.api.*;
AR System API functions
com.bmc.cmdb.api.*;
CMDB API functions
java.util.*;
Java utilities library
Version information for BMC Atrium CMDB API With BMC Atrium CMDB 2.1.00, you can view version information, such as version number, and build date and time for the BMC Atrium CMDB API. To view the information, open a command line window and type java –jar cmdbapi21.jar. On Windows, a command line window is displayed, as shown in Figure 2-1 Figure 2-1: API version information
Build time Build date
28
Developer’s Reference Guide
Sample source code
Sample source code The sdk/samples/driver subdirectory in the BMC Atrium CMDB installation directory, includes the source code for a sample BMC Atrium CMDB client program. A compiled version of the cmdbdriver program is located in the sdk/bin directory. When the BMC Atrium CMDB API package is installed, a series of directories is created in the installation directory. The src directory contains subdirectories with source code for the cmdbdriver sample program. For more information about the cmdbdriver program, see Chapter 4, “Working with the cmdbdriver program.” After compiling the source code or locating the prebuilt program supplied with the API, you can use cmdbdriver to:
Identify function input parameters and load them with appropriate values. Examine the content and structure of function output parameters. Experiment with different parameter values.
Migrating to the BMC Atrium CMDB from 1.1 to 2.0 API In version 2.0, several API changes were made, such as modifications to the function parameters and data structures. For the list of parameters and data structures that were modified, see the BMC Atrium CMDB 2.0 Developer’s Reference Guide.
Chapter 2 Getting started
29
BMC Atrium CMDB 2.1.00
30
Developer’s Reference Guide
Chapter
3
Programming common BMC Atrium CMDB tasks This section describes how to use the BMC Atrium CMDB Java methods to perform common tasks. These tasks are explained using Java code samples. The following topics are provided:
Java program requirements (page 32) Working with configuration item classes and instances (page 32) Working with relationship classes and instances (page 37)
Chapter 3 Programming common BMC Atrium CMDB tasks
31
BMC Atrium CMDB 2.1.00
Java program requirements The procedural building blocks of a BMC Atrium CMDB program are functions or operations that can invoke one another. For more information about specific Java method parameters, see the Javadoc API Help, which is located in the sdk/ javadoc/cmdbapi/ subdirectory of your CMDB installation directory. To access the Javadoc API Help, open the index.html file. For your Java code to compile with the BMC Atrium CMDB classes, make sure you point the class path environment variable to the BMC Atrium CMDB jar files directory. For the list of header files and link files required for your Java code, see “Java API package contents” on page 27.
Working with configuration item classes and instances Configuration items (CIs) are the focal point of the BMC Atrium CMDB application. The attributes of a CI and other properties, such as data storage and inheritance, are encapsulated in a CI class definition. When you create a class, you define all the characteristics for it, such as the class name, namespace, superclass, and data storage method.
Creating a CI class The following example creates two classes, PhoneSystem and Socket. Both classes are created in the ACME namespace. All class definitions that extend the CDM use a namespace other than BMC.CORE. Example: Creating classes //Create variables to hold the class name data String acmeNamespace = "ACME"; String phoneSystemClassName = "phoneSystem"; String socketClassName = "Socket"; //Create the class name key for the Phone System class. CMDBClassNameKey phoneSystemClassNameKey = new CMDBClassNameKey(phoneSystemClassName, acmeNamespace); String phoneSystemClassID = "ABCD-1234";
32
Developer’s Reference Guide
Working with configuration item classes and instances
//Create an instance of the CMDBClass CMDBClass phoneSystemClass = new CMDBClass(phoneSystemClassNameKey, phoneSystemClassID, null); try { //Create the Phone System class in BMC Atrium CMDB phoneSystemClass.create(currentUser); } catch (ARException ex) { System.out.println(ex.toString()); } //create the socket class CMDBClassNameKey socketClassNameKey = new CMDBClassNameKey(socketClassName, acmeNamespace); String socketClassID = "ACME_SocketClass"; CMDBClass socketClass = new CMDBClass(socketClassNameKey, socketClassID, null); // create the socket class in BMC Atrium CMDB try { socketClass.create(currentUser); } catch (ARException ex) { System.out.println(ex.toString()); }
In the example, the phoneSystemClassNameKey and socketClassNameKey class variables hold the class name and namespace definitions for the phoneSystem and Socket classes respectively. The classNameKey class variables are passed as parameters to the constructor of the CMDBClass class. A class ID is an identification string that uniquely identifies a particular class within the BMC Atrium CMDB. In the try loop, the phoneSystemClass and socketClass classes are created in the BMC Atrium CMDB. The currentUser parameter is a pre-instantiated ARServerUser class that has valid user login credentials. For more information about the parameters for the CMDBCreateClass function, open index.html of the Java API Help, which is located in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
Chapter 3 Programming common BMC Atrium CMDB tasks
33
BMC Atrium CMDB 2.1.00
Creating attributes for your class Every class you create will have attributes that hold different values for each instance of the class. The following example illustrates how to create attributes for the phoneSystemClass. Example: Creating attributes //Create attributes for the phoneSystem class String serialNumAttrName = "ACMESerialNumber"; int serialNumFieldId = ACME_SERIAL_NUM_FIELD_ID; int serialNumEntryMode = CMDBAttribute.CMDB_ATTR_ENTRYMODE_REQUIRED; //Define a data type and limit for the attribute CMDBAttributeLimit serialNumLimit = newCMDBCharLimit(30); //Create a default value for the attribute Value serialNumDefaultValue = null; //Create a Java instance of the attribute CMDBAttribute serialNumAttr = new CMDBAttribute(serialNumAttrName, serialNumFieldId, serialNumEntryMode, serialNumLimit, null); //Create another attribute for the phoneSystem class String costAttrName = "Cost"; int costFieldId = ACME_COST_FIELD_ID; int costEntryMode = CMDBAttribute.CMDB_ATTR_ENTRYMODE_OPTIONAL; //Create a variable of type Currency CMDBAttributeLimit costLimit = new CMDBCurrencyLimit; //create a Java instance of the Cost attribute CMDBAttribute costAttr = new CMDBAttribute(costAttrName, costFieldId, costEntryMode, costLimit, null); //Create a hash map to hold the attribute data HashMap attributeHashMap = new HashMap(); //Add the two attributes to the hash map attributeHashMap.put(serialNumAttruName, serialNumAttr); attributeHashMap.put(costAttrName, costAttr); //Associate these attributes to the phoneSystemClass phoneSystemClass.setAttributes(attributeHashMap); // Update the BMC Atrium CMDB with the new attributes try { phoneSystemClass.update(currentUser); } catch (ARException ex) { System.out.println(ex.toString()); }
34
Developer’s Reference Guide
Working with configuration item classes and instances
In the example, the serialNumAttrName, serialNumFieldId, and serialNumEntryMode variables are created to hold the attribute name, attribute field ID, and the entry mode for the attribute, respectively. When you specify the Required entry mode for an attribute, you must provide a value for this attribute for every instance of the class. The field ID is a unique numeric identifier for an attribute. The data type and limit for the attribute is defined using the serialNumLimit class variable, which is of type CMDBAttributeLimit class. In the example, the serialNumAttr attribute is defined as a character data type with a limit of 30 characters. A default value of Null is specified for the attribute in the serialNumDefaultValue variable. This value is used if no value is provided for the ACMESerialNumber attribute when creating an instance. After these values are defined for the variables, they are passed as parameters to the CMDBAttribute class constructor, which creates a Java instance of the attribute. In the example, the Cost attribute is created to hold the cost information for the phoneSystemClass class. Similar to the ACMESerialNumber definition, the attribute name, field ID, entry mode, and attribute limit details are specified for the Cost attribute. The entry mode for the Cost attribute is defined as Optional. The attribute data type is defined as Currency. After the attributes for a specific class are defined as CMDBAttribute variables, these attributes are added to a hash map. These hash maps can hold multiple attributes at a time. The setAttributes method of the phoneSystemClass is used to set the attributes for the class. The hash map array, which holds the attribute definitions, is passed to this setAttributes method as a parameter. After the attributes are set in the class, the class information is updated in the BMC Atrium CMDB using the update method of the phoneSystemClass. For more information about the setAttributes method of the CMDBClass Java class, data types, and data limits, open index.html of the Java API Help, which is located in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
Chapter 3 Programming common BMC Atrium CMDB tasks
35
BMC Atrium CMDB 2.1.00
Creating a CI instance After you create a class in the BMC Atrium CMDB, you can create an instance of this class. When you create an instance, you must specify all the required attributes for the class. The following code illustrates how to create an instance of the phoneSystemClass. Example: Creating a CI instance //Create variables to hold the serial number and cost details for the instance String serialNum = "SN-1492-22919"; Value cost = new Value("12.95",Constants.AR_DATA_TYPE_CURRENCY); CMDBAttributeValue serialNumAttrValue = new CMDBAttributeValue(serialNumAttrName, serialNum); CMDBAttributeValue costAttrValue = new CMDBAttributeValue(costAttrName, cost); //Create a HashMap to hold the attribute values Map attributeHashMap = new HashMap(); attributeHashMap.put(serialNumAttrName, serialNumAttrValue); attributeHashMap.put(costAttrName, costAttrValue); // create an instance of a phoneSystemClass CMDBInstance phoneInstance = new CMDBInstance(phoneSystemClassNameKey, attributeHashMap); //create a variable to hold the dataset ID String acmeDatasetId = "ACME.DATASET"; try { //Create the new instance within the BMC Atrium CMDB phoneInstance.create(currentUser, datasetId); } catch (ARException ex) { System.out.println(ex.toString()); } //Get the instance ID of the new instance String phoneSystemInstId = phoneInstance.getId();
In the example, the serialNum and cost variables are created to hold the serial number and cost information for the instance. The serialNumAttrValue and costAttrValue class variables are created of type CMDBAttributeValue. After the attribute name and other attribute information is created as explained in the previous section, the serialNumAttrName and serialNum variables are assigned to the serialNumAttrValue variable, which is of type CMDBAttributeValue. The costAttrValue class variable holds the costAttrName and cost details for the instance. Using a hash map, the serial number and cost details are added to the phoneInstance instance, which is of type CMDBInstance. To create the new instance in Java, the phoneSystemClassNameKey, which was shown in “Creating a CI class” on page 32, and attributeHashMap variables are passed as parameters to the instance. 36
Developer’s Reference Guide
Working with relationship classes and instances
Before creating the phoneInstance instance in the BMC Atrium CMDB, a dataset variable is created to specify the dataset to which the instance belongs. In the example, the acmeDatasetId variable is created that holds the dataset details. Because an instance must reside in a dataset, you must specify a dataset ID for the instance. In the try loop, the phoneInstance instance is created in the BMC Atrium CMDB. The currentUser and datasetId parameters are passed to the create method of the instance. After the instance is created in the BMC Atrium CMDB, the instance ID of the new instance is retrieved using the getId method. For more information about the parameters for the create method of the CMDBInstance Java class, open index.html of the Java API Help, which is located in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
Working with relationship classes and instances The BMC Atrium CMDB enables you to create relationships between CI classes. To relate two CI classes, you must create a relationship class that refers to the two CI classes. After you create the relationship class, you create a relationship between the two CI instances using this relationship class.
Creating a relationship class When defining the relationship class, you can specify several characteristics for the relationship, such as the cardinality of the relationship, for example one-to-many or one-to-one, or whether the class defines a weak relationship. In the following example, a relationship class is created between the phoneSystemClass class and the socketClass class. Example: Creating a relationship class //Create a variable that holds the relationship class name String relationshipClassName = "phoneSystemToSocketRelationship"; CMDBClassNameKey relationshipClassKey = new CMDBClassNameKey(relationshipClassName, acmeNamespace); //Create a variable that holds the two classes that will be related CMDBClassNameKey[] relationshipClasses = {phoneSystemClassKey, socketClassKey}; //create a role name for each instance in the relationship String[] roleNames = {"Source", "Destination"}; //create the relationship class
Chapter 3 Programming common BMC Atrium CMDB tasks
37
BMC Atrium CMDB 2.1.00
CMDBRelationship phoneSystemToSocketRelClass = new CMDBRelationship(relationshipClassKey, null, roleNames, relationshipClasses); //set the cardinality of the relationship phoneSystemToSocketRelClass.setCardinality( CMDBRelationship.CMDB_CLASS_RELATIONSHIP_CARDINALITY_1_MANY); try { // create the relationship class in the BMC Atrium CMDB phoneSystemToSocketRelClass.create(this.getARServerUser()); } catch(ARException ex){ System.out.println(ex.toString());}
In the example, the relationshipClassName variable is created to hold the name of the relationship class. The relationshipClassKey variable, which is of type CMDBClassNameKey, is created to define the class name and namespace details for the relationship class. The class name and namespace information for the two classes that will be related in the relationship class is specified in the relationshipClasses variable. The role names for the two classes are specified in the roleNames variable. Each of the two classes in a relationship must have its role defined. You can define role names for Class 1 and Class 2, known respectively as the source and destination members of the relationship. The BMC Atrium CMDB prepends these role names to the attributes of a relationship class that pertain to its members. For example, on any CDM relationship class the attributes that hold the class IDs of its member CIs are named Source.ClassId and Destination.ClassId. After the role name and class name key details are defined, the instance of the relationship class is created,
phoneSystemToSocketRelClass Java which of type CMDBRelationship.
The setCardinality method of the CMDBRelationship class sets the cardinality. In this example, the cardinality for the relationship class is set to one-to-many. A oneto-many cardinality means that for each instance of the phoneSystem class, there can be many relationships to instances of the socket class. In the try loop, the phoneSystemToSocketRelationship relationship class is then created in the BMC Atrium CMDB. For more information about the parameters for the create method of the CMDBRelationship Java class, open index.html of the Java API Help, which is located in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
38
Developer’s Reference Guide
Working with relationship classes and instances
Creating a relationship between two CI instances To create a relationship between two CI instances, you create a relationship instance. An instance of a relationship class defines a specific relationship between two particular instances of two CI classes. The following code illustrates how to create a relationship between two CIs. In the following example, it is assumed that the newPhoneSystem and newSocket variables, representing existing CI instances, the phoneClassId and the socketClassId variables are already created. Example: Relating two CIs //retrieve the instance IDs for the newPhoneSystem and newSocket instances String phoneInstId = newPhoneSystem.getId(); String socketInstId = newSocket.getId(); //create the required attributes of the relationship instance CMDBAttributeValue srcInstId = new CMDBAttributeValue("Source.InstanceId", new Value(phoneInstId)); CMDBAttributeValue destInstId = new CMDBAttributeValue("Destination.InstanceId", new Value(socketInstId)); CMDBAttributeValue datasetId = new CMDBAttributeValue("DatasetId", new Value(acmeDatasetId)); Map attrHashMap = new HashMap(); attrHashMap.put(srcInstId.getAttributeName(), srcInstId); attrHashMap.put(destInstId.getAttributeName(), destInstId); attrHashMap.put(datasetId.getAttributeName(), datasetId); // create a Java instance of the relationship class CMDBInstance relInstance = new CMDBInstance(relationshipClassKey, attrHashMap); try { //Create an instance of the class within the BMC Atrium CMDB relInstance.create(this.getARServerUser()); }
In the example, the phoneInstId and socketInstId variables are created to hold the instance IDs of the newPhoneSystem and newSocket instances. The srcInstId and destInstId variables are created to hold the IDs of the source and destination classes, which are phoneInstId and socketInstId respectively. The datasetId variable holds the dataset ID of the ACME dataset. These source, destination, and dataset ID variables are written to the attrHashMap array. The Java instance of the relationship class is then created using the constructor of the CMDBInstance class. In the try loop, the relationship instance is created in the BMC Atrium CMDB. The getARServerUser method of the relInstance instance retrieves the user ID that is currently used to log in to the AR System server. The user ID parameter is required to create the instance in the BMC Atrium CMDB.
Chapter 3 Programming common BMC Atrium CMDB tasks
39
BMC Atrium CMDB 2.1.00
For more information about the parameters for the create method of the CMDBInstance Java class, open index.html of the Java API Help, which is located in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
Retrieving instance details You can query CI and relationship instances that exist in the BMC Atrium CMDB. The following code illustrates how to query instances of the phoneSystemClass class. Example: Querying an instance //Set specific attributes to return String[] attributesToGet = {"InstanceId", "ReconciliationIdentity", "DatasetId"}; //Specify values for the query to retrieve all instances where DatasetId //is ACME.DATASET String query = "'DatasetId' = \"ACME.DATASET\""; try { CMDBInstance[] instanceList = CMDBInstance.findObjects( this.getARServerUser(), phoneSystemClassKey, query, attributesToGet, null, //do not sort CMDB_START_WITH_FIRST_INSTANCE, CMDB_NO_MAX_LIST_RETRIEVE, Null); } catch(ARException ex){ System.out.println(ex.toString()); }
In the example, the attributes to retrieve in the query are specified in the attributesToGet array of type String. The query in this example retrieves the InstanceID, ReconciliationIdentity, and DatasetID attributes from all instances. If no attributes are specified to return in the query, all attributes of the instances will be returned by default. The query variable specifies a qualification that will retrieve all instances where the dataset ID is ACME.DATASET. In the try loop, the findObjects method of the CMDBInstance Java class is used to retrieve instances. The retrieved instances are placed in the instanceList array, which is of type CMDBInstance. For more information about the parameters for the findObjects method of the CMDBInstance Java class, open index.html of the Java API Help, which is located in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
40
Developer’s Reference Guide
Chapter
4
BMC Atrium CMDB tools
This section describes how to use the various BMC Atrium CMDB tools. The following topics are provided:
Working with the cmdbdriver program (page 42) Migrating data between BMC Atrium CMDB servers (page 45) Using the extension loader (page 53) Integrating the CI Relationship Viewer with other applications (page 63) Configuring the CI Relationship Viewer (page 69) Creating CMDB status alerts (page 75) Importing data with Integration Engine (page 76) Working with SQL views (page 77) Debugging BMC Atrium CMDB API programs using print.c routines (page 78)
Chapter 4
BMC Atrium CMDB tools
41
BMC Atrium CMDB 2.1.00
Working with the cmdbdriver program The cmdbdriver program, which prompts you one at a time for parameters to each command you type, enables you to execute various BMC Atrium CMDB API functions from a command line, such as class, instance, and attribute data manipulation. Figure 4-1 on page 43 displays the list of tasks that you can perform with the cmdbdriver program. The parameters that are required for cmdbdriver commands are the same as the parameters that are required for the equivalent C API functions. For more information about API functions and their parameters, see Chapter 5, “C API functions and data structures.”
From the command line Once you compile the source code or locate the prebuilt program supplied with the API, you are ready to use the cmdbdriver program. When you execute the program, the system displays the list of cmdbdriver commands. You must provide the necessary login information and perform initialization operations for connecting to the BMC Atrium CMDB. You can then use the cmdbdriver commands to call any number of API functions. When you are working with the specific commands, see Chapter 5, “C API functions and data structures,” to enter the appropriate values for the function parameters. If you are working with specific entries, use leading zeros to see the entry ID of those entries.
To use the cmdbdriver program (Windows and UNIX) 1 Start the cmdbdriver program using the following steps based on your platform:
Windows Navigate to C:\Program
Files\AR System Applications\\BMC
Atrium CMDB\sdk\bin.
Double-click cmdbdriver.exe. UNIX Navigate to /usr/arsystem//cmdb/sdk/bin. Type the command cmdbdriver.
42
Developer’s Reference Guide
Working with the cmdbdriver program
Figure 4-1: Initial screen of cmdbdriver
2 Initialize an API session with the init command. 3 Specify the login parameters with the log command.
You are prompted to specify several parameters one at a time. You must enter the following parameters:
Type a valid user name and password. Type the name of your server. You can skip the other parameters. After you specify the login parameters, the command prompt appears. 4 Type the abbreviation of the function and provide the appropriate input parameter
values. For example, for importing class definitions, type impdf at the prompt. Use the help command (h or ?) to display the cmdbdriver commands. When you are finished using the cmdbdriver, type e or q to exit the program.
Chapter 4
BMC Atrium CMDB tools
43
BMC Atrium CMDB 2.1.00
Using a script You can also use a script file that contains the cmdbdriver commands and execute it at the cmdbdriver prompt. You can create this script file using any text editor, such as Notepad or Wordpad. Example 1: cmdbdriver script file—Import definitions command impdf 2 1 BMC.CORE BMC_ComputerSystem 1 BMC.CORE BMC_SystemComponent 1 C:\ImportClasses
This example uses a script to import the BMC_ComputerSystem and BMC_SystemComponent classes from the BMC.CORE namespace. To accept a default value for a parameter in the cmdbdriver script, insert a blank line. Example 2: cmdbdriver script file—Get List Class command glc BMC.CORE BMC.CORE BMC_System BMC.CORE BMC_Component T
This example uses a script to retrieve the destination CI for the BMC_System source class. BMC_Component is the relationship between these CIs and both these classes exist within the BMC.CORE namespace. To accept a default value for a parameter in the cmdbdriver script, insert a blank line. The blank line in this example accepts the default value for the Number of characteristics parameter. The default for this parameter is set to 0 (none). You can use the rec and srec commands of the cmdbdriver program to record cmdbdriver commands. The rec command starts recording the commands you use at the prompt and srec stops recording these commands. When you type the rec command, you are prompted for the name of the file in which to store these commands. After you record the commands in a file, you can execute it at the cmdbdriver program using the execute command.
44
Developer’s Reference Guide
Migrating data between BMC Atrium CMDB servers
Using cmdbdriver on UNIX The cmdbdriver program requires specific shared libraries in the bin subdirectory of the BMC Atrium CMDB installation directory. By default, this subdirectory is located at /usr/arsystem//cmdb/sdk/bin. These shared libraries are not added in the library path when you install BMC Atrium CMDB. To add them to the library path, you need to set the appropriate library path variable using setenv or export command. The variable that you need to set varies for each UNIX platform. Table 4-1 lists the various UNIX platforms and their corresponding variables. Table 4-1: UNIX platforms and corresponding Library Path variables UNIX platform
Variable name
Solaris and Linux
LD_LIBRARY_PATH
HPUX
SHLIB_PATH
AIX
LIBPATH
Migrating data between BMC Atrium CMDB servers This section explains how to migrate data from one BMC Atrium CMDB server to another using the cmdbdriver program. The most common reason to migrate data from one BMC Atrium CMDB to another is to move your BMC Atrium CMDB into production. The following procedure explains the steps to migrate from a BMC Atrium CMDB development server to a BMC Atrium CMDB production server. Before migrating your BMC Atrium CMDB data, make sure both your BMC Atrium CMDB servers are configured and running.
NOTE The procedure explained in this section covers the steps for migrating only BMC Atrium CMDB definitions and data. If you have other BMC Software applications installed on your development server that access the BMC Atrium CMDB, such as BMC Remedy Asset Management, you need to migrate that data separately. Migrating your BMC Atrium CMDB from a development server to a production server requires the following high-level steps: Step 1 Export class data with cmdbdriver (see page 47). Step 2 Export instance data with cmdbdriver (see page 48). Step 3 Import class data with cmdbdriver (see page 49). Step 4 Import instance data with cmdbdriver (see page 50).
Chapter 4
BMC Atrium CMDB tools
45
BMC Atrium CMDB 2.1.00
Step 5 Export reconciliation information with BMC® Remedy® User (see page 50). Step 6 Import reconciliation information with BMC® Remedy® Import (see page 52).
For information about known issues regarding the procedure explained in this section, see “Known issues” on page 52. You can use cmdbdriver scripts to perform some of these steps.
Logging in to the cmdbdriver program The cmdbdriver program is the command-line interface to the BMC Atrium CMDB C API. Prior to BMC Atrium CMDB 1.1 Patch 002, the driver program was named osdriver.The following steps describe the procedure to start the cmdbdriver program.
To log in to the cmdbdriver program 1 Start the cmdbdriver program using the following steps based on your platform:
Windows Navigate to C:\Program
Files\AR System Applications\\BMC
Atrium CMDB\sdk\bin.
Double-click cmdbdriver.exe. UNIX Navigate to /usr/arsystem//cmdb/sdk/bin. Type the command cmdbdriver. 2 Type the command init to initialize the driver. 3 Type the command log to log into your development server.
You are prompted to specify several parameters one at a time. You must enter the following parameters:
Type a valid user name and password. Type the name of your server. You can leave the other parameters blank. After you specify the login parameters the command prompt appears. 4 Type the abbreviation of the function and provide the appropriate input parameter
values. For example, for importing class definitions, type impdf at the prompt. Use the help command (h or ?) to display the cmdbdriver commands. When you are finished using the cmdbdriver, type e or q to exit the program.
46
Developer’s Reference Guide
Migrating data between BMC Atrium CMDB servers
Step 1—Exporting class data with cmdbdriver If you have added or changed any CI or relationship classes on your development server, you need to export them. This class data is also called metadata because it describes the instance data in the BMC Atrium CMDB. You need to export only those classes that you have added or changed, and their subclasses. When you export a superclass that you modified, all the subclasses for the superclass will also be exported with it. If you have not made any additions or changes, you can skip Step 1 and import the class definitions using the steps explained in “Step 3—Import class definitions with cmdbdriver” on page 49.
To export definitions for a class and its subclasses 1 Log in to your development server. 2 Start the cmdbdriver program and specify your user credentials.
For more information about logging in to the cmdbdriver program, see “Logging in to the cmdbdriver program” on page 46. 3 Type the xexpdf command. 4 At the Export all class? (F): prompt, type T to export all class definitions from
the BMC Atrium CMDB. If you press Enter to accept the default value of F, you need to specify the namespace, class, and attribute details for which you want to export the class definitions. 5 At the Export all attributes with classes? (T): prompt, press Enter to accept
the default value of True. 6 At the Filename for exported data: prompt, specify the file name in which to save
the exported definitions. Make sure you specify the exact path for the file name, for example, you specify a file name that already exists, the contents of the file is overwritten.
c:\ExportedClassDefinitions\CoreClassDefinitions.xml. If
Chapter 4
BMC Atrium CMDB tools
47
BMC Atrium CMDB 2.1.00
Step 2—Export instance data with cmdbdriver You must export both CI and relationship configuration data from your development server.
To export instance data for a class 1 Log in to your development server. 2 Start the cmdbdriver program and specify your user credentials.
For more information about starting the cmdbdriver program, see “Logging in to the cmdbdriver program” on page 46. 3 Type the xexpdt command to export instance data from the BMC Atrium CMDB. 4 At the Export instance data from all classes? (F): prompt, type T to export all
instance data. If you press Enter to accept the default value of F, you need to specify the namespace, class, and attribute details for which you want to export the class definitions. 5 At the Dataset ID (): prompt, type the dataset ID from which you want to export
the instance data. 6 At the Filename for exported data: prompt, specify the file name in which to save
the exported instance data. Make sure you specify the exact path for the file name, for example, If you specify a file name that already exists, the contents of the file is overwritten. c:\ExportedInstanceData\CoreInstanceData.xml.
48
Developer’s Reference Guide
Migrating data between BMC Atrium CMDB servers
Step 3—Import class definitions with cmdbdriver You must import the class definitions that you exported from your development server in Step 1 and 2 of this procedure, to your production server. Use the steps explained in this section to migrate the class definitions to the production server.
To import class definitions 1 Log in to your production server. 2 Start the cmdbdriver program and specify your user credentials.
For more information about logging in to the cmdbdriver program, see “Logging in to the cmdbdriver program” on page 46. 3 Type the impdf command to import class definitions into the BMC Atrium CMDB. 4 Specify the directory path where the import data is located, such as c:\ExportedClassDefinitions.
5 To import all class definitions contained in the source folder (recommended),
accept the default of 0 and skip to step 8. To import definitions for a specific class, type 1 for the Number of Import Items.
NOTE When you enter a number other than 0, you cannot automatically import the subclasses of a specified class. Each subclass must be specified as a separate import item, either by increasing the number you specify here or by running the impdf command multiple times. 6 To import a class from the source folder, accept the default value of 1.
To import attributes for the class, run the impdf command again and type 2 at this prompt. 7 At the Class Name prompt, type the namespace and class name for the class, for
example, BMC.CORE. and BMC_BaseElement respectively. 8 Accept the default value of 1 to import Metadata. 9 Type any of the following import options:
1 (Create)—Create the specified class in the BMC Atrium CMDB. If this class already exists, the program generates an error.
2 (Overwrite)—Overwrite
the existing class in the BMC Atrium CMDB.
The definition is imported.
Chapter 4
BMC Atrium CMDB tools
49
BMC Atrium CMDB 2.1.00
Step 4—Import instance data with cmdbdriver You must import the CI and relationship instances from the export files, which contain the class and instance data you exported in Step 1 and 2 of this procedure, to your production server.
To import instances of a class or classes 1 Log in to your production server. 2 Start the cmdbdriver program and specify your user credentials.
For more information about logging in to the cmdbdriver program, see “Logging in to the cmdbdriver program” on page 46. 3 Type the impdt command to import instance data into the BMC Atrium CMDB. 4 Type any of the following import options to specify the action to take when an
instance to be imported has the same Instance ID as an existing instance in the BMC Atrium CMDB:
1 (Error on dup)—If
2 (Generate new ID on dup)— If the instance already exists with the same Instance ID, generate a new Instance ID and import the instance.
3 (Merge on dup)— If the instance already exists with the same Instance ID, merge the new instance and the existing instance.
4 (Generate new ID for all)—Create a new Instance ID for the instance to import even if the new instance is not a duplicate.
the instance already exists with the same Instance ID, generate an error message and do not import the instance.
5 Type the directory path where the import data is located, for example, c:\ExportedInstanceData.
The data is imported into the BMC Atrium CMDB.
Step 5—Export reconciliation definitions You can export reconciliation definitions from one server and import them onto another server instead of manually recreating all your definitions. You can export all your reconciliation definitions, or select one or more definitions of a certain type.
NOTE When exporting definitions, make sure you save them in an AR Export (.arx) format. If you use comma-separated values (.csv), or XML (.xml) formats, the resulting files will not import correctly using the arimportcmd command. For more information about AR Export files, see the BMC Remedy Action Request System 7.1.00: Form and Application Objects guide.
50
Developer’s Reference Guide
Migrating data between BMC Atrium CMDB servers
Any definitions used by those you select are also exported. For example, if you select a job, the export will include that job plus all the activities in it, plus all the rulesets in those activities, and so on. You can export reconciliation definitions either using BMC Remedy User or a browser. When exporting definitions from a browser, several file dialogs might appear, depending on the definitions you export. Each dialog box requires you to enter an export filename for a particular definition.
NOTE Due to the browser limitation, BMC recommends that you use BMC Remedy User for exporting reconciliation definitions.
To export reconciliation definitions 1 Using BMC Remedy User, open the CMDB Console. 2 Click the Reconciliation Manager tab and choose the Export Definitions link from
the left navigation pane. 3 Select an Export Type:
Everything—All definitions. Job—Selected jobs and the definitions used by them. Group—Selected Identification groups, Qualification groups, Precedence groups, and Workflow Execution groups and the definitions used by them.
Dataset—All datasets. DatasetMergePrecedenceSet—Selected Dataset Merge Precedence sets and the definitions used by them. 4 If you selected either Job, Group, or DatasetMergePrecedenceSet, select the
definitions to be exported. If your Export Type is Group, you have the option of also exporting the activities that reference your selected definitions. To do this, click the Options tab and select Include Associations. 5 Type the fully qualified File Name to which the definitions should be exported.
You can use any of the approved extensions for the file name. For more information about the extensions for the export definitions file, see “Step 5—Export reconciliation definitions” on page 50. If you include no path or a relative path, the file is placed in or under the BMC Remedy User application folder. 6 Click Export.
The definitions are exported.
TIP If you encounter errors when exporting reconciliation definitions, see the BMC Atrium CMDB 2.1.00 Troubleshooting Guide to correct them.
Chapter 4
BMC Atrium CMDB tools
51
BMC Atrium CMDB 2.1.00
Step 6—Import reconciliation definitions You import reconciliation definitions by using the BMC Remedy Import command-line interface (CLI).
NOTE Before using the CLI on UNIX for the first time, you must add an entry to your library path. The CLI also has several other options not described in the following procedure, some of which might be necessary depending on your AR System server environment. For more information about these topics, see the BMC Remedy Action Request System 7.1.00: Integrating with Plug-ins and Third-Party Products guide.
To import reconciliation definitions 1 Open a command prompt. 2 If using Windows, change to the directory where BMC Remedy Import and other
AR System clients are installed. The default directory is c:\Program Files\AR System. 3 Enter the command: arimportcmd -x -u -p -o -l -e 179 -D 4
For , specify the full path to the file containing the exported definitions from the procedure “To export reconciliation definitions” on page 51. Specifying a log file is optional, but recommended in case there are any errors with the import. The -e 179 option enables you to verify whether a definition you are importing already exists. This check is performed based on the globally unique identifier (GUID) values. Specifying the -D4 option updates an entry if a match is found. If no match is found, a new entry is created. For more information about the various options for the arimportcmd command, click the Help menu in BMC Remedy Administrator and search for the command.
Known issues These issues can occur when performing the migration procedures in this section.
When exporting or importing instances for a categorization class, data from its superclass is also exported or imported. This is because a categorization class stores its instance data on the same AR System form as its superclass.
When you attempt to export instance data from an abstract class, cmdbdriver crashes. There is no reason to do this, since abstract classes cannot have any instances.
When importing the weak member in a weak relationship, you will receive an error if that instance already exists. You must delete the existing weak member before you can import it. 52
Developer’s Reference Guide
Using the extension loader
Using the extension loader The cmdbExtLoader program enables you to install one or more of BMC Atrium CMDB classes from one server to another. You use the extension loader either to extend the BMC Atrium CMDB or to install an extension pack. For information about the guidelines for extending the CDM, see the Concepts and Best Practices Guide. The extension loader program can also install objects other than the data model extensions. However, this guide covers only the instructions for installing class and attribute extensions. For more information about importing data into AR System forms, see the BMC Remedy Action Request System 7.1.00: Configuring guide. If you encounter errors when using the extension loader to install the extensions, see the Troubleshooting Guide to correct the issues.
The extension loader directory structure The directory structure of the extension loader program is displayed in Figure 4-2. Figure 4-2: Extension loader directory structure
At the top level is the directory where you copy the extension loader files, for example, CMDBExtensionLoader. Under the CMDBExtensionLoader directory is the common folder, and two cmdbExtLoader executables, one each for UNIX (no extension) and Windows (.exe).
NOTE You must name the directory that contains the extension subdirectories as extensions. If you specify any other name for this directory, the extension loader will not recognize it. After you copy the extension loader files into the extension loader directory you created, you create an extensions directory, as displayed in Figure 4-2. The extensions directory can contain one or more extension subdirectories. Each extension subdirectory can contain a package.xml file, an installation activity file, and one or more class XML files. These class files are obtained when you use the expdf command of the cmdbdriver program to export the class or attribute definitions.
Chapter 4
BMC Atrium CMDB tools
53
BMC Atrium CMDB 2.1.00
The following naming convention is used for extension subdirectories: -
where:
is a three-digit number ranging from 000 to 999. The instructs the extension loader to install the objects in the extensions directory in ascending order. Therefore, you must specify a lower for the object that you want to install first.
For example, if you have two extension subdirectories, 650-EXClass and 655EXClass, the 650-EXClass subdirectory will be installed first.
is an alphanumeric name for the extension. Make sure you do not use spaces, quotation marks, or wildcard characters in the element.
Examples of extension subdirectory names are 500-EXClass and 501-EXAtt.
Packaging and installing BMC Atrium CMDB extensions Packaging and installing your BMC Atrium CMDB extensions requires the following high-level steps: Step 1 Export the class definitions with cmdbdriver (see page 54). Step 2 Create the package.xml file (see page 55). Step 3 Create an installation activity file (see page 57). Step 4 Start the cmdbExtLoader program (see page 59).
Step 1—Export the class definitions using the cmdbdriver Before you create the extension package, you must export your class or attribute definitions.
To export class definitions 1 Create an extension subdirectory.
See “The extension loader directory structure” on page 53. This directory will contain all the extension loader files. 2 Export the class definitions using the cmdbdriver expdf command.
For more information about exporting class definitions with the cmdbdriver program, see “Step 1—Exporting class data with cmdbdriver” on page 47. The expdf command creates several XML files that contain the class definition information for the specified class.
54
Developer’s Reference Guide
Using the extension loader
Step 2—Create the package.xml file The package.xml file contains the registration and dependency information for the extension. The registration information defines the extension that you are creating. When the extension loader runs, it stores the extension registration values that you specify in the package.xml file, such as the extension name, version, and GUID in the SHARE:Application_Properties AR System form. A GUID is a unique ID for the extension. This ID is used by the extension loader program to determine if an extension is already installed. After you create an extension with a specific GUID, you can only change the version number to update the extension. The GUID will remain the same for the life span of an extension. Example: package.xml ComSys Hardware Component OS005056C0000898YWQgUsMLAAKwAA 1.0 cmdb OB00C04FA081BABZlxQAmyflAg1wEA BMC Atrium CMDB 2.1.00
This package.xml example instructs the extension loader program to install the ComSys Hardware Component class extension version 1.0 on the BMC Atrium CMDB application version 2.1.00. The first line of code is an xml version tag that is required for all XML files.
NOTE When you specify a GUID for the BMC Atrium CMDB dependency in your package.xml file, make sure you use the same GUID as shown in the example. This is the GUID stored in the SHARE:Application_Properties AR System form for the BMC Atrium CMDB.
Chapter 4
BMC Atrium CMDB tools
55
BMC Atrium CMDB 2.1.00
To create the package.xml file 1 Depending on whether you are creating a new extension or modifying an existing
extension, perform one of the following steps:
If you are creating a new extension, generate a GUID using the cg command of the cmdbdriver program. For more information about using the cmdbdriver program, see “Logging in to the cmdbdriver program” on page 46.
If you are modifying an existing extension, skip to step 2. 2 Specify values for the following elements in the package.xml file:
Registration information—Specify the following registration information for the extension:
—The
—The
—The version number for the extension. Modify the version number only if you are modifying an extension.
name for the extension.
GUID for the extension. For new extensions, specify the GUID that you created in step 1. For existing extensions, specify the currently existing GUID.
Dependencies—Specify the following dependency information for the extensions:
—The applications that the extension depends upon. The applications specified here can be other extensions, AR System applications, or the AR System Server on which you want to install the extension.
—The version number of the application specified in the element. You can either specify a value for the
element, which indicates the exact version number required for the application, or you can specify values for the and elements, which indicate the range of permissible version numbers for the application. 3 Save the package.xml file under the extension subdirectory you created in
“Step 1—Export the class definitions using the cmdbdriver.”
56
Developer’s Reference Guide
Using the extension loader
Step 3—Create an installation activity file The installation activity file contains information about the type of activity you want to perform with the extension loader program, such as importing or exporting class definitions. Based on the activity description provided in the activity file, the extension loader performs a specified task. An installation activity file uses the following naming convention: --. where:
is a three-digit number from 000 to 999. The install-order instructs the extension loader to install the objects in the Extensions directory in ascending order. Therefore, you must specify a lower install-order for the object that you want to install first. For example, if you have two extension subdirectories, 650-EXClass and 655EXClass, the 650-EXClass subdirectory will be installed first.
is an alphanumeric name for the extension. Do not use spaces, quotation marks, or wildcard characters in the element.
instructs the extension loader to perform an action based on a specific value. The options for the parameter include:
IMP—Import data into an AR System form ARD—AR System driver script OSD—cmdbdriver script RIK—Remedy Installation Kit is the file extension for the installation activity file. The file extensions for the activity file include:
XML—The file extension for the RIK file must be of type XML. Other types—The file extension for all other activities (IMP, ARD, and OSD) can be of any type such as txt. An example of an activity file name is 500-CLASS-OSD.txt. Every installation activity file you create must contain the oout and cout commands. The oout command instructs the extension loader to log the script actions. You must specify the OSDriver.out output filename with the oout command, as illustrated in the example, to save the script actions. After the script stops executing the activity file, the extension loader reads these log comments to verify whether the script execution was successful. The cout command closes the log entry file.
Chapter 4
BMC Atrium CMDB tools
57
BMC Atrium CMDB 2.1.00
Example: Activity file oout OSDriver.out imp //activity type 1 // Number of class or instance defintions to import TEST // Class name SampleClass // Namespace 1 // metadata or instance data choice. 1 indicates metdata. . cout term q
When the extension loader executes the activity file shown in this example, the class definitions for the Test class will be imported. You can specify multiple cmdbdriver commands in your activity file, for example, your script file can contain both export and import commands.
To create an installation activity file 1 Open an empty file in a UNIX text editor, such as the vi text editor.
You must create the activity file in UNIX format for running it on the UNIX platform.
IMPORTANT If you create the activity file in Windows format, make sure you use the DostoUnix command to convert the file from Windows format to UNIX before you run it. 2 Type oout and OSDriver.out output file name in the beginning of the file as shown
in the previous example. You must specify the oout command and the OSDriver.out output file for the activity script. The extension loader program generates an error if you skip this line in the activity file.
IMPORTANT You must name the output file for the oout command as OSDriver.out. If you specify any other file name, the extension loader program generates an error. 3 Specify the type of activity the extension loader must perform, such as ARD or OSD. 4 Specify the number of class definitions or instance data objects you want to export
or import. 5 Specify the class name and namespace for the OSD activity.
58
Developer’s Reference Guide
Using the extension loader
6 Specify if you want to export or import the metadata or instance data.
You can use the cmdbdriver program for the import and export function parameters. For more information about the cmdbdriver program, see “Working with the cmdbdriver program” on page 42. 7 Save the activity file under the extension subdirectory you created in step 1 with
an xml, txt, or any other type of extension, depending on the activity type. For more information about the activity file extensions, see “Step 3—Create an installation activity file” on page 57. The Extensions subdirectories will now contain a package.xml file, an installation activity file, and the XML files, which were created when you exported your classes using the cmdbdriver program.
Step 4—Start the cmdbExtLoader program After your extension subdirectory package is ready with all the required files, you can the start the extension loader program.
To start the cmdbExtLoader program 1 Depending on your environment, perform any of the following steps to start the
extension loader:
On Windows Double-click cmdbExtLoader.exe from the directory in which you copied the extension loader program.
On UNIX Using the command prompt, navigate to the directory in which you copied the extension loader program.
Type ./cmdbExtLoader to run the extension loader program.
NOTE To install the extension loader on a UNIX machine, follow the prompts. For information about the parameters you need to provide, see step 4 on page 60. The Welcome screen of the extension loader installation wizard appears. 2 Click Next.
The Software License Agreement screen appears. 3 Click I Agree.
The AR Server Connection Information screen appears, as displayed in Figure 4-3 on page 60.
Chapter 4
BMC Atrium CMDB tools
59
BMC Atrium CMDB 2.1.00
Figure 4-3: AR Server Connection Information screen
4 Specify the following details:
AR Server Name—Type the AR System server on which you want to install the extensions.
Port Number—If you specified a port number when installing the AR System server, type that number in this field. If the server uses a portmapper to automatically select a port to use, leave this field blank.
RPC Port Number—If you specified an RPC port number when installing the AR System server, type that number in this field. 5 Click Next.
The Administrator Logon Information Required screen appears. 6 Specify an Administrator user name and password in the User Name and
Password fields respectively. The extension loader program begins installing the extensions. Depending on whether the installation was successful, one of the following installation status is displayed in the Package Load Summary screen:
SUCCESS—The extensions are successfully installed on the server. DEPENDENCY FAILURE—The dependency details that you specified in the package.xml file such as, guid and minversion is incorrect. For specific details about the failure, see the cmdbext_install.log, which is located in the %temp% directory of your machine.
60
Developer’s Reference Guide
Using the extension loader
NOTE %temp% is an environment variable that is already set when you install the operating
system. To access this folder, open Windows Explorer and type %temp% in the Address list.
SKIPPED—The extensions that you are attempting to install on the specified server is already installed.
NOTHING TO LOAD—The extensions folder did not contain any extensions to be installed. When you use only the package.xml file, excluding the extensions, to add an entry in the SHARE:Application_Properties form, this message is displayed. You could use this option when one of the components of your application did not change, but you want to update its version number to match the version of the changed components.
FAILURE—The extensions installation failed because of an error in any of the activity files. For more information about the activity files, see the section, “Step 3—Create an installation activity file” on page 57. Figure 4-4: Installation status—Package Load Summary screen
Chapter 4
BMC Atrium CMDB tools
61
BMC Atrium CMDB 2.1.00
7 Click Next.
The Setup Complete screen is displayed. 8 Click Finish.
To view the installation log files, open Windows Explorer and type %temp% in the Address list. The log file is named as cmdbext_install.log.
Verifying your installed extensions If your extensions are successfully installed on the server, you can view an entry for the application that added the extensions in the SHARE:Application_Properties form, as displayed in Figure 4-5. Figure 4-5: SHARE:Application_properties form—Installed extensions
To verify whether your extensions installed successfully 1 Log on to the AR System server on which you installed the extensions using BMC
Remedy User. For more information about how to log on to the BMC Remedy User, see the User’s Guide. 2 Press CTRL+O on your keyboard to display the Object List window. 3 In the Search what keywords? field, type share.
62
Developer’s Reference Guide
Integrating the CI Relationship Viewer with other applications
4 From the list below, double-click the entry for SHARE:Application_Properties.
The SHARE:Application_Properties is displayed in Search mode. 5 In the Property Name field, type name and click Search.
A list of entries for various applications that are installed on the server is displayed in the result section of the SHARE:Application_Properties form. 6 Click the entry that pertains to the application for which you installed the
extensions. 7 Verify the details of the extension such as Name and Version.
Integrating the CI Relationship Viewer with other applications The CI Relationship Viewer graphically displays the relationships between existing CIs. Although the CI Relationship Viewer is a part of the CMDB Console, the CI Relationship Viewer can also be integrated with other AR System applications. For information about using the CI Relationship Viewer to view instance relationships from the CMDB Console, see the User’s Guide. You can integrate the CI Relationship Viewer with other applications using the following methods:
AR System applications Launch the CI Relationship Viewer form from AR System applications. This is a quick and easy way to integrate the CI Relationship Viewer with your AR System application. In this method, you can launch the CI Relationship Viewer form, which is installed within the CMDB, using AR System workflow (see page 64).
Embed CI Relationship Viewer in AR System applications. In this method, the CI Relationship Viewer field is embedded in the AR System application itself (see page 66).
Non-AR System applications Launching the CI Relationship Viewer from non-AR System applications. In this method, you can launch the CI Relationship Viewer directly using a browser. (see page 67).
TIP To view version details for the CI Relationship Viewer, type java –jar civiewer.jar at the command line prompt. For information about version details, see the Troubleshooting Guide.
Chapter 4
BMC Atrium CMDB tools
63
BMC Atrium CMDB 2.1.00
Launching the CI Relationship Viewer from AR System applications When you launch the CI Relationship Viewer form from other AR System applications, the BMC Atrium CMDB performs the initialization function for the CI Relationship Viewer. You must specify the initialization parameters, such as Namespace, Class Name, Dataset ID, CI ID, and Filters of the CI for which the relationship data will be displayed. Table 4-2 lists the parameters required to launch the CI Relationship Viewer form from other AR System applications. Table 4-2: CI Relationship Viewer parameters—AR System applications
64
Parameter name
Description
Namespace
The namespace to which the instance belongs.
Class Name
The class name to which the instance belongs.
CI ID
The Instance ID of the CI for which the relationship data will be displayed.
Dataset ID
The ID of the dataset where the instance resides.
Filter Name
The filter name for the CI Relationship Viewer. These filters enable you to specify qualifications for the instances you want to view. The BMC Atrium CMDB application ships with one or more default filters. You can also create additional filters to suit your needs.
Developer’s Reference Guide
Integrating the CI Relationship Viewer with other applications
To launch the CI Relationship Viewer from AR System applications 1 With BMC® Remedy® Administrator, log in to the BMC Atrium CMDB server and
create a new active link for launching the CI Relationship Viewer. The properties for the active link are displayed in a tab form. For more information about creating active links, see the BMC Software Remedy Action Request System 7.1.00: Workflow Objects guide. 2 On the Basic tab, specify details, such as the Form Name and Execute On criteria. Figure 4-6: Setting CI Relationship Viewer parameters
3 On the If Action tab, specify the following details:
From the New Action list, select Open Window. From the Window Type list, select Search. From the Target Location list, select New.
NOTE Launching the CI Relationship Viewer from AR Systems does not support the Current option for the Target Location list.
Chapter 4
BMC Atrium CMDB tools
65
BMC Atrium CMDB 2.1.00
From the Form Name list, select CMDB:CIViewer. In the Field Mapping section, specify the parameters listed in Table 4-2 on page 64. 4 Click Add Action. 5 On the Permissions tab, specify permissions for the active link. 6 On the BMC Remedy Administrator toolbar, click the Save icon.
Your active link is now saved.
Embedding the CI Relationship Viewer in AR System applications Use the following procedure to embed the CI Relationship Viewer in your AR System form.
To embed the CI Relationship Viewer in your AR System form 1 Using BMC Remedy Administrator, open the form in which you want to embed
the CI Relationship Viewer. 2 Place a Data Visualization field on the form and double-click it to open the Field
Properties tab. 3 On the Advanced tab, set the following Data Visualization field properties:
From the Module type list, select CI Viewer.
NOTE The CI Viewer value in the Module type list does not appear if you have not installed the BMC Atrium CMDB application on your system.
From the Definition Name list, select the data visualization definition you created for the CI Viewer. Select Default if you did not create any customized definitions. For more information about creating definitions, see “Creating a definition for the CI Relationship Viewer” on page 73. 4 On the Database tab, specify a name for the Data Visualization field in the Name
text box. 5 Create an active link that will be executed when the Data Visualization field is
initialized and specify the following details for the active link:
On the Basic tab: Specify a name for the active link. From the Form Name list, select the form name.
66
Developer’s Reference Guide
Integrating the CI Relationship Viewer with other applications
On the If Action tab: From the New Action list, select Set Fields. From the Read Value for Field From list, select the form name on which the data visualization field is placed.
From the Name list, select the name of the Data Visualization field you created.
In the Value field, set the required parameters for launching the CI Relationship Viewer, for example: (((((((( "namespace=" + $Namespace$) + ",classname=") + $Class Name$) + ",datasetid=") + $Dataset ID$) + ",instanceid=") + $CI ID$) + ",filtername=") + “Components and Dependencies”
In the example, the field names, such as $Namespace$ and $Class Name$ are based on the field names of a form. You need to provide these field names as you have specified in your form. You might also specify string values as shown in the example.
IMPORTANT The namespace, classname, datasetid, instanceid, and filtername parameters are CI Relationship Viewer-defined keywords. 6 Click Add Action to save the settings for the action. 7 Click Save to save the active link.
Launching the CI Relationship Viewer from non-AR System applications You can launch the CI Relationship Viewer directly from any non-AR System applications using a browser. To launch the CI Relationship Viewer from a nonAR System application, you must specify the initialization parameters for the viewer in the URL format. In the URL for launching the CI Relationship Viewer, constants, such as F490001100, indicate the field ID on the CI Relationship Viewer form. These IDs are fixed values for the initialization parameters. Table 4-3 lists the parameters and field ID mappings that are required to launch the CI Relationship Viewer form. Table 4-3: CI Relationship Viewer parameters—non-AR System applications Field ID
Parameter name
Description
F49000110f0
Namespace
The namespace to which the instance belongs.
F400109900
Class Name
The class name to which the instance belongs.
F431400000
CI ID
The Instance ID of the CI for which the relationship data will be displayed.
Chapter 4
BMC Atrium CMDB tools
67
BMC Atrium CMDB 2.1.00
Field ID
Parameter name
Description
F431400001
Dataset ID
The dataset from where the instance data will be selected.
F431400003
Filter Name
The filter name for the CI Relationship Viewer. These filters enable you to specify qualifications for the instances you want to view. The CMDB application ships with one or more default filters. You can also create additional filters to suit your needs.
To launch the CI Relationship Viewer from a browser 1 Open a browser and type the following URL in the address field: http:///arsys/apps//AtriumCMDBConsole/ CMDB:CIViewer?F490001100=&F400109900=&F431400000=&F431400001=&F431400003=
Make sure that you specify appropriate values for placeholders, such as , , , , , , and . 2 Press Enter.
The BMC Remedy Action Request System login screen appears. 3 Type a user name and password in the login screen, and click Log In.
The CI Relationship Viewer window opens, as shown in Figure 4-7.
68
Developer’s Reference Guide
Configuring the CI Relationship Viewer
Figure 4-7: CI Relationship Viewer—From a browser
Configuring the CI Relationship Viewer You can configure the CI Relationship Viewer to restrict the relationships displayed by number of levels, create various events, specify font size and color, and display a context menu that enables you to perform various actions based on the menu selection.
Working with filters The CI Relationship Viewer enables you to define filters for retrieving relationship information to generate a graphical relationship map. These filters are useful when retrieving large amounts of class and relationship data. As you can view relationships up to any number of levels from the root CI, filters provide a way to limit the items that are shown in the graph. You can filter class and relationship data by CI class types, relationship types, status, and view relationships up to any number of levels from the root CI. The BMC Atrium CMDB ships with two default filters—All and Components and Dependencies. You can create custom filters using the Manage Filters link on the CMDB Console. For more information about creating filters, see the Installation and Configuration Guide.
Chapter 4
BMC Atrium CMDB tools
69
BMC Atrium CMDB 2.1.00
Customizing the configuration file The settings that specify the visual and display definitions for the CI Relationship Viewer are encapsulated in a configuration file. Although the CI Relationship Viewer provides a default configuration file (config.xml) that contains standard settings for the viewer, you can create a custom configuration file to suit your needs. After you create a configuration file, you add it as an attachment to the CI Relationship Viewer definition, which is an entry in the Data Visualization Definition form. You customize the CI Relationship Viewer settings using the following steps:
“Creating a configuration file” on page 70 “Creating a definition for the CI Relationship Viewer” on page 73
Creating a configuration file This section explains how to create a custom configuration file, which includes settings, such as the context menu that displays various menu options, launch in context, and color settings for the CI Relationship Viewer. The following example specifies the format for defining a menu item: Example: Menu item definition
Where:
id—Uniquely
textid—The ID that is used in the AR
identifies the menu item. System Message Catalog form to localize
the text.
text—The text string for the menu that will be displayed in the CI Relationship
Viewer. Enter a meaningful name for this attribute.
action—Specifies the action that will be performed when the user selects the menu item. The action attribute can contain JavaScript code or one of the predefined event types, for example, CIRV_NOTIFY_AR.
If the action attribute for any menu item is set to CIRV_NOTIFY_AR, then the ID of the menu item is passed to the container AR System form in the event type parameter. For more information about the CI Relationship Viewer events, see Appendix B, “Using graph queries to find related CIs.”
70
enabled—Used
to enable or disable the menu item. If you do not define this attribute, the default value of true is accepted.
Developer’s Reference Guide
Configuring the CI Relationship Viewer
You can create submenus up to any number of levels. The example that follows, shows a submenu definition. Example: Submenu definition
You can create separators between the menu items to apply a context for them. A separator does not have the text and action attributes. The following example shows a menu separator: Example: Menu separator
The CI Relationship Viewer predefines a set of standard menu items for the applications that use the viewer. Table 4-4 lists the menu or submenu items of the CI Relationship Viewer along with their functions.
NOTE The menu items listed in Table 4-4 are displayed in the context menu by default. To hide any of submenus in the context menu pop-up, modify the config.xml file or create a custom configuration file. Table 4-4: Menu items and their functions Action value
Function
Text displayed in the CI Relationship Viewer
MNU_VIEW
Open the class form for the selected instance
View
MNU_SET_AS_ROOT
Sets the currently selected CI as Set as Root root
SUBMENU_LAUNCH
Submenu for showing the items Launch in Context for Launch in Context
MNU_SEPARATOR
Separator
MNU_GRP_SHOWCI
Displays a window with a list of Select Items to Show CIs
MNU_GRP_SHOWALL
Displays all the CIs for the selected group
MNU_GRP_HIDEALL
Hides all the items for the group Hide all Items
SUBMENU_GRPITEMS
Lists all expanded groups for a selected CI
Group Items
SUBMENU_LAYOUT
Submenu for showing the layouts
Layout
MNU_LAYOUT_TREE
Tree Layout
Tree
MNU_LAYOUT_RADIAL
Radial Layout
Radial
MNU_REFRESH
Refreshes the Relationship Graph
Refresh
A line
Chapter 4
Show all Items
BMC Atrium CMDB tools
71
BMC Atrium CMDB 2.1.00
is a special menu type that is used for adding menu items for launching federated data in context. If a SUBMENU_LAUNCH menu item is included in the configuration file, menu items for all applicable federated interfaces are automatically displayed. SUBMENU_LAUNCH
The default option for the Launch in Context submenu in the CI Relationship Viewer is CI Viewer, which launches the CI Relationship Viewer in a browser. The SUBMENU_LAUNCH submenu will appear disabled in the CI Relationship Viewer if there are no CIs that are selected on the CI Relationship Viewer map.
NOTE Do not add any menu items for the SUBMENU_LAUNCH menu option in the configuration file. Based on the federation definitions, the menu items will be dynamically added to SUBMENU_LAUNCH at run time. The configuration, style, and context menu information must be placed within the , , element tags respectively. Table 4-5 explains the various style attributes for the CI Relationship Viewer context menu. Table 4-5: Context menu style attributes. Style attribute name
Description
fontSize
The font size for the CI labels.
nodeSize
The default icon size for CI representation.
fill
The color for the links. When used in the link element, it represents the default color.
width
The width of the link. When used in the link element, it represents the default width.
text
The text to display in the legend.
The color scheme for the different relationship types should be placed inside the tag. If the color for a specific relationship type is not defined, the default values for the color and width tags will be used, as defined in the parent XML element. Example: config.xml file
When you create a configuration file with the code explained in the config.xml example, the context menu shown in Figure 4-8 on page 73 is displayed in the CI Relationship Viewer. Figure 4-8: CI Relationship Viewer context Menu
Creating a definition for the CI Relationship Viewer This section explains how to attach a configuration file to a CI Relationship Viewer definition. You create a definition for the CI Relationship Viewer to apply the settings you specified in the custom configuration file. This definition is created using the Data Visualization Definition form. After you create a definition for the custom configuration file, you must then change the Definition Name on the Advanced tab of the CI Relationship Viewer field properties to override the default definitions provided with the BMC Atrium CMDB application. For more information about creating a configuration XML file, see “Customizing the configuration file” on page 70.
Chapter 4
BMC Atrium CMDB tools
73
BMC Atrium CMDB 2.1.00
To create a CI Relationship Viewer definition 1 In BMC Remedy User, open the Data Visualization Definition form in Search
mode. 2 Click Search on the form toolbar.
All existing Data Visualization Definition entries are listed in the results pane, as displayed in Figure 4-9 on page 74. Figure 4-9: Data Visualization Definition form
3 In the results pane, select the entry with a Definition Name of Default.
The default definition is displayed. 4 Choose Edit > Copy to New.
The field values are copied to a Data Visualization Definition window in New mode. You can now modify the fields before saving the new definition.
74
Developer’s Reference Guide
Creating CMDB status alerts
5 Specify the following details for the definition:
Definition Name—A unique name for the definition.
NOTE The Module Name for the definition must always be CI Viewer to integrate with the CI Relationship Viewer.
Description—A description for the definition. Complex Definition—Your customized config.xml file. To specify a complex definition file, drag it into the Complex Definition attachment field.
IMPORTANT After you modify a configuration XML file and attach it to the Data Visualization Definition, you must restart the BMC Remedy Mid Tier to view the changes in the CI Relationship Viewer context menu. 6 Click Save.
Creating CI Relationship Viewer events The CI Relationship Viewer can send and receive various types of events from AR System forms. These events include instructions for setting a CI as the root, refreshing the CI Relationship Viewer map, and notifying the AR System. For more information about the CI Relationship Viewer events, see Appendix A, “CI Relationship Viewer events.”
Creating CMDB status alerts You create status alerts for the BMC Atrium CMDB from other integrating applications to display on the CMDB Console.To create status alerts, you add an entry in the CMDB:StatusAlerts form. You can use either the AR System API or workflow to add this entry. You must provides values for the Type, Priority, and Short Description fields.
Type—The type of alert. You can specify any value in this field. However, the best practice is to provide the name of the integrating application that adds an entry in the CMDB:StatusAlerts form for tracking purposes.
Priority—The priority for the alert. You can choose from Low, Medium, or High. Short Description—The description of the alert. You specify the problem or status description in this field. Optionally, you can provide an additional description for the alert in the Description field. Date/Time is an auto-generated field. The fields that appear on the CMDB Console include Short Description, Priority, Type, and Date/Time.
Chapter 4
BMC Atrium CMDB tools
75
BMC Atrium CMDB 2.1.00
Importing data with Integration Engine The BMC Atrium Integration Engine (Integration Engine) application enables you to transfer data between a third-party data source and the BMC Atrium CMDB. With Integration Engine, you perform scheduled bulk data transfers and eventbased integrations. You can use Integration Engine for initial data load, incremental data transfers, and data synchronization. Figure 4-10: Data exchange process
Third-party data source
Data object
AR System database
BMC Atrium Integration Engine
CMDB class
When you transfer data into the BMC Atrium CMDB, a database table and its columns from the third-party data source are mapped to a BMC Atrium CMDB class and its attributes respectively. In general, this relationship is many-to-many because you can map different columns from different data sources to different attributes in the same BMC Atrium CMDB class. For more information about EIE data transfer between a third-party data source and the BMC Atrium CMDB, see the BMC Atrium Integration Engine 7.1.00 Administrator’s Guide.
76
Developer’s Reference Guide
Working with SQL views
Working with SQL views SQL views are available to facilitate data access to the BMC Atrium CMDB from third-party database clients. These views provide direct access to the database tables for the various BMC Atrium CMDB classes, without having to know the hierarchy of a given class. For each database table in the AR System (except for the attachment tables), a corresponding SQL view is automatically created. These views, which have the same name as their underlying forms, are created using the following naming rules:
Alphabetic and numeric characters remain as defined. Colons and other special characters are replaced by underscores. For example, the SQL view for the BMC.CORE:BMC_BaseElement form is named BMC.CORE_BMC_BaseElement.
A leading A is appended to all view names that do not begin with an alphanumeric character.
If the name contains a database reserved word, the string _x is appended to the name.
View names are limited to 30 characters. When a form name exceeds the 30 character limit, the corresponding view name is truncated to 27 or 28 characters. A schema ID is appended to the view name to differentiate between any other view that was truncated to the same string. Because schema IDs vary from one system to another, these view names cannot be formulated in advance. For example, the view of the BMC.CORE.CONFIG:BMC_ConfigBaseRelationship form might be named BMC_CORE_CONFIG_BMC_ConfigB131 or BMC_CORE_CONFIG_BMC_Config2131e
Abstract classes do not store any data. Therefore, abstract classes do not have corresponding views. For more information about SQL views and table naming conventions, see the BMC Remedy Action Request System 7.1.00: Database Reference guide.
Chapter 4
BMC Atrium CMDB tools
77
BMC Atrium CMDB 2.1.00
Debugging BMC Atrium CMDB API programs using print.c routines One of the components of the cmdbdriver program is the set of print routines located in the print.c file. These routines enable you to print the contents of any data structure in the API. The routines provide code examples for accessing the various structures. Printing the contents of a structure before and after an API call is useful for debugging.
NOTE See the function definitions in print.c to determine the specific parameters and their types for these routines. The print.h file contains a complete list of these routines.
78
Developer’s Reference Guide
Section
II
API reference
This section provides reference information for the C and web services APIs. The Java API documentation is available in the Javadoc HTML files. This section is organized into the following chapters:
Chapter 5, “C API functions and data structures,” provides information about the functions and the data structures used in the C APIs. Chapter 6, “Web services API operations and data structures,” provides information about the operations and data structures used in the Web services APIs.
Section II
API reference
79
BMC Atrium CMDB 2.1.00
80
Developer’s Reference Guide
Chapter
5
C API functions and data structures This section describes the C API functions. The following topics are provided:
Related files (page 82) Functions (page 82) Data structures (page 158)
Chapter 5
C API functions and data structures
81
BMC Atrium CMDB 2.1.00
Related files The cmdb.h and cmdbfree.h files contain the C API function definitions. For a complete list of header files required for the BMC Atrium CMDB, see Chapter 2, “Header files.”
Functions The CMDB C API functions are categorized by the type of actions these functions perform. The function categories include data model, instance, and general purpose functions, such as session, authentication, and import or export definition functions.
NOTE In the C API function descriptions, the usage of the term specified for a given parameter denotes that the parameter is listed under the Synopsis heading of the API function.
Data model functions The data model functions manipulate the attribute and class. The C API functions for data model include:
CMDBCreateAttribute (page 83) CMDBCreateMultipleAttribute (page 86) CMDBDeleteAttribute (page 88) CMDBGetAttribute (page 89) CMDBGetMultipleAttribute (page 92) CMDBSetAttribute (page 95) CMDBSetMultipleAttribute (page 97) CMDBCreateClass (page 99) CMDBDeleteClass (page 101) CMDBGetClass (page 102) CMDBGetListClass (page 104) CMDBSetClass (page 105)
82
Developer’s Reference Guide
Functions
CMDBCreateAttribute Description Privileges Synopsis
Creates a new attribute with the specified name for the specified class. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateAttribute(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
classNameID,
ARNameType
attributeName,
ARNameType
attributeId,
unsigned int
dataType,
ARInternalId
*arsubclassesId,
unsigned int
entryMode,
CMDBAttributeLimit
*attributeLimit,
ARValueStruct
*defaultValue,
ARPropList
*characList,
ARPropList
*customCharacList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameID The name of the class for which you want to create an attribute. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.
attributeName The name of the attribute to create. The name of the attribute must be unique within the specified class and within its superclasses and subclasses.
attributeID The ID of the attribute to create.
dataType The datatype of the attribute to create. 1: Keyword (CMDB_ATTR_DATA_TYPE_KEYWORD) 2:
Integer (CMDB_ATTR_DATA_TYPE_INTEGER)
3:
Real (CMDB_ATTR_DATA_TYPE_REAL)
Chapter 5
C API functions and data structures
83
BMC Atrium CMDB 2.1.00
4:
Character (CMDB_ATTR_DATA_TYPE_CHAR)
5:
Diary (CMDB_ATTR_DATA_TYPE_DIARY)
6:
Selection (CMDB_ATTR_DATA_TYPE_ENUM)
7:
Time (CMDB_ATTR_DATA_TYPE_TIME)
10: Fixed-point decimal (CMDB_ATTR_DATA_TYPE_DECIMAL) 11: Attachment (CMDB_ATTR_DATA_TYPE_ATTACH) 12: Currency (CMDB_ATTR_DATA_TYPE_CURRENCY) 13: Date (CMDB_ATTR_DATA_TYPE_DATE) 14: Time 37:
of day (CMDB_ATTR_DATA_TYPE_TIME_OF_DAY)
Attachment pool (CMDB_ATTR_DATA_TYPE_ATTACH_POOL)
arsubclassesId The AR System subclasses ID of the attribute to create. The IDs of all attributes must be unique within the class. Specify 0 for this parameter if you want the system to generate the ID.
entryMode The entry mode for the attribute. Entry mode can be set to any one of the following: required, optional, or display only. 1: Users must enter data when the (CMDB_ATTR_ENTRYMODE_REQUIRED).
entry mode is set to required
2: Users do not have to enter data when the entry mode is set to optional but they can if they want to (CMDB_ATTR_ENTRYMODE_OPTIONAL). 4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).
attributeLimit The value limits for the attribute and other properties specific to the attribute’s type. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute you are creating. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the attribute limits and properties.
defaultValue The value to apply if a user submits an entry with no attribute value. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute. Specify NULL if you do not want to specify a default value.
characList A list of characteristics for the attribute. It includes the following characteristics: View Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description.
84
Developer’s Reference Guide
Functions
Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). When querying for attributes, you will see all attributes including the hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;-5.
1:
Users can specify a list of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).
2:
3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN). This setting marks the atribute as hidden for a group
or a role. When querying for classes, you can retrieve hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;3. The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is |.
5:
6: CMDB_ATTR_CHARAC_CREATE_MODE 7:Users can set the audit option on CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can
to store the audit history for the attribute.
set the description for the attribute. CMDB_ATTR_CHARAC_DESCRIPTION
customCharacList A list of user-defined custom characteristics for the attribute. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX). After the properties list structure you specify is serialized, it is converted into the format, where: : :
The number of items in the properties list.
The ID for the property, which is within the 300000 - 399999 range.
:
The data type for the property, which can be of any native data type.
: The value
for the property.
An example for the serialized property list is 1\300050\2\1. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5
C API functions and data structures
85
BMC Atrium CMDB 2.1.00
CMDBCreateMultipleAttribute Description Privileges Synopsis
Creates multiple new attributes with the specified names for the specified class. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateMultipleAttribute(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameID,
ARNameList
*attributeNameList,
ARNameList
*attributeIdList,
ARUnsignedIntList
*dataTypeList,
ARInternalIdList
*arsubclassesIdList,
ARUnsignedIntList
*entryModeList,
CMDBAttributeLimitList
*attributeLimitList,
ARValueList
*defaultValueList,
ARPropListList
*characListList,
ARPropListList
*customCharacListList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameID The name of the class for which the attributes need to be created. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.
attributeNameList The list of attribute names. The names of all attributes must be unique within the specified class and within its superclasses and subclasses.
attributeIdList The list of attribute IDs for the attributes being created.
dataTypeList The list of data types for the attributes being created.
arsubclassesIdList The AR System subclasses IDs of the attributes being created.
86
Developer’s Reference Guide
Functions
entryModeList The list of entry modes for the attributes being created. Options include display only, required, and optional. 1: Users must enter data when the (CMDB_ATTR_ENTRYMODE_REQUIRED).
entry mode is set to required
Users do not have to enter data when the entry mode is set to optional but they can if they want to (CMDB_ATTR_ENTRYMODE_OPTIONAL). 2:
4: Users cannot enter data when the entry (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).
mode is set to display only
attributeLimitList The list of value limits for the attributes being created and other properties specific to the attributes’ types. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute list you are modifying. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the limits and properties for the attribute list.
defaultValueList The list of values to apply if a user submits an entry with no value for the attributes being created. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute. Specify NULL if you do not want to specify a default value.
characListList A list of characteristics for each attribute. Characteristics include View Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description. Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).When querying for attributes, you will see all attributes, including the hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;-5. 1:
Users can specify a list of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).
2:
3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN). Marks a list of atributes as hidden
for a group or a role. When querying for classes, you can choose to retrieve hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;3. The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is |.
5:
6: CMDB_ATTR_CHARAC_CREATE_MODE
Chapter 5
C API functions and data structures
87
BMC Atrium CMDB 2.1.00
7:Users can set the audit option on CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can
to store the audit history for the attribute.
set descriptions for the attributes. CMDB_ATTR_CHARAC_DESCRIPTION
customCharacListList A list of user-defined custom characteristics list for each attribute. The value can be set to any user-defined characteristic but must be in the range between 300000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 399999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this attribute. After the properties list structure you specify is serialized, it is converted into the format, where: : :
The number of items in the properties list.
The ID for the property, which is within the 300000 - 399999 range.
:
The data type for the property, which can be of any native data type.
: The value
for the property.
An example for the serialized property list is 1\300050\2\1. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBDeleteAttribute Description
Privileges Synopsis
Deletes the attribute with the specified ID. Depending on the value you specify for the deleteOption parameter, the attribute is deleted immediately and is not returned to users who request information about attributes. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBDeleteAttribute( ARControlStruct
Input arguments
88
*control,
CMDBClassNameId
classNameID,
ARNameType
attributeName,
unsigned int
deleteOption,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
Developer’s Reference Guide
Functions
classNameID The name of the class from which to delete the attribute.
attributeName The name of the attribute to delete.
deleteOption A value indicating the action to take if the specified attribute contains data. 0:
Do not delete the attribute (AR_ATTRIBUTE_CLEAN_DELETE).
1: Delete if the attribute contains (AR_ATTRIBUTE_DATA_DELETE). 2: Delete the attribute even if it (AR_ATTRIBUTE_FORCE_DELETE).
Return values
data but not if it is inherited by subclasses
has subclasses that are associated with it
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetAttribute Description Privileges Synopsis
Retrieves a single attribute. CMDB administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetAttribute( ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
attributeName,
ARNameType
attributeId,
unsigned int
*dataType,
unsigned int
*attributeType,
CMDBClassNameId
*baseClassNameId,
ARInternalId
*arsubclassesId,
unsigned int
*entryMode,
CMDBAttributeLimit
*attributeLimit,
ARValueStruct
*defaultValue,
ARPropList
*characList,
ARPropList
*customCharacList,
ARStatusList
*status)
Chapter 5
C API functions and data structures
89
BMC Atrium CMDB 2.1.00
Input arguments
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The name of the class. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.
attributeName The name of the attribute to retrieve. Return values
attributeId The ID of the attribute.
dataType The datatype of the attribute. 1:
Keyword (CMDB_ATTR_DATA_TYPE_KEYWORD)
2:
Integer (CMDB_ATTR_DATA_TYPE_INTEGER)
3:
Real (CMDB_ATTR_DATA_TYPE_REAL)
4:
Character (CMDB_ATTR_DATA_TYPE_CHAR)
5:
Diary (CMDB_ATTR_DATA_TYPE_DIARY)
6:
Selection (CMDB_ATTR_DATA_TYPE_ENUM)
7:
Time (CMDB_ATTR_DATA_TYPE_TIME)
10: Fixed-point decimal (CMDB_ATTR_DATA_TYPE_DECIMAL) 12: Currency (CMDB_ATTR_DATA_TYPE_CURRENCY) 13: Date (CMDB_ATTR_DATA_TYPE_DATE) 14: Time 37:
of day (CMDB_ATTR_DATA_TYPE_TIME_OF_DAY)
Attachment pool (CMDB_ATTR_DATA_TYPE_ATTACH_POOL)
attributeType The type of attribute to retrieve. 1: CMDB_ATTR_TYPE_CORE_INTERNAL 2: CMDB_ATTR_TYPE_CORE 3: CMDB_ATTR_TYPE_REGULAR
baseClassNameId The name of the class that owns this attribute.
arsubclassesId The internal ID of the attribute to retrieve.
90
Developer’s Reference Guide
Functions
entryMode The entry mode for the attribute list. Entry mode can be set to any one of the following: display only, required, optional. 1: CMDB_ATTR_ENTRYMODE_REQUIRED 2: CMDB_ATTR_ENTRYMODE_OPTIONAL 4: CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY
attributeLimit The value limits for the attribute and other properties specific to the attribute’s type. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute you are creating. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the attribute limits and properties.
defaultValue The value to apply if a user gets an entry with no attribute value. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute.
characList A list of characteristics for each attribute. Characteristics include View Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description. 1: List of groups or roles that have (CMDB_ATTR_CHARAC_VIEW_PERMS).
permissions to view this attribute
2: List of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).
The flag value of the Hidden characteristic. If the flag is set to false, users cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN).
3:
4: Specifies whether the attribute is (CMDB_ATTR_CHARAC_PRIMARY_KEY).
a part of the primary key of the class
The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is |.
5:
6: CMDB_ATTR_CHARAC_CREATE_MODE
The audit option for the attribute. If the audit option is on, the audit history for the attribute is stored. CMDB_ATTR_CHARAC_AUDIT_OPTION 7:
9:
The description of the attribute. CMDB_ATTR_CHARAC_DESCRIPTION
Chapter 5
C API functions and data structures
91
BMC Atrium CMDB 2.1.00
customCharacList A list of user-defined custom characteristics for the attribute. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX).
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetMultipleAttribute Description Privileges Synopsis
Retrieves multiple attributes. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetMultipleAttribute(
Input arguments
92
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARBoolean
getHiddenAttrs,
ARBoolean
getDerivedAttrs,
ARNameList
*nameList,
ARPropList
*attrCharacQueryList,
ARBooleanList
*existList,
ARNameList
*attributeNameList,
ARNameList
*attributeIdList,
ARUnsignedIntList
*dataTypeList,
ARUnsignedIntList
*attributeTypeList,
CMDBClassNameIdList
*baseClassNameIdList,
ARInternalIdList
*arsubclassesIdList,
ARUnsignedIntList
*entryModeList,
CMDBAttributeLimitList
*attributeLimitList,
ARValueList
*defaultValueList,
ARPropListList
*characList,
ARPropListList
*customCharacList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
Developer’s Reference Guide
Functions
classNameId The name of the class to retrieve. It is a two-part structure that contains the namespace and the classname.
getHiddenAttrs A flag indicating whether to retrieve the hidden attributes. Specifying FALSE will not retrieve the hidden attributes.
getDerivedAttrs A flag indicating whether to retrieve attributes derived from a superclass. Specifying FALSE will not retrieve the derived attributes.
nameList A list of attributes to retrieve.
attrCharacQueryList A list of attribute characteristic queries to retrieve. Return values
existList A list of flags and corresponding Boolean values indicating whether the attribute list exists. The value TRUE indicates that the attribute list exists; FALSE indicates that the attribute list does not exist.
attributeNameList The list of attribute names retrieved.
attributeIdList The list of attribute IDs retrieved.
dataTypeList The list of data types for the attribute.
attributeTypeList The list of the attribute’s type.
baseClassNameIdList The name of the base class attribute to retrieve.
arsubclassesIdList The AR System subclasses ID of the attribute.
entryModeList The entry mode for the attribute list. Options include display only, required, and optional. 1: Users must enter data when the entry (CMDB_ATTR_ENTRYMODE_REQUIRED ). 2: Users do not have to enter data (CMDB_ATTR_ENTRYMODE_OPTIONAL).
mode is set to required
when the entry mode is set to optional
Chapter 5
C API functions and data structures
93
BMC Atrium CMDB 2.1.00
4: Users cannot enter data when the entry (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).
mode is set to display only
attributeLimitList The value limits for the list of attributes and other properties specific to the attribute’s type. See “CMDBAttributeLimit” on page 162 to find the contained structure that applies to the type of attribute you are modifying. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the attribute limits and properties.
defaultValueList The value to apply if a user submits an entry with no attribute list value. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute.
characList A list of characteristics for each attribute. Characteristics include View Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description. 1: List of groups or roles that have (CMDB_ATTR_CHARAC_VIEW_PERMS).
permissions to view this attribute
2: List of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).
The flag value of the Hidden characteristic. If the flag is set to false, users cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN).
3:
4: Specifies whether the attributes are (CMDB_ATTR_CHARAC_PRIMARY_KEY).
a part of the primary key of the class
The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is |.
5:
6: CMDB_ATTR_CHARAC_CREATE_MODE 7: The audit option for the attribute. If the audit option is on, the audit history for the attribute is stored. CMDB_ATTR_CHARAC_AUDIT_OPTION 9:
The description of the attribute. CMDB_ATTR_CHARAC_DESCRIPTION
customCharacList A list of user-defined custom characteristics for the attribute. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX).
status A list of zero or more notes, warnings, or errors generated from a call of this function.
94
Developer’s Reference Guide
Functions
CMDBSetAttribute Description Privileges Synopsis
Sets an attribute with the specified name for the specified class. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSetAttribute(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
attributeName,
ARNameType
newAttributeName,
unsigned int
*entryMode,
CMDBAttributeLimit
*attributeLimit,
ARValueStruct
*defaultValue,
ARPropList
*characList,
ARPropList
*customCharacList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The name of the class for which the attribute needs to set. It is a two-part structure that contains the namespace and the classname.
attributeName The name of the attribute to set.
newAttributeName The new name of the attribute, which must be unique within the specified class and within its superclasses and subclasses.
entryMode The entry mode for the attribute. Options include display only, required, and optional. 1: Users must enter data when the (CMDB_ATTR_ENTRYMODE_REQUIRED).
entry mode is set to required
2: Users do not have to enter data when the entry mode is set to optional but they can if they want to (CMDB_ATTR_ENTRYMODE_OPTIONAL). 4: Users cannot enter data when the entry (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).
Chapter 5
mode is set to display only
C API functions and data structures
95
BMC Atrium CMDB 2.1.00
attributeLimit The value limits for the attribute and other properties specific to the attribute’s type. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute you are setting. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the attribute limits and properties.
defaultValue The value to apply if a user sets an entry with no attribute value. The default value can be as many as 255 bytes in length and must be of the same data type as the attribute.
characList A list of characteristics for each attribute. Characteristics include View Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description. 1: Users can view but not modify (CMDB_ATTR_CHARAC_VIEW_PERMS).
the characteristics of the attribute
2: Users can view and modify the characteristics of (CMDB_ATTR_CHARAC_CHANGE_PERMS). 3: Users can set the flag to false (CMDB_ATTR_CHARAC_HIDDEN).
the attribute
so they cannot see hidden attributes
The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is |.
5:
6: CMDB_ATTR_CHARAC_CREATE_MODE 7:Users can set the audit option on CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can
to store the audit history for the attribute.
set the description of the attribute. CMDB_ATTR_CHARAC_DESCRIPTION
customCharacList A list of user-defined custom characteristics for the attribute. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX). In version 2.0 of the BMC Atrium CMDB, the custom characteristic list was overwritten when you specified new values. With version 2.0.1, the new values are appended to the existing list. To delete a custom characteristic, set its datatype to NULL. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
96
Developer’s Reference Guide
Functions
CMDBSetMultipleAttribute Description Privileges Synopsis
Sets multiple attributes with the specified names for the specified class. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSetMultipleAttribute(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameList
*attributeNameList,
ARNameList
*newAttributeNameList,
ARUnsignedIntList
*entryModeList,
CMDBAttributeLimitList
*attributeLimitList,
ARValueList
*defaultValueList,
ARPropListList
*characListList,
ARPropListList
*customCharacListList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The name of the class for which the attributes need to be set. It is a two-part structure that contains the namespace and the classname.
attributeNameList The list of attribute names to set.
newAttributeNameList The list of new names of the attributes. The names of all attributes must be unique within the specified class and within its superclasses and subclasses.
entryModeList The list of entry modes for the attributes being created. Entry mode can be set to any one of the following modes: display only, required, optional. 1: Users must enter data when the entry (CMDB_ATTR_ENTRYMODE_REQUIRED ).
mode is set to required
2: Users do not have to enter data when the entry mode is set to optional but they can if they want to (CMDB_ATTR_ENTRYMODE_OPTIONAL). 4: Users cannot enter data when the entry (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).
Chapter 5
mode is set to display only
C API functions and data structures
97
BMC Atrium CMDB 2.1.00
attributeLimitList The list of value limits for the attributes being created and other properties specific to the attributes' types. See “CMDBAttributeLimit” on page 162 to find the contained structure that applies to the type of attribute list you are modifying. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the limits and properties for the attribute list.
defaultValueList The list of values to apply if a user submits an entry with no value for the attributes being created. The default value can be as many as 255 bytes in length and must be of the same data type as the attribute. Specify NULL if you do not want to specify a default value.
characListList A list of characteristics for each attribute. Characteristics include View Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description. Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).
1:
Users can specify a list of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).
2:
3: Users can set the flag to false (CMDB_ATTR_CHARAC_HIDDEN).
so that this attribute is hidden
The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is |.
5:
6: CMDB_ATTR_CHARAC_CREATE_MODE 7:User can set the audit option on CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can
to store the audit history for the attribute.
set descriptions of the attributes. CMDB_ATTR_CHARAC_DESCRIPTION
customCharacListList A list of user-defined custom characteristics list for the attribute. The value can be set to any user-defined characteristic but must be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this attribute. In version 2.0 of the BMC Atrium CMDB, the custom characteristic list was overwritten when you specified new values. With version 2.0.1, the new values are appended to the existing list. To delete a custom characteristic, set its datatype to NULL.
98
Developer’s Reference Guide
Functions
Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBCreateClass Description
Privileges Synopsis
Creates a class with the core attributes in the OBJSTR:Class. The data model is stored in the OBJSTR:Class form and the attribute information is stored in the OBJSTR:AttributeDefinition form. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateClass(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameID,
ARNameType
classID,
CMDBClassTypeInfo
*classTypeInfo,
CMDBClassNameId
*superclassNameId,
CMDBIndexList
*indexList,
CMDBAuditInfoStruct
*auditInfo,
ARPropList
*characList,
ARPropList
*customCharacList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameID The name of the class to create. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.
classID The unique identifier for the class. It can be provided by the user. If left blank, the class ID will be automatically generated by the system.
classTypeInfo The type of class to create. The information contained in this definition depends on the type of class you specify. 1:
Indicates a regular class (CMDB_CLASS_TYPE_REGULAR).
2:
Indicates a class of type relationship (CMDB_CLASS_TYPE_RELATIONSHIP).
Chapter 5
C API functions and data structures
99
BMC Atrium CMDB 2.1.00
superclassNameID The superclass of this class. Specify NULL for this parameter if there is no superclass.
indexList A list of indexes defined for the class.
auditInfo The audit information for the class.
characList A list of characteristics for the class. Specify NULL for this parameter if you do not want to associate characteristics with this class. 1: Used to specify if this is a singleton class. This characteristic is an integer value where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a singleton class (CMDB_CLASS_CHARAC_SINGLETON). 2: This property does not allow you to create instances for this abstract class (CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the attribute,
you cannot create instances for it. All the attributes are propagated to the subclasses. 3:
You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL).
4:
The author of the class (CMDB_CLASS_CHARAC_AUTHOR).
5:
The class description (CMDB_CLASS_CHARAC_DESCRIPTION).
6: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). Marks the class as hidden for a group
or a role. When querying for classes, you can choose to retrieve hidden classes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;3. 7: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_VISIBLE_PERMS). Marks the class as visible for a group
or a role. When querying for classes, you will see all classes, including the hidden classes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;-5. 8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS 9: CMDB_CLASS_CHARAC_FORM_NAME
customCharacList A list of user-defined custom characteristics for the class. The ID for each list item can be set to any user-defined characteristic but must be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this class. After the properties list structure you specify is serialized, it is converted into the format, where: :
100
Is the number of items in the properties list.
Developer’s Reference Guide
Functions
:
Is the ID for the property, which is within the 100000 - 199999 range.
: Is the data type for the property, which can be of any native data type. : Is
the value for the property.
An example for the serialized property list is 1\100050\2\1. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBDeleteClass Description Privileges Synopsis
Deletes a specified class. Also deletes the associated attributes of the class. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBDeleteClass(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
unsigned int
deleteOption,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameID The name of the class to delete.
deleteOption A value indicating the action to take if the specified class contains attributes or subclasses. 0:
Delete the class only if the class contains no instances and has no subclasses or dependent relationships (CMDB_DELETE_CLASS_OPTION_NONE). Delete the class only if the class has no subclasses or dependent relationships. This applies only to regular classes (CMDB_DELETE_CLASS_OPTION_WITH_DATA).
1:
2: Delete the class, including all the subclasses and dependent relationship classes
that are associated with it. All the dependencies for the specified class are deleted (CMDB_DELETE_CLASS_OPTION_ALL_DEPENDENCIES). This option overrides the CMDB_CLASS_DATA_DELETE option.
Chapter 5 C API functions and data structures
101
BMC Atrium CMDB 2.1.00
Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetClass Description Privileges Synopsis
Retrieves the class information from the OBJSTR:Class form. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetClass(
Input arguments
ARControlStruct
*control,
CMDBClassNameID
*classNameId,
ARNameType
*classId,
CMDBClassTypeInfo
*classTypeInfo,
CMDBClassNameId
*superclassNameId,
CMDBIndexList
*indexList,
CMDBAuditInfoStruct
auditInfo,
ARPropList
*characList,
ARPropList
*customCharacList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameID The name of the class. It is a two-part structure that contains the namespace and the classname. Return values
classId The ID used to identify the class.
classTypeInfo Information about the type of class.
superclassNameId The name of the superclass.
indexList The list of indexes defined for the class.
102
Developer’s Reference Guide
Functions
auditInfo The audit information for the class.
characList A list of characteristics for this class. Specify NULL for this parameter if you do not want to associate characteristics with this class. 1: Used to specify if this is a singleton class. This characteristic is an integer value where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a singleton class (CMDB_CLASS_CHARAC_SINGLETON). 2: This property does not allow you to create instances for this abstract class (CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the attribute,
you cannot create instances for it. All the attributes are propagated to the subclasses. 3:
You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL).
4:
The author of the class (CMDB_CLASS_CHARAC_AUTHOR).
5:
The class description (CMDB_CLASS_CHARAC_DESCRIPTION).
6: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). Marks
the class as hidden for the users in the group. When querying for classes, you can choose to retrieve hidden classes.
7: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_VISIBLE_PERMS). Marks the class
as visible for the users in the group. When querying for classes, you will see all classes including the hidden classes. 8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS 9: CMDB_CLASS_CHARAC_FORM_NAME
customCharacList A list of user-defined custom characteristics for the class. The value retrieved must be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to retrieve custom characteristics with this class.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5 C API functions and data structures
103
BMC Atrium CMDB 2.1.00
CMDBGetListClass Description
Privileges Synopsis
Retrieves information about relationship classes for a specified class. The classes that are retrieved will have the class that is specified in the classNameIdRelation parameter as part of the relationship. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetListClass(
Input arguments
ARControlStruct
*control,
ARNameType
namespaceName,
CMDBClassNameId
*classNameIdRelation,
CMDBClassNameId
*superclassName,
ARPropList
*characQueryList,
ARBoolean
getHiddenClasses,
CMDBClassNameIdList
*classNameIdList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
namespaceName The name of the namespace. Namespaces are a way of partitioning your data model to create logical groups of classes. The Class Manager namespaces are implemented using a prefix-based naming convention on classes.
classNameIdRelation Retrieves the relationship classes that have a class specified in this parameter as part of the relationship.
superclassName Retrieves the classes that are derived from the superclass.
characQueryList Retrieves all the classes that match the criteria.
getHiddenClasses Retrieves the hidden classes.
104
Developer’s Reference Guide
Functions
Return values
classNameIdList A list of class names that match the specified criteria.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBSetClass Description
Privileges Synopsis
Sets the class properties in the OBJSTR:Class form. After you create a class, you cannot modify the following properties: classId, classType (regular, relationship), and persistence provider. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSetClass(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
CMDBClassNameId
*newclassNameId,
CMDBClassTypeInfo
*classTypeInfo,
CMDBIndexList
*indexList,
CMDBAuditInfoStruct
*auditInfo,
ARPropList
*characList,
ARPropList
*customCharacList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The name of the class. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.
newclassNameId The new name of the class.
classTypeInfo Information about the type of class.
Chapter 5 C API functions and data structures
105
BMC Atrium CMDB 2.1.00
indexList The list of indexes defined for the class. When this parameter is specified, all previously existing indexes are replaced by its contents. If you want to add indexes without losing existing indexes, include the existing indexes in this list.
auditInfo The audit information for the class.
characList A list of characteristics for this class. Specify NULL for this parameter if you do not want to associate characteristics with this class. Used to specify if this is a singleton class. This characteristic is an integer value, where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a singleton class (CMDB_CLASS_CHARAC_SINGLETON).
1:
2: This property does not allow you to create instances for this abstract class (CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the class, you
cannot create instances for it. All the attributes are propagated to the subclasses. 3:
You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL).
4:
The author of the class (CMDB_CLASS_CHARAC_AUTHOR).
5:
The class description (CMDB_CLASS_CHARAC_DESCRIPTION).
6: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). Marks
the class as hidden for the users in the group. When querying for classes, you can choose to retrieve hidden classes.
7: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_VISIBLE_PERMS). Marks the class
as visible for the users in the group. When querying for classes, you will see all classes, including the hidden classes. 8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS 9: CMDB_CLASS_CHARAC_FORM_NAME
customCharacList A list of user-defined custom characteristics for the class. The value can be set to any user-defined characteristic but must be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this class. In version 2.0 of the BMC Atrium CMDB, the custom characteristic list was overwritten when you specified new values. With version 2.0.1, the new values are appended to the existing list. To delete a custom characteristic, set its datatype to NULL.
106
Developer’s Reference Guide
Functions
Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Instance functions The C APIfunctions for instance include:
CMDBCreateInstance (page 107) CMDBDeleteInstance (page 108) CMDBGetInstance (page 109) CMDBGetListInstance (page 110) CMDBGetMultipleInstances (page 112) CMDBGraphQuery (page 115) CMDBSetInstance (page 117)
CMDBCreateInstance Description Privileges Synopsis
Creates a CI or relationship instance of the specified class. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateInstance(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
datasetId,
CMDBAttributeValueList
*attributeValueList,
ARNameType
instanceId,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The name of the class from which the instance is derived. It is a two-part structure that contains the namespace and the classname.
Chapter 5 C API functions and data structures
107
BMC Atrium CMDB 2.1.00
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
attributeValueList A list of one or more subclasses/value pairs (specified in any order) that identifies the data for the new attribute. You must specify values for all required subclasses that do not have defined defaults. Values must be of the data type defined for the subclasses or have a data type of 0. NULL values can be specified for optional subclasses only. An error is generated if a subclasses does not exist or the user specified by the control parameter does not have write permission for a subclasses. Return values
instanceId The unique identifier for the new attribute (system-generated).
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBDeleteInstance Description Privileges Synopsis
Deletes the instance of the class. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBDeleteInstance(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
datasetId,
ARNameType
instanceId,
unsigned int
deleteOption,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The name of the class that holds the instance to delete.
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter. 108
Developer’s Reference Guide
Functions
instanceId The unique identifier for the instance (system-generated).
deleteOption Allows you to delete only the specified instance when the instance can be retrieved (CMDB_DERIVED_DELOPTION_NONE).
0:
1: Allows you to delete the instance even when the instance cannot be retrieved (CMDB_DERIVED_DELOPTION_FORCE). Errors will be ignored for instances that do not
exist. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetInstance Description Privileges Synopsis
Retrieves information about the instance. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetInstance(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
datasetId,
usigned int
getMask,
ARNameType
instanceId,
ARNameList
*attributeGetList,
CMDBAttributeValueList
*attributeValueList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The name of the class. It is a two-part structure that contains the namespace and the classname.
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
Chapter 5 C API functions and data structures
109
BMC Atrium CMDB 2.1.00
getMask The identifier for specifying the dataset type. 0: Based on the datasetId being passed, instances are retrieved from either the overlay or the original dataset. 1:
Allows you to retrieve instances from the current dataset only.
instanceId The unique identifier for the instance to retrieve.
attributeGetList The list of attributes to retrieve. Return values
attributeValueList The list of attribute ID and value pairs for the instance.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetListInstance Description Privileges Synopsis
Retrieves a list of instances. You can limit the instance list to entries that match particular conditions by specifying the qualifier parameter. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetListInstance(
110
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
datasetId,
usigned int
getMask,
CMDBQualifierStruct
*qualifier,
ARNameList
*attributeGetList,
CMDBSortList
*sortList,
unsigned int
firstRetrieve,
unsigned int
maxRetrieve,
ARNameList
*instanceIdList,
CMDBAttributeValueListList
*attributeValueListList,
unsigned int
*numMatches,
ARStatusList
*status)
Developer’s Reference Guide
Functions
Input arguments
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The name of the class. It is a two-part structure that contains the namespace and the classname.
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
getMask The identifier for specifying the dataset type. Based on the datasetId being passed, instances are retrieved from either the overlay or the original dataset. 0:
1:
Allows you to retreive instances from the current dataset only.
qualifier A query that determines the set of entries to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations.
attributeGetList A list of attribute names to retrieve.
sortList The sort order for the retrieved data.
firstRetrieve The first entry to retrieve. CMDB_START_WITH_FIRST_ENTRY represents the first entry to retrieve and is the default value if the value is not set.
maxRetrieve The maximum number of entries to retrieve. Use this parameter to limit the amount of data returned if the qualification does not narrow the list. Specify CMDB_NO_MAX_LIST_RETRIEVE to assign no maximum. Return values
instanceIdList The list of instance IDs that match the criteria.
attributeValueListList A list of the attribute value list.
Chapter 5 C API functions and data structures
111
BMC Atrium CMDB 2.1.00
numMatches The total number of entries that match the qualification criteria. This value does not represent the number of entries returned unless the number of matching entries is less than or equal to the maxRetrieve value.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetMultipleInstances Description Privileges Synopsis
Retrieves multiple instances. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetMultipleInstances(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
datasetId,
unsigned int
getMask,
ARNameList
*instanceIds,
ARNameList
*attributeGetList,
ARBooleanList
*existList,
CMDBAttributeValueListList
*attributeValueListList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The name of the class to retrieve. It is a two-part structure that contains the namespace and the classname.
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
getMask The identifier for specifying the dataset type. 0: Based on the datasetId being passed, a list of instances are retrieved from either
the overlay or the original dataset. 112
Developer’s Reference Guide
Functions
1:
Allows you to retreive a list of instances from the current dataset only.
instanceIds A list of instance IDs to retrieve.
attributeGetList A list of attributes to retrieve. Return values
existList A list of flags and corresponding Boolean values indicating whether the attribute list exists. The value TRUE indicates that the attribute list exists; FALSE indicates that the attribute list does not exist.
attributeValueListList The list of attributeID and value pairs for instances to retrieve.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetInstanceBLOB Description Privileges Synopsis
Retrieves the attachment, or binary large object (BLOB), stored for the attachment subclasses. The BLOB can be returned in a file or in an in-memory buffer. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetInstanceBLOB(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
datasetId,
unsigned int
getMask,
ARNameType
instanceId,
ARNameType
attributeName,
ARLocStruct
*loc,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
Chapter 5 C API functions and data structures
113
BMC Atrium CMDB 2.1.00
classNameId The name of the class. It is a two-part structure that contains the namespace and the classname.
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
getMask The identifier for specifying the dataset type. 0: Based on the datasetId being passed, instances are retrieved from either the overlay or the original dataset. 1:
Allows you to retreive instances from the current dataset only.
instanceId The unique identifier for the instance.
attributeName The name of the attribute that contains the attachment. Return values
loc The location where the BLOB is stored.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
114
Developer’s Reference Guide
Functions
CMDBGraphQuery Description Privileges Synopsis
Searches related instances. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGraphQuery(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*startClassNameId,
ARNameType
datasetId,
unsigned int
getMask,
ARNameType
startExtensionId,
ARNameType
startInstanceId,
int
numLevels,
int
direction,
ARBoolean
noMatchProceed,
ARBoolean
onMatchProceed,
CMDBGraphList
*queryGraph,
CMDBGetObjectList
*objects,
CMDBGetRelationList
*relations,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
startClassNameId The name of the starting node class.
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
getMask The identifier for specifying the dataset type. 0: Based on the datasetId being passed, instances are retrieved from either the overlay or the original dataset. 1:
Allows you to retreive instances from the current dataset only.
Chapter 5 C API functions and data structures
115
BMC Atrium CMDB 2.1.00
startExtensionId The extension ID of the starting CI node. This is required if the query graph contains the same class of CI more than once and needs to distinguish one from another.
startInstanceId The ID of the starting node.
numLevels The number of levels to traverse the specified queryGraph. The value A-1 specifies the graph query to traverse to the end of the graph.
direction The direction in which the graph is to traverse. CMDB_RELATIONSHIP_DIRECTION_OUT (0):
Return the node that exists on the right side of the relationship. CMDB_RELATIONSHIP_DIRECTION_IN (1):
Return the node that exists on the left side of the relationship. CMDB_RELATIONSHIP_DIRECTION_BOTH (2):
Return the nodes that exist on both left and right side of the relationship.
noMatchProceed T (1):
When the node returned for a given relationship instance does not match the criteria specified, proceed to the next relationship. Notice that, in this case, no relationship information will be returned because the returned components might not be connected, due to skipping the non-matching nodes. F (0):
When the node returned for a given relationship instance does not match the criteria specified, do not proceed any further.
onMatchProceed T (1):
When the node returned for a given relationship instance matches the criteria specified, proceed to the next relationship. F (0):
When the node returned for a given relationship instance matches the criteria specified, do not proceed any further.
queryGraph The details of the information indicating the path that needs to be queried to return the desired CIs and relationships.
116
Developer’s Reference Guide
Functions
Return values
objects List of one or more CI instances matching the specified criteria. The starting node is not included.
relations List of relationship instances matching the specified criteria that connects the CIs returned.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBSetInstance Description Privileges Synopsis
Sets a CI or relationship instance of the specified class. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSetInstance(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
datasetId,
ARNameType
instanceId,
CMDBAttributeValueList
*attributeValueList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The name of the class. It is a two-part structure that contains the namespace and the classname.
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
instanceId The unique identifier for the instance (system-generated).
Chapter 5 C API functions and data structures
117
BMC Atrium CMDB 2.1.00
attributeValueList A list of one or more attribute value pairs (specified in any order) that identifies the data for the new attribute. You must specify values for all required subclasses that do not have defined defaults. Values must be of the data type defined for the subclasses or have a data type of 0. NULL values can be specified for optional subclasses only. An error is generated if a subclasses does not exist or the user specified by the control parameter does not have write permission for a subclasses. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Bulk entry transaction functions The bulk entry transaction functions invoke the bulk entry API functions. The C API bulk entry transaction functions include:
CMDBBeginBulkEntryTransaction (page 118) CMDBEndBulkEntryTransaction (page 119)
CMDBBeginBulkEntryTransaction Description
Privileges Synopsis
Indicates that subsequent API functions are part of the bulk transaction. Any API calls that arrive after this function call are placed in a queue. Data model functions are not part of the bulk transaction. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBBeginBulkEntryTransaction(
Input argument
Return value
ARControlStruct
*control,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
118
Developer’s Reference Guide
Functions
CMDBEndBulkEntryTransaction Description
Privileges Synopsis
This function commits or rolls back the bulk transaction, depending on the action type. For an action type of SEND, the API call will be executed as part of the transaction. For an action type of CANCEL, the transaction will be canceled. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBEndBulkEntryTransaction( ARControlStruct
Input arguments
*control,
unsigned int
actionType,
ARBulkEntryReturnList
*bulkEntryReturnList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
actionType The type of action. Action type can be SEND or CANCEL. Return values
bulkEntryReturnList Returns the status of the entry calls.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5 C API functions and data structures
119
BMC Atrium CMDB 2.1.00
Environment functions The Class Manager includes the following environment functions:
CMDBInitialization (page 120) CMDBSystemInit (page 121) CMDBSynchMetaData (page 121) CMDBGetServerPort (page 122) CMDBSetServerPort (page 123) CMDBTermination (page 124)
CMDBInitialization Description Privileges Synopsis
Initializes the C API session. This function must be called before any C API calls are made. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBInitialization(
Input arguments
Return values
ARControlStruct
*control,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
120
Developer’s Reference Guide
Functions
CMDBSystemInit Description Privileges Synopsis
Performs server- and network-specific initialization operations for internal use by BMC. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSystemInit(
Return values
ARPropList
*propList,
ARStatusList
*status)
propList A list of properties that need to be initialized.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBSynchMetaData Description Privileges Synopsis
Creates AR System forms from the data model definitions that hold instance data, and workflow, which enforces class hierarchy and data integrity. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSynchMetaData(
Input arguments
ARControlStruct
*control,
ARNameType
pendingId,
CMDBClassNameIdList
*classNameIdList,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
pendingId The ID of the object to be synchronized with the system.
Chapter 5 C API functions and data structures
121
BMC Atrium CMDB 2.1.00
Return values
classNameIDList The list of classes that are successfully synchronized with the system.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetServerPort Description Privileges Synopsis
Retrieves information about the server port. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetServerPort(
Input arguments
Return values
ARControlStruct
*control,
int
*tcpPort,
int
*rpcPort,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
tcpPort Retrieves the CMDB server TCP port information.
rpcPort Retrieves the CMDB server RPC port information.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
122
Developer’s Reference Guide
Functions
CMDBSetServerPort Description Privileges Synopsis
Sets the specified server port. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSetServerPort(
Input arguments
ARControlStruct
*control,
int
*tcpPort,
int
*rpcPort,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
tcpPort The TCP port number that your program will use to communicate with the AR System server. If you do not specify this parameter or provide 0 for the port number, your program will use the port number supplied by the portmapper. This parameter is overridden by the ARTCPPORT environment variable.
rpcPort The RPC port number for the CMDB server. Specify 390697 to use the admin server. The default RPC port number is set to 390696. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5 C API functions and data structures
123
BMC Atrium CMDB 2.1.00
CMDBTermination Description
Privileges Synopsis
Performs environment-specific cleanup routines and disconnects from the specified session. All API programs that interact with the Class Manager session should call this function upon completing work in a given session. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBTermination(
Input arguments
Return values
ARControlStruct
*control,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
124
Developer’s Reference Guide
Functions
User interface component functions The user interface (UI) component functions work with components, such as tool tips, icons, and labelized strings. The Class Manager includes the following user interface (UI) functions:
CMDBGetCMDBUIComponents (page 125) CMDBRunQualificationForCI (page 126) CMDBExpandParametersForCI (page 127)
CMDBGetCMDBUIComponents Description Privileges Synopsis
Retrieves a list of various UI components for a specified class. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetCMDBUIComponents( ARControlStruct
Input arguments
*control,
CMDBUIComponentInfo
*inputInfo,
ARNameType
instanceId,
CMDBUIComponentResultList
*outputInfo,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, locale, and server subclasses are required.
inputInfo The qualification for the user interface component. You can specify information such as locale, classId, and tags to get the required UI component data. If there are no qualifications specified, all existing UI components will be returned.
instanceId The unique identifier used to get component information for a specific instance. Return Values
outputInfo The CMDBUIComponents result set for the specified qualifications.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5 C API functions and data structures
125
BMC Atrium CMDB 2.1.00
CMDBRunQualificationForCI Description
Privileges Synopsis
Performs validation on a list of attributes for a specified CI. The CMDBRunQualificationForCI function takes qualification parameters in both structured and encoded modes. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBRunQualificationForCI( ARControlStruct
Input arguments
*control,
CMDBQualifierStruct
*qualifier,
CMDBAttributeValueList
*attValueList,
ARBoolean*
passed,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, locale, and server subclasses are required.
qualifier A query that determines the set of CIs to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations.
attValueList The list of attributes to validate. Return Values
passed A Boolean value that specifies whether the qualification passed.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
126
Developer’s Reference Guide
Functions
CMDBExpandParametersForCI Description Privileges Synopsis
Accepts an unexpanded string that contains parameters and substitutes values from the attribute value list provided in the CMDBAttributeValueList structure. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBQualificationForCI( ARControlStruct
Input arguments
*control,
char
*paramString,
CMDBAttributeValueList
*attValueList,
char
**expandedStr,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, locale, and server subclasses are required.
paramString The string that contains the unexpanded parameters.
attValueList The list of attribute values that will be used to expand the parameters. Return Values
expandedStr The string that contains the expanded parameters.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5 C API functions and data structures
127
BMC Atrium CMDB 2.1.00
Import and Export functions The export and import functions enable you to export or import CMDB data. The Class Manager includes the following export and import functions:
CMDBExport (page 128) CMDBExportDef (page 129) CMDBExportData (page 130) CMDBImport (page 131) CMDBImportDef (page 132) CMDBImportData (page 133)
CMDBExport Description Privileges Synopsis
Exports the specified class definitions from the specified server. This function is deprecated in the 2.0 release of the BMC Atrium CMDB. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBExport(
Input arguments
ARControlStruct
*control,
CMDBExportItemList
*exportItemList,
unsigned int
exportFormat,
char
*directoryPath,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
exportItemList The list of items to export.
exportFormat The format of the export. The default export format is set to CMDB_EXPORT_FORMAT_XML.
directoryPath The directory in which the exported file is to be stored.
128
Developer’s Reference Guide
Functions
Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBExportDef Description Privileges Synopsis
Exports a list of specified class definitions. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBExportDef(
Input arguments
ARControlStruct
*control,
CMDBExportItemList
*exportItemList,
char
*exportBuf,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
exportItemList A list of zero or more classes or attributes to export. Return values
exportBuf The exported buffer which contains the class definitions in XML format.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5 C API functions and data structures
129
BMC Atrium CMDB 2.1.00
CMDBExportData Description Privileges Synopsis
Exports the specified class data for a specific qualification. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBExportData( ARControlStruct
Input arguments
*control,
ARQualifierStruct
*qualifier,
ARNameList
*attributeGetList,
CMDBSortList
*sortList,
unsigned int
firstRetrieve,
unsigned int
maxRetrieve,
char
*exportBuf,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
qualifier A query that determines the set of classes or attributes to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations.
attributeGetList The list of attributes names to retrieve.
sortList A list of zero or more fields that identifies the sort order for the exported data. Specify a NULL value for this parameter to use no specific sort order.
firstRetrieve The first instance to retrieve. A value of 0 (CMDB_START_WITH_FIRST_INSTANCE)represents the first entry and is the default value if no value is set.
maxRetrieve The maximum number of instances to retrieve. Use this parameter to limit the instances returned in the query if the qualification does not sufficiently narrow the list. Specify 0 (CMDB_NO_MAX_LIST_RETRIEVE) to assign no maximum instances.
130
Developer’s Reference Guide
Functions
Return values
exportBuf The exported buffer, which contains the class data in an XML format.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBImport Description
Privileges Synopsis
Imports the specified class definitions to the specified server. Use this function to copy structure definitions from one server to another. This function is deprecated in the 2.0 release of the BMC Atrium CMDB. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBImport(
Input arguments
ARControlStruct
*control,
CMDBImportItemList
*importItemList,
char
*directoryPath,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
importItemList A list of zero or more items to import.
directoryPath The directory where the contents of the exported file are available for importing. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5 C API functions and data structures
131
BMC Atrium CMDB 2.1.00
CMDBImportDef Description Privileges Synopsis
Imports a list of specified class definitions. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBImportDef(
Input arguments
ARControlStruct
*control,
CMDBXMLImportItemList
*importItemList,
unsigned int
importOption,
char
*importBuf,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
importItemList A list of zero or more items to import. Specify NULL for this parameter to import all definitions in the import buffer.
importOption A value indicating whether to replace class definitions being imported if they already exist. If an import item already exists, the function generates an error. 1:
Generate an error if an item to import already exists
CMDB_DEF_IMPORT_OPT_CREATE. 2:
Overwrite if an item to import already exists
CMDB_DEF_IMPORT_OPT_OVERWRITE.
importBuf The import buffer that contains the class definitions to import in XML format. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
132
Developer’s Reference Guide
Functions
CMDBImportData Description Privileges Synopsis
Imports the specified instance data. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBImportData( ARControlStruct
Input arguments
*control,
unsigned int
importOption,
char
*importBuf,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
importOption A value indicating the options available for handling duplicates found during the importing of instance data. These options are mutually exclusive. 1:
Generate an error
(CMDB_DATA_IMPORT_OPT_ERROR_FOR_DUP). 2:
Create an instance with a new instance ID if the instance ID already exists
(CMDB_DATA_IMPORT_OPT_NEWID_FOR_DUP).
3: Update the existing instance if the instance ID specified already exists (CMDB_DATA_IMPORT_OPT_MERGE_FOR_DUP).
4: Create a new instance ID for all the imported instances, including those instances that are not duplicates. (CMDB_DATA_IMPORT_OPT_NEWID_FOR_ALL).
importBuf The import buffer, which contains the class data to import in XML format. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5 C API functions and data structures
133
BMC Atrium CMDB 2.1.00
Utility functions The utility functions enable you to use CMDB utilities such as export, import, and generate globally unique identifiers (GUIDs). The Class Manager includes the following utility functions:
CMDBCreateGuid (page 134) CMDBGetVersions (page 134)
CMDBCreateGuid Description Privileges Synopsis
Creates a globally unique identifier. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateGuid(
Return values
ARGuid
guid,
ARStatusList
*status)
guid The unique identifier (system-generated).
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetVersions Description Privileges Synopsis
Retrieves the version information for any BMC Atrium CMDB component that is installed. CMDB Administrator #include "ar.h" #include "arextern.h" int CMDBGetVersions(
134
ARControlStruct
*control,
ARNameList
*appIdList
ARBooleanList
*existList
CMDBVersionInfoList
*versionInfoList
ARStatusList
*status)
Developer’s Reference Guide
Functions
Input arguments
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
appIdList A list of application IDs for which the version information is required. Specify a NULL value in this argument to get version information of all the existing applications. Return values
existList A list of TRUE or FALSE values. Each value in this list denotes whether the corresponding application IDs in the supplied appIdList exists.
versionInfoList A list of BMC Atrium CMDB version structures.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5 C API functions and data structures
135
BMC Atrium CMDB 2.1.00
Free functions The free functions release the memory allocated to a specified function. The Class Manager includes the following free functions:
FreeCMDBVersionInfoList (page 137) FreeCMDBClassNameIdList (page 137) FreeCMDBAttributeLimit (page 138) FreeCMDBAttributeLimitList (page 139) FreeCMDBAttributeLimitStruct (page 138) FreeCMDBIndexList (page 139) FreeCMDBExportItemStruct (page 140) FreeCMDBExportItemList (page 140) FreeCMDBImportItemList (page 141) FreeCMDBAttributeGetStruct (page 141) FreeCMDBGraphAdjacentStruct (page 142) FreeCMDBGraphAdjacentList (page 142) FreeCMDBGraphStruct (page 143) FreeCMDBGraphList (page 143) FreeCMDBClassTypeInfo (page 144) FreeCMDBQualifierStruct (page 144) FreeCMDBGetRelationList (page 145) FreeCMDBGetObjectList (page 145) FreeCMDBAttributeValueList (page 146) FreeCMDBAttributeValueListList (page 146) FreeCMDBSortList (page 147) FreeCMDBREJobRunInfoList (page 147)
136
Developer’s Reference Guide
Functions
FreeCMDBVersionInfoList Description Privileges Synopsis
Releases the memory space allocated to the CMDBVersionInfoList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBVersionInfoList(
Input arguments
CMDBVersionInfoList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBVersionInfoList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBClassNameIdList Description Privileges Synopsis
Releases the memory space allocated to the CMDBClassNameIdList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBClassNameIdList(
Input arguments
CMDBClassNameIdList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBClassNameIdList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
Chapter 5 C API functions and data structures
137
BMC Atrium CMDB 2.1.00
FreeCMDBAttributeLimit Description Privileges Synopsis
Releases the memory space allocated to the CMDBAttributeLimit structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBAttributeLimit(
Input arguments
CMDBAttributeLimit
*value,
ARBoolean
freestruct)
value A pointer to the CMDBAttributeLimit structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBAttributeLimitStruct Description Privileges Synopsis
Releases the memory space allocated to the CMDBAttributeLimitStruct structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBAttributeLimitStruct(
Input arguments
CMDBAttributeLimit
*value,
ARBoolean
freestruct)
value A pointer to the CMDBAttributeLimitStruct structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
138
Developer’s Reference Guide
Functions
FreeCMDBAttributeLimitList Description Privileges Synopsis
Releases the memory space allocated to the CMDBAttributeLimitList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBAttributeLimitList(
Input arguments
CMDBAttributeLimitList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBAttributeLimitList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBIndexList Description Privileges Synopsis
Releases the memory space allocated to the CMDBIndexList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBIndexList(
Input arguments
CMDBIndexList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBIndexList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
Chapter 5 C API functions and data structures
139
BMC Atrium CMDB 2.1.00
FreeCMDBExportItemStruct Description Privileges Synopsis
Releases the memory space allocated to the CMDBExportItemStruct structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBExportItemStruct(
Input arguments
CMDBExportItemStruct
*value,
ARBoolean
freestruct)
value A pointer to the CMDBExportItemStruct structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBExportItemList Description Privileges Synopsis
Releases the memory space allocated to the CMDBExportItemList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBExportItemList(
Input arguments
CMDBExportItemList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBExportItemList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
140
Developer’s Reference Guide
Functions
FreeCMDBImportItemList Description Privileges Synopsis
Releases the memory space allocated to the CMDBImportItemList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBImportItemList(
Input arguments
CMDBImportItemList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBImportItemList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBAttributeGetStruct Description Privileges Synopsis
Releases the memory space allocated to the CMDBAttributeGetStruct structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBAttributeGetStruct(
Input arguments
CMDBAttributeGetStruct
*value,
ARBoolean
freestruct)
value A pointer to the CMDBAttributeGetStruct structure that you want to free. The system does not perform an operation if the structure is a list with zero items or if you specify NULL for this parameter.
freeStruct A flag indicating whether you need to free the top-level structure. If you allocated memory for the top-level structure, specify 1 (TRUE) to free both the structure and its contents. If you used a stack variable for the top-level structure, specify 0 (FALSE) to free only the contents of the structure.
Chapter 5 C API functions and data structures
141
BMC Atrium CMDB 2.1.00
FreeCMDBGraphAdjacentStruct Description Privileges Synopsis
Releases the memory space allocated to the CMDBGraphAdjacentStruct structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBGraphAdjacentStruct(
Input arguments
CMDBGraphAdjacentStruct
*value,
ARBoolean
freestruct)
value A pointer to the CMDBGraphAdjacentStruct structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBGraphAdjacentList Description Privileges Synopsis
Releases the memory space allocated to the CMDBGraphAdjacentList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBGraphAdjacentList(
Input arguments
CMDBGraphAdjacentList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBGraphAdjacentList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
142
Developer’s Reference Guide
Functions
FreeCMDBGraphStruct Description Privileges Synopsis
Releases the memory space allocated to the CMDBGraphStruct structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBGraphStruct(
Input arguments
CMDBGraphStruct
*value,
ARBoolean
freestruct)
value A pointer to the CMDBGraphStruct structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBGraphList Description Privileges Synopsis
Releases the memory space allocated to the CMDBGraphList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBGraphList(
Input arguments
CMDBGraphList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBGraphList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
Chapter 5 C API functions and data structures
143
BMC Atrium CMDB 2.1.00
FreeCMDBClassTypeInfo Description Privileges Synopsis
Releases the memory space allocated to the CMDBClassTypeInfo structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBClassTypeInfo(
Input arguments
CMDBClassTypeInfo
*value,
ARBoolean
freestruct)
value A pointer to the CMDBClassTypeInfo structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBQualifierStruct Description Privileges Synopsis
Releases the memory space allocated to the CMDBQualifierStruct structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBQualifierStruct(
Input arguments
CMDBQualifierStruct
*value,
ARBoolean
freestruct)
value A pointer to the CMDBQualifierStruct structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
144
Developer’s Reference Guide
Functions
FreeCMDBGetRelationList Description Privileges Synopsis
Releases the memory space allocated to the CMDBGetRelationList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBGetRelationList(
Input arguments
CMDBGetRelationList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBGetRelationList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBGetObjectList Description Privileges Synopsis
Releases the memory space allocated to the CMDBGetObjectList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBGetObjectList(
Input arguments
CMDBGetObjectList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBGetObjectList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
Chapter 5 C API functions and data structures
145
BMC Atrium CMDB 2.1.00
FreeCMDBAttributeValueList Description Privileges Synopsis
Releases the memory space allocated to the CMDBAttributeValueList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBAttributeValueList(
Input arguments
CMDBAttributeValueList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBAttributeValueList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBAttributeValueListList Description Privileges Synopsis
Releases the memory space allocated to the CMDBAttributeValueListList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBAttributeValueListList(
Input arguments
CMDBAttributeValueListList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBAttributeValueListList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
146
Developer’s Reference Guide
Functions
FreeCMDBSortList Description Privileges Synopsis
Releases the memory space allocated to the CMDBSortList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBSortList(
Input arguments
CMDBSortList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBSortList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
FreeCMDBREJobRunInfoList Description Privileges Synopsis
Releases the memory space allocated to the CMDBREJobRunInfoList structure. CMDB Administrator #include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBREJobRunInfoList(
Input arguments
CMDBREJobRunInfoList
*value,
ARBoolean
freestruct)
value A pointer to the CMDBREJobRunInfoList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
freeStruct A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.
Chapter 5 C API functions and data structures
147
BMC Atrium CMDB 2.1.00
Reconciliation Engine functions The Reconciliation Engine functions manipulate Reconciliation Engine jobs. The C API functions for the Reconciliation Engine include:
CMDBStartJobRun (page 148) CMDBGetJobRun (page 149) CMDBGetListJobRun (page 150) CMDBCancelJobRun (page 151)
CMDBStartJobRun Description
Privileges Synopsis
Starts an existing Reconciliation Engine job. Before starting a job, make sure the job is defined and exists in an Active state. If no job for the specified job name exists, or the job is not Active, the CMDBStartJobRun function returns an error. Only one instance of the same job can be executed at a given time. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBStartJobRun(
Input arguments
ARControlStruct
*control,
ARNameType
jobName,
CMDBClassQualList
*classQualList,
CMDBREDatasetList
*datasetList
ARNameType
jobRunId,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
jobName The name of the reconciliation job.
classQualList The list of class qualifications with which to substitute the Qualification group defined for the job. In the qualification list, specify the class ID and the qualification that applies to it, for example, “BMC_ComputerSystem”, {“1”, “('ReconciliationId' = NULL AND'CreateDate' > ($TIMESTAMP$ - 86400))”}.
148
Developer’s Reference Guide
Functions
datasetList The list of dataset pairs, where the first one represents the substitution dataset (working dataset) and the second represents the dataset defined in the Reconciliation Engine job (defined dataset), for example, “2”, {“BMC.IMPORT.CONFIG”, BMC.SAMPLE”}. Return values
jobRunId A unique job identifier.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetJobRun Description
Privileges Synopsis
Gets information about the currently running reconciliation job and retrieves a job log. For information about interpreting job run logs and job run information, see the section “Viewing job status, results, and history” in the Installation and Configuration Guide. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetJobRun(
Input arguments
ARControlStruct
*control,
ARNameType
jobRunId,
ARREJobRunInfoStruct
*jobRunInfo,
char
**jobRunLog
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
jobRunId A unique job identifier. Return values
jobRunInfo The job run information to retrieve.
jobRunLog The job run log to retrieve.
Chapter 5 C API functions and data structures
149
BMC Atrium CMDB 2.1.00
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetListJobRun Description Privileges Synopsis
Get a list of running Reconciliation Engine jobs. The job list will be retrieved based on the qualification passed to the function. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetListJobRun(
Input arguments
ARControlStruct
*control,
CMDBQualifierStruct
*jobQualifier,
ARREJobRunInfoList
*jobRunInfoList,
unsigned int
*numMatches,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
jobQualifier A query that determines the set of entries to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations. The following qualifiers are currently supported: Run Status*, Run Start Time, Run End Time, Job Instance ID*, Job Run ID, Submitter.
Return values
and
jobRunInfoList The list of running jobs that match the qualification criteria.
numMatches The total number of jobs that match the qualification criteria.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
150
Developer’s Reference Guide
Functions
CMDBCancelJobRun Description Privileges Synopsis
Cancels a currently running Reconciliation Engine job. Depending on the system resources, Reconciliation Engine might cancel a job with a certain delay. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCancelJobRun(
Input arguments
ARControlStruct
*control,
ARNameType
jobRunId,
ARStatusList
*status)
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
jobRunId A unique job identifier. Return values
status A list of zero or more notes, warnings, or errors generated from a call of this function.
Chapter 5 C API functions and data structures
151
BMC Atrium CMDB 2.1.00
Federation functions The federation functions manipulate federated data for an instance. The C API functions for federation include:
CMDBGetRelatedFederatedInContext (page 152) CMDBActivateFederatedInContext (page 153)
CMDBGetRelatedFederatedInContext Description Privileges Synopsis
Returns related FederatedInterface instances for a specific CI (context). CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetRelatedFederatedInContext(
Input arguments
ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
datasetId,
ARNameType
instanceId,
ARNameList
*attributeGetList,
ARNameList
*instanceIdList,
CMDBAttributeValueListList
*attrValueListList,
ARStatusList
*status
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The class name of the specified instance for which federated instances are to be retrieved.
datasetId The dataset ID of the instance to retrieve.
instanceId The instance ID of the specific instance for which federated instances are to be retrieved.
attributeGetList The list of attribute names to retrieve.
152
Developer’s Reference Guide
Functions
Return values
instanceIdList The list of instance GUIDs.
attrValueListList The list of attribute value list.
status A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBActivateFederatedInContext Description
Privileges Synopsis
Expands the FederatedInterface instance for a specific CI and federated interface. Depending on a flag you specify when you call this function, your federated instance might either be only expanded, or expanded and launched. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBActivateFederatedInContext( ARControlStruct
*control,
CMDBClassNameId
*classNameId,
ARNameType
datasetId,
ARNameType
instanceId,
ARNameType
federatedInstanceId,
unsigned int
activateOption,
CMDBFederatedActivateInfo
*federatedInfo,
ARStatusList
*status
control The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId The class name of the specified CI for which the federated instance is to be expanded or launched.
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified.
instanceId The instance ID of the specified instance for which the federated instance is to be expanded or launched. Chapter 5 C API functions and data structures
153
BMC Atrium CMDB 2.1.00
federatedInstanceId The instance ID of the federated instance that is to be expanded or launched.
activateOption The mask number that indicates if the federated instance is to be launched and expanded. CMDB_FEDERATION_ACTIVATION_NONE 0:
Activate none. CMDB_FEDERATION_ACTIVATION_EXPAND 1
Input arguments
loginInfo The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
classNameId The class name of the specified CI for which the federated instance is to be expanded or launched.
aDatasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
instanceId The instance ID of the specified instance for which the federated instance is to be expanded or launched.
federatedInstanceId The instance ID of the federated instance that is to be expanded or launched.
activateOption The mask number that indicates if the federated instance is to be launched and expanded. ACTIVATION_NONE:
No specific operation to be performed. ACTIVATION_EXPAND:
Only expand the federated interface. ACTIVATION_LAUNCH:
Expand and launch the federated interface. Return values
federatedActivateInfo The expanded federated instance information. This parameter is returned only if you specify a value of 1in the activateOption parameter.
status A list of zero or more notes, warnings, or errors generated from a call to this operation.
220
Developer’s Reference Guide
Operations
GetRelatedFederatedInContext Description Privileges Synopsis
Input arguments
Returns related FederatedInterface instances for a specific CI (context). CMDB Administrator
loginInfo The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
classNameId The class name of the specified instance for which federated instances are to be retrieved.
instanceId The Instance ID of the specific instance for which federated instances are to be retrieved.
attributeNames The list of attribute names to retrieve. Chapter 6 Web services API operations and data structures
221
BMC Atrium CMDB 2.1.00
Return values
instanceIdList The list of instance GUIDs.
status A list of zero or more notes, warnings, or errors generated from a call to this operation.
Audit operations The audit functions manipulate the audit option for the classes and attributes. The web services API for audit includes:
GetCopyAuditData (page 222)
GetCopyAuditData Description
Privileges Synopsis
222
Retrieves a copy of the specified CI instance if the attribute data for the instance is modified. The audit option must be set for the attribute’s characteristic to get the audit data. CMDB Administrator
Developer’s Reference Guide
Operations
Input arguments
loginInfo The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
classNameId The class name (class name and namespace combination) of the specified CI instance for which a copy of the audit data is to be retrieved.
instanceId The instance ID of the specified CI instance for which a copy of the audit data is to be retrieved.
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
query A query that determines the set of CI instances to retrieve. The qualification can include one or more attributes and any combination of conditional, relational, and arithmetic (numeric data types only) operations.
attributes A list of attribute names for which the audit data is to be retrieved. Return values
auditValueListList The list of values for the specified attributes. If the audit option at the CI class-level is disabled then, an error is returned.
status A list of zero or more notes, warnings, or errors generated from a call to this operation.
Chapter 6 Web services API operations and data structures
223
BMC Atrium CMDB 2.1.00
User interface component operations The user interface (UI) component operations work with components, such as tool tips, icons, and labelized strings. The web services API includes the following user interface (UI) operations:
GetUIComponents (page 224)
GetUIComponents Description Privileges Synopsis
Input arguments
Retrieves a list of various UI components for a specified class. CMDB Administrator
loginInfo The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
componentInfo The qualification for the user interface component. You can specify information such as locale, classId, and tags to get the required UI component data. If there are no qualifications specified, all existing UI components will be returned. 224
Developer’s Reference Guide
Operations
datasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
instanceId The unique identifier used to get component information for a specific instance. Return Values
uiComponentResultList The CMDBUIComponents result set for the specified qualifications.
status A list of zero or more notes, warnings, or errors generated from a call to this operation.
Utility operations The utility operations enable you to use CMDB utilities such as get version information of the BMC Atrium CMDB application. The web services API includes the following utility operations:
GetVersions (page 225)
GetVersions Description Privileges Synopsis
Retrieves the version information for any BMC Atrium CMDB component that is installed. CMDB Administrator
Chapter 6 Web services API operations and data structures
225
BMC Atrium CMDB 2.1.00
Input arguments
loginInfo The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
appIdList A list of application IDs for which the version information is required. Specify a NULL value in this argument to get version information of all the existing applications. Return values
versionInfoList A list of BMC Atrium CMDB version structures.
status A list of zero or more notes, warnings, or errors generated from a call to this operation.
226
Developer’s Reference Guide
Data structures
Data structures The web services data structures are used as parameters for web services operations. The data structure categories include Instance, Graph query, Class, and Reconciliation Engine structures.
Instance structures Instance structures are data structures for the instance data. Instance structures include:
LoginInfo (page 227) ClassNameIdList (page 228) ClassNameId (page 228) ArrayOf_String (page 228) SortOrderList (page 229) SortOrder (page 229) InstanceInfoList (page 229) InstanceInfo (page 230) StatusList (page 230) Status (page 231)
LoginInfo The LoginInfo data structure is used to hold the login information for a user.
The LoginInfo structure consists of the following elements: userId
The login ID for the user.
password
The password for the user.
lang
The language to use for the current session of the application.
Chapter 6 Web services API operations and data structures
227
BMC Atrium CMDB 2.1.00
ClassNameIdList The ClassNameIdList data structure is used to hold a list of ClassNameID structures.
The ClassNameIdList structure consists of the following element: ClassNameId
The list of class name IDs.
ClassNameId The ClassNameId data structure is used to hold a class.
The ClassNameId structure consists of the following elements: namespaceName
The namespace name for the class.
className
The name of the class.
ArrayOf_String The ArrayOf_String data structure is used to hold a list of string values.
The ArrayOf_String structure consists of the following element: items
228
Developer’s Reference Guide
The value of the attribute.
Data structures
SortOrderList The SortOrderList data structure is used to hold a list of attributes on which to sort.
The SortOrderList structure consists of the following element: items
A list of SortOder structure items.
SortOrder The SortOrder data structure is used to hold a list of attributes on which to sort along with the sort type.
The SortOrder structure consists of the following elements: attributeName
The name of the attribute to sort.
sortOder
The sort order for the list of attributes. ASCENDING—The
attributes will be sorted in ascending order
of the list. DESCENDING—The attributes will be sorted in descending order of the list.
InstanceInfoList The InstanceInfoList data structure is used to hold a list of InstanceInfo structures.
The InstanceInfoList structure consists of the following element: items
A list of InstanceInfo structure items.
Chapter 6 Web services API operations and data structures
229
BMC Atrium CMDB 2.1.00
InstanceInfo The InstanceInfo data structure is used to hold instance values.
The InstanceInfo structure consists of the following elements: instanceId
The ID of the instance.
instanceAttributes
The attributes of the instance.
StatusList The StatusList data structure is used to hold a list of status information for an operation.
The StatusList structure consists of the following element: items
230
Developer’s Reference Guide
The status value of the operation.
Data structures
Status The Status data structure is used to hold the status information for an operation.
The Status structure consists of the following elements: statusType
The type of status message for the operation. OK—Operation successful. Status might contain one or more
informational messages. WARNING—Operation successful, but some problems encountered. Status contains one or more warning messages and might also contain information messages. ERROR—Operation failed. Status contains one or more error
messages and might also contain warning or informational messages. FATAL—Operation failed. BAD_STATUS—Invalid status parameter. Operaion cancelled. PROMPT—Status for the active link action. ACCESSIBLE—Status message for client accessibility.
messageNum
An integer value indicating the message number.
messageText
The description for the status message.
appendedText
Additional information for the status message.
Chapter 6 Web services API operations and data structures
231
BMC Atrium CMDB 2.1.00
Graph query structures Graph query structures are data structures used in graph queries. The graph query data structures include:
GraphList (page 232) Graph (page 232) GraphAdjacencyList (page 233) GraphAdjacency (page 233) ObjectQueryInfoList (page 234) ObjectQueryInfo (page 234) RelationQueryInfoList (page 235) RelationQueryInfo (page 235)
GraphList The GraphList data structure is used to hold a list of graph information.
The GraphList structure consists of the following element: items
A list of Graph structure items.
Graph The Graph data structure is used to hold the query graph information.
The Graph structure consists of the following elements:
232
classNameId
The name of the class for the object (node).
extensionId
The extension ID of the node.
adjacencyList
The list of adjacent objects (nodes).
Developer’s Reference Guide
Data structures
GraphAdjacencyList The GraphAdjacencyList data structure is used to hold a list of graph adjacency items.
The GraphAdjacencyList structure consists of the following element:\ items
A list of GraphAdjancency structure items.
GraphAdjacency The GraphAdjacency data structure is used to hold an adjacent node.
Chapter 6 Web services API operations and data structures
233
BMC Atrium CMDB 2.1.00
The GraphAdjacency structure consists of the following elements: extensionId
The extension ID of the object. This item can contain an empty string.
objectClassName
The object class name.
objectAttributeNames
The object attribute to retrieve.
objectAttributeType
The type of object attributes to retrieve. NONE—Retreive no attributes in the query. NOHIDDEN—Retreive all non-hidden attributes. ALL—Retreive all the attributes.
objectQuery
The qualification for the object. This item can be NULL.
relationClassNames
The name of the class that makes up the relationship.
relationAttributeNames
The related attribute to retrieve from the relationship.
relationAttributeType
The related attribute type.
relationQuery
The qualification string that qualifies the relationship. This item can be NULL.
ObjectQueryInfoList The ObjectQueryInfoList data structure is used to hold a list of CI instances.
The ObjectQueryInfoList structure consists of the following element: items
A list of ObjectQueryInfo items.
ObjectQueryInfo The ObjectQueryInfo data structure is used to hold a CI instance. < xsd:element name="classNameId" type="tns:ClassNameId"/>
The ObjectQueryInfoList structure consists of the following element: classNameId
234
Developer’s Reference Guide
The class name ID for the class.
Data structures
RelationQueryInfoList The RelationQueryInfoList data structure is used to hold a list of relationships.
The RelationQueryInfoList structure consists of the following element: items
A list of RelationQueryInfo items.
RelationQueryInfo The RelationQueryInfo data structure is used to hold relationship information.
