CMDB2.0.1_DevelopersReferenceGuide

BMC® Atrium™ CMDB 2.0.1 Developer’s Reference Guide November 2006 Part No: 64742 Copyright 1991–2006 BMC Software, Inc. All rights reserved. BMC, the BMC logo, all other BMC product or service names, BMC Software, the BMC Software logos, and all other BMC Software product or service names, are registered trademarks or trademarks of BMC Software, Inc. All other trademarks belong to their respective companies. BMC Software, Inc., 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 or nondisclosure 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. Contacting Us If you need technical support for this product, contact Customer Support by email at [email protected]. If you have comments or suggestions about this documentation, contact Information Development by email at [email protected]. This edition applies to version 2.0.1 of the licensed program. BMC Software, Inc. www.bmc.com Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 The New icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 BMC Atrium CMDB documentation . . . . . . . . . . . . . . . . . . 10 Section I Chapter 1 Developing programs with the CMDB APIs . . . . . . . . . . 13 Introduction to the BMC Atrium CMDB APIs . . . . . . . . . . . . 15 BMC Atrium CMDB API overview . . . . . . . . . . . . . . . . . . . 16 C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Web services API . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Using API programming compared with the CMDB Console . . . . . . . . 20 When to use the API compared with the CMDB Console . . . . . . . . . 20 CMDB Console and API terminology . . . . . . . . . . . . . . . . . 21 Chapter 2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . 23 C API package contents . . . . . . . . . . . . . . . . . . . . . . . . 24 Header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Compiler information . . . . . . . . . . . . . . . . . . . . . . . . 29 Link information . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Contents 3 BMC Atrium CMDB 2.0.1 Java API package contents . . . . . . . . . . . . . . . . . . . . . . . 30 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Sample source code . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Renamed C and Java API objects . . . . . . . . . . . . . . . . . . . . 33 Migrating to the BMC Atrium CMDB 2.0 API . . . . . . . . . . . . . . 33 API parameter changes . . . . . . . . . . . . . . . . . . . . . . . 34 Data structure changes. . . . . . . . . . . . . . . . . . . . . . . . 35 Chapter 3 Programming common BMC Atrium CMDB tasks . . . . . . . . . 37 Java program requirements . . . . . . . . . . . . . . . . . . . . . . . 38 Working with configuration item classes and instances. . . . . . . . . . . 38 Creating a CI class . . . . . . . . . . . . . . . . . . . . . . . . . 38 Creating attributes for your class . . . . . . . . . . . . . . . . . . . 40 Creating a CI instance . . . . . . . . . . . . . . . . . . . . . . . . 42 Working with relationship classes and instances. . . . . . . . . . . . . . 44 Creating a relationship class . . . . . . . . . . . . . . . . . . . . . 44 Creating a relationship between two CI instances . . . . . . . . . . . . 46 Retrieving instance details . . . . . . . . . . . . . . . . . . . . . . 47 Chapter 4 BMC Atrium CMDB tools . . . . . . . . . . . . . . . . . . . . . 49 Working with the cmdbdriver program . . . . . . . . . . . . . . . . . 50 From the command line . . . . . . . . . . . . . . . . . . . . . . . 50 Using a script . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Using cmdbdriver on UNIX . . . . . . . . . . . . . . . . . . . . . 52 Migrating data between BMC Atrium CMDB servers . . . . . . . . . . . 53 Logging in to the cmdbdriver program . . . . . . . . . . . . . . . . . 54 Step 1—Exporting class data with cmdbdriver . . . . . . . . . . . . . . 55 Step 2—Export instance data with cmdbdriver . . . . . . . . . . . . . 56 Step 3—Import class definitions with cmdbdriver . . . . . . . . . . . . 57 Step 4—Import instance data with cmdbdriver . . . . . . . . . . . . . 58 Step 5—Export reconciliation definitions . . . . . . . . . . . . . . . . 59 Step 6—Import reconciliation definitions . . . . . . . . . . . . . . . 60 4 Contents Developer’s Reference Guide Using the extension loader . . . . . . . . . . . . . . . . . . . . . . . 61 The extension loader directory structure . . . . . . . . . . . . . . . . 62 Packaging and installing BMC Atrium CMDB extensions . . . . . . . . . 63 Integrating the CI Relationship Viewer with other applications . . . . . . . 70 Launching the CI Relationship Viewer from AR System applications . . . . 71 Embedding the CI Relationship Viewer in AR System applications . . . . . 73 Launching the CI Relationship Viewer from non-AR System applications . . 75 Configuring the CI Relationship Viewer . . . . . . . . . . . . . . . . . 77 Working with filters . . . . . . . . . . . . . . . . . . . . . . . . . 77 Customizing the configuration file. . . . . . . . . . . . . . . . . . . 77 Creating CI Relationship Viewer events . . . . . . . . . . . . . . . . 84 Creating CMDB status alerts . . . . . . . . . . . . . . . . . . . . . . 85 Importing data with EIE . . . . . . . . . . . . . . . . . . . . . . . . 86 Working with SQL views . . . . . . . . . . . . . . . . . . . . . . . . 87 Debugging BMC Atrium CMDB API programs . . . . . . . . . . . . . . 88 Using the API Logging option . . . . . . . . . . . . . . . . . . . . 88 Using print.c routines . . . . . . . . . . . . . . . . . . . . . . . . 89 Section II Chapter 5 API reference . . . . . . . . . . . . . . . . . . . . . . . . 91 C API functions and data structures . . . . . . . . . . . . . . . . 93 Related files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Deprecated objects . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Deprecated functions . . . . . . . . . . . . . . . . . . . . . . . . 94 Deprecated data structures . . . . . . . . . . . . . . . . . . . . . . 95 Contents 5 BMC Atrium CMDB 2.0.1 Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Data model functions . . . . . . . . . . . . . . . . . . . . . . . . 95 Instance functions . . . . . . . . . . . . . . . . . . . . . . . . 126 Bulk entry transaction functions . . . . . . . . . . . . . . . . . . 139 Environment functions . . . . . . . . . . . . . . . . . . . . . . 141 User interface component functions . . . . . . . . . . . . . . . . . 146 Import and Export functions . . . . . . . . . . . . . . . . . . . . 149 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . 155 Free functions . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Reconciliation Engine functions. . . . . . . . . . . . . . . . . . . 172 Federation functions . . . . . . . . . . . . . . . . . . . . . . . 176 Audit functions. . . . . . . . . . . . . . . . . . . . . . . . . . 179 Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Class structures . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Attribute structures . . . . . . . . . . . . . . . . . . . . . . . . 186 Instance structures . . . . . . . . . . . . . . . . . . . . . . . . 196 General purpose structures . . . . . . . . . . . . . . . . . . . . . 198 Export and import structures . . . . . . . . . . . . . . . . . . . . 199 Graph query structures . . . . . . . . . . . . . . . . . . . . . . 206 User interface components structures . . . . . . . . . . . . . . . . 210 Reconciliation Engine structures . . . . . . . . . . . . . . . . . . 212 Federation structures . . . . . . . . . . . . . . . . . . . . . . . 215 Audit structures . . . . . . . . . . . . . . . . . . . . . . . . . 218 Chapter 6 Web services API operations and data structures . . . . . . . . 221 Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Instance data operations . . . . . . . . . . . . . . . . . . . . . . 222 Data model operations. . . . . . . . . . . . . . . . . . . . . . . 234 Reconciliation Engine operations . . . . . . . . . . . . . . . . . . 247 Federation operations . . . . . . . . . . . . . . . . . . . . . . . 252 Audit operations . . . . . . . . . . . . . . . . . . . . . . . . . 256 User interface component operations . . . . . . . . . . . . . . . . 258 Utility operations . . . . . . . . . . . . . . . . . . . . . . . . . 260 6 Contents Developer’s Reference Guide Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Instance structures . . . . . . . . . . . . . . . . . . . . . . . . 262 Graph query structures . . . . . . . . . . . . . . . . . . . . . . 267 Class Structures. . . . . . . . . . . . . . . . . . . . . . . . . . 272 Attribute structures . . . . . . . . . . . . . . . . . . . . . . . . 278 Utility structures . . . . . . . . . . . . . . . . . . . . . . . . . 286 User interface component structures . . . . . . . . . . . . . . . . . 288 Reconciliation Engine structures . . . . . . . . . . . . . . . . . . 290 Federation structures . . . . . . . . . . . . . . . . . . . . . . . 293 Audit structures . . . . . . . . . . . . . . . . . . . . . . . . . 295 Chapter 7 Error messages . . . . . . . . . . . . . . . . . . . . . . . . . 297 BMC Atrium CMDB C API error messages . . . . . . . . . . . . . . . . 298 CMDB Console active link error messages . . . . . . . . . . . . . . . . 327 CMDB Console filter error messages. . . . . . . . . . . . . . . . . . . 334 Appendix A CI Relationship Viewer events . . . . . . . . . . . . . . . . . . 341 Events from AR System to CI Relationship Viewer. . . . . . . . . . . . . 342 Events from CI Relationship Viewer to AR . . . . . . . . . . . . . . . . 344 Appendix B Finding related CIs using graph queries . . . . . . . . . . . . . 345 Representing graphs . . . . . . . . . . . . . . . . . . . . . . . . . . 346 The CMDBGraphQuery API function . . . . . . . . . . . . . . . . . . 347 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 Contents 7 0.BMC Atrium CMDB 2.1 8 Contents . and other BMC Atrium CMDB tools to program your BMC Atrium CMDB application and integrate it with other applications. ! 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. provides instructions on how to program the BMC Atrium CMDB using Java methods. 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. web services operations.0. Java. and the data structures used by each function and operation.Preface The BMC Atrium CMDB 2.1 Developer’s Reference Guide describes how to use the BMC Atrium Configuration Management Database (CMDB) C. Preface 9 . and web services APIs. API reference—This section provides descriptions of the C API functions. It also provides a list of error messages generated in the BMC Atrium CMDB along with their descriptions and solutions. and provides procedures for using other BMC Atrium CMDB tools. 0.0.1 Installation and Configuration Guide Information about installing and configuring the BMC Atrium CMDB. online documentation in Adobe Acrobat (PDF) format is available in the sdk\doc subdirectory of the product installation directory. Users Print and PDF 10 Preface . Administrators Print and PDF BMC Atrium CMDB 2. or both.1 Audience This guide is intended for application programmers. For more information about configuring the application. see the Installation and Configuration Guide. BMC Atrium CMDB 2.0 Information about CMDB concepts and IT leaders and Print and Concepts and Best Practices Guide best practices for planning your BMC administrators PDF Atrium CMDB implementation. Title Document provides Audience Format BMC Atrium CMDB 2. relating CIs.0. 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. Other documentation is available in the sdk\doc subdirectory. including permissions.1 User’s Information about using the BMC Guide Atrium CMDB. BMC Atrium CMDB documentation The following table lists the documentation available for the BMC Atrium CMDB. viewing history.com.BMC Atrium CMDB 2.0. and federation. You can access product Help by clicking on Help links. and launching federated data. including searching for and comparing CIs and relationships. Unless otherwise noted. from the Support link from http://supportweb. class definitions. reconciliation.remedy. 1 Help Help for using and configuring the BMC Users and Product Atrium CMDB.1 Common Data Model Help BMC Atrium CMDB 2.1 Release Notes BMC Atrium CMDB 2. Procedures for installing AR System.0.1 Javadoc API Help Information about Java classes. and resolved issues. attributes.0. and relationships for each class.0. Print and PDF Administrators Print and PDF BMC Atrium CMDB documentation 11 . open issues. importing and exporting data. and archiving data. Everyone Everyone Print and PDF Print and PDF BMC Atrium CMDB 2. Combined index of all guides. and OLE and programmers support. methods.1 Developer’s Reference Guide Document provides Audience Format Administrators Print and Information about creating API PDF programs.1 Master Index BMC Atrium CMDB 2.0: C API Reference BMC Remedy Action Request System 7.0. HTML BMC Atrium CMDB 2. Information about new features.0: Form and Application Objects BMC Remedy Action Request System 7. localizing. administrators Help BMC Remedy Action Request System 7. and views. C API function calls. forms. subclasses.0: Installing Administrators Print and Information about AR System data PDF structures.0: Configuring BMC Remedy Action Request System 7.0 Common Data Model Diagram Hierarchical diagram of all classes in the Administrators PDF Common Data Model (CDM) including unique attributes and applicable relationships. and a list programmers of error messages. using C and web services API and functions and data structures. fields. Programmers and variables that integrate with the BMC Atrium CMDB. Administrators HTML BMC Atrium CMDB 2.0. and a relationship normalization table. Information about configuring AR System servers and clients.0. including applications. Administrators Print and PDF Description of the components necessary Developers to build applications in AR System. Description and details of superclasses.Developer’s Reference Guide Title BMC Atrium CMDB 2. Audience Format Administrators Print and PDF Administrators Print and Information about integrating AR System with external systems using plug.1 Title BMC Remedy Action Request System 7.0: Integrating with Plug-ins and Third-Party Products BMC Remedy Action Request System 7.0: Workflow Objects Document provides Information about the mid tier. including LDAP.0.BMC Atrium CMDB 2.and developers PDF ins and other products. and web server configuration. Developers Print and PDF 12 Preface . Information about the workflow. and ARDBC. including mid tier installation and configuration.0: Installing and Administering BMC Remedy Mid Tier BMC Remedy Action Request System 7. OLE. such as the cmdbdriver program and the extension loader. which includes a C 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. “Introduction to the BMC Atrium CMDB APIs.Section I Developing programs with the CMDB APIs This section explains how to use the BMC Atrium CMDB tools. “Programming common BMC Atrium CMDB tasks. Chapter 4. “Getting started.” provides Java code samples for a list of basic programming tasks that are performed most often in BMC Atrium CMDB API programs. Java API. and web services API.” provides instructions for using the BMC Atrium CMDB tools.” provides information about the preparatory steps you must follow before you use the BMC Atrium CMDB API suite. such as the cmdbdriver and extension loader. Chapter 3. Developing programs with the CMDB APIs 13 . This section is organized into the following chapters: ! ! ! ! Chapter 1. “BMC Atrium CMDB tools. and how to programmatically extend your application using the BMC Atrium CMDB APIs.” provides an overview of the BMC Atrium CMDB architecture and the BMC Atrium CMDB API suite. 1 14 Section I—Developing programs with the CMDB APIs .0.BMC Atrium CMDB 2. The following topics are provided: ! ! BMC Atrium CMDB API overview (page 16) Using API programming compared with the CMDB Console (page 20) Introduction to the BMC Atrium CMDB APIs 15 .Chapter 1 Introduction to the BMC Atrium CMDB APIs This chapter provides an overview of the BMC Atrium CMDB application programming interface (API) suite. 0. You can use either C or Java API depending on your application platform. federation. The BMC Atrium CMDB API suite is composed of the C. reconciliation. Data can flow in any direction. Java. Figure 1-1: BMC Atrium CMDB C and Java architecture AR System Applications Service Impact Manager CMDB Console BMC Remedy User Web Client CI Relationship Viewer BMC Remedy User Web Client Topology Discovery Web Service Clients . 16 Chapter 1—Introduction to the BMC Atrium CMDB APIs . instance data. The C and Java APIs provide similar data structures and functions to encapsulate information and functionality.Net Client AXIS 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. and web services APIs. The web services API provides a set of platform-independent operations that communicate with your applications to retrieve and send data.BMC Atrium CMDB 2.1 BMC Atrium CMDB API overview The BMC Atrium CMDB provides an API suite to programmatically work with class definitions. audit and other functions. To access the Javadoc API Help. reconciliation. such as: ! ! ! Create. Includes a set of Free functions that you can use to deallocate memory. Components The C API consists of a set of functions and data structures. BMC Atrium CMDB API overview 17 . most of which perform a specific database or data source operation. federation. For more information about the Java API. a BMC Atrium CMDB components. see the Javadoc API Help. which is located in the sdk/ doc/javadoc/cmdbapi/ subdirectory of your BMC Atrium CMDB installation directory. instance data. For example. open the index.html file. delete. C API A BMC Atrium CMDB client can use the C API to create. and other functions. whereas the external data consumers and data providers can communicate either using the web services API or Java API. you can use a function to retrieve information about a particular BMC Atrium CMDB class. A simple data structure serves as the primary building block for a complex data structure. modify. Create log files in a format that is different from the standard reports. Retrieve CI and relationship information. Provides server-access information with every call in the control parameter of the function. and delete classes and instances.Developer’s Reference Guide As shown in Figure 1-1 on page 16. such as the CI Relationship Viewer and CMDB Console use the Java API to manipulate the CDM. and query the class definitions. ! ! Features You can use the C API functions to perform operations. The C API: ! Contains data structures that store both simple and complex information. modify. This guide describes the C and web services APIs. “C API functions and data structures. they do not correspond one-to-one with the C API. BMC® Remedy® Change Management. The cmdbdriver program also includes print routines for every data structure in the API.1 Most of these C API functions accept one or more BMC Atrium CMDB C data structures as parameters that qualify the action to perform.BMC Atrium CMDB 2. Users—For developing programs that set up communication between the BMC Atrium CMDB and other products running in their environment. Web services API The BMC Atrium CMDB web services API provides a standard interface for interacting with the BMC Atrium CMDB. for example. such as type of class to create. or class name to modify. For more information about the C API functions and data structures. or any other third-party application. see Chapter 5. You can use the web services API to integrate BMC Atrium CMDB data with other applications. Features External web-based programs can communicate with the BMC Atrium CMDB using the web services operations. For more information about the print routines.” 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. see “Debugging BMC Atrium CMDB API programs” on page 88. ! Although the web services operations are based on the BMC Atrium CMDB C API functions. making it a useful debugging tool.0. The web services operations are wrapper classes on top of the BMC Atrium CMDB and AR System APIs. The BMC Atrium CMDB web services operations are developed to assist the following communities: ! BMC software partners—For developing integrated solutions with the BMC Atrium CMDB. qualification for an instance to retrieve or delete. BMC Topology Discovery and BMC Foundation Discovery. 18 Chapter 1—Introduction to the BMC Atrium CMDB APIs . server access information is encapsulated in an ARServerUser object. To access the Javadoc API Help. which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. For more information about the web services operations that are currently available. ! ! BMC Atrium CMDB API overview 19 . In the Java API. see BMC Remedy Action Request System 7. open the index. You will find it easier to use the Java API if you are already familiar with the C API. 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. “Web services API operations and data structures. see the Javadoc API Help. Features The following list describes the Java API features: ! The Java virtual machine (JVM) automatically deallocates objects that are created with the Java API. For more information about the Java API. see Chapter 6. For more information about ARServerUser object.Developer’s Reference Guide Components The web services API is a wrapper on top of the Java API. each of the web services operations and data structures corresponds to a method in the Java API. Therefore.” 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. The Java API provides an object model of the BMC Atrium CMDB.html file.0: Integrating with Plug-ins and Third-Party Products. The Java API has its own naming conventions. such as viewing CI history. and maintain.BMC Atrium CMDB 2. or search for BMC Atrium CMDB classes. and relationships. delete. Use API Programming? Use the CMDB Console? Yes Yes Yes 20 Chapter 1—Introduction to the BMC Atrium CMDB APIs . Table 1-1: API Programming scenarios Requirement You want to modify the CDM. Viewing CI and relationship classes. API solutions are more complex to design. CIs. You need to create. and. the Reconciliation Engine Manager. see the Installation and Configuration Guide. such as using the Class Manager. and comparing instances. The CMDB Console provides an easy-to-use graphical user interface for performing BMC Atrium CMDB tasks. In addition. implement.1 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. Federation Manager. However. API programming gives you the flexibility to customize your application. You need to access multiple BMC Atrium CMDB components at the same time or integrate with programs or data outside the BMC Atrium CMDB. For more information about performing user tasks using the CMDB Console.0. and viewing instance history. such as creating classes. For more information about performing administrator tasks using the CMDB Console. see the 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. You need a two-way interface (or gateway) between the BMC Atrium CMDB and another application. Use API Programming? Yes Use the CMDB Console? Yes Yes Yes CMDB Console and API terminology The CMDB Console and the APIs use different terms to see a specific task. Table 1-2 list these differences. delete. You need to create. The values you want to specify for $PROCESS$ or the Run Process action exceed the size limitation of the command line. Table 1-2: CMDB Console and API terminology BMC Atrium CMDB term search create modify view/display API term getList create set get Using API programming compared with the CMDB Console 21 .Developer’s Reference Guide Requirement You need to perform complex operations that involve multiple objects. or search BMC Atrium CMDB relationships. BMC Atrium CMDB 2.1 22 Chapter 1—Introduction to the BMC Atrium CMDB APIs .0. 0 API (page 33) Getting started 23 . The following topics are provided: ! ! ! ! ! C API package contents (page 24) Java API package contents (page 30) Sample source code (page 32) Renamed C and Java API objects (page 33) Migrating to the BMC Atrium CMDB 2.Chapter 2 Getting started This chapter describes the preliminary steps you must follow before you use the BMC Atrium CMDB API suite. h arstruct. ANSI C. arfree. BMC Atrium CMDB C API data type and structure definitions.h arerrno. and source code for the cmdbdriver sample programs. These functions recursively free all allocated memory associated with a particular data structure.BMC Atrium CMDB 2. library files. Core and reserved subclasses ID definitions. the C API is also installed with the package. These functions recursively free all allocated memory associated with a particular data structure. size limits. and constant definitions.h Contents AR System API data type and structure definitions.h 24 Chapter 2—Getting started . Header files Table 2-1 displays the list of C API header files installed in the include directory: Table 2-1: C API Header files File Name ar. or C++ compilers. External declarations for the FreeAR functions. specified with and without prototypes for use with standard C. and constant definitions. External declarations for the FreeCMDB functions. size limits. When you install the BMC Atrium CMDB application.0. database separator characters. External declarations for the API functions.1 C API package contents The C API package includes header files.h arextern. Error code definitions. and labels for exporting structure definitions.h cmdb.h cmdbfree. dll arutl70.dll xerces-c_2_6.dll icudt32.dll libcmdbconsolefilterapi20.dll icuuc32.dll cmdbeng20.dll msvcp71.dll msvcr71.dll cmdbsvr20.dll icuin32.dll XalanMessages_1_9.dll cmdb2asset.dll in your path at runtime and make sure the lib directory contains the API library files listed in Table 2-2.dll xerces-depdom_2_6.dll ariapi70.dll arjni70.dll arapi70.dll Xalan-C_1_9.dll rcmn70.dll arrpc70. Table 2-2: C API library files Platform Windows Files mfc71.dll cmdbjni20.dll cmdbapi20.dll arcatalog_eng.Developer’s Reference Guide Library files You must have arcatalog_eng.dll C API package contents 25 .dll arutiljni70.dll arxmlutil70. 26 libari70.so libcmdbconsolefilterapi20.a libxerces-depdombmc.so libcmdbeng20.so libutil.so libcmdbsvr20.BMC Atrium CMDB 2.19 libarxmlutil.a libcmdbapi20.so.0.so libarjni70.so.so.so.1 Platform Solaris Files libcmdbjni20.so libxalan-cbmc.so libcmdb2asset.32 libxerces-cbmc.19 libjlicapi70.32 libxalanMsgbmc.so libicui18nbmc.so libar.so libicuucbmc.so libicudatabmc.32 libarutiljni70.26 26 Chapter 2—Getting started .so.so.so. a libari70.a libarxmlutil.a libar.a libxalanMsgbmc.0.a libcmdbjni20.a libcmdb2asset.a libxerces-cbmc26.a libxerces-depdombmc26.a libxerces-depdombmc.a libutil.a libxerces-depdombmc26.a C API package contents 27 .a libicudatabmc32.a libxalan-cbmc19.a libcmdbeng20.a libxerces-cbmc.a libcmdbapi20.a libarutiljni70.a libjlicapi70.a libxerces-cbmc26.a libicuucbmc32.0.Developer’s Reference Guide Platform AIX Files libcmdbsvr20.a libcmdbconsolefilterapi20.a libicui18nbmc32.a libarjni70. 0.19 libari70.sl libcmdbsvr20.sl libcmdbapi20.26 libarutiljni70.19 libarxmlutil.sl libxerces-cbmc.32 libxalanMsgbmc.a libcmdbjni20.sl.sl.1 Platform HP-UX Files libutil.sl libarjni70.sl libicudatabmc.sl libicui18nbmc.sl.32 libxalan-cbmc.sl.a libcmdb2asset.sl libjlicapi70.BMC Atrium CMDB 2.sl.32 28 Chapter 2—Getting started .sl.26 libicuucbmc.sl libxerces-depdombmc.sl libar.sl libcmdbeng20.sl libcmdbconsolefilterapi20.sl. For more information about linking and compiling your code. make sure that the following software programs are installed or configured on your system: ! ! Microsoft Visual C++ version 7.so libxerces-depdombmc.so libarutiljni70.so.19 libxerces-cbmc.so libar.32 libjlicapi70. see the driver sample makefile in the sdk\samples\driver subdirectory of the BMC Atrium CMDB installation directory.32 For Solaris and Linux: To load dynamic libraries.so libicui18nbmc.26 libari70.so.32 libxalanMsgbmc.Developer’s Reference Guide Platform Linux Files libcmdbeng20.so.so.so libicuucbmc. you need to include the -ldl link flag in the link command.so.so libcmdbconsolefilterapi20.0 or later Structure member alignment: 8 bytes (default) C API package contents 29 .19 libxalan-cbmc.so libutil.a libcmdbjni20.so libcmdbapi20.so.a libicudatabmc.so libcmdbsvr20.so libcmdb2asset.26 libarxmlutil.so. Compiler information Before you write C API programs.so libarjni70. Linux HP-UX AIX Links cmdbapi20.so libarapi70.1 ! Set code generation to Multithreaded DLL.a Java API package contents The Java API package includes several header files and library files. 30 Chapter 2—Getting started . If your program references this library at runtime. When you install the BMC Atrium CMDB application. memory management errors will occur when memory pointers are referenced by both the Debug and Release C runtime libraries.a libarapi70.BMC Atrium CMDB 2.dll arapi70. ANSI standard C or C++ compiler (for UNIX) ! Link information Table 2-3 lists the libraries that your programs must use for linking to the BMC Atrium CMDB.0.sl libarapi70.sl libcmdbapi20. not DebugMultithreaded DLL. Table 2-3: Link files Platform Windows Solaris.dll libcmdbapi20. the Java API is also installed with the package.so libcmdbapi20. add /nodefaultlib:"MSVCRTD" to the project options to avoid using the Debug C runtime library. Where other included libraries cause conflicts. jar libarutil70.jar arjni70.sl Java API package contents 31 .jar libcmdbapi20.jar arutil70.jar libarjni70.Developer’s Reference Guide Requirements To build and run a Java API program on either Windows or UNIX. Table 2-4: Java API library files Platform Windows Files arapi70. J2SE Software Development Kit (SDK).jar libarjni70.sl libcmdbjni20.so HP-UX libarapi70.jar cmdbjni20. ! ! Library files Table 2-4 lists the Java API library files that are installed with the BMC Atrium CMDB application.so libcmdbjni20. as listed in the “C API package contents” on page 24.dll cmdbapi20.jar libcmdbapi20.jar libarutil70. version 1. you need the following environment components: ! All C API libraries and DLLs. Windows dynamic link library (DLL) files or UNIX library files as listed in Table 2-4.2 or higher.4.dll Solaris libarapi70. see Chapter 4. Table 2-5: Header files for the CMDB programs Header file name com.remedy.0. “Working with the cmdbdriver program. Description AR System API functions CMDB API functions Java utilities library Sample source code The sdk/samples/driver subdirectory in the BMC Atrium CMDB installation directory. When the BMC Atrium CMDB API package is installed.so libcmdbjni20.jar libcmdbapi20.jar libarutil70.api.cmdb.a Linux libarapi70.api.” 32 Chapter 2—Getting started .jar libcmdbapi20. For more information about the cmdbdriver program.remedy.*.arsys. java. includes the source code for a sample BMC Atrium CMDB client program.*. The src directory contains subdirectories with source code for the cmdbdriver sample program.*. a series of directories is created in the installation directory.jar libarjni70. com.jar libarjni70.BMC Atrium CMDB 2.util.a libcmdbjni20.so Header files Table 2-5 lists the header files that are installed with the Java API.1 Platform AIX Files libarapi70. A compiled version of the cmdbdriver program is located in the sdk/bin directory.jar libarutil70. exe ! Java API namespaces. several CMDB API objects are renamed.0. Experiment with different parameter values. and will not work for the 2. Examine the content and structure of function output parameters. variables.0 API This section describes the API changes for the 2. replacing the strings “AROS” and “OS” with “CMDB. Renamed C and Java API objects 33 .0 release.0 libraries. If your programs use one of the earlier versions of the BMC Atrium CMDB APIs. it does not support all functions from the client applications that use the 1. packages.0 release of the BMC Atrium CMDB. need not change. methods. Therefore. The main program structure and processing. data structures.” These include: ! ! C API functions. and constants C API library and header files ! osdriver. and link to the 2. The old names are deprecated.0 release. however. or 1. classes. you can use cmdbdriver to: ! Identify function input parameters and load them with appropriate values.Developer’s Reference Guide After compiling the source code or locating the prebuilt program supplied with the API. Migrating to the BMC Atrium CMDB 2. The BMC Atrium CMDB is not backward-compatible. ! ! Renamed C and Java API objects In the BMC Atrium CMDB version 2.1 APIs. you must rewrite your programs to use the 2. functions.0 API functions. and constants Java and JNI library and header files Javadoc directory and files ! ! This guide and the Java API Help use only the new names for these objects. auditInfo The auditInfo parameter specifies the audit information for the CI class. datasetId 34 Chapter 2—Getting started .0.1 API parameter changes Table 2-6 describes the changes in the 2. Table 2-6: API function changes Parameter added getMask Functions affected CMDBGetInstance CMDBGetListInstance CMDBGetMultipleInstance CMDBGetInstanceBLOB CMDBGraphQuery CMDBCreateClass CMDBSetClass CMDBGetClass CMDBCreateInstance CMDBSetInstance CMDBGetInstance CMDBGetListInstance CMDBGetMultipleInstance CMDBDeleteInstance CMDBGetInstanceBLOB CMDBGetRelatedFederatedInContext CMDBActivateFederatedInContext CMDBGraphQuery CMDBGetCopyAuditData CMDBGetLogAuditData CMDBGetUIComponents Description The getMask parameter specifies that the function should manipulate the data in the overlay datasets.0 APIs that might affect your existing programs.BMC Atrium CMDB 2. The datasetId parameter specifies the dataset that the function should use. Holds federation information. Holds the BMC Atrium CMDB version information. Holds a list of audit values in audit functions. Holds audit information. Holds job run information. Holds a list of BMC Atrium CMDB version information. Holds component information. Holds audit values. CMDBGetClass CMDBStartJobRun Holds a list of qualifications for the class when running a job with qualification substitution. Holds job run information. CMDBSetClass. Holds a list of component results.Developer’s Reference Guide Data structure changes This section describes the changes to the data structures that are used in the API functions.0 API 35 . Holds the federated AR System information. CMDBCreateClass. Migrating to the BMC Atrium CMDB 2. Table 2-7: API data structure changes Data structure added CMDBUIComponentResult (New) CMDBUIComponentInfo (New) CMDBUIComponentResultList (New) CMDBVersionInfo (New) CMDBVersionInfoList (New) CMDBREJobRunInfoStruct (New) CMDBREJobRunInfoList (New) CMDBFederatedARInfo (New) CMDBFederatedActiveInfo (New) CMDBAuditValueList (New) CMDBAuditValueListList (New) CMDBAuditInfoStruct (New) CMDBREClassQualList (New) Functions affected CMDBGetCMDBUIComponents CMDBGetCMDBUIComponents CMDBGetCMDBUIComponents CMDBGetVersions CMDBGetVersions CMDBGetJobRun CMDBGetListJobRun CMDBActivateFederatedInContext CMDBActivateFederatedInContext CMDBGetCopyAuditData CMDBGetCopyAuditData Description Holds component result information. 0. 36 Chapter 2—Getting started . Holds a list of CMDBREDatasetPair CMDBREDatasetList CMDBStartJobRun structures when running a job with dataset substitution.1 Table 2-7: API data structure changes Data structure added CMDBREDatasetPair Functions affected CMDBStartJobRun Description Holds the substitute and original datasets when running a job with dataset substitution.BMC Atrium CMDB 2. Chapter 3 Programming common BMC Atrium CMDB tasks This chapter describes how to use the BMC Atrium CMDB Java methods to perform common tasks. The following topics are provided: ! ! ! Java program requirements (page 38) Working with configuration item classes and instances (page 38) Working with relationship classes and instances (page 44) Programming common BMC Atrium CMDB tasks 37 . These tasks are explained using Java code samples. such as the class name. are encapsulated in a CI class definition. Working with configuration item classes and instances Configuration items (CIs) are the focal point of the BMC Atrium CMDB application. such as data storage and inheritance. make sure you point the class path environment variable to the BMC Atrium CMDB jar files directory. see the Javadoc API Help. When you create a class. see “Java API package contents” on page 30.0. which can invoke one another. and data storage method. PhoneSystem and Socket. Creating a CI class The following example creates two classes. The attributes of a CI and other properties. CMDBClassNameKey phoneSystemClassNameKey = new CMDBClassNameKey(phoneSystemClassName. Example: Creating classes //Create variables to hold the class name data String acmeNamespace = "ACME". acmeNamespace).BMC Atrium CMDB 2. To access the Javadoc API Help. you define all the characteristics for it. 38 Chapter 3—Programming common BMC Atrium CMDB tasks . For your Java code to compile with the BMC Atrium CMDB classes. //Create the class name key for the Phone System class. All class definitions that extend the CDM use a namespace other than BMC. namespace. String phoneSystemClassName = "phoneSystem". open the index. For the list of header files and link files required for your Java code. String phoneSystemClassID = "ABCD-1234". Both classes are created in the ACME namespace. For more information about specific Java method parameters.CORE. superclass.html file.1 Java program requirements The procedural building blocks of a BMC Atrium CMDB program are functions or operations. which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. String socketClassName = "Socket". out. } In the example.println(ex.toString()).toString()). /* create the socket class in the BMC Atrium CMDB try { socketClass. the phoneSystemClassNameKey and socketClassNameKey class variables hold the class name and namespace definitions for the phoneSystem and Socket classes respectively. A class ID is an identification string that uniquely identifies a particular class within the BMC Atrium CMDB.out. The classNameKey class variables are passed as parameters to the constructor of the CMDBClass class. open index.create(currentUser).println(ex. socketClassID. the phoneSystemClass and socketClass classes are created in the BMC Atrium CMDB. acmeNamespace). try { //Create the Phone System class in the BMC Atrium CMDB phoneSystemClass. null). } catch (ARException ex) { System. null).create(currentUser). } //create the socket class CMDBClassNameKey socketClassNameKey = new CMDBClassNameKey(socketClassName. For more information about the parameters for the CMDBCreateClass function. String socketClassID = "ACME_SocketClass". which is located in the sdk/ doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. In the try loop. phoneSystemClassID. } catch (ARException ex) { System.html of the Java API Help. CMDBClass socketClass = new CMDBClass(socketClassNameKey.Developer’s Reference Guide //Create an instance of the CMDBClass CMDBClass phoneSystemClass = new CMDBClass(phoneSystemClassNameKey. The currentUser parameter is a pre-instantiated ARServerUser class that has valid user login credentials. Working with configuration item classes and instances 39 . int costFieldId = ACME_COST_FIELD_ID.update(currentUser). costAttr).CMDB_ATTR_ENTRYMODE_REQUIRED. //Create another attribute for the phoneSystem class String costAttrName = "Cost". //Define a data type and limit for the attribute CMDBAttributeLimit serialNumLimit = newCMDBCharLimit(30). //Create a variable of type Currency CMDBAttributeLimit costLimit = new CMDBCurrencyLimit.BMC Atrium CMDB 2. null). //Create a Java instance of the attribute CMDBAttribute serialNumAttr = new CMDBAttribute(serialNumAttrName. //Add the two attributes to the hash map attributeHashMap.put(serialNumAttruName. Example: Creating attributes //Create attributes for the phoneSystem class String serialNumAttrName = "ACMESerialNumber". The following example illustrates how to create attributes for the phoneSystemClass. serialNumEntryMode.put(costAttrName. //Create a hash map to hold the attribute data HashMap attributeHashMap = new HashMap().0.1 Creating attributes for your class Every class you create will have attributes that hold different values for each instance of the class. costEntryMode. // Update the BMC Atrium CMDB with the new attributes try { phoneSystemClass. //Associate these attributes to the phoneSystemClass phoneSystemClass. int serialNumFieldId = ACME_SERIAL_NUM_FIELD_ID. serialNumAttr). int serialNumEntryMode = CMDBAttribute. int costEntryMode = CMDBAttribute. costLimit. serialNumLimit. 40 Chapter 3—Programming common BMC Atrium CMDB tasks .setAttributes(attributeHashMap). null). costFieldId. serialNumFieldId.CMDB_ATTR_ENTRYMODE_OPTIONAL. attributeHashMap. //create a Java instance of the Cost attribute CMDBAttribute costAttr = new CMDBAttribute(costAttrName. //Create a default value for the attribute Value serialNumDefaultValue = null. open index. } In the example. and attribute limit details are specified for the Cost attribute. data types. which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. these attributes are added to a hash map.toString()). attribute field ID. respectively. The attribute data type is defined as Currency. The data type and limit for the attribute is defined using the serialNumLimit class variable. A default value of Null is specified for the attribute in the serialNumDefaultValue variable. the serialNumAttr attribute is defined as a character data type with a limit of 30 characters. After the attributes are set in the class. The setAttributes method of the phoneSystemClass is used to set the attributes for the class. serialNumFieldId. Similar to the ACMESerialNumber definition. you must provide a value for this attribute for every instance of the class.html of the Java API Help. which holds the attribute definitions.out. When you specify the Required entry mode for an attribute. the Cost attribute is created to hold the cost information for the phoneSystemClass class. and the entry mode for the attribute. is passed to this setAttributes method as a parameter. Working with configuration item classes and instances 41 . the serialNumAttrName. In the example. The entry mode for the Cost attribute is defined as Optional. In the example. After the attributes for a specific class are defined as CMDBAttribute variables. field ID. After these values are defined for the variables. This value is used if no value is provided for the ACMESerialNumber attribute when creating an instance. which creates a Java instance of the attribute. the class information is updated in the BMC Atrium CMDB using the update method of the phoneSystemClass. The hash map array.println(ex. they are passed as parameters to the CMDBAttribute class constructor. The field ID is a unique numeric identifier for an attribute. which is of type CMDBAttributeLimit class. and data limits. and serialNumEntryMode variables are created to hold the attribute name. For more information about the setAttributes method of the CMDBClass Java class.Developer’s Reference Guide } catch (ARException ex) { System. the attribute name. These hash maps can hold multiple attributes at a time. entry mode. println(ex.Constants.95". datasetId).put(costAttrName.out. Value cost = new Value("12.getId(). attributeHashMap). When you create an instance. serialNum). //Create a HashMap to hold the attribute values Map attributeHashMap = new HashMap(). serialNumAttrValue). costAttrValue). // create an instance of a phoneSystemClass CMDBInstance phoneInstance = new CMDBInstance(phoneSystemClassNameKey.toString()). In the example.DATASET". attributeHashMap. CMDBAttributeValue costAttrValue = new CMDBAttributeValue(costAttrName.BMC Atrium CMDB 2. //create a variable to hold the dataset ID String acmeDatasetId = "ACME.AR_DATA_TYPE_CURRENCY). The serialNumAttrValue and costAttrValue class variables are created of type CMDBAttributeValue. CMDBAttributeValue serialNumAttrValue = new CMDBAttributeValue(serialNumAttrName.create(currentUser. try { //Create the new instance within the BMC Atrium CMDB phoneInstance.put(serialNumAttrName. } catch (ARException ex) { System. you can create an instance of this class. 42 Chapter 3—Programming common BMC Atrium CMDB tasks . The following code illustrates how to create an instance of the phoneSystemClass. attributeHashMap. Example: Creating a CI instance //Create variables to hold the serial number and cost details for the instance String serialNum = "SN-1492-22919".1 Creating a CI instance After you create a class in the BMC Atrium CMDB. the serialNum and cost variables are created to hold the serial number and cost information for the instance.0. cost). } //Get the instance ID of the new instance String phoneSystemInstId = phoneInstance. you must specify all the required attributes for the class. html of the Java API Help. The currentUser and datasetId parameters are passed to the create method of the instance. open index. In the example. you must specify a dataset ID for the instance. In the try loop. the instance ID of the new instance is retrieved using the getId method. which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. a dataset variable is created to specify the dataset to which the instance belongs. The costAttrValue class variable holds the costAttrName and cost details for the instance. the phoneInstance instance is created in the BMC Atrium CMDB. the phoneSystemClassNameKey. and attributeHashMap variables are passed as parameters to the instance. After the instance is created in the BMC Atrium CMDB. Before creating the phoneInstance instance in the BMC Atrium CMDB.Developer’s Reference Guide After the attribute name and other attribute information is created as explained in the previous section. For more information about the parameters for the create method of the CMDBInstance Java class. which was shown in “Creating a CI class” on page 38. the serial number and cost details are added to the phoneInstance instance. which is of type CMDBAttributeValue. Working with configuration item classes and instances 43 . Because an instance must reside in a dataset. the serialNumAttrName and serialNum variables are assigned to the serialNumAttrValue variable. Using a hash map. the acmeDatasetId variable is created that holds the dataset details. To create the new instance in Java. which is of type CMDBInstance. 0. //create the relationship class CMDBRelationship phoneSystemToSocketRelClass = new CMDBRelationship(relationshipClassKey. //Create a variable that holds the two classes that will be related CMDBClassNameKey[] relationshipClasses = {phoneSystemClassKey.1 Working with relationship classes and instances The BMC Atrium CMDB enables you to create relationships between CI classes.setCardinality( CMDBRelationship. null. relationshipClasses). } catch(ARException ex){ System. CMDBClassNameKey relationshipClassKey = new CMDBClassNameKey(relationshipClassName. In the following example. socketClassKey}. Creating a relationship class When defining the relationship class.toString()).create(this. such as the cardinality of the relationship.} 44 Chapter 3—Programming common BMC Atrium CMDB tasks . //create a role name for each instance in the relationship String[] roleNames = {"Source".BMC Atrium CMDB 2. After you create the relationship class. you must create a relationship class that refers to the two CI classes. a relationship class is created between the phoneSystemClass class and the socketClass class.println(ex. for example one-to-many or one-to-one. Example: Creating a relationship class //Create a variable that holds the relationship class name String relationshipClassName = "phoneSystemToSocketRelationship". or whether the class defines a weak relationship. try { // create the relationship class in the BMC Atrium CMDB phoneSystemToSocketRelClass. you create a relationship between the two CI instances using this relationship class. roleNames. //set the cardinality of the relationship phoneSystemToSocketRelClass. you can specify several characteristics for the relationship.CMDB_CLASS_RELATIONSHIP_CARDINALITY_1_MANY). To relate two CI classes. "Destination"}.getARServerUser()).out. acmeNamespace). For example. In this example. 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. the relationshipClassName variable is created to hold the name of the relationship class. Each of the two classes in a relationship must have its role defined.ClassId and Destination. For more information about the parameters for the create method of the CMDBRelationship Java class. open index.ClassId. which of type CMDBRelationship. You can define role names for Class 1 and Class 2. on any CDM relationship class the attributes that hold the class IDs of its member CIs are named Source. which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. The setCardinality method of the CMDBRelationship class sets the cardinality. the phoneSystemToSocketRelClass Java instance of the relationship class is created. which is of type CMDBClassNameKey. the phoneSystemToSocketRelationship relationship class is then created in the BMC Atrium CMDB. the cardinality for the relationship class is set to one-to-many. there can be many relationships to instances of the socket class. After the role name and class name key details are defined. The class name and namespace information for the two classes that will be related in the relationship class is specified in the relationshipClasses variable.Developer’s Reference Guide In the example. A one-to-many cardinality means that for each instance of the phoneSystem class. Working with relationship classes and instances 45 .html of the Java API Help. In the try loop. is created to define the class name and namespace details for the relationship class. The role names for the two classes are specified in the roleNames variable. The relationshipClassKey variable. attrHashMap. An instance of a relationship class defines a specific relationship between two particular instances of two CI classes. new Value(acmeDatasetId)). attrHashMap.create(this.1 Creating a relationship between two CI instances To create a relationship between two CI instances. CMDBAttributeValue srcInstId = new CMDBAttributeValue("Source. srcInstId). new Value(phoneClassId)).getARServerUser()).put(destClassId. CMDBAttributeValue destClassId = new CMDBAttributeValue("Destination. attrHashMap.ClassId". attrHashMap).0. the phoneClassId and the socketClassId variables are already created. // create a Java instance of the relationship class CMDBInstance relInstance = new CMDBInstance(relationshipClassKey.getId().getAttributeName(). Map attrHashMap = new HashMap().InstanceId". representing existing CI instances. new Value(socketClassId)). CMDBAttributeValue datasetId = new CMDBAttributeValue("DatasetId". String socketInstId = newSocket.put(srcClassId. try { //Create an instance of the class within the BMC Atrium CMDB relInstance. srcClassId). Example: Relating two CIs //retrieve the instance IDs for the newPhoneSystem and newSocket instances String phoneInstId = newPhoneSystem. In the following example.put(datasetId. destInstId). attrHashMap.getAttributeName().BMC Atrium CMDB 2.getAttributeName().getAttributeName(). datasetId).put(destInstId. new Value(socketInstId)). attrHashMap.ClassId". destClassId). //create the required attributes of the relationship instance CMDBAttributeValue srcClassId = new CMDBAttributeValue("Source.getId(). The following code illustrates how to create a relationship between two CIs.getAttributeName(). new Value(phoneInstId)). you create a relationship instance. CMDBAttributeValue destInstId = new CMDBAttributeValue("Destination. } 46 Chapter 3—Programming common BMC Atrium CMDB tasks .put(srcInstId. it is assumed that the newPhoneSystem and newSocket variables.InstanceId". For more information about the parameters for the create method of the CMDBInstance Java class. "ReconciliationIdentity".html of the Java API Help. //do not sort CMDB_START_WITH_FIRST_INSTANCE. the phoneInstId and socketInstId variables are created to hold the instance IDs of the newPhoneSystem and newSocket instances. null. The getARServerUser method of the relInstance instance retrieves the user ID that is currently used to log in to the AR System server. which are phoneInstId and socketInstId respectively. phoneSystemClassKey. destination. The Java instance of the relationship class is then created using the constructor of the CMDBInstance class. In the try loop. Example: Querying an instance //Set specific attributes to return String[] attributesToGet = {"InstanceId". The datasetId variable holds the dataset ID of the ACME dataset.DATASET String query = "'DatasetId' = \"ACME. The srcInstId and destInstId variables are created to hold the IDs of the source and destination classes. try { CMDBInstance[] instanceList = CMDBInstance. the relationship instance is created in the BMC Atrium CMDB. The user ID parameter is required to create the instance in the BMC Atrium CMDB. //Specify values for the query to retrieve all instances where DatasetId //is ACME.findObjects( this. and dataset ID variables are written to the attrHashMap array. attributesToGet. open index. These source.getARServerUser(). which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. Working with relationship classes and instances 47 . query. The following code illustrates how to query instances of the phoneSystemClass class.DATASET\"". Retrieving instance details You can query CI and relationship instances that exist in the BMC Atrium CMDB. "DatasetId"}.Developer’s Reference Guide In the example. For more information about the parameters for the findObjects method of the CMDBInstance Java class. open index. and DatasetID attributes from all instances.println(ex.0. 48 Chapter 3—Programming common BMC Atrium CMDB tasks . which is of type CMDBInstance.DATASET. all attributes of the instances will be returned by default. Null).1 CMDB_NO_MAX_LIST_RETRIEVE. } In the example. } catch(ARException ex){ System. The retrieved instances are placed in the instanceList array. the findObjects method of the CMDBInstance Java class is used to retrieve instances. If no attributes are specified to return in the query.out. In the try loop.BMC Atrium CMDB 2. ReconciliationIdentity.html of the Java API Help. The query in this example retrieves the InstanceID. the attributes to retrieve in the query are specified in the attributesToGet array of type String.toString()). which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. The query variable specifies a qualification that will retrieve all instances where the dataset ID is ACME. The following topics are provided: ! ! ! ! ! ! ! ! ! Working with the cmdbdriver program (page 50) Migrating data between BMC Atrium CMDB servers (page 53) Using the extension loader (page 61) Integrating the CI Relationship Viewer with other applications (page 70) Configuring the CI Relationship Viewer (page 77) Creating CMDB status alerts (page 85) Importing data with EIE (page 86) Working with SQL views (page 87) Debugging BMC Atrium CMDB API programs (page 88) BMC Atrium CMDB tools 49 .Chapter 4 BMC Atrium CMDB tools This chapter describes how to use the various BMC Atrium CMDB tools. see Chapter 5. ! ! UNIX ! ! Navigate to /usr/arsystem/<server_name>/cmdb/api/bin. such as class. 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\<server_name>\Remedy CMDB\api\bin. use leading zeros to see the entry ID of those entries. You can then use the cmdbdriver commands to call any number of API functions.” to enter the appropriate values for the function parameters. “C API functions and data structures.BMC Atrium CMDB 2. instance. The parameters that are required for cmdbdriver commands are the same as the parameters that are required for the equivalent C API functions. and attribute data manipulation.exe. When you are working with the specific commands. “C API functions and data structures. Figure 4-1 on page 51 displays the list of tasks that you can perform with the cmdbdriver program. If you are working with specific entries.1 Working with the cmdbdriver program The cmdbdriver program.0.” From the command line Once you compile the source code or locate the prebuilt program supplied with the API. the system displays the list of cmdbdriver commands. Type the command cmdbdriver. Double-click cmdbdriver. enables you to execute various BMC Atrium CMDB API functions from a command line. For more information about API functions and their parameters. which prompts you one at a time for parameters to each command you type. see Chapter 5. When you execute the program. you are ready to use the cmdbdriver program. 50 Chapter 4—BMC Atrium CMDB tools . You must provide the necessary login information and perform initialization operations for connecting to the BMC Atrium CMDB. type impdf at the prompt. Type the name of your server.Developer’s Reference Guide Figure 4-1: Initial screen of cmdbdriver 2 Initialize an API session with the init command. For example. Working with the cmdbdriver program 51 . type e or q to exit the program. 4 Type the abbreviation of the function and provide the appropriate input parameter values. for importing class definitions. Use the help command (h or ?) to display the cmdbdriver commands. You are prompted to specify several parameters one at a time. the command prompt appears. You must enter the following parameters: ! ! Type a valid user name and password. 3 Specify the login parameters with the log command. You can skip the other parameters. After you specify the login parameters. When you are finished using the cmdbdriver. The last line of the example accepts the default value for the Metadata. The rec command starts recording the commands you use at the prompt and srec stops recording these commands.1 Using a script You can also use a script file that contains the cmdbdriver commands and execute it at the cmdbdriver prompt. To make these libraries available to cmdbdriver. Using cmdbdriver on UNIX The cmdbdriver program uses shared code libraries in the bin subdirectory of the BMC Atrium CMDB installation directory.BMC Atrium CMDB 2. After you record the commands in a file.CORE namespace. you are prompted for the name of the file in which to store these commands. When you type the rec command. you can execute it at the cmdbdriver program using the execute command. Example: cmdbdriver script file imp 1 BMC. 52 Chapter 4—BMC Atrium CMDB tools . the directory is located in /usr/arsystem/<server_name>/cmdb/bin. By default. These libraries are not available to it by default in UNIX environments. Instance data <1-2> parameter.CORE BMC_BASEELEMENT This example uses a script to import the BMC_BASEELEMENTclass from the BMC. You can create this script file using any text editor. The default for this parameter is set to 1 (metadata). add the bin subdirectory to your LD_LIBRARY_PATH environment variable either permanently or by using the export or setenv command.0. To accept a default value for a parameter in the cmdbdriver script. insert a blank line. such as Notepad or Wordpad. You can use the rec and srec commands of the cmdbdriver program to record cmdbdriver commands. such as Remedy Asset Management. The most common reason to migrate data from one BMC Atrium CMDB to another is to move your BMC Atrium CMDB into production.Developer’s Reference Guide 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. see “Known issues” on page 61. The following procedure explains the steps to migrate from a BMC Atrium CMDB development server to a BMC Atrium CMDB production server. make sure both your BMC Atrium CMDB servers are configured and running. Step 4 Import instance data with cmdbdriver (see page 58). You can use cmdbdriver scripts to perform some of these steps. See the documentation and white papers for your applications to find the appropriate migration instructions. attributes. Step 3 Import class data with cmdbdriver (see page 57). Step 2 Export instance data with cmdbdriver (see page 56). Migrating the BMC Atrium CMDB in such cases requires additional steps beyond migrating a base installation of the BMC Atrium CMDB. Before migrating your BMC Atrium CMDB data. or workflow. these applications might have extended the BMC Atrium CMDB by adding classes. Migrating data between BMC Atrium CMDB servers 53 . Note: If you have other BMC Software applications installed on your development server that access the BMC Atrium CMDB. Step 6 Import reconciliation information with BMC® Remedy® Import (see page 60). 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 55). For information about known issues regarding the procedure explained in this section. Step 5 Export reconciliation information with BMC® Remedy® User (see page 59). Those steps are not covered in this section. forms. Prior to BMC Atrium CMDB 1. 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\<server_name>\Remedy CMDB\api\bin. type e or q to exit the program. After you specify the login parameters the command prompt appears. 2 Type the command init to initialize the driver.0. Double-click cmdbdriver. Type the command cmdbdriver. the driver program was named osdriver. ! ! UNIX ! ! Navigate to /usr/arsystem/<server_name>/cmdb/api/bin. You are prompted to specify several parameters one at a time. For example. When you are finished using the cmdbdriver.exe. for importing class definitions.1 Logging in to the cmdbdriver program The cmdbdriver program is the command-line interface to the BMC Atrium CMDB C API. 54 Chapter 4—BMC Atrium CMDB tools . Use the help command (h or ?) to display the cmdbdriver commands. 3 Type the command log to log into your development server. 4 Type the abbreviation of the function and provide the appropriate input parameter values. You must enter the following parameters: ! ! Type a valid user name and password.The following steps describe the procedure to start the cmdbdriver program. You can leave the other parameters blank. Type the name of your server.BMC Atrium CMDB 2. type impdf at the prompt.1 Patch 002. To export definitions for a specific class. The definitions for the classes and their subclasses are saved to the specified directory as XML files. 5 At the Export Classes prompt. all the subclasses for the superclass will also be exported with it. for example. Migrating data between BMC Atrium CMDB servers 55 . This class data is also called metadata. type 2 at the Export Classes prompt.Developer’s Reference Guide Step 1—Exporting class data with cmdbdriver If you have added or changed any CI or relationship classes on your development server. you can skip Step 1 and import the class definitions using the steps explained in “Step 3—Import class definitions with cmdbdriver” on page 57. 4 Specify the file name in which to store the exported definitions. you will be prompted for additional parameters. Make sure you specify the exact path for the file name. type 1 to export all classes and their subclasses. You need to export only those classes that you have added or changed. When you export a superclass that you modified. If you have not made any additions or changes. and their subclasses. because it describes the instance data in the BMC Atrium CMDB. 2 Start the cmdbdriver program and specify your user credentials. see “Logging in to the cmdbdriver program” on page 54. c:\ExportedClassDefinitions. If you specify a file name that already exists. When you type option 2. For more information about logging in to the cmdbdriver program. To export definitions for a class and its subclasses 1 Log in to your development server. the contents of the file will be overwritten. 3 Type the xexpdf command to export all class definitions from the BMC Atrium CMDB. you need to export them. see “Logging in to the cmdbdriver program” on page 54. 4 Type the file name in which to store the exported instance data. 6 At the Dataset ID prompt. 56 Chapter 4—BMC Atrium CMDB tools . If you specify a file name that already exists. the contents of the file will be overwritten. The instance data for the classes is saved to the specified directory as an XML file. c:\ExportedInstanceData. Make sure you specify the exact path for the file name. For more information about starting the cmdbdriver program.0. When you type option 2. type 1 to export instance data for all classes and their subclasses.1 Step 2—Export instance data with cmdbdriver You must export both CI and relationship configuration data from your development server. type 2 at the Export Instances from prompt. you will be prompted for additional parameters. Tip: If you export all your instance data to the same directory. 3 Type the xexpdt command to export instance data from the BMC Atrium CMDB.BMC Atrium CMDB 2. To export instance data for a class 1 Log in to your development server. type the dataset ID from which to export the instance data. 2 Start the cmdbdriver program and specify your user credentials. for example. it can later be imported in one step. To export instance data for a specific class. 5 At the Export Instances from prompt. to your production server. and BMC_BaseElement respectively. For more information about logging in to the cmdbdriver program. 4 Specify the directory path where the import data is located. type 1 for the Number of Import Items. 5 To import all class definitions contained in the source folder (recommended). you cannot automatically import the subclasses of a specified class. To import class definitions 1 Log in to your production server. Migrating data between BMC Atrium CMDB servers 57 . see “Logging in to the cmdbdriver program” on page 54. To import attributes for the class. run the impdf command again and type 2 at this prompt.CORE. for example. Each subclass must be specified as a separate import item. such as c:\ExportedClassDefinitions.Developer’s Reference Guide 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. BMC. 3 Type the impdf command to import class definitions into the BMC Atrium CMDB. To import definitions for a specific class. accept the default value of 1. 2 Start the cmdbdriver program and specify your user credentials. 6 To import a class from the source folder. type the namespace and class name for the class. Use the steps explained in this section to migrate the class definitions to the production server. Note: When you enter a number other than 0. accept the default of 0 and skip to step 8. 8 Accept the default value of 1 to import Metadata. either by increasing the number you specify here or by running the impdf command multiple times. 7 At the Class Name prompt. ! 4 (New Id for all)—Create 5 Type the directory path where the import data is located. The data is imported into the BMC Atrium CMDB. see “Logging in to the cmdbdriver program” on page 54. to your production server. 3 Type the impdt command to import instance data into the BMC Atrium CMDB. the existing data for a given ! 2 (Replace with new ID)—Overwrite instance. 4 Type any of the following import options to specify the action to take when an instance to be imported has the same InstanceId as an existing instance in the BMC Atrium CMDB: ! 1 (Error)—Write an error message and do not import the instance. a new ID for every duplicate instance. ! 3 (Merge)— Merge the new instance and the existing instance. for example. 2 Start the cmdbdriver program and specify your user credentials. the program generates an error. If this class already exists. For more information about logging in to the cmdbdriver program. Step 4—Import instance data with cmdbdriver You must import the CI and relationship instances from the export files. c:\ExportedInstanceData.1 9 Type any of the following import options: ! 1 (Create)—Create the specified class in the BMC Atrium CMDB. 58 Chapter 4—BMC Atrium CMDB tools . The definition is imported and each class name is displayed. To import instances of a class or classes 1 Log in to your production server.BMC Atrium CMDB 2. ! 2 (Overwrite)—Overwrite the existing class in the BMC Atrium CMDB.0. which contain the class and instance data you exported in Step 1 and 2 of this procedure. Each dialog requires you to enter an export filename for a particular definition. several file dialogs might appear. DatasetMergePrecedenceSet—Selected Dataset Merge Precedence sets and the definitions used by them.0: Form and Application Objects guide. For more information about AR Export files.arx). Dataset—All datasets. You can export reconciliation definitions either using BMC Remedy User or a browser. Precedence groups. and so on. For example. You can export all your reconciliation definitions.rep). ! ! Migrating data between BMC Atrium CMDB servers 59 . plus all the rulesets in those activities. 2 Click the Reconciliation Manager tab and choose the Export Definitions link from the left navigation pane. When exporting definitions from a browser.csv).xml) format. 3 Select an Export Type: ! ! ! Everything—All definitions. Note: Due to the browser limitation. depending on the definitions you export. open the CMDB Console. report (. if you select a job.Developer’s Reference Guide Step 5—Export reconciliation definitions In version 2. or select one or more definitions of a certain type. and Workflow Execution groups and the definitions used by them. Any definitions used by those you select are also exported. The definitions can be stored in either AR Export (. Job—Selected jobs and the definitions used by them.0. comma-separated values (. see the BMC Remedy Action Request System 7. Group—Selected Identification groups. Qualification groups. To export reconciliation definitions 1 Using BMC Remedy User. you can export reconciliation definitions from one server and import them onto another server instead of manually recreating all your definitions. the export will include that job plus all the activities in it. the recommended method is to use BMC Remedy User for exporting reconciliation definitions. or XML (. The definitions are exported. For more information about the extensions for the export definitions file. Step 6—Import reconciliation definitions You import reconciliation definitions by using the BMC Remedy Import command-line interface (CLI). 6 Click Export. 60 Chapter 4—BMC Atrium CMDB tools . You can use any of the approved extensions for the file name. the file is placed in or under the BMC Remedy User application folder.BMC Atrium CMDB 2. For more information about these topics. 5 Type the fully qualified File Name to which the definitions should be exported. click the Options tab and select Include Associations. 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. If you include no path or a relative path. To do this.0.0: Integrating with Plug-ins and Third-Party Products guide. see the BMC Remedy Action Request System 7. If your Export Type is Group. The default directory is c:\Program Files\AR System. Note: Before using the CLI on UNIX for the first time. you have the option of also exporting the activities that reference your selected definitions. To import reconciliation definitions 1 Open a command prompt. you must add an entry to your library path. select the definitions to be exported.1 4 If you selected either Job. 2 If using Windows. change to the directory where BMC Remedy Import and other AR System clients are installed. see “Step 5—Export reconciliation definitions” on page 59. Group. or DatasetMergePrecedenceSet. see the Concepts and Best Practices Guide. 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. For more information about importing data into AR System forms. You use the extension loader either to extend the BMC Atrium CMDB or to install an extension pack. Known issues These issues can occur when performing the migration procedures in this section. You must delete the existing weak member before you can import it. When importing the weak member in a weak relationship. Specifying a log file is optional. see the BMC Remedy Action Request System 7. specify the full path to the file containing the exported definitions from the procedure “To export reconciliation definitions” on page 59. ! When exporting or importing instances for a categorization class. since abstract classes cannot have any instances. such as existing data with duplicate entry IDs. There is no reason to do this. For information about the guidelines for extending the CDM. However. you will receive an error if that instance already exists. The extension loader program can also install objects other than the data model extensions. When you attempt to export instance data from an abstract class.0: Configuring guide. Using the extension loader 61 . but recommended in case there are any errors with the import. cmdbdriver crashes. this guide covers only the instructions for installing class and attribute extensions. ! ! Using the extension loader The cmdbExtLoader program enables you to install one or more of BMC Atrium CMDB classes from one server to another.Developer’s Reference Guide 3 Enter the command: arimportcmd -x <server_name> -u <user_name> -p <password> -o <import_file> -l <log_file> For <import_file>. xml file. and one or more class XML files.exe).BMC Atrium CMDB 2. you create an extensions directory. Each extension subdirectory contains a package. as displayed in Figure 4-2. After you copy the extension loader files into the extension loader directory you created.1 The extension loader directory structure The directory structure of the extension loader program is displayed in Figure 4-2. The extensions directory can contain one or more extension subdirectories. 62 Chapter 4—BMC Atrium CMDB tools .0. If you specify any other name for this directory. one each for UNIX (no extension) and Windows (. for example. an installation activity file. and two cmdbExtLoader executables. Under the CMDBExtensionLoader directory is the common folder. Figure 4-2: Extension loader directory structure At the top level is the directory where you copy the extension loader files. Note: You must name the directory that contains the extension subdirectories as extensions. CMDBExtensionLoader. These class files are obtained when you use the expdf command of the cmdbdriver program to export the class or attribute definitions. the extension loader will not recognize it. Step 3 Create an installation activity file (see page 67). the 650-EXClass subdirectory will be installed first. ! <name> is an alphanumeric name for the extension. Using the extension loader 63 . Therefore. For example. Examples of extension subdirectory names are 500-EXClass and 501-EXAtt. if you have two extension subdirectories. you must specify a lower <install-order> for the object that you want to install first. 650-EXClass and 655-EXClass. Make sure you do not use spaces.xml file (see page 64). The <install-order> instructs the extension loader to install the objects in the extensions directory in ascending order. or wildcard characters in the <name> element. Step 4 Start the cmdbExtLoader program (see page 69). 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 64).Developer’s Reference Guide The following naming convention is used for extension subdirectories: <install-order>-<name> where: ! <install-order> is a three-digit number ranging from 000 to 999. Step 2 Create the package. quotation marks. To export class definitions 1 Create an extension subdirectory. This directory will contain all the extension loader files. it stores the extension registration values that you specify in the package. you must export your class or attribute definitions. see “Step 1—Exporting class data with cmdbdriver” on page 55. 2 Export the class definitions using the cmdbdriver expdf command. you can only change the version number to update the extension. When the extension loader runs. such as the extension name. Step 2—Create the package.1 Step 1—Export the class definitions using the cmdbdriver Before you create the extension package. The GUID will remain the same for the life span of an extension.xml file The package. The registration information defines the extension that you are creating. This ID is used by the extension loader program to determine if an extension is already installed. and globally unique identifier (GUID) in the SHARE:Application_Properties AR System form. A GUID is a unique ID for the extension.xml file contains the registration and dependency information for the extension.xml file. 64 Chapter 4—BMC Atrium CMDB tools . See “The extension loader directory structure” on page 62. The expdf command creates several XML files that contain the class definition information for the specified class.0. version. For more information about exporting class definitions with the cmdbdriver program. After you create an extension with a specific GUID.BMC Atrium CMDB 2. Requires CMDB --> <cmdb> <guid>OB00C04FA081BABZlxQAmyflAg1wEA</guid> <name>BMC Atrium CMDB</name> <minversion>2.xml example instructs the extension loader program to install the ComSys Hardware Component class extension version 1. Note: When you specify a GUID for the BMC Atrium CMDB dependency in your package. The first line of code is an xml version tag that is required for all XML files. see “Logging in to the cmdbdriver program” on page 54. make sure you use the same GUID as shown in the example.This extension adds a class.0</minversion> </cmdb> </applications> </dependencies> </package> This package. skip to step 2. For more information about using the cmdbdriver program.0 on the BMC Atrium CMDB application version 2.0" standalone="yes" ?> <package> <!-.xml file.xml file 1 Depending on whether you are creating a new extension or modifying an existing extension. If you are modifying an existing extension.Developer’s Reference Guide Example: package. generate a GUID using the cg command of the cmdbdriver program.--> <name> ComSys Hardware Component</name> <guid>OS005056C0000898YWQgUsMLAAKwAA</guid> <version>1. ! Using the extension loader 65 .xml <?xml version="1. This is the GUID stored in the SHARE:Application_Properties AR System form for the BMC Atrium CMDB.0</version> <dependencies> <applications> <list>cmdb</list> <!-.0. perform one of the following steps: ! If you are creating a new extension. To create the package. For new extensions. ! <version>—The version number of the application specified in the <application> element. which indicate the range of permissible version numbers for the application.1 2 Specify values for the following elements in the package.” 66 Chapter 4—BMC Atrium CMDB tools . The applications specified here can be other extensions. 3 Save the package.BMC Atrium CMDB 2.xml file under the extension subdirectory you created in “Step 1—Export the class definitions using the cmdbdriver. which indicates the exact version number required for the application. You can either specify a value for the <version> element. or you can specify values for the <minversion> and <maxversion> elements. specify the currently existing GUID. ! <version>—The version number for the extension. GUID for the extension. specify the GUID that you created in step 1.xml file: ! Registration information—Specify the following registration information for the extension: ! <name>—The ! <guid>—The name for the extension. or the AR System Server on which you want to install the extension. For existing extensions. Modify the version number only if you are modifying an extension. AR System applications.0. ! Dependencies—Specify the following dependency information for the extensions: ! <applications>—The applications that the extension depends upon. Every installation activity file you create must contain the oout and cout commands. such as importing or exporting class definitions. Using the extension loader 67 . After the script stops executing the activity file. 650-EXClass and 655-EXClass. The oout command instructs the extension loader to log the script actions. You must specify the OSDriver. to save the script actions. Based on the activity description provided in the 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. Therefore. The cout command closes the log entry file. or wildcard characters in the <name> element. the extension loader performs a specified task. the 650-EXClass subdirectory will be installed first. For example. The options for the <type> parameter include: ! ! ! ! ! ! IMP—Import data into an AR System form ARD—AR System driver script OSD—cmdbdriver script RIK—Remedy Installation Kit ! <suffix> is the file extension for the installation activity file. <name> is an alphanumeric name for the extension. and OSD) can be of any type such as txt. An installation activity file uses the following naming convention: <install-order>-<name>-<type>. <type> instructs the extension loader to perform an action based on a specific value. you must specify a lower installorder for the object that you want to install first.txt. as illustrated in the example. The installorder instructs the extension loader to install the objects in the Extensions directory in ascending order. if you have two extension subdirectories.out output filename with the oout command. Do not use spaces. quotation marks. the extension loader reads these log comments to verify whether the script execution was successful.Developer’s Reference Guide 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. ARD.<suffix> where: ! <install-order> is a three-digit number from 000 to 999. An example of an activity file name is 500-CLASS-OSD. make sure you use the DostoUnix command to convert the file from Windows format to UNIX before you run it. To create an installation activity file 1 Open an empty file in a UNIX text editor. You must create the activity file in UNIX format for running it on the UNIX platform. such as the vi text editor.BMC Atrium CMDB 2.1 Example: Activity file oout OSDriver. the class definitions for the Test class will be imported. for example. If you specify any other file name. 68 Chapter 4—BMC Atrium CMDB tools . cout term q //activity type // Number of class or instance defintions to import // Class name // Namespace // metadata or instance data choice. You must specify the oout command and the OSDriver. Important: If you create the activity file in Windows format. Important: You must name the output file for the oout command as OSDriver.0. the extension loader program generates an error. You can specify multiple cmdbdriver commands in your activity file. The extension loader program generates an error if you skip this line in the activity file.out imp 1 TEST SampleClass 1 .out output file for the activity script.out. 2 Type oout and OSDriver. such as ARD or OSD. When the extension loader executes the activity file shown in this example. 3 Specify the type of activity the extension loader must perform. your script file can contain both export and import commands.out output file name in the beginning of the file as shown in the previous example. 1 indicates metdata. ” 7 Save the activity file under the extension subdirectory you created in step 1 with an xml. 5 Specify the class name and namespace for the OSD activity. or any other type of extension. For more information about the activity file extensions. your extensions are installed in the BMC Atrium CMDB. depending on the activity type. which were created when you exported your classes using the cmdbdriver program. you can the start the extension loader program. start the cmdbExtLoader program using the following steps.xml file. see “Working with the cmdbdriver program. After you complete the installation.exe. and the XML files. which guides you through the installation process. Step 4—Start the cmdbExtLoader program After your extension subdirectory package is ready with all the required files. The Extensions subdirectories will now contain a package. To start the cmdbExtLoader program ! From the directory in which you installed the extension loader program. see “Step 3—Create an installation activity file” on page 67. UNIX—Double-click cmdbExtLoader file with no extension.Developer’s Reference Guide 4 Specify the number of class definitions or instance data objects you want to export or import. Using the extension loader 69 . based on your platform: ! ! Windows—Double-click cmdbExtLoader. 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. The extension loader installation wizard appears. For more information about the cmdbdriver program. an installation activity file. txt. In this method. 70 Chapter 4—BMC Atrium CMDB tools . which is installed within the CMDB. This is a quick and easy way to integrate the CI Relationship Viewer with your AR System application. the CI Relationship Viewer field is embedded in the AR System application itself (see page 73). (see page 75). Embed CI Relationship Viewer in AR System applications. see the User’s Guide. you can launch the CI Relationship Viewer form. For information about using the CI Relationship Viewer to view instance relationships from the CMDB Console. 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.BMC Atrium CMDB 2.0. you can launch the CI Relationship Viewer directly using a browser. using AR System workflow (see page 71). ! ! Non-AR System applications ! Launching the CI Relationship Viewer from non-AR System applications. In this method. In this method. 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.1 Integrating the CI Relationship Viewer with other applications The CI Relationship Viewer graphically displays the relationships between existing CIs. Table 4-1 lists the parameters required to launch the CI Relationship Viewer form from other AR System applications. For more information about creating active links. To launch the CI Relationship Viewer from AR System applications 1 With BMC® Remedy® Administrator. You must specify the initialization parameters. The BMC Atrium CMDB application ships with one or more default filters. Integrating the CI Relationship Viewer with other applications 71 . You can also create additional filters to suit your needs. The class name to which the instance belongs.Developer’s Reference Guide Launching the CI Relationship Viewer from AR System applications When you launch the CI Relationship Viewer form from other AR System applications. These filters enable you to specify qualifications for the instances you want to view. The Instance ID of the CI for which the relationship data will be displayed. specify details. such as the Form Name and Execute On criteria. The filter name for the CI Relationship Viewer. and CI ID of the CI for which the relationship data will be displayed. such as Dataset ID. see the BMC Remedy Action Request System 7. 2 On the Basic tab. Filters. Table 4-1: CI Relationship Viewer parameters—AR System applications Parameter name Namespace Class Name CI ID Dataset ID Filter Name Description The namespace to which the instance belongs. The ID of the dataset where the instance resides. The properties for the active link are displayed in a tab form. the BMC Atrium CMDB performs the initialization function for the CI Relationship Viewer. log in to the BMC Atrium CMDB server and create a new active link for launching the CI Relationship Viewer.0: Workflow Objects guide. 0. 72 Chapter 4—BMC Atrium CMDB tools . select New. From the Window Type list. select Search.BMC Atrium CMDB 2.1 Figure 4-3: Setting CI Relationship Viewer parameters 3 On the If Action tab. From the Target Location list. specify the following details: ! ! ! From the New Action list. Note: Launching the CI Relationship Viewer from AR Systems does not support the Current option for the Target Location list. select Open Window. specify the parameters listed in Table 4-1 on page 71. ! From the Definition Name list. open the form in which you want to embed the CI Relationship Viewer. Select Default if you did not create any customized definitions. For more information about creating definitions.Developer’s Reference Guide ! ! From the Form Name list. Integrating the CI Relationship Viewer with other applications 73 . click the Save icon. see “Creating a definition for the CI Relationship Viewer” on page 82. To embed the CI Relationship Viewer in your AR System form 1 Using BMC Remedy Administrator. select the data visualization definition you created for the CI Viewer. 4 Click Add Action. 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. specify permissions for the active link. select CI Viewer. select CMDB:CIViewer. set the following Data Visualization field properties: ! From the Module type list. 2 Place a Data Visualization field on the form and double-click it to open the Field Properties tab. specify a name for the Data Visualization field in the Name text box. Your active link is now saved. 4 On the Database tab. In the Field Mapping section. 3 On the Advanced tab. 6 On the BMC Remedy Administrator toolbar. 5 On the Permissions tab. Embedding the CI Relationship Viewer in AR System applications Use the following procedure to embed the CI Relationship Viewer in your AR System form. select the name of the Data Visualization field you created. datasetid. 7 Click Save to save the active link.0.filtername=") + “Components and Dependencies” ! ! In the example.classname=") + $Class Name$) + ".BMC Atrium CMDB 2. classname. Important: The namespace. set the required parameters for launching the CI Relationship Viewer.1 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. such as $Namespace$ and $Class Name$ are based on the field names of a form. for example: (((((((( "namespace=" + $Namespace$) + ". 74 Chapter 4—BMC Atrium CMDB tools . 6 Click Add Action to save the settings for the action. instanceid.datasetid=") + $Dataset ID$) + ". select the form name. In the Value field. You might also specify string values as shown in the example. From the Read Value for Field From list. You need to provide these field names as you have specified in your form. From the Form Name list. and filtername parameters are CI Relationship Viewer-defined keywords. select the form name on which the data visualization field is placed. the field names. select Set Fields. ! On the If Action tab: ! ! From the New Action list. From the Name list.instanceid=") + $CI ID$) + ". constants. The CMDB application ships with one or more default filters. you must specify the initialization parameters for the viewer in the URL format. The dataset from where the instance data will be selected. To launch the CI Relationship Viewer from a non-AR System application. In the URL for launching the CI Relationship Viewer. These filters enable you to specify qualifications for the instances you want to view. These IDs are fixed values for the initialization parameters. The Instance ID of the CI for which the relationship data will be displayed. The filter name for the CI Relationship Viewer. You can also create additional filters to suit your needs. The class name to which the instance belongs. indicate the field ID on the CI Relationship Viewer form. Table 4-2 lists the parameters and field ID mappings that are required to launch the CI Relationship Viewer form. Table 4-2: CI Relationship Viewer parameters—non-AR System applications Field ID F49000110f0 F400109900 F431400000 Parameter name Namespace Class Name CI ID Description The namespace to which the instance belongs.Developer’s Reference Guide Launching the CI Relationship Viewer from non-AR System applications You can launch the CI Relationship Viewer directly from any nonAR System applications using a browser. such as F490001100. F431400001 F431400003 Dataset ID Filter Name Integrating the CI Relationship Viewer with other applications 75 . BMC Atrium CMDB 2. The BMC Remedy Action Request System login screen appears. Figure 4-4: CI Relationship Viewer—From a browser 76 Chapter 4—BMC Atrium CMDB tools . <datasetid>. and <filtername>. <ciid>. 2 Press Enter. and click Log In.0. <arserver>. <namespace>. 3 Type a user name and password in the login screen. <classname>.1 To launch the CI Relationship Viewer from a browser 1 Open a browser and type the following URL in the address field: http://<midtier>/arsys/apps/<arserver>/AtriumCMDBConsole/ CMDB:CIViewer?F490001100=<namespace>&F400109900=<classname>&F43140000 0=<ciid>&F431400001=<datasetid>&F431400003=<filtername> Make sure that you specify appropriate values for placeholders. such as <mid tier>. The CI Relationship Viewer window appears as shown in Figure 4-4. The BMC Atrium CMDB ships with two default filters—All and Components and Dependencies. These filters are useful when retrieving large amounts of class and relationship data. For more information about creating filters. create various events. status. see the Installation and Configuration Guide. Although the CI Relationship Viewer provides a default configuration file (config. Working with filters The CI Relationship Viewer enables you to define filters for retrieving relationship information to generate a graphical relationship map. and view relationships up to any number of levels from the root CI. specify font size and color. You can filter class and relationship data by CI class types.Developer’s Reference Guide Configuring the CI Relationship Viewer You can configure the CI Relationship Viewer to restrict the relationships displayed by number of levels. relationship types. you add it as an attachment to the CI Relationship Viewer definition. which is an entry in the Data Visualization Definition form. After you create a configuration file. You can create custom filters using the Manage Filters link on the CMDB Console.xml) that contains standard settings for the viewer. filters provide a way to limit the items that are shown in the graph. and display a context menu that enables you to perform various actions based on the menu selection. Customizing the configuration file The settings that specify the visual and display definitions for the CI Relationship Viewer are encapsulated in a configuration file. As you can view relationships up to any number of levels from the root CI. you can create a custom configuration file to suit your needs. You customize the CI Relationship Viewer settings using the following steps: ! ! “Creating a configuration file” on page 78 “Creating a definition for the CI Relationship Viewer” on page 82 Configuring the CI Relationship Viewer 77 . If the action attribute for any menu item is set to CIRV_NOTIFY_AR. see Appendix B. and color settings for the CI Relationship Viewer. The following example specifies the format for defining a menu item: Example: Menu item definition <menuitem id="MNU_ID1" text="item1" action="action1" enabled="false"/ > Where: ! id—Uniquely ! text—The identifies the menu item. You can create submenus up to any number of levels. A separator does not have the text and action attributes. the default value of true is accepted. If you do not define this attribute. For more information about the CI Relationship Viewer events. then the ID of the menu item is passed to the container AR System form in the event type parameter.0. The following example shows a submenu definition: Example: Submenu definition <submenu id="SUBMENU_ID1" text="sub menu1"> <menuitem id="MNU_ID1" text="item1" action="action1"/> <menuitem id="MNU_ID2" text="item2" action="action2"/> </submenu> You can create separators between the menu items to apply a context for them.” ! enabled—Used to enable or disable the menu item. The following example shows a menu separator: Example: Menu separator <menuitem id="MNU_SEPARATOR"/> 78 Chapter 4—BMC Atrium CMDB tools . “Finding related CIs using graph queries. ! action—Specifies the action that will be performed when the user selects the menu item. launch in context.1 Creating a configuration file This section explains how to create a custom configuration file. such as the context menu that displays various menu options. which includes settings. CIRV_NOTIFY_AR. The action attribute can contain JavaScript code or one of the predefined event types. Enter a meaningful name for this attribute.BMC Atrium CMDB 2. for example. text string for the menu that will be displayed in the CI Relationship Viewer. Note: Do not add any menu items for the SUBMENU_LAUNCH menu option in the configuration file. Table 4-3: Menu items and their functions Action value MNU_SET_AS_ROOT MNU_SEPARATOR MNU_LAYOUT_TREE MNU_LAYOUT_RADIAL MNU_SHOW_LEGEND MNU_REFRESH SUBMENU_LAYOUT SUBMENU_LAUNCH Function Sets the currently selected CI as root Separator Tree Layout Radial Layout Show/Hide Legend Refreshes the Relationship Graph Submenu for showing the layouts Submenu for showing the items for Launch in Context Text displayed in the CI Relationship Viewer Set as Root A line Tree Radial Show/Hide legend Refresh Layout Launch in Context SUBMENU_LAUNCH is a special menu type that is used for adding menu items for launching federated data in context. Configuring the CI Relationship Viewer 79 . Table 4-3 lists the menu or submenu items of the CI Relationship Viewer along with their functions. the menu items will be dynamically added to SUBMENU_LAUNCH at run time. 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. menu items for all applicable federated interfaces are automatically displayed. Note: The menu items listed in Table 4-3 are displayed in the context menu by default. Based on the federation definitions. To hide any of submenus in the context menu pop-up. If a SUBMENU_LAUNCH menu item is included in the configuration file. modify the config.xml file or create a custom configuration file.Developer’s Reference Guide The CI Relationship Viewer predefines a set of standard menu items for the applications that use the viewer. which launches the CI Relationship Viewer in a browser. The default option for the Launch in Context submenu in the CI Relationship Viewer is CI Viewer. If the color for a specific relationship type is not defined. width text The color scheme for the different relationship types should be placed inside the <link> tag. <contextmenu> element tags respectively.1 The configuration. When used in the link element. The text to display in the legend. it represents the default width. and context menu information must be placed within the <config>. Table 4-4: Context menu style attributes. 80 Chapter 4—BMC Atrium CMDB tools . it represents the default color. The width of the link.BMC Atrium CMDB 2. as defined in the parent XML element. The color for the links. Style attribute name fontSize nodeSize fill Description The font size for the CI labels. The default icon size for CI representation. <style>. the default values for the color and width tags will be used. When used in the link element. style.0. Table 4-4 explains the various style attributes for the CI Relationship Viewer context menu. xml example.f"> <link fill="#000000" width="1"> <BMC_Component text="Component" fill="#6C8A28"/> <BMC_Dependency text="Dependency" fill="#9E0000"/> <BMC_ElementLocation text="Element Location" fill="#0069A5"/ > <BMC_MemberOfCollection text="Member of Collection" fill="#1B2837"/> </link> </style> <contextmenu> <menuitem id="MNU_VIEW" text="View" enabled="false"/> <menuitem id="MNU_SET_AS_ROOT" text="Set as Root" enabled="false"/> <menuitem id="MNU_SEPARATOR"/> <submenu id="SUBMENU_LAUNCH" text="Launch in Context" enabled="false"/> <menuitem id="MNU_SEPARATOR"/> <submenu id="SUBMENU_LAYOUT" text="Layout"> <menuitem id="MNU_LAYOUT_TREE" text="Tree"/> <menuitem id="MNU_LAYOUT_RADIAL" text="Radial"/> </submenu> <menuitem id="MNU_SHOW_LEGEND" text="Show/Hide Legend"/> <menuitem id="MNU_SEPARATOR"/> <menuitem id="MNU_REFRESH" text="Refresh"/> </contextmenu> </config> When you create a configuration file with the code explained in the config.xml file <config> <style fontSize="10" nodeSize="35.Developer’s Reference Guide Example: config. the context menu shown in Figure 4-5 is displayed in the CI Relationship Viewer. Figure 4-5: CI Relationship Viewer context Menu Configuring the CI Relationship Viewer 81 . For more information about creating a configuration XML file. open the Data Visualization Definition form in Search mode.BMC Atrium CMDB 2.1 Creating a definition for the CI Relationship Viewer This section explains how to attach a configuration file to a CI Relationship Viewer definition. To create a CI Relationship Viewer definition 1 In BMC Remedy User. This definition is created using the Data Visualization Definition form.0. as displayed in Figure 4-6 on page 83. After you create a definition for the custom configuration file. You create a definition for the CI Relationship Viewer to apply the settings you specified in the custom configuration file. 82 Chapter 4—BMC Atrium CMDB tools . 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. 2 Click Search on the form toolbar. see “Customizing the configuration file” on page 77. All existing Data Visualization Definition entries are listed in the results pane. The field values are copied to a Data Visualization Definition window in New mode.Developer’s Reference Guide Figure 4-6: Data Visualization Definition form 3 In the results pane. 4 Choose Edit > Copy to New. The default definition is displayed. Configuring the CI Relationship Viewer 83 . You can now modify the fields before saving the new definition. select the entry with a Definition Name of Default. see Appendix A. drag it into the Complex Definition attachment field. refreshing the CI Relationship Viewer map. To specify a complex definition file. Note: The Module Name for the definition must always be CI Viewer to integrate with the CI Relationship Viewer. and notifying the AR System. These events include instructions for setting a CI as the root. “CI Relationship Viewer events.xml file. you must restart the BMC Remedy Mid Tier to view the changes in the CI Relationship Viewer context menu. Creating CI Relationship Viewer events The CI Relationship Viewer can send and receive various types of events from AR System forms. ! ! Description—A description for the definition.BMC Atrium CMDB 2.0. For more information about the CI Relationship Viewer events. 6 Click Save.” 84 Chapter 4—BMC Atrium CMDB tools . Important: After you modify a configuration XML file and attach it to the Data Visualization Definition.1 5 Specify the following details for the definition: ! Definition Name—A unique name for the definition. Complex Definition—Your customized config. The fields that appear on the CMDB Console include Short Description. ! ! Optionally. You must provides values for the Type. Priority. Date/Time is an auto-generated field.To create status alerts. and Short Description fields. you can provide an additional description for the alert in the Description field. Short Description—The description of the alert. You can use either the AR System API or workflow to add this entry. Creating CMDB status alerts 85 . ! Type—The type of alert. However. Priority—The priority for the alert. You can specify any value in this field. you add an entry in the CMDB:StatusAlerts form. and Date/Time. You can choose from Low. Type. Medium.Developer’s Reference Guide Creating CMDB status alerts You create status alerts for the BMC Atrium CMDB from other integrating applications to display on the CMDB Console. the best practice is to provide the name of the integrating application that adds an entry in the CMDB:StatusAlerts form for tracking purposes. or High. Priority. You specify the problem or status description in this field. 1 Importing data with EIE The BMC Remedy Enterprise Integration Engine (EIE) application enables you to transfer data between a third-party data source and the BMC Atrium CMDB. Figure 4-7: Data exchange process 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.BMC Atrium CMDB 2. you perform scheduled bulk data transfers and eventbased integrations. With EIE. and data synchronization.0 Administrator’s Guide. For more information about EIE data transfer between a third-party data source and the BMC Atrium CMDB. 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.0. 86 Chapter 4—BMC Atrium CMDB tools . incremental data transfers. You can use EIE for initial data load. see the BMC Remedy Enterprise Integration Engine 7. Colons and other special characters are replaced by underscores. see the BMC Remedy Action Request System 7. are created using the following naming rules: ! ! Alphabetic and numeric characters remain as defined. 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. For more information about SQL views and table naming conventions. For each database table in the AR System (except for the attachment tables). For example. the view of the BMC. Therefore. the string _x is appended to the name.CORE:BMC_BaseElement form is named BMC. which have the same name as their underlying forms. When a form name exceeds the 30 character limit. For example.Developer’s Reference Guide Working with SQL views SQL views are available to facilitate data access to the BMC Atrium CMDB from third-party database clients. a corresponding SQL view is automatically created. the SQL view for the BMC. A leading A is appended to all view names that do not begin with an alphanumeric character. these view names cannot be formulated in advance. If the name contains a database reserved word. Because schema IDs vary from one system to another. View names are limited to 30 characters.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. abstract classes do not have corresponding views.CORE_BMC_BaseElement.0: Database Reference guide. These views provide direct access to the database tables for the various BMC Atrium CMDB classes.CORE. Working with SQL views 87 . without having to know the hierarchy of a given class. These views. add the following entry in the ar. To enable CMDB Engine debug logging.cfg or ar.BMC Atrium CMDB 2. Using the API Logging option The BMC Atrium CMDB logs the engine processing. The various debug levels include: ! ! 1—Severe errors messages 2—Warnings messages 88 Chapter 4—BMC Atrium CMDB tools .conf configuration file depending on your platform. you can only add these parameters after you set the CMDB-Debug-Flag parameter to true (T). and information. Log Type—The type of log entry such as warning. “Environment functions” on page 141.0. These levels determine the type of messages that are logged for the calls. graph query. see “Import and Export functions” on page 149. You can specify additional parameters for the logging option in the ar. the BMC Atrium CMDB records details about operations.cfg configuration file on Windows or the ar. Each entry in the log provides the following details: ! ! ! Timestamp—The date and time of the log entry. The BMC Atrium CMDB Engine log classifies the messages into error. However. warning. error. and export and import. For more information about related API functions. When you enable logging. and “Instance functions” on page 126. or information.conf configuration file on UNIX and restart the AR System server: CMDB-Debug-Flag: T To disable logging. Message—The message for the log entry. set this parameter to F. such as SynchMetaData.1 Debugging BMC Atrium CMDB API programs This section discusses the logging and debugging options that are available to you for solving problems with your API programs. which helps you to debug your API program. ! CMDB-Debug-Level—Specifies the level of logging you require for your API calls. Debugging BMC Atrium CMDB API programs 89 . you will receive log messages for levels 1.c file. Printing the contents of a structure before and after an API call is useful for debugging. When the log file reaches the specified limit. if you set the debug level at 3. An example of this parameter is. The default value for the CMDB-Max-Log-File-Size parameter is set to 0. The default value for CMDB-Debug-level parameter is set to 3. The size of the log file is specified in kilobytes (KB). which specifies an unlimited size for the log file. CMDB-Max-Log-File-Size: 50000. 2. An example for this parameter is. ! CMDB-Log-File-Location—Enables you to specify the directory location on your system where the log file will be written. and 3. the log file is written to the Db directory of the AR System server. you to specify a maximum size for your log file.Developer’s Reference Guide ! ! ! 3—Informational messages 4—Detail messages 5—Additional detail messages All these logging levels are inclusive of their preceding levels. CMDB-Debug-Level: 2. the system automatically creates a backup of the log file and stores the log entries in a new log file. The print. The routines provide code examples for accessing the various structures. Note: See the function definitions in print.c to determine the specific parameters and their types for these routines. ! CMDB-Max-Log-File-Size—Enables Using print. You can specify any location on your system for the log files.h file contains a complete list of these routines.c routines One of the components of the cmdbdriver program is the set of print routines located in the print. These routines allow you to print the contents of any data structure in the API. By default. For example. 0.1 90 Chapter 4—BMC Atrium CMDB tools .BMC Atrium CMDB 2. Chapter 6. “Web services API operations and data structures. Chapter 7.” provides information about the operations and data structures used in the web services APIs.” provides all CMDB error messages with their descriptions. The Java API documentation is available in the Javadoc HTML files. “C API functions and data structures.Section II API reference This section provides reference information for the C and web services APIs.” provides information about the functions and the data structures used in the C APIs. API reference 91 . This section is organized into the following chapters: ! ! ! Chapter 5. “Error messages. 1 92 Section II—API reference .BMC Atrium CMDB 2.0. The following topics are provided: ! ! ! ! Related files (page 94) Deprecated objects (page 94) Functions (page 95) Data structures (page 182) C API functions and data structures 93 .Chapter 5 C API functions and data structures This chapter describes the C API functions. BMC Atrium CMDB 2. the following functions are available to export or import class definitions or instance data: ! CMDBExportDef—Exports class definitions to a specified directory in a given format. see Chapter 2. the following functions and data structures are deprecated: Deprecated functions The deprecated C API functions for the BMC Atrium CMDB include: ! ! CMDBImport (page 152) CMDBExport (page 149) In these export and import functions. CMDBExportData—Exports instance data to a specified directory in a given format.1 Related files The cmdb.h and cmdbfree.0 of the BMC Atrium CMDB.0. “Header files.h files contain the C API function definitions.0. For a complete list of header files required for the BMC Atrium CMDB. CMDBImportData—Imports the specific instance data. ! ! ! 94 Chapter 5—C API functions and data structures .” Deprecated objects In version 2. you pass a parameter to specify whether you want to export or import class definitions or instance data. CMDBImportDef—Imports a list of specified class definitions. In version 2. The function categories include data model. The C API functions for data model include: ! ! ! ! ! ! ! ! ! CMDBCreateAttribute (page 96) CMDBCreateMultipleAttribute (page 100) CMDBDeleteAttribute (page 103) CMDBGetAttribute (page 104) CMDBGetMultipleAttribute (page 107) CMDBSetAttribute (page 111) CMDBSetMultipleAttribute (page 113) CMDBCreateClass (page 116) CMDBDeleteClass (page 119) Functions 95 . and import or export definition functions. instance. the usage of the term specified for a given parameter denotes that the parameter is listed under the Synopsis heading of the API function. and general purpose functions. Data model functions The data model functions manipulate the attribute and class. Note: In the C API function descriptions. such as session.Developer’s Reference Guide Deprecated data structures The deprecated C API data structures for the BMC Atrium CMDB include: ! ! ! ! ! CMDBExportItem (page 200) FreeCMDBExportItemList (page 162) FreeCMDBExportItemStruct (page 161) CMDBImportItem (page 202) CMDBImportItemList (page 203) Functions The CMDB C API functions are categorized by the type of actions these functions perform. authentication. 1 ! ! ! CMDBGetClass (page 120) CMDBGetListClass (page 122) CMDBSetClass (page 123) CMDBCreateAttribute Description Privileges Synopsis Creates a new attribute with the specified name for the specified class. classNameID The name of the class for which you want to create an attribute. and server subclasses are required. The user. classNameID. entryMode. *arsubclassesId. *defaultValue. CMDB Administrator #include "ar. It is a twopart structure that contains the namespace and the classname. *status) Input arguments control The control record for the operation.h" #include "cmdb. The name of the class must be unique. sessionId. where that operation is to be performed. attributeName. *customCharacList.0. dataType. It contains information about the user requesting the operation.h" #include "arextern. *attributeLimit. *characList.BMC Atrium CMDB 2. attributeId. 96 Chapter 5—C API functions and data structures .h" int CMDBCreateAttribute( ARControlStruct CMDBClassNameId ARNameType ARNameType unsigned int ARInternalId unsigned int CMDBAttributeLimit ARValueStruct ARPropList ARPropList ARStatusList *control. and which session is used to perform it. 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) 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 of day (CMDB_ATTR_DATA_TYPE_TIME_OF_DAY) 37: 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. attributeID The ID of the attribute to create.Developer’s Reference Guide attributeName The name of the attribute to create. Functions 97 . The name of the attribute must be unique within the specified class and within its superclasses and subclasses. Specify 0 for this parameter if you want the system to generate the ID. Create Mode. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute. Audit Option. or display only. defaultValue The value to apply if a user submits an entry with no attribute value. 20. attributeLimit The value limits for the attribute and other properties specific to the attribute’s type. 4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).1 entryMode The entry mode for the attribute. characList A list of characteristics for the attribute. 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). 1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED). Primary Key.BMC Atrium CMDB 2. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon. optional. Hidden. Specify NULL if you do not want to specify a default value. 2: 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). It includes the following characteristics: View Permissions. Specify NULL for this parameter if you do not want to change the attribute limits and properties. for example.h to find the contained structure that applies to the type of attribute you are creating.-5. Propagated Owner. and Description. The limits and properties you assign must be of the same data type as the attribute. Change Permissions. 1: Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).0. you will see all attributes including the hidden attributes. When querying for attributes. See the CMDBsubclassesLimitStruct definition in cmdb. Entry mode can be set to any one of the following: required. 98 Chapter 5—C API functions and data structures . 5: The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). <prop_value>: The value for the property. CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can set the description for the attribute. Functions 99 . Return values status A list of zero or more notes. When querying for classes. An example for the serialized property list is 1\300050\2\1. it is converted into the <list_size><prop_id><data_type><prop_value> format.Developer’s Reference Guide 3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN). 6: CMDB_ATTR_CHARAC_CREATE_MODE 7:Users can set the audit option on to store the audit history for the attribute. or errors generated from a call of this function. <data_type>: The data type for the property.3. 20. The format for this value is <leadclassID>|<lead attribute>. which is within the 300000 . <prop_id>: The ID for the property. CMDB_ATTR_CHARAC_DESCRIPTION customCharacList A list of user-defined custom characteristics for the attribute. which can be of any native data type. 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. for example. you can retrieve hidden attributes. warnings. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon.399999 range. where: <list_size>: The number of items in the properties list. This setting marks the atribute as hidden for a group or a role. h" #include "arextern.BMC Atrium CMDB 2. and server subclasses are required. The user. *attributeNameList. *entryModeList. CMDB Administrator #include "ar. attributeNameList The list of attribute names. *attributeLimitList.h" #include "cmdb. attributeIdList The list of attribute IDs for the attributes being created. *arsubclassesIdList. *characListList. sessionId. and which session is used to perform it.0. classNameID The name of the class for which the attributes need to be created.h" int CMDBCreateMultipleAttribute( ARControlStruct CMDBClassNameId ARNameList ARNameList ARUnsignedIntList ARInternalIdList ARUnsignedIntList CMDBAttributeLimitList ARValueList ARPropListList ARPropListList ARStatusList *control. The name of the class must be unique. *classNameID.1 CMDBCreateMultipleAttribute Description Privileges Synopsis Creates multiple new attributes with the specified names for the specified class. The names of all attributes must be unique within the specified class and within its superclasses and subclasses. *customCharacListList. 100 Chapter 5—C API functions and data structures . *status) Input arguments control The control record for the operation. It contains information about the user requesting the operation. *attributeIdList. *dataTypeList. *defaultValueList. where that operation is to be performed. It is a two-part structure that contains the namespace and the classname. 20. 1: Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). See the CMDBsubclassesLimitStruct definition in cmdb. required. Hidden. you will see all attributes. 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). Specify NULL if you do not want to specify a default value.Developer’s Reference Guide dataTypeList The list of data types for the attributes being created.-5. Specify NULL for this parameter if you do not want to change the limits and properties for the attribute list. 1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED). attributeLimitList The list of value limits for the attributes being created and other properties specific to the attributes’ types. Characteristics include View Permissions. Functions 101 . Change Permissions. Audit Option.When querying for attributes. 4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY). The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute. for example. entryModeList The list of entry modes for the attributes being created. and optional. Propagated Owner. and Description. including the hidden attributes. The limits and properties you assign must be of the same data type as the attribute. defaultValueList The list of values to apply if a user submits an entry with no value for the attributes being created. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon. Create Mode. Primary Key. Options include display only. characListList A list of characteristics for each attribute.h to find the contained structure that applies to the type of attribute list you are modifying. arsubclassesIdList The AR System subclasses IDs of the attributes being created. BMC Atrium CMDB 2. Return values status A list of zero or more notes. The format for this value is <leadclassID>|<lead attribute>. Marks a list of atributes as hidden for a group or a role. where: <list_size>: The number of items in the properties list. 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). 3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN). 102 Chapter 5—C API functions and data structures . which can be of any native data type. CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can set descriptions for the attributes. you can choose to retrieve hidden attributes. 20. 6: CMDB_ATTR_CHARAC_CREATE_MODE 7:Users can set the audit option on to store the audit history for the attribute. <prop_value>: The value for the property. for example.1 2: 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). After the properties list structure you specify is serialized.399999 range.0. <prop_id>: The ID for the property. warnings. CMDB_ATTR_CHARAC_DESCRIPTION customCharacListList A list of user-defined custom characteristics list for each attribute. or errors generated from a call of this function. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon. <data_type>: The data type for the property. which is within the 300000 . it is converted into the <list_size><prop_id><data_type><prop_value> format. An example for the serialized property list is 1\300050\2\1. 5: The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). When querying for classes.3. Specify NULL for this parameter if you do not want to associate custom characteristics with this attribute. Depending on the value you specify for the deleteOption parameter. 0: Do not delete the attribute (AR_ATTRIBUTE_CLEAN_DELETE). and which session is used to perform it. where that operation is to be performed. classNameID. The user. CMDB Administrator #include "ar. 2: Delete the attribute even if it has subclasses that are associated with it (AR_ATTRIBUTE_FORCE_DELETE). attributeName. and server subclasses are required. the attribute is deleted immediately and is not returned to users who request information about attributes. deleteOption A value indicating the action to take if the specified attribute contains data. attributeName The name of the attribute to delete. It contains information about the user requesting the operation. sessionId. 1: Delete if the attribute contains data but not if it is inherited by subclasses (AR_ATTRIBUTE_DATA_DELETE). *status) Privileges Synopsis Input arguments control The control record for the operation.h" #include "arextern.Developer’s Reference Guide CMDBDeleteAttribute Description Deletes the attribute with the specified ID. classNameID The name of the class from which to delete the attribute.h" int CMDBDeleteAttribute( ARControlStruct CMDBClassNameId ARNameType unsigned int ARStatusList *control. deleteOption. Functions 103 .h" #include "cmdb. *defaultValue. *arsubclassesId. sessionId. *entryMode. attributeName The name of the attribute to retrieve. *attributeType. *characList. CMDBGetAttribute Description Privileges Synopsis Retrieves a single attribute. CMDB administrator #include "ar. and which session is used to perform it. attributeName. or errors generated from a call of this function. 104 Chapter 5—C API functions and data structures . classNameId The name of the class. *attributeLimit. *baseClassNameId. It contains information about the user requesting the operation.0.h" int CMDBGetAttribute( ARControlStruct CMDBClassNameId ARNameType ARNameType unsigned int unsigned int CMDBClassNameId ARInternalId unsigned int CMDBAttributeLimit ARValueStruct ARPropList ARPropList ARStatusList *control. *customCharacList.1 Return values status A list of zero or more notes. where that operation is to be performed. It is a two-part structure that contains the namespace and the classname. warnings.BMC Atrium CMDB 2. and server subclasses are required. *status) Input arguments control The control record for the operation. The name of the class must be unique. *classNameId.h" #include "arextern.h" #include "cmdb. The user. *dataType. attributeId. optional.Developer’s Reference Guide Return values attributeId The ID of the attribute. 1: CMDB_ATTR_ENTRYMODE_REQUIRED Functions 105 . entryMode The entry mode for the attribute list. 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. required. dataType The datatype of the attribute. Entry mode can be set to any one of the following: display only. 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 of day (CMDB_ATTR_DATA_TYPE_TIME_OF_DAY) 37: Attachment pool (CMDB_ATTR_DATA_TYPE_ATTACH_POOL) attributeType The type of attribute to retrieve. arsubclassesId The internal ID of the attribute to retrieve. Specify NULL for this parameter if you do not want to change the attribute limits and properties. Characteristics include View Permissions. Audit Option.0. Propagated Owner. 1: List of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).h to find the contained structure that applies to the type of attribute you are creating. Primary Key. 6: CMDB_ATTR_CHARAC_CREATE_MODE 7: The audit option for the attribute. characList A list of characteristics for each attribute. Create Mode. Change Permissions. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute. 3: 4: Specifies whether the attribute is a part of the primary key of the class (CMDB_ATTR_CHARAC_PRIMARY_KEY). 5: The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). Hidden. The flag value of the Hidden characteristic. CMDB_ATTR_CHARAC_AUDIT_OPTION 9: The description of the attribute. the audit history for the attribute is stored. CMDB_ATTR_CHARAC_DESCRIPTION 106 Chapter 5—C API functions and data structures .BMC Atrium CMDB 2. 2: List of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS). The format for this value is <leadclassID>|<lead attribute>. See the CMDBsubclassesLimitStruct definition in cmdb. and Description.1 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. users cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN). defaultValue The value to apply if a user gets an entry with no attribute value. If the audit option is on. If the flag is set to false. The limits and properties you assign must be of the same data type as the attribute. getHiddenAttrs. *existList. *status) Functions 107 . *arsubclassesIdList. *attributeNameList. or errors generated from a call of this function.Developer’s Reference Guide customCharacList A list of user-defined custom characteristics for the attribute. *attributeLimitList. status A list of zero or more notes. *nameList. *defaultValueList. *baseClassNameIdList. CMDBGetMultipleAttribute Description Privileges Synopsis Retrieves multiple attributes. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX).h" int CMDBGetMultipleAttribute( ARControlStruct CMDBClassNameId ARBoolean ARBoolean ARNameList ARPropList ARBooleanList ARNameList ARNameList ARUnsignedIntList ARUnsignedIntList CMDBClassNameIdList ARInternalIdList ARUnsignedIntList CMDBAttributeLimitList ARValueList ARPropListList ARPropListList ARStatusList *control. *entryModeList. *dataTypeList.h" #include "arextern. CMDB Administrator #include "ar. *customCharacList. *attributeIdList. *attributeTypeList. *attrCharacQueryList. getDerivedAttrs. *characList. warnings. *classNameId.h" #include "cmdb. attributeIdList The list of attribute IDs retrieved. and which session is used to perform it.0. The user. FALSE indicates that the attribute list does not exist. sessionId. dataTypeList The list of data types for the attribute. classNameId The name of the class to retrieve. Return values existList A list of flags and corresponding Boolean values indicating whether the attribute list exists. attributeTypeList The list of the attribute’s type. The value TRUE indicates that the attribute list exists. getHiddenAttrs A flag indicating whether to retrieve the hidden attributes.1 Input arguments control The control record for the operation. attrCharacQueryList A list of attribute characteristic queries to retrieve. where that operation is to be performed. Specifying FALSE will not retrieve the derived attributes. getDerivedAttrs A flag indicating whether to retrieve attributes derived from a superclass. attributeNameList The list of attribute names retrieved. 108 Chapter 5—C API functions and data structures .BMC Atrium CMDB 2. nameList A list of attributes to retrieve. Specifying FALSE will not retrieve the hidden attributes. and server subclasses are required. It is a two-part structure that contains the namespace and the classname. It contains information about the user requesting the operation. 1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED ). Characteristics include View Permissions. See “CMDBAttributeLimit” on page 187 to find the contained structure that applies to the type of attribute you are modifying. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute. Change Permissions. entryModeList The entry mode for the attribute list. Propagated Owner. Create Mode. Options include display only. defaultValueList The value to apply if a user submits an entry with no attribute list value. Specify NULL for this parameter if you do not want to change the attribute limits and properties. Audit Option. 1: List of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). arsubclassesIdList The AR System subclasses ID of the attribute. and optional. attributeLimitList The value limits for the list of attributes and other properties specific to the attribute’s type. 2: Functions 109 . The limits and properties you assign must be of the same data type as the attribute. 2: Users do not have to enter data when the entry mode is set to optional (CMDB_ATTR_ENTRYMODE_OPTIONAL). Hidden. List of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS). required. Primary Key. and Description. 4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY). characList A list of characteristics for each attribute.Developer’s Reference Guide baseClassNameIdList The name of the base class attribute to retrieve. 6: CMDB_ATTR_CHARAC_CREATE_MODE 7: The audit option for the attribute.0. users cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN). 4: Specifies whether the attributes are a part of the primary key of the class (CMDB_ATTR_CHARAC_PRIMARY_KEY). or errors generated from a call of this function. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX). The format for this value is <leadclassID>|<lead attribute>. the audit history for the attribute is stored. status A list of zero or more notes. CMDB_ATTR_CHARAC_AUDIT_OPTION 9: The description of the attribute. If the flag is set to false. If the audit option is on. warnings. 5: The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). 110 Chapter 5—C API functions and data structures . CMDB_ATTR_CHARAC_DESCRIPTION customCharacList A list of user-defined custom characteristics for the attribute.BMC Atrium CMDB 2.1 3: The flag value of the Hidden characteristic. which must be unique within the specified class and within its superclasses and subclasses.h" #include "arextern. entryMode The entry mode for the attribute. It contains information about the user requesting the operation. *entryMode. *status) Input arguments control The control record for the operation. where that operation is to be performed.h" #include "cmdb. *customCharacList. *classNameId. required.Developer’s Reference Guide CMDBSetAttribute Description Privileges Synopsis Sets an attribute with the specified name for the specified class. classNameId The name of the class for which the attribute needs to set. and which session is used to perform it. *attributeLimit. and optional. and server subclasses are required. sessionId. CMDB Administrator #include "ar. Options include display only.h" int CMDBSetAttribute( ARControlStruct CMDBClassNameId ARNameType ARNameType unsigned int CMDBAttributeLimit ARValueStruct ARPropList ARPropList ARStatusList *control. attributeName The name of the attribute to set. newAttributeName. *defaultValue. attributeName. newAttributeName The new name of the attribute. It is a two-part structure that contains the namespace and the classname. The user. *characList. Functions 111 . 1: Users can view but not modify the characteristics of the attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). Create Mode. defaultValue The value to apply if a user sets an entry with no attribute value.BMC Atrium CMDB 2. Hidden. 5: The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER).h to find the contained structure that applies to the type of attribute you are setting. Characteristics include View Permissions.1 1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED). Specify NULL for this parameter if you do not want to change the attribute limits and properties. The limits and properties you assign must be of the same data type as the attribute. Primary Key. 4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY). characList A list of characteristics for each attribute. and Description. The default value can be as many as 255 bytes in length and must be of the same data type as the attribute. 3: Users can set the flag to false so they cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN). 6: CMDB_ATTR_CHARAC_CREATE_MODE 112 Chapter 5—C API functions and data structures . attributeLimit The value limits for the attribute and other properties specific to the attribute’s type. 2: Users can view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS). Propagated Owner. Audit Option. 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). See the CMDBsubclassesLimitStruct definition in cmdb.0. Change Permissions. The format for this value is <leadclassID>|<lead attribute>. *characListList. CMDB_ATTR_CHARAC_DESCRIPTION customCharacList A list of user-defined custom characteristics for the attribute. CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can set the description of the attribute. or errors generated from a call of this function. *newAttributeNameList. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX). CMDBSetMultipleAttribute Description Privileges Synopsis Sets multiple attributes with the specified names for the specified class. *attributeLimitList. In version 2. set its datatype to NULL.0 of the BMC Atrium CMDB.1. Return values status A list of zero or more notes.h" #include "cmdb. *customCharacListList. the custom characteristic list was overwritten when you specified new values. With version 2.h" #include "arextern. To delete a custom characteristic. *status) Functions 113 . *attributeNameList. CMDB Administrator #include "ar. *classNameId. *entryModeList. *defaultValueList.Developer’s Reference Guide 7:Users can set the audit option on to store the audit history for the attribute. warnings. the new values are appended to the existing list.0.h" int CMDBSetMultipleAttribute( ARControlStruct CMDBClassNameId ARNameList ARNameList ARUnsignedIntList CMDBAttributeLimitList ARValueList ARPropListList ARPropListList ARStatusList *control. where that operation is to be performed. sessionId.BMC Atrium CMDB 2. and server subclasses are required. attributeNameList The list of attribute names to set. It is a two-part structure that contains the namespace and the classname. 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). See “CMDBAttributeLimit” on page 187 to find the contained structure that applies to the type of attribute list you are modifying. 114 Chapter 5—C API functions and data structures . attributeLimitList The list of value limits for the attributes being created and other properties specific to the attributes' types. and which session is used to perform it. The limits and properties you assign must be of the same data type as the attribute. 1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED ). classNameId The name of the class for which the attributes need to be set. entryModeList The list of entry modes for the attributes being created. The names of all attributes must be unique within the specified class and within its superclasses and subclasses. It contains information about the user requesting the operation. newAttributeNameList The list of new names of the attributes. required. optional. Specify NULL for this parameter if you do not want to change the limits and properties for the attribute list.0. The user.1 Input arguments control The control record for the operation. Entry mode can be set to any one of the following modes: display only. 4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY). 2: 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). Audit Option. The format for this value is <leadclassID>|<lead attribute>. Hidden. Create Mode. the new values are appended to the existing list. Characteristics include View Permissions. and Description. Functions 115 .0 of the BMC Atrium CMDB. CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can set descriptions of the attributes. Change Permissions. 6: CMDB_ATTR_CHARAC_CREATE_MODE 7:User can set the audit option on to store the audit history for the attribute. characListList A list of characteristics for each attribute. The default value can be as many as 255 bytes in length and must be of the same data type as the attribute. In version 2. To delete a custom characteristic. 5: The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). 1: Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). Propagated Owner. the custom characteristic list was overwritten when you specified new values. Primary Key.0.1. Specify NULL for this parameter if you do not want to associate custom characteristics with this attribute. With version 2. 3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN).Developer’s Reference Guide defaultValueList The list of values to apply if a user submits an entry with no value for the attributes being created. Specify NULL if you do not want to specify a default value. 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). set its datatype to NULL. CMDB_ATTR_CHARAC_DESCRIPTION customCharacListList A list of user-defined custom characteristics list for the attribute. sessionId. It is a two-part structure that contains the namespace and the classname. *customCharacList. *indexList. The data model is stored in the OBJSTR:Class form and the attribute information is stored in the OBJSTR:AttributeDefinition form. warnings. It can be provided by the user.0. where that operation is to be performed. classID The unique identifier for the class.h" #include "cmdb. *superclassNameId.h" #include "arextern. The name of the class must be unique. *classTypeInfo. *characList. or errors generated from a call of this function. *status) Privileges Synopsis Input arguments control The control record for the operation. the class ID will be automatically generated by the system. CMDB Administrator #include "ar. 116 Chapter 5—C API functions and data structures .h" int CMDBCreateClass( ARControlStruct CMDBClassNameId ARNameType CMDBClassTypeInfo CMDBClassNameId CMDBIndexList CMDBAuditInfoStruct ARPropList ARPropList ARStatusList *control. The user. It contains information about the user requesting the operation.BMC Atrium CMDB 2. classNameID The name of the class to create. classID. *auditInfo. and server subclasses are required.1 Return values status A list of zero or more notes. If left blank. CMDBCreateClass Description Creates a class with the core attributes in the OBJSTR:Class. and which session is used to perform it. *classNameID. for example. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a singleton class (CMDB_CLASS_CHARAC_SINGLETON). Specify NULL for this parameter if there is no superclass. indexList A list of indexes defined for the class. This characteristic is an integer value where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a singleton class. 3: You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL). You can specify one or more group IDs or role IDs for the permissions separated by a semicolon. 2: Indicates a class of type relationship (CMDB_CLASS_TYPE_RELATIONSHIP). 6: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). auditInfo The audit information for the class. 1: 2: This property does not allow you to create instances for this abstract class (CMDB_CLASS_CHARAC_ABSTRACT ). you cannot create instances for it. The class description (CMDB_CLASS_CHARAC_DESCRIPTION). All the attributes are propagated to the subclasses.3. After the property has been set for the attribute. The information contained in this definition depends on the type of class you specify. characList A list of characteristics for the class. 4: 5: The author of the class (CMDB_CLASS_CHARAC_AUTHOR). Marks the class as hidden for a group or a role. When querying for classes. you can choose to retrieve hidden classes. superclassNameID The superclass of this class. Functions 117 . 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.Developer’s Reference Guide classTypeInfo The type of class to create. 1: Indicates a regular class (CMDB_CLASS_TYPE_REGULAR). 20. BMC Atrium CMDB 2. it is converted into the <list_size><prop_id><data_type><prop_value> format.1 7: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_VISIBLE_PERMS).199999 range. which is within the 100000 .0. warnings. <data_type>: Is the data type for the property. Marks the class as visible for a group or a role. 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). Return values status A list of zero or more notes. 8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS 9: CMDB_CLASS_CHARAC_FORM_NAME customCharacList A list of user-defined custom characteristics for the class. <prop_id>: Is the ID for the property. After the properties list structure you specify is serialized. An example for the serialized property list is 1\100050\2\1. Specify NULL for this parameter if you do not want to associate custom characteristics with this class. <prop_value>: Is the value for the property.-5. or errors generated from a call of this function. which can be of any native data type. When querying for classes. 20. you will see all classes. 118 Chapter 5—C API functions and data structures . for example. including the hidden classes. where: <list_size>: Is the number of items in the properties list. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon. All the dependencies for the specified class are deleted (CMDB_DELETE_CLASS_OPTION_ALL_DEPENDENCIES). or errors generated from a call of this function. *classNameId.h" #include "cmdb. *status) Input arguments control The control record for the operation.h" int CMDBDeleteClass( ARControlStruct CMDBClassNameId unsigned int ARStatusList *control. It contains information about the user requesting the operation. 1: Delete the class only if the class has no subclasses or dependent relationships. deleteOption A value indicating the action to take if the specified class contains attributes or subclasses. and which session is used to perform it. classNameID The name of the class to delete. CMDB Administrator #include "ar. The user. This option overrides the CMDB_CLASS_DATA_DELETE option. including all the subclasses and dependent relationship classes that are associated with it. Also deletes the associated attributes of the class. 2: Delete the class. This applies only to regular classes (CMDB_DELETE_CLASS_OPTION_WITH_DATA). sessionId. deleteOption. where that operation is to be performed. Functions 119 . Return values status A list of zero or more notes. 0: Delete the class only if the class contains no instances and has no subclasses or dependent relationships (CMDB_DELETE_CLASS_OPTION_NONE).h" #include "arextern. and server subclasses are required. warnings.Developer’s Reference Guide CMDBDeleteClass Description Privileges Synopsis Deletes a specified class. *customCharacList. *indexList. superclassNameId The name of the superclass. It is a two-part structure that contains the namespace and the classname. classNameID The name of the class. *classId. *classTypeInfo.1 CMDBGetClass Description Privileges Synopsis Retrieves the class information from the OBJSTR:Class form.h" #include "cmdb. *classNameId. *superclassNameId.h" #include "arextern. *characList. and which session is used to perform it. CMDB Administrator #include "ar. where that operation is to be performed. classTypeInfo Information about the type of class. The user. auditInfo. and server subclasses are required. 120 Chapter 5—C API functions and data structures .h" int CMDBGetClass( ARControlStruct CMDBClassNameID ARNameType CMDBClassTypeInfo CMDBClassNameId CMDBIndexList CMDBAuditInfoStruct ARPropList ARPropList ARStatusList *control. sessionId.BMC Atrium CMDB 2. It contains information about the user requesting the operation. *status) Input arguments control The control record for the operation. Return values classId The ID used to identify the class.0. Developer’s Reference Guide indexList The list of indexes defined for the class. 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 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: 5: The author of the class (CMDB_CLASS_CHARAC_AUTHOR). 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 Functions 121 BMC Atrium CMDB 2.0.1 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. CMDBGetListClass Description 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( ARControlStruct ARNameType CMDBClassNameId CMDBClassNameId ARPropList ARBoolean CMDBClassNameIdList ARStatusList *control, namespaceName, *classNameIdRelation, *superclassName, *characQueryList, getHiddenClasses, *classNameIdList, *status) Privileges Synopsis 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. namespaceName The name of the namespace. Namespaces are a way of partitioning your data model to create logical groups of classes. The C API namespaces are implemented using a prefix-based naming convention on classes. 122 Chapter 5—C API functions and data structures Developer’s Reference Guide 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. 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 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( ARControlStruct CMDBClassNameId CMDBClassNameId CMDBClassTypeInfo CMDBIndexList CMDBAuditInfoStruct ARPropList ARPropList ARStatusList *control, *classNameId, *newclassNameId, *classTypeInfo, *indexList, *auditInfo, *characList, *customCharacList, *status) Privileges Synopsis Functions 123 BMC Atrium CMDB 2.0.1 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. newclassNameId The new name of the class. classTypeInfo Information about the type of class. 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). 124 Chapter 5—C API functions and data structures Developer’s Reference Guide 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. Return values status A list of zero or more notes, warnings, or errors generated from a call of this function. Functions 125 BMC Atrium CMDB 2.0.1 Instance functions The C APIfunctions for instance include: ! ! ! ! ! ! ! CMDBCreateInstance (page 126) CMDBDeleteInstance (page 127) CMDBGetInstance (page 129) CMDBGetListInstance (page 130) CMDBGetMultipleInstances (page 132) CMDBGraphQuery (page 135) CMDBSetInstance (page 138) CMDBCreateInstance Description Privileges Synopsis Creates a CI or relationship instance in the OBJSTR:Class. CMDB Administrator #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateInstance( ARControlStruct CMDBClassNameId ARNameType CMDBAttributeValueList ARNameType ARStatusList *control, *classNameId, datasetId, *attributeValueList, instanceId, *status) 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 from which the instance is derived. It is a two-part structure that contains the namespace and the classname. 126 Chapter 5—C API functions and data structures Developer’s Reference Guide 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( ARControlStruct CMDBClassNameId ARNameType ARNameType unsigned int ARStatusList *control, *classNameId, datasetId, instanceId, deleteOption, *status) Functions 127 and server subclasses are required. datasetId The unique identifier for the dataset. The user. 128 Chapter 5—C API functions and data structures . deleteOption 0: Allows you to delete only the specified instance when the instance can be retrieved (CMDB_DERIVED_DELOPTION_NONE).0. and which session is used to perform it. where that operation is to be performed.1 Input arguments control The control record for the operation. It contains information about the user requesting the operation. 1: Allows you to delete the instance even when the instance cannot be retrieved (CMDB_DERIVED_DELOPTION_FORCE). The data in the return values are based on the dataset ID specified in this parameter. Errors will be ignored for instances that do not exist. sessionId. warnings.BMC Atrium CMDB 2. Return values status A list of zero or more notes. instanceId The unique identifier for the instance (system-generated). or errors generated from a call of this function. classNameId The name of the class that holds the instance to delete. *status) Input arguments control The control record for the operation. getMask. *classNameId. *attributeValueList. classNameId The name of the class. sessionId.h" int CMDBGetInstance( ARControlStruct CMDBClassNameId ARNameType usigned int ARNameType ARNameList CMDBAttributeValueList ARStatusList *control. where that operation is to be performed. instances are retrieved from either the overlay or the original dataset. 0: Based on the datasetId being passed. and which session is used to perform it. Functions 129 . and server subclasses are required. The user.Developer’s Reference Guide CMDBGetInstance Description Privileges Synopsis Retrieves information about the instance. It contains information about the user requesting the operation. *attributeGetList. CMDB Administrator #include "ar. The data in the return values are based on the dataset ID specified in this parameter. It is a two-part structure that contains the namespace and the classname. instanceId. datasetId The unique identifier for the dataset. datasetId. getMask The identifier for specifying the dataset type.h" #include "arextern. 1: Allows you to retrieve instances from the current dataset only.h" #include "cmdb. *instanceIdList. *numMatches.1 instanceId The unique identifier for the instance to retrieve. Return values attributeValueList The list of attribute ID and value pairs for the instance. getMask. *qualifier. attributeGetList The list of attributes to retrieve.BMC Atrium CMDB 2. CMDBGetListInstance Description Privileges Synopsis Retrieves a list of instances. *attributeValueListList.h" #include "cmdb. *sortList. status A list of zero or more notes. *attributeGetList. *status) 130 Chapter 5—C API functions and data structures . or errors generated from a call of this function. You can limit the instance list to entries that match particular conditions by specifying the qualifier parameter. datasetId. maxRetrieve.0. firstRetrieve. CMDB Administrator #include "ar.h" #include "arextern. *classNameId.h" int CMDBGetListInstance( ARControlStruct CMDBClassNameId ARNameType usigned int CMDBQualifierStruct ARNameList CMDBSortList unsigned int unsigned int ARNameList CMDBAttributeValueListList unsigned int ARStatusList *control. warnings. relational. Specify CMDB_NO_MAX_LIST_RETRIEVE to assign no maximum. and arithmetic operations. where that operation is to be performed. attributeGetList A list of attribute names to retrieve. 0: Based on the datasetId being passed. and server subclasses are required. The user. instances are retrieved from either the overlay or the original dataset. classNameId The name of the class. maxRetrieve The maximum number of entries to retrieve. Functions 131 . firstRetrieve The first entry to retrieve. The qualification can include one or more subclasses and any combination of conditional. 1: Allows you to retreive instances from the current dataset only. It is a two-part structure that contains the namespace and the classname. The data in the return values are based on the dataset ID specified in this parameter.Developer’s Reference Guide Input arguments control The control record for the operation. datasetId The unique identifier for the dataset. It contains information about the user requesting the operation. sortList The sort order for the retrieved data. Use this parameter to limit the amount of data returned if the qualification does not narrow the list. getMask The identifier for specifying the dataset type. qualifier A query that determines the set of entries to retrieve. CMDB_START_WITH_FIRST_ENTRY represents the first entry to retrieve and is the default value if the value is not set. sessionId. and which session is used to perform it. datasetId. CMDB Administrator #include "ar. *status) Input arguments control The control record for the operation. *classNameId. 132 Chapter 5—C API functions and data structures . *attributeGetList.1 Return values instanceIdList The list of instance IDs that match the criteria.h" #include "cmdb. and server subclasses are required. where that operation is to be performed. attributeValueListList A list of the attribute value list. *instanceIds. *attributeValueListList. CMDBGetMultipleInstances Description Privileges Synopsis Retrieves multiple instances.BMC Atrium CMDB 2.h" int CMDBGetMultipleInstances( ARControlStruct CMDBClassNameId ARNameType unsigned int ARNameList ARNameList ARBooleanList CMDBAttributeValueListList ARStatusList *control. warnings. getMask.0. numMatches The total number of entries that match the qualification criteria.h" #include "arextern. status A list of zero or more notes. sessionId. The user. or errors generated from a call of this function. and which session is used to perform it. 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. It contains information about the user requesting the operation. *existList. The data in the return values are based on the dataset ID specified in this parameter. a list of instances are retrieved from either the overlay or the original dataset. FALSE indicates that the attribute list does not exist. 0: Based on the datasetId being passed. It is a two-part structure that contains the namespace and the classname. attributeValueListList The list of attributeID and value pairs for instances to retrieve. attributeGetList A list of attributes to retrieve. Functions 133 . getMask The identifier for specifying the dataset type. The value TRUE indicates that the attribute list exists. datasetId The unique identifier for the dataset. 1: Allows you to retreive a list of instances from the current dataset only. instanceIds A list of instance IDs to retrieve. status A list of zero or more notes.Developer’s Reference Guide classNameId The name of the class to retrieve. warnings. Return values existList A list of flags and corresponding Boolean values indicating whether the attribute list exists. or errors generated from a call of this function. CMDB Administrator #include "ar. and which session is used to perform it. getMask The identifier for specifying the dataset type. datasetId The unique identifier for the dataset. The user.BMC Atrium CMDB 2. It contains information about the user requesting the operation. classNameId The name of the class. 134 Chapter 5—C API functions and data structures . datasetId. 0: Based on the datasetId being passed. stored for the attachment subclasses. where that operation is to be performed. or binary large object (BLOB). *classNameId. The data in the return values are based on the dataset ID specified in this parameter. It is a two-part structure that contains the namespace and the classname. The BLOB is placed in a file. and server subclasses are required. attributeName. *status) Input arguments control The control record for the operation. instances are retrieved from either the overlay or the original dataset.1 CMDBGetInstanceBLOB Description Privileges Synopsis Retrieves the attachment.h" int CMDBGetInstanceBLOB( ARControlStruct CMDBClassNameId ARNameType unsigned int ARNameType ARNameType ARLocStruct ARStatusList *control. instanceId. *loc.0. getMask. 1: Allows you to retreive instances from the current dataset only.h" #include "cmdb.h" #include "arextern. sessionId. *relations.Developer’s Reference Guide instanceId The unique identifier for the instance.h" int CMDBGraphQuery( ARControlStruct CMDBClassNameId ARNameType unsigned int ARNameType ARNameType int int ARBoolean ARBoolean CMDBGraphList CMDBGetObjectList CMDBGetRelationList ARStatusList *control. getMask. direction. *objects.h" #include "cmdb. attributeName The name of the attribute that contains the attachment. numLevels. noMatchProceed. status A list of zero or more notes. *queryGraph. CMDB Administrator #include "ar. Return values loc The location where the BLOB is stored. *status) Functions 135 . or errors generated from a call of this function. CMDBGraphQuery Description Privileges Synopsis Searches related instances.h" #include "arextern. startInstanceId. datasetId. onMatchProceed. warnings. startExtensionId. *startClassNameId. and server subclasses are required. and which session is used to perform it. The data in the return values are based on the dataset ID specified in this parameter. instances are retrieved from either the overlay or the original dataset. 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. 0: Based on the datasetId being passed. sessionId. startClassNameId The name of the starting node class. CMDB_RELATIONSHIP_DIRECTION_IN (1): The node to be queried is on the left side of the relationship. getMask The identifier for specifying the dataset type. direction The direction in which the graph is to traverse. 1: Allows you to retreive instances from the current dataset only.BMC Atrium CMDB 2.1 Input arguments control The control record for the operation. The user.0. where that operation is to be performed. datasetId The unique identifier for the dataset. 136 Chapter 5—C API functions and data structures . startInstanceId The ID of the starting node. CMDB_RELATIONSHIP_DIRECTION_OUT (0): The node to be queried is on the right side of the relationship. It contains information about the user requesting the operation. 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. F (0): When the node returned for a given relationship instance matches the criteria specified. queryGraph The details of the information indicating the path that needs to be queried to return the desired CIs and relationships. no relationship information will be returned because the returned components might not be connected. status A list of zero or more notes. relations List of relationship instances matching the specified criteria that connects the CIs returned. do not proceed any further. Return values objects List of one or more CI instances matching the specified criteria. F (0): When the node returned for a given relationship instance does not match the criteria specified. due to skipping the non-matching nodes. proceed to the next relationship. in this case. Notice that. do not proceed any further.Developer’s Reference Guide noMatchProceed T (1): When the node returned for a given relationship instance does not match the criteria specified. The starting node is not included. warnings. Functions 137 . onMatchProceed T (1): When the node returned for a given relationship instance matches the criteria specified. proceed to the next relationship. or errors generated from a call of this function. h" #include "arextern. You must specify values for all required subclasses that do not have defined defaults. where that operation is to be performed.0.1 CMDBSetInstance Description Privileges Synopsis Sets a CI or relationship instance in the OBJSTR:Class.BMC Atrium CMDB 2. CMDB Administrator #include "ar. It is a two-part structure that contains the namespace and the classname. attributeValueList A list of one or more attribute value pairs (specified in any order) that identifies the data for the new attribute. The data in the return values are based on the dataset ID specified in this parameter. *attributeValueList. It contains information about the user requesting the operation. sessionId. 138 Chapter 5—C API functions and data structures . and which session is used to perform it. instanceId. The user. and server subclasses are required. *classNameId. datasetId The unique identifier for the dataset. *status) Input arguments control The control record for the operation. instanceId The unique identifier for the instance (system-generated).h" int CMDBSetInstance( ARControlStruct CMDBClassNameId ARNameType ARNameType CMDBAttributeValueList ARStatusList *control.h" #include "cmdb. classNameId The name of the class. datasetId. 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. Data model functions are not part of the bulk transaction. or errors generated from a call of this function. and which session is used to perform it. Functions 139 .Developer’s Reference Guide Values must be of the data type defined for the subclasses or have a data type of 0. where that operation is to be performed.h" #include "arextern. Return values status A list of zero or more notes. warnings. The C API bulk entry transaction functions include: ! ! CMDBBeginBulkEntryTransaction (page 139) CMDBEndBulkEntryTransaction (page 140) CMDBBeginBulkEntryTransaction Description Indicates that subsequent API functions are part of the bulk transaction. warnings. The user. CMDB Administrator #include "ar. or errors generated from a call of this function. Bulk entry transaction functions The bulk entry transaction functions invoke the bulk entry API functions. NULL values can be specified for optional subclasses only. Any API calls that arrive after this function call are placed in a queue. *status) Privileges Synopsis Input argument control The control record for the operation.h" int CMDBBeginBulkEntryTransaction( ARControlStruct ARStatusList *control. Return value status A list of zero or more notes.h" #include "cmdb. It contains information about the user requesting the operation. sessionId. and server subclasses are required. *status) Privileges Synopsis Input arguments control The control record for the operation. *bulkEntryReturnList.0. status A list of zero or more notes. actionType The type of action. Action type can be SEND or CANCEL. and server subclasses are required. For an action type of CANCEL. 140 Chapter 5—C API functions and data structures .1 CMDBEndBulkEntryTransaction Description This function commits or rolls back the bulk transaction. For an action type of SEND. Return values bulkEntryReturnList Returns the status of the entry calls.h" #include "arextern. warnings. The user. actionType. depending on the action type. sessionId. CMDB Administrator #include "ar.BMC Atrium CMDB 2.h" int CMDBEndBulkEntryTransaction( ARControlStruct unsigned int ARBulkEntryReturnList ARStatusList *control. the transaction will be canceled.h" #include "cmdb. the API call will be executed as part of the transaction. It contains information about the user requesting the operation. or errors generated from a call of this function. where that operation is to be performed. and which session is used to perform it. CMDB Administrator #include "ar. and which session is used to perform it. Return values status A list of zero or more notes. and server subclasses are required. warnings.h" #include "cmdb. *status) Input arguments control The control record for the operation.h" #include "arextern.Developer’s Reference Guide Environment functions The C API includes the following environment functions: ! ! ! ! ! ! CMDBInitialization (page 141) CMDBSystemInit (page 142) CMDBSynchMetaData (page 142) CMDBGetServerPort (page 143) CMDBSetServerPort (page 144) CMDBTermination (page 145) CMDBInitialization Description Privileges Synopsis Initializes the C API session. where that operation is to be performed.h" int CMDBInitialization( ARControlStruct ARStatusList *control. This function must be called before any C API calls are made. It contains information about the user requesting the operation. or errors generated from a call of this function. Functions 141 . sessionId. The user. *status) Return values propList A list of properties that need to be initialized. or errors generated from a call of this function.h" int CMDBSynchMetaData( ARControlStruct ARNameType CMDBClassNameIdList ARStatusList *control. warnings. which enforces class hierarchy and data integrity. pendingId. CMDB Administrator #include "ar. CMDB Administrator #include "ar.h" int CMDBSystemInit( ARPropList ARStatusList *propList.h" #include "arextern. CMDBSynchMetaData Description Privileges Synopsis Creates AR System forms from the data model definitions that hold instance data.h" #include "cmdb.h" #include "arextern.h" #include "cmdb. status A list of zero or more notes.BMC Atrium CMDB 2.0.1 CMDBSystemInit Description Privileges Synopsis Performs server.and network-specific initialization operations for internal use by BMC. and workflow. *status) 142 Chapter 5—C API functions and data structures . *classNameIdList. h" #include "cmdb. status A list of zero or more notes. The user. and server subclasses are required.h" #include "arextern. and server subclasses are required. warnings. where that operation is to be performed.h" int CMDBGetServerPort( ARControlStruct int int ARStatusList *control. *rpcPort.Developer’s Reference Guide Input arguments control The control record for the operation. pendingId The ID of the object to be synchronized with the system. The user. It contains information about the user requesting the operation. Return values tcpPort Retrieves the CMDB server TCP port information. and which session is used to perform it. *tcpPort. CMDBGetServerPort Description Privileges Synopsis Retrieves information about the server port. where that operation is to be performed. sessionId. CMDB Administrator #include "ar. It contains information about the user requesting the operation. and which session is used to perform it. *status) Input arguments control The control record for the operation. sessionId. Functions 143 . Return values classNameIDList The list of classes that are successfully synchronized with the system. or errors generated from a call of this function. sessionId. The user. This parameter is overridden by the ARTCPPORT environment variable.0. Specify 390697 to use the admin server. It contains information about the user requesting the operation. CMDB Administrator #include "ar. The default RPC port number is set to 390696. your program will use the port number supplied by the portmapper. *status) Input arguments control The control record for the operation.h" int CMDBSetServerPort( ARControlStruct int int ARStatusList *control. 144 Chapter 5—C API functions and data structures . *tcpPort.1 rpcPort Retrieves the CMDB server RPC port information. and server subclasses are required. *rpcPort. status A list of zero or more notes. or errors generated from a call of this function. CMDBSetServerPort Description Privileges Synopsis Sets the specified server port. tcpPort The TCP port number that your program will use to communicate with the AR System server.BMC Atrium CMDB 2. warnings.h" #include "arextern.h" #include "cmdb. and which session is used to perform it. rpcPort The RPC port number for the CMDB server. where that operation is to be performed. If you do not specify this parameter or provide 0 for the port number. warnings. Functions 145 . CMDBTermination Description Performs environment-specific cleanup routines and disconnects from the specified session.h" #include "cmdb. or errors generated from a call of this function. where that operation is to be performed. The user. All API programs that interact with the C API session should call this function upon completing work in a given session. *status) Privileges Synopsis Input arguments control The control record for the operation. Return values status A list of zero or more notes. warnings. or errors generated from a call of this function. sessionId. CMDB Administrator #include "ar.Developer’s Reference Guide Return values status A list of zero or more notes. It contains information about the user requesting the operation. and server subclasses are required.h" int CMDBTermination( ARControlStruct ARStatusList *control.h" #include "arextern. and which session is used to perform it. It contains information about the user requesting the operation. *status) Input arguments control The control record for the operation. *inputInfo. sessionId. locale. The C API includes the following user interface (UI) functions: ! ! ! CMDBGetCMDBUIComponents (page 146) CMDBRunQualificationForCI (page 147) CMDBExpandParametersForCI (page 148) CMDBGetCMDBUIComponents Description Privileges Synopsis Retrieves a list of various UI components for a specified class. inputInfo The qualification for the user interface component. instanceId The unique identifier used to get component information for a specific instance. instanceId. where that operation is to be performed. all existing UI components will be returned.BMC Atrium CMDB 2. 146 Chapter 5—C API functions and data structures . and tags to get the required UI component data. CMDB Administrator #include "ar. You can specify information such as locale. and which session is used to perform it. The user. such as tool tips. *outputInfo. classId.0. and server subclasses are required. and labelized strings. icons.h" #include "cmdb.h" #include "arextern.1 User interface component functions The user interface (UI) component functions work with components.h" int CMDBGetCMDBUIComponents( ARControlStruct CMDBUIComponentInfo ARNameType CMDBUIComponentResultList ARStatusList *control. If there are no qualifications specified. h" #include "arextern. *qualifier. qualifier A query that determines the set of CIs to retrieve.h" int CMDBRunQualificationForCI( ARControlStruct CMDBQualifierStruct CMDBAttributeValueList ARBoolean* ARStatusList Privileges Synopsis *control. The user. or errors generated from a call of this function. *attValueList. Return Values passed A Boolean value that specifies whether the qualification passed. The CMDBRunQualificationForCI function takes qualification parameters in both structured and encoded modes. and server subclasses are required. locale. where that operation is to be performed. It contains information about the user requesting the operation. CMDBRunQualificationForCI Description Performs validation on a list of attributes for a specified CI. relational. attValueList The list of attributes to validate. status A list of zero or more notes. warnings. and which session is used to perform it. Functions 147 . sessionId. *status) Input arguments control The control record for the operation.Developer’s Reference Guide Return Values outputInfo The CMDBUIComponents result set for the specified qualifications.h" #include "cmdb. CMDB Administrator #include "ar. passed. The qualification can include one or more subclasses and any combination of conditional. and arithmetic operations. and which session is used to perform it. locale. *attValueList. and server subclasses are required.1 status A list of zero or more notes. CMDBExpandParametersForCI Description Accepts an unexpanded string that contains parameters and substitutes values from the attribute value list provided in the CMDBAttributeValueList structure.h" int CMDBQualificationForCI( ARControlStruct char CMDBAttributeValueList char ARStatusList Privileges Synopsis *control. The user. sessionId. or errors generated from a call of this function. *paramString. It contains information about the user requesting the operation. attValueList The list of attribute values that will be used to expand the parameters. *status) Input arguments control The control record for the operation. or errors generated from a call of this function.0. CMDB Administrator #include "ar. **expandedStr.h" #include "cmdb. 148 Chapter 5—C API functions and data structures .BMC Atrium CMDB 2. paramString The string that contains the unexpanded parameters. where that operation is to be performed. Return Values expandedStr The string that contains the expanded parameters. status A list of zero or more notes.h" #include "arextern. warnings. warnings. and which session is used to perform it. It contains information about the user requesting the operation. *directoryPath. exportItemList The list of items to export. where that operation is to be performed. The user.0 release of the BMC Atrium CMDB. and server subclasses are required. sessionId. CMDB Administrator #include "ar.h" #include "arextern. The C API includes the following export and import functions: ! ! ! ! ! ! CMDBExport (page 149) CMDBExportDef (page 150) CMDBExportData (page 151) CMDBImport (page 152) CMDBImportDef (page 153) CMDBImportData (page 154) CMDBExport Description Privileges Synopsis Exports the specified class definitions from the specified server. This function is deprecated in the 2. exportFormat. Functions 149 .Developer’s Reference Guide Import and Export functions The export and import functions enable you to export or import CMDB data.h" int CMDBExport( ARControlStruct CMDBExportItemList unsigned int char ARStatusList *control. *status) Input arguments control The control record for the operation. *exportItemList.h" #include "cmdb. 1 exportFormat The format of the export. and server subclasses are required. *exportBuf. warnings. *exportItemList. where that operation is to be performed. CMDB Administrator #include "ar. Return values status A list of zero or more notes. 150 Chapter 5—C API functions and data structures . It contains information about the user requesting the operation.0. *status) Input arguments control The control record for the operation. sessionId. Return values exportBuf The exported buffer which contains the class definitions in XML format. The user. and which session is used to perform it. directoryPath The directory in which the exported file is to be stored.h" int CMDBExportDef( ARControlStruct CMDBExportItemList char ARStatusList *control. or errors generated from a call of this function.h" #include "cmdb. CMDBExportDef Description Privileges Synopsis Exports a list of specified class definitions.h" #include "arextern.BMC Atrium CMDB 2. The default export format is set to CMDB_EXPORT_FORMAT_XML. exportItemList A list of zero or more classes or attributes to export. h" int CMDBExportData( ARControlStruct ARQualifierStruct ARNameList CMDBSortList unsigned int unsigned int char ARStatusList *control. sortList A list of zero or more fields that identifies the sort order for the exported data. *exportBuf. *qualifier. *status) Input arguments control The control record for the operation. sessionId. firstRetrieve.h" #include "cmdb. or errors generated from a call of this function. It contains information about the user requesting the operation. *attributeGetList. and server subclasses are required. CMDB Administrator #include "ar. warnings. CMDBExportData Description Privileges Synopsis Exports the specified class data for a specific qualification.Developer’s Reference Guide status A list of zero or more notes.h" #include "arextern. The qualification can include one or more subclasses and any combination of conditional. Functions 151 . qualifier A query that determines the set of classes or attributes to retrieve. Specify a NULL value for this parameter to use no specific sort order. attributeGetList The list of attributes names to retrieve. The user. and which session is used to perform it. where that operation is to be performed. *sortList. relational. and arithmetic operations. maxRetrieve. 0. This function is deprecated in the 2. It contains information about the user requesting the operation.0 release of the BMC Atrium CMDB.BMC Atrium CMDB 2. warnings. Specify 0 (CMDB_NO_MAX_LIST_RETRIEVE) to assign no maximum instances. The user. which contains the class data in an XML format. 152 Chapter 5—C API functions and data structures . and server subclasses are required. CMDB Administrator #include "ar. status A list of zero or more notes. *importItemList. or errors generated from a call of this function. sessionId.h" #include "cmdb. maxRetrieve The maximum number of instances to retrieve. Return values exportBuf The exported buffer. Use this parameter to limit the instances returned in the query if the qualification does not sufficiently narrow the list. where that operation is to be performed. *status) Privileges Synopsis Input arguments control The control record for the operation. *directoryPath. and which session is used to perform it.1 firstRetrieve The first instance to retrieve.h" int CMDBImport( ARControlStruct CMDBImportItemList char ARStatusList *control. CMDBImport Description Imports the specified class definitions to the specified server.h" #include "arextern. Use this function to copy structure definitions from one server to another. A value of 0 (CMDB_START_WITH_FIRST_INSTANCE)represents the first entry and is the default value if no value is set. If an import item already exists. the function generates an error. and server subclasses are required. importOption. 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. The user. importOption A value indicating whether to replace class definitions being imported if they already exist. Specify NULL for this parameter to import all definitions in the import buffer. CMDB Administrator #include "ar.Developer’s Reference Guide importItemList A list of zero or more items to import. and which session is used to perform it.h" #include "arextern. where that operation is to be performed. sessionId. It contains information about the user requesting the operation. or errors generated from a call of this function. *importBuf. *status) Input arguments control The control record for the operation. *importItemList.h" #include "cmdb.h" int CMDBImportDef( ARControlStruct CMDBXMLImportItemList unsigned int char ARStatusList *control. Functions 153 . importItemList A list of zero or more items to import. CMDBImportDef Description Privileges Synopsis Imports a list of specified class definitions. 1 1: Generate an error if an item to import already exists CMDB_DEF_IMPORT_OPT_CREATE. where that operation is to be performed. and server subclasses are required. sessionId.0. 1: Generate an error (CMDB_DATA_IMPORT_OPT_ERROR_FOR_DUP).h" int CMDBImportData( ARControlStruct unsigned int char ARStatusList *control. and which session is used to perform it. The user. *importBuf. These options are mutually exclusive. CMDBImportData Description Privileges Synopsis Imports the specified instance data. CMDB Administrator #include "ar.BMC Atrium CMDB 2. It contains information about the user requesting the operation.h" #include "cmdb. importOption A value indicating the options available for handling duplicates found during the importing of instance data.h" #include "arextern. importOption. 154 Chapter 5—C API functions and data structures . warnings. or errors generated from a call of this function. Return values status A list of zero or more notes. importBuf The import buffer that contains the class definitions to import in XML format. *status) Input arguments control The control record for the operation. 2: Overwrite if an item to import already exists CMDB_DEF_IMPORT_OPT_OVERWRITE. *status) Functions 155 . import.h" #include "arextern. CMDB Administrator #include "ar. (CMDB_DATA_IMPORT_OPT_NEWID_FOR_ALL). Utility functions The utility functions enable you to use CMDB utilities such as export. 3: Update the existing instance if the instance ID specified already exists (CMDB_DATA_IMPORT_OPT_MERGE_FOR_DUP). The C API includes the following utility functions: ! ! CMDBCreateGuid (page 155) CMDBGetVersions (page 156) CMDBCreateGuid Description Privileges Synopsis Creates a globally unique identifier. or errors generated from a call of this function.h" int CMDBCreateGuid( ARGuid ARStatusList guid.Developer’s Reference Guide 2: Create an instance with a new instance ID if the instance ID already exists (CMDB_DATA_IMPORT_OPT_NEWID_FOR_DUP).h" #include "cmdb. and generate globally unique identifiers (GUIDs). 4: Create a new instance ID for all the imported instances. including those instances that are not duplicates. importBuf The import buffer. warnings. Return values status A list of zero or more notes. which contains the class data to import in XML format. Return values existList A list of TRUE or FALSE values. It contains information about the user requesting the operation. and server subclasses are required. and which session is used to perform it.h" int CMDBGetVersions( ARControlStruct ARNameList ARBooleanList CMDBVersionInfoList ARStatusList *control.1 Return values guid The unique identifier (system-generated). sessionId. appIdList A list of application IDs for which the version information is required. Each value in this list denotes whether the corresponding application IDs in the supplied appIdList exists. status A list of zero or more notes. or errors generated from a call of this function. warnings.h" #include "arextern. where that operation is to be performed.0. *appIdList *existList *versionInfoList *status) Input arguments control The control record for the operation. CMDBGetVersions Description Privileges Synopsis Retrieves the version information for any BMC Atrium CMDB component that is installed.BMC Atrium CMDB 2. The user. Specify a NULL value in this argument to get version information of all the existing applications. 156 Chapter 5—C API functions and data structures . versionInfoList A list of BMC Atrium CMDB version structures. CMDB Administrator #include "ar. The C API includes the following free functions: ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! FreeCMDBVersionInfoList (page 158) FreeCMDBClassNameIdList (page 158) FreeCMDBAttributeLimit (page 159) FreeCMDBAttributeLimitList (page 160) FreeCMDBAttributeLimitStruct (page 159) FreeCMDBIndexList (page 161) FreeCMDBExportItemStruct (page 161) FreeCMDBExportItemList (page 162) FreeCMDBImportItemList (page 162) FreeCMDBAttributeGetStruct (page 163) FreeCMDBGraphAdjacentStruct (page 164) FreeCMDBGraphAdjacentList (page 164) FreeCMDBGraphStruct (page 165) FreeCMDBGraphList (page 166) FreeCMDBClassTypeInfo (page 166) FreeCMDBQualifierStruct (page 167) FreeCMDBGetRelationList (page 167) FreeCMDBGetObjectList (page 168) FreeCMDBAttributeValueList (page 169) FreeCMDBAttributeValueListList (page 169) FreeCMDBSortList (page 170) FreeCMDBREJobRunInfoList (page 171) Functions 157 . or errors generated from a call of this function.Developer’s Reference Guide status A list of zero or more notes. warnings. Free functions The free functions release the memory allocated to a specified function. FALSE indicates to free only the contents of the structure.h" #include "arfree.1 FreeCMDBVersionInfoList Description Privileges Synopsis Releases the memory space allocated to the CMDBVersionInfoList structure. freestruct) Input arguments value A pointer to the CMDBVersionInfoList structure to be released. freeStruct A flag indicating if the top-level structure is to be released. 158 Chapter 5—C API functions and data structures .BMC Atrium CMDB 2.h" #include "cmdbfree.h" #include "cmdbfree. CMDB Administrator #include "ar. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.0. The value TRUE indicates to release the allocated memory for the top-level structure. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. freestruct) Input arguments value A pointer to the CMDBClassNameIdList structure to be released.h" #include "arfree.h" FreeCMDBClassNameIdList( CMDBClassNameIdList ARBoolean *value. CMDB Administrator #include "ar.h" FreeCMDBVersionInfoList( CMDBVersionInfoList ARBoolean *value. FreeCMDBClassNameIdList Description Privileges Synopsis Releases the memory space allocated to the CMDBClassNameIdList structure. h" FreeCMDBAttributeLimitStruct( CMDBAttributeLimit ARBoolean *value.h" #include "arfree. freestruct) Input arguments value A pointer to the CMDBAttributeLimit structure to be released. FreeCMDBAttributeLimit Description Privileges Synopsis Releases the memory space allocated to the CMDBAttributeLimit structure.h" #include "arfree. The value TRUE indicates to release the allocated memory for the top-level structure. CMDB Administrator #include "ar. The value TRUE indicates to release the allocated memory for the top-level structure. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.h" #include "cmdbfree.h" FreeCMDBAttributeLimit( CMDBAttributeLimit ARBoolean *value.h" #include "cmdbfree.Developer’s Reference Guide freeStruct A flag indicating if the top-level structure is to be released. CMDB Administrator #include "ar. FreeCMDBAttributeLimitStruct Description Privileges Synopsis Releases the memory space allocated to the CMDBAttributeLimitStruct structure. freeStruct A flag indicating if the top-level structure is to be released. freestruct) Functions 159 . FALSE indicates to free only the contents of the structure. FALSE indicates to free only the contents of the structure. CMDB Administrator #include "ar.h" FreeCMDBAttributeLimitList( CMDBAttributeLimitList ARBoolean *value. 160 Chapter 5—C API functions and data structures . freeStruct A flag indicating if the top-level structure is to be released.h" #include "cmdbfree.BMC Atrium CMDB 2. 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. FreeCMDBAttributeLimitList Description Privileges Synopsis Releases the memory space allocated to the CMDBAttributeLimitList structure. FALSE indicates to free only the contents of the structure.1 Input arguments value A pointer to the CMDBAttributeLimitStruct structure to be released. freestruct) Input arguments 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. The value TRUE indicates to release the allocated memory for the top-level structure.0.h" #include "arfree. FALSE indicates to free only the contents of the structure. The value TRUE indicates to release the allocated memory for the top-level structure. FALSE indicates to free only the contents of the structure.h" FreeCMDBIndexList( CMDBIndexList ARBoolean *value. freestruct) Input arguments 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.h" #include "arfree.h" #include "arfree. FreeCMDBExportItemStruct Description Privileges Synopsis Releases the memory space allocated to the CMDBExportItemStruct structure.Developer’s Reference Guide FreeCMDBIndexList Description Privileges Synopsis Releases the memory space allocated to the CMDBIndexList structure. 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. Functions 161 .h" #include "cmdbfree. freestruct) Input arguments value A pointer to the CMDBExportItemStruct structure to be released.h" #include "cmdbfree. CMDB Administrator #include "ar.h" FreeCMDBExportItemStruct( CMDBExportItemStruct ARBoolean *value. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. CMDB Administrator #include "ar. 0.h" #include "arfree.BMC Atrium CMDB 2.h" #include "arfree. CMDB Administrator #include "ar. freeStruct A flag indicating if the top-level structure is to be released.1 freeStruct A flag indicating if the top-level structure is to be released.h" FreeCMDBImportItemList( CMDBImportItemList ARBoolean *value. FreeCMDBImportItemList Description Privileges Synopsis Releases the memory space allocated to the CMDBImportItemList structure. freestruct) Input arguments 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. The value TRUE indicates to release the allocated memory for the top-level structure.h" #include "cmdbfree.h" FreeCMDBExportItemList( CMDBExportItemList ARBoolean *value. CMDB Administrator #include "ar. FALSE indicates to free only the contents of the structure. freestruct) 162 Chapter 5—C API functions and data structures . FreeCMDBExportItemList Description Privileges Synopsis Releases the memory space allocated to the CMDBExportItemList structure. FALSE indicates to free only the contents of the structure. The value TRUE indicates to release the allocated memory for the top-level structure.h" #include "cmdbfree. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. freestruct) Input arguments value A pointer to the CMDBAttributeGetStruct structure that you want to free. FALSE indicates to free only the contents of the structure.h" #include "arfree.h" #include "cmdbfree. FreeCMDBAttributeGetStruct Description Privileges Synopsis Releases the memory space allocated to the CMDBAttributeGetStruct structure. specify 0 (FALSE) to free only the contents of the structure. The system does not perform an operation if the structure is a list with zero items or if you specify NULL for this parameter. Functions 163 . If you used a stack variable for the top-level structure. freeStruct A flag indicating if the top-level structure is to be released. specify 1 (TRUE) to free both the structure and its contents.h" FreeCMDBAttributeGetStruct( CMDBAttributeGetStruct ARBoolean *value. freeStruct A flag indicating whether you need to free the top-level structure. If you allocated memory for the top-level structure. CMDB Administrator #include "ar. The value TRUE indicates to release the allocated memory for the top-level structure.Developer’s Reference Guide Input arguments value A pointer to the CMDBImportItemList structure to be released. h" #include "arfree.1 FreeCMDBGraphAdjacentStruct Description Privileges Synopsis Releases the memory space allocated to the CMDBGraphAdjacentStruct structure.h" #include "cmdbfree. FreeCMDBGraphAdjacentList Description Privileges Synopsis Releases the memory space allocated to the CMDBGraphAdjacentList structure. CMDB Administrator #include "ar. FALSE indicates to free only the contents of the structure. freestruct) 164 Chapter 5—C API functions and data structures .0.h" #include "cmdbfree.h" FreeCMDBGraphAdjacentStruct( CMDBGraphAdjacentStruct ARBoolean *value. freestruct) Input arguments value A pointer to the CMDBGraphAdjacentStruct structure to be released.h" FreeCMDBGraphAdjacentList( CMDBGraphAdjacentList ARBoolean *value.h" #include "arfree.BMC Atrium CMDB 2. CMDB Administrator #include "ar. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. The value TRUE indicates to release the allocated memory for the top-level structure. freeStruct A flag indicating if the top-level structure is to be released. h" FreeCMDBGraphStruct( CMDBGraphStruct ARBoolean *value. FALSE indicates to free only the contents of the structure. freeStruct A flag indicating if the top-level structure is to be released. CMDB Administrator #include "ar.h" #include "arfree. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. FreeCMDBGraphStruct Description Privileges Synopsis Releases the memory space allocated to the CMDBGraphStruct structure. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.Developer’s Reference Guide Input arguments value A pointer to the CMDBGraphAdjacentList structure to be released. freeStruct A flag indicating if the top-level structure is to be released. FALSE indicates to free only the contents of the structure. freestruct) Input arguments value A pointer to the CMDBGraphStruct structure to be released. Functions 165 . The value TRUE indicates to release the allocated memory for the top-level structure.h" #include "cmdbfree. The value TRUE indicates to release the allocated memory for the top-level structure. h" FreeCMDBClassTypeInfo( CMDBClassTypeInfo ARBoolean *value. CMDB Administrator #include "ar.h" #include "arfree. FALSE indicates to free only the contents of the structure. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. freestruct) Input arguments 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.BMC Atrium CMDB 2. 166 Chapter 5—C API functions and data structures . CMDB Administrator #include "ar. The value TRUE indicates to release the allocated memory for the top-level structure. FreeCMDBClassTypeInfo Description Privileges Synopsis Releases the memory space allocated to the CMDBClassTypeInfo structure.h" FreeCMDBGraphList( CMDBGraphList ARBoolean *value. freestruct) Input arguments value A pointer to the CMDBClassTypeInfo structure to be released.0.h" #include "cmdbfree. freeStruct A flag indicating if the top-level structure is to be released.h" #include "arfree.1 FreeCMDBGraphList Description Privileges Synopsis Releases the memory space allocated to the CMDBGraphList structure.h" #include "cmdbfree. CMDB Administrator #include "ar.Developer’s Reference Guide freeStruct A flag indicating if the top-level structure is to be released.h" #include "cmdbfree. The value TRUE indicates to release the allocated memory for the top-level structure. freestruct) Input arguments value A pointer to the CMDBQualifierStruct structure to be released. FreeCMDBGetRelationList Description Privileges Synopsis Releases the memory space allocated to the CMDBGetRelationList structure. The value TRUE indicates to release the allocated memory for the top-level structure. CMDB Administrator #include "ar. freeStruct A flag indicating if the top-level structure is to be released. FALSE indicates to free only the contents of the structure.h" FreeCMDBQualifierStruct( CMDBQualifierStruct ARBoolean *value. freestruct) Functions 167 . The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.h" #include "arfree. FreeCMDBQualifierStruct Description Privileges Synopsis Releases the memory space allocated to the CMDBQualifierStruct structure.h" FreeCMDBGetRelationList( CMDBGetRelationList ARBoolean *value.h" #include "cmdbfree.h" #include "arfree. FALSE indicates to free only the contents of the structure. h" #include "arfree.0. FALSE indicates to free only the contents of the structure. 168 Chapter 5—C API functions and data structures . 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. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. CMDB Administrator #include "ar. FreeCMDBGetObjectList Description Privileges Synopsis Releases the memory space allocated to the CMDBGetObjectList structure. FALSE indicates to free only the contents of the structure.h" #include "cmdbfree.h" FreeCMDBGetObjectList( CMDBGetObjectList ARBoolean *value.1 Input arguments 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.BMC Atrium CMDB 2. The value TRUE indicates to release the allocated memory for the top-level structure. freestruct) Input arguments value A pointer to the CMDBGetObjectList structure to be released. freeStruct A flag indicating if the top-level structure is to be released. Developer’s Reference Guide FreeCMDBAttributeValueList Description Privileges Synopsis Releases the memory space allocated to the CMDBAttributeValueList structure. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. FALSE indicates to free only the contents of the structure.h" FreeCMDBAttributeValueListList( CMDBAttributeValueListList ARBoolean *value. 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. FreeCMDBAttributeValueListList Description Privileges Synopsis Releases the memory space allocated to the CMDBAttributeValueListList structure. CMDB Administrator #include "ar.h" FreeCMDBAttributeValueList( CMDBAttributeValueList ARBoolean *value.h" #include "cmdbfree.h" #include "cmdbfree. freestruct) Input arguments value A pointer to the CMDBAttributeValueList structure to be released.h" #include "arfree. freestruct) Functions 169 .h" #include "arfree. CMDB Administrator #include "ar. h" #include "cmdbfree. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. FreeCMDBSortList Description Privileges Synopsis Releases the memory space allocated to the CMDBSortList structure. freestruct) Input arguments value A pointer to the CMDBSortList structure to be released.BMC Atrium CMDB 2.1 Input arguments value A pointer to the CMDBAttributeValueListList structure to be released. CMDB Administrator #include "ar. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. The value TRUE indicates to release the allocated memory for the top-level structure. FALSE indicates to free only the contents of the structure. 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. freeStruct A flag indicating if the top-level structure is to be released. 170 Chapter 5—C API functions and data structures . FALSE indicates to free only the contents of the structure.h" FreeCMDBSortList( CMDBSortList ARBoolean *value.0.h" #include "arfree. h" #include "arfree. The value TRUE indicates to release the allocated memory for the top-level structure. Functions 171 .h" #include "cmdbfree. freeStruct A flag indicating if the top-level structure is to be released. freestruct) Input arguments value A pointer to the CMDBREJobRunInfoList structure to be released. CMDB Administrator #include "ar.Developer’s Reference Guide FreeCMDBREJobRunInfoList Description Privileges Synopsis Releases the memory space allocated to the CMDBREJobRunInfoList structure.h" FreeCMDBREJobRunInfoList( CMDBREJobRunInfoList ARBoolean *value. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter. FALSE indicates to free only the contents of the structure. and which session is used to perform it. the CMDBStartJobRun function returns an error.h" #include "arextern. Before starting a job. CMDB Administrator #include "ar. *datasetList jobRunId. The user. Only one instance of the same job can be executed at a given time. and server subclasses are required.BMC Atrium CMDB 2. *classQualList. make sure the job is defined and exists in an Active state. sessionId.h" int CMDBStartJobRun( ARControlStruct ARNameType CMDBClassQualList CMDBREDatasetList ARNameType ARStatusList *control.0.h" #include "cmdb. jobName. If no job for the specified job name exists. where that operation is to be performed. 172 Chapter 5—C API functions and data structures . jobName The name of the reconciliation job. It contains information about the user requesting the operation. The C API functions for the Reconciliation Engine include: ! ! ! ! CMDBStartJobRun (page 172) CMDBGetJobRun (page 173) CMDBGetListJobRun (page 174) CMDBCancelJobRun (page 175) CMDBStartJobRun Description Starts an existing Reconciliation Engine job. or the job is not Active. *status) Privileges Synopsis Input arguments control The control record for the operation.1 Reconciliation Engine functions The Reconciliation Engine functions manipulate Reconciliation Engine jobs. Developer’s Reference Guide classQualList The list of class qualifications. warnings.h" int CMDBGetJobRun( ARControlStruct ARNameType ARREJobRunInfoStruct char ARStatusList *control.h" #include "arextern. CMDBGetJobRun Description Privileges Synopsis Gets information about the currently running reconciliation job and retrieves a job log. *jobRunInfo. where that operation is to be performed. and which session is used to perform it. The user. It contains information about the user requesting the operation. jobRunId. Return values jobRunId A unique job identifier. and server subclasses are required. sessionId. datasetList The list of Reconciliation Engine dataset pair. Functions 173 .h" #include "cmdb. CMDB Administrator #include "ar. or errors generated from a call of this function. jobRunId A unique job identifier. **jobRunLog *status) Input arguments control The control record for the operation. status A list of zero or more notes. or errors generated from a call of this function. and which session is used to perform it.1 Return values jobRunInfo The job run information to retrieve. Job Instance ID*. CMDB Administrator #include "ar. Job Run ID. 174 Chapter 5—C API functions and data structures . The following qualifiers are currently supported: Run Status*. status A list of zero or more notes. *numMatches. *jobQualifier.h" #include "arextern. and arithmetic operations. The qualification can include one or more subclasses and any combination of conditional. where that operation is to be performed. sessionId. *status) Input arguments control The control record for the operation. The user. jobQualifier A query that determines the set of entries to retrieve. The job list will be retrieved based on the qualification passed to the function. Run End Time. jobRunLog The job run log to retrieve. CMDBGetListJobRun Description Privileges Synopsis Get a list of running Reconciliation Engine jobs. relational. It contains information about the user requesting the operation. warnings. and server subclasses are required. *jobRunInfoList. and Submitter.0.h" #include "cmdb.BMC Atrium CMDB 2. Run Start Time.h" int CMDBGetListJobRun( ARControlStruct CMDBQualifierStruct ARREJobRunInfoList unsigned int ARStatusList *control. The user.h" #include "arextern. *status) Privileges Synopsis Input arguments control The control record for the operation.h" int CMDBCancelJobRun( ARControlStruct ARNameType ARStatusList *control. CMDBCancelJobRun Description Cancels a currently running Reconciliation Engine job. warnings. sessionId. numMatches The total number of jobs that match the qualification criteria. where that operation is to be performed. and which session is used to perform it. CMDB Administrator #include "ar. jobRunId. or errors generated from a call of this function. status A list of zero or more notes.h" #include "cmdb. Functions 175 . or errors generated from a call of this function. It contains information about the user requesting the operation. Depending on the system resources. jobRunId A unique job identifier. and server subclasses are required. warnings. Reconciliation Engine might cancel a job with a certain delay. Return values status A list of zero or more notes.Developer’s Reference Guide Return values jobRunInfoList The list of running jobs that match the qualification criteria. *attributeGetList.1 Federation functions The federation functions manipulate federated data for an instance. instanceId. and server subclasses are required. *attrValueListList. 176 Chapter 5—C API functions and data structures . datasetId. *classNameId. datasetId The dataset ID of the instance to retrieve. The user. and which session is used to perform it. classNameId The class name of the specified instance for which federated instances are to be retrieved.BMC Atrium CMDB 2. *status Input arguments control The control record for the operation.h" #include "cmdb.0. where that operation is to be performed.h" #include "arextern. sessionId. The C API functions for federation include: ! ! CMDBGetRelatedFederatedInContext (page 176) CMDBActivateFederatedInContext (page 177) CMDBGetRelatedFederatedInContext Description Privileges Synopsis Returns related FederatedInterface instances for a specific CI (context). It contains information about the user requesting the operation. CMDB Administrator #include "ar.h" int CMDBGetRelatedFederatedInContext( ARControlStruct CMDBClassNameId ARNameType ARNameType ARNameList ARNameList CMDBAttributeValueListList ARStatusList *control. *instanceIdList. attrValueListList The list of attribute value list. *federatedInfo.h" #include "arextern. attributeGetList The list of attribute names to retrieve.h" int CMDBActivateFederatedInContext( ARControlStruct CMDBClassNameId ARNameType ARNameType ARNameType unsigned int CMDBFederatedActivateInfo ARStatusList *control. or errors generated from a call of this function. *status Privileges Synopsis Functions 177 .h" #include "cmdb. *classNameId.Developer’s Reference Guide instanceId The instance ID of the specific instance for which federated instances are to be retrieved. your federated instance might either be only expanded. CMDBActivateFederatedInContext Description Expands the FederatedInterface instance for a specific CI and federated interface. CMDB Administrator #include "ar. activateOption. status A list of zero or more notes. or expanded and launched. datasetId. instanceId. Return values instanceIdList The list of instance GUIDs. warnings. federatedInstanceId. Depending on a flag you specify when you call this function. CMDB_FEDERATION_ACTIVATION_NONE 0: Activate none. The data in the return values are based on the dataset ID specified. classNameId The class name of the specified CI for which the federated instance is to be expanded or launched. It contains information about the user requesting the operation.0. or errors generated from a call of this function. instanceId The instance ID of the specified instance for which the federated instance is to be expanded or launched. activateOption The mask number that indicates if the federated instance is to be launched and expanded. 178 Chapter 5—C API functions and data structures . federatedInstanceId The instance ID of the federated instance that is to be expanded or launched. and which session is used to perform it. Return values federatedInfo The expanded federated instance information. status A list of zero or more notes.1 control The control record for the operation. warnings. CMDB_FEDERATION_ACTIVATION_LAUNCH 1 << 1: Activate and launch. sessionId. and server subclasses are required.BMC Atrium CMDB 2. The user. no launch. datasetId The unique identifier for the dataset. where that operation is to be performed. This parameter is returned only if you specify a value of 1in the activateOption parameter. CMDB_FEDERATION_ACTIVATION_EXPAND 1 << 0: Only activate. h" #include "cmdb. instanceId. and which session is used to perform it. *numMatches. *attributeGetList. Functions 179 . where that operation is to be performed. It contains information about the user requesting the operation. maxRetrieve. *classNameId.Developer’s Reference Guide Audit functions The audit functions retrieve audit data for a class. The audit option must be set for the attribute’s characteristic to get the audit data. The user.h" #include "arextern. *qualifier. sessionId. *auditValueListList. The C API functions for audit include: ! ! CMDBGetCopyAuditData (page 179) CMDBGetLogAuditData (page 181) CMDBGetCopyAuditData Description Retrieves a copy of the specified CI instance if the attribute data for the instance is modified. firstRetrieve. and server subclasses are required. *sortList. *status) Privileges Synopsis control The control record for the operation. CMDB Administrator #include "ar. auditTimestamp.h" int CMDBGetCopyAuditData( ARControlStruct CMDBClassNameId ARNameType ARTimestamp CMDBQualifierStruct ARNameList CMDBSortList unsigned int unsigned int CMDBAuditValueListList unsigned int ARStatusList *control. maxRetrieve The maximum number of entries to retrieve for the qualification. an error is returned. instanceId The instance ID of the specified CI instance for which a copy of the audit data is to be retrieved. relational. and arithmetic (numeric data types only) operations. sortList The sort order for the attributes. If auditTimestamp is 0.0. The qualification can include one or more attributes and any combination of conditional. 180 Chapter 5—C API functions and data structures . qualifier A query that determines the set of CI instances to retrieve. If the audit option at the CI class-level is disabled. The CI instances with the data and time greater than or equal to the auditTimestamp will be retrieved. numMatches The number of CI instance entries that matched the specified qualification. Return values auditValueListList The list of values for the specified attributes. Use this parameter to limit the amount of data returned if the query does not narrow the list. CMDB_START_WITH_FIRST_ENTRY represents the first entry and is the default value if the value is not set. firstRetrieve The first instance to retrieve for the qualification. then all the audit data is retrieved.1 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. attributeGetList A list of attribute names for which the audit data is to be retrieved. Specify CMDB_NO_MAX_LIST_RETRIEVE to assign no maximum. auditTimestamp The data and time information for the instance.BMC Atrium CMDB 2. *status) control The control record for the operation.h" #include "cmdb. or errors generated from a call of this function. *classNameId. instanceId. instanceId The instance ID of the specified CI instance for which the audit log is to be retrieved. CMDB Administrator #include "ar. and which session is used to perform it.h" #include "arextern. sessionId. where that operation is to be performed. *auditLog.h" int CMDBGetLogAuditData( ARControlStruct CMDBClassNameId ARNameType ARTextString ARStatusList *control. or errors generated from a call of this function. status A list of zero or more notes. The user. warnings. warnings. classNameId The class name (class name and namespace combination) of the specified CI instance for which the audit log is to be retrieved. and server subclasses are required. Functions 181 . the AuditLog option must be set at the class-level. CMDBGetLogAuditData Description Privileges Synopsis Retrieves the audit log for the specified CI instance.Developer’s Reference Guide status A list of zero or more notes. Return values auditLog The audit log information for the specified instance. For you to retrieve the audit log. It contains information about the user requesting the operation. Attributes. 182 Chapter 5—C API functions and data structures . Graph Query. } CMDBClassTypeInfo. then the relationship information is retrieved. The class data structures include: ! ! ! ! CMDBClassTypeInfo (page 182) CMDBClassRelationship (page 183) CMDBIndexList (page 184) CMDBIndexStruct (page 185) CMDBClassTypeInfo The CMDBClassTypeInfo structure is used to hold the class type information.1 Data structures The C API data structures are categorized by function types. (CMDB_CLASS_TYPE_RELATIONSHIP). union { CMDBClassRelationship relationshipInfo. } u. typedef struct CMDBClassTypeInfo { unsigned int classType. 1—The class type is regular. The CMDBClassTypeInfo structure consists of the following elements: classType An integer value identifying the type for a class. such as class functions and attribute functions.0. General purpose. Class structures Class structures are data structures for CI and relationship definitions (data model). (CMDB_CLASS_TYPE_REGULAR). Export and Import. 2—The class type is relationship. and Reconciliation Engine structures. relationshipInfo If the class type specified in the classType parameter is relationship.BMC Atrium CMDB 2. The data structures categories include Class. isRole2WeakReference A Boolean value indicating whether role 2 is a weak reference: TRUE—The role 2 class is a weak reference. cardinality must be one-to-one or many-to-many. An integer identifying the cardinality of the relationship between the related classes: 1—One-to-one. ARNameType roleNames[2]. one instance of a class is associated with a single instance of another class (CMDB_CLASS_RELATIONSHIP_CARDINALITY_1). many instances of a class are associated with many instances of another class (CMDB_CLASS_RELATIONSHIP_CARDINALITY _MANY_MANY). ARBoolean isRole2WeakReference. 4—Many-to-many. The role names for the two classes that are a part of the relationship. Data structures 183 . Role 2 is a weak entity and it uses role 1’s primary key as part of its own key. typedef struct CMDBClassRelationship { CMDBClassNameID relClassNames[2]. CMDBWeakPropagatedAttrsList weakPropagatedAttrsList. one instance of a class is associated with one or more instances of another class (CMDB_CLASS_RELATIONSHIP_CARDINALITY_1 _MANY). The CMDBClassRelationship structure consists of the following elements: relClassNames[2] roleNames[2] cardinality The names of the two classes that are a part of the relationship. If the value is TRUE. } CMDBClassRelationship.Developer’s Reference Guide CMDBClassRelationship The CMDBClassRelationship structure is used to hold the relationship information of the CI classes. 2—Many-to-one. unsigned int cardinality. 3—One-to-many. ARBoolean cascadeDelete. one or more instances of a class are associated with one instance of another class (CMDB_CLASS_RELATIONSHIP_CARDINALITY _MANY_1). FALSE—The role 2 class is not a weak reference. 184 Chapter 5—C API functions and data structures . Each index can include from 1 to 16 attributes (limited by AR_MAX_INDEX_subclasses). The CMDBIndexList structure consists of the following elements: numItems indexList An integer value indicating the number of CMDBIndexStruct items in the list.BMC Atrium CMDB 2. Diary attributes and character attributes larger than 255 bytes cannot be indexed.0. cascadeDelete A Boolean value indicating the type of delete allowed between the related classes: TRUE—A cascade delete is allowed. CMDBIndexList The CMDBIndexList structure is used to hold index information for the class.1 weakPropagatedAttrsList If the value of isRole2WeakReference is TRUE. FALSE—A cascade delete is not allowed. indicates the list of attributes that are propagated from the role 1 class to the role 2 class. CMDBIndexStruct *indexList. Deleting an instance in one class also deletes the instance in the related class. The set of zero or more CMDBIndexStruct items defined for the class. Note: This item is applicable only for one-to-one and one-to-many relationships. } CMDBIndexList. typedef struct CMDBIndexList { unsigned int numItems. FALSE—The index key is not unique. Data structures 185 . ARBoolean isPrimaryKey. ARNameType attributeName[AR_MAX_INDEX_subclasses]. A Boolean value indicating if the index key must be unique: TRUE—The index key is unique. FALSE—The index key is not a primary key index. indexName The name of the index. isPrimaryKey A Boolean value indicating whether to make this index a primary key index: TRUE—The index key is a primary key index.Developer’s Reference Guide CMDBIndexStruct The CMDBIndexStruct structure is used to hold the attributes to index. The names of attributes to index. ARNameType indexName. } CMDBIndexStruct. ARBoolean unique. The CMDBIndexStruct structure consists of the following elements: numAttributes attributeName unique An integer value indicating the number of attributes to index. typedef struct CMDBIndexStruct { unsigned int numAttributes. 1 Attribute structures Attribute structures are data structures for defining attributes. The attribute data structures include: ! ! ! ! ! ! ! ! ! CMDBAttributeGetStruct (page 186) CMDBAttributeLimitList (page 187) CMDBAttributeLimit (page 187) CMDBAttributNameId (page 192) CMDBAttributeValueList (page 192) CMDBAttributeValueListList (page 193) CMDBAttributeValueStruct (page 193) CMDBWeakPropagatedAttrs (page 194) CMDBWeakPropagatedAttrsList (page 194) CMDBAttributeGetStruct The CMDBAttributeGetStruct structure is used to hold the attributes to retrieve. 2—Retrieve all attributes except hidden attributes (CMDB_GET_ATTR_NONHIDDEN). 3—Retrieve all attributes (CMDB_GET_ATTR_ALL). The CMDBAttributeGetStruct structure consists of the following elements: type An integer value indicating the type of attributes to retrieve. } CMDBAttributeGetStruct. 1—Retrieve all attributes in attributeNameList (CMDB_GET_ATTR_CUSTOM_LIST). } u. 186 Chapter 5—C API functions and data structures .0. union { ARNameList attributeNameList. attributeNameList The name of the attribute list. typedef struct CMDBAttributeGetStruct { unsigned int type.BMC Atrium CMDB 2. typedef struct CMDBAttributeLimitList { unsigned int numItems. Data structures 187 . int rangeHigh. unsigned int qbeMatchOperation. double rangeHigh. union { struct { int rangeLow. int precision. unsigned int menuStyle. ARNameType charMenu. } realLimits. struct { char *rangeLow. The CMDBAttributeLimitList structure consists of the following elements: numItems limitList An integer value indicating the number of CMDBAttributeLimit items in the list. CMDBAttributeLimit *limitList. } CMDBAttributeLimitList. } integerLimits. The list of attribute limit items that hold the limit definitions for the attribute. } charLimits. char *format. char *pattern. typedef struct CMDBAttributeLimit { unsigned int dataType. CMDBAttributeLimit The CMDBAttributeLimit structure is used to hold the data limit definitions for an attribute list of any data type.Developer’s Reference Guide CMDBAttributeLimitList The CMDBAttributeLimitList structure is used to hold a list of data limit definitions for attributes. struct { double rangeLow. struct { int maxLength. 0. A 64-bit floating-point value. Specifies a NULL value. }CMDBAttributeLimit. } attachLimits. } enumLimits. struct { char *rangeLow. An integer identifying the particular keyword (defined in cmdb. The following table describes the possible values. A 32-bit signed integer value. ARCurrencyDetailList functionalCurrencies. int precision. AREnumItemList customList. } dateLimits.h). } u. } decimalLimits. struct { unsigned long maxSize. union { ARNameList regularList. ARCurrencyDetailList allowableCurrencies. int precision.1 char *rangeHigh. int maxDate. ARNameType attachmentPoolName. struct { int minDate. The CMDBAttributeLimit structure consists of the following element: dataType An integer value indicating the data type of the value being passed. } currencyLimits. } u.BMC Atrium CMDB 2. 0 1 CMDB_ATTR_DATA_TYPE_NULL CMDB_ATTR_DATA_TYPE_KEYWORD 2 3 CMDB_ATTR_DATA_TYPE_INTEGER CMDB_ATTR_DATA_TYPE_REAL 188 Chapter 5—C API functions and data structures . char *rangeHigh. struct { unsigned int listStyle. A NULL pointer of this type is equivalent to CMDB_ATTR_DATA_TYPE_NU LL. for example. You must specify an attribute limit by using ARNameList to define string values for each selection. Values must be specified in C locale. of the current day. The number of seconds since 12:00 a. 1970). 7 CMDB_ATTR_DATA_TYPE_TIME 10 CMDB_ATTR_DATA_TYPE_DECIMAL 11 12 13 CMDB_ATTR_DATA_TYPE_ATTACH CMDB_ATTR_DATA_TYPE_CURRENCY CMDB_ATTR_DATA_TYPE_DATE 14 37 CMDB_ATTR_DATA_TYPE_TIME_OF_DAY CMDB_ATTR_DATA_TYPE_ATTACH_POOL A pool for grouping attachments. A NULL pointer of this type is equivalent to CMDB_ATTR_DATA_TYPE_NU LL. An attachment attribute. 6 CMDB_ATTR_DATA_TYPE_ENUM A set of integer values (beginning with zero) that represent possible selection values as an indexed list. 1234. A Julian date number (number of days since January 1. Data structures 189 . A UNIX-style date and time stamp (number of seconds since midnight January 1.Developer’s Reference Guide 4 CMDB_ATTR_DATA_TYPE_CHAR A null-terminated string that requires freeing allocated space. A currency attribute. 5 CMDB_ATTR_DATA_TYPE_DIARY A null-terminated string that requires freeing allocated space.m. A fixed-point decimal attribute.56. 4713 BC). It consists of the following elements: rangelow rangeHigh precision The low range of the custom characteristic for the decimal data type. The high range of the custom characteristic for the decimal data type. indicates a list of a maximum of 4 items. The high range of the custom characteristic for the integer data type. It consists of the following elements: rangelow rangeHigh precision The low range of the custom characteristic for the real data type. Defining decimal limits The decimalLimits structure is used to hold data limit definitions for the decimal data type. for example. Defining character limits The charLimits structure is used to hold data limit definitions for the character data type. specified as L<n>. The number of integers allowed for the decimal data type. NULL indicates a list is not used. The high range of the custom characteristic for the real data type. L4. Used for character list data. 190 Chapter 5—C API functions and data structures . where n is the number of items in the list.0. Defining real limits The realLimits structure is used to hold data limit definitions for the real data type. It consists of the following elements: maxLength format The maximum length of the custom characteristic for the character data type. with each item separated by a semicolon (.1 Defining integer limits The integerLimits structure is used to hold data limit definitions for the integer data type.BMC Atrium CMDB 2. The number of integers allowed for the real data type. It consists of the following elements: rangeLow rangeHigh The low range of the custom characteristic for the integer data type.). The number of integers allowed to the right of the decimal point for the currency data type. Defining currency limits The currencyLimits structure is used to hold data limit definitions for the currency data type. It consists of the following elements: minDate maxDate The minimum limit for the date data type. Data structures 191 . It consists of the following element: regularList A name list of possible selection values for the enum data type. Defining attachment limits The attachLimits structure is used to hold data limit definitions for the attachment data type. A value of 0 (zero) represents an unlimited size. Default list of allowable currencies when new currency attributes are created. It consists of the following elements: maxSize attachmentPoolName The maximum size in bytes of an attachment data type.Developer’s Reference Guide Defining date limits The dateLimits structure is used to hold data limit definitions for the date data type. Defining enum limits The enumLimits structure is used to hold data limit definitions for the enum data type. The high range of the custom characteristic for the currency data type. The maximum limit for the date data type. Default list of functional currencies when new currency attributes are created. It consists of the following elements: rangelow rangeHigh precision functionalCurrencies allowableCurrencies The low range of the custom characteristic for the currency data type. The name of the attachment pool attribute this attachment attribute is associated with. } CMDBAttributeValueList. ARNameType className. 192 Chapter 5—C API functions and data structures . CMDBAttributeValueStruct *attributeValueList. ARNameType attributeName.BMC Atrium CMDB 2. CMDBAttributeValueList The CMDBAttributeValueList structure holds a list of values for an attribute. } CMDBAttributeNameId. typedef struct CMDBAttributeValueList { unsigned int numItems. The name of the class.0. A list of CMDBAttributeValueStruct items. The CMDBAttributeNameId structure consists of the following elements: namespaceName className attributeName The namespace name for the class. The CMDBAttributeValueList structure consists of the following elements: numItems attributeValueList An integer value indicating the number of CMDBAttributeValueStruct items in the list. typedef struct CMDBAttributeNameId { ARNameType namespaceName.1 CMDBAttributNameId The CMDBAttributeNameId structure is used to hold the namespace name and the class name information for a class. The name of the attribute. The value of the attribute.Developer’s Reference Guide CMDBAttributeValueListList The CMDBAttributeValueListList structure holds a list of values for an attributes list. typedef struct CMDBAttributeValueStruct { ARNameType attributeName. CMDBAttributeValueStruct The CMDBAttributeValueStruct structure is used to hold values for attributes. The CMDBAttributeValueListList structure consists of the following elements: numItems attributeValueListList An integer value indicating the number of CMDBAttributeValueList items in the list. } CMDBAttributeValueListList. typedef struct CMDBAttributeValueListList { unsigned int numItems. } CMDBAttributeValueStruct. Data structures 193 . ARValueStruct attributeValue. CMDBAttributeValueList *attributeValueListList. The CMDBAttributeValueStruct structure consists of the following elements: attributeName attributeValue The name of the attribute. A list of CMDBAttributeValueList items. The specified source and target attributes must already exist on the role one and role two classes. typedef struct CMDBWeakPropagatedAttrs { ARNameType sourceAttributeName. CMDBWeakPropagatedAttrsList The CMDBWeakPropagatedAttrsList structure is used to hold a list of CMDBWeakPropagatedAttrs structures. ARNameType targetAttributeName.BMC Atrium CMDB 2. The list of attributes to propagate from the role one class to the role two class. This list describes a mapping of which attribute values from the role one class will be propagated to the role two class. } CMDBWeakPropagatedAttrsList. The CMDBWeakPropagatedAttrs structure consists of the following elements: sourceAttributeName The name of the attribute on the role one class. typedef struct CMDBWeakPropagatedAttrsList { unsigned int numItems.1 CMDBWeakPropagatedAttrs The CMDBWeakPropagatedAttrs structure is used to hold a list of source and target attributes to use for attribute value propagation when isRole2WeakReference is TRUE. 194 Chapter 5—C API functions and data structures . targetAttributeName The name of the attribute on the role two class. } CMDBWeakPropagatedAttrs.0. The CMDBWeakPropagatedAttrsList structure consists of the following elements: numItems attrsList An integer value indicating the number of CMDBWeakPropagatedAttrs items in the list. CMDBWeakPropagatedAttrs *attrsList. The CMDBSortList structure consists of the following elements: numItems sortList An integer value indicating the number of CMDBSortStruct items in the list. unsigned int sortOrder. Data structures 195 . 1—Sort attributes in ascending order (CMDB_SORT_ASCENDING). CMDBSortStruct *sortList.Developer’s Reference Guide CMDBSortList The CMDBSortList structure is used to hold a list of attributes to sort. } CMDBSortStruct. A list of CMDBSortStruct items. typedef struct CMDBSortStruct { ARNameType attributeName. } CMDBSortList. The CMDBSortStruct structure consists of the following elements: attributeName sortOrder The name of the attribute to sort. CMDBSortStruct The CMDBSortStruct structure is used to hold the attribute to sort. typedef struct CMDBSortList { unsigned int numItems. 2—Sort attributes in descending order (CMDB_SORT_DESCENDING). An integer value indicating sort order. The CMDBClassNameIDList structure consists of the following elements: numItems classNameIdList An integer value indicating the number of CMDBClassNameIditems in the list. } CMDBClassNameId. typedef struct CMDBClassNameIdList { unsigned int numItems.0. 196 Chapter 5—C API functions and data structures . The instance data structures include: ! ! ! CMDBClassNameId (page 196) CMDBClassNameIdList (page 196) CMDBQualifierStruct (page 197) CMDBClassNameId The CMDBClassNameId structure is used to hold the namespace name and the class name information for a class. The CMDBClassNameId structure consists of the following elements: namespaceName className The namespace name of the class. } CMDBClassNameIdList. CMDBClassNameId *classNameIdList. ARNameType className.BMC Atrium CMDB 2. The name of the class.1 Instance structures Instance structures are data structures for instance data. typedef struct CMDBClassNameId { ARNameType namespaceName. CMDBClassNameIdList The CMDBClassNameIdList structure is used to hold a list of CMDBClassNameId structures. The list of class names. The CMDBQualifierStruct structure consists of the following elements: qualifierType An integer value indicating the type of qualifier. qualifierStruct Data structures 197 . qualifierString The qualification in string format. } CMDBQualifierStruct. The qualification in structure format. and arithmetic (numeric data types only) operations. } u. 2—The qualifier is a structure (CMDB_QUALIFIER_TYPE_STRUCT). relational. The qualification string can include one or more attributes and any combination of conditional. 1—The qualifier is a string (CMDB_QUALIFIER_TYPE_STRING). typedef struct CMDBQualifierStruct { unsigned int qualifierType.Developer’s Reference Guide CMDBQualifierStruct The CMDBQualifierStruct structure is used to hold the qualifier string based on the qualifier type that is provided. ARQualifierStruct qualifierStruct. union { char *qualifierString. 0. unsigned int majorVer. unsigned int patchNum. The minor part (succeeding the dot) of the version number information. unsigned int minorVer. The maintenance version number. The general purpose data structures include: ! ! CMDBVersionInfo (page 198) CMDBVersionInfoList (page 198) CMDBVersionInfo The CMDBVersionInfo structure is used to hold version information for the BMC Atrium CMDB components. typedef struct CMDBVersionInfoList { unsigned int numItems. typedef struct CMDBVersionInfo { ARNameType applicationId. } CMDBVersionInfo.1 General purpose structures General purpose structures are structures for miscellaneous uses. The CMDBVersionInfo structure consists of the following elements: applicationId applicationName majorVer minorVer maintenanceVer patchNum An ID for the application. The name for the application. The patch number. The major part (preceding the dot) of the version number information. CMDBVersionInfoList The CMDBVersionInfoList structure is used to hold a list of version information elements for the CMDB component. ARNameType applicationName. unsigned int maintenanceVer. CMDBVersionInfo *versionInfoList. 198 Chapter 5—C API functions and data structures . } CMDBVersionInfoList.BMC Atrium CMDB 2. Export and import structures Export/Import structures are used for export and import functions.Developer’s Reference Guide The CMDBVersionInfoList structure consists of the following elements: numItems versionInfoList The number of items in the list. The export and import structures include: ! ! ! ! ! ! ! ! ! ! CMDBItemTypeClass (page 199) CMDBItemTypeAttribute (page 200) CMDBExportItem (page 200) CMDBExportItemList (page 201) CMDBExportItemStruct (page 201) CMDBXMLExportItemList (page 201) CMDBImportItem (page 202) CMDBImportItemList (page 203) CMDBImportItemStruct (page 204) CMDBXMLImportItemList (page 203) CMDBItemTypeClass The CMDBItemTypeClass data structure is used to hold the class name information. The CMDBItemTypeClass structure consists of the following elements: classNameId The ID for the class. typedef struct CMDBItemTypeClass { CMDBClassNameId classNameId. A list of version information. }CMDBItemTypeClass. Data structures 199 . 1—Export class (CMDB_ITEM_TYPE_CLASS).0 release of the BMC Atrium CMDB. union { CMDBItemTypeClass CMDBItemTypeAttribute } }CMDBExportItem. if the itemType is CMDB_ITEM_TYPE_ATTRIBUTE. classItem attributeItem The class items to import. attributeItem. if the itemType is CMDB_ITEM_TYPE_CLASS. ARNameList attribNameList. classItem.BMC Atrium CMDB 2. The CMDBExportItem structure consists of the following elements: itemType The type of item to export.0. CMDBExportItem The CMDBExportItem data structure is used to hold the items to export for the specified item type. This data structure is deprecated in the 2. 2—Export attribute (CMDB_ITEM_TYPE_ATTRIBUTE). The list of attribute names. typedef struct CMDBItemTypeAttribute { CMDBClassNameId classNameId. The attribute items to import. 200 Chapter 5—C API functions and data structures . 0—No item to export (CMDB_ITEM_TYPE_NONE). }CMDBItemTypeAttribute.1 CMDBItemTypeAttribute The CMDBItemTypeAttribute data structure is used to hold a list of attribute information. typedef CMDBExportItem { unsigned int itemType. The CMDBItemTypeAttribute structure consists of the following elements: classNameId attributeNameList The ID of the class name. The CMDBXMLExportItemList structure consists of the following elements: numItems exportItemList An integer value indicating the number of CMDBXMLExportItem items in the list.Developer’s Reference Guide CMDBExportItemList The CMDBExportItemList data structure is used to hold a list of CMDBExportItemStruct structures.} CMDBExportItemStruct.0 release of the BMC Atrium CMDB. numItems. CMDBExportItemStruct The CMDBExportItemStruct data structure is used to hold a single item to export.0 release of the BMC Atrium CMDB. unsigned long exportOption. The CMDBExportItemList structure consists of the following elements: numItems exportItemList An integer value indicating the number of CMDBExportItemStruct items in the list. typedef struct CMDBXMLExportItemList unsigned int CMDBXMLExportItemStruct }CMDBXMLExportItemList. *exportItemList. Data structures 201 . A structure that holds the list of items to export. } u. typedef struct CMDBExportItemStruct { unsigned int itemType. typedef struct CMDBExportItemList { unsigned int numItems. } CMDBExportItemList. CMDBClassNameId classNameId. CMDBXMLExportItemList The CMDBXMLExportItemList data structure is used to hold a list of items to export. This data structure is deprecated in the 2. This data structure is deprecated in the 2. CMDBExportItemStruct *exportItemList. The list of items to export. union { char *qualifier. 202 Chapter 5—C API functions and data structures . classNameId qualifier The namespace name and the class name of the class that contains the items to export. To use more than one export option. This item is applicable only if CMDB_ITEM_TYPE_INSTANCE_DATA is set. The qualification can include one or more attributes and any combination of conditional. 4—Export subclasses (CMDB_EXPORT_OPTION_SUB_CLASSES). add the value for each option. Note: This item is applicable only if CMDB_ITEM_TYPE_META_DATA is set. relational. attributeItem. CMDBImportItem The CMDBImportItem data structure is used to hold the items to import for the specified item type. This data structure is deprecated in the 2. A query that determines the set of entries to export. typedef CMDBImportItem { unsigned int itemType. For example. 1—Export the class only (CMDB_EXPORT_OPTION_CLASS_ONLY). and arithmetic (numeric data types only) operations.0 release of the BMC Atrium CMDB. 2—Export superclasses (CMDB_EXPORT_OPTION_SUPER_CLASSES). 2—Export instance data. (CMDB_ITEM_TYPE_INSTANCE_DATA).0. 1—Export (CMDB_ITEM_TYPE_META_DATA). union { CMDBItemTypeClass CMDBItemTypeAttribute } }CMDBImportItem. exportOption An integer value indicating the type of classes to export. classItem.BMC Atrium CMDB 2.1 The CMDBExportItemStruct structure consists of the following elements: itemType An integer value indicating the type of information to export. 3 indicates the class and superclasses will be exported. typedef struct CMDBImportItemList { unsigned int numItems. CMDBImportItemList The CMDBImportItemList data structure is used to hold a list of items to import. This data structure is deprecated in the 2. A structure that holds the list of items to import. 0—No item to import (CMDB_ITEM_TYPE_NONE). 2—Import attribute (CMDB_ITEM_TYPE_ATTRIBUTE). CMDBXMLImportItemList The CMDBXMLImportItemList data structure is used to hold a list of XML items to import. }CMDBXMLImportItemList.Developer’s Reference Guide The CMDBImportItem structure consists of the following elements: itemType The type of item to import. 1—Import class (CMDB_ITEM_TYPE_CLASS). } CMDBImportItemList. CMDBImportItemStruct *importItemList. The attribute item to import. A NULL value indicates that all items in the specified directory will be imported.0 release of the BMC Atrium CMDB. classItem attributeItem The class item to import. CMDBXMLImportItemStruct *importItemList. typedef struct CMDBXMLImportItemList unsigned int numItems. The CMDBImportItemList structure consists of the following elements: numItems importItemList An integer value indicating the number of CMDBImportItemStruct items in the list. Data structures 203 . typedef struct CMDBImportItemStruct { unsigned int itemType. The CMDBImportItemStruct structure consists of the following elements: itemType An integer value indicating the type of information to import.0 release of the BMC Atrium CMDB. } CMDBImportItemStruct. CMDBClassNameId classNameId. A structure that holds the list of XML items to import. CMDBImportItemStruct The CMDBImportItemStruct data structure is used to hold the items to import. 1—Import (CMDB_ITEM_TYPE_META_DATA). 204 Chapter 5—C API functions and data structures . This data structure is deprecated in the 2.BMC Atrium CMDB 2.1 The CMDBXMLImportItemList structure consists of the following elements: numItems exportItemList An integer value indicating the number of CMDBXMLImportItem items in the list. 2—Import instance data (CMDB_ITEM_TYPE_INSTANCE_DATA) classNameId The namespace name and the class name of the class that contains the items to import. unsigned long importOption.0. Developer’s Reference Guide importOption An integer value indicating how the import of instances is handled if any duplicates are found during the import. 3—Delete the existing entry and create a new entry in its place if the Entry ID attribute and the ID specified already exist in the target class (AR_MERGE_ENTRY_DUP_OVERWRITE). Note: This item is applicable only if CMDB_ITEM_TYPE_META_DATA is set. These constants are the same as used by the ARMergeEntry function in the CMDB C API. 1—Generate an error (AR_MERGE_ENTRY_DUP_ERROR). For more information. see the CMDB ar. Data structures 205 . These option values are mutually exclusive. 4—Update the attributes specified in the existing entry if the Entry ID attribute and the ID specified already exist in the target class (AR_MERGE_ENTRY_DUP_MERGE). 2—Create a new entry with a new ID if the Entry ID attribute and the ID specified already exist in the target class (AR_MERGE_ENTRY_DUP_NEW_ID). 5—Create an entry with a new ID (AR_MERGE_ENTRY_NEW_ID).h file. The CMDBGetObjectList structure consists of the following elements: numItems objectList An integer value indicating the number of CMDBGetObjectStruct items in the list. typedef struct CMDBGetObjectStruct { CMDBClassNameId classNameId. ARNameType instanceId. } CMDBGetObjectList. } CMDBGetObjectStruct.BMC Atrium CMDB 2. The list of CI instances. CMDBAttributeValueList attributeValueList. The export and import data structures include: ! ! ! ! ! ! ! ! CMDBGetObjectList (page 206) CMDBGetObjectStruct (page 206) CMDBGetRelationList (page 207) CMDBGetRelationStruct (page 207) CMDBGraphAdjacentList (page 208) CMDBGraphAdjacentStruct (page 208) CMDBGraphList (page 209) CMDBGraphStruct (page 209) CMDBGetObjectList The CMDBGetObjectList data structure is used to hold a list of CI instances.1 Graph query structures Graph query structures are data structures used in graph queries.0. 206 Chapter 5—C API functions and data structures . CMDBGetObjectStruct The CMDBGetObjectStruct data structure is used to hold a CI instance. typedef struct CMDBGetObjectList { unsigned int numItems. CMDBGetObjectStruct *objectList. ARNameType roleNames[2]. Data structures 207 . CMDBClassNameId relatedClassNames[2]. CMDBAttributeValueList attributeValueList. ARNameType relatedInstanceIds[2]. The list of relationships. The list of attribute values. typedef struct CMDBGetRelationList { unsigned int numItems. typedef struct CMDBGetRelationStruct { CMDBClassNameId classNameId. ARNameType instanceId. The instance ID of the related class. CMDBGetRelationStruct The CMDBGetRelationStruct data structure is used to hold a single relationship. } CMDBGetRelationStruct. The CMDBGetRelationList structure consists of the following elements: numItems relationList An integer value indicating the number of CMDBGetRelationStruct items in the list. CMDBGetRelationStruct *relationList. CMDBGetRelationList The CMDBGetRelationList data structure is used to hold a list of relationships. The role names for the two classes that make up the relationship. The instance ID of the object. } CMDBGetRelationList. ARNameType relatedClassIds[2]. The CMDBGetRelationStruct structure consists of the following elements: classNameId instanceId roleNames[2] The class name ID of the relationship class. relatedClassNames[2] The names of the two classes that make up the relationship.Developer’s Reference Guide The CMDBGetObjectStruct structure consists of the following elements: classNameId instanceId attributeValueList The class name ID for the class. relQual relGetAttribute objClassNameId The qualification string that qualifies the relationship. The related attribute to retrieve from the relationship. CMDBGraphAdjacentStruct *adjacents. The CMDBGraphAdjacentList structure consists of the following elements: numItems adjacents An integer value indicating the number of CMDBGraphAdjacentStruct items in the list. The object class name. CMDBAttributeGetStruct objGetAttribute. typedef struct CMDBGraphAdjacentStruct { CMDBClassNameId relClassNameId.BMC Atrium CMDB 2. The CMDBGraphAdjacentStruct structure consists of the following elements: relClassNamesNameId The name of the class that makes up the relationship. CMDBAttributeGetStruct relGetAttribute. The list of relationship attribute values. This item can be NULL. CMDBQualifierStruct relQual.0. } CMDBGraphAdjacentStruct.1 relatedClassIds[2] relatedInstanceIds[2] attributeValueList The class IDs of the two classes that make up the relationship. ARNameType extensionId. 208 Chapter 5—C API functions and data structures . CMDBGraphAdjacentStruct The CMDBGraphAdjacentStruct data structure is used to hold an adjacent node. CMDBQualifierStruct objQual. The list of adjacent nodes. typedef struct CMDBGraphAdjacentList { unsigned int numItems. CMDBClassNameId objClassNameId. CMDBGraphAdjacentList The CMDBGraphAdjacentList data structure is used to hold a list of adjacent nodes in CMDBGraphAdjacentStruct. The instance IDs of the two classes that make up the relationship. } CMDBGraphAdjacentList. The CMDBGraphStruct structure consists of the following elements: classNameId extensionId adjacentList The name of the class for the object (node). The extension ID of the node. CMDBGraphList The CMDBGraphList data structure is used to define the query graph list in the CMDBGraphQuery function. The qualification of the object. The graph structure. The list of adjacent objects (nodes). typedef struct CMDBGraphList { unsigned int numItems.Developer’s Reference Guide extensionId objQual objGetAttribute The extension ID of the object. This item can be NULL. This item can contain an empty string. The CMDBGraphList structure consists of the following elements: numItems graph An integer value indicating the number of CMDBGraphStruct items in the list. typedef struct CMDBGraphStruct { CMDBClassNameId classNameId. } CMDBGraphStruct. CMDBGraphStruct The CMDBGraphStruct data structure is used to hold each graph node in the query graph. Data structures 209 . CMDBGraphAdjacentList adjacentList. The object attribute to retrieve. CMDBGraphStruct *graph. ARNameType extensionId. } CMDBGraphList. the default locale will be used.BMC Atrium CMDB 2. The CMDBUIComponentInfo structure consists of the following elements: classId locale An integer value indicating the class ID for the UI component. char *tag4. If no locale is specified in this subclasses. The UI data structures include: ! ! ! CMDBUIComponentInfo (page 210) CMDBUIComponentResult (page 211) CMDBUIComponentResultList (page 212) CMDBUIComponentInfo The CMDBUIComponentInfo data structure is used to hold the UI components to retrieve. char *encodedQual. typedef struct CMDBUIComponentInfo { ARNameType classId.0. The name of the locale specific to the component. char *tag5. 210 Chapter 5—C API functions and data structures . char *tag2. char *tag3. } CMDBUIComponentInfo.1 User interface components structures The user interface (UI) component structures are data structures used in UI component functions. ARLocaleType locale. char *tag1. unsigned int componentType. Information tag used to filter a specific component type. The encoded qualifier for the UI component query.Developer’s Reference Guide componentType The integer value indicating the component type. tag1 tag2 tag3 tag4 tag5 encodedQual Information tag used to filter a specific component type. Contains the component data string. Information tag used to filter a specific component type.) (CMDB_COMPONENT_TYPE_LINE). Information tag used to filter a specific component type. CMDBUIComponentResult The CMDBUIComponentResult data structure is used to hold the component query result. Information tag used to filter a specific component type. 1—The icon type component to retrieve (CMDB_COMPONENT_TYPE_ICON). char *dataString. typedef struct CMDBUIComponentResult { ARNameType instanceId. } CMDBUIComponentResult. Contains the component information for the specific instance. ARAttachStruct *attachVal. The CMDBUIComponentResult structure consists of the following elements: instanceId componentInfo dataString attachVal An integer value indicating the class ID of the UI component class. 0—No component information to retrieve (CMDB_COMPONENT_TYPE_NONE). Contains the attachment for the component. Data structures 211 . CMDBUIComponentIno componentInfo. 3—The tooltip type component to retrieve (CMDB_COMPONENT_TYPE_TOOLTIP). 4—The user interface graphical line information to retrieve (This option is currently not being used. 2—The localized label type component to retrieve (CMDB_COMPONENT_TYPE_LOCALIZED_LABEL). CMDBREJobRunInfo *jobRunList. CMDBUIComponentResult *componentResList.0. Reconciliation Engine structures Reconciliation Engine structures are data structures used in Reconciliation Engine queries. typedef struct CMDBREJobRunInfoList { unsigned int numItems. Contains a list of UI components. The CMDBUIComponentResultList structure consists of the following elements: numItems componentResultList An integer value indicating the number of CMDBUIComponent items in the list.BMC Atrium CMDB 2. } CMDBUIComponentResultList. The Reconciliation Engine data structures include: ! ! ! ! ! ! CMDBREJobRunInfoList (page 212) CMDBREJobRunInfo (page 213) CMDBREClassQualStruct (page 213) CMDBREClassQualList (page 214) CMDBREDatasetPair (page 214) CMDBREDatasetList (page 215) CMDBREJobRunInfoList The CMDBREJobRunInfoList data structure is used to hold a list of Reconciliation Engine jobs that are currently running.1 CMDBUIComponentResultList The CMDBUIComponentResultList data structure is used to hold the component query result. } CMDBREJobRunInfoList. typedef struct CMDBUIComponentResultList { unsigned int numItems. 212 Chapter 5—C API functions and data structures . The CMDBREJobRunInfo structure consists of the following elements: jobRunId jobInstanceId jobName startTime endTime jobStatus The Reconciliation Engine job run ID. ARTimestamp startTime. The current status of the Reconciliation Engine job.Developer’s Reference Guide The CMDBREJobRunInfoList structure consists of the following elements: numItems jobRunList An integer value indicating the number of CMDBREJobRunInfo items in the list. typedef struct CMDREBClassQualStruct { ARNameType classId. typedef struct CMDBREJobRunInfo { ARNameType jobRunId. The name of the Reconciliation Engine job. ARTimestamp endTime. ARNameType jobInstanceId. The instance ID of the Reconciliation Engine job. The list of Reconciliation Engine jobs to execute. The end time of the job. CMDBQualifierStruct *qual. CMDBREClassQualStruct The CMDBREClassQualStruct data structure is used to hold information about the class qualification. CMDBREJobRunInfo The CMDBREJobRunInfo data structure is used to hold information about a currently running Reconciliation Engine job. }CMDBREClassQualStruct. } CMDBREJobRunInfo. ARNameType jobName. The start time of the job. unsigned int jobState. Data structures 213 . CMDBREDatasetPair The CMDBREDatasetPair data structure is used to hold information about the datasets to use in the reconciliation job. The dataset for the reconciliation job. CMDBREClassQualStruct *classQualList. The qualification for the class.1 The CMDBREClassQualStruct structure consists of the following elements: classId qual The ID of the class. }CMDBREDatasetPair. CMDBREClassQualList The CMDBREClassQualList data structure is used to hold a list of CMDBREClassQualStruct structures. A list of CMDBClassQualStruct structures. If the workingDataset field in the structure contains a Null. The CMDBREClassQualList structure consists of the following elements: numItems classQualList An integer value indicating the number of CMDBREClassQualStruct structure items in the list.BMC Atrium CMDB 2. typedef Struct CMDBREDatasetPair { ARNameType workingDataset. all the instances in the class will be reconciled. typedef struct CMDBREClassQuaList { unsigned int numItems. ARNameType dataset. If the qualification contains a null value.0. }CMDBREClassQuaList. If this field contains a Null. The CMDBREDatasetPair structure consists of the following elements: workingDataset The dataset name of the working dataset. the dataset for the reconciliation job will be replaced with workingDataset before reconciliation. the dataset specified in this field will be used. dataset 214 Chapter 5—C API functions and data structures . }CMDBREDatasetList. char *qualifier. A list of CMDBREDatasetPair items. typedef Struct CMDBREDatasetList { Unsigned int numItems. ARNameType form. Data structures 215 . ARNameType server. The federation structures include: ! ! CMDBFederatedARInfo (page 215) CMDBFederatedActivateInfo (page 216) CMDBFederatedARInfo The CMDBFederatedARInfo data structure is used to hold the AR System related federated interface information to retrieve.Developer’s Reference Guide CMDBREDatasetList The CMDBREDatasetList data structure is used to hold a list of CMDBREDatasetPair structures. CMDBREDatasetPair* datasetList. Federation structures Federation structures are data structures used in federation functions. typedef struct CMDBFederatedARInfo { unsigned int arAccessType. ARNameType view. } CMDBFederatedARInfo. char *url. The CMDBREDatasetList structure consists of the following elements: numItems datasetList An integer value indicating the number of CMDBREDatasetPair items in the list. } CMDBFederatedActivateInfo. Contains a URL to access the AR System form depending on whether the default webpath is specified on the AR System server. server form view qualifier url The AR System server name. typedef struct CMDBFederatedActivateInfo { unsigned int actionType. The AR System form name. unsigned int accessType.0.BMC Atrium CMDB 2. The AR System view name. char *accessString. The qualifier string for accessing the AR System. 216 Chapter 5—C API functions and data structures .1 The CMDBFederatedARInfo structure consists of the following elements: arAccessType The access type for the AR System. 1—Retrieve AR System Process (CMDB_FEDERATED_ACCESS_TYPE_AR_PROCESS). union { CMDBFederatedARInfo arInfo. } u. CMDBFederatedActivateInfo The CMDBFederatedActivateInfo data structure is used to hold the federated instance data activation information to retrieve. 0—Retrieve AR System URL (CMDB_FEDERATED_ACCESS_TYPE_AR_URL). 4—Access a manual launch link information for the federated interface (CMDB_FEDERATED_ACCESS_TYPE_MANUAL). process command. 1<<0—Return the expanded federated interface data. 0—Access an AR System form for the federated interface (CMDB_FEDERATED_ACCESS_TYPE_AR). 5—Access a data store for the federated interface (CMDB_FEDERATED_ACCESS_TYPE_DATA_STORE). or other information. 1<<0—Expand and launch the federated interface. Based on the accessType subclasses. (CMDB_FEDERATION_ACTIVATION_NONE). (CMDB_FEDERATION_ACTIVATION_LAUNCH). accessType The type of access required.Developer’s Reference Guide The CMDBFederatedActivateInfo structure consists of the following elements: actionType The action to perform. 2—Use a web service for the federated interface (CMDB_FEDERATED_ACCESS_TYPE_WEBSERVICE). contains the URL link. arInfo accessString Contains information related to the AR System form. (CMDB_FEDERATION_ACTIVATION_EXPAND). Data structures 217 . 0—Activate none. 3—Start a process for the federated interface (CMDB_FEDERATED_ACCESS_TYPE_PROCESS). 1—Access a URL for the federated interface (CMDB_FEDERATED_ACCESS_TYPE_URL). The list of attribute values that changed for the specified attributes. 218 Chapter 5—C API functions and data structures . The CMDBAuditValueList structure consists of the following elements: operation The type of audit operation performed. The audit structures include: ! ! ! CMDBAuditValueList (page 218) CMDBAuditValueListList (page 219) CMDBAuditInfoStruct (page 219) CMDBAuditValueList The CMDBAuditValueList data structure is used to hold a list of audit values to retrieve. ARNameList attrNameChangeList.1 Audit structures Audit structures are data structures used in audit functions. 2—The create operation performed (CMDB_AUDIT_OPERATION_CREATE). (CMDB_AUDIT_OPERATION_NONE).BMC Atrium CMDB 2. changedBy auditTimestamp attrNameChangeList attrAuditValueList The user who performed the audit operation. The list of attribute names that changed in the audit operation. 3—The delete operation performed (CMDB_AUDIT_OPERATION_DELETE). } CMDBAuditValueList. 4—The merge operation performed (CMDB_AUDIT_OPERATION_MERGE). typedef struct CMDBAuditValueList { unsigned int operation. CMDBAuditValueList *attrAuditValueList. ARTimestamp auditTimestamp. 1—The modify operation performed (CMDB_AUDIT_OPERATION_SET). 0—No audit operation performed.0. The date and time when the audit operation was performed. ARAccessNameType changedBy. 0—None No auditing option set. CMDBAuditInfoStruct The CMDBAuditInfoStruct data structure is used to hold the audit information to set audit options for the class. typedef struct CMDBAuditValueListList { unsigned int numItems. typedef struct CMDBAuditInfoStruct { unsigned int type. union { ARNameType logForm. 2—Log Store the information for the modified attributes in a log. Data structures 219 . } CMDBAuditValueListList. CMDBQualifierStruct qual. The CMDBAuditInfoStruct structure consists of the following elements: type The type of audit option to set. 1—Copy Create a copy of an instance when an attribute is modified. qual logForm The qualification to retrieve the audit information for the class. The CMDBAuditValueListList structure consists of the following elements: numItems attrAuditValueList An integer value indicating the number of CMDBAuditValueList structure items in the list. The list of audit value list. } CMDBAuditInfoStruct. } u. The name of the AR System form for the Log audit option. CMDBAuditValueList *attrAuditValueList.Developer’s Reference Guide CMDBAuditValueListList The CMDBAuditValueListList data structure is used to hold a list of audit values list to retrieve. 0.1 220 Chapter 5—C API functions and data structures .BMC Atrium CMDB 2. The following topics are provided: ! ! Operations (page 222) Data structures (page 262) Web services API operations and data structures 221 .Chapter 6 Web services API operations and data structures This chapter provides reference information for the web services API operations and data structures. The operation categories include instance. data model. the usage of the term specified for a given parameter denotes that the parameter is listed under the Synopsis heading of the API function. Instance data operations include: ! ! ! ! ! ! GetInstances (page 223) SetInstance (page 225) CreateInstance (page 226) DeleteInstance (page 228) CreateRelationInstance (page 229) GraphQuery (page 231) 222 Chapter 6—Web services API operations and data structures .0.BMC Atrium CMDB 2. Note: In the web services API function descriptions. Instance data operations The instance data operations act on CI or relationship instances. reconciliation object. and session.1 Operations The web services operations are categorized by the type of functions these operations perform. It is a two-part structure that contains the namespace and the class name. password. classNameId The class from which the instances are to be retrieved.Developer’s Reference Guide GetInstances Description Privileges Synopsis Retrieves a list of instances. and the language to be used for the session. CMDB Administrator <wsdl:operation name="GetInstances" parameterOrder="inargs"> <wsdl:input message="tns:GetInstancesRequest" name="GetInstancesRequest"/> <wsdl:output message="tns:GetInstancesResponse" name="GetInstancesResponse"/> </wsdl:operation> <wsdl:message name="GetInstancesRequest"> <wsdl:part element="tns:GetInstances" name="inargs"/> </wsdl:message> <wsdl:message name="GetInstancesResponse"> <wsdl:part element="tns:GetInstancesOutput" name="outargs"/> </wsdl:message> <element name="GetInstances"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="query" type="xsd:string"/> <element name="attributes" type="impl:ArrayOf_String"/> <element name="firstRetrieve" type="xsd:int"/> <element name="maxRetrieve" type="xsd:int"/> <element name="sortOrder" type="tns:SortOrderList"/> <element name="aDatasetId" type="xsd:string"/> <element name="aGetMask" type="tns:GetMask"/> </sequence> </complexType> </element> <element name="GetInstancesOutput"> <complexType> <sequence> <element name="instanceInfo" type="impl:InstanceInfoList"/> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation. Operations 223 . The userId is a required element. such as the user ID. You can limit the retrieved instance result-set by specifying a qualification. Specify CMDB_NO_MAX_LIST_RETRIEVE to assign no maximum. aGetMask The identifier for specifying the dataset type. attributes A list of attribute names to retrieve. and arithmetic operations.0. relational. status A list of zero or more notes. sortOrder The sort order for the retrieved data. warnings. The data in the return values are based on the dataset ID specified in this parameter. aDatasetId The unique identifier for the dataset. DATASET_MODE_CURRENT: Allows you to retreive instances from the current dataset only. 224 Chapter 6—Web services API operations and data structures . CMDB_START_WITH_FIRST_ENTRY represents the first entry and is the default value if the value is not set. GET_MASK_NONE: Based on the datasetId being passed. Use this parameter to limit the amount of data returned if the query does not narrow the list. The qualification can include one or more attributes and any combination of conditional. Return values instanceInfo The list of instances that match the criteria. instances are retrieved from either the overlay or the original dataset. firstRetrieve The first instance to retrieve. or errors generated from a call of this operation. each with a list of attributes and values. maxRetrieve The maximum number of entries to retrieve.BMC Atrium CMDB 2.1 query A qualification that determines the set of instances to retrieve. Developer’s Reference Guide SetInstance Description Privileges Sets a CI or relationship instance in the class form. CMDB Administrator <wsdl:operation name="SetInstance" parameterOrder="inargs"> <wsdl:input message="tns:SetInstanceRequest" name="SetInstanceRequest"/> <wsdl:output message="tns:SetInstanceResponse" name="SetInstanceResponse"/> </wsdl:operation> <wsdl:message name="SetInstanceRequest"> <wsdl:part element="tns:SetInstance" name="inargs"/> </wsdl:message> <wsdl:message name="SetInstanceResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="SetInstance"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="instanceId" type="xsd:string"/> <element name="aDatasetId" type="xsd:string"/> <element name="attributes" type="impl:AttributeValueList"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> 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 for which the instance is to be set. It is a two-part structure that contains the namespace and the class name. instanceId The unique identifier for the instance. Operations 225 BMC Atrium CMDB 2.0.1 aDatasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter. attributes A list of one or more name and 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 attribute names only. An error is generated if an attribute does not exist or the user specified in the loginInfo parameter does not have the write permission for an attribute name. Return values status A list of zero or more notes, warnings, or errors generated from a call of this operation. CreateInstance Description Privileges Synopsis Creates a CI or relationship instance in the class form. CMDB Administrator <wsdl:operation name="CreateInstance" parameterOrder="inargs"> <wsdl:input message="tns:CreateInstanceRequest" name="CreateInstanceRequest"/> <wsdl:output message="tns:CreateInstanceResponse" name="CreateInstanceResponse"/> </wsdl:operation> <wsdl:message name="CreateInstanceRequest"> <wsdl:part element="tns:CreateInstance" name="inargs"/> </wsdl:message> <wsdl:message name="CreateInstanceResponse"> <wsdl:part element="tns:CreateInstanceOutput" name="outargs"/> </wsdl:message> <element name="CreateInstance"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="aDatasetId" type="xsd:string"/> <element name="attributes" type="impl:AttributeValueList"/> </sequence> </complexType> </element> 226 Chapter 6—Web services API operations and data structures Developer’s Reference Guide <element name="CreateInstanceOutput"> <complexType> <sequence> <element name="instanceId" type="xsd:string"/> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> 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 for which the instance is to be created. It is a two-part structure that contains the namespace and the class name. aDatasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter. attributes A list of one or more name and 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 attribute names only. An error is generated if an attribute does not exist or the user specified in the loginInfo parameter does not have the write permission for an attribute name. Return values instanceId The unique identifier for the new attribute. status A list of zero or more notes, warnings, or errors generated from a call of this operation. Operations 227 BMC Atrium CMDB 2.0.1 DeleteInstance Description Privileges Synopsis Deletes an instance of a class. CMDB Administrator <wsdl:operation name="DeleteInstance" parameterOrder="inargs"> <wsdl:input message="tns:DeleteInstanceRequest" name="DeleteInstanceRequest"/> <wsdl:output message="tns:DeleteInstanceResponse" name="DeleteInstanceResponse"/> </wsdl:operation> <wsdl:message name="DeleteInstanceRequest"> <wsdl:part element="tns:DeleteInstance" name="inargs"/> </wsdl:message> <wsdl:message name="DeleteInstanceResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="DeleteInstance"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="instanceId" type="xsd:string"/> <element name="aDatasetId" type="xsd:string"/> <element name="deleteOption" type="impl:InstanceDeleteOption"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> 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 from which the instance is to be deleted. It is a two-part structure that contains the namespace and the class name. instanceId The unique identifier for the instance. 228 Chapter 6—Web services API operations and data structures Developer’s Reference Guide aDatasetId The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter. deleteOption DERIVED_INSTANCE_FOUND: Allows you to delete only the specified instance, if the instance is retrieved. UNCONDITIONALLY: Allows you to delete the instance even when the instance cannot be retrieved . 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 operation. CreateRelationInstance Description Privileges Synopsis Creates relationship instances for the specified CIs. CMDB Administrator <wsdl:operation name="CreateRelationInstance"> <wsdlsoap:operation soapAction="CreateRelationInstance" style="document"/> <wsdl:input name="CreateRelationInstanceRequest"> <wsdlsoap:body parts="inargs" use="literal"/> </wsdl:input> <wsdl:output name="CreateRelationInstanceResponse"> <wsdlsoap:body parts="outargs" use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:message name="CreateRelationInstanceRequest"> <wsdl:part element="tns:CreateRelationInstance" name="inargs"/> </wsdl:message> <wsdl:message name="CreateRelationInstanceResponse"> <wsdl:part element="tns:CreateInstanceOutput" name="outargs"/> </wsdl:message> <xsd:element name="CreateRelationInstance"> <xsd:complexType> <xsd:sequence> <xsd:element name="loginInfo" type="tns:LoginInfo"/> <xsd:element name="classNameId" type="tns:ClassNameId"/> <xsd:element name="role1Name" type="xsd:string"/> <xsd:element name="instance1Id" type="xsd:string"/> <xsd:element name="class1Id" type="xsd:string"/> <xsd:element name="role2Name" type="xsd:string"/> <xsd:element name="instance2Id" type="xsd:string"/> <xsd:element name="class2Id" type="xsd:string"/> Operations 229 BMC Atrium CMDB 2.0.1 <xsd:element name="aDatasetId" type="xsd:string"/> <xsd:element name="attributes" type="tns:AttributeValueList"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="CreateInstanceOutput"> <xsd:complexType> <xsd:sequence> <xsd:element name="instanceId" type="xsd:string"/> <xsd:element name="status" type="tns:StatusList"/> </xsd:sequence> </xsd:complexType> </xsd:element> 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 in which the relationship instance is to be created. It is a two-part structure that contains the namespace and the class name. role1Name The role name of the parent instance. instance1Id The instance ID of the parent instance. classId The class ID of the parent instance. role2Name The role name of the child instance. instance2Id The instance ID of the child instance. class2Id The class name of the child instance. aDatasetId The ID of the dataset within which the CI classes exist. 230 Chapter 6—Web services API operations and data structures Developer’s Reference Guide attributes The list of attributes values for the relationship class. Return Values instanceId The instance ID of the relationship instance that is created. status A list of zero or more notes, warnings, or errors generated from a call of this operation. GraphQuery Description Privileges Synopsis Queries related instances for the specified CI. CMDB Administrator <wsdl:operation name="GraphQuery" parameterOrder="inargs"> <wsdl:input message="tns:GraphQueryRequest" name="GraphQueryRequest"/> <wsdl:output message="tns:GraphQueryResponse" name="GraphQueryResponse"/> </wsdl:operation> <wsdl:message name="GraphQueryRequest"> <wsdl:part element="tns:GraphQuery" name="inargs"/> </wsdl:message> <wsdl:message name="GraphQueryResponse"> <wsdl:part element="tns:GraphQueryOutput" name="outargs"/> </wsdl:message> <element name="GraphQuery"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="startClassNameId" type="impl:ClassNameId"/> <element name="startExtensionId" type="xsd:string"/> <element name="startInstanceId" type="xsd:string"/> <element name="numLevels" type="xsd:int"/> <element name="direction" type="impl:GraphDirection"/> <element name="noMatchProceed" type="xsd:boolean"/> <element name="onMatchProceed" type="xsd:boolean"/> <element name="graph" type="impl:GraphList"/> <element name="aGetMask" type="tns:GetMask"/> <element name="aDatasetId" type="xsd:string"/> </sequence> </complexType> </element> Operations 231 such as the user ID.1 <element name="GraphQueryOutput"> <complexType> <sequence> <element name="objects" type="impl:ObjectQueryInfoList"/> <element name="relations" type="impl:RelationQueryInfoList"/> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation. The userId is a required element. 232 Chapter 6—Web services API operations and data structures . IMPACT_NODE_RIGHT: The node to be queried is on the right side of the relationship. CAUSE_NODE_LEFT: The node to be queried is on the left side of the relationship. if the starting node class is BMC:A and BMC:A appears more than once in the query graph. you can designate one of them to have an extension ID of 2 to distinguish it from the other one.0. This is required if the query graph contains more than one instance of the same class and needs to distinguish one from another. startExtensionId The extension ID of the starting node CI. For example. The value A-1 specifies the graph query to traverse to the end of the graph. startClassNameId The name of the starting node class in the CI graph. password.BMC Atrium CMDB 2. startInstanceId The ID of the starting node in the CI graph. and the language to be used for the session. direction The direction in which the graph is to traverse. numLevels The number of levels to traverse the specified queryGraph. proceed to the next relationship. Notice that. F (0): When the node returned for a given relationship instance does not match the criteria specified. do not proceed any further. in this case. aGetMask The identifier for specifying the dataset type. instances are retrieved from either the overlay or the original dataset. aDatasetId The unique identifier for the dataset. onMatchProceed T (1): When the node returned for a given relationship instance matches the criteria specified. no relationship information will be returned because the returned components might not be connected. The starting node is not included. proceed to the next relationship. graph The details of the information indicating the path that needs to be queried to return the desired CIs and relationships. do not proceed any further. GET_MASK_NONE: Based on the datasetId being passed.Developer’s Reference Guide noMatchProceed T (1): When the node returned for a given relationship instance does not match the criteria specified. Operations 233 . F (0): When the node returned for a given relationship instance matches the criteria specified. Return values objects List of one or more CI instances matching the specified criteria. The data in the return values are based on the dataset ID specified in this parameter. due to skipping the non-matching nodes. DATASET_MODE_CURRENT: Allows you to retreive instances from the current dataset only. status A list of zero or more notes.1 relations List of relationship instances matching the specified criteria that links the CIs returned. or errors generated from a call of this operation. The data model operations include: ! ! ! ! ! ! ! ! ! GetClass (page 235) SetClass (page 236) CreateClass (page 237) ListClasses (page 238) DeleteClass (page 240) GetAttributes (page 241) SetAttribute (page 244) CreateAttribute (page 242) Delete Attribute (page 245) 234 Chapter 6—Web services API operations and data structures . Data model operations The data model operations act on classes and their attributes in the data model.0. warnings.BMC Atrium CMDB 2. status A list of zero or more notes. classNameID The class which is to be retrieved. such as the user ID. CMDB Administrator <wsdl:operation name="GetClass" parameterOrder="inargs"> <wsdl:input message="tns:GetClassRequest" name="GetClassRequest"/> <wsdl:output message="tns:GetClassResponse" name="GetClassResponse"/> </wsdl:operation> <wsdl:message name="GetClassRequest"> <wsdl:part element="tns:GetClass" name="inargs"/> </wsdl:message> <wsdl:message name="GetClassResponse"> <wsdl:part element="tns:GetClassOutput" name="outargs"/> </wsdl:message> <element name="GetClass"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> </sequence> </complexType> </element> <element name="GetClassOutput"> <complexType> <sequence> <element name="classInfo" type="impl:ClassInfoOut"/> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation. Return values classInfo Information about the class. or errors generated from a call of this operation. warnings. Operations 235 . The userId is a required element. and the language to be used for the session. It is a two-part structure that contains the namespace and the class name.Developer’s Reference Guide GetClass Description Privileges Synopsis Retrieves the class information. password. such as the user ID. and the language to be used for the session. classInfo Information about the class. It is a two-part structure that contains the namespace and the class name. Privileges Synopsis CMDB Administrator <wsdl:operation name="SetClass" parameterOrder="inargs"> <wsdl:input message="tns:SetClassRequest" name="SetClassRequest"/> <wsdl:output message="tns:SetClassResponse" name="SetClassResponse"/> </wsdl:operation> <wsdl:message name="SetClassRequest"> <wsdl:part element="tns:SetClass" name="inargs"/> </wsdl:message> <wsdl:message name="SetClassResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="SetClass"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="newClassNameId" type="impl:ClassNameId"/> <element name="classInfo" type="impl:ClassInfoIn"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation. 236 Chapter 6—Web services API operations and data structures .1 SetClass Sets the properties for a specified class.0. The userId is a required element. newclassNameId The new name of the class. classNameId The class that is to be set. password.BMC Atrium CMDB 2. password. CreateClass Creates a class with core attributes. such as the user ID. Privileges Synopsis CMDB Administrator <wsdl:operation name="CreateClass" parameterOrder="inargs"> <wsdl:input message="tns:CreateClassRequest" name="CreateClassRequest"/> <wsdl:output message="tns:CreateClassResponse" name="CreateClassResponse"/> </wsdl:operation> <wsdl:message name="CreateClassRequest"> <wsdl:part element="tns:CreateClass" name="inargs"/> </wsdl:message> <wsdl:message name="CreateClassResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="CreateClass"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="superclassNameId" type="impl:ClassNameId"/> <element name="classId" type="xsd:string"/> <element name="classInfo" type="impl:ClassInfoIn"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation. Operations 237 .Developer’s Reference Guide Return values status A list of zero or more notes. and the language to be used for the session. warnings. or errors generated from a call of this operation. The userId is a required element. The classes that are retrieved will have the class that is specified in the relatedClass parameter as part of the relationship.0. classId The unique identifier for the class. The name of the class must be unique. classInfo The information about the class. ListClasses Description Retrieves information about relationship classes for a specified class. Specify NULL for this parameter if there is no superclass. The information contained in this definition depends on the type of class you specify. It can be provided by the user. warnings.BMC Atrium CMDB 2. superClassNameId The superclass of class being created. CMDB Administrator <wsdl:operation name="ListClasses"> <wsdlsoap:operation soapAction="ListClasses" style="document"/> <wsdl:input name="ListClassesRequest"> <wsdlsoap:body parts="inargs" use="literal"/> </wsdl:input> <wsdl:output name="ListClassesResponse"> <wsdlsoap:body parts="outargs" use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:message name="ListClassesRequest"> <wsdl:part element="tns:ListClassesInput" name="inargs"/> </wsdl:message> Privileges Synopsis 238 Chapter 6—Web services API operations and data structures . If it is not provided by the user. Return values status A list of zero or more notes.1 classNameId The name of the class to create. such as the type of class to create. It is a two-part structure that contains the namespace and classname in the <namespace>:<classname> format. it will be automatically generated by the system. or errors generated from a call to this operation. The userId is a required element. propInfo The list property information of the class to retrieve. getHidden Retrieves the hidden classes. password. superClass The superclass of the class to retrieve. Operations 239 . and the language to be used for the session. relatedClass Retrieves the relationship classes that have a class specified in this parameter as part of the relationship. Retrieves the classes that are derived from the superclass.Developer’s Reference Guide <wsdl:message name="ListClassesResponse"> <wsdl:part element="tns:ListClassesOutput" name="outargs"/> </wsdl:message> <xsd:element name="ListClassesInput"> <xsd:complexType> <xsd:sequence> <xsd:element name="loginInfo" type="tns:LoginInfo"/> <xsd:element name="namespace" type="xsd:string"/> <xsd:element name="relatedClass” type="tns:ClassNameId"/> <xsd:element name="superClass" type="tns:ClassNameId"/> <xsd:element name="propInfo" type="tns:PropInfoList"/> <xsd:element name="getHidden" type="xsd:boolean"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="ListClassesOutput"> <xsd:complexType> <xsd:sequence> <xsd:element name="classList" type="tns:ClassNameIdList"/> <xsd:element name="status" type="tns:StatusList"/> </xsd:sequence> </xsd:complexType> </xsd:element> Input arguments loginInfo The login information for the operation. Namespaces are a way of partitioning your data model to create logical groups of classes. namespace The name of the namespace. The Class Manager namespaces are implemented using a prefix-based naming convention on classes. such as the user ID. CMDB Administrator <wsdl:operation name="DeleteClass" parameterOrder="inargs"> <wsdl:input message="tns:DeleteClassRequest" name="DeleteClassRequest"/> <wsdl:output message="tns:DeleteClassResponse" name="DeleteClassResponse"/> </wsdl:operation> <wsdl:message name="DeleteClassRequest"> <wsdl:part element="tns:DeleteClass" name="inargs"/> </wsdl:message> <wsdl:message name="DeleteClassResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="DeleteClass"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="option" type="impl:ClassDeleteOption"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation. status A list of zero or more notes. 240 Chapter 6—Web services API operations and data structures .0. DeleteClass Description Privileges Synopsis Deletes a specified class. or errors generated from a call to this operation.BMC Atrium CMDB 2. warnings. such as the user ID. Also deletes the associated attributes of the class. The userId is a required element.1 Return values classList A list of class names that match the specified criteria. and the language to be used for the session. password. option A value indicating the action to take if the specified class contains instances. OPTION_WITH_DATA: Delete the class only if the class has no subclasses or dependent relationships. GetAttributes Description Privileges Synopsis Retrieves information about a list of attributes CMDB Administrator <wsdl:operation name="GetAttributes" parameterOrder="inargs"> <wsdl:input message="tns:GetAttributesRequest" name="GetAttributesRequest"/> <wsdl:output message="tns:GetAttributesResponse" name="GetAttributesResponse"/> </wsdl:operation> <wsdl:message name="GetAttributesRequest"> <wsdl:part element="tns:GetAttributes" name="inargs"/> </wsdl:message> <wsdl:message name="GetAttributesResponse"> <wsdl:part element="tns:GetAttributesOutput" name="outargs"/> </wsdl:message> <element name="GetAttributes"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="attributeNames" type="impl:ArrayOf_String"/> </sequence> Operations 241 . warnings. OPTION_NONE: Delete the class only if the class contains no instances and has no subclasses or dependent relationships. has subclasses. This applies only to regular classes. This option overrides the CMDB_CLASS_DATA_DELETE option.Developer’s Reference Guide classNameID The name of the class to delete. or is a member of a relationship class. Return values status A list of zero or more notes. All the dependencies for the specified class are deleted. OPTION_ALL_DEPENDENCIES: Delete the class including all the subclasses and dependent relationship classes that are associated with it. or errors generated from a call to this operation. The userId is a required element. such as the user ID. CMDB Administrator <wsdl:operation name="CreateAttribute" parameterOrder="inargs"> <wsdl:input message="tns:CreateAttributeRequest" name="CreateAttributeRequest"/> <wsdl:output message="tns:CreateAttributeResponse" name="CreateAttributeResponse"/> </wsdl:operation> <wsdl:message name="CreateAttributeRequest"> <wsdl:part element="tns:CreateAttribute" name="inargs"/> </wsdl:message> <wsdl:message name="CreateAttributeResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> 242 Chapter 6—Web services API operations and data structures . It is a two-part structure that contains the namespace and the classname. attributeNames The names of the attributes to retrieve.0. or errors generated from a call to this operation. Return values attributeInfoList The information about the list of attributes. password. and the language to be used for the session. warnings. CreateAttribute Description Privileges Synopsis Creates an attribute for the specified instance. status A list of zero or more notes. classNameId The class for which the attributes are to be retrieved.1 </complexType> </element> <element name="GetAttributesOutput"> <complexType> <sequence> <element name="attributeInfoList" type="impl:AttributeInfoList"/> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation.BMC Atrium CMDB 2. password. fieldId The AR System field ID of the attribute to create. Specify 0 for this parameter if you want the system to generate the ID. The userId is a required element. The name of all attributes must be unique within the class. It is a two-part structure that contains the namespace and the classname. such as the user ID.Developer’s Reference Guide </wsdl:message> <element name="CreateAttribute"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="attributeName" type="xsd:string"/> <element name="attributeId" type="xsd:string"/> <element name="fieldId" type="xsd:long"/> <element name="attributeInfo" type="impl:AttributeInfoIn"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation. classNameId The name of the class for which the attribute is to be created. attributeId The ID of the attribute to create. attributeName The name of the attribute to create. and the language to be used for the session. The IDs of all attributes must be unique within the class. Operations 243 . CMDB Administrator <wsdl:operation name="SetAttribute" parameterOrder="inargs"> <wsdl:input message="tns:SetAttributeRequest" name="SetAttributeRequest"/> <wsdl:output message="tns:SetAttributeResponse" name="SetAttributeResponse"/> </wsdl:operation> <wsdl:message name="SetAttributeRequest"> <wsdl:part element="tns:SetAttribute" name="inargs"/> </wsdl:message> <wsdl:message name="SetAttributeResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="SetAttribute"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="attributeName" type="xsd:string"/> <element name="newAttributeName" type="xsd:string"/> <element name="attributeInfo" type="impl:AttributeInfoIn"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> 244 Chapter 6—Web services API operations and data structures . Return values status A list of zero or more notes. The limits and properties you assign must be of the same data type as the attribute. See the CMDBsubclassesLimitStruct definition in cmdb.BMC Atrium CMDB 2. warnings. or errors generated from a call to this operation.h to find the contained structure that applies to the type of attribute you are creating. SetAttribute Description Privileges Synopsis Sets an attribute for the specified instance. Specify NULL for this parameter if you do not want to change the attribute limits and properties.1 attributeInfo The value limits for the attribute and other properties specific to the attribute’s type.0. such as the user ID. classNameId The class for which the attribute is to be set. Specify NULL for this parameter if you do not want to change the attribute limits and properties. The userId is a required element. newAttributeName The new name of the attribute. Delete Attribute Description Privileges Synopsis Deletes the attribute with the specified name. Return values status A list of zero or more notes. attributeName The name of the attribute to set. password.Developer’s Reference Guide Input arguments loginInfo The login information for the operation. warnings. and the language to be used for the session. or errors generated from a call to this operation. It is a two-part structure that contains the namespace and the classname. attributeInfo The value limits for the attribute and other properties specific to the attribute’s type.h to find the contained structure that applies to the type of attribute you are setting. See the CMDBsubclassesLimitStruct definition in cmdb. The limits and properties you assign must be of the same data type as the attribute. CMDB Administrator <wsdl:operation name="DeleteAttribute" parameterOrder="inargs"> <wsdl:input message="tns:DeleteAttributeRequest" name="DeleteAttributeRequest"/> <wsdl:output message="tns:DeleteAttributeResponse" name="DeleteAttributeResponse"/> </wsdl:operation> <wsdl:message name="DeleteAttributeRequest"> <wsdl:part element="tns:DeleteAttribute" name="inargs"/> </wsdl:message> <wsdl:message name="DeleteAttributeResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> Operations 245 . The userId is a required element. Return values status A list of zero or more notes.BMC Atrium CMDB 2. and the language to be used for the session. such as the user ID. 246 Chapter 6—Web services API operations and data structures . classNameID The name of the class from which to delete the attribute. or errors generated from a call to this operation. attributeName The name of the attribute to delete.1 <element name="DeleteAttribute"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="attributeName" type="xsd:string"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation. warnings. password.0. CMDB Administrator <wsdl:operation name="ExecuteJobRun" parameterOrder="inargs"> <wsdl:input message="tns:ExecuteJobRunRequest" name="ExecuteJobRunRequest"/> <wsdl:output message="tns:ExecuteJobRunResponse" name="ExecuteJobRunResponse"/> </wsdl:operation> <wsdl:message name="ExecuteJobRunRequest"> <wsdl:part element="tns:ExecuteJobRun" name="inargs"/> </wsdl:message> <wsdl:message name="ExecuteJobRunResponse"> <wsdl:part element="tns:ExecuteJobRunOutput" name="outargs"/> </wsdl:message> <element name="ExecuteJobRun"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="jobName" type="xsd:string"/> <xsd:element name="qualifierList" type="tns:ClassQualifierList"/> <xsd:element name="datasetList" type="tns:DatasetPairList"/> </sequence> </complexType> </element> <element name="ExecuteJobRunOutput"> <complexType> <sequence> <element name="jobId" type="xsd:string"/> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Operations 247 .Developer’s Reference Guide Reconciliation Engine operations The Reconciliation Engine operations act on reconciliation jobs. The Reconciliation Engine operations include: ! ! ! ! ExecuteJobRun (page 247) GetJobRun (page 248) GetListJobRun (page 250) CancelJobRun (page 251) ExecuteJobRun Description Privileges Synopsis Starts a job. warnings. password. status A list of zero or more notes.1 Input arguments loginInfo The login information for the operation. qualifierList The list of class qualifications. jobName The name of the job to start. GetJobRun Description Privileges Synopsis Retrieves information about a currently running job. and the language to be used for the session.BMC Atrium CMDB 2. such as the user ID. The userId is a required element. CMDB Administrator <wsdl:operation name="GetJobRun" parameterOrder="inargs"> <wsdl:input message="tns:GetJobRunRequest" name="GetJobRunRequest"/> <wsdl:output message="tns:GetJobRunResponse" name="GetJobRunResponse"/> </wsdl:operation> <wsdl:message name="GetJobRunRequest"> <wsdl:part element="tns:GetJobRun" name="inargs"/> </wsdl:message> <wsdl:message name="GetJobRunResponse"> <wsdl:part element="tns:GetJobRunOutput" name="outargs"/> </wsdl:message> <element name="GetJobRun"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="jobId" type="xsd:string"/> </sequence> </complexType> </element> 248 Chapter 6—Web services API operations and data structures . or errors generated from a call to this operation. datasetList The list of Reconciliation Engine dataset pair.0. Return values jobId The ID of the job. Operations 249 . such as the user ID. The userId is a required element.Developer’s Reference Guide <element name="GetJobRunOutput"> <complexType> <sequence> <element name="jobRunInfo" type="impl:JobRunInfo"/> <element name="jobLog" type="xsd:string"/> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation. jobId The ID of the job. or errors generated from a call to this operation. password. warnings. status A list of zero or more notes. jobLog The log for the currently running job. Return values jobRunInfo The information about the currently running job. and the language to be used for the session. and arithmetic operations.1 GetListJobRun Description Privileges Synopsis Retrieves information about a list of currently running jobs. relational. password. The qualification can include one or more subclasses and any combination of conditional. and the language to be used for the session. Return Values jobRunInfo The information about the currently running jobs. 250 Chapter 6—Web services API operations and data structures . such as the user ID. qualifier A query that determines the set of jobs to retrieve.0.BMC Atrium CMDB 2. The userId is a required element. CMDB Administrator <wsdl:operation name="GetListJobRun" parameterOrder="inargs"> <wsdl:input message="tns:GetListJobRunRequest" name="GetListJobRunRequest"/> <wsdl:output message="tns:GetListJobRunResponse" name="GetListJobRunResponse"/> </wsdl:operation> <wsdl:message name="GetListJobRunRequest"> <wsdl:part element="tns:GetListJobRun" name="inargs"/> </wsdl:message> <wsdl:message name="GetListJobRunResponse"> <wsdl:part element="tns:GetListJobRunOutput" name="outargs"/> </wsdl:message> <element name="GetListJobRun"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="qualifier" type="xsd:string"/> </sequence> </complexType> </element> <element name="GetListJobRunOutput"> <complexType> <sequence> <element name="jobRunInfo" type="impl:JobRunInfoList"/> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input argument loginInfo The login information for the operation. or errors generated from a call to this operation. The userId is a required element. such as the user ID.Developer’s Reference Guide status A list of zero or more notes. password. jobId The ID of the job. and the language to be used for the session. Operations 251 . warnings. CMDB Administrator <wsdl:operation name="CancelJobRun" parameterOrder="inargs"> <wsdl:input message="tns:CancelJobRunRequest" name="CancelJobRunRequest"/> <wsdl:output message="tns:CancelJobRunResponse" name="CancelJobRunResponse"/> </wsdl:operation> <wsdl:message name="CancelJobRunRequest"> <wsdl:part element="tns:CancelJobRun" name="inargs"/> </wsdl:message> <wsdl:message name="CancelJobRunResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="CancelJobRun"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="jobId" type="xsd:string"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element> Input arguments loginInfo The login information for the operation. CancelJobRun Description Privileges Synopsis Stops a currently running job. 1 Return values status A list of zero or more notes. warnings.0.BMC Atrium CMDB 2. The web services functions for federation includes: ! ! ActivateFederatedInContext (page 252) GetRelatedFederatedInContext (page 254) ActivateFederatedInContext Description Expands the FederatedInterface instance for a specific CI and federated interface. Depending on a flag you specify when you call this function. Federation operations The federation functions manipulate the federated data for an instance. or errors generated from a call to this operation. your federated instance might either be only expanded or expanded and launched. CMDB Administrator <wsdl:operation name="ActivateFederatedInContext" parameterOrder="inargs"> <wsdl:input message="tns:ActivateFederatedInContextRequest" name="ActivateFederatedInContextRequest"/> <wsdl:output message="tns:ActivateFederatedInContextResponse" name="ActivateFederatedInContextResponse"/> </wsdl:operation> <wsdl:message name="ActivateFederatedInContextRequest"> <wsdl:part element="tns:FederatedActivateInfoInput" name="inargs"/> </wsdl:message> <wsdl:message name="ActivateFederatedInContextResponse"> <wsdl:part element="tns:FederatedActivateInfoOutput" name="outargs"/> </wsdl:message> <xsd:element name="FederatedActivateInfoInput"> <xsd:complexType> <xsd:sequence> <xsd:element name="loginInfo" type="tns:LoginInfo"/> <xsd:element name="classNameId" type="tns:ClassNameId"/> <xsd:element name="aDatasetId" type="xsd:string"/> <xsd:element name="instanceId" type="xsd:string"/> <xsd:element name="federatedInstanceId” type="xsd:string"/> <xsd:element name="activateOption" type="tns:FederatedActivationOption"/> </xsd:sequence> </xsd:complexType> </xsd:element> Privileges Synopsis 252 Chapter 6—Web services API operations and data structures . ACTIVATION_EXPAND: Only expand the federated interface. The userId is a required element. and the language to be used for the session. classNameId The class name of the specified CI for which the federated instance is to be expanded or launched. ACTIVATION_NONE: No specific operation to be performed. federatedInstanceId The instance ID of the federated instance that is to be expanded or launched. The data in the return values are based on the dataset ID specified in this parameter. Operations 253 . instanceId The instance ID of the specified instance for which the federated instance is to be expanded or launched. ACTIVATION_LAUNCH: Expand and launch the federated interface. activateOption The mask number that indicates if the federated instance is to be launched and expanded. aDatasetId The unique identifier for the dataset. such as the user ID. password.Developer’s Reference Guide <xsd:element name="FederatedActivateInfoOutput"> <xsd:complexType> <xsd:sequence> <xsd:element name="federatedActivateInfo" type="tns:FederatedActivateInfo"/> <xsd:element name="status" type="tns:StatusList"/> </xsd:sequence> </xsd:complexType> </xsd:element> Input arguments loginInfo The login information for the operation. GetRelatedFederatedInContext Description Privileges Synopsis Returns related FederatedInterface instances for a specific CI (context).BMC Atrium CMDB 2.0. warnings. This parameter is returned only if you specify a value of 1in the activateOption parameter.1 Return values federatedActivateInfo The expanded federated instance information. status A list of zero or more notes. CMDB Administrator <wsdl:operation name="GetRelatedFederatedInContext" parameterOrder="inargs"> <wsdl:input message="tns:GetRelatedFederatedInContextRequest" name="GetRelatedFederatedInContextRequest"/> <wsdl:output message="tns:GetRelatedFederatedInContextResponse" name="GetRelatedFederatedInContextResponse"/> </wsdl:operation> <wsdl:message name="GetRelatedFederatedInContextRequest"> <wsdl:part element="tns:FederatedRelatedInfoInput" name="inargs"/> </wsdl:message> <wsdl:message name="GetRelatedFederatedInContextResponse"> <wsdl:part element="tns:FederatedRelatedInfoOutput" name="outargs"/> </wsdl:message> <xsd:element name="FederatedRelatedInfoInput"> <xsd:complexType> <xsd:sequence> <xsd:element name="loginInfo" type="tns:LoginInfo"/> <xsd:element name="classNameId" type="tns:ClassNameId"/> <xsd:element name="instanceId" type="xsd:string"/> <xsd:element name="attributeNames" type="tns:ArrayOf_String"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="FederatedRelatedInfoOutput"> <xsd:complexType> <xsd:sequence> <xsd:element name="instanceInfo" type="tns:InstanceInfoList"/> <xsd:element name="status" type="tns:StatusList"/> </xsd:sequence> </xsd:complexType> </xsd:element> 254 Chapter 6—Web services API operations and data structures . or errors generated from a call to this operation. instanceId The Instance ID of the specific instance for which federated instances are to be retrieved.Developer’s Reference Guide Input arguments loginInfo The login information for the operation. and the language to be used for the session. or errors generated from a call to this operation. status A list of zero or more notes. Return values instanceIdList The list of instance GUIDs. warnings. attributeNames The list of attribute names to retrieve. Operations 255 . classNameId The class name of the specified instance for which federated instances are to be retrieved. The userId is a required element. such as the user ID. password. 1 Audit operations The audit functions manipulate the audit option for the classes and attributes.BMC Atrium CMDB 2. CMDB Administrator <wsdl:operation name="GetCopyAuditData"> <wsdlsoap:operation soapAction="GetCopyAuditData" style="document"/> <wsdl:input name="GetCopyAuditDataRequest"> <wsdlsoap:body parts="inargs" use="literal"/> </wsdl:input> <wsdl:output name="GetCopyAuditDataResponse"> <wsdlsoap:body parts="outargs" use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:message name="GetCopyAuditDataRequest"> <wsdl:part element="tns:GetCopyAuditDataInput" name="inargs"/> </wsdl:message> <wsdl:message name="GetCopyAuditDataResponse"> <wsdl:part element="tns:GetCopyAuditDataOutput" name="outargs"/> </wsdl:message> <xsd:element name="GetCopyAuditDataInput"> <xsd:complexType> <xsd:sequence> <xsd:element name="loginInfo" type="tns:LoginInfo"/> <xsd:element name="classNameId" type="tns:ClassNameId"/> <xsd:element name="instanceId" type="xsd:string"/> <xsd:element name="datasetId" type="xsd:string"/> <xsd:element name="query" type="xsd:string"/> <xsd:element name="attributes" type="tns:ArrayOf_String"/> </xsd:sequence> </xsd:complexType> </xsd:element> Privileges Synopsis 256 Chapter 6—Web services API operations and data structures . The web services API for audit includes: ! GetCopyAuditData (page 256) GetCopyAuditData Description Retrieves a copy of the specified CI instance if the attribute data for the instance is modified.0. The audit option must be set for the attribute’s characteristic to get the audit data. password. such as the user ID. status A list of zero or more notes. Operations 257 . If the audit option at the CI class-level is disabled then. and the language to be used for the session. instanceId The instance ID of the specified CI instance for which a copy of the audit data is to be retrieved. Return values auditValueListList The list of values for the specified attributes. The qualification can include one or more attributes and any combination of conditional. warnings. attributes A list of attribute names for which the audit data is to be retrieved. an error is returned. or errors generated from a call to this operation.Developer’s Reference Guide <xsd:element name="GetCopyAuditDataOutput"> <xsd:complexType> <xsd:sequence> <xsd:element name="auditValueListList" type="tns:AuditValueListList"/> <xsd:element name="status" type="tns:StatusList"/> </xsd:sequence> </xsd:complexType> </xsd:element> Input arguments loginInfo The login information for the operation. The data in the return values are based on the dataset ID specified in this parameter. relational. query A query that determines the set of CI instances to retrieve. The userId is a required element. datasetId The unique identifier for the dataset. 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. and arithmetic (numeric data types only) operations. and labelized strings. CMDB Administrator <wsdl:operation name="GetUIComponents" parameterOrder="inargs"> <wsdl:input message="tns:GetUIComponentsRequest" name="GetUIComponentsRequest"/> <wsdl:output message="tns:GetUIComponentsResponse" name="GetUIComponentsResponse"/> </wsdl:operation> <wsdl:message name="GetUIComponentsRequest"> <wsdl:part element="tns:GetUIComponentsInput" name="inargs"/> </wsdl:message> <wsdl:message name="GetUIComponentsResponse"> <wsdl:part element="tns:GetUIComponentsOutput" name="outargs"/> </wsdl:message> <xsd:element name="GetUIComponentsInput"> <xsd:complexType> <xsd:sequence> <xsd:element name="loginInfo" type="tns:LoginInfo"/> <xsd:element name="componentInfo" type="tns:UIComponentInfo"/> <xsd:element name="datasetId" type="xsd:string"/> <xsd:element name="instanceId" type="xsd:string"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="GetUIComponentsOutput"> <xsd:complexType> <xsd:sequence> <xsd:element name="uiComponentResultList" type="tns:UIComponentResultList"/> <xsd:element name="status" type="tns:StatusList"/> </xsd:sequence> </xsd:complexType> </xsd:element> 258 Chapter 6—Web services API operations and data structures . icons.1 User interface component operations The user interface (UI) component operations work with components. The web services API includes the following user interface (UI) operations: ! GetUIComponents (page 258) GetUIComponents Description Privileges Synopsis Retrieves a list of various UI components for a specified class. such as tool tips.0.BMC Atrium CMDB 2. If there are no qualifications specified. all existing UI components will be returned. componentInfo The qualification for the user interface component. or errors generated from a call to this operation. classId. instanceId The unique identifier used to get component information for a specific instance. The data in the return values are based on the dataset ID specified in this parameter. The userId is a required element.Developer’s Reference Guide Input arguments loginInfo The login information for the operation. status A list of zero or more notes. password. and the language to be used for the session. You can specify information such as locale. and tags to get the required UI component data. such as the user ID. Operations 259 . Return Values uiComponentResultList The CMDBUIComponents result set for the specified qualifications. warnings. datasetId The unique identifier for the dataset. 0.BMC Atrium CMDB 2. password. CMDB Administrator <wsdl:operation name="GetVersions" parameterOrder="inargs"> <wsdl:input message="tns:GetVersionsRequest" name="GetVersionsRequest"/> <wsdl:output message="tns:GetVersionsResponse" name="GetVersionsResponse"/> </wsdl:operation> <wsdl:message name="GetVersionsRequest"> <wsdl:part element="tns:GetVersionsInput" name="inargs"/> </wsdl:message> <wsdl:message name="GetVersionsResponse"> <wsdl:part element="tns:GetVersionsOutput" name="outargs"/> </wsdl:message> <xsd:element name="GetVersionsInput"> <xsd:complexType> <xsd:sequence> <xsd:element name="loginInfo" type="tns:LoginInfo"/> <xsd:element name="appIdList" type="tns:ArrayOf_String"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="GetVersionsOutput"> <xsd:complexType> <xsd:sequence> <xsd:element name="versionInfoList" type="tns:VersionInfoList"/> <xsd:element name="status" type="tns:StatusList"/> </xsd:sequence> </xsd:complexType> </xsd:element> Input arguments loginInfo The login information for the operation. such as the user ID. and the language to be used for the session. The userId is a required element. The web services API includes the following utility operations: ! GetVersions (page 260) GetVersions Description Privileges Synopsis Retrieves the version information for any BMC Atrium CMDB component that is installed. 260 Chapter 6—Web services API operations and data structures .1 Utility operations The utility operations enable you to use CMDB utilities such as get version information of the BMC Atrium CMDB application. Operations 261 . Return values versionInfoList A list of BMC Atrium CMDB version structures. or errors generated from a call to this operation. status A list of zero or more notes. Specify a NULL value in this argument to get version information of all the existing applications.Developer’s Reference Guide appIdList A list of application IDs for which the version information is required. warnings. <complexType name="LoginInfo"> <sequence> <element name="userId" type="xsd:string"/> <element name="password" type="xsd:string"/> <element name="lang" type="xsd:string"/> </sequence> </complexType> The LoginInfo structure consists of the following elements: userId password lang The login ID for the user.1 Data structures The web services data structures are used as parameters for web services operations. Class. Instance structures Instance structures are data structures for the instance data. 262 Chapter 6—Web services API operations and data structures . The password for the user. The language to use for the current session of the application. Instance structures include: ! ! ! ! ! ! ! ! ! ! LoginInfo (page 262) ClassNameIdList (page 263) ClassNameId (page 263) ArrayOf_String (page 263) SortOrderList (page 264) SortOrder (page 264) InstanceInfoList (page 264) InstanceInfo (page 265) StatusList (page 265) Status (page 265) LoginInfo The LoginInfo data structure is used to hold the login information for a user. The data structure categories include Instance.BMC Atrium CMDB 2.0. Graph query. and Reconciliation Engine structures. ArrayOf_String The ArrayOf_String data structure is used to hold a list of string values. <xsd:complexType name="ClassNameIdList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:ClassNameId"/> </xsd:sequence> </xsd:complexType> The ClassNameIdList structure consists of the following element: ClassNameId The list of class name IDs.Developer’s Reference Guide ClassNameIdList The ClassNameIdList data structure is used to hold a list of ClassNameID structures. <complexType name="ClassNameId"> <sequence> <element name="namespaceName" type="xsd:string"/> <element name="className" type="xsd:string"/> </sequence> </complexType> The ClassNameId structure consists of the following elements: namespaceName className The namespace name for the class. Data structures 263 . The name of the class. ClassNameId The ClassNameId data structure is used to hold a class. <complexType name="ArrayOf_String"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="xsd:string"/> </sequence> </complexType> The ArrayOf_String structure consists of the following element: items The value of the attribute. <xsd:complexType name="SortOrder"> <xsd:sequence> <xsd:element name="attributeName" type="xsd:string"/> <xsd:element name="sortOrder" type="tns:SortOrderType"/> </xsd:sequence> </xsd:complexType> The SortOrder structure consists of the following elements: attributeName sortOder The name of the attribute to sort.0.BMC Atrium CMDB 2. DESCENDING—The attributes will be sorted in descending order of the list. ASCENDING—The attributes will be sorted in ascending order of the list. SortOrder The SortOrder data structure is used to hold a list of attributes on which to sort along with the sort type.1 SortOrderList The SortOrderList data structure is used to hold a list of attributes on which to sort. <complexType name="InstanceInfoList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:InstanceInfo"/> </sequence> </complexType> 264 Chapter 6—Web services API operations and data structures . InstanceInfoList The InstanceInfoList data structure is used to hold a list of InstanceInfo structures. <complexType name="SortOrderList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:SortOrder"/> </sequence> </complexType> The SortOrderList structure consists of the following element: items A list of SortOder structure items. The sort order for the list of attributes. <xsd:complexType name="InstanceInfo"> <xsd:sequence> <xsd:element name="instanceId" type="xsd:string"/> <xsd:element name="instanceAttributes" type="tns:AttributeValueList"/> </xsd:sequence> </xsd:complexType> The InstanceInfo structure consists of the following elements: instanceId instanceAttributes The ID of the instance. <complexType name="StatusList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:Status"/> </sequence> </complexType> The StatusList structure consists of the following element: items The status value of the operation. The attributes of the instance.Developer’s Reference Guide The InstanceInfoList structure consists of the following element: items A list of InstanceInfo structure items. <xsd:complexType name="Status"> <xsd:sequence> <xsd:element name="statusType" type="tns:StatusType"/> <xsd:element name="messageNum" type="xsd:long"/> <xsd:element name="messageText" type="xsd:string"/> <xsd:element name="appendedText" type="xsd:string"/> </xsd:sequence> </xsd:complexType> Data structures 265 . StatusList The StatusList data structure is used to hold a list of status information for an operation. InstanceInfo The InstanceInfo data structure is used to hold instance values. Status The Status data structure is used to hold the status information for an operation. Status might contain one or more informational messages. ERROR—Operation failed. messageNum messageText appendedText An integer value indicating the message number. Additional information for the status message. ACCESSIBLE—Status message for client accessibility.BMC Atrium CMDB 2. OK—Operation successful. 266 Chapter 6—Web services API operations and data structures .1 The Status structure consists of the following elements: statusType The type of status message for the operation. PROMPT—Status for the active link action.0. BAD_STATUS—Invalid status parameter. Status contains one or more warning messages and might also contain information messages. but some problems encountered. FATAL—Operation failed. Operaion cancelled. The description for the status message. Status contains one or more error messages and might also contain warning or informational messages. WARNING—Operation successful. Developer’s Reference Guide Graph query structures Graph query structures are data structures used in graph queries. <xsd:complexType name="Graph"> <xsd:sequence> <xsd:element name="classNameId" type="tns:ClassNameId"/> <xsd:element name="extensionId" type="xsd:string"/> <xsd:element name="adjacencyList" type="tns:GraphAdjacencyList"/> </xsd:sequence> </xsd:complexType> Data structures 267 . The graph query data structures include: ! ! ! ! ! ! ! ! GraphList (page 267) Graph (page 267) GraphAdjacencyList (page 268) GraphAdjacency (page 268) ObjectQueryInfoList (page 269) ObjectQueryInfo (page 270) RelationQueryInfoList (page 270) RelationQueryInfo (page 271) GraphList The GraphList data structure is used to hold a list of graph information. <complexType name="GraphList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:Graph"/> </sequence> </complexType> 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. GraphAdjacency The GraphAdjacency data structure is used to hold an adjacent node. <xsd:complexType name="GraphAdjancency"> <xsd:sequence> <xsd:element name="extensionId" type="xsd:string"/> <xsd:element name="objectClassName" type="tns:ClassNameId"/> <xsd:element name="objectAttributeNames" type="tns:ArrayOf_String"/> <xsd:element name="objectAttributeType" type="tns:GraphAdjancencyAttributeType"/> <xsd:element name="objectQuery" type="xsd:string"/> <xsd:element name="relationClassName" type="tns:ClassNameId"/> <xsd:element name="relationAttributeNames" type="tns:ArrayOf_String"/> <xsd:element name="relationAttributeType" type="tns:GraphAdjancencyAttributeType"/> <xsd:element name="relationQuery" type="xsd:string"/> </xsd:sequence> </xsd:complexType> 268 Chapter 6—Web services API operations and data structures .1 The Graph structure consists of the following elements: classNameId extensionId adjacencyList The name of the class for the object (node). The list of adjacent objects (nodes). <xsd:complexType name="GraphAdjancencyList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:GraphAdjancency"/> </xsd:sequence> </xsd:complexType> The GraphAdjacencyList structure consists of the following element:\ items A list of GraphAdjancency structure items. GraphAdjacencyList The GraphAdjacencyList data structure is used to hold a list of graph adjacency items. The extension ID of the node.0.BMC Atrium CMDB 2. ObjectQueryInfoList The ObjectQueryInfoList data structure is used to hold a list of CI instances. The qualification string that qualifies the relationship. NOHIDDEN—Retreive all non-hidden attributes. Data structures 269 . NONE—Retreive no attributes in the query. <complexType name="ObjectQueryInfoList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:ObjectQueryInfo"/> </sequence> </complexType> The ObjectQueryInfoList structure consists of the following element: items A list of ObjectQueryInfo items.Developer’s Reference Guide The GraphAdjacency structure consists of the following elements: extensionId objectClassName objectAttributeNames objectAttributeType The extension ID of the object. The related attribute to retrieve from the relationship. The type of object attributes to retrieve. The related attribute type. This item can be NULL. The name of the class that makes up the relationship. ALL—Retreive all the attributes. This item can be NULL. The object class name. This item can contain an empty string. objectQuery relationClassNames relationAttributeNames relationAttributeType relationQuery The qualification for the object. The object attribute to retrieve. 1 ObjectQueryInfo The ObjectQueryInfo data structure is used to hold a CI instance. <xsd:complexType name="ObjectQueryInfo"> <xsd:complexContent> <xsd:extension base="tns:InstanceInfo"> <xsd:sequence> < xsd:element name="classNameId" type="tns:ClassNameId"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> The ObjectQueryInfoList structure consists of the following element: classNameId The class name ID for the class. <complexType name="RelationQueryInfoList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:RelationQueryInfo"/> </sequence> </complexType> The RelationQueryInfoList structure consists of the following element: items A list of RelationQueryInfo items.BMC Atrium CMDB 2. 270 Chapter 6—Web services API operations and data structures .0. RelationQueryInfoList The RelationQueryInfoList data structure is used to hold a list of relationships. Developer’s Reference Guide RelationQueryInfo The RelationQueryInfo data structure is used to hold relationship information. The class ID of the child class. The class ID of the parent class. The class name of the parent class. The role name of the child instance in a relationship. The class name of the child class. <xsd:complexType name="RelationQueryInfo"> <xsd:complexContent> <xsd:extension base="tns:ObjectQueryInfo"> <xsd:sequence> <xsd:element name="instanceRole1”type="xsd:string"/> <xsd:element name="instanceRole2" type="xsd:string"/> <xsd:element name="role1ClassName" type="tns:ClassNameId"/> <xsd:element name="role2ClassName" type="tns:ClassNameId"/> <xsd:element name="role1ClassId" type="xsd:string"/> <xsd:element name="role2ClassId" type="xsd:string"/> <xsd:element name="role1InstanceId" type="xsd:string"/> <xsd:element name="role2InstanceId" type="xsd:string"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> The RelationQueryInfo structure consists of the following elements: instanceRole1 instanceRole2 role1ClassName role2ClassName role1ClassId role2ClassId role1InstanceId role2InstanceId The role name for the parent instance in a relationship. Data structures 271 . The instance ID of the parent class. The instance ID of the child class. 1 Class Structures Class structures are data structures for class and relationship definitions.0. The role names for the two classes that make up the relationship. The names of the two classes that make up the relationship. <complexType name="ClassInfoIn"> <sequence> <element name="relationshipInfo" nillable="true" type="impl:ClassRelationship"/> <element name="indexList" type="impl:IndexList"/> <element name="properties" type="impl:ClassProperties"/> <element name="customCharacList" type="impl:PropertyList"/> </sequence> </complexType> The ClassInfoIn structure consists of the following elements: relationshipInfo indexList properties customCharacList The relationship information of the class. The index list for the class. 272 Chapter 6—Web services API operations and data structures .BMC Atrium CMDB 2. The class data structures include: ! ! ! ! ! ! ! ! ClassInfoIn (page 272) ClassInfoOut (page 273) ClassRelationship (page 273) ClassProperties (page 275) IndexList (page 276) IndexInfo (page 276) PropInfoList (page 277) PropInfo (page 277) ClassInfoIn The ClassInfoIn data structure is used to set class information. <xsd:complexType name="ClassRelationship"> <xsd:sequence> <xsd:element name="relClassName1" type="tns:ClassNameId"/> <xsd:element name="relClassName2" type="tns:ClassNameId"/> <xsd:element name="roleName1" type="xsd:string"/> <xsd:element name="roleName2" type="xsd:string"/> <xsd:element name="cardinality" type="tns:Cardinality"/> <xsd:element name="cascadeDelete" type="xsd:boolean"/> <xsd:element name="isRole2WeakReference"type="xsd:boolean"/> <xsd:element name="weakPropagatedAttrsList" type="tns:WeakPropagatedAttrsList"/> </xsd:sequence> </xsd:complexType> The ClassRelationship structure consists of the following elements: relClassNames1 relClassNames2 roleNames1 The name of the parent class that is a part of the relationship. Data structures 273 . The name of the child class that is a part of the relationship. The role name of the parent class that is a part of the relationship. The ID of the class.Developer’s Reference Guide ClassInfoOut The ClassInfoOut data structure is used to retrieve class information. The type of class. <complexType name="ClassInfoOut"> <complexContent> <extension base="impl:ClassInfoIn"> <sequence> <element name="superclassNameId" type="impl:ClassNameId"/> <element name="classId" type="xsd:string"/> <element name="classType" type="impl:ClassType"/> </sequence> </extension> </complexContent> </complexType> The ClassInfoOut structure consists of the following elements: superClassNameId classId classType The name of the superclass. ClassRelationship The ClassRelationship data structure is used to hold relationship information for CI classes. ONE_MANY—One-to-many. cardinality must be one-to-one or many-to-many. isRole2WeakReference A Boolean value indicating whether role 2 is a weak reference: TRUE—The role 2 class is a weak reference. One or more instances of a class are associated with one instance of another class. FALSE—The role 2 class is not a weak reference. One instance of a class is associated with a single instance of another class. Deleting an instance in one class also deletes the instance in the related class. If the value is TRUE. FALSE—A cascade delete is not allowed.0. 274 Chapter 6—Web services API operations and data structures . MANY_ONE—Many-to-one.1 roleNames2 cardinality The role name of the parent class that is a part of the relationship. Role 2 is a weak entity and it uses role 1’s primary key as part of its own key. indicates the list of attributes that are propagated from the role 1 class to the role 2 class. ONE_ONE—One-to-one. MANY_MANY—Many-to-many. Note: This item is applicable only for one-to-one and one-to-many relationships. One instance of a class is associated with one or more instances of another class. weakPropagatedAttrsList If the value of isRole2WeakReference is TRUE. Many instances of a class are associated with many instances of another class.BMC Atrium CMDB 2. cascadeDelete A Boolean value indicating the type of delete allowed between the related classes: TRUE—A cascade delete is allowed. An integer identifying the cardinality of the relationship between the related classes: NONE—Undefined cardinality for a relationship. visiblePerms categorizationSubclass A Boolean value indicating whether the class is a categorization class. <xsd:complexType name="ClassProperties"> <xsd:sequence> <xsd:element name="isAbstract" type="tns:AbstractType"/> <xsd:element name="hiddenPerms" type="xsd:string"/> <xsd:element name="visiblePerms" type="xsd:string"/> <xsd:element name="catogorizationSubclass" type="xsd:boolean"/> <xsd:element name="description" type="xsd:string"/> <xsd:element name="isFinal" type="xsd:boolean"/> <xsd:element name="isSingleton" type="xsd:boolean"/> <xsd:element name="formName" type="xsd:string"/> <xsd:element name="author" type="xsd:string"/> <xsd:element name="auditInfo" type="tns:AuditInfo"/> </xsd:sequence> </xsd:complexType> The AttributeInfoList structure consists of the following element: isAbstract A value indicating whether the class is an abstract class. FALSE—The class is not a final class. You cannot create a subclass for a Final type class. TRUE—This is a Final class. description isFinal The description text for the class.Developer’s Reference Guide ClassProperties The ClassProperties data structure is used to hold properties for a CI class. A value indicating the groups or roles that can view the class form both—in the ObjectList form of the application and the workflow. TRUE—This is a categorization class. A Boolean value indicating whether the class is a Final class. The class will be only available through the workflow once this parameter is set for a group or role. Data structures 275 . NO—A regular class REGULAR—A regular abstract class WITH_DATA_REPLICATION—A data replication hiddenPerms abstract class A value indicating the groups or roles that cannot view the class form in the ObjectList form of the application. In categorization classes the data is stored in the parent class. FALSE—This is not a categorization class. 0. The name of the author for the class. IndexInfo The IndexInfo structure is used to hold the attributes to index. The form name for the class. 276 Chapter 6—Web services API operations and data structures .1 isSingleton formName author auditInfo A Boolean value indicating whether the class is a singleton class. <xsd:complexType name="IndexList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:IndexInfo"/> </xsd:sequence> </xsd:complexType> The IndexList structure consists of the following elements: Items An integer value indicating the number of IndexStruct items in the list. A Boolean value indicating whether the index key must be unique: TRUE—The index key is unique. The structure that holds the audit information for the class. <xsd:complexType name="IndexInfo"> <xsd:sequence> <xsd:element name="indexName" type="xsd:string"/> <xsd:element name="unique" type="xsd:boolean"/> <xsd:element name="isPrimaryKey" type="xsd:boolean"/> <xsd:element name="attributeNames" type="tns:ArrayOf_String"/> </xsd:sequence> </xsd:complexType> The IndexInfo structure consists of the following elements: indexName unique The name of the index.BMC Atrium CMDB 2. IndexList The IndexList structure is used to hold index information for the class. FALSE—The index key is not unique. <xsd:complexType name="PropInfo"> <xsd:sequence> <xsd:element name="tag" type="xsd:int"/> <xsd:element name="value" type="tns:Value"/> </xsd:sequence> </xsd:complexType> The PropInfo structure consists of the following elements: tag value An integer value indicating the particular display property.) Data structures 277 . FALSE—The index key is not a primary key index. The value for the property. PropInfoList The PropInfoList structure is used to hold a list of PropInfo structures. PropInfo The PropInfo structure is used to hold common display properties for the class. <xsd:complexType name="PropInfoList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:PropInfo"/> </xsd:sequence> </xsd:complexType> The PropInfoList structure consists of the following elements: Items A list of PropInfo structure items.Developer’s Reference Guide isPrimaryKey A Boolean value indicating whether the index is a primary key index: TRUE—The index key is a primary key index. which can be of any supported data type (see Value data structure. attributeNames The names of attributes to index. <complexType name="AttributeInfoList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:AttributeInfoOut"/> </sequence> </complexType> The AttributeInfoList structure consists of the following element: items A list of AttributeInfoOut items.BMC Atrium CMDB 2.1 Attribute structures Attribute structures are data structures for attribute definitions.0. The attribute data structures include: ! ! ! ! ! ! ! ! ! ! ! ! ! AttributeInfoList (page 278) AttributeValueList (page 279) AttributeValue (page 279) AttributeInfoIn (page 279) AttributeLimit (page 281) AttachmentLimit (page 282) CurrencyLimit (page 283) CharLimit (page 282) DateLimit (page 284) EnumLimit (page 284) IntLimit (page 285) RealLimit (page 285) AttributeLimitList (page 286) AttributeInfoList The AttributeInfoList data structure is used to retrieve attribute information. 278 Chapter 6—Web services API operations and data structures . AttributeValue The AttributeValue data structure is used to hold a list of values for an attribute. <complexType name="AttributeValueList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:AttributeValue"/> </sequence> </complexType> The AttributeValueList structure consists of the following element: items A list of AttributeValue structure items. <xsd:complexType name="AttributeValue"> <xsd:sequence> <xsd:element name="name" type="xsd:string"/> <xsd:element name="value" nillable="true" type="tns:Value"/> </xsd:sequence> </xsd:complexType> The AttributeValueList structure consists of the following elements: name value The name of the attribute. AttributeInfoIn The AttributeInfoIn data structure is used to set attribute information.Developer’s Reference Guide AttributeValueList The AttributeValueList data structure is used to hold a list of attribute information. <complexType name="AttributeInfoIn"> <sequence> <element name="value" nillable="true" type="impl:Value"/> <element name="entryMode" type="impl:AttributeEntryMode"/> <element name="createMode" type="impl:AttributeCreateMode"/> <element name="attrLimit" type="impl:AttributeLimit"/> <element name="changePerms" type="xsd:string"/> <element name="isHidden" type="xsd:boolean"/> <element name="viewPerms" type="xsd:string"/> <element name="customCharacList" type="impl:PropertyList"/> </sequence> </complexType> Data structures 279 . The value for the attribute. TRUE—The attribute is hidden in the class form. The entry mode for the attribute. PROTECTED—Allow restricted users to create an createMode attribute. A value indicating the change permissions for the attribute.BMC Atrium CMDB 2. OPTIONALENTRY—Data entry for the attribute is optional. viewPerms customCharacList A value indicating the view permissions for the attribute. DISPLAY_ONLY—Data for the attribute is display only. This attribute can be left blank. NONE—No specific entry mode defined for the attribute. A structure indicating the custom properties for the attribute. FALSE—The attribute is not hidden in the class form. OPEN—Allow any user to create an attribute. REQUIREDENTRY—Data entry for the attribute is required. 280 Chapter 6—Web services API operations and data structures . attrLimit changePerms isHidden The AttributeLimit structure defining the limit for the attribute. A Boolean value indicating whether the attribute is hidden. SYSTEM—A system-generated value will be used for this attribute.1 The AttributeInfoIn structure consists of the following elements: value entryMode The value of the attribute. This attribute cannot be modified. This attribute cannot be left blank.0. The create mode for the attribute. A DiaryLimit structure indicating the data limit for a diary data type. <xsd:complexType name="AttributeLimit"> <xsd:sequence> <xsd:element name="attachmentLimit" nillable="true" type="tns:AttachmentLimit"/> <xsd:element name="charLimit" nillable="true" type="tns:CharLimit"/> <xsd:element name="currencyLimit" nillable="true" type="tns:CurrencyLimit"/> <xsd:element name="dateLimit" nillable="true" type="tns:DateLimit"/> <xsd:element name="decimalLimit" nillable="true" type="tns:DecimalLimit"/> <xsd:element name="enumLimit" nillable="true" type="tns:EnumLimit"/> <xsd:element name="intLimit" nillable="true" type="tns:IntLimit"/> <xsd:element name="realLimit" nillable="true" type="tns:RealLimit"/> <xsd:element name="timeLimit" nillable="true" </xsd:sequence> </xsd:complexType> The AttributeLimit structure consists of the following elements: attachmentLimit attachPoolLimit charLimit currencyLimit dateLimit diaryLimit enumLimit intLimit realLimit An AttachmentLimit structure indicating the data limit value for an attachment data type. An EnumLimit structure indicating the data limit for an enumeration. An IntLimit structure indicating the data limit for an integer field. Data structures 281 . A CharLimit structure indicating the data limit for a char data type. A CurrencyLimit structure indicating the data limit for a currency data type. A RealLimit structure indicating the data limit for a real data type.Developer’s Reference Guide AttributeLimit The AttributeLimit structure is used to hold the data limit definitions for an attribute list of any data type. A DateLimit structure indicating the data limit for a date data type. An AttachPoolLimit structure indicating the data limit for an attach pool data type. A value of 0 (zero) represents an unlimited size. <xsd:complexType name="CharLimit"> <xsd:sequence> <xsd:element name="charMenu" type="xsd:string"/> <xsd:element name="format" type="xsd:string"/> <xsd:element name="FTSOption" type="xsd:int"/> <xsd:element name="maxCharLength" type="xsd:int"/> <xsd:element name="menuStyle" type="xsd:int"/> <xsd:element name="pattern" type="xsd:string"/> <xsd:element name="QBEOption" type="xsd:int"/> </xsd:sequence> </xsd:complexType> 282 Chapter 6—Web services API operations and data structures . A TimeOfDayLimit structure indicating the data limit for a time of day data type.0. maxSize The maximum size in bytes of an attachment data type.1 timeLimit timeOfDayLimit A TimeLimit structure indicating the data limit for a time data type. The AttachPoolLimit structure consists of the following elements: attachPoolName maxSize A unique name for the attachment pool. AttachmentLimit The AttachmentLimit structure is used to hold data limit definitions for the attachment data type. An integer value indicating the maximum size limit for the attachment. CharLimit The CharLimit structure is used to hold data limit definitions for the character data type.BMC Atrium CMDB 2. <xsd:complexType name="AttachmentLimit"> <xsd:sequence> <xsd:element name="attachmentPoolName" type="xsd:string"/> <xsd:element name="maxSize" type="xsd:long"/> </xsd:sequence> </xsd:complexType> The AttachmentLimit structure consists of the following elements: attachmentPoolName The name of the attachment pool for the attachment attribute. where n is the number of items in the list. L4. 0—Not full text search indexed. Specifies a style for the menu. indicates a list of a maximum of 4 items. Indicates an integer value for the query match type. specified as L<n>. 2—In the leading characters of the string. pattern QBEOption The AR System pattern specification for the field that is attached to this attribute. <xsd:complexType name="CurrencyLimit"> <xsd:sequence> <xsd:element name="allowableType" type="tns:CurrencyDetailList"/> <xsd:element name="functionalType" type="tns:CurrencyDetailList"/> <xsd:element name="highRange" type="xsd:decimal"/> <xsd:element name="lowRange" type="xsd:decimal"/> <xsd:element name="precision" type="xsd:int"/> </xsd:sequence> </xsd:complexType> Data structures 283 . NULL indicates a list is not used. Specifies whether the attached field is indexed for full text search (FTS).). 1—Full text search indexed. FTSOption maxCharLength menuStyle The menyStyle field is applicable only if a menu is attached. for example. 3—The same as the string CurrencyLimit The CurrencyLimit structure is used to hold data limit definitions for the currency data type. 1—Anywhere in the string. 1—Overwrite the existing value. with each item separated by a semicolon (.Developer’s Reference Guide The AttachPoolLimit structure consists of the following elements: charMenu format Sets the name of the AR System character menu attached to the char limit attribute Used for character list data. 2—Append to the existing value. An integer value indicating the maximum size limit for the char attribute. EnumLimit The EnumLimit structure is used to hold data limit definitions for the enum data type. The number of integers allowed to the right of the decimal point for the currency data type. DateLimit The DateLimit structure is used to hold data limit definitions for the date data type. <xsd:complexType name="DateLimit"> <xsd:sequence> <xsd:element name="minDate" type="xsd:int"/> <xsd:element name="maxDate" type="xsd:int"/> </xsd:sequence> </xsd:complexType> The DateLimit structure consists of the following elements: minDate maxDate The minimum value for the date data type.0.1 The CurrencyLimit structure consists of the following elements: allowableType functionalType highRange lowRange precision Default list of allowable currencies when new currency attributes are created. The low range of the custom characteristic for the currency data type. The high range of the custom characteristic for the currency data type. The maximum value for the date data type. <xsd:complexType name="EnumLimit"> <xsd:sequence> <xsd:element name="listStyle" type="tns:EnumStyle"/> <xsd:element name="regularEnumItems" type="tns:ArrayOf_String"/> <xsd:element name="customEnumItems" type="tns:EnumItemList"/> </xsd:sequence> </xsd:complexType> 284 Chapter 6—Web services API operations and data structures .BMC Atrium CMDB 2. Default list of functional currencies when new currency attributes are created. regularEnumItems An ordered list of enumerations. The low range of the custom characteristic for the real data type. The low range of the custom characteristic for the integer data type. customEnumItems An unordered list of enumeration. <xsd:complexType name="RealLimit"> <xsd:sequence> <xsd:element name="highRange" type="xsd:double"/> <xsd:element name="lowRange" type="xsd:double"/> <xsd:element name="precision" type="xsd:int"/> </xsd:sequence> </xsd:complexType> The RealLimit structure consists of the following elements: highRange lowRange precision The high range of the custom characteristic for the real data type. <xsd:complexType name="IntLimit"> <xsd:sequence> <xsd:element name="highRange" type="xsd:int"/> <xsd:element name="lowRange" type="xsd:int"/> </xsd:sequence> </xsd:complexType> The IntLimit structure consists of the following elements: highRange lowRange The high range of the custom characteristic for the integer data type. Data structures 285 . IntLimit The intLimit structure is used to hold data limit definitions for the integer data type. The number of digits allowed to the right of the decimal point for the real data type. RealLimit The RealLimit structure is used to hold data limit definitions for the real data type.Developer’s Reference Guide The EnumLimit structure consists of the following elements: listStyle This enumeration type is not currently supported. 0.BMC Atrium CMDB 2. Utility structures Utility structures are structures used in utility operations. such as for retrieving version information of the BMC Atrium CMDB application.1 AttributeLimitList The AttributeLimitList structure is used to hold a list of data limit definitions for an attribute list of any data type. 286 Chapter 6—Web services API operations and data structures . The utility data structures include: ! ! VersionInfoList (page 286) VersionInfo (page 287) VersionInfoList The VersionInfoList structure is used to hold a list of version information elements for the BMC Atrium CMDB components. <xsd:complexType name="VersionInfoList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:VersionInfo"/> </xsd:sequence> </xsd:complexType> The VersionInfoList structure consists of the following element: Items A list of VersionInfo structure items. <xsd:complexType name="AttributeLimitList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:AttributeLimit"/> </xsd:sequence> </xsd:complexType The AttributeLimitList structure consists of the following elements: Items A list of AttributeLimit items. The minor part (succeeding the dot) of the version number information. FALSE—The specified version does not exit.Developer’s Reference Guide VersionInfo The VersionInfo structure is used to hold version information for the BMC Atrium CMDB components. TRUE—The specified version exists. <xsd:complexType name="VersionInfo"> <xsd:sequence> <xsd:element name="applicationId" type="xsd:string"/> <xsd:element name="applicationName" type="xsd:string"/> <xsd:element name="maintenanceVer" type="xsd:int"/> <xsd:element name="majorVer" type="xsd:int"/> <xsd:element name="minorVer" type="xsd:int"/> <xsd:element name="patchNum" type="xsd:int"/> <xsd:element name="isExist" type="xsd:boolean"/> </xsd:sequence> </xsd:complexType> The VersionInfo structure consists of the following elements: applicationId applicationName maintenanceVer majorVer minorVer patchNum isExist An ID for the application. The name for the application. The major part (preceding the dot) of the version number information. Data structures 287 . The patch number. The maintenance version number. A Boolean value indicating whether the specified version of a component exists. COMPONENT_TYPE_LINE—The user interface graphical line information to retrieve (This option is currently not being used. encodedQual The encoded qualifier for the UI component query.0. The UI data structures include: ! ! ! UIComponentInfo (page 288) UIComponentResult (page 289) UIComponentResultList (page 289) UIComponentInfo The UIComponentInfo data structure is used to hold the UI components to retrieve.BMC Atrium CMDB 2. 288 Chapter 6—Web services API operations and data structures . <xsd:complexType name="UIComponentInfo"> <xsd:sequence> <xsd:element name="classId" type="xsd:string"/> <xsd:element name="componentType" type="tns:ComponentType"/> <xsd:element name="encodedQual" type="xsd:string"/> <xsd:element name="locale" type="xsd:string"/> <xsd:element name="tag1" type="xsd:string"/> <xsd:element name="tag2" type="xsd:string"/> <xsd:element name="tag3" type="xsd:string"/> <xsd:element name="tag4" type="xsd:string"/> <xsd:element name="tag5" type="xsd:string"/> </xsd:sequence> </xsd:complexType> The UIComponentInfo structure consists of the following elements: classId componentType An integer value indicating the class ID for the UI component. COMPONENT_TYPE_NONE—No component information to retrieve. COMPONENT_TYPE_ICON—The icon type component to retrieve.) COMPONENT_TYPE_LOCALIZED_LABEL—The localized label type component to retrieve.1 User interface component structures The user interface (UI) component structures are data structures used in UI component operations. COMPONENT_TYPE_TOOLTIP—The tooltip type component to retrieve. The integer value indicating the component type. the default locale will be used. Information tag used to filter a specific component type.Developer’s Reference Guide locale The name of the locale specific to the component. Information tag used to filter a specific component type. tag1 tag2 tag3 tag4 tag5 UIComponentResultList The UIComponentResultList data structure is used to hold UI component information. Information tag used to filter a specific component type. <xsd:complexType name="UIComponentResult"> <xsd:sequence> <xsd:element name="attachVal" type="tns:Attachment"/> <xsd:element name="componentInfo" type="tns:UIComponentInfo"/> <xsd:element name="dataString" type="xsd:string"/> <xsd:element name="instanceId" type="xsd:string"/> </xsd:sequence> </xsd:complexType> Data structures 289 . UIComponentResult The UIComponentResult data structure is used to hold the component query result. Information tag used to filter a specific component type. Information tag used to filter a specific component type. <xsd:complexType name="UIComponentResultList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:UIComponentResult"/> </xsd:sequence> </xsd:complexType> The UIComponentResultList structure consists of the following element: Items A list of CMDBUIComponentResult structure items. If no locale is specified in this subclasses. The instance ID for the job. Contains the component information for the specific instance.1 The UIComponentResult structure consists of the following elements: attachVal componentInfo dataString instanceId Contains the attachment for the component.BMC Atrium CMDB 2. The run ID for the job. The end time for the job. The name of the job. Contains the component data string. The Reconciliation Engine structures include: ! ! ! ! ! ! JobRunInfo (page 290) JobRunInfoList (page 291) ClassQualifierList (page 291) ClassQualifier (page 291) DatasetPairList (page 292) DatasetPair (page 292) JobRunInfo The JobRunInfo data structure is used to retrieve job information. Reconciliation Engine structures Reconciliation Engine structures are data structures for reconciliation jobs. <complexType name="JobRunInfo"> <sequence> <element name="jobStartTime" type="xsd:dateTime"/> <element name="jobEndTime" type="xsd:dateTime"/> <element name="jobInstanceId" type="xsd:string"/> <element name="jobName" type="xsd:string"/> <element name="jobRunId" type="xsd:string"/> </sequence> </complexType> The JobRunInfo structure consists of the following elements: jobStartTime jobEndTime jobInstanceId jobName jobRunId The start time for the job.0. 290 Chapter 6—Web services API operations and data structures . An integer value indicating the class ID of the UI component class. ClassQualifier The ClassQualifier data structure is used to hold information about the class qualification. all the instances in the class will be reconciled. If the qualification contains a Null value. classId Data structures 291 . <xsd:complexType name="ClassQualifier"> <xsd:sequence> <xsd:element name="qualifierString" type="xsd:string"/> <xsd:element name="classId" type="xsd:string"/> </xsd:sequence> </xsd:complexType> The ClassQualifier structure consists of the following elements: qualifierString The qualification for the class. <complexType name="JobRunInfoList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:JobRunInfo"/> </sequence> </complexType> The JobRunInfoList structure consists of the following element: items A list of information about the jobs. The ID of the class.Developer’s Reference Guide JobRunInfoList The JobRunInfoList data structure is used to retrieve information of all running jobs. ClassQualifierList The ClassQualifierList data structure is used to hold a list of ClassQualifier structures. <xsd:complexType name="ClassQualifierList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:ClassQualifier"/> </xsd:sequence> </xsd:complexType> The ClassQualifierList structure consists of the following element: Items A list of ClassQualifier structure items. If this field contains a Null. DatasetPair The DatasetPair data structure is used to hold information about the datasets to use in the reconciliation job. The dataset name of the working dataset. the dataset specified in this field will be used. workingDataset 292 Chapter 6—Web services API operations and data structures .0.1 DatasetPairList The DatasetPairList data structure is used to hold a list of DatasetPair structures. the dataset for the reconciliation job will be replaced with workingDataset before reconciliation. <xsd:complexType name="DatasetPair"> <xsd:sequence> <xsd:element name="dataset" type="xsd:string"/> <xsd:element name="workingDataset" type="xsd:string"/> </xsd:sequence> </xsd:complexType> The DatasetPair structure consists of the following elements: dataset The dataset for the reconciliation job. If the workingDataset field in the structure contains a Null.BMC Atrium CMDB 2. <xsd:complexType name="DatasetPairList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:DatasetPair"/> </xsd:sequence> </xsd:complexType> The DatasetPairList structure consists of the following element: Items A list of DatasetPair items. ACCESS_TYPE_PROCESS—Start a process for the federated interface. ACTIVATION_LAUNCH—Expand and launch the federated interface. The action to perform. ACTIVATION_DATA_RETURN—Return the expanded actionType federated interface data.Developer’s Reference Guide Federation structures Federation structures are data structures used in federation operations. ACCESS_TYPE_URL—Access a URL for the federated interface. ACCESS_TYPE_DATA_STORE—Access a data store for the federated interface. Data structures 293 . <xsd:complexType name="FederatedActivateInfo"> <xsd:sequence> <xsd:element name="accessType" type="tns:FederatedAccessType"/> <xsd:element name="actionType" type="tns:FederatedActionType"/> <xsd:element name="accessString" type="xsd:string"/> <xsd:element name="arInfo" type="tns:FederatedARInfo"/> </xsd:sequence> </xsd:complexType> The FederatedActivateInfo structure consists of the following elements: accessType The type of access required. ACCESS_TYPE_AR—Access an AR System form for the federated interface. The federation structures include: ! ! FederatedActivateInfo (page 293) FederatedARInfo (page 294) FederatedActivateInfo The FederatedActivateInfo data structure is used to hold the federated instance data activation information to retrieve. ACCESS_TYPE_MANUAL—Access a manual launch link information for the federated interface. ACCESS_TYPE_WEBSERVICE—Use a web service for the federated interface. The qualifier string for accessing the AR System. or other information. The AR System server name. 294 Chapter 6—Web services API operations and data structures .0.BMC Atrium CMDB 2. FederatedARInfo The FederatedARInfo data structure is used to hold the AR System related federated interface information to retrieve. ACCESS_TYPE_AR_PROCESS—Retrieve AR System form qualifier server url Process. <xsd:complexType name="FederatedARInfo"> <xsd:sequence> <xsd:element name="accessType" type="tns:FederatedAccessTypeAr"/> <xsd:element name="form" type="xsd:string"/> <xsd:element name="qualifier" type="xsd:string"/> <xsd:element name="server" type="xsd:string"/> <xsd:element name="url" type="xsd:string"/> </xsd:sequence> </xsd:complexType> The FederatedARInfo structure consists of the following elements: accessType The access type for the AR System. process command. Contains information related to the AR System form. ACCESS_TYPE_AR_URL—Retrieve AR System URL.1 accessString arInfo Based on the accessType subclasses. The AR System form name. contains the URL link. Contains a URL to access the AR System form depending on whether the default web path is specified on the AR System server. The audit structures include: ! ! ! AuditValueListList (page 295) AuditValueList (page 295) AuditInfo (page 296) AuditValueListList The AuditValueListList data structure is used to hold a list of audit values to retrieve. AuditValueList The AuditValueList data structure is used to hold a list of audit values to retrieve. The date and time when the audit operation was performed.Developer’s Reference Guide Audit structures Audit structures are data structures used in audit operations. <xsd:complexType name="AuditValueList"> <xsd:sequence> <xsd:element name="attributeList" type="tns:AttributeValueList"/> <xsd:element name="auditDate" type="xsd:dateTime"/> <xsd:element name="changedBy" type="xsd:string"/> <xsd:element name="operation" type="tns:AuditOpType"/> </xsd:sequence> </xsd:complexType> The AuditValueList structure consists of the following elements: attributeList auditDate The list of attribute names that changed in the audit operation. <xsd:complexType name="AuditValueListList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:AuditValueList"/> </xsd:sequence> </xsd:complexType> The AuditValueListList structure consists of the following element: Items A list of AuditValueListList structures. Data structures 295 . BMC Atrium CMDB 2. qualifierString The qualification to retrieve the audit information for the class. AuditInfo The AuditInfo data structure is used to hold the audit information to set audit options for the class. The type of audit operation performed. AUDIT_OP_MERGE—The merge operation performed. Log—Store the information for the modified attributes in a log.1 changedBy operation The user who performed the audit operation. AUDIT_OP_DELETE—The delete operation performed. AUDIT_OP_CREATE—The create operation performed. None—No auditing option set.0. AUDIT_OP_SET—The modify operation performed. <xsd:complexType name="AuditInfo"> <xsd:sequence> <xsd:element name="auditType" type="tns:AuditType"/> <xsd:element name="qualifierString" type="xsd:string"/> </xsd:sequence> </xsd:complexType> The AuditInfo structure consists of the following elements: auditType The type of audit option to set. Copy—Create a copy of an instance when an attribute is modified. 296 Chapter 6—Web services API operations and data structures . Chapter 7 Error messages This chapter contains all BMC Atrium CMDB error messages in their numerical order. Use the error number to look up any error message. The following topics are provided: ! ! ! BMC Atrium CMDB C API error messages (page 298) CMDB Console active link error messages (page 327) CMDB Console filter error messages (page 334) Error messages 297 BMC Atrium CMDB 2.0.1 BMC Atrium CMDB C API error messages Table 7-1 provides the error message details for the BMC Atrium CMDB C API errors. Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120000 Message type Error Error message The CMDB API session is not initialized. (CMDB_ERROR_SYSTEM_NOT_INITIALIZED) Description You did not initialize the CMDB API session in your API calls. Solution You must call the CMDBInitialization function before calling another BMC Atrium CMDB C API function. 120001 Error A fatal error occurred during CMDB initialization. The CMDB system cannot be initialized. (CMDB_ERROR_SYSTEM_CANNOT_BE_INITIALIZED) Description A system error prevented the CMDB from being initialized. Solution Contact your CMDB system administrator. 120002 Error Class does not exist. (CMDB_ERROR_NO_SUCH_CLASS) Description The class you are attempting to view does not exist in the CMDB. Solution Specify a valid class name or class ID. 120003 Error A required parameter is empty. (CMDB_ERROR_REQUIRED_PARAM_EMPTY) Description You did not specify a value for a required function parameter. Solution Provide a non-empty parameter to the BMC Atrium CMDB C API function call. 298 Chapter 7—Error messages Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120004 Message type Error Error message Attribute does not exist. (CMDB_ERROR_NO_SUCH_ATTRIBUTE) Description The attribute you are attempting to view does not exist. Solution Provide a valid attribute name or ID. 120005 Error The supplied attribute data type is not supported. (CMDB_ERROR_UNSUPPORTED_ATTRIBUTE_DATA_TYPE) Description The data type specified for the attribute does not exist in the CMDB. Solution Make sure that the supplied attribute data type is supported. For more information about data types, see AR_DATA_TYPE section of the ar.h file. 120006 Error Instance not found. (CMDB_ERROR_INSTANCE_NOT_FOUND) Description The specified instance is not found. Solution Specify a valid instance ID. 120007 Error CMDB system error occurred during processing. (CMDB_ERROR_SYSTEM_ERROR) Description An unexpected system error occurred during CMDB processing. Solution Contact your CMDB system administrator. 120009 Error The class name is not unique. The class name is already in use. (CMDB_ERROR_CLASS_NAME_ID_NOT_UNIQUE) Description The specified class name already exists within the given namespace. Solution Specify an unused class name. BMC Atrium CMDB C API error messages 299 BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120011 Message type Error Error message Class already exists. (CMDB_ERROR_CLASS_ALREADY_EXISTS) Description A class with the specified class ID already exists. Solution Create a class with a different class ID. 120014 Error The attribute name is not unique. The attribute name is already in use. (CMDB_ERROR_ATTRIBUTE_NAME_NOT_UNIQUE) Description An attribute with the specified name already exists. Solution Specify an unused attribute name. 120015 Error Attribute already exists. (CMDB_ERROR_ATTRIBUTE_ALREADY_EXISTS) Description An attribute with the same attribute ID already exists. Solution Specify a different attribute ID. 120016 Error The default enumeration value is invalid. (CMDB_ERROR_INVALID_ENUM_DEFAULT) Description The default value specified for the enumeration attribute is not one of the defined values. Solution Specify an enumeration value you defined. 120017 Error The specified list format is not valid. (CMDB_ERROR_INVALID_LIST_FORMAT) Description The format is L<n>, where n is the maximum number of items. Solution Modify the list format to L<n>. 300 Chapter 7—Error messages Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120018 Message type Error Error message (CMDB_ERROR_EXCEED_MAX_LIST_ITEMS) Description The number of semicolon-separated items in a character subclass exceeds the number specified in the list subclasses. Solution Decrease the number of items in the subclasses or change the list format. 120019 Error The relationship role names must be different. (CMDB_ERROR_ROLE_NAMES_MUST_BE_DIFFERENT) Description You cannot create a relationship class with the same role name. Solution Provide a different role name for each role. 120020 Error An invalid cardinality value was supplied. (CMDB_ERROR_INVALID_CARDINALITY_VALUE) Description The cardinality you specified is not one of the defined values. Solution Specify a valid cardinality value. 120021 Error Cannot create a relationship class that is derived for a nonrelationship class. (CMDB_ERROR_SUPERCLASS_MUST_BE_REL_CLASS) Description You are attempting to derive a relationship class from a class of another type. Solution Derive from a relationship class. 120022 Error The role name does not match the superclass role name. (CMDB_ERROR_ROLE_NAME_DOES_NOT_MATCH_SUPERCLASS) Description When creating a derived relationship class, the role name properties must match the superclass’s role name properties. Solution Supply the same role name as the superclass. BMC Atrium CMDB C API error messages 301 BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120023 Message type Error Error message The Configuration Item Class for the role is not a derived class of the superclass’s role. (CMDB_ERROR_CLASS_ROLE_NOT_SUPERCLASS_DERIVED) Description When creating a derived relationship class, the configuration item role classes must be the same as or derived from the superclass' configuration item role classes. Solution Derive a role class from the superclasss’ role class. 120024 Error The cardinality of the derived relationship class cannot be less restrictive than the superclass. (CMDB_ERROR_SUBCLASS_CARDINALITY_LESS_RESTRICTIVE) Description If the superclass cardinality is one-to-many, the derived class cardinality can be one-to-one, but cannot be many-to-many. Solution Specify a cardinality that is the same as the superclass or is more restrictive than the superclass. 120025 Error The supplied relationship parameter cannot be modified. (CMDB_ERROR_RELATIONSHIP_PARAM_CANNOT_BE_CHANGED) Description You cannot modify the relationship parameter. Solution Do not attempt to modify the relationship parameter. 120026 Error The supplied class type is invalid. (CMDB_ERROR_INVALID_CLASS_TYPE) Description The class type you specified is not one of the system defined class types. Solution Select a valid class type—CI or Relationship. 302 Chapter 7—Error messages Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120027 Message type Error Error message The class type cannot be modified. (CMDB_ERROR_CLASS_TYPE_CANNOT_BE_CHANGED) Description You cannot modify the class type. Solution Do not attempt to modify an existing class type. 120028 Error The attribute cannot be set. (CMDB_ERROR_ATTRIBUTE_CANNOT_BE_SET) Description You cannot set the attribute. Solution Contact your CMDB Systems Administrator. 120029 Error The attribute information is corrupt. (CMDB_ERROR_ATTRIBUTE_INFO_CORRUPT) Description Information for the attribute is corrupt. Solution Contact your CMDB systems administrator. 120030 Error Invalid instance operation on the abstract class. (CMDB_ERROR_INVALID_ABSTRACT_CLASS_INST_OPERATION) Description You are attempting to perform an abstract class operation on an instance. Solution Perform the operation on a non-abstract class. 120031 Error The parameters for the categorization class are invalid. (CMDB_ERROR_INVALID_CATEGORAIZATION_SUBCLASS) Description The parameter value you specified for the categorization class does not match with the class definition. Solution Make sure that the parameters for the categorization class are correct. BMC Atrium CMDB C API error messages 303 (CMDB_WARN_INVALID_EXPORT_ITEM_TYPE) Description The item type you are attempting to export is invalid. 120035 Error The permission list must be a list of group IDs separated by semicolons. 120033 Error The parameters for the singleton class are invalid. Solution Make sure that the parameters for the final class are correct. 120034 Warning The specified export item type is invalid.BMC Atrium CMDB 2. Solution The export item should be either of type CMDB-ITEM-TYPE-METADATA (1) or CMDB-INSTANCE-DATA (2). (CMDB_ERROR_PERMISSION_LIST_INVALID) Description You are attempting to separate a list of group IDs using an invalid character. (CMDB_ERROR_INVALID_SINGLETON_CLASS) Description The parameter value you specified for the singleton class does not match with the class definition. Solution Use semicolons to separate the groups IDs in the permission list. 304 Chapter 7—Error messages .1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120032 Message type Error Error message The parameters for the final class are invalid. (CMDB_ERROR_INVALID_FINAL_CLASS) Description The parameter value you specified for the final class does not match with the class definition. Solution Make sure that the parameters for the singleton class are correct.0. (CMDB_ERROR_RELATION_CARDINALITY_CHECK) Description The operation you are performing violates the cardinality constraint of the relationship. (CMDB_ERROR_QUERY_GRAPH_HAS_NO_STARTNODE) Description You omitted the starting node parameter in a graph query. 120039 Error The operation violates the cardinality constraint of the relationship. make sure that the operation does not violate the cardinality constraint. Solution Use an extension ID to distinguish between nodes within the same class and namespace. (CMDB_ERROR_QUERY_GRAPH_HAS_AMBIGUOUS_NODE) Description There is more than one node with the same name for the query graph. Solution Do not create more than one instance from a singleton class. Solution Make sure you specify the starting node information in the graph query. BMC Atrium CMDB C API error messages 305 . 120038 Error Creating more than one instance in a singleton class is not allowed. 120037 Error A specified node is ambiguous.Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120036 Message type Error Error message The specified query graph does not have a starting node. Solution Using the CI Relationship Viewer. (CMDB_ERROR_INVALID_SINGLETON_CLASS_INST_OPERATION) Description You can create only one instance from a singleton class. This option is not allowed. (CMDB_ERROR_RELATION_END_PT_DOES_NOT_EXIST) Description You are attempting to create a relationship for a CI instance that does not exist. 306 Chapter 7—Error messages . (CMDB_ERROR_CATSUBCLASS_REQD_ATTR_NOT_ALLOWED) Description You are specifying the entry mode option as Required for the categorization class. 120041 Error Required attributes are not allowed in categorization classes. Solution Change the entry mode to Optional. (CMDB_ERROR_SUBCLASS_MUST_BE_RS_WEAK_REFERENCE) Description You cannot derive a regular relationship subclass from a weak relationship superclass. 120043 Error Invalid cardinality for the weak relationship. Solution The cardinality for a weak relationship must be either one-to-many or one-to-one. this class must also be a weak relationship. 120042 Error Because the relationship superclass is a weak relationship.BMC Atrium CMDB 2.0. (CMDB_ERROR_INVALID_CARDINALITY_FOR_WEAK_REFERENCE) Description You are attempting to specify an incorrect cardinality for a weak relationship.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120040 Message type Error Error message The relationship endpoint instance does not exist. Solution Define this class to be of type weak relationship. Solution Make sure that the instance exists. Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120044 Message type Error Error message The weak instance is already associated with another lead instance. 120046 Error Setting lead class reference values is not allowed. Solution Unassociate the weak instance before trying to associate it with another lead instance. 120048 Error You cannot set a primary key characteristic on an attribute. Solution Define the weak class of the weak relationship to be non-abstract. (CMDB_ERROR_WEAK_INSTANCE_ALREADY_ASSOCIATED) Description You are attempting to specify more than one lead instance for a weak instance. BMC Atrium CMDB C API error messages 307 . Solution You must set the primary key characteristic by way of an index. (CMDB_ERROR_CANNOT_MODIFY_PRIMARY_KEY_ON_ATTRIBUTE) Description You can only set an attribute as the primary key by way of a unique index. 120045 Error The weak class of the weak relationship cannot be abstract. (CMDB_ERROR_NO_WEAK_RELATION_ABSTRACT_CLASS_ALLOWED) Description You cannot create a weak class of abstract type for a weak relationship. Solution Do not attempt to modify propagated read-only attributes values. (CMDB_ERROR_SETTING_LEAD_CLASS_REF_DISALLOWED) Description You cannot modify the attributes propagated from the lead class. Solution Define the weak class to be a non-categorization class. (CMDB_ERROR_DELETE_CLASS_FAILED_DATA_EXISTS) Description You are attempting to delete a class that contains data.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120049 Message type Error Error message The primary key must be a unique index. Solution To delete a class that contains data. Solution Specify only one primary key per class. 120051 Error The weak class for the weak relationship class cannot be a categorization class. (CMDB_ERROR_PRIMARY_KEY_ISNT_UNIQUE) Description The attribute you are attempting to set as primary key contains duplicate values. (CMDB_ERROR_NO_RHS_CATSUBCLASS_FOR_WEAK_REFERENCE) Description You are attempting to create the right-hand class of type categorization class in a week relationship. specify Delete With Data as the delete option. 308 Chapter 7—Error messages .BMC Atrium CMDB 2.0. Solution Specify a unique index as the primary key. 120053 Error The class cannot be deleted because this class has instance data. 120050 Error You can have only one primary key per class. (CMDB_ERROR_MORE_THAN_ONE_PRIMARY_KEY_DISALLOWED) Description You are attempting to set more than one primary key for a class. Solution To delete a class with dependencies. specify Delete With Dependencies as the delete option. WARNING: The Delete With Dependencies option will also delete all dependent classes. 120057 Warning This class is a weak class of the relationship class being deleted. (CMDB_WARN_DELETE_CLASS_FAILED_DEP_REL_CLASS) Description This is a warning that a CI instance for the specified relationship class is being deleted.Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120054 Message type Error Error message The class cannot be deleted because there are class dependencies on this class. (CMDB_WARN_DELETE_CLASS_FAILED_DEP_REG_CLASS) Description This is a warning that the class being deleted had a derived class. This option will delete the classes even if they contain data. BMC Atrium CMDB C API error messages 309 . (CMDB_WARN_DELETE_CLASS_FAILED_DEP_WEAK_REF_CLASS) Description This is a warning that the specified weak class of the relationship class is being deleted. Solution Make sure that the source attribute exists in the lead class. 120058 Error The source attribute on the lead class for attribute propagation does not exist. (CMDB_ERROR_DELETE_CLASS_FAILED_DEPENDECIES_EXISTS) Description You are attempting to delete a class that has a subclass or is CI instance for a relationship. 120056 Warning An endpoint for this relationship class is the class being deleted. (CMDB_ERROR_NO_SUCH_SOURCE_ATTRIBUTE_FOR_WEAK_REL) Description You are attempting to propagate an attribute that does not exist in the source class. 120055 Warning This class is a derived class of the class being deleted. (CMDB_ERROR_ATTRIBUTE_DATATYPE_MISMATCH_FOR_WEAK_REL) Description The attributes being propagated from the lead and weak classes must have the same data type. (CMDB_ERROR_CATGORIZATION_SUB_PERM_LIST_INVALID) Description The categorization class permissions must match the permissions of its superclass.0. (CMDB_ERROR_TARGET_WEAK_ATTR_CANNOT_DERIVED_ATTR) Description You are attempting to specify a derived attribute as the target attribute in the weak class. 120060 Error The data types for the source and target attributes do not match. 120062 Error Permissions for a categorization class must be the same as the permissions for the superclass. (CMDB_ERROR_NO_SUCH_TARGET_ATTRIBUTE_FOR_WEAK_REL) Description You are attempting to propagate an attribute of the weak class that does not exist. Solution Specify a target attribute for the weak class that is not a derived from its superclass.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120059 Message type Error Error message The target attribute on the weak class for attribute propagation does not exist. Solution Make sure that the categorization class permissions match its superclass.BMC Atrium CMDB 2. 310 Chapter 7—Error messages . Solution Make sure that the data type of the propagated attributes match. 120061 Error The specified target attribute on the weak class cannot be a derived attribute from a superclass. Solution Make sure that the target attribute exists in the weak class. Solution Specify appropriate values that match the attribute data type definition. (CMDB_WARN_NO_SUCH_ATTACHMENT_POOL) Description You are attempting to specify an attachment pool that does not exist. 120068 Error Data type does not match the data type defined for this attribute. 120067 Error An entry in the import item list is invalid. (CMDB_ERROR_MISMATCHING_ATTR_DATATYPE) Description The value you specified for the attribute does not match the attribute definition. Solution Make sure that the item exists in the specified directory. 120064 Error The system failed to create a unique identifier. (CMDB_ERROR_INSTANCE_DELETE_ON_FORM_DISALLOWED) Description You cannot delete an instance from the regular subclass form. (CMDB_ERROR_CREATE_GUID_FAILED) Description The system was unable to generate a unique identifier. Solution Create the attachment pool. 120065 Warning Specified attachment pool does not exist. Solution If required. (CMDB_ERROR_IMPORT_ITEM_ITEM) Description An item in the specified import directory is not available. restart your process to generate the GUID.Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120063 Message type Error Error message Instances cannot be deleted from this form. BMC Atrium CMDB C API error messages 311 . Solution Delete the instance using the join form of the class. Solution Specify a namespace name that is 70 characters or less. (CMDB_ERROR_SETTING_FORM_NAME_CHARAC_DISALLOWED) Description The Form Name characteristic is an invalid option for the class.0. (CMDB_ERROR_INVALID_INDEX_LIST) Description You specified an invalid index list.BMC Atrium CMDB 2. Solution Specify a valid value for the class characteristic. Must be 70 characters or less. 312 Chapter 7—Error messages . 120071 Error Setting the form name class characteristic is not allowed. 120070 Error Index list is invalid.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120069 Message type Error Error message Attribute value does not fall within the limits defined for this attribute. 120072 Error The data type for the class characteristic value is invalid. Solution You cannot set the form name class characteristic. Solution Make sure that the index properties that are specified in the error message. 120073 Error The namespace name is too long. (CMDB_ERROR_ATTRIBUTE_VALUE_OUT_OF_LIMITS) Description The attribute value you specified is not within the defined range for the attribute. (CMDB_ERROR_INVALID_DATATYPE_FOR_CLASS_CHARAC) Description The value you specified for class characteristic subclasses does not match its datatype. are valid. (CMDB_ERROR_NAMESPACE_NAME_TOO_LONG) Description The namespace name you specified cannot exceed its character limit. Solution Make sure that the attribute value is within the defined range. Must be 80 characters or less. 120075 Error The subclass namespace must match the superclass namespace. Solution Create a name containing the following valid characters: alphanumeric.) BMC Atrium CMDB C API error messages 313 . Solution Specify a class name that is 80 characters or less.Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120074 Message type Error Error message The class name is too long. (CMDB_ERROR_CHARACTER_DISALLOWED_IN_NAME) Description You specified invalid characters for the name. 120076 Error No value supplied for a required attribute. (CMDB_ERROR_MODIFY_NAMESPACE_NAME_IS_DISALLOWED) Description You cannot modify the namespace name after the class is created. Solution If required. (CMDB_ERROR_SUBCLASS_SUPERCLASS_NAMESPACE_MISMATCH) Description The namespace you specified for the subclass does not match its superclass. Solution Specify the same subclass namespace as the superclass. 120077 Error Modifying the namespace name after class creation is not allowed. (CMDB_ERROR_REQUIRED_ATTRIBUTE_VALUE_MISSING) Description You did not specify a value for a required attribute. underscore (_). delete this class and create a new one. Solution Specify a value for the required attribute. 120078 Error The supplied character is not allowed in the name. (CMDB_ERROR_CLASS_NAME_TOO_LONG) Description The classname you specified cannot exceed its character limit. or period (. 7-Audit_Option. 1-View_Perms. Solution Specify an attribute name that is 80 characters or less. 1-Required. 6-Create_Mode. (CMDB_ERROR_ATTR_subclasses_ID_NOT_UNIQUE) Description The subclasses ID you specified is already in use within the specified class hierarchy. 5Propogated_Owner. or 8Namespace. 120080 Error Invalid value for the entry mode. 4-Primary_Key. Must be 80 characters or less.0. (CMDB_ERROR_ATTRIBUTE_NAME_TOO_LONG) Description The attribute name you specified cannot exceed its character limit. Solution Specify one of the valid values: 0-None. Solution Specify one of the valid values: 0-None. 120082 Error Invalid data type for the attribute characteristic. (CMDB_ERROR_INVALID_DATATYPE_FOR_ATTR_CHARAC) Description The data type you specified for the attribute characteristic is invalid. Solution Specify a different subclasses ID.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120079 Message type Error Error message The attribute name is too long. 3-System. 3-Hidden. (CMDB_ERROR_INVALID_ATTRIBUTE_ENTRY_MODE) Description You specified an invalid value for the entry mode subclasses. or 4-Display_Only. 120081 Error The subclasses ID is not unique within the class or within the class hierarchy. 2-Optional. 2Change_Perms. 314 Chapter 7—Error messages .BMC Atrium CMDB 2. (CMDB_ERROR_ATTRIBUTE_ID_NOT_UNIQUE) Description You specified an attribute ID that is not unique within the class hierarchy. Solution Specify a CI instance from the same namespace as the relationship class. (CMDB_ERROR_SETTING_PROP_OWNER_CHARAC_DISALLOWED) Description The propagated owner characteristic is an invalid option for the attribute. 120087 Error Attribute ID is not unique within the class or within the class hierarchy. BMC Atrium CMDB C API error messages 315 . (CMDB_ERROR_SETTING_PRIMARY_KEY_CHARAC_DISALLOWED) Description The primary key characteristic is an invalid option for the attribute. 120085 Error The namespace for the relationship end point class does not match the namespace of the relationship class.Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120083 Message type Error Error message Setting the primary key attribute characteristic is not allowed. Solution Specify a unique attribute ID within the class hierarchy. Solution You cannot set the primary key attribute characteristic. Solution Specify a valid enum name. Solution You cannot set the propagated owner attribute characteristic. (CMDB_ERROR_REL_END_POINT_CLASS_NAMESPACE_MISMATCH) Description You are attempting to create a CI instance in a different namespace that the relationship class. 120086 Error Enum name is invalid. (CMDB_ERROR_ENUM_NAME_INVALID) Description The enum name you specified is invalid. 120084 Error Setting the propagated owner attribute characteristic is not allowed. (CMDB_ERROR_NO_ACCESS_TO_ATTRIBUTE) Description You do not have permission to the access the attribute. Solution Contact your CMDB system administrator. 120089 Error You do not have access to the class. 120094 Error The direction provided for graph query is not valid.0. 120092 Error The dataset ID and Reconciliation Identity combination is not unique. (CMDB_ERROR_INVALID_ATTR_LIMIT_DATA_TYPE) Description You specified an invalid value for the attribute limit structure. Solution Specify one of the valid values: 0-Direction_Out.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120088 Message type Error Error message Invalid data type for the attribute limit structure. 316 Chapter 7—Error messages . Solution Change one of these values to make the combination unique. (CMDB_ERROR_DATASET_ID_RECON_ID_NOT_UNIQUE) Description The combination of reconciliation ID and dataset ID is not unique. (CMDB_ERROR_QUERY_GRAPH_INVALID_DIRECTION) Description You specified an invalid direction value for the graph query. Solution The data type for the attribute limit structure must either match the data type of the attribute or be NULL.BMC Atrium CMDB 2. or 1Direction_In. Solution Contact your CMDB system administrator. (CMDB_ERROR_NO_ACCESS_TO_CLASS) Description You do not have permissions to access the class. 120090 Error You do not have access to the attribute. Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120095 Message type Error Error message Current object store API version is deprecated. Solution Upgrade to the current version of the CMDB API. 120097 Information Instance import summary. CMDB_DELETE_CLASS_OPTION_WITH_DATA. 120099 Error The metadata status value specified is invalid. CMDB_ERROR_INVALID_DELETE_OPTION) Description You specified an invalid delete option for the class. (CMDB_ERROR_CURRENT_API_IS_DEPRECATED) Description You are attempting to use an API call that is now deprecated. 120096 Warning Instances skipped during import. Solution Specify one of the valid values: CMDB_DELETE_CLASS_OPTION_NONE. BMC Atrium CMDB C API error messages 317 . (CMDB_INFO_IMPORT_INST_SUMMARY) Description This message signifies that the instance import summary follows. or CMDB_DELETE_CLASS_OPTION_ALL_DEPENDENCIES. (CMDB_WARN_IMPORT_INST_SKIPPED) Description This is a warning that certain instances were not imported during the import activity. 120098 Error The deleteOption value specified is invalid. (CMDB_ERROR_INVALID_META_DATA_STATUS) Description You specified an invalid value for the metadata status. Solution Specify one of the valid values: CMDB_META_DATA_STATUS_DELETE_PENDING or CMDB_META_DATA_STATUS_CHANGE_PENDING. 120103 Error Cascade Delete cannot be enabled for the relationship because its cardinality is invalid for cascade deletes. (CMDB_ERROR_UNRECOGNIZED_VERSION_PATCH_STRING) Description The version string for the CMDB patch is invalid. Solution Specify a cardinality of one-to-many or one-to-one for the relationship. Solution Specify a valid class ID for the instance. Solution Contact BMC technical support for help. 120102 Error A version string in the SHARE:Application_Properties form is invalid.0. (CMDB_ERROR_ACCESS_TLS_BLOCK_FAILED) Description Access to thread local storage block failed. 120101 Error Internal system error. 120104 Error Reconciliation job cannot be started. (CMDBRE_ERROR_START_JOB_RUN_FAILED) Description An internal error has caused your reconciliation job to fail. 318 Chapter 7—Error messages .BMC Atrium CMDB 2. (CMDB_ERROR_INVALID_REL_ENDPOINT_CLASS_ID) Description You specified an invalid class ID for one of the CI instances in the relationship. (CMDB_ERROR_INVALID_CASCADE_DELETE_VALUE) Description You specified an invalid cascade delete option for the relationship.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120100 Message type Error Error message One of the endpoints specified for the relationship has an invalid class ID. Solution Replace the patch string with a valid version string. Solution Contact your CMDB system administrator. (CMDBRE_ERROR_JOB_NOT_RUNNING) Description You are attempting to cancel a job that is not running. Solution Before you cancel a job. (CMDBRE_ERROR_INACTIVE_JOB_START) Description You are attempting to start an inactive job. (CMDBRE_ERROR_JOB_LOOKUP) Description The job you are referring to does not exist. 120109 Error Failed to start an inactive job. Solution Contact BMC technical support for help. BMC Atrium CMDB C API error messages 319 . make sure that the job is running. (CMDBRE_ERROR_CANCEL_JOB_RUN_FAILED) Description An internal error has caused an unsuccessful cancellation of your reconciliation job. 120110 Error Job does not exist. Solution Make sure that the associated job ID is correct. 120108 Error Failed to find the specified job. Solution A job must be in an active state before you start the it. 120107 Error Failed to cancel a job not running. Solution Make sure that the job exists.Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120105 Message type Error Error message Failed to cancel reconciliation job. (CMDBRE_ERROR_JOB_NOT_EXIST) Description The job you are referring to does not exist. Solution Make sure that the number of IDs and the values match.BMC Atrium CMDB 2. Solution Make sure that the control structure is correct and your API session is properly initialized. 120114 Error Invalid Enum ID. Solution Please wait until the currently running job is completed. which is already running. 120117 Error (CMDB_ERROR_INVALID_AUDIT_LOG_TYPE) Description If you specified the Copy audit option for your derived class. 120116 Error The session ID in the supplied control structure is invalid. (CMDBRE_ERROR_JOB_ALREADY_RUN) Description You cannot start a job that is already running. Solution Make sure that the superclass and subclasses have the same audit option settings. (CMDB_ERROR_ENUM_ID_INVALID) Description You have specified an invalid Enum ID.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120111 Message type Error Error message Failed to start a job. Solution Make sure that the Enum ID is valid. 320 Chapter 7—Error messages . its superclasses cannot contain the Log audit option setting.0. (CMDB_ERROR_ENUM_ID_VALUE_LEN_MISMATCH) Description The number of IDs and their values you specified do not match. (CMDB_ERROR_INVALID_AUDIT_COPY_TYPE) Description The session ID that you specified for the login information is invalid. 120113 Error Number of IDs and Values does not match. Solution Make sure that the If instance for the dataset ID you specified exists in the BMC. 120123 Error An internal error occurred. 120122 Error The source dataset ID is missing. BMC Atrium CMDB C API error messages 321 . make sure that the ID is the same as the DatasetId passed as parameter to the API call. (CMDB_ERROR_DATASET_UNDERLAY_INTERNAL_ERROR) Description The specified class ID and reconciliation ID for the underlay dataset do not exist.Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120120 Message type Error Error message Invalid dataset ID reference by the instance. 120121 Error The dataset ID does not exist. Create. (CMDB_ERROR_NO_SUCH_DATASET) Description The dataset ID you specified does not exist. Delete operations. (CMDB_ERROR_DATASET_OVERLAY_SOURCE_MISSING) Description You did not specify the source dataset ID. Solution Make sure that the source dataset for the dataset provided exists. restart the AR System server. If the problem persists. Solution Make sure the specified class ID and reconciliation ID exist.CORE:BMC_Dataset class. If the DatasetId attribute value is given in the attribute value list. Solution Perform the Set. (CMDB_ERROR_INVALID_DATASET_ID) Description The dataset ID you specified for the instance is invalid. Solution Make sure that the access for the dataset is not set to read-only or writable by the client type. (CMDB_WARNING_DATASET_CACHE_LOADING) Description An internal error occurred when accessing federated data. (CMDB_ERROR_BULK_TRAN_API_SESSION_ID_BAD) Description The API session information that you specified in the bulk transaction function is incorrect. (CMDB_WARNING_FOREIGN_KEY_EXPAND_FAILED) Description An error occurred when attempting to expand a federated link. 120126 Error Federation foreign key expansion failed. Solution Contact your CMDB system administrator. 322 Chapter 7—Error messages . 120127 Error The session ID in the supplied control structure is invalid. Solution Make sure that the control structure is correct and that your API session is properly initialized.BMC Atrium CMDB 2. Solution Make sure that the federated foreign key link has the appropriate BMC_FederatedKeyLink class name.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120124 Message type Error Error message Access to the dataset denied. (CMDB_ERROR_DATASET_NO_PROPER_ACCESS) Description You are attempting to access a dataset for which you do not have appropriate access.0. 120125 Warning Federated data corruption. 120131 Error Federation launch failed. 120130 Error Failed to promote class. (CMDB_ERROR_SUPERCLASS_OF_TYPE_ABSTRACT) Description You are attempting to promote a class that is derived from an abstract class. Solution The attempted operation can only be performed once a bulk transaction session is started. Solution Make sure no other bulk transaction function is in progress. which has abstract superclass. (CMDB_ERROR_BULK_TRAN_ALREADY_BEGUN) Description You cannot start more than one bulk transaction function at a time. (CMDB_ERROR_FEDLINK_LAUNCH_FAILED) Description The federation link that you are attempting to launch failed.Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120128 Message type Error Error message Cannot start another bulk transaction because a bulk transaction has already been started. (CMDB_ERROR_BULK_TRAN_NOT_BEGUN) Description You are attempting to perform a bulk transaction operation before starting a bulk transaction session. BMC Atrium CMDB C API error messages 323 . Solution You cannot promote a class that is derived from an abstract class. Solution Contact your CMDB system administrator. 120129 Error The attempted operation cannot be performed because the bulk transaction has not started. Solution Specify a valid CMDB RPC port number. 324 Chapter 7—Error messages . 120133 Error The CMDB RPC port specified is invalid. 120136 Error The requested object was not found in the import buffer. (CMDB_ERROR_SUPER_CLASS_NOT_FOUND) Description The superclass you specified is not found. or 390697 (Admin thread).xml (import) file.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120132 Message type Error Error message Superclass not found. (CMDB_WARNING_REQUESTED_IMPORT_OBJECT_NOT_FOUND) Description The import item list object (class or attribute) that you requested does not exist in the . (CMDB_ERROR_FAILED_TO_RUN_QUALIFICATION) Description The application failed to parse the specific qualification. Solution Make sure that the requested import object (class or attribute) exists in the . Solution Correct the qualification based on the error message description provided. (CMDB_ERROR_RPC_SOCKET_RANGE) Description The RPC port that you specified for the BMC Atrium CMDB is invalid. Valid port numbers include: 0.xml (import) file. 390696. 120134 Error Failed to parse the qualification.0. Solution Make sure that the specified superclass exists.BMC Atrium CMDB 2. (CMDB_ERROR_INVALID_DATA_IMPORT_OPTION) Description The import option value you specified is incorrect. 120139 Error The CoreDatasetId specified already exists. BMC Atrium CMDB C API error messages 325 .Developer’s Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120137 Message type Error Error message Cannot import instance because the instance ID already exists. Solution Make sure you select the correct import option. Solution Delete the specified attribute from the superclass. (CMDB_ERROR_DUPLICATE_DATASET_ID) Description The CoreDatasetId you specified already exists. Solution Specify a different CoreDatasetId. Solution Make sure you specify a unique instance ID for the instance or select an import option other than 1. (CMDB_ERROR_INSTANCE_ID_ALREADY_EXISTS) Description The instance ID you specified already exists. 120138 Error Invalid import data option. 120140 Error Attribute does not belong to the class specified. (CMDB_ERROR_ATTRIBUTE_BELONGS_TO_SUPERCLASS) Description The attribute you specified is inherited from a superclass and cannot be deleted from this subclass. 120145 Error Class ID and qualification information exceeded the limit of 4096 bytes. Solution Divide the classQualList information into more than one API calls.0. (CMDB_ERROR_REL_ENDPOINT_MARK_AS_DELETED) Description You are attempting to set MarkAsDeleted to No for a relationship instance whose one or both endpoints are still soft deleted.1 Table 7-1: BMC Atrium CMDB C API Error Messages Error number 120141 Message type Error Error message Can’t set MarkAsDeleted to ‘No’ on the relationship instance because one or both of the relationship endpoints are MarkAsDeleted. (CMDB_ERROR_NO_AUDIT_COPY_CLASS) Description You are attempting to retrieve Copy audit data from a class whose audit type is set to a value other than Copy. 326 Chapter 7—Error messages . Solution You cannot retrieve Copy audit data from a class whose audit type is set to a value other than Copy. (CMDB_ERROR_RE_START_JOB_RUN_INFO_EXCEED_LIMIT) Description The combined length of the classQualList and datasetList parameters you specified exceeds 4096 bytes after encoding the qualification. 120142 Error Audit type Copy is not set for this class.BMC Atrium CMDB 2. (MarkAsDeleted) Solution Make sure you set MarkAsDeleted to No on both endpoints of the relationship before setting MarkAsDeleted to No on the relationship instance. operator. Description You cannot leave the attribute. Solution Make sure you specify the required fields for the qualification. Description The Audit option is not enabled for any class in the CDM. Table 7-2: CMDB Console active link error messages Error number 13002 Message type Error Error message Qualification for the Where clause not defined. and value for the search. To view audit history.Developer’s Reference Guide CMDB Console active link error messages Table 7-2 provides the error message details for CMDB Console messages that are generated by active links. and value fields empty when specifying a qualification for the instance search. CMDB Console active link error messages 327 . Description You are attempting to save a search without specifying a search name for it. Solution Contact your CMDB system administrator to make sure the Audit option for classes is enabled both at the class and attribute level. Solution Make sure you specify a name for the search that you want to save. 13010 Error Search name not defined. such as the attribute. Description You cannot search instances unless you specify the Where clause qualification. operator. 13015 Error Auditing not enabled for any class. Solution Make sure you specify the Where clause qualification for the instance search. 13003 Error Qualification for the search operation not defined. at least one class must be audit enabled. Solution Make sure you select an instance for the viewing the audit history. Solution Make sure you specify a unique name for saving the search. You must select only two instances at a given time for the comparison. Description The name you specified for the search is already in use.0. You can view audit history for only one instance at a given time. Description You are attempting to view the audit history of the instance. Solution Make sure you select two instances for the comparison. Solution Make sure you specify a unique name for saving the Public search. Solution Contact your CMDB system administrator. 13204 Error You do not have access to any audited entry for this instance. Description You did not select the instances that you want to compare. Description The name you specified for the Public search is already in use. 13203 Error A Public saved search with the specified name already exists. 13202 Error A saved search with the specified name already exists. 328 Chapter 7—Error messages . You do not have access permissions to perform this operation.1 Table 7-2: CMDB Console active link error messages Error number 13200 Message type Error Error message Instance not selected for viewing audit history.BMC Atrium CMDB 2. 13201 Error Instances not selected for the comparison. Description You did not select the instance for which the audit history is to be displayed. use the Cancel button. 120065 Error OBJSTR:AttributeDef_CheckCustomSelection You must provide ID Values for a Custom Selection. Description You did not specify ID values for the field values when creating a custom selection field. The field ID you specified for the attribute is greater than the maximum value of a 32-bit signed integer data type. No changes were saved. Description Your changes were not saved. Solution Make sure you specify ID values for the custom selection field. CMDB Console active link error messages 329 . see the Installation and Configuration Guide. Solution Make sure that the field ID is less than or equal to 2147483647. 125000 Error OBJSTR:AttributeDef_OnLoseFocus_subclassesID Invalid subclasses ID. Description You have not installed the BMC Atrium CMDB 2.Developer’s Reference Guide Table 7-2: CMDB Console active link error messages Error number 13205 Message type Warning Error message There is no audited entry for this instance. Solution To save your changes before closing a form. Description The instance for which you want to view audit history has no data.0 Help. 20152 Warning OBJSTR:OnCancel_Cancel_Close/Undisplay Close operation canceled. Solution Make sure there is data for the specific instance. 44000 Error OBJSTR:Help_OpenHelpFile Online Help has not been installed. Solution To install the online Help. Description You did not specify the data type for a field on the Characteristics tab. Solution Make sure you specify a data type for the field.1 Table 7-2: CMDB Console active link error messages Error number 125002 Message type Error Error message OBJSTR:AttributeDef_OnSelect_CharacteristicsTab01 Please specify Data Type.0. Solution Specify a data type for the Characteristics tab. Solution Specify a data type for the Characteristics tab. Description You did not specify the data type for a field on the Characteristics tab. Description You did not specify the data type for a field on the Characteristics tab.BMC Atrium CMDB 2. 125004 Error OBJSTR:AttributeDef_OnSelect_CharacteristicsTab03 Please specify Data Type. 125005 Error OBJSTR:AttributeDef_OnSelect_CharacteristicsTab05 Please specify Data Type. 125003 Error OBJSTR:AttributeDef_OnSelect_CharacteristicsTab02 Please specify Data Type. Description You did not specify a data type for a field on the Characteristics Tab. Solution Specify a data type for the Characteristics tab. Solution Specify a data type for the Characteristics tab. 125005 Error OBJSTR:AttributeDef_OnSelect_CharacteristicsTab04 Please specify Data Type. Description You did not specify the data type for a field on the Characteristics tab. 330 Chapter 7—Error messages . Solution Make sure you specify the classname and namespace attributes.Developer’s Reference Guide Table 7-2: CMDB Console active link error messages Error number 125006 Message type Error Error message OBJSTR:ClassDef_Attrib_AddSearchBtns_CheckForClassAndName space_Msg Namespace and Class Name must be entered before you can add or search attributes. Description You did not specify the classname and namespace attributes for the subclass. 125009 Error OBJSTR:ClassDef_OnSaveChkReqsubclasses Namespace and Class Name are required subclasses. Description The class name you specified is not unique within the class namespace. 125008 Error OBJSTR:ClassDef_ChkSuperclassIsNotFinalClass02 Invalid superclass. 125007 Error OBJSTR:ClassDef_ChkDuplicateClass02 There is already an existing class with class name $490001100$ in the namespace $400109900$. Description You are attempting to derive a subclass from a final class. Class $400103900$ is a final class and cannot be used as a superclass. Solution You cannot derive a subclass from a final class. Solution Specify a different name for your class. CMDB Console active link error messages 331 . Description You did not specify a namespace and classname for the attribute. Solution Make sure that you specify a namespace and classname. Role 1. Role 2. Description You did not specify the required attributes for the relationship class. 125012 Error OBJSTR:IdxCon-AttribAlreadyExist This attribute is already part of the Index. Solution Specify a different attribute. Please use a different name. 125013 Error OBJSTR:IdxCon-GainFocusProperty_tbl Please enter the Index Name first. 332 Chapter 7—Error messages . Description You are attempting to specify an attribute for the index that is already in use. Solution Specify an index name. 125014 Error OBJSTR:IdxCon-IndexNameLooseFocus01a There is already an index by the name of: $400111200$. Solution Specify a different attribute. Solution Make sure you specify these values before saving. Class 2.1 Table 7-2: CMDB Console active link error messages Error number 125010 Message type Error Error message OBJSTR:ClassDef_OnSaveChkReqsubclassesForRelationship Class 1. Description You are attempting to specify an attribute for the index that is already in use.0.BMC Atrium CMDB 2. Description You must specify a name for the index before you create it. and Association Enforcement are required subclasses for relationship classes. Description You are attempting to create a categorization class without specifying its superclass. Description You did not specify the attribute that you want to propagate in the weak relationship. 125036 Error AL: OBJSTR:ClassDef_OnSave_ValidateCategSubClass You must specify a superclass when creating a categorization class. Description The attribute number specified in the message is saved. You can only map Attributes with the same data type. CMDB Console active link error messages 333 . Solution You must specify an attribute from Class 1 and Class 2.Developer’s Reference Guide Table 7-2: CMDB Console active link error messages Error number 125028 Message type Error Error message OBJSTR:WRdlg-cmdMapWeakRel01 Please select an Attribute from Class 1 and Class 2. 125029 Error OBJSTR:WRdlg-cmdMapWeakRel02 Invalid data type mismatch. 125030 Information OBJSTR:AttributeDef_SaveChanges Attribute '$400009700$' has been saved. Description The data types of the attributes you specified do not match. Solution Make sure that you specify a superclass for the categorization class. Solution Make sure that the data types of the attributes match. Solution Make sure that the instance name is correct. make sure you specify a many-to-one or one-to-many cardinality for it. Description You are attempting to create a relationship for an instance that is already related to another instance. If you need to create more than one relationship for the specified instance.BMC Atrium CMDB 2. and there is already an association of type $490005100$ between this $490021101$ and another $490021100$.1 CMDB Console filter error messages Table 7-3 provides the error message details for the CMDB Console messages that are generated by filters. Solution Make sure that the instance name is correct. and there is already an association of type $490005100$ between this $490021101$ and another $490021100$. Solution Make sure that the association type exists. or between this $490021100$ and another $490021101$. 334 Chapter 7—Error messages . If you need to create more than one relationship for the specified instance. 20280 Error BSM:AUD_AssocEnforce1-ManyRelationship 2 The relationship $490005100$ between $490021100$ and $490021101$ is defined as “1 to Many”. Description You are attempting to create a relationship for an instance that is already related to another instance.0. Table 7-3: CMDB Console filter error messages Error number 20163 Message type Error Error message OBJSTR:Lookup Association Name5 No entry found in SHARE:AssociationType with associationTypeId = $500000041$. 20279 Error BSM:AUD_AssocEnforce1-1Relationship 2 The relationship $490005100$ between $490021100$ and $490021101$ is defined as 1 to 1. Description The association type you specified is not found. make sure you specify a many-to-one or one-to-many cardinality for it. ” and there is already an association of type $490005100$ between this $490021100$ and another $490021101$. Solution Make sure that the superclass name you specified for the instance is correct. If you need to create more than one relationship for the specified instance. 50030 Error OBJSTR:Instance_CheckAbstractClassNoInstantiate Invalid instance related operation on this abstract class. 20369 Error OBJSTR:Lookup Form Name5 No entry found in SHARE:Object with Form Name = $-5$. Description You are attempting to create a relationship for an instance that is already related to another instance. Solution Contact your CMDB system administrator. Description You cannot derive an instance from an abstract class. CMDB Console filter error messages 335 . Solution Make sure that the instance name is correct. Description The form name you specified is not found.Developer’s Reference Guide Table 7-3: CMDB Console filter error messages Error number 20281 Message type Error Error message BSM:AUD_AssocEnforceMany-1Relationship 2 The relationship $490005100$ between $490021100$ and $490021101$ is defined as “Many to 1. 20366 Error OBJSTR:Lookup Localized String5 No entry found in SHARE:MenuItem_LT with Developer Name = $300132000$. Solution Contact your CMDB system administrator. make sure you specify a many-to-one or one-to-many cardinality for it. Description The localized string for the menu item is not found. Solution Make sure that the class name you specified for the singleton class is correct. Instance ID: $490008000$. Solution Make sure that the Instance ID for the specified Class ID exists. Description The instance ID specified in the role <number> for the specified class is not found. Description You are attempting to modify the reference values of the lead class in a weak relationship. 50046 Error OBJSTR:Instance_RelWeakRef:BMC:<class name>:<step number> Modifications to the lead class references values are not allowed. This instance is already a part of another weak relationship.0. 336 Chapter 7—Error messages . Solution Make sure that the instance name you specified for the weak instance is correct. 50044 Error OBJSTR:Instance_RelWeakRef:<class name>:<step number> Weak relationship instance cannot be created. Weak instance is already associated to another lead instance.BMC Atrium CMDB 2. Description You cannot assign the specified instance as a weak instance more than once. 50040 Error OBJSTR:Instance_CheckRelationshipEndpoint<endpoint number> The role <number> instance does not exist. The Class ID and Instance ID combination was not found.1 Table 7-3: CMDB Console filter error messages Error number 50038 Message type Error Error message OBJSTR:Instance_CheckSingleton02 Class $400124700$ is a Singleton class and can only have one instance. Description You cannot derive more than one instance from a singleton class. Solution Make sure you do not modify the reference values for the lead class. Class ID: $490008100$. Description Data type and attribute name are required fields for the subclass. Description The field ID you specified for the attribute is already in use in the class. Solution Make sure you specify a different field ID. 125016 Error OBJSTR:AttributeDef_CheckForDupsubclassesName_Msg Duplicate subclasses Name for attribute $400009700$. Solution Make sure you are using the join form to delete the instance.Developer’s Reference Guide Table 7-3: CMDB Console filter error messages Error number 50063 Message type Error Error message OBJSTR:Instance_CheckDeleteOp Instances cannot be deleted from this form. CMDB Console filter error messages 337 . Solution Make sure you specify values for these required fields. Solution Make sure you specify a different field name. 125016 Error OBJSTR:AttributeDef_CheckForDupsubclassesID_Msg Duplicate subclasses ID $400004800$ for attribute $400009700$. Description You cannot delete an instance from the instance base form. Description The field name you specified for the attribute is already in use in the class. 125017 Error OBJSTR:AttributeDef_CheckRequiredsubclasses Data Type and Attribute Name must be specified. 0. Description The class name and namespace combination that you specified for the class is not unique. 125020 Error OBJSTR:Class_ChkDuplicateClass02 There is already an existing class with class name $490001100$ in the namespace $400109900$. Solution Make sure that you specify a default value from the list of approved values. 338 Chapter 7—Error messages .h header file. Solution Make sure that the class name is unique within the specified namespace. 125019 Error OBJSTR:AttributeDef_CheckSelectionDefaltValue Invalid Default Value for selection subclasses.BMC Atrium CMDB 2. Solution Make sure that the ID you specify is not a system-reserved value. Solution Make sure you specify only one class type for the subclass. Please specify a different class name. 125021 Error OBJSTR:Class-ChkAbstractFinal This is an invalid combination of the Abstract and Final subclasses. For more information about reserved values. Description The default value you specified for the subclass is invalid. see the cmdb. Description You are attempting to derive a subclass as an abstract and final class.1 Table 7-3: CMDB Console filter error messages Error number 125018 Message type Error Error message OBJSTR:AttributeDef_CheckReservedsubclassesID Invalid subclasses ID for attribute $400009700$. Description The ID you specified for the subclass is a reserved value. Subclasses IDs below 100 are reserved for Core subclasses. 125027 Error OBJSTR:Instance_EnforceMany-1Relationship02 The relationship between $400126800$ and $400126900$ is defined as “Many to 1. 125026 Error OBJSTR:Instance_Enforce1-ManyRelationship02 The relationship between $400126800$ and $400126900$ is defined as “1 to Many. Solution Make sure that you do not specify more than one relationship between the two instances. and there is already a relationship instance between $400126800$ and $400126900$. Description You are attempting to create an attribute name that has a blank character.Developer’s Reference Guide Table 7-3: CMDB Console filter error messages Error number 125025 Message type Error Error message OBJSTR:Instance_Enforce1-1Relationship02 The relationship between $400126800$ and $400126900$ is defined as 1 to 1. CMDB Console filter error messages 339 . Description The relationship cardinality for the specified instances is violated. Solution Make sure that you do not specify more than one relationship between the two instances.” and there is already a relationship instance between $400126800$ and $400126900$.” and there is already a relationship instance between $400126900$ and $400126800$. Description The relationship cardinality for the specified instances is violated. Solution Make sure that you do not specify more than one relationship between the two instances. Solution Make sure you create attribute name fields with no space or wildcard characters. Description The relationship cardinality for the specified instances is violated. 125033 Error OBJSTR:AttributeDef_CheckSpaceInName02 Spaces are not allowed in the Attribute Name Field. Solution Make sure you create superclass fields with no space or wildcard characters.BMC Atrium CMDB 2.1 Table 7-3: CMDB Console filter error messages Error number 125034 Message type Error Error message OBJSTR:Class_CheckSpaceInName02 Spaces are not allowed in the Class Name Field. Description You are attempting to create a superclass field that has a blank character. 340 Chapter 7—Error messages .0. Description You are attempting to create a class name that has a blank character. Solution Make sure you create class name fields with no space or wildcard characters. 125035 Error OBJSTR:Class_CheckSpaceInSuperClass02 Spaces are not allowed in the Superclass Field. The following topics are provided: ! ! Events from AR System to CI Relationship Viewer (page 342) Events from CI Relationship Viewer to AR (page 344) CI Relationship Viewer events 341 .Appendix A CI Relationship Viewer events This appendix explains the CI Relationship Viewer events that you can use to transfer data to an AR System form. The CI Relationship Viewer provides the following types of events for data transfer with AR System forms. CORE|BMC_ComputerSystem BMC_DiskDrive|BMC_Dependency BMC_Component|Active|0|5 342 Appendix A—CI Relationship Viewer events .0 Workflow Objects. Event Type: CIRV_SET_CUSTOM_FILTER Event Data: <Namespace>|<Classes>|<Relationships>|<Statuses>| <Direction>|<NumLevels> The following code shows an example Event Data for the CIRV_SET_CUSTOM_FILTER event: BMC. The syntax for the command is: PERFORM-ACTION-SEND-EVENT <CIRV Flashboard subclasses ID> <Event Type> <Event Data> The possible Event Types and the Event Data required for them are explained in the following sections. Event Data: <filter name> An example of Event Data for the CIRV_SET_FILTER event is All. see BMC Remedy Action Request System 7.0. The CI Relationship Viewer displays relationship information based on this filter. When you specify All in Eventa Data. For more information about the Run Process workflow action. Sending events from the AR System forms enables you to programmatically manipulate the CI Relationship Viewer settings. CIRV_SET_FILTER Changes the filter for displaying the relationship information. CIRV_SET_CUSTOM_FILTER Sets the characteristics of the currently selected filter without saving it. This event enables you to customize the display when an existing filter does not meet your needs. the default filter will be used.1 Events from AR System to CI Relationship Viewer You send an event to the CI Relationship Viewer with the PERFORM-ACTIONSEND-EVENT Run Process command.BMC Atrium CMDB 2. it changes to Radial view. Example:BMC.Developer’s Reference Guide CIRV_SHOW Displays a new relationship map with the details specified in Event Data. If RadialLayout is passed. Event Type: CIRV_SET_AS_ROOT Event Data: none CIRV_SELECT_CI Selects the given CI in the relationship diagram. Event Type: CIRV_LAYOUT Event Data: <layout style> An example of Event Data for the CIRV_LAYOUT event is TreeLayout. This is useful to change the graph that is displayed in the CI Relationship Viewer when it is initialized. Event Type: CIRV_SHOW Event Data: <namespace>:<class name>#<dataset id>. Events from AR System to CI Relationship Viewer 343 . Event Type: CIRV_SELECT_CI Event Data: <instance id> An example of Event Data for the CIRV_SELECT_CI event is AS0050560C63F28d6HQQYFQGAAKQAA.AS0050560C63F28d6HQQ YFQGAAKQAA CIRV_SET_AS_ROOT Sets the currently selected CI node as the root. if any. will be reset.<instance id> The following code shows an example Event Data for the CIRV_SHOW event. CIRV_REFRESH Refreshes the graphical representation with updated data from the BMC Atrium CMDB.CORE:BMC_Computer_System#sim_dataset. Event Type: CIRV_REFRESH Event Data: none CIRV_LAYOUT Changes the layout of the graphical representation. The root CI remains the same as before. then the layout changes to Tree view. If the layout style TreeLayout is passed to the view. but the selection. CIRV_NOTIFY_AR This is a special type of event used by context menu items. Both Event Type and Event Data are set to menu item ID for this event. SELECTED_CI When you select a CI in the CI Relationship Viewer. which is the instance ID of the selected CI.BMC Atrium CMDB 2. The AR System form can use this data to perform any task. when that menu item is selected in the CI Relationship Viewer. Event Type: SELECTED_CI Event data: <instance id> An example of Event Data for the SELECTED_CI event is AS0050560C63F28d6HQQYFQGAAKQAA. When you specify CIRV_NOTIFY_AR as the value for the context menu item’s action key in the configuration file. an event is sent to the container form. Event Type: <menu item ID> Event Data: <menu item ID> 344 Appendix A—CI Relationship Viewer events .1 Events from CI Relationship Viewer to AR You can program the CI Relationship Viewer to send back data to the AR System form in the form of events. a CI event is sent to the AR System to notify the container form.0. you send the data in the $EVENTDATA$ variable and the event type in the $EVENTTYPE$ variable. The AR System form can capture these events to use its data. When you send an event to the AR System form. The following section lists the various events and the corresponding event data sent by the CI Relationship Viewer. see Chapter 6. then explains how the graph query works. These APIs include a graph query function that lets you “walk” the graph of CIs and relationships in the CMDB. and web services APIs that allow programmatic manipulation of class and instance data.” Finding related CIs using graph queries 345 . the concepts and strategies discussed here are the same for it as they are for the C API. “Web services API operations and data structures. For more information about the web services graph query operation. using two examples. To apply these concepts and strategies to a graph query with the Java API. Java. The following topics are provided: ! ! Representing graphs (page 346) The CMDBGraphQuery API function (page 347) Note: Though this section does not discuss specific elements of the Java API and web services API. starting with a specified CI and following its relationships to other CIs and continuing along the graph for as many levels as you want. This appendix provides you a context for these graphs. see the Java documentation installed in the sdk/doc/javadoc/cmdbapi/ subdirectory of your BMC Atrium CMDB installation directory.Appendix B Finding related CIs using graph queries The BMC Atrium CMDB provides C. because it provides a compact way to represent sparse graphs—those for which E is much less than V 2 . The adjacency-list representation is usually preferred. when the graph is dense: E is close to V 2 . 2 1 346 Appendix B—Finding related CIs using graph queries . v } . For each u ∈ V . The adjacency-list representation of a graph G = ( V. An adjacency-matrix representation might be preferred. v ) ∈ E . rather than ordered pairs. E ) consists of an array Adj of V lists.0. E ) . In an undirected graph G = ( V. Adj [ u ] consists of all the vertices adjacent to u in G . That is. The representation used by the CMDBGraphQuery input query graph is an adjacency list. the adjacency list Adj [ u ] contains pointers to all the vertices v such that there is an edge ( u. Figure B-1: Undirected graph and its equivalent adjacency list V stands for vertices. however. the edge set E consists of unordered pairs of vertices. and so every edge consists of exactly two distinct vertices. In an undirected graph. v ∈ V and u ≠ v . That is. self-loops are forbidden. Figure B-1 (b) is an adjacency-list representation in an arbitrary order of the undirected2 graph in Figure B-1 (a).BMC Atrium CMDB 2. one for each vertex in V . where u. E ) 1: as a collection of adjacency lists or as an adjacency matrix. an edge is a set { u.1 Representing graphs There are two standard ways to represent a graph G = ( V. E stands for edges. The vertices in each adjacency list are typically stored in an arbitrary order. Figure B-2 (b) is an adjacency-list representation of the directed graph in Figure B-2 (a). This section explains two example graph queries that operate against the CI and relationship data illustrated as a graph in Figure B-3 on page 348. To accommodate this range. each relationship instance is like an edge and each CI instance is like a vertex. CI instances are circular nodes and relationship instances are the lines connecting them. In the CMDB. In the graph.Developer’s Reference Guide Similarly. Figure B-2: Directed graph and its equivalent adjacency list The CMDBGraphQuery API function The graph query API function handles a wide range of queries from simple to complex. so our query graph is a directed graph. The CMDBGraphQuery API function 347 . In this graph. it uses an adjacency-list data structure to represent the input query graph. see “CMDBGraphQuery” on page 135. all relationships are directional. For a description of the CMDBGraphQuery function. 0.BMC Atrium CMDB 2.1 Figure B-3: Graph of data to use with example queries 348 Appendix B—Finding related CIs using graph queries . Graphically. In representation (a). Figure B-6 on page 351 shows the data structures of the queryGraph argument for Figure B-4 (b). the class A:A appears twice. Figure B-4: Graph of Query Example 1 Figure B-5 on page 350 shows the data structures of the queryGraph argument for Figure B-4 (a). you are retrieving all of the attributes on the relationship instances and the CI instances. one of the instances is assigned the arbitrary extensionId of two. an extensionId is needed. the query you want to walk is illustrated in Figure B-4. In this example.Developer’s Reference Guide Example 1 You want to start on a CI instance of class A:A with instance ID 1 and walk relationships of class A:rAA. Notice that for the same query. which is defined as a relationship with A:A instances on both ends. The CMDBGraphQuery API function 349 . There’s no qualification on the instances of A:rAA or A:A. For return data. To distinguish one instance of A:A from the other. so the value of the numLevels argument will be -1. You want to walk outward to the last level. the graph can be represented either as (a) or (b). BMC Atrium CMDB 2.1 Figure B-5: queryGraph data structures for Figure B-4 (a) 350 Appendix B—Finding related CIs using graph queries .0. Developer’s Reference Guide Figure B-6: queryGraph data structures for Figure B-4 (b) The path taken to walk this graph is shown by the bolded relationships in Figure B-7 on page 352. The bolded nodes are those returned in the objects list. The CMDBGraphQuery API function 351 . 1 Figure B-7: Path walked and nodes returned by Query Example 1 352 Appendix B—Finding related CIs using graph queries .0.BMC Atrium CMDB 2. one of the instances is assigned the arbitrary extensionId of two. the class A:A appears twice. and 7. As with Example 1. 4. Eight relationship instances of A:rAA with instance IDs 1. Figure B-8: Graph of Query Example 2 Figure B-9 on page 354 shows the data structures of the queryGraph argument for Figure B-8 (a). 8. 9. which is defined as a relationship with an A:A instance on the left and an A:B instance on the right. Example 2 You want to start on a CI instance of class A:A with instance ID 1 and walk relationships of class A:rAB. you are retrieving all of the attributes on the relationship instances and the CI instances. You want to walk outward to the last level. 3. In this example. and 7. 3. The CMDBGraphQuery API function 353 . so the value of the numLevels argument will be -1. Graphically. 4.Developer’s Reference Guide The expected data to be returned is: ! ! Seven CI instances of A:A with instance IDs 2. 2. In representation (a). To distinguish one instance of A:A from the other. 6. 5. 6. the query you want to walk is illustrated in Figure B-7. an extensionId is needed. the graph for this query can be represented either as (a) or (b). From A:B you want to walk relationship A:rBA which has class A:B on the left and class A:A on the right. 5. For return data. Figure B-10 on page 355 shows the data structures of the queryGraph argument for Figure B-8 (b). There’s no qualification on the instances of any of the CI or relationship classes. 0.BMC Atrium CMDB 2.1 Figure B-9: queryGraph data structures for Figure B-8 (a) 354 Appendix B—Finding related CIs using graph queries . The CMDBGraphQuery API function 355 .Developer’s Reference Guide Figure B-10: queryGraph data structures for Figure B-8 (b) The path taken to walk this graph is shown by the bolded relationships in Figure B-11 on page 356. The bolded nodes are those returned in the objects list. 0.BMC Atrium CMDB 2.1 Figure B-11: Path walked and nodes returned by Query Example 2 356 Appendix B—Finding related CIs using graph queries . Six relationships. 3. and 3. 3. and 2. Three are instances of A:rAB with instance IDs 1.Developer’s Reference Guide The expected data to be returned is: ! Six CIs. and 2. Three are instances of A:A with instance IDs 8. Three are instances of A:B with instance IDs 1. 5. and 9. ! The CMDBGraphQuery API function 357 . Three are instances of A:rBA with instance IDs 1. 2. BMC Atrium CMDB 2.1 358 Appendix B—Finding related CIs using graph queries .0. An audit is triggered when the value of one or more specified attributes changes or when the instance is created or deleted. account A property or characteristic of a class. attribute substitution An individual reconciliation task that can be grouped together in a defined sequence to form a reconciliation job. Copy Dataset activity. base class A class that has no superclass. attribute permission An entity or party whose data is represented in the BMC Atrium CMDB. Business Service Management (BSM) The concept of prioritizing IT efforts to supports the overall goals of the business.Glossary abstract class attribute A class that has attributes but of which no instances can be created. Rename Dataset activity. A method of data federation in context that uses placeholders to represent attributes from a linked class. An attribute equates to a column on a database table or a field on an AR System form. See also Comparison activity. Identification activity. assuming valid instance permissions. audit A logging of attribute values and other information for purposes of tracking the history of changes to instance data. Merge activity. Specifying instance permission by account enables the BMC Atrium CMDB to support multitenancy. Delete Dataset activity. An abstract class exists for the purpose of creating an organizational layer without a database join. Purge Dataset activity. See also data replication. only as part of a job. Execute Job activity. Glossary 359 . such as the IP address of a computer system. You cannot run an activity by itself. Launching the link triggers the respective attribute values to be substituted for the placeholders. and to whom specific levels of permission can be granted. activity Permission to view or change the value in the attribute for any instance. BMC Atrium CMDB 2.0.1 cardinality CI Relationship Viewer event The number of members a relationship class can have on each side. Cardinality can be one to one, one to many, many to one, or many to many. cascading delete A message sent to the CI Relationship Viewer from AR System workflow to change its settings. The CI Relationship Viewer can also send AR System events. CIM To automatically delete, or mark as deleted, the destination member of a relationship when the source member is deleted or marked. Categories, Types, and Items (CTI) See Common Information Model (CIM). class A method formerly used for categorizing assets in BMC Remedy Asset Management. Category, Type, and Item are each an attribute on the BMC_BaseElement class, so you can use CTIs in the BMC Atrium CMDB. categorization class Metadata in the BMC Atrium CMDB that defines a type of object, usually a configuration item (CI) or relationship. Either of these types of class can store data as a regular class, categorization class, abstract class, or abstract class with data replication. You can apply the final class and singleton class options to it as well. Class Manager A class that does not have its own AR System form, but stores its instance data in the form of its superclass, preventing the need for a database join. CDM A component of the BMC Atrium CMDB where you can view, create, modify, and delete the classes and attributes that make up the data model, as well as view a list of subclasses for each class. class permissions See Common Data Model (CDM). child See destination. CI Permission to view instances of a class in the BMC Atrium CMDB interface or access them with AR System workflow. CMDB See configuration item (CI). CI class See Configuration Management Database (CMDB). CMDB Console A class that defines a type of configuration item (CI), such as a computer system or software application. CI Relationship Viewer The main user interface of the BMC Atrium CMDB, accessible from both web and BMC Remedy User clients. CMDB Console User A component of the BMC Atrium CMDB that graphically displays the relationships between CIs. It can also be embedded in other AR System-based applications. An application role. Members can perform searches from the CMDB Console and view federation definitions. 360 Glossary Developer’s Reference Guide CMDB Console Admin cmdbdriver An application role. Members can perform searches from the CMDB Console, view, create, and modify federation definitions, and perform CMDB Console administrative tasks. CMDB Data Change A utility that executes BMC Atrium CMDB C API functions from a command line, prompting for parameters. Common Data Model (CDM) An application role. Members can view, create, and modify instances if they have row-level security. CMDB Data Change All An application role. Members can view, create, and modify instances independent of row-level security. CMDB Data View The object-oriented, hierarchical set of classes in the BMC Atrium CMDB used to represent types of CIs and relationships. The CDM is based on industry standards such as the Common Information Model (CIM) and Microsoft’s Windows Management Instrumentation. Common Information Model (CIM) An application role. Members can view instances if they have row-level security. CMDB Definitions Admin A definition of management information developed by the Distributed Management Task Force (DMTF) that facilitates the exchange of management information between systems. Comparison activity An application role. Members can view, create, modify, and delete classes. CMDB Definitions Viewer An application role. Members can view class definitions. CMDB Extended Data A Reconciliation Engine activity that compares identified instances between two datasets, either producing a report that shows the differences or executing workflow. configuration data Related data linked to or from the BMC Atrium CMDB. CMDB RE Definitions Admin Data about your IT environment, consisting of CIs and relationships. configuration item (CI) An application role. Members can view, create, modify, and delete reconciliation definitions and can start and cancel jobs. CMDB RE Manual Identification An application role. Members can identify instances manually. CMDB RE User A physical, logical, or conceptual entity that is part of your IT environment and has configurable attributes. Examples include computer systems, buildings, employees, software, and business services. One of the two types of classes in the BMC Atrium CMDB. See also relationship. Configuration Management Database (CMDB) An application role. Members can view reconciliation definitions and can start and cancel jobs. A database that stores information about your IT configuration, including both CIs and relationships. Glossary 361 BMC Atrium CMDB 2.0.1 consumer Definitive Software Library (DSL) An application that works with data in the BMC Atrium CMDB. It might view the data or modify it. See also provider. Copy Dataset activity A Reconciliation Engine activity that copies instances from one dataset to another. CTI A repository where approved software configurations are stored. Installed instances of the software can be checked against the DSL for compliance with licenses and policies. Delete Dataset activity See Categories, Types, and Items (CTI). data replication An option for abstract classes. With this option, the instances of all subclasses are replicated to a single form to allow you to search the abstract class as though it had data. Only the attributes inherited from the abstract class are replicated. dataset A Reconciliation Engine activity that deletes instances from one or more datasets without removing the dataset itself. See also cascading delete, hard delete, and soft delete. destination The CI class defined as Class 2 in a relationship class, or an instance of that CI class as a member of such a relationship. Also known as the child member or weak member. discovery A logical group of data in the BMC Atrium CMDB. A dataset can represent data from a particular source, a snapshot from a particular date, or other purpose. The dataset used by BMC Software products for reconciled production data is named BMC Asset. See also overlay dataset. Dataset Merge Precedence The act of scanning your environment for configuration data. discovery application An application that scans your environment for configuration data and can act as a provider to the BMC Atrium CMDB. Distributed Management Task Force (DMTF) A pairing of a dataset with a Precedence group. Each Merge activity references a collection of these, called a Dataset Merge Precedence set. defined dataset An organization appointed to facilitate the exchange of management information by promoting the initiation of industry standards and interoperability. DMTF One of a pair of dataset IDs that is specified when executing a job with dynamic dataset substitution. The job is executed with the working dataset in place of the defined dataset. See Distributed Management Task Force (DMTF). DSL See Definitive Software Library (DSL). 362 Glossary Developer’s Reference Guide Enterprise Integration Engine federated interface The BMC Remedy Enterprise Integration Engine is a product that enables you to transfer large amounts of data between third-party data sources and both the AR System and BMC Atrium CMDB. event An instance of the BMC_FederatedInterface class that specifies how to access a particular type of federated data. See also federated link. federated link A particular type of change to the instances of specified classes. You can publish an event so that any instance of it is written to the CMDB:Events form. You can receive notification each time an instance of the event occurs by polling the form. See also CI Relationship Viewer event. Exclusion rule The connection between a class or CI and a federated interface. federated product A product that holds federated data. It can be linked to more than one federated interface. federation A rule that specifies an attribute to be excluded from participation in a Comparison activity. Execute Job activity The act of linking CIs in the BMC Atrium CMDB to external data. Federation Manager A Reconciliation Engine activity that executes a job. extension A component of the BMC Atrium CMDB that you can use to manage federated data. From the Federation Manager, you can view, create, and modify federated products, federated interfaces, and federated links. filter A logical set of classes and attributes, usually in its own namespace, that is not part of the Common Data Model (CDM). extension loader A set of criteria for restricting the information displayed by the CI Relationship Viewer. This is different from an AR System filter. final class The cmdbExtLoader program, which is used for installing data model extensions and importing other BMC Atrium CMDB data and metadata. federated data A class that cannot have subclasses. foreign key substitution Data linked from CIs in the BMC Atrium CMDB but stored externally. Federated data might represent more attributes of the CIs or related information such as change requests on the CIs. A method of federation that assigns a key from the federated product to each linked CI. Foreign key substitution is useful when no attributes that also exist in the BMC Atrium CMDB are stored in the federated product. Glossary 363 BMC Atrium CMDB 2.0.1 group incident A set of a particular type of reconciliation definition that is referenced by an activity. See also Identification group, Precedence group, Qualification group, Workflow Execution group. GUID Defined by ITIL as any event that is not part of the standard operation of a service and which causes, or might cause, an interruption to, or a reduction in, the quality of that service. instance A globally unique identifier, automatically generated by the AR System server. GUIDs are used for instance IDs, reconciliation IDs, and other cases where a unique value is needed without human interaction. hard delete An actual incarnation of a particular class, represented as a record in the BMC Atrium CMDB. Both CIs and relationships are instances of their respective classes. instance ID The act of removing an instance from the BMC Atrium CMDB. Identification activity A GUID that the BMC Atrium CMDB applies to each instance to uniquely identify it. instance permissions A Reconciliation Engine activity that matches instances from two or more datasets and assigns them the same identity, meaning that they represent the same reallife object. Identification group The right to view or modify a specific instance. These permissions are called rowlevel security and write security, respectively. ITIL A set of Identification rules that collectively identify instances from a particular dataset against other datasets. Each dataset that participates in an Identification activity is paired with one Identification group. Identification rule The Information Technology Infrastructure Library (ITIL) is an internationally accepted set of best practices for management of IT services developed by the British government job A rule used when identifying instances between datasets. When two instances match the qualification for the rule, they are assigned the same reconciliation ID. identity A group of one or more reconciliation activities executed in sequence. You cannot run an activity by itself; only as part of a job. You can start a job manually, with a schedule, with an Execute Job activity, with workflow, or with an API program. Merge activity See reconciliation ID. A Reconciliation Engine activity that merges two or more datasets into a single complete and correct dataset based on precedence values that favor the strengths of each dataset. 364 Glossary Developer’s Reference Guide metadata production dataset Definitions that describe the data stored in the BMC Atrium CMDB. Metadata includes classes in the data model and special classes to define things such as datasets and federation objects. multitenancy The dataset that serves as the single source of reference for your organization and from which you make business decisions. It acts as the target dataset in most Merge activities. provider The separation of data and access so that a single BMC Atrium CMDB can contain the data of multiple parties, but each party can access only their own data. See also account and role. namespace An application, often a discovery application, that loads bulk data into the BMC Atrium CMDB. See also consumer. provisioning A logical set of classes and attributes in the data model, usually related to a specific consumer or provider. The Common Data Model (CDM) uses the BMC.CORE namespace. overlay dataset The process of providing access to resources, such as printers, telephones, and such, and to information, such as permissions, databases, and so on. publish To make an event available so that instances of it can be written to the CMDB:Events form. Purge Dataset activity A dataset that provides a layer in which to make changes that are pending approval. API queries to the dataset seamlessly return its modified instances along with unmodified instances from the underlying regular dataset. parent A Reconciliation Engine activity that removes instances that have been marked as deleted from one or more datasets. Qualification See source. Precedence group A Boolean statement that is evaluated to determine whether an instance should be included in an activity. Qualification group The definition of an overall precedence value for a dataset. It can optionally contain precedence values for specific classes and attributes within the dataset. precedence value A set of Qualifications that can be used in various types of activity. An instance that meets one or more Qualifications in the group is included in the activity. reconciliation A method of assigning weight to specific datasets, classes, and attributes in a Merge activity. Attribute precedence values override class precedence values, which override dataset precedence values. The process of managing data in multiple datasets using the Reconciliation Engine. The main activities of reconciliation are identifying, comparing, and merging datasets, though the Reconciliation Engine performs other activities as well. Glossary 365 BMC Atrium CMDB 2.0.1 reconciliation definition role An entity defined in the Reconciliation Manager such as a job, activity, or group. Reconciliation Engine A designation that grants permissions to more than one AR System group. row-level security The component of the BMC Atrium CMDB that reconciles data from different datasets. reconciliation ID The permission required to view a specific instance. See also write security. rule A GUID that the Reconciliation Engine assigns to instances in different datasets that represent the same real-life object. Reconciliation Manager The component of the BMC Atrium CMDB that you can use to manage reconciliation definitions. regular class One or more criteria that, when met, cause an action. The types of rules used in the BMC Atrium CMDB are Exclusion rule, Identification rule, and Workflow Execution rule. ruleset A group of rules. service level agreement A class that stores its instance data in its own AR System form. See also abstract class, categorization class. related information A contract between a service provider and a purchaser that defines the level of service. singleton class Information about a CI that does not qualify as attributes of the CI, and should therefore not be stored in a Configuration Management Database (CMDB). relationship An optional class characteristic that restricts the class to holding only one instance. snapshot A connection between two CIs such as a dependency or membership. It is an instance of a relationship class. See also configuration item (CI). relationship class A set of data that represents a configuration at a certain point in time, usually stored in its own dataset. There can be multiple snapshots of a given configuration. soft delete The act of marking an instance as deleted from the BMC Atrium CMDB by setting the MarkAsDeleted attribute to Yes. source A class that defines a type of relationship between CIs, such as a dependency or membership. relationship filter See filter. Rename Dataset activity The CI class defined as Class 1 in a relationship class, or an instance of that CI class as a member of such a relationship. Also known as the parent member or strong member. A reconciliation activity that renames a dataset without changing its ID, preserving references to the dataset from any reconciliation definitions. 366 Glossary Glossary 367 . and filters that perform actions against data. escalations. weak relationship An optional characteristic for relationship classes. weak reference One of a pair of dataset IDs that is specified when executing a job with dynamic dataset substitution. Each Comparison activity can optionally reference one Workflow Execution group. which is called its superclass. When a compared instance matches the qualification for the rule. Windows Management Instrumentation (WMI) The permission required along with rowlevel security to modify or delete a specific instance. workflow AR System objects such as active links. are derived. The class is not available until synchronization completes. The child member is considered the weak member of a weak relationship. Microsoft's application of the Web-Based Enterprise Management initiative for an industry standard for accessing management information.Developer’s Reference Guide subclass Workflow Execution group A class that is derived from another class. specified AR System workflow is executed against the instance or the instance against which it is compared. The subclass inherits all the attributes of its superclass and any superclasses above it in the hierarchy. WMI See Windows Management Instrumentation (WMI). superclass A set of Workflow Execution rules. called subclasses. working dataset The automatic process of creating AR System forms and workflow to represent a class that has just been created or modified. and can also participate in relationships defined for all superclasses. signifying that the members of a relationship form a composite object that can be reconciled as one. synchronization A rule used when comparing instances between datasets. The job is executed with the working dataset in place of the defined dataset. existing as part of the parent member. write security See weak relationship. Workflow Execution rule A class from which other classes. 1 368 Glossary .0.BMC Atrium CMDB 2. 244 storing attachment limits 282 character limits 282 currency limits 283 data limits 281. 96. 242 data structures 186 attributes (continued) deleting 103. 100. storing for graphs 268 adjacency lists. storing 208 API logging 88 AR System CI Relationship Viewer and 70 creating forms 142 storing related federation data 215. 241 setting 111.Index A ActivateFederatedInContext operation 252 activating federated instances 177. representing graphs as 346 adjacency matrixes. 286 date limits 284 definitions 186 enum limits 284 index information 185. 119. 294 transferring data from CI Relationship Viewer 344 to CI Relationship Viewer 342 architecture. representing graphs as 346 adjacent nodes. 276 information 200 information to retrieve 278 information to set 279 integer limits 285 lists of values 279 real data limits 285 retrieval information 186 sort information 195. 293 active link error messages 327 adjacency items. defining 191 AttachmentLimit structure 282 AttributeInfoIn structure 279 AttributeInfoList structure 278 AttributeLimit structure 281 AttributeLimitList structure 286 attributes C API data structures 186 creating 40. 245 expanding CI parameters 148 exporting definitions with cmdbdriver 64 installing extensions with cmdbExtLoader 61 managing 95 retrieving 104. 107. 264 sort information by type 264 sources for propagation 194 targets for propagation 194 values 192. 113. 279 validating CI 147 web services API data structures 278 Index 369 . 193. 240. CMDB API 16 AROS string. replaced in object names 33 ArrayOf_String structure 263 attachLimits structure 191 attachment limits. 216. 1 AttributeValue structure 279 AttributeValueList structure 279 audience for this guide 10 AuditInfo structure 296 audits data structures 218.0. 287 tools 49–89 utilities 49–89. 296 value lists 218. 295 functions 179 operations 256 retrieving CI instance logs 181 retrieving modified CI instances 179. 219.BMC Atrium CMDB 2. 256 storing class options 219. 155. 260 bulk entries beginning transactions 139 committing transactions 140 ending transactions 140 invoking API calls 139 rolling back transactions 140 transaction functions 139 370 Index . 295 AuditValueList structure 295 AuditValueListList structure 295 C C API data structures about 182 attribute about 186 attachLimits 191 charLimits 190 CMDBAttributeGetStruct 186 CMDBAttributeLimit 187 CMDBAttributeNameId 192 CMDBSortList 195 CMDBSortStruct 195 CMDBWeakPropagatedAttrs 194 CMDBWeakPropagatedAttrsList 194 currencyLimits 191 dateLimits 191 decimalLimits 190 enumLimits 191 integerLimits 190 realLimits 190 audit about 218 CMDBAuditInfoStruct 219 CMDBAuditValueList 218 CMDBAuditValueListList 219 class about 182 CMDBClassRelationship 183 CMDBClassTypeInfo 182 CMDBIndexList 184 CMDBIndexStruct 185 federation about 215 CMDBFederatedActivateInfo 216 CMDBFederatedARInfo 215 general purpose about 198 CMDBClassNameId 196 CMDBClassNameIdList 196 CMDBQualifierStruct 197 CMDBVersionInfo 198 CMDBVersionInfoList 198 B BLOBs. 286. retrieving instance 134 BMC Atrium CMDB accessing classes 87 cmdbdriver program 50 documents available for 10 error messages C API 298 Console active link 327 Console filter 334 exporting data 149 importing data 149 importing data with EIE 86 installing extensions 63 migrating data between servers 53 programming 38 programs header files 32 structure 38 storing version information 198. Developer’s Reference Guide graph query about 206 CMDBGetObjectList 206 CMDBGetObjectStruct 206 CMDBGetRelationList 207 CMDBGetRelationStruct 207 CMDBGraphAdjacentList 208 CMDBGraphAdjacentStruct 208 CMDBGraphList 209 CMDBGraphStruct 209 import and export about 199 CMDBExportItem 200 CMDBExportItemList 201 CMDBExportItemStruct 201 CMDBImportItem 202 CMDBImportItemList 203 CMDBImportItemStruct 204 CMDBItemTypeAttribute 200 CMDBItemTypeClass 199 CMDBXMLExportItemList 201 CMDBXMLImportItemList 203 instance about 196 CMDBAttributeValueList 192 CMDBAttributeValueListList 193 CMDBAttributeValueStruct 193 Reconciliation Engine about 212 CMDBREClassQualList 214 CMDBREClassQualStruct 213 CMDBREDatasetList 215 CMDBREDatasetPair 214 CMDBREJobRunInfo 213 CMDBREJobRunInfoList 212 user interface component about 210 CMDBUIComponentInfo 210 CMDBUIComponentResult 211 CMDBUIComponentResultList 212 C API functions about 95 audit about 179 CMDBGetCopyAuditData 179 C API functions (continued) audit (continued) CMDBGetLogAuditData 181 bulk entry transaction about 139 CMDBBeginBulkEntryTransaction 139 CMDBEndBulkEntryTransaction 140 data model management about 95 CMDBCreateAttribute 96 CMDBCreateClass 116 CMDBCreateMultipleAttribute 100 CMDBDeleteAttribute 103 CMDBDeleteClass 119 CMDBGetAttribute 104 CMDBGetClass 120 CMDBGetListClass 122 CMDBGetMultipleAttribute 107 CMDBSetAttribute 111 CMDBSetClass 123 CMDBSetMultipleAttribute 113 environment about 141 CMDBGetServerPort 143 CMDBInitialization 141 CMDBSetServerPort 144 CMDBSynchMetaData 142 CMDBSystemInit 142 CMDBTermination 145 federation about 176 CMDBActivateFederatedInContext 177 CMDBGetRelatedFederatedInContext 1 76 free about 157 FreeCMDBAttributeGetStruct 163 FreeCMDBAttributeLimit 159 FreeCMDBAttributeLimitList 160 FreeCMDBAttributeLimitStruct 159 FreeCMDBAttributeValueList 169 FreeCMDBAttributeValueListList 169 FreeCMDBClassNameIdList 158 FreeCMDBClassTypeInfo 166 Index 371 . 347 CMDBSetInstance 138 Reconciliation Engine about 172 CMDBCancelJobRun 175 CMDBGetJobRun 173 CMDBGetListJobRun 174 CMDBStartJobRun 172 user interface component about 146 CMDBExpandParametersForCI 148 CMDBGetCMDBUIComponents 146 CMDBRunQualificationForCI 147 C API functions (continued) utility about 155 CMDBCreateGuid 155 CMDBGetVersions 156 C API sessions initializing 141 terminating 145 C APIs about 17 compilers 29 components 17 data structures 182 driver source code 24 error messages 298 function calls 17 function definitions 94 functions 95 header files 24 installing package 24 library files 25 library links 30 calls C API function 17 data structure changes 35 debugging with data structure contents 89 debugging with log information 88 invoking bulk entry API 139 canceling reconciliation jobs 175. See instances CI Relationship Viewer about 70 AR System and 70 configuring 77 creating context menus 78 creating definitions 82 creating events 84 embedding in AR System forms 73 events CIRV_LAYOUT 343 CIRV_NOTIFY_AR 344 372 Index . defining 190 CharLimit structure 282 charLimits structure 190 CI instances.0.BMC Atrium CMDB 2.1 C API functions (continued) free (continued) FreeCMDBExportItemList 162 FreeCMDBExportItemStruct 161 FreeCMDBGetObjectList 168 FreeCMDBGetRelationList 167 FreeCMDBGraphAdjacentList 164 FreeCMDBGraphAdjacentStruct 164 FreeCMDBGraphList 166 FreeCMDBGraphStruct 165 FreeCMDBImportItemList 162 FreeCMDBIndexList 161 FreeCMDBQualifierStruct 167 FreeCMDBREJobRunInfoList 171 FreeCMDBSortList 170 FreeCMDBVersionInfoList 158 import and export about 149 CMDBExport 149 CMDBExportData 151 CMDBExportDef 150 CMDBImport 152 CMDBImportData 154 CMDBImportDef 153 instance management about 126 CMDBCreateInstance 126 CMDBDeleteInstance 127 CMDBGetInstance 129 CMDBGetInstanceBLOB 134 CMDBGetListInstance 130 CMDBGetMultipleInstances 132 CMDBGraphQuery 135. 251 CancelJobRun operation 251 character limits. 236 storing attribute index information 185 audit options 219 CI definitions 182 CI properties 275 CI relationship information 273 class names 192 display properties 277 display property structures 277 index information 184. 263 namespace names 192. 196. 263 qualification information 291 relationship definitions 182 relationship information 183 type information 182 web services API data structures 272 ClassInfoIn structure 272 ClassInfoOut structure 273 ClassNameId structure 263 ClassNameIdList structure 263 ClassProperties structure 275 ClassQualifier structure 291 ClassQualifierList structure 291 ClassRelationship structure 273 CMDB APIs about 16 architecture 16 Index 373 . 153 definitions with cmdbdriver 57 installing extensions with cmdbExtLoader 61 managing 95 relationship about 44 creating 44 retrieving 238 retrieving 120. 199. 75 opening 71. 75 transferring data with events from AR System 342 to AR System 344 CIRV_LAYOUT event 343 CIRV_NOTIFY_AR event 344 CIRV_REFRESH event 343 CIRV_SELECT_CI event 343 CIRV_SET_AS_ROOT event 343 CIRV_SET_CUSTOM_FILTER event 342 CIRV_SET_FILTER event 342 CIRV_SHOW event 343 class forms creating instances in 226 setting instances in 225 classes accessing BMC Atrium CMDB directly 87 C API data structures 182 configuration item about 38 creating 38 creating attributes 40 creating instances 42 creating attributes 40 with cmdbdriver program 50 with core attributes 116. 64 qualified 151 classes (continued) importing data 154 data with cmdbdriver 57 definitions 152. 240 exporting data with cmdbdriver 55 definitions 149. 122. 258 setting properties 123. 276 information to retrieve 273 information to set 272 names 196. 235 retrieving list of UI components 146. 237 data structures 182 deleting 119.Developer’s Reference Guide CI Relationship Viewer (continued) events (continued) CIRV_REFRESH 343 CIRV_SELECT_CI 343 CIRV_SET_AS_ROOT 343 CIRV_SET_CUSTOM_FILTER 342 CIRV_SET_FILTER 342 CIRV_SHOW 343 SELECTED_CI 344 filters 77 launching 71. 150 definitions with cmdbdriver 55. 0.BMC Atrium CMDB 2. See BMC Atrium CMDB CMDBActivateFederatedInContext function 177 CMDBAttributeGetStruct structure 186 CMDBAttributeLimit structure 187 CMDBAttributeNameId structure 192 CMDBAttributeValueList structure 192 CMDBAttributeValueListList structure 193 CMDBAttributeValueStruct structure 193 CMDBAuditInfoStruct structure 219 CMDBAuditValueList structure 218 CMDBAuditValueListList structure 219 CMDBBeginBulkEntryTransaction function 139 CMDBCancelJobRun function 175 CMDBClassNameId structure 196 CMDBClassNameIdList structure 196 CMDBClassRelationship structure 183 CMDBClassTypeInfo structure 182 CMDBCreateAttribute function 96 CMDBCreateClass function 116 CMDBCreateGuid function 155 CMDBCreateInstance function 126 CMDBCreateMultipleAttribute function 100 CMDBDeleteAttribute function 103 CMDBDeleteClass function 119 CMDBDeleteInstance function 127 cmdbdriver program about 50 exporting class data 55 class definitions 55 instance data 56 subclass definitions 55 importing class data 57 class definitions 57 instance data 58 starting 54 using from command line 50 using on UNIX 52 CMDBEndBulkEntryTransaction function 140 CMDBExpandParametersForCI function 148 CMDBExport function 149 CMDBExportData function 151 CMDBExportDef function 150 CMDBExportItem structure 200 CMDBExportItemList structure 201 CMDBExportItemStruct structure 201 cmdbExtLoader program about 61 file structure 62 starting 69 CMDBFederatedActivateInfo structure 216 CMDBFederatedARInfo structure 215 CMDBGetAttribute function 104 CMDBGetClass function 120 CMDBGetCMDBUIComponents function 146 CMDBGetCopyAuditData function 179 CMDBGetInstance function 129 CMDBGetInstanceBLOB function 134 CMDBGetJobRun function 173 CMDBGetListClass function 122 CMDBGetListInstance function 130 CMDBGetListJobRun function 174 CMDBGetLogAuditData function 181 CMDBGetMultipleAttribute function 107 CMDBGetMultipleInstances function 132 CMDBGetObjectList structure 206 CMDBGetObjectStruct structure 206 CMDBGetRelatedFederatedInContext function 176 374 Index . renamed 33 parameter changes 34 programming 20 programs. when to write 20 sample source code 32 terminology changes 21 web services APIs 18 CMDB Console active link errors 327 API programming and 20 filter errors 334 CMDB. deprecated 33 objects.1 CMDB APIs (continued) C APIs 17 call changes 35 data structure changes 35 function changes 34 Java APIs 19 logging option 88 migrating to 33 objects. 100. creating 78 CreateAttribute operation 242 CreateClass operation 237 CreateInstance operation 226 CreateRelationInstance operation 229 creating AR System forms 142 attributes 96. defining 191 CurrencyLimit structure 283 currencyLimits structure 191 Index 375 . cmdbdriver program 50 committing bulk entry transactions 140 compilers. 347 CMDBGraphStruct structure 209 CMDBImport function 152 CMDBImportData function 154 CMDBImportDef function 153 CMDBImportItem structure 202 CMDBImportItemList structure 203 CMDBImportItemStruct structure 204 CMDBIndexList structure 184 CMDBIndexStruct structure 185 CMDBInitialization function 141 CMDBItemTypeAttribute structure 200 CMDBItemTypeClass structure 199 CMDBQualifierStruct structure 197 CMDBREClassQualList structure 214 CMDBREClassQualStruct structure 213 CMDBREDatasetList structure 215 CMDBREDatasetPair structure 214 CMDBREJobRunInfo structure 213 CMDBREJobRunInfoList structure 212 CMDBRunQualificationForCI function 147 CMDBSetAttribute function 111 CMDBSetClass function 123 CMDBSetInstance function 138 CMDBSetMultipleAttribute function 113 CMDBSetServerPort function 144 CMDBSortList structure 195 CMDBSortStruct structure 195 CMDBStartJobRun functions 172 CMDBSynchMetaData function 142 CMDBSystemInit function 142 CMDBTermination function 145 CMDBUIComponentInfo structure 210 CMDBUIComponentResult structure 211 CMDBUIComponentResultList structure 212 CMDBVersionInfo structure 198 CMDBVersionInfoList structure 198 CMDBWeakPropagatedAttrs structure 194 CMDBWeakPropagatedAttrsList structure 194 CMDBXMLExportItemList structure 201 CMDBXMLImportItemList structure 203 commands. 237 classes with cmdbdriver program 50 forms 142 globally unique IDs 155 installation activity file 67 instances CI 42.xml file 64 relationship classes 44 currency limits. 242 CI classes 38 CI Relationship Viewer context menus 78 definitions 82 events 84 classes 116. 126 in class forms 226 relationship 126 with cmdbdriver program 50 instances relationship 229 package. C APIs 29 components C API 17 web services API 19 configuration items See also instances classes 38 creating instances 42 querying instances 47 viewing relationships 70 context menus.Developer’s Reference Guide CMDBGetRelationList structure 207 CMDBGetRelationStruct structure 207 CMDBGetServerPort function 143 CMDBGetVersions function 156 CMDBGraphAdjacentList structure 208 CMDBGraphAdjacentStruct structure 208 CMDBGraphList structure 209 CMDBGraphQuery function 135. BMC Atrium CMDB 2. storing for classes 277 documents. importing data with 86 Enterprise Integration Engine. 64 subclass with cmdbdriver 55 importing class 152. defining 190 decimalLimits structure 190 defining attachment limits 191 character limits 190 currency limits 191 date limits 191 decimal limits 190 enum limits 191 integer limits 190 query graph lists 209 real limits 190 definitions creating CI Relationship Viewer 82 exporting attribute with cmdbdriver 64 class 149. available for CMDB 10 E EIE. changed 35 printing contents 89 web services API about 262 attribute 278 audit 295 class 272 federation 293 graph 267 instance 262 job 290 user interface component 288 utility 286 DatasetPair structure 292 DatasetPairList structure 292 DateLimit structure 284 dateLimits structure 191 debugging calls with data structure contents 89 calls with log information 88 debugging APIs 88 decimal limits. defining 191 EnumLimit structure 284 enumLimits structure 191 environment functions 141 error messages C API 298 Console active link 327 376 Index .1 D data importing with EIE 86 limits. defining 191 data models management functions. 245 classes 119. 150 class with cmdbdriver 55. web services API 234 data structures C API about 182 attribute 186 audit 218 class 182 export 199 federation 215 general purpose 198 graph query 206 import 199 instance 196 Reconciliation Engine 212 user interface component 210 CMDB API. 228 deprecated CMDB API objects 33 display properties. See EIE enum limits. 240 instances 127. 153 class with cmdbdriver 57 storing attribute 186 CI 182 relationship 182 Delete Attribute operation 245 DeleteClass operation 240 DeleteInstance operation 228 deleting attributes 103.0. C API 95 managing 95 operations. 252 operations 252 retrieving instances 176. 252 exporting attribute definitions with cmdbdriver 64 C API data structures 199 C API functions 149 class data with cmdbdriver 55 data. 254 storing AR system data 215. 294 storing instance activation data 216. 150 definitions with cmdbdriver 55. 64 CMDB data 149 instance data with cmdbdriver 56 storing data for 199 subclass definitions with cmdbdriver 55 F features Java API 19 Web services API 18 FederatedActivateInfo structure 293 FederatedARInfo structure 294 federation data structures 215. 293 expanding instances 177. 252 functions 176 launching instances 177. qualified 151 definitions 149. 293 filters CI Relationship Viewer 77 error messages 334 forms.Developer’s Reference Guide error messages (continued) Console filter 334 events creating CI Relationship Viewer 84 transferring from AR System to CI Relationship Viewer 342 CI Relationship Viewer to AR System 344 ExecuteJobRun operation 247 expanding federated instances 177. changed 34 web services API 222 G general purpose data structures 198 GetAttributes operation 241 GetClass operation 235 GetCopyAuditData operation 256 GetInstances operation 223 GetJobRun operation 248 GetListJobRun operation 250 Index 377 . creating 142 free functions 157 FreeCMDBAttributeGetStruct function 163 FreeCMDBAttributeLimit function 159 FreeCMDBAttributeLimitList function 160 FreeCMDBAttributeLimitStruct function 159 FreeCMDBAttributeValueList function 169 FreeCMDBAttributeValueListList function 169 FreeCMDBClassNameIdList function 158 FreeCMDBClassTypeInfo function 166 FreeCMDBExportItemList function 162 FreeCMDBExportItemStruct function 161 FreeCMDBGetObjectList function 168 FreeCMDBGetRelationList function 167 FreeCMDBGraphAdjacentList function 164 FreeCMDBGraphAdjacentStruct function 164 FreeCMDBGraphList function 166 FreeCMDBGraphStruct function 165 FreeCMDBImportItemList function 162 FreeCMDBIndexList function 161 FreeCMDBQualifierStruct function 167 FreeCMDBREJobRunInfoList function 171 FreeCMDBSortList function 170 FreeCMDBVersionInfoList function 158 functions C API audit 179 bulk entry transaction 139 calls 17 data model management 95 environment 141 federation 176 free 157 import and export 149 instance management 126 Reconciliation Engine 172 user interface component 146 utility 155 CMDB API. 223 multiple 132 single 129 retrieving federated 254 searching for related 135 setting CI 138 setting in class forms 225 setting relationship 138 storing CI 206 data 196 list of values 264 relationship 207 378 Index . collections of 346 adjacency matrixes 346 query data structures C API 206 web services API 267 representing 346 storing adjacency items 268 H header files C API 24 CMDB program 32 I icon. creating globally unique 155 import and export functions 149 importing C API data structures 199 C API functions 149 class data 154 data with cmdbdriver 57 definitions 152. 231 retrieving audit logs 181 BLOBs 134 CI audit data 179. 153 definitions with cmdbdriver 57 CMDB data 149 data with EIE 86 instance data with cmdbdriver 58 storing data for 199 IndexInfo structure 276 IndexList structure 276 initializing networks 142 servers 142 installation activity file. New 10 IDs.0.1 GetRelatedFederatedInContext operation 254 GetUIComponents operation 258 GetVersions operation 260 Graph structure 267 GraphAdjacency structure 268 GraphAdjacencyList structure 268 GraphList structure 267 GraphQuery operation 231 graphs adjacency lists. 228 expanding CI parameters 148 expanding federated 177. 256 federated 176 list of 130. 252 exporting data with cmdbdriver 56 importing data with cmdbdriver 58 launching federated 177 management functions 126 managing 126 querying 47.BMC Atrium CMDB 2. creating 67 installing attribute extensions with cmdbExtLoader 61 C API package 24 class extensions with cmdbExtLoader 61 CMDB extensions 63 InstanceInfo structure 265 InstanceInfoList structure 264 instances See also configuration items and relationships C API management functions 126 C API structures 196 creating CI 126 configuration item 42 in class forms 226 relationship 126 with cmdbdriver program 50 data operations 222 data structures 262 deleting 127. web services API about 222 audit 256 data model 234 federation 252 reconciliation job 247 storing status 265 user interface component 258 utility 260 OS string.Developer’s Reference Guide instances (continued) storing (continued) values 265 structures 196 viewing relationships 70 web services API data structures 262 web services API operations 222 integer limits. C API 25 links. 263 storing namespace 192. representing graphs as 346 memory. C API 30 ListClasses operation 238 log files. replaced in object names 33 Index 379 . initializing 142 New icon 10 K known issues. C API 30 limits. 75 federated instances 177. BMC Atrium CMDB 88 logging option for API calls 88 login information. 196. 75 operations. releasing 157 menus. migrating CMDB data 61 L launching CI Relationship Viewer 71. defining 190 integerLimits attribute structure 190 IntLimit structure 285 LoginInfo structure 262 M managing attributes 95 classes 95 data models 95 instances 126 reconciliation jobs 172 matrixes. 196. CI Relationship Viewer 71. storing 262 O ObjectQueryInfo structure 270 ObjectQueryInfoList structure 269 objects deprecated from CMDB API 33 renamed in CMDB API 33 opening. See reconciliation jobs N names storing class 192. 263 networks. creating context 78 migrating CMDB data between servers 53 known issues 61 to BMC Atrium CMDB 2.0 API 33 J Java APIs about 19 environment components 31 features 19 program requirements 31 JobRunInfo structure 290 JobRunInfoList structure 291 jobs. defining attachment 191 character 190 currency 191 date 191 decimal 190 enum 191 integer 190 real 190 linking libraries. 252 library files. 0.xml file.c file 89 printing data structure contents 89 print. 241 audit data 179. 251 data structures 290 reconciliation jobs (continued) operations 247 retrieving data for running 173 list of running 174. 254 instance BLOBs 134 instances 129.c file 89 programs cmdbdriver program 50 cmdbExtLoader 61 propagating attribute values 194 PropInfo structure 277 PropInfoList structure 277 Q qualifications. 256 audit logs 181 classes 120. 215. 122. 260 S samples C API driver programs 24 CMDB API source code 32 searching for instances 135 SELECTED_CI event 344 380 Index . 292 qualifications 213. 250 relationship classes 238 server ports 143 UI component lists 146. 258 version of CMDB components 156. 132. 214 running 212. 250 logs for running 173 single running 248 starting 172. creating 229 relationships See also instances classes 44 querying instances 47 viewing 70 releasing memory 157 renamed CMDB API objects 33 retrieving attributes 104. 213 single 290 RelationQueryInfo structure 271 RelationQueryInfoList structure 270 relationship instances. creating 64 parameters changed CMDB API 34 expanding CI 148 ports retrieving 143 setting 144 print.BMC Atrium CMDB 2.1 P package. 130. 248. defining 190 RealLimit structure 285 realLimits attribute structure 190 Reconciliation Engine C API data structures 212 C API functions 172 managing jobs 172 reconciliation jobs canceling 175. 235 federated instances 176. 223 ports 143 reconciliation jobs 173. 247 storing all running 291 datasets 214. storing strings 197 querying C API graph query data structures 206 instances 47 instances related to CIs 231 storing CIs for 270 graph list definitions for 209 graph nodes for 209 graphs for 267 list of CIs for 269 list of relationships for 270 relationships for 271 R real data limits. 174. 107. 295 CI definitions 182 CI instances 206 CIs to query 269. 196. storing 265 StatusList structure 265 storing adjacent nodes 208 AR System federated data 215. 193. 113. 219. 293 graph adjacency items 268 graph nodes 209 import data 199 instance data 196 instance values 264. 279 audit options 219. 264 sort information by type 264 values 192. 203. 263 qualification information 291 type information 182 export data 199 federated instance activation data 216. 196. 276 information 200. 236 instances 138 instances in class forms 225 ports 144 server ports 144 sorting attributes 264 sorting attributes by type 264 SortOrder structure 264 SortOrderList structure 264 source code C API driver 24 sample CMDB API 32 SQL views 87 starting bulk entry transactions 139 cmdbdriver program 54 cmdbExtLoader program 69 reconciliation jobs 172. 296 audit value lists 218. 270 classes CI properties 275 CI relationship information 273 data 182 display properties 277 display property structures 277 index information 184. 278. 244 class properties 123. 294 attributes attachment limits 282 character limits 282 currency limits 283 data limits 281. 263 namespace names 192. 292 Index 381 . 199. 265 items to export 200.Developer’s Reference Guide server ports retrieving 143 setting 144 servers initializing 142 retrieving ports 143 setting ports 144 sessions initializing C API 141 terminating C API 145 SetAttribute operation 244 SetClass operation 236 SetInstance operation 225 setting attributes 111. 286 date limits 284 storing (continued) attributes (continued) definitions 186 enum limits 284 index information 185. 276 information to retrieve 273 information to set 272 names 192. 201 items to import 202. 204 login information 262 operation statuses 265 qualification strings 197 query graph list definitions 209 query graphs 267 reconciliation job datasets 214. 215. 279 integer limits 285 real data limits 285 retrieval information 186 sort information 195. 247 Status structure 265 status. See data structures subclasses. 291 relationships definitions 182 information 183 instances 207 to query 270. 289 UI components to retrieve 210. CMDB 49–89 U UI components. storing 262 382 Index . 271 running reconciliation jobs 212. 286. storing 263 structures. 289 to retrieve 210.0. 260 functions 155 operations 260 web services API data structures 286 V validating attributes. SQL 87 W web services API data structures attribute about 278 AttachmentLimit 282 AttributeInfoIn 279 AttributeInfoList 278 AttributeLimit 281 AttributeLimitList 286 AttributeValue 279 AttributeValueList 279 CharLimit 282 CurrencyLimit 283 DateLimit 284 EnumLimit 284 IntLimit 285 RealLimit 285 audit about 295 AuditInfo 296 AuditValueList 295 AuditValueListList 295 class about 272 ClassInfoIn 272 ClassInfoOut 273 ClassProperties 275 ClassRelationship 273 IndexInfo 276 T terminating C API sessions 145 terminology changes 21 CMDB and API 21 tools. 260 viewing configuration item relationships 70 instance relationships 70 views. 288 web services API data structures 288 user login information. 213 source attributes 194 strings 263 target attributes 194 UI component information 289 UI component query results 211. exporting definitions 55 utilities CMDB 49–89.BMC Atrium CMDB 2. CI 147 VersionInfo structure 287 VersionInfoList structure 286 versions. retrieving CMDB component 156. See user interface components UIComponentInfo structure 288 UIComponentResult structure 289 UIComponentResultList structure 289 user interface components data structures 210 functions 146 operations 258 retrieving list of 146. 258 storing information 289 query results 211. 212. 288 versions of CMDB components 198. 212. 287 XML items to export 201 XML items to import 203 strings.1 storing (continued) reconciliation job qualifications 213. 214 reconciliation jobs 290. 155. Developer’s Reference Guide web services API data structures (continued) class (continued) IndexList 276 PropInfo 277 PropInfoList 277 federation about 293 FederatedActivateInfo 293 FederatedARInfo 294 graph about 267 Graph 267 GraphAdjacency 268 GraphAdjacencyList 268 GraphList 267 ObjectQueryInfo 270 ObjectQueryInfoList 269 RelationQueryInfo 271 RelationQueryInfoList 270 instance about 262 ArrayOf_String 263 ClassNameId 263 ClassNameIdList 263 InstanceInfo 265 InstanceInfoList 264 LoginInfo 262 SortOrder 264 SortOrderList 264 Status 265 StatusList 265 job about 290 ClassQualifier 291 ClassQualifierList 291 DatasetPair 292 DatasetPairList 292 JobRunInfo 290 JobRunInfoList 291 user interface component about 288 UIComponentInfo 288 UIComponentResult 289 UIComponentResultList 289 web services API data structures (continued) utility about 286 VersionInfo 287 VersionInfoList 286 web services API operations audit about 256 GetCopyAuditData 256 data model about 234 CreateAttribute 242 CreateClass 237 Delete Attribute 245 DeleteClass 240 GetAttributes 241 GetClass 235 ListClasses 238 SetAttribute 244 SetClass 236 federation about 252 ActivateFederatedInContext 252 GetRelatedFederatedInContext 254 instance data about 222 CreateInstance 226 CreateRelationInstance 229 DeleteInstance 228 GetInstances 223 GraphQuery 231 SetInstance 225 reconciliation job about 247 CancelJobRun 251 ExecuteJobRun 247 GetJobRun 248 GetListJobRun 250 user interface component about 258 GetUIComponents 258 utility about 260 GetVersions 260 Index 383 . 0.1 web services APIs about 18 components 19 data structures 262 features 18 functions 222 operations 222 384 Index .BMC Atrium CMDB 2. . *24746* *24746* *24746* *24746* *64742* .