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

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

www.bmc.com

mailto:[email protected]

mailto:[email protected]

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

The New icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

BMC Atrium CMDB documentation . . . . . . . . . . . . . . . . . . 10

Section I Developing programs with the CMDB APIs . . . . . . . . . . 13

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


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 API reference . . . . . . . . . . . . . . . . . . . . . . . . 91

Chapter 5 C API functions and data structures . . . . . . . . . . . . . . . . 93

Related files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Deprecated objects . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Deprecated functions . . . . . . . . . . . . . . . . . . . . . . . . 94

Deprecated data structures . . . . . . . . . . . . . . . . . . . . . . 95

Contents � 5


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


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


8 � Contents

Preface

The BMC Atrium CMDB 2.0.1 Developer’s Reference Guide describes how to use the BMC Atrium Configuration Management Database (CMDB) C, Java, and web services APIs, and other BMC Atrium CMDB tools to program your BMC Atrium CMDB application and integrate it with other applications.

This guide is divided into the following sections:

! Developing programs with the BMC Atrium CMDB APIs—This section provides an introduction to the BMC Atrium CMDB API suite, provides instructions on how to program the BMC Atrium CMDB using Java methods, and provides procedures for using other BMC Atrium CMDB tools.

! API reference—This section provides descriptions of the C API functions, web services operations, and the data structures used by each function and operation. It also provides a list of error messages generated in the BMC Atrium CMDB along with their descriptions and solutions.

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.

Preface � 9


Audience

This guide is intended for application programmers. For more information about configuring the application, see the Installation and Configuration Guide.

The New icon

Documentation for the BMC Atrium CMDB Developer’s Reference Guide contains a New icon that identifies features or products that are new or enhanced with version 2.0.

BMC Atrium CMDB documentation

The following table lists the documentation available for the BMC Atrium CMDB.

Unless otherwise noted, online documentation in Adobe Acrobat (PDF) format is available in the sdk\doc subdirectory of the product installation directory, from the Support link from http://supportweb.remedy.com, or both. Other documentation is available in the sdk\doc subdirectory.

You can access product Help by clicking on Help links.

Title Document provides Audience Format

BMC Atrium CMDB 2.0 Concepts and Best Practices Guide

Information about CMDB concepts and best practices for planning your BMC Atrium CMDB implementation.

IT leaders and administrators

Print and PDF

BMC Atrium CMDB 2.0.1 Installation and Configuration Guide

Information about installing and configuring the BMC Atrium CMDB, including permissions, class definitions, reconciliation, and federation.

Administrators Print and PDF

BMC Atrium CMDB 2.0.1 User’s Guide

Information about using the BMC Atrium CMDB, including searching for and comparing CIs and relationships, relating CIs, viewing history, and launching federated data.

Users Print and PDF

10 � Preface

supportweb.remedy.com


BMC Atrium CMDB 2.0.1 Developer’s Reference Guide

Information about creating API programs, using C and web services API functions and data structures, and a list of error messages.

Administrators and programmers

Print and PDF

BMC Atrium CMDB 2.0.1 Master Index

Combined index of all guides. Everyone Print and PDF

BMC Atrium CMDB 2.0.1 Release Notes

Information about new features, open issues, and resolved issues.

Everyone Print and PDF

BMC Atrium CMDB 2.0 Common Data Model Diagram

Hierarchical diagram of all classes in the Common Data Model (CDM) including unique attributes and applicable relationships, and a relationship normalization table.

Administrators PDF

BMC Atrium CMDB 2.0.1 Common Data Model Help

Description and details of superclasses, subclasses, attributes, and relationships for each class.

Administrators HTML

BMC Atrium CMDB 2.0.1 Javadoc API Help

Information about Java classes, methods, and variables that integrate with the BMC Atrium CMDB.

Programmers HTML

BMC Atrium CMDB 2.0.1 Help Help for using and configuring the BMC Atrium CMDB.

Users and administrators

Product Help

BMC Remedy Action Request System 7.0: C API Reference

Information about AR System data structures, C API function calls, and OLE support.

Administrators and programmers

Print and PDF

BMC Remedy Action Request System 7.0: Configuring

Information about configuring AR System servers and clients, localizing, importing and exporting data, and archiving data.


BMC Remedy Action Request System 7.0: Form and Application Objects

Description of the components necessary to build applications in AR System, including applications, fields, forms, and views.

Developers Print and PDF

BMC Remedy Action Request System 7.0: Installing

Procedures for installing AR System. Administrators Print and PDF


BMC Atrium CMDB documentation � 11


BMC Remedy Action Request System 7.0: Installing and Administering BMC Remedy Mid Tier

Information about the mid tier, including mid tier installation and configuration, and web server configuration.


BMC Remedy Action Request System 7.0: Integrating with Plug-ins and Third-Party Products

Information about integrating AR System with external systems using plug-ins and other products, including LDAP, OLE, and ARDBC.

Administrators and developers

Print and PDF

BMC Remedy Action Request System 7.0: Workflow Objects

Information about the workflow. Developers Print and PDF


12 � Preface

Section

I
Developing programs with the CMDB APIs
This section explains how to use the BMC Atrium CMDB tools, such as the cmdbdriver program and the extension loader, and how to programmatically extend your application using the BMC Atrium CMDB APIs.

This section is organized into the following chapters:

! Chapter 1, “Introduction to the BMC Atrium CMDB APIs,” provides an overview of the BMC Atrium CMDB architecture and the BMC Atrium CMDB API suite, which includes a C API, Java API, and web services API. It also provides information about when to use API programming and when to use the BMC Atrium CMDB Console to perform the required tasks.

! Chapter 2, “Getting started,” provides information about the preparatory steps you must follow before you use the BMC Atrium CMDB API suite.

! Chapter 3, “Programming common BMC Atrium CMDB tasks,” provides Java code samples for a list of basic programming tasks that are performed most often in BMC Atrium CMDB API programs.

! Chapter 4, “BMC Atrium CMDB tools,” provides instructions for using the BMC Atrium CMDB tools, such as the cmdbdriver and extension loader.

Developing programs with the CMDB APIs � 13


14 � Section I—Developing programs with the CMDB APIs

Chapter

1
Introduction to the BMC Atrium CMDB APIs
This chapter provides an overview of the BMC Atrium CMDB application programming interface (API) suite.

The following topics are provided:

! BMC Atrium CMDB API overview (page 16)

! Using API programming compared with the CMDB Console (page 20)

Introduction to the BMC Atrium CMDB APIs � 15


BMC Atrium CMDB API overview

The BMC Atrium CMDB provides an API suite to programmatically work with class definitions, instance data, federation, reconciliation, audit and other functions. The BMC Atrium CMDB API suite is composed of the C, Java, and web services APIs.

The C and Java APIs provide similar data structures and functions to encapsulate information and functionality. You can use either C or Java API depending on your application platform.

The web services API provides a set of platform-independent operations that communicate with your applications to retrieve and send data.

Figure 1-1: BMC Atrium CMDB C and Java architecture

Note: The arrows indicate the directions in which each program or process can initiate an API function. Data can flow in any direction.

BMC BMC

ReconciliationEngine

Service ImpactManager

TopologyDiscovery

CMDB Console CI Relationship Viewer

AR SystemAPI

CMDB CAPI

CMDB JavaAPI

CMDB Web ServicesAPI

Database

CDM

BMC Atrium CMDB

Action Request System

WebClientRemedy

User

AR SystemApplications

RemedyUser

WebClient

Web Service Clients

.NetClient

AXISClient

BMC Remedy Mid Tier (CMDB API)

16 � Chapter 1—Introduction to the BMC Atrium CMDB APIs


As shown in Figure 1-1 on page 16, a BMC Atrium CMDB components, such as the CI Relationship Viewer and CMDB Console use the Java API to manipulate the CDM, whereas the external data consumers and data providers can communicate either using the web services API or Java API.

This guide describes the C and web services APIs. For more information about the Java API, see the Javadoc API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your BMC Atrium CMDB installation directory. To access the Javadoc API Help, open the index.html file.

C API

A BMC Atrium CMDB client can use the C API to create, modify, delete, and query the class definitions, instance data, federation, reconciliation, and other functions. The C API:

! Contains data structures that store both simple and complex information. A simple data structure serves as the primary building block for a complex data structure.

! Includes a set of Free functions that you can use to deallocate memory.

! Provides server-access information with every call in the control parameter of the function.

Features

You can use the C API functions to perform operations, such as:

! Create, modify, and delete classes and instances.

! Retrieve CI and relationship information.

! Create log files in a format that is different from the standard reports.

Components

The C API consists of a set of functions and data structures, most of which perform a specific database or data source operation. For example, you can use a function to retrieve information about a particular BMC Atrium CMDB class.

BMC Atrium CMDB API overview � 17


Most of these C API functions accept one or more BMC Atrium CMDB C data structures as parameters that qualify the action to perform, such as type of class to create, qualification for an instance to retrieve or delete, or class name to modify. For more information about the C API functions and data structures, see Chapter 5, “C API functions and data structures.”

The sdk/samples/driver subdirectory in your BMC Atrium CMDB installation directory contains the source code for the cmdbdriver program. This program provides a command-line interface for calling C API functions. The cmdbdriver program also includes print routines for every data structure in the API, making it a useful debugging tool.

For more information about the print routines, see “Debugging BMC Atrium CMDB API programs” on page 88.

Web services API

The BMC Atrium CMDB web services API provides a standard interface for interacting with the BMC Atrium CMDB. You can use the web services API to integrate BMC Atrium CMDB data with other applications, for example, BMC Topology Discovery and BMC Foundation Discovery, BMC® Remedy® Change Management, or any other third-party application.

The web services operations are wrapper classes on top of the BMC Atrium CMDB and AR System APIs.

Features

External web-based programs can communicate with the BMC Atrium CMDB using the web services operations. The BMC Atrium CMDB web services operations are developed to assist the following communities:

! BMC software partners—For developing integrated solutions with the BMC Atrium CMDB.

! Users—For developing programs that set up communication between the BMC Atrium CMDB and other products running in their environment.

Although the web services operations are based on the BMC Atrium CMDB C API functions, they do not correspond one-to-one with the C API.



Components

The web services API is a wrapper on top of the Java API. Therefore, each of the web services operations and data structures corresponds to a method in the Java API.

For more information about the web services operations that are currently available, see Chapter 6, “Web services API operations and data structures.”

Java API

The BMC Atrium CMDB Java API is a collection of Java classes and methods that provide the C API functionality in a Java development environment. Use the Java API if you write server-side web applications that you access through the Java Server page (JSP) or Java servlets web tier layer.

The Java API provides an object model of the BMC Atrium CMDB. You will find it easier to use the Java API if you are already familiar with the C API.

For more information about the Java API, see the Javadoc API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. To access the Javadoc API Help, open the index.html file.

Features

The following list describes the Java API features:

! The Java virtual machine (JVM) automatically deallocates objects that are created with the Java API.

! In the Java API, server access information is encapsulated in an ARServerUser object. For more information about ARServerUser object, see BMC Remedy Action Request System 7.0: Integrating with Plug-ins and Third-Party Products.

! The Java API has its own naming conventions.

BMC Atrium CMDB API overview � 19


Using API programming compared with the CMDB Console

The primary reason to write your own API program is to satisfy specific business needs that you cannot meet with the CMDB Console.

In addition, API programming gives you the flexibility to customize your application. However, API solutions are more complex to design, implement, and maintain.

The CMDB Console provides an easy-to-use graphical user interface for performing BMC Atrium CMDB tasks, such as creating classes, CIs, and relationships, and viewing instance history.

For more information about performing administrator tasks using the CMDB Console, such as using the Class Manager, Federation Manager, and, the Reconciliation Engine Manager, see the Installation and Configuration Guide.

For more information about performing user tasks using the CMDB Console, such as viewing CI history, Viewing CI and relationship classes, and comparing instances, see the User’s Guide.

When to use the API compared with the CMDB Console

Table 1-1 outlines the scenarios in which you should use APIs instead of the CMDB Console.

Table 1-1: API Programming scenarios

Requirement Use API Programming?

Use the CMDB Console?

You want to modify the CDM. Yes

You need to access multiple BMC Atrium CMDB components at the same time or integrate with programs or data outside the BMC Atrium CMDB.

Yes

You need to create, delete, or search for BMC Atrium CMDB classes.

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.

Table 1-2: CMDB Console and API terminology

You need to perform complex operations that involve multiple objects.

Yes

You need to create, delete, or search BMC Atrium CMDB relationships.

Yes

You need a two-way interface (or gateway) between the BMC Atrium CMDB and another application.

Yes

The values you want to specify for $PROCESS$ or the Run Process action exceed the size limitation of the command line.

Yes

Requirement Use API Programming?

Use the CMDB Console?

BMC Atrium CMDB term API term

search getList

create create

modify set

view/display get

Using API programming compared with the CMDB Console � 21

Chapter

2
Getting started
This chapter describes the preliminary steps you must follow before you use the BMC Atrium CMDB API suite.


! 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.0 API (page 33)

Getting started � 23


C API package contents

The C API package includes header files, library files, and source code for the cmdbdriver sample programs. When you install the BMC Atrium CMDB application, the C API is also installed with the package.

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 Contents

ar.h AR System API data type and structure definitions, size limits, and constant definitions.

cmdb.h BMC Atrium CMDB C API data type and structure definitions, size limits, and constant definitions.

arerrno.h Error code definitions.

arextern.h External declarations for the API functions, specified with and without prototypes for use with standard C, ANSI C, or C++ compilers.

arfree.h External declarations for the FreeAR functions. These functions recursively free all allocated memory associated with a particular data structure.

cmdbfree.h External declarations for the FreeCMDB functions. These functions recursively free all allocated memory associated with a particular data structure.

arstruct.h Core and reserved subclasses ID definitions, database separator characters, and labels for exporting structure definitions.

24 � Chapter 2—Getting started


Library files

You must have arcatalog_eng.dll in your path at runtime and make sure the lib directory contains the API library files listed in Table 2-2.

Table 2-2: C API library files

Platform Files

Windows mfc71.dll

msvcp71.dll

msvcr71.dll

Xalan-C_1_9.dll

XalanMessages_1_9.dll

arapi70.dll

arcatalog_eng.dll

ariapi70.dll

arjni70.dll

arrpc70.dll

arutiljni70.dll

arutl70.dll

arxmlutil70.dll

cmdb2asset.dll

cmdbapi20.dll

cmdbeng20.dll

cmdbjni20.dll

cmdbsvr20.dll

icudt32.dll

icuin32.dll

icuuc32.dll

libcmdbconsolefilterapi20.dll

rcmn70.dll

xerces-c_2_6.dll

xerces-depdom_2_6.dll

C API package contents � 25


Solaris libcmdbjni20.so

libcmdbeng20.so

libcmdbsvr20.so

libutil.a

libcmdbapi20.so

libcmdb2asset.so

libcmdbconsolefilterapi20.so

libar.a

libxerces-depdombmc.so.26

libari70.so

libicui18nbmc.so.32

libarutiljni70.so

libarjni70.so

libicudatabmc.so.32

libxalanMsgbmc.so.19

libjlicapi70.so

libxalan-cbmc.so.19

libarxmlutil.so

libicuucbmc.so.32

libxerces-cbmc.so.26

Platform Files



AIX libcmdbsvr20.a

libcmdbapi20.a

libcmdbeng20.a

libcmdbconsolefilterapi20.a

libutil.a

libcmdb2asset.a

libar.a

libcmdbjni20.a

libxerces-cbmc26.0.a

libarutiljni70.a

libarxmlutil.a

libxerces-depdombmc.a

libxerces-cbmc.a

libarjni70.a

libxerces-cbmc26.a

libxalan-cbmc19.a

libxerces-depdombmc26.a

libicui18nbmc32.a

libicuucbmc32.a

libxerces-depdombmc26.0.a

libxalanMsgbmc.a

libicudatabmc32.a

libjlicapi70.a

libari70.a

Platform Files



HP-UX libutil.a

libcmdbjni20.sl

libar.a

libcmdb2asset.sl

libcmdbeng20.sl

libcmdbapi20.sl

libcmdbsvr20.sl

libcmdbconsolefilterapi20.sl

libicui18nbmc.sl.32

libxalan-cbmc.sl.19

libari70.sl

libarjni70.sl

libjlicapi70.sl

libicudatabmc.sl.32

libxalanMsgbmc.sl.19

libarxmlutil.sl

libxerces-depdombmc.sl.26

libarutiljni70.sl

libxerces-cbmc.sl.26

libicuucbmc.sl.32

Platform Files



For Solaris and Linux: To load dynamic libraries, you need to include the -ldl link flag in the link command. For more information about linking and compiling your code, see the driver sample makefile in the sdk\samples\driver subdirectory of the BMC Atrium CMDB installation directory.

Compiler information

Before you write C API programs, make sure that the following software programs are installed or configured on your system:

! Microsoft Visual C++ version 7.0 or later

! Structure member alignment: 8 bytes (default)

Linux libcmdbeng20.so

libar.a

libcmdbjni20.so

libcmdbconsolefilterapi20.so

libcmdbapi20.so

libcmdbsvr20.so

libcmdb2asset.so

libutil.a

libicudatabmc.so.32

libxalanMsgbmc.so.19

libxalan-cbmc.so.19

libxerces-cbmc.so.26

libari70.so

libarutiljni70.so

libicui18nbmc.so.32

libjlicapi70.so

libxerces-depdombmc.so.26

libarxmlutil.so

libarjni70.so

libicuucbmc.so.32

Platform Files



! Set code generation to Multithreaded DLL, not DebugMultithreaded DLL. Where other included libraries cause conflicts, add /nodefaultlib:"MSVCRTD" to the project options to avoid using the Debug C runtime library. If your program references this library at runtime, memory management errors will occur when memory pointers are referenced by both the Debug and Release C runtime libraries.

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

Table 2-3: Link files

Java API package contents

The Java API package includes several header files and library files. When you install the BMC Atrium CMDB application, the Java API is also installed with the package.

Platform Links

Windows cmdbapi20.dllarapi70.dll

Solaris, Linux libcmdbapi20.solibarapi70.so

HP-UX libcmdbapi20.sl

libarapi70.sl

AIX libcmdbapi20.a

libarapi70.a



Requirements

To build and run a Java API program on either Windows or UNIX, you need the following environment components:

! All C API libraries and DLLs, as listed in the “C API package contents” on page 24.

! J2SE Software Development Kit (SDK), version 1.4.2 or higher.

! Windows dynamic link library (DLL) files or UNIX library files as listed in Table 2-4.

Library files

Table 2-4 lists the Java API library files that are installed with the BMC Atrium CMDB application.

Table 2-4: Java API library files

Platform Files

Windows arapi70.jar

arutil70.jar

arjni70.dll

cmdbapi20.jar

cmdbjni20.dll

Solaris libarapi70.jar

libarutil70.jar

libarjni70.jar

libcmdbapi20.so

libcmdbjni20.so

HP-UX libarapi70.jar

libarutil70.jar

libarjni70.jar

libcmdbapi20.sl

libcmdbjni20.sl

Java API package contents � 31


Header files

Table 2-5 lists the header files that are installed with the Java API.

Table 2-5: Header files for the CMDB programs

Sample source code

The sdk/samples/driver subdirectory in the BMC Atrium CMDB installation directory, includes the source code for a sample BMC Atrium CMDB client program. A compiled version of the cmdbdriver program is located in the sdk/bin directory.

When the BMC Atrium CMDB API package is installed, a series of directories is created in the installation directory. The src directory contains subdirectories with source code for the cmdbdriver sample program.

For more information about the cmdbdriver program, see Chapter 4, “Working with the cmdbdriver program.”

AIX libarapi70.jar

libarutil70.jar

libarjni70.jar

libcmdbapi20.a

libcmdbjni20.a

Linux libarapi70.jar

libarutil70.jar

libarjni70.jar

libcmdbapi20.so

libcmdbjni20.so

Platform Files

Header file name Description

com.remedy.arsys.api.*; AR System API functions

com.remedy.cmdb.api.*; CMDB API functions

java.util.*; Java utilities library



After compiling the source code or locating the prebuilt program supplied with the API, you can use cmdbdriver to:

! Identify function input parameters and load them with appropriate values.

! Examine the content and structure of function output parameters.

! Experiment with different parameter values.

Renamed C and Java API objects

In the BMC Atrium CMDB version 2.0 release, several CMDB API objects are renamed, replacing the strings “AROS” and “OS” with “CMDB.” These include:

! C API functions, data structures, and constants

! C API library and header files

! osdriver.exe

! Java API namespaces, packages, classes, methods, functions, variables, 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. The old names are deprecated, and will not work for the 2.0 release of the BMC Atrium CMDB.

Migrating to the BMC Atrium CMDB 2.0 API

This section describes the API changes for the 2.0 release. The BMC Atrium CMDB is not backward-compatible. Therefore, it does not support all functions from the client applications that use the 1.0, or 1.1 APIs.

If your programs use one of the earlier versions of the BMC Atrium CMDB APIs, you must rewrite your programs to use the 2.0 API functions, and link to the 2.0 libraries. The main program structure and processing, however, need not change.

Renamed C and Java API objects � 33


API parameter changes

Table 2-6 describes the changes in the 2.0 APIs that might affect your existing programs.

Table 2-6: API function changes

Parameter added

Functions affected Description

getMask CMDBGetInstanceCMDBGetListInstance CMDBGetMultipleInstance CMDBGetInstanceBLOB CMDBGraphQuery

The getMask parameter specifies that the function should manipulate the data in the overlay datasets.

auditInfo CMDBCreateClassCMDBSetClass CMDBGetClass

The auditInfo parameter specifies the audit information for the CI class.

datasetId CMDBCreateInstanceCMDBSetInstanceCMDBGetInstanceCMDBGetListInstance CMDBGetMultipleInstanceCMDBDeleteInstanceCMDBGetInstanceBLOB CMDBGetRelatedFederatedInContextCMDBActivateFederatedInContextCMDBGraphQueryCMDBGetCopyAuditDataCMDBGetLogAuditDataCMDBGetUIComponents

The datasetId parameter specifies the dataset that the function should use.



Data structure changes

This section describes the changes to the data structures that are used in the API functions.

Table 2-7: API data structure changes

Data structure added Functions affected Description

CMDBUIComponentResult (New)

CMDBGetCMDBUIComponents Holds component result information.

CMDBUIComponentInfo(New)

CMDBGetCMDBUIComponents Holds component information.

CMDBUIComponentResultList(New)

CMDBGetCMDBUIComponents Holds a list of component results.

CMDBVersionInfo(New)

CMDBGetVersions Holds the BMC Atrium CMDB version information.

CMDBVersionInfoList(New)

CMDBGetVersions Holds a list of BMC Atrium CMDB version information.

CMDBREJobRunInfoStruct(New)

CMDBGetJobRun Holds job run information.

CMDBREJobRunInfoList(New)

CMDBGetListJobRun Holds job run information.

CMDBFederatedARInfo(New)

CMDBActivateFederatedInContext Holds the federated AR System information.

CMDBFederatedActiveInfo(New)

CMDBActivateFederatedInContext Holds federation information.

CMDBAuditValueList(New)

CMDBGetCopyAuditData Holds audit values.

CMDBAuditValueListList(New)

CMDBGetCopyAuditData Holds a list of audit values in audit functions.

CMDBAuditInfoStruct(New)

CMDBCreateClass, CMDBSetClass, CMDBGetClass

Holds audit information.

CMDBREClassQualList(New)

CMDBStartJobRun Holds a list of qualifications for the class when running a job with qualification substitution.

Migrating to the BMC Atrium CMDB 2.0 API � 35


CMDBREDatasetPair CMDBStartJobRun Holds the substitute and original datasets when running a job with dataset substitution.

CMDBREDatasetList CMDBStartJobRun Holds a list of CMDBREDatasetPair structures when running a job with dataset substitution.

Table 2-7: API data structure changes

Data structure added Functions affected Description


Chapter

3
Programming common BMC Atrium CMDB tasks
This chapter describes how to use the BMC Atrium CMDB Java methods to perform common tasks. These tasks are explained using Java code samples.


! 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


Java program requirements

The procedural building blocks of a BMC Atrium CMDB program are functions or operations, which can invoke one another. For more information about specific Java method parameters, see the Javadoc API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. To access the Javadoc API Help, open the index.html file.

For your Java code to compile with the BMC Atrium CMDB classes, make sure you point the class path environment variable to the BMC Atrium CMDB jar files directory.

For the list of header files and link files required for your Java code, see “Java API package contents” on page 30.

Working with configuration item classes and instances

Configuration items (CIs) are the focal point of the BMC Atrium CMDB application. The attributes of a CI and other properties, such as data storage and inheritance, are encapsulated in a CI class definition. When you create a class, you define all the characteristics for it, such as the class name, namespace, superclass, and data storage method.

Creating a CI class

The following example creates two classes, PhoneSystem and Socket. Both classes are created in the ACME namespace. All class definitions that extend the CDM use a namespace other than BMC.CORE.

Example: Creating classes

//Create variables to hold the class name dataString acmeNamespace = "ACME";String phoneSystemClassName = "phoneSystem";String socketClassName = "Socket";

//Create the class name key for the Phone System class.CMDBClassNameKey phoneSystemClassNameKey = new CMDBClassNameKey(phoneSystemClassName, acmeNamespace);

String phoneSystemClassID = "ABCD-1234";

38 � Chapter 3—Programming common BMC Atrium CMDB tasks


//Create an instance of the CMDBClassCMDBClass phoneSystemClass = new CMDBClass(phoneSystemClassNameKey, phoneSystemClassID, null);

try { //Create the Phone System class in the BMC Atrium CMDB

phoneSystemClass.create(currentUser);} catch (ARException ex) { System.out.println(ex.toString());}

//create the socket classCMDBClassNameKey socketClassNameKey = new CMDBClassNameKey(socketClassName, acmeNamespace);

String socketClassID = "ACME_SocketClass";CMDBClass socketClass = new CMDBClass(socketClassNameKey, socketClassID, null);/* create the socket class in the BMC Atrium CMDBtry {

socketClass.create(currentUser);}catch (ARException ex) { System.out.println(ex.toString());}

In the example, the phoneSystemClassNameKey and socketClassNameKey class variables hold the class name and namespace definitions for the phoneSystem and Socket classes respectively. The classNameKey class variables are passed as parameters to the constructor of the CMDBClass class. A class ID is an identification string that uniquely identifies a particular class within the BMC Atrium CMDB.

In the try loop, the phoneSystemClass and socketClass classes are created in the BMC Atrium CMDB. The currentUser parameter is a pre-instantiated ARServerUser class that has valid user login credentials.

For more information about the parameters for the CMDBCreateClass function, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.

Working with configuration item classes and instances � 39


Creating attributes for your class

Every class you create will have attributes that hold different values for each instance of the class. The following example illustrates how to create attributes for the phoneSystemClass.

Example: Creating attributes

//Create attributes for the phoneSystem classString serialNumAttrName = "ACMESerialNumber";int serialNumFieldId = ACME_SERIAL_NUM_FIELD_ID;int serialNumEntryMode = CMDBAttribute.CMDB_ATTR_ENTRYMODE_REQUIRED;

//Define a data type and limit for the attributeCMDBAttributeLimit serialNumLimit = newCMDBCharLimit(30);

//Create a default value for the attribute Value serialNumDefaultValue = null;

//Create a Java instance of the attributeCMDBAttribute serialNumAttr = new CMDBAttribute(serialNumAttrName,

serialNumFieldId, serialNumEntryMode, serialNumLimit, null);

//Create another attribute for the phoneSystem classString costAttrName = "Cost";int costFieldId = ACME_COST_FIELD_ID;int costEntryMode = CMDBAttribute.CMDB_ATTR_ENTRYMODE_OPTIONAL;

//Create a variable of type CurrencyCMDBAttributeLimit costLimit = new CMDBCurrencyLimit;

//create a Java instance of the Cost attributeCMDBAttribute costAttr = new CMDBAttribute(costAttrName, costFieldId, costEntryMode, costLimit, null);

//Create a hash map to hold the attribute dataHashMap attributeHashMap = new HashMap();

//Add the two attributes to the hash mapattributeHashMap.put(serialNumAttruName, serialNumAttr);attributeHashMap.put(costAttrName, costAttr);

//Associate these attributes to the phoneSystemClassphoneSystemClass.setAttributes(attributeHashMap);

// Update the BMC Atrium CMDB with the new attributestry {

phoneSystemClass.update(currentUser);



}catch (ARException ex) { System.out.println(ex.toString());}

In the example, the serialNumAttrName, serialNumFieldId, and serialNumEntryMode variables are created to hold the attribute name, attribute field ID, and the entry mode for the attribute, respectively.

When you specify the Required entry mode for an attribute, you must provide a value for this attribute for every instance of the class. The field ID is a unique numeric identifier for an attribute.

The data type and limit for the attribute is defined using the serialNumLimit class variable, which is of type CMDBAttributeLimit class. In the example, the serialNumAttr attribute is defined as a character data type with a limit of 30 characters.

A default value of Null is specified for the attribute in the serialNumDefaultValue variable. This value is used if no value is provided for the ACMESerialNumber attribute when creating an instance.

After these values are defined for the variables, they are passed as parameters to the CMDBAttribute class constructor, which creates a Java instance of the attribute.

In the example, the Cost attribute is created to hold the cost information for the phoneSystemClass class. Similar to the ACMESerialNumber definition, the attribute name, field ID, entry mode, and attribute limit details are specified for the Cost attribute.

The entry mode for the Cost attribute is defined as Optional. The attribute data type is defined as Currency. After the attributes for a specific class are defined as CMDBAttribute variables, these attributes are added to a hash map. These hash maps can hold multiple attributes at a time.

The setAttributes method of the phoneSystemClass is used to set the attributes for the class. The hash map array, which holds the attribute definitions, is passed to this setAttributes method as a parameter. After the attributes are set in the class, the class information is updated in the BMC Atrium CMDB using the update method of the phoneSystemClass.

For more information about the setAttributes method of the CMDBClass Java class, data types, and data limits, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.



Creating a CI instance

After you create a class in the BMC Atrium CMDB, you can create an instance of this class. When you create an instance, you must specify all the required attributes for the class. The following code illustrates how to create an instance of the phoneSystemClass.

Example: Creating a CI instance

//Create variables to hold the serial number and cost details for the instanceString serialNum = "SN-1492-22919";Value cost = new Value("12.95",Constants.AR_DATA_TYPE_CURRENCY);CMDBAttributeValue serialNumAttrValue = new

CMDBAttributeValue(serialNumAttrName, serialNum);CMDBAttributeValue costAttrValue = new

CMDBAttributeValue(costAttrName, cost);

//Create a HashMap to hold the attribute valuesMap attributeHashMap = new HashMap();

attributeHashMap.put(serialNumAttrName, serialNumAttrValue);attributeHashMap.put(costAttrName, costAttrValue);

// create an instance of a phoneSystemClassCMDBInstance phoneInstance = new CMDBInstance(phoneSystemClassNameKey, attributeHashMap);

//create a variable to hold the dataset IDString acmeDatasetId = "ACME.DATASET";

try {

//Create the new instance within the BMC Atrium CMDBphoneInstance.create(currentUser, datasetId);

}catch (ARException ex) { System.out.println(ex.toString());}//Get the instance ID of the new instanceString phoneSystemInstId = phoneInstance.getId();

In the example, the serialNum and cost variables are created to hold the serial number and cost information for the instance. The serialNumAttrValue and costAttrValue class variables are created of type CMDBAttributeValue.



After the attribute name and other attribute information is created as explained in the previous section, the serialNumAttrName and serialNum variables are assigned to the serialNumAttrValue variable, which is of type CMDBAttributeValue. The costAttrValue class variable holds the costAttrName and cost details for the instance.

Using a hash map, the serial number and cost details are added to the phoneInstance instance, which is of type CMDBInstance. To create the new instance in Java, the phoneSystemClassNameKey, which was shown in “Creating a CI class” on page 38, and attributeHashMap variables are passed as parameters to the instance.

Before creating the phoneInstance instance in the BMC Atrium CMDB, a dataset variable is created to specify the dataset to which the instance belongs. In the example, the acmeDatasetId variable is created that holds the dataset details. Because an instance must reside in a dataset, you must specify a dataset ID for the instance.

In the try loop, the phoneInstance instance is created in the BMC Atrium CMDB. The currentUser and datasetId parameters are passed to the create method of the instance.

After the instance is created in the BMC Atrium CMDB, the instance ID of the new instance is retrieved using the getId method.

For more information about the parameters for the create method of the CMDBInstance Java class, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.



Working with relationship classes and instances

The BMC Atrium CMDB enables you to create relationships between CI classes. To relate two CI classes, you must create a relationship class that refers to the two CI classes.

After you create the relationship class, you create a relationship between the two CI instances using this relationship class.

Creating a relationship class

When defining the relationship class, you can specify several characteristics for the relationship, such as the cardinality of the relationship, for example one-to-many or one-to-one, or whether the class defines a weak relationship.

In the following example, a relationship class is created between the phoneSystemClass class and the socketClass class.

Example: Creating a relationship class

//Create a variable that holds the relationship class nameString relationshipClassName = "phoneSystemToSocketRelationship";

CMDBClassNameKey relationshipClassKey = new CMDBClassNameKey(relationshipClassName, acmeNamespace);

//Create a variable that holds the two classes that will be relatedCMDBClassNameKey[] relationshipClasses = {phoneSystemClassKey, socketClassKey};

//create a role name for each instance in the relationshipString[] roleNames = {"Source", "Destination"};

//create the relationship classCMDBRelationship phoneSystemToSocketRelClass = new CMDBRelationship(relationshipClassKey, null, roleNames, relationshipClasses);

//set the cardinality of the relationship phoneSystemToSocketRelClass.setCardinality( CMDBRelationship.CMDB_CLASS_RELATIONSHIP_CARDINALITY_1_MANY);

try { // create the relationship class in the BMC Atrium CMDB

phoneSystemToSocketRelClass.create(this.getARServerUser());}catch(ARException ex){ System.out.println(ex.toString());}



In the example, the relationshipClassName variable is created to hold the name of the relationship class. The relationshipClassKey variable, which is of type CMDBClassNameKey, is created to define the class name and namespace details for the relationship class.

The class name and namespace information for the two classes that will be related in the relationship class is specified in the relationshipClasses variable. The role names for the two classes are specified in the roleNames variable.

Each of the two classes in a relationship must have its role defined. You can define role names for Class 1 and Class 2, known respectively as the source and destination members of the relationship. The BMC Atrium CMDB prepends these role names to the attributes of a relationship class that pertain to its members. For example, on any CDM relationship class the attributes that hold the class IDs of its member CIs are named Source.ClassId and Destination.ClassId.

After the role name and class name key details are defined, the phoneSystemToSocketRelClass Java instance of the relationship class is created, which of type CMDBRelationship.

The setCardinality method of the CMDBRelationship class sets the cardinality. In this example, the cardinality for the relationship class is set to one-to-many. A one-to-many cardinality means that for each instance of the phoneSystem class, there can be many relationships to instances of the socket class.

In the try loop, the phoneSystemToSocketRelationship relationship class is then created in the BMC Atrium CMDB.

For more information about the parameters for the create method of the CMDBRelationship Java class, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.

Working with relationship classes and instances � 45


Creating a relationship between two CI instances

To create a relationship between two CI instances, you create a relationship instance. An instance of a relationship class defines a specific relationship between two particular instances of two CI classes. The following code illustrates how to create a relationship between two CIs.

In the following example, it is assumed that the newPhoneSystem and newSocket variables, representing existing CI instances, the phoneClassId and the socketClassId variables are already created.

Example: Relating two CIs

//retrieve the instance IDs for the newPhoneSystem and newSocket instancesString phoneInstId = newPhoneSystem.getId();String socketInstId = newSocket.getId();

//create the required attributes of the relationship instanceCMDBAttributeValue srcClassId = new CMDBAttributeValue("Source.ClassId", new Value(phoneClassId));CMDBAttributeValue destClassId = new CMDBAttributeValue("Destination.ClassId", new Value(socketClassId));CMDBAttributeValue srcInstId = new CMDBAttributeValue("Source.InstanceId", new Value(phoneInstId));CMDBAttributeValue destInstId = new CMDBAttributeValue("Destination.InstanceId", new Value(socketInstId));CMDBAttributeValue datasetId = new CMDBAttributeValue("DatasetId", new Value(acmeDatasetId));

Map attrHashMap = new HashMap();attrHashMap.put(srcClassId.getAttributeName(), srcClassId);attrHashMap.put(destClassId.getAttributeName(), destClassId);attrHashMap.put(srcInstId.getAttributeName(), srcInstId);attrHashMap.put(destInstId.getAttributeName(), destInstId);attrHashMap.put(datasetId.getAttributeName(), datasetId);

// create a Java instance of the relationship classCMDBInstance relInstance = new CMDBInstance(relationshipClassKey, attrHashMap);

try { //Create an instance of the class within the BMC Atrium CMDB relInstance.create(this.getARServerUser());}



In the example, the phoneInstId and socketInstId variables are created to hold the instance IDs of the newPhoneSystem and newSocket instances. The srcInstId and destInstId variables are created to hold the IDs of the source and destination classes, which are phoneInstId and socketInstId respectively.

The datasetId variable holds the dataset ID of the ACME dataset. These source, destination, and dataset ID variables are written to the attrHashMap array. The Java instance of the relationship class is then created using the constructor of the CMDBInstance class.

In the try loop, the relationship instance is created in the BMC Atrium CMDB. The getARServerUser method of the relInstance instance retrieves the user ID that is currently used to log in to the AR System server. The user ID parameter is required to create the instance in the BMC Atrium CMDB.

For more information about the parameters for the create method of the CMDBInstance Java class, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.

Retrieving instance details

You can query CI and relationship instances that exist in the BMC Atrium CMDB. The following code illustrates how to query instances of the phoneSystemClass class.

Example: Querying an instance

//Set specific attributes to returnString[] attributesToGet = {"InstanceId", "ReconciliationIdentity", "DatasetId"};

//Specify values for the query to retrieve all instances where DatasetId//is ACME.DATASETString query = "'DatasetId' = \"ACME.DATASET\"";

try {CMDBInstance[] instanceList = CMDBInstance.findObjects( this.getARServerUser(), phoneSystemClassKey, query, attributesToGet, null, //do not sort CMDB_START_WITH_FIRST_INSTANCE,

Working with relationship classes and instances � 47


CMDB_NO_MAX_LIST_RETRIEVE, Null);}catch(ARException ex){ System.out.println(ex.toString());}

In the example, the attributes to retrieve in the query are specified in the attributesToGet array of type String. The query in this example retrieves the InstanceID, ReconciliationIdentity, and DatasetID attributes from all instances. If no attributes are specified to return in the query, all attributes of the instances will be returned by default.

The query variable specifies a qualification that will retrieve all instances where the dataset ID is ACME.DATASET. In the try loop, the findObjects method of the CMDBInstance Java class is used to retrieve instances. The retrieved instances are placed in the instanceList array, which is of type CMDBInstance.

For more information about the parameters for the findObjects method of the CMDBInstance Java class, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.


Chapter

4
BMC Atrium CMDB tools
This chapter describes how to use the various BMC Atrium CMDB tools.


! 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


Working with the cmdbdriver program

The cmdbdriver program, which prompts you one at a time for parameters to each command you type, enables you to execute various BMC Atrium CMDB API functions from a command line, such as class, instance, and attribute data manipulation. Figure 4-1 on page 51 displays the list of tasks that you can perform with the cmdbdriver program.

The parameters that are required for cmdbdriver commands are the same as the parameters that are required for the equivalent C API functions. For more information about API functions and their parameters, see Chapter 5, “C API functions and data structures.”

From the command line

Once you compile the source code or locate the prebuilt program supplied with the API, you are ready to use the cmdbdriver program. When you execute the program, the system displays the list of cmdbdriver commands.

You must provide the necessary login information and perform initialization operations for connecting to the BMC Atrium CMDB. You can then use the cmdbdriver commands to call any number of API functions. When you are working with the specific commands, see Chapter 5, “C API functions and data structures,” to enter the appropriate values for the function parameters. If you are working with specific entries, use leading zeros to see the entry ID of those entries.

� To use the cmdbdriver program (Windows and UNIX)

1 Start the cmdbdriver program using the following steps based on your platform:

! Windows

! Navigate to C:\Program Files\AR System Applications\<server_name>\Remedy CMDB\api\bin.

! Double-click cmdbdriver.exe.

! UNIX

! Navigate to /usr/arsystem/<server_name>/cmdb/api/bin.

! Type the command cmdbdriver.

50 � Chapter 4—BMC Atrium CMDB tools


Figure 4-1: Initial screen of cmdbdriver

2 Initialize an API session with the init command.

3 Specify the login parameters with the log command.

You are prompted to specify several parameters one at a time. You must enter the following parameters:

! Type a valid user name and password.

! Type the name of your server.

You can skip the other parameters. After you specify the login parameters, the command prompt appears.

4 Type the abbreviation of the function and provide the appropriate input parameter values.

For example, for importing class definitions, type impdf at the prompt. Use the help command (h or ?) to display the cmdbdriver commands. When you are finished using the cmdbdriver, type e or q to exit the program.

Working with the cmdbdriver program � 51


Using a script

You can also use a script file that contains the cmdbdriver commands and execute it at the cmdbdriver prompt. You can create this script file using any text editor, such as Notepad or Wordpad.

Example: cmdbdriver script file

imp1BMC.COREBMC_BASEELEMENT

This example uses a script to import the BMC_BASEELEMENTclass from the BMC.CORE namespace. To accept a default value for a parameter in the cmdbdriver script, insert a blank line. The last line of the example accepts the default value for the Metadata, Instance data <1-2> parameter. The default for this parameter is set to 1 (metadata).

You can use the rec and srec commands of the cmdbdriver program to record cmdbdriver commands. The rec command starts recording the commands you use at the prompt and srec stops recording these commands.

When you type the rec command, you are prompted for the name of the file in which to store these commands. After you record the commands in a file, you can execute it at the cmdbdriver program using the execute command.

Using cmdbdriver on UNIX

The cmdbdriver program uses shared code libraries in the bin subdirectory of the BMC Atrium CMDB installation directory. These libraries are not available to it by default in UNIX environments.

To make these libraries available to cmdbdriver, add the bin subdirectory to your LD_LIBRARY_PATH environment variable either permanently or by using the export or setenv command. By default, the directory is located in /usr/arsystem/<server_name>/cmdb/bin.



Migrating data between BMC Atrium CMDB servers

This section explains how to migrate data from one BMC Atrium CMDB server to another using the cmdbdriver program. The most common reason to migrate data from one BMC Atrium CMDB to another is to move your BMC Atrium CMDB into production. The following procedure explains the steps to migrate from a BMC Atrium CMDB development server to a BMC Atrium CMDB production server. Before migrating your BMC Atrium CMDB data, make sure both your BMC Atrium CMDB servers are configured and running.

Note: If you have other BMC Software applications installed on your development server that access the BMC Atrium CMDB, such as Remedy Asset Management, these applications might have extended the BMC Atrium CMDB by adding classes, attributes, forms, or workflow.

Migrating the BMC Atrium CMDB in such cases requires additional steps beyond migrating a base installation of the BMC Atrium CMDB. Those steps are not covered in this section. See the documentation and white papers for your applications to find the appropriate migration instructions.

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

Step 2 Export instance data with cmdbdriver (see page 56).

Step 3 Import class data with cmdbdriver (see page 57).

Step 4 Import instance data with cmdbdriver (see page 58).

Step 5 Export reconciliation information with BMC® Remedy® User (see page 59).

Step 6 Import reconciliation information with BMC® Remedy® Import (see page 60).

For information about known issues regarding the procedure explained in this section, see “Known issues” on page 61.

You can use cmdbdriver scripts to perform some of these steps.

Migrating data between BMC Atrium CMDB servers � 53


Logging in to the cmdbdriver program

The cmdbdriver program is the command-line interface to the BMC Atrium CMDB C API. Prior to BMC Atrium CMDB 1.1 Patch 002, the driver program was named osdriver.The following steps describe the procedure to start the cmdbdriver program.

� To log in to the cmdbdriver program

1 Start the cmdbdriver program using the following steps based on your platform:

! Windows

! Navigate to C:\Program Files\AR System Applications\<server_name>\Remedy CMDB\api\bin.

! Double-click cmdbdriver.exe.

! UNIX

! Navigate to /usr/arsystem/<server_name>/cmdb/api/bin.

! Type the command cmdbdriver.

2 Type the command init to initialize the driver.

3 Type the command log to log into your development server.

You are prompted to specify several parameters one at a time. You must enter the following parameters:

! Type a valid user name and password.

! Type the name of your server.

You can leave the other parameters blank. After you specify the login parameters the command prompt appears.

4 Type the abbreviation of the function and provide the appropriate input parameter values.

For example, for importing class definitions, type impdf at the prompt. Use the help command (h or ?) to display the cmdbdriver commands. When you are finished using the cmdbdriver, type e or q to exit the program.



Step 1—Exporting class data with cmdbdriver

If you have added or changed any CI or relationship classes on your development server, you need to export them. This class data is also called metadata, because it describes the instance data in the BMC Atrium CMDB. You need to export only those classes that you have added or changed, and their subclasses.

When you export a superclass that you modified, all the subclasses for the superclass will also be exported with it. If you have not made any additions or changes, you can skip Step 1 and import the class definitions using the steps explained in “Step 3—Import class definitions with cmdbdriver” on page 57.

� To export definitions for a class and its subclasses

1 Log in to your development server.

2 Start the cmdbdriver program and specify your user credentials.

For more information about logging in to the cmdbdriver program, see “Logging in to the cmdbdriver program” on page 54.

3 Type the xexpdf command to export all class definitions from the BMC Atrium CMDB.

4 Specify the file name in which to store the exported definitions.

Make sure you specify the exact path for the file name, for example, c:\ExportedClassDefinitions. If you specify a file name that already exists, the contents of the file will be overwritten.

5 At the Export Classes prompt, type 1 to export all classes and their subclasses.

The definitions for the classes and their subclasses are saved to the specified directory as XML files. To export definitions for a specific class, type 2 at the Export Classes prompt. When you type option 2, you will be prompted for additional parameters.



Step 2—Export instance data with cmdbdriver

You must export both CI and relationship configuration data from your development server.

� To export instance data for a class

1 Log in to your development server.


For more information about starting the cmdbdriver program, see “Logging in to the cmdbdriver program” on page 54.

3 Type the xexpdt command to export instance data from the BMC Atrium CMDB.

4 Type the file name in which to store the exported instance data.

Make sure you specify the exact path for the file name, for example, c:\ExportedInstanceData. If you specify a file name that already exists, the contents of the file will be overwritten.

5 At the Export Instances from prompt, type 1 to export instance data for all classes and their subclasses.

To export instance data for a specific class, type 2 at the Export Instances from prompt. When you type option 2, you will be prompted for additional parameters.

6 At the Dataset ID prompt, type the dataset ID from which to export the instance data.

Tip: If you export all your instance data to the same directory, it can later be imported in one step.

The instance data for the classes is saved to the specified directory as an XML file.



Step 3—Import class definitions with cmdbdriver

You must import the class definitions that you exported from your development server in Step 1 and 2 of this procedure, to your production server. Use the steps explained in this section to migrate the class definitions to the production server.

� To import class definitions

1 Log in to your production server.



3 Type the impdf command to import class definitions into the BMC Atrium CMDB.

4 Specify the directory path where the import data is located, such as c:\ExportedClassDefinitions.

5 To import all class definitions contained in the source folder (recommended), accept the default of 0 and skip to step 8. To import definitions for a specific class, type 1 for the Number of Import Items.

Note: When you enter a number other than 0, you cannot automatically import the subclasses of a specified class. Each subclass must be specified as a separate import item, either by increasing the number you specify here or by running the impdf command multiple times.

6 To import a class from the source folder, accept the default value of 1.

To import attributes for the class, run the impdf command again and type 2 at this prompt.

7 At the Class Name prompt, type the namespace and class name for the class, for example, BMC.CORE. and BMC_BaseElement respectively.

8 Accept the default value of 1 to import Metadata.



9 Type any of the following import options:

! 1 (Create)—Create the specified class in the BMC Atrium CMDB. If this class already exists, the program generates an error.

! 2 (Overwrite)—Overwrite the existing class in the BMC Atrium CMDB.

The definition is imported and each class name is displayed.

Step 4—Import instance data with cmdbdriver

You must import the CI and relationship instances from the export files, which contain the class and instance data you exported in Step 1 and 2 of this procedure, to your production server.

� To import instances of a class or classes

1 Log in to your production server.



3 Type the impdt command to import instance data into the BMC Atrium CMDB.

4 Type any of the following import options to specify the action to take when an instance to be imported has the same InstanceId as an existing instance in the BMC Atrium CMDB:

! 1 (Error)—Write an error message and do not import the instance.

! 2 (Replace with new ID)—Overwrite the existing data for a given instance.

! 3 (Merge)— Merge the new instance and the existing instance.

! 4 (New Id for all)—Create a new ID for every duplicate instance.

5 Type the directory path where the import data is located, for example, c:\ExportedInstanceData.

The data is imported into the BMC Atrium CMDB.



Step 5—Export reconciliation definitions

In version 2.0, you can export reconciliation definitions from one server and import them onto another server instead of manually recreating all your definitions. The definitions can be stored in either AR Export (.arx), report (.rep), comma-separated values (.csv), or XML (.xml) format. For more information about AR Export files, see the BMC Remedy Action Request System 7.0: Form and Application Objects guide.

You can export all your reconciliation definitions, or select one or more definitions of a certain type. Any definitions used by those you select are also exported. For example, if you select a job, the export will include that job plus all the activities in it, plus all the rulesets in those activities, and so on.

You can export reconciliation definitions either using BMC Remedy User or a browser. When exporting definitions from a browser, several file dialogs might appear, depending on the definitions you export. Each dialog requires you to enter an export filename for a particular definition.

Note: Due to the browser limitation, the recommended method is to use BMC Remedy User for exporting reconciliation definitions.

� To export reconciliation definitions

1 Using BMC Remedy User, open the CMDB Console.

2 Click the Reconciliation Manager tab and choose the Export Definitions link from the left navigation pane.

3 Select an Export Type:

! Everything—All definitions.

! Job—Selected jobs and the definitions used by them.

! Group—Selected Identification groups, Qualification groups, Precedence groups, and Workflow Execution groups and the definitions used by them.

! Dataset—All datasets.

! DatasetMergePrecedenceSet—Selected Dataset Merge Precedence sets and the definitions used by them.



4 If you selected either Job, Group, or DatasetMergePrecedenceSet, select the definitions to be exported.

If your Export Type is Group, you have the option of also exporting the activities that reference your selected definitions. To do this, click the Options tab and select Include Associations.

5 Type the fully qualified File Name to which the definitions should be exported.

You can use any of the approved extensions for the file name. For more information about the extensions for the export definitions file, see “Step 5—Export reconciliation definitions” on page 59.

If you include no path or a relative path, the file is placed in or under the BMC Remedy User application folder.

6 Click Export.

The definitions are exported.

Step 6—Import reconciliation definitions

You import reconciliation definitions by using the BMC Remedy Import command-line interface (CLI).

Note: Before using the CLI on UNIX for the first time, you must add an entry to your library path. The CLI also has several other options not described in the following procedure, some of which might be necessary depending on your AR System server environment. For more information about these topics, see the BMC Remedy Action Request System 7.0: Integrating with Plug-ins and Third-Party Products guide.

� To import reconciliation definitions

1 Open a command prompt.

2 If using Windows, change to the directory where BMC Remedy Import and other AR System clients are installed.

The default directory is c:\Program Files\AR System.



3 Enter the command:

arimportcmd -x <server_name> -u <user_name> -p <password> -o <import_file> -l <log_file>

For <import_file>, specify the full path to the file containing the exported definitions from the procedure “To export reconciliation definitions” on page 59. Specifying a log file is optional, but recommended in case there are any errors with the import, such as existing data with duplicate entry IDs.

Known issues

These issues can occur when performing the migration procedures in this section.

! When exporting or importing instances for a categorization class, data from its superclass is also exported or imported. This is because a categorization class stores its instance data on the same AR System form as its superclass.

! When you attempt to export instance data from an abstract class, cmdbdriver crashes. There is no reason to do this, since abstract classes cannot have any instances.

! When importing the weak member in a weak relationship, you will receive an error if that instance already exists. You must delete the existing weak member before you can import it.

Using the extension loader

The cmdbExtLoader program enables you to install one or more of BMC Atrium CMDB classes from one server to another. You use the extension loader either to extend the BMC Atrium CMDB or to install an extension pack. For information about the guidelines for extending the CDM, see the Concepts and Best Practices Guide.

The extension loader program can also install objects other than the data model extensions. However, this guide covers only the instructions for installing class and attribute extensions. For more information about importing data into AR System forms, see the BMC Remedy Action Request System 7.0: Configuring guide.

Using the extension loader � 61


The extension loader directory structure

The directory structure of the extension loader program is displayed in Figure 4-2.

Figure 4-2: Extension loader directory structure

At the top level is the directory where you copy the extension loader files, for example, CMDBExtensionLoader. Under the CMDBExtensionLoader directory is the common folder, and two cmdbExtLoader executables, one each for UNIX (no extension) and Windows (.exe).

Note: You must name the directory that contains the extension subdirectories as extensions. If you specify any other name for this directory, the extension loader will not recognize it.

After you copy the extension loader files into the extension loader directory you created, you create an extensions directory, as displayed in Figure 4-2. The extensions directory can contain one or more extension subdirectories.

Each extension subdirectory contains a package.xml file, an installation activity file, and one or more class XML files. These class files are obtained when you use the expdf command of the cmdbdriver program to export the class or attribute definitions.



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. The <install-order> instructs the extension loader to install the objects in the extensions directory in ascending order. Therefore, you must specify a lower <install-order> for the object that you want to install first.

For example, if you have two extension subdirectories, 650-EXClass and 655-EXClass, the 650-EXClass subdirectory will be installed first.

! <name> is an alphanumeric name for the extension. Make sure you do not use spaces, quotation marks, or wildcard characters in the <name> element.

Examples of extension subdirectory names are 500-EXClass and 501-EXAtt.

Packaging and installing BMC Atrium CMDB extensions

Packaging and installing your BMC Atrium CMDB extensions requires the following high-level steps:

Step 1 Export the class definitions with cmdbdriver (see page 64).

Step 2 Create the package.xml file (see page 64).

Step 3 Create an installation activity file (see page 67).

Step 4 Start the cmdbExtLoader program (see page 69).



Step 1—Export the class definitions using the cmdbdriver

Before you create the extension package, you must export your class or attribute definitions.

� To export class definitions

1 Create an extension subdirectory.

See “The extension loader directory structure” on page 62. This directory will contain all the extension loader files.

2 Export the class definitions using the cmdbdriver expdf command.

For more information about exporting class definitions with the cmdbdriver program, see “Step 1—Exporting class data with cmdbdriver” on page 55.

The expdf command creates several XML files that contain the class definition information for the specified class.

Step 2—Create the package.xml file

The package.xml file contains the registration and dependency information for the extension. The registration information defines the extension that you are creating. When the extension loader runs, it stores the extension registration values that you specify in the package.xml file, such as the extension name, version, and globally unique identifier (GUID) in the SHARE:Application_Properties AR System form.

A GUID is a unique ID for the extension. This ID is used by the extension loader program to determine if an extension is already installed. After you create an extension with a specific GUID, you can only change the version number to update the extension. The GUID will remain the same for the life span of an extension.


Example: package.xml

<?xml version="1.0" standalone="yes" ?> <package>  <name> ComSys Hardware Component</name> <guid>OS005056C0000898YWQgUsMLAAKwAA</guid> <version>1.0</version> <dependencies> <applications> <list>cmdb</list>  <cmdb> <guid>OB00C04FA081BABZlxQAmyflAg1wEA</guid> <name>BMC Atrium CMDB</name> <minversion>2.0</minversion>

</cmdb> </applications> </dependencies></package>

This package.xml example instructs the extension loader program to install the ComSys Hardware Component class extension version 1.0 on the BMC Atrium CMDB application version 2.0. The first line of code is an xml version tag that is required for all XML files.

Note: When you specify a GUID for the BMC Atrium CMDB dependency in your package.xml file, make sure you use the same GUID as shown in the example. This is the GUID stored in the SHARE:Application_Properties AR System form for the BMC Atrium CMDB.

� To create the package.xml file

1 Depending on whether you are creating a new extension or modifying an existing extension, perform one of the following steps:

! If you are creating a new extension, generate a GUID using the cg command of the cmdbdriver program. For more information about using the cmdbdriver program, see “Logging in to the cmdbdriver program” on page 54.

! If you are modifying an existing extension, skip to step 2.


2 Specify values for the following elements in the package.xml file:

! Registration information—Specify the following registration information for the extension:

! <name>—The name for the extension.

! <guid>—The GUID for the extension. For new extensions, specify the GUID that you created in step 1. For existing extensions, specify the currently existing GUID.

! <version>—The version number for the extension. Modify the version number only if you are modifying an extension.

! Dependencies—Specify the following dependency information for the extensions:

! <applications>—The applications that the extension depends upon. The applications specified here can be other extensions, AR System applications, or the AR System Server on which you want to install the extension.

! <version>—The version number of the application specified in the <application> element. You can either specify a value for the <version> element, which indicates the exact version number required for the application, or you can specify values for the <minversion> and <maxversion> elements, which indicate the range of permissible version numbers for the application.

3 Save the package.xml file under the extension subdirectory you created in “Step 1—Export the class definitions using the cmdbdriver.”



Step 3—Create an installation activity file

The installation activity file contains information about the type of activity you want to perform with the extension loader program, such as importing or exporting class definitions. Based on the activity description provided in the activity file, the extension loader performs a specified task.

An installation activity file uses the following naming convention:

<install-order>-<name>-<type>.<suffix> where:

! <install-order> is a three-digit number from 000 to 999. The install-order instructs the extension loader to install the objects in the Extensions directory in ascending order. Therefore, you must specify a lower install-order for the object that you want to install first.For example, if you have two extension subdirectories, 650-EXClass and 655-EXClass, the 650-EXClass subdirectory will be installed first.

! <name> is an alphanumeric name for the extension. Do not use spaces, quotation marks, or wildcard characters in the <name> element.

! <type> instructs the extension loader to perform an action based on a specific value. 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. The file extensions for the activity file include:

! XML—The file extension for the RIK file must be of type XML.

! Other types—The file extension for all other activities (IMP, ARD, and OSD) can be of any type such as txt.

An example of an activity file name is 500-CLASS-OSD.txt.

Every installation activity file you create must contain the oout and cout commands. The oout command instructs the extension loader to log the script actions. You must specify the OSDriver.out output filename with the oout command, as illustrated in the example, to save the script actions.

After the script stops executing the activity file, the extension loader reads these log comments to verify whether the script execution was successful. The cout command closes the log entry file.



Example: Activity file

ooutOSDriver.outimp //activity type1 // Number of class or instance defintions to importTEST // Class nameSampleClass // Namespace1 // metadata or instance data choice. 1 indicates metdata.

.couttermq

When the extension loader executes the activity file shown in this example, the class definitions for the Test class will be imported. You can specify multiple cmdbdriver commands in your activity file, for example, your script file can contain both export and import commands.

� To create an installation activity file

1 Open an empty file in a UNIX text editor, such as the vi text editor.

You must create the activity file in UNIX format for running it on the UNIX platform.

Important: If you create the activity file in Windows format, make sure you use the DostoUnix command to convert the file from Windows format to UNIX before you run it.

2 Type oout and OSDriver.out output file name in the beginning of the file as shown in the previous example.

You must specify the oout command and the OSDriver.out output file for the activity script. The extension loader program generates an error if you skip this line in the activity file.

Important: You must name the output file for the oout command as OSDriver.out. If you specify any other file name, the extension loader program generates an error.

3 Specify the type of activity the extension loader must perform, such as ARD or OSD.



4 Specify the number of class definitions or instance data objects you want to export or import.

5 Specify the class name and namespace for the OSD activity.

6 Specify if you want to export or import the metadata or instance data.

You can use the cmdbdriver program for the import and export function parameters. For more information about the cmdbdriver program, see “Working with the cmdbdriver program.”

7 Save the activity file under the extension subdirectory you created in step 1 with an xml, txt, or any other type of extension, depending on the activity type.

For more information about the activity file extensions, see “Step 3—Create an installation activity file” on page 67.

The Extensions subdirectories will now contain a package.xml file, an installation activity file, and the XML files, which were created when you exported your classes using the cmdbdriver program.

Step 4—Start the cmdbExtLoader program

After your extension subdirectory package is ready with all the required files, you can the start the extension loader program.

� To start the cmdbExtLoader program

! From the directory in which you installed the extension loader program, start the cmdbExtLoader program using the following steps, based on your platform:

! Windows—Double-click cmdbExtLoader.exe.

! UNIX—Double-click cmdbExtLoader file with no extension.

The extension loader installation wizard appears, which guides you through the installation process. After you complete the installation, your extensions are installed in the BMC Atrium CMDB.



Integrating the CI Relationship Viewer with other applications

The CI Relationship Viewer graphically displays the relationships between existing CIs. Although the CI Relationship Viewer is a part of the CMDB Console, the CI Relationship Viewer can also be integrated with other AR System applications. For information about using the CI Relationship Viewer to view instance relationships from the CMDB Console, see the User’s Guide.

You can integrate the CI Relationship Viewer with other applications using the following methods:

! AR System applications

! Launch the CI Relationship Viewer form from AR System applications. This is a quick and easy way to integrate the CI Relationship Viewer with your AR System application. In this method, you can launch the CI Relationship Viewer form, which is installed within the CMDB, using AR System workflow (see page 71).

! Embed CI Relationship Viewer in AR System applications. In this method, the CI Relationship Viewer field is embedded in the AR System application itself (see page 73).

! Non-AR System applications

! Launching the CI Relationship Viewer from non-AR System applications. In this method, you can launch the CI Relationship Viewer directly using a browser. (see page 75).



Launching the CI Relationship Viewer from AR System applications

When you launch the CI Relationship Viewer form from other AR System applications, the BMC Atrium CMDB performs the initialization function for the CI Relationship Viewer. You must specify the initialization parameters, such as Dataset ID, Filters, and CI ID of the CI for which the relationship data will be displayed.

Table 4-1 lists the parameters required to launch the CI Relationship Viewer form from other AR System applications.

Table 4-1: CI Relationship Viewer parameters—AR System applications

� To launch the CI Relationship Viewer from AR System applications

1 With BMC® Remedy® Administrator, log in to the BMC Atrium CMDB server and create a new active link for launching the CI Relationship Viewer.

The properties for the active link are displayed in a tab form. For more information about creating active links, see the BMC Remedy Action Request System 7.0: Workflow Objects guide.

2 On the Basic tab, specify details, such as the Form Name and Execute On criteria.

Parameter name Description

Namespace The namespace to which the instance belongs.

Class Name The class name to which the instance belongs.

CI ID The Instance ID of the CI for which the relationship data will be displayed.

Dataset ID The ID of the dataset where the instance resides.

Filter Name The filter name for the CI Relationship Viewer. These filters enable you to specify qualifications for the instances you want to view. The BMC Atrium CMDB application ships with one or more default filters. You can also create additional filters to suit your needs.

Integrating the CI Relationship Viewer with other applications � 71


Figure 4-3: Setting CI Relationship Viewer parameters

3 On the If Action tab, specify the following details:

! From the New Action list, select Open Window.

! From the Window Type list, select Search.

! From the Target Location list, select New.

Note: Launching the CI Relationship Viewer from AR Systems does not support the Current option for the Target Location list.



! From the Form Name list, select CMDB:CIViewer.

! In the Field Mapping section, specify the parameters listed in Table 4-1 on page 71.

4 Click Add Action.

5 On the Permissions tab, specify permissions for the active link.

6 On the BMC Remedy Administrator toolbar, click the Save icon.

Your active link is now saved.

Embedding the CI Relationship Viewer in AR System applications

Use the following procedure to embed the CI Relationship Viewer in your AR System form.

� To embed the CI Relationship Viewer in your AR System form

1 Using BMC Remedy Administrator, open the form in which you want to embed the CI Relationship Viewer.

2 Place a Data Visualization field on the form and double-click it to open the Field Properties tab.

3 On the Advanced tab, set the following Data Visualization field properties:

! From the Module type list, select CI Viewer.

Note: The CI Viewer value in the Module type list does not appear if you have not installed the BMC Atrium CMDB application on your system.

! From the Definition Name list, select the data visualization definition you created for the CI Viewer.

Select Default if you did not create any customized definitions. For more information about creating definitions, see “Creating a definition for the CI Relationship Viewer” on page 82.

4 On the Database tab, specify a name for the Data Visualization field in the Name text box.



5 Create an active link that will be executed when the Data Visualization field is initialized and specify the following details for the active link:

! On the Basic tab:

! Specify a name for the active link.

! From the Form Name list, select the form name.

! On the If Action tab:

! From the New Action list, select Set Fields.

! From the Read Value for Field From list, select the form name on which the data visualization field is placed.

! From the Name list, select the name of the Data Visualization field you created.

! In the Value field, set the required parameters for launching the CI Relationship Viewer, for example:

(((((((( "namespace=" + $Namespace$) + ",classname=") + $Class Name$) + ",datasetid=") + $Dataset ID$) + ",instanceid=") + $CI ID$) + ",filtername=") + “Components and Dependencies”

In the example, the field names, such as $Namespace$ and $Class Name$ are based on the field names of a form. You need to provide these field names as you have specified in your form. You might also specify string values as shown in the example.

Important: The namespace, classname, datasetid, instanceid, and filtername parameters are CI Relationship Viewer-defined keywords.

6 Click Add Action to save the settings for the action.

7 Click Save to save the active link.



Launching the CI Relationship Viewer from non-AR System applications

You can launch the CI Relationship Viewer directly from any non-AR System applications using a browser. To launch the CI Relationship Viewer from a non-AR System application, you must specify the initialization parameters for the viewer in the URL format.

In the URL for launching the CI Relationship Viewer, constants, such as F490001100, indicate the field ID on the CI Relationship Viewer form. These IDs are fixed values for the initialization parameters. Table 4-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 Parameter name Description

F49000110f0 Namespace The namespace to which the instance belongs.

F400109900 Class Name The class name to which the instance belongs.

F431400000 CI ID The Instance ID of the CI for which the relationship data will be displayed.

F431400001 Dataset ID The dataset from where the instance data will be selected.

F431400003 Filter Name The filter name for the CI Relationship Viewer. These filters enable you to specify qualifications for the instances you want to view. The CMDB application ships with one or more default filters. You can also create additional filters to suit your needs.



� To launch the CI Relationship Viewer from a browser

1 Open a browser and type the following URL in the address field:

http://<midtier>/arsys/apps/<arserver>/AtriumCMDBConsole/CMDB:CIViewer?F490001100=<namespace>&F400109900=<classname>&F431400000=<ciid>&F431400001=<datasetid>&F431400003=<filtername>

Make sure that you specify appropriate values for placeholders, such as <mid tier>, <arserver>, <namespace>, <classname>, <ciid>, <datasetid>, and <filtername>.

2 Press Enter.

The BMC Remedy Action Request System login screen appears.

3 Type a user name and password in the login screen, and click Log In.

The CI Relationship Viewer window appears as shown in Figure 4-4.

Figure 4-4: CI Relationship Viewer—From a browser



Configuring the CI Relationship Viewer

You can configure the CI Relationship Viewer to restrict the relationships displayed by number of levels, create various events, specify font size and color, and display a context menu that enables you to perform various actions based on the menu selection.

Working with filters

The CI Relationship Viewer enables you to define filters for retrieving relationship information to generate a graphical relationship map. These filters are useful when retrieving large amounts of class and relationship data.

As you can view relationships up to any number of levels from the root CI, filters provide a way to limit the items that are shown in the graph. You can filter class and relationship data by CI class types, relationship types, status, and view relationships up to any number of levels from the root CI.

The BMC Atrium CMDB ships with two default filters—All and Components and Dependencies. You can create custom filters using the Manage Filters link on the CMDB Console.

For more information about creating filters, see the Installation and Configuration Guide.

Customizing the configuration file

The settings that specify the visual and display definitions for the CI Relationship Viewer are encapsulated in a configuration file. Although the CI Relationship Viewer provides a default configuration file (config.xml) that contains standard settings for the viewer, you can create a custom configuration file to suit your needs.

After you create a configuration file, you add it as an attachment to the CI Relationship Viewer definition, which is an entry in the Data Visualization Definition form.

You customize the CI Relationship Viewer settings using the following steps:

! “Creating a configuration file” on page 78

! “Creating a definition for the CI Relationship Viewer” on page 82

Configuring the CI Relationship Viewer � 77


Creating a configuration file

This section explains how to create a custom configuration file, which includes settings, such as the context menu that displays various menu options, launch in context, and color settings for the CI Relationship Viewer.

The following example specifies the format for defining a menu item:

Example: Menu item definition

<menuitem id="MNU_ID1" text="item1" action="action1" enabled="false"/>

Where:

! id—Uniquely identifies the menu item.

! text—The text string for the menu that will be displayed in the CI Relationship Viewer. Enter a meaningful name for this attribute.

! action—Specifies the action that will be performed when the user selects the menu item. The action attribute can contain JavaScript code or one of the predefined event types, for example, CIRV_NOTIFY_AR.

If the action attribute for any menu item is set to CIRV_NOTIFY_AR, then the ID of the menu item is passed to the container AR System form in the event type parameter. For more information about the CI Relationship Viewer events, see Appendix B, “Finding related CIs using graph queries.”

! enabled—Used to enable or disable the menu item. If you do not define this attribute, the default value of true is accepted.

You can create submenus up to any number of levels. 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. A separator does not have the text and action attributes. The following example shows a menu separator:

Example: Menu separator

<menuitem id="MNU_SEPARATOR"/>



The CI Relationship Viewer predefines a set of standard menu items for the applications that use the viewer. Table 4-3 lists the menu or submenu items of the CI Relationship Viewer along with their functions.

Note: The menu items listed in Table 4-3 are displayed in the context menu by default. To hide any of submenus in the context menu pop-up, modify the config.xml file or create a custom configuration file.

SUBMENU_LAUNCH is a special menu type that is used for adding menu items for launching federated data in context. If a SUBMENU_LAUNCH menu item is included in the configuration file, menu items for all applicable federated interfaces are automatically displayed.

The default option for the Launch in Context submenu in the CI Relationship Viewer is CI Viewer, which launches the CI Relationship Viewer in a browser. The SUBMENU_LAUNCH submenu will appear disabled in the CI Relationship Viewer if there are no CIs that are selected on the CI Relationship Viewer map.

Note: Do not add any menu items for the SUBMENU_LAUNCH menu option in the configuration file. Based on the federation definitions, the menu items will be dynamically added to SUBMENU_LAUNCH at run time.

Table 4-3: Menu items and their functions

Action value Function Text displayed in the CI Relationship Viewer

MNU_SET_AS_ROOT Sets the currently selected CI as root Set as Root

MNU_SEPARATOR Separator A line

MNU_LAYOUT_TREE Tree Layout Tree

MNU_LAYOUT_RADIAL Radial Layout Radial

MNU_SHOW_LEGEND Show/Hide Legend Show/Hide legend

MNU_REFRESH Refreshes the Relationship Graph Refresh

SUBMENU_LAYOUT Submenu for showing the layouts Layout

SUBMENU_LAUNCH Submenu for showing the items for Launch in Context

Launch in Context



The configuration, style, and context menu information must be placed within the <config>, <style>, <contextmenu> element tags respectively. Table 4-4 explains the various style attributes for the CI Relationship Viewer context menu.

Table 4-4: Context menu style attributes.

The color scheme for the different relationship types should be placed inside the <link> tag. If the color for a specific relationship type is not defined, the default values for the color and width tags will be used, as defined in the parent XML element.

Style attribute name Description

fontSize The font size for the CI labels.

nodeSize The default icon size for CI representation.

fill The color for the links. When used in the link element, it represents the default color.

width The width of the link. When used in the link element, it represents the default width.

text The text to display in the legend.



Example: config.xml file

<config><style fontSize="10" nodeSize="35.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 example, the context menu shown in Figure 4-5 is displayed in the CI Relationship Viewer.

Figure 4-5: CI Relationship Viewer context Menu



Creating a definition for the CI Relationship Viewer

This section explains how to attach a configuration file to a CI Relationship Viewer definition. You create a definition for the CI Relationship Viewer to apply the settings you specified in the custom configuration file. This definition is created using the Data Visualization Definition form.

After you create a definition for the custom configuration file, you must then change the Definition Name on the Advanced tab of the CI Relationship Viewer field properties to override the default definitions provided with the BMC Atrium CMDB application.

For more information about creating a configuration XML file, see “Customizing the configuration file” on page 77.

� To create a CI Relationship Viewer definition

1 In BMC Remedy User, open the Data Visualization Definition form in Search mode.

2 Click Search on the form toolbar.

All existing Data Visualization Definition entries are listed in the results pane, as displayed in Figure 4-6 on page 83.



Figure 4-6: Data Visualization Definition form

3 In the results pane, select the entry with a Definition Name of Default.

The default definition is displayed.

4 Choose Edit > Copy to New.

The field values are copied to a Data Visualization Definition window in New mode. You can now modify the fields before saving the new definition.



5 Specify the following details for the definition:

! Definition Name—A unique name for the definition.

Note: The Module Name for the definition must always be CI Viewer to integrate with the CI Relationship Viewer.

! Description—A description for the definition.

! Complex Definition—Your customized config.xml file. To specify a complex definition file, drag it into the Complex Definition attachment field.

Important: After you modify a configuration XML file and attach it to the Data Visualization Definition, you must restart the BMC Remedy Mid Tier to view the changes in the CI Relationship Viewer context menu.

6 Click Save.

Creating CI Relationship Viewer events

The CI Relationship Viewer can send and receive various types of events from AR System forms. These events include instructions for setting a CI as the root, refreshing the CI Relationship Viewer map, and notifying the AR System.

For more information about the CI Relationship Viewer events, see Appendix A, “CI Relationship Viewer events.”



Creating CMDB status alerts

You create status alerts for the BMC Atrium CMDB from other integrating applications to display on the CMDB Console.To create status alerts, you add an entry in the CMDB:StatusAlerts form.

You can use either the AR System API or workflow to add this entry. You must provides values for the Type, Priority, and Short Description fields.

! Type—The type of alert. You can specify any value in this field. However, the best practice is to provide the name of the integrating application that adds an entry in the CMDB:StatusAlerts form for tracking purposes.

! Priority—The priority for the alert. You can choose from Low, Medium, or High.

! Short Description—The description of the alert. You specify the problem or status description in this field.

Optionally, you can provide an additional description for the alert in the Description field. Date/Time is an auto-generated field. The fields that appear on the CMDB Console include Short Description, Priority, Type, and Date/Time.

Creating CMDB status alerts � 85


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. With EIE, you perform scheduled bulk data transfers and event-based integrations. You can use EIE for initial data load, incremental data transfers, and data synchronization.

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, this relationship is many-to-many because you can map different columns from different data sources to different attributes in the same BMC Atrium CMDB class.

For more information about EIE data transfer between a third-party data source and the BMC Atrium CMDB, see the BMC Remedy Enterprise Integration Engine 7.0 Administrator’s Guide.



Working with SQL views

SQL views are available to facilitate data access to the BMC Atrium CMDB from third-party database clients. These views provide direct access to the database tables for the various BMC Atrium CMDB classes, without having to know the hierarchy of a given class.

For each database table in the AR System (except for the attachment tables), a corresponding SQL view is automatically created. These views, which have the same name as their underlying forms, are created using the following naming rules:

! Alphabetic and numeric characters remain as defined.

! Colons and other special characters are replaced by underscores. For example, the SQL view for the BMC.CORE:BMC_BaseElement form is named BMC.CORE_BMC_BaseElement.

! A leading A is appended to all view names that do not begin with an alphanumeric character.

! If the name contains a database reserved word, the string _x is appended to the name.

! View names are limited to 30 characters. When a form name exceeds the 30 character limit, the corresponding view name is truncated to 27 or 28 characters. A schema ID is appended to the view name to differentiate between any other view that was truncated to the same string. Because schema IDs vary from one system to another, these view names cannot be formulated in advance. For example, the view of the BMC.CORE.CONFIG:BMC_ConfigBaseRelationship form might be named BMC_CORE_CONFIG_BMC_ConfigB131 or BMC_CORE_CONFIG_BMC_Config2131e

! Abstract classes do not store any data. Therefore, abstract classes do not have corresponding views.

For more information about SQL views and table naming conventions, see the BMC Remedy Action Request System 7.0: Database Reference guide.

Working with SQL views � 87


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.

Using the API Logging option

The BMC Atrium CMDB logs the engine processing, which helps you to debug your API program. When you enable logging, the BMC Atrium CMDB records details about operations, such as SynchMetaData, graph query, and export and import.

For more information about related API functions, see “Import and Export functions” on page 149, “Environment functions” on page 141, and “Instance functions” on page 126.

The BMC Atrium CMDB Engine log classifies the messages into error, warning, and information. To enable CMDB Engine debug logging, add the following entry in the ar.cfg configuration file on Windows or the ar.conf configuration file on UNIX and restart the AR System server:

CMDB-Debug-Flag: T

To disable logging, set this parameter to F. Each entry in the log provides the following details:

! Timestamp—The date and time of the log entry.

! Log Type—The type of log entry such as warning, error, or information.

! Message—The message for the log entry.

You can specify additional parameters for the logging option in the ar.cfg or ar.conf configuration file depending on your platform. However, you can only add these parameters after you set the CMDB-Debug-Flag parameter to true (T).

! CMDB-Debug-Level—Specifies the level of logging you require for your API calls. These levels determine the type of messages that are logged for the calls. The various debug levels include:

! 1—Severe errors messages

! 2—Warnings messages



! 3—Informational messages

! 4—Detail messages

! 5—Additional detail messages

All these logging levels are inclusive of their preceding levels. For example, if you set the debug level at 3, you will receive log messages for levels 1, 2, and 3. The default value for CMDB-Debug-level parameter is set to 3. An example for this parameter is, CMDB-Debug-Level: 2.

! CMDB-Log-File-Location—Enables you to specify the directory location on your system where the log file will be written. You can specify any location on your system for the log files. By default, the log file is written to the Db directory of the AR System server.

! CMDB-Max-Log-File-Size—Enables you to specify a maximum size for your log file. The size of the log file is specified in kilobytes (KB). When the log file reaches the specified limit, the system automatically creates a backup of the log file and stores the log entries in a new log file.

The default value for the CMDB-Max-Log-File-Size parameter is set to 0, which specifies an unlimited size for the log file. An example of this parameter is, CMDB-Max-Log-File-Size: 50000.

Using print.c routines

One of the components of the cmdbdriver program is the set of print routines located in the print.c file. These routines allow you to print the contents of any data structure in the API. The routines provide code examples for accessing the various structures. Printing the contents of a structure before and after an API call is useful for debugging.

Note: See the function definitions in print.c to determine the specific parameters and their types for these routines.

The print.h file contains a complete list of these routines.

Debugging BMC Atrium CMDB API programs � 89

Section

II
API reference
This section provides reference information for the C and web services APIs. The Java API documentation is available in the Javadoc HTML files.

This section is organized into the following chapters:

! Chapter 5, “C API functions and data structures,” provides information about the functions and the data structures used in the C APIs.

! Chapter 6, “Web services API operations and data structures,” provides information about the operations and data structures used in the web services APIs.

! Chapter 7, “Error messages,” provides all CMDB error messages with their descriptions.

API reference � 91


92 � Section II—API reference

Chapter

5
C API functions and data structures
This chapter describes the C API functions.


! Related files (page 94)

! Deprecated objects (page 94)

! Functions (page 95)

! Data structures (page 182)

C API functions and data structures � 93


Related files

The cmdb.h and cmdbfree.h files contain the C API function definitions. For a complete list of header files required for the BMC Atrium CMDB, see Chapter 2, “Header files.”

Deprecated objects

In version 2.0 of the BMC Atrium CMDB, 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, you pass a parameter to specify whether you want to export or import class definitions or instance data. In version 2.0, 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.

! CMDBExportData—Exports instance data to a specified directory in a given format.

! CMDBImportDef—Imports a list of specified class definitions.

! CMDBImportData—Imports the specific instance data.

94 � Chapter 5—C API functions and data structures


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. The function categories include data model, instance, and general purpose functions, such as session, authentication, and import or export definition functions.

Note: In the C API function descriptions, the usage of the term specified for a given parameter denotes that the parameter is listed under the Synopsis heading of the API function.

Data model functions

The data model functions manipulate the attribute and class. The C API functions for data model include:

! CMDBCreateAttribute (page 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


! CMDBGetClass (page 120)

! CMDBGetListClass (page 122)

! CMDBSetClass (page 123)

CMDBCreateAttribute

Description Creates a new attribute with the specified name for the specified class.

Privileges CMDB Administrator

Synopsis #include "ar.h"#include "arextern.h"#include "cmdb.h"

int CMDBCreateAttribute(

Inputarguments

control

The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.

classNameID

The name of the class for which you want to create an attribute. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.

ARControlStruct *control,

CMDBClassNameId classNameID,

ARNameType attributeName,

ARNameType attributeId,

unsigned int dataType,

ARInternalId *arsubclassesId,

unsigned int entryMode,

CMDBAttributeLimit *attributeLimit,

ARValueStruct *defaultValue,

ARPropList *characList,

ARPropList *customCharacList,

ARStatusList *status)



attributeName

The name of the attribute to create. The name of the attribute must be unique within the specified class and within its superclasses and subclasses.

attributeID

The ID of the attribute to create.

dataType

The datatype of the attribute to create.

1: Keyword (CMDB_ATTR_DATA_TYPE_KEYWORD)

2: Integer (CMDB_ATTR_DATA_TYPE_INTEGER)

3: Real (CMDB_ATTR_DATA_TYPE_REAL)

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. Specify 0 for this parameter if you want the system to generate the ID.

Functions � 97


entryMode

The entry mode for the attribute. Entry mode can be set to any one of the following: required, optional, or display only.

1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED).

2: Users do not have to enter data when the entry mode is set to optional but they can if they want to (CMDB_ATTR_ENTRYMODE_OPTIONAL).

4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).

attributeLimit

The value limits for the attribute and other properties specific to the attribute’s type. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute you are creating. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the attribute limits and properties.

defaultValue

The value to apply if a user submits an entry with no attribute value. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute. Specify NULL if you do not want to specify a default value.

characList

A list of characteristics for the attribute. It includes the following characteristics: View Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description.

1: Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). When querying for attributes, you will see all attributes including the hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;-5.

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



3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN). This setting marks the atribute as hidden for a group or a role. When querying for classes, you can retrieve hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;3.

5: The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is <leadclassID>|<lead attribute>.

6: CMDB_ATTR_CHARAC_CREATE_MODE

7:Users can set the audit option on to store the audit history for the attribute. CMDB_ATTR_CHARAC_AUDIT_OPTION

9:Users can set the description for the attribute. CMDB_ATTR_CHARAC_DESCRIPTION

customCharacList

A list of user-defined custom characteristics for the attribute. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX). After the properties list structure you specify is serialized, it is converted into the <list_size><prop_id><data_type><prop_value> format, where:

<list_size>: The number of items in the properties list.

<prop_id>: The ID for the property, which is within the 300000 - 399999 range.

<data_type>: The data type for the property, which can be of any native data type.

<prop_value>: The value for the property.

An example for the serialized property list is 1\300050\2\1.

Return values status

A list of zero or more notes, warnings, or errors generated from a call of this function.

Functions � 99


CMDBCreateMultipleAttribute

Description Creates multiple new attributes with the specified names for the specified class.



int CMDBCreateMultipleAttribute(

Inputarguments

control


classNameID

The name of the class for which the attributes need to be created. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.

attributeNameList

The list of attribute names. The names of all attributes must be unique within the specified class and within its superclasses and subclasses.

attributeIdList

The list of attribute IDs for the attributes being created.


CMDBClassNameId *classNameID,

ARNameList *attributeNameList,

ARNameList *attributeIdList,

ARUnsignedIntList *dataTypeList,

ARInternalIdList *arsubclassesIdList,

ARUnsignedIntList *entryModeList,

CMDBAttributeLimitList *attributeLimitList,

ARValueList *defaultValueList,

ARPropListList *characListList,

ARPropListList *customCharacListList,




dataTypeList

The list of data types for the attributes being created.

arsubclassesIdList

The AR System subclasses IDs of the attributes being created.

entryModeList

The list of entry modes for the attributes being created. Options include display only, required, and optional.




attributeLimitList

The list of value limits for the attributes being created and other properties specific to the attributes’ types. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute list you are modifying. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the limits and properties for the attribute list.

defaultValueList

The list of values to apply if a user submits an entry with no value for the attributes being created. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute. Specify NULL if you do not want to specify a default value.

characListList

A list of characteristics for each attribute. Characteristics include View Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description.

1: Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).When querying for attributes, you will see all attributes, including the hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;-5.

Functions � 101



3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN). Marks a list of atributes as hidden for a group or a role. When querying for classes, you can choose to retrieve hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;3.




9:Users can set descriptions for the attributes. CMDB_ATTR_CHARAC_DESCRIPTION

customCharacListList

A list of user-defined custom characteristics list for each attribute. The value can be set to any user-defined characteristic but must be in the range between 300000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 399999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this attribute. After the properties list structure you specify is serialized, it is converted into the <list_size><prop_id><data_type><prop_value> format, where:

<list_size>: The number of items in the properties list.

<prop_id>: The ID for the property, which is within the 300000 - 399999 range.

<data_type>: The data type for the property, which can be of any native data type.

<prop_value>: The value for the property.






CMDBDeleteAttribute

Description Deletes the attribute with the specified ID. Depending on the value you specify for the deleteOption parameter, the attribute is deleted immediately and is not returned to users who request information about attributes.



int CMDBDeleteAttribute(

Inputarguments

control


classNameID

The name of the class from which to delete the attribute.

attributeName

The name of the attribute to delete.

deleteOption

A value indicating the action to take if the specified attribute contains data.

0: Do not delete the attribute (AR_ATTRIBUTE_CLEAN_DELETE).

1: Delete if the attribute contains data but not if it is inherited by subclasses (AR_ATTRIBUTE_DATA_DELETE).

2: Delete the attribute even if it has subclasses that are associated with it (AR_ATTRIBUTE_FORCE_DELETE).


CMDBClassNameId classNameID,


unsigned int deleteOption,


Functions � 103




CMDBGetAttribute

Description Retrieves a single attribute.

Privileges CMDB administrator


int CMDBGetAttribute(

Inputarguments

control


classNameId

The name of the class. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.

attributeName

The name of the attribute to retrieve.


CMDBClassNameId *classNameId,


ARNameType attributeId,

unsigned int *dataType,

unsigned int *attributeType,

CMDBClassNameId *baseClassNameId,

ARInternalId *arsubclassesId,

unsigned int *entryMode,








Return values attributeId

The ID of the attribute.

dataType

The datatype of the attribute.

1: Keyword (CMDB_ATTR_DATA_TYPE_KEYWORD)

2: Integer (CMDB_ATTR_DATA_TYPE_INTEGER)

3: Real (CMDB_ATTR_DATA_TYPE_REAL)

4: Character (CMDB_ATTR_DATA_TYPE_CHAR)

5: Diary (CMDB_ATTR_DATA_TYPE_DIARY)

6: Selection (CMDB_ATTR_DATA_TYPE_ENUM)

7: Time (CMDB_ATTR_DATA_TYPE_TIME)

10: Fixed-point decimal (CMDB_ATTR_DATA_TYPE_DECIMAL)

12: Currency (CMDB_ATTR_DATA_TYPE_CURRENCY)

13: Date (CMDB_ATTR_DATA_TYPE_DATE)

14: Time 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.

1: CMDB_ATTR_TYPE_CORE_INTERNAL

2: CMDB_ATTR_TYPE_CORE

3: CMDB_ATTR_TYPE_REGULAR

baseClassNameId

The name of the class that owns this attribute.

arsubclassesId

The internal ID of the attribute to retrieve.

entryMode

The entry mode for the attribute list. Entry mode can be set to any one of the following: display only, required, optional.

1: CMDB_ATTR_ENTRYMODE_REQUIRED

Functions � 105


2: CMDB_ATTR_ENTRYMODE_OPTIONAL

4: CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY

attributeLimit


defaultValue

The value to apply if a user gets an entry with no attribute value. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute.

characList


1: List of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).

2: List of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).

3: The flag value of the Hidden characteristic. If the flag is set to false, users cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN).

4: Specifies whether the attribute is a part of the primary key of the class (CMDB_ATTR_CHARAC_PRIMARY_KEY).



7: The audit option for the attribute. If the audit option is on, the audit history for the attribute is stored. CMDB_ATTR_CHARAC_AUDIT_OPTION

9: The description of the attribute. CMDB_ATTR_CHARAC_DESCRIPTION



customCharacList

A list of user-defined custom characteristics for the attribute. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX).

status


CMDBGetMultipleAttribute

Description Retrieves multiple attributes.



int CMDBGetMultipleAttribute(



ARBoolean getHiddenAttrs,

ARBoolean getDerivedAttrs,

ARNameList *nameList,

ARPropList *attrCharacQueryList,

ARBooleanList *existList,


ARNameList *attributeIdList,

ARUnsignedIntList *dataTypeList,

ARUnsignedIntList *attributeTypeList,

CMDBClassNameIdList *baseClassNameIdList,

ARInternalIdList *arsubclassesIdList,




ARPropListList *characList,

ARPropListList *customCharacList,


Functions � 107


Inputarguments

control


classNameId

The name of the class to retrieve. It is a two-part structure that contains the namespace and the classname.

getHiddenAttrs

A flag indicating whether to retrieve the hidden attributes. Specifying FALSE will not retrieve the hidden attributes.

getDerivedAttrs

A flag indicating whether to retrieve attributes derived from a superclass. Specifying FALSE will not retrieve the derived attributes.

nameList

A list of attributes to retrieve.

attrCharacQueryList

A list of attribute characteristic queries to retrieve.

Return values existList

A list of flags and corresponding Boolean values indicating whether the attribute list exists. The value TRUE indicates that the attribute list exists; FALSE indicates that the attribute list does not exist.

attributeNameList

The list of attribute names retrieved.

attributeIdList

The list of attribute IDs retrieved.

dataTypeList

The list of data types for the attribute.

attributeTypeList

The list of the attribute’s type.



baseClassNameIdList

The name of the base class attribute to retrieve.

arsubclassesIdList

The AR System subclasses ID of the attribute.

entryModeList

The entry mode for the attribute list. Options include display only, required, and optional.

1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED ).

2: Users do not have to enter data when the entry mode is set to optional (CMDB_ATTR_ENTRYMODE_OPTIONAL).


attributeLimitList

The value limits for the list of attributes and other properties specific to the attribute’s type. See “CMDBAttributeLimit” on page 187 to find the contained structure that applies to the type of attribute you are modifying. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the attribute limits and properties.

defaultValueList

The value to apply if a user submits an entry with no attribute list value. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute.

characList


1: List of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).

2: List of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).

Functions � 109


3: The flag value of the Hidden characteristic. If the flag is set to false, 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).



7: The audit option for the attribute. If the audit option is on, the audit history for the attribute is stored. CMDB_ATTR_CHARAC_AUDIT_OPTION

9: The description of the attribute. CMDB_ATTR_CHARAC_DESCRIPTION

customCharacList


status




CMDBSetAttribute

Description Sets an attribute with the specified name for the specified class.



int CMDBSetAttribute(

Inputarguments

control


classNameId

The name of the class for which the attribute needs to set. It is a two-part structure that contains the namespace and the classname.

attributeName

The name of the attribute to set.

newAttributeName

The new name of the attribute, which must be unique within the specified class and within its superclasses and subclasses.

entryMode

The entry mode for the attribute. Options include display only, required, and optional.




ARNameType newAttributeName,

unsigned int *entryMode,






Functions � 111





attributeLimit

The value limits for the attribute and other properties specific to the attribute’s type. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute you are setting. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the attribute limits and properties.

defaultValue

The value to apply if a user sets an entry with no attribute value. The default value can be as many as 255 bytes in length and must be of the same data type as the attribute.

characList


1: Users can view but not modify the characteristics of the attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).

2: Users can view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).

3: Users can set the flag to false so they cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN).






9:Users can set the description of the attribute. CMDB_ATTR_CHARAC_DESCRIPTION

customCharacList


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.



CMDBSetMultipleAttribute

Description Sets multiple attributes with the specified names for the specified class.



int CMDBSetMultipleAttribute(




ARNameList *newAttributeNameList,




ARPropListList *characListList,

ARPropListList *customCharacListList,


Functions � 113


Inputarguments

control


classNameId

The name of the class for which the attributes need to be set. It is a two-part structure that contains the namespace and the classname.

attributeNameList

The list of attribute names to set.

newAttributeNameList

The list of new names of the attributes. The names of all attributes must be unique within the specified class and within its superclasses and subclasses.

entryModeList

The list of entry modes for the attributes being created. Entry mode can be set to any one of the following modes: display only, required, optional.

1: Users must enter data when the entry 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. See “CMDBAttributeLimit” on page 187 to find the contained structure that applies to the type of attribute list you are modifying. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the limits and properties for the attribute list.



defaultValueList

The list of values to apply if a user submits an entry with no value for the attributes being created. The default value can be as many as 255 bytes in length and must be of the same data type as the attribute. Specify NULL if you do not want to specify a default value.

characListList


1: Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).


3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN).



7:User can set the audit option on to store the audit history for the attribute. CMDB_ATTR_CHARAC_AUDIT_OPTION

9:Users can set descriptions of the attributes. CMDB_ATTR_CHARAC_DESCRIPTION

customCharacListList

A list of user-defined custom characteristics list for the attribute. The value can be set to any user-defined characteristic but must be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this attribute.


Functions � 115




CMDBCreateClass

Description Creates a class with the core attributes in the OBJSTR:Class. The data model is stored in the OBJSTR:Class form and the attribute information is stored in the OBJSTR:AttributeDefinition form.



int CMDBCreateClass(

Inputarguments

control


classNameID

The name of the class to create. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.

classID

The unique identifier for the class. It can be provided by the user. If left blank, the class ID will be automatically generated by the system.


CMDBClassNameId *classNameID,

ARNameType classID,

CMDBClassTypeInfo *classTypeInfo,

CMDBClassNameId *superclassNameId,

CMDBIndexList *indexList,

CMDBAuditInfoStruct *auditInfo,






classTypeInfo

The type of class to create. The information contained in this definition depends on the type of class you specify.

1: Indicates a regular class (CMDB_CLASS_TYPE_REGULAR).

2: Indicates a class of type relationship (CMDB_CLASS_TYPE_RELATIONSHIP).

superclassNameID

The superclass of this class. Specify NULL for this parameter if there is no superclass.

indexList

A list of indexes defined for the class.

auditInfo

The audit information for the class.

characList

A list of characteristics for the class. Specify NULL for this parameter if you do not want to associate characteristics with this class.

1: Used to specify if this is a singleton class. This characteristic is an integer value where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a singleton class (CMDB_CLASS_CHARAC_SINGLETON).

2: This property does not allow you to create instances for this abstract class (CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the attribute, you cannot create instances for it. All the attributes are propagated to the subclasses.

3: You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL).

4: The author of the class (CMDB_CLASS_CHARAC_AUTHOR).

5: The class description (CMDB_CLASS_CHARAC_DESCRIPTION).

6: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). Marks the class as hidden for a group or a role. When querying for classes, you can choose to retrieve hidden classes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;3.

Functions � 117


7: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_VISIBLE_PERMS). Marks the class as visible for a group or a role. When querying for classes, you will see all classes, including the hidden classes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;-5.

8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS

9: CMDB_CLASS_CHARAC_FORM_NAME

customCharacList

A list of user-defined custom characteristics for the class. The ID for each list item can be set to any user-defined characteristic but must be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this class. After the properties list structure you specify is serialized, it is converted into the <list_size><prop_id><data_type><prop_value> format, where:

<list_size>: Is the number of items in the properties list.

<prop_id>: Is the ID for the property, which is within the 100000 - 199999 range.

<data_type>: Is the data type for the property, which can be of any native data type.

<prop_value>: Is the value for the property.






CMDBDeleteClass

Description Deletes a specified class. Also deletes the associated attributes of the class.



int CMDBDeleteClass(

Inputarguments

control


classNameID

The name of the class to delete.

deleteOption

A value indicating the action to take if the specified class contains attributes or subclasses.

0: Delete the class only if the class contains no instances and has no subclasses or dependent relationships (CMDB_DELETE_CLASS_OPTION_NONE).

1: Delete the class only if the class has no subclasses or dependent relationships. This applies only to regular classes (CMDB_DELETE_CLASS_OPTION_WITH_DATA).

2: Delete the class, including all the subclasses and dependent relationship classes that are associated with it. All the dependencies for the specified class are deleted (CMDB_DELETE_CLASS_OPTION_ALL_DEPENDENCIES). This option overrides the CMDB_CLASS_DATA_DELETE option.







Functions � 119


CMDBGetClass

Description Retrieves the class information from the OBJSTR:Class form.



int CMDBGetClass(

Inputarguments

control


classNameID

The name of the class. It is a two-part structure that contains the namespace and the classname.

Return values classId

The ID used to identify the class.

classTypeInfo

Information about the type of class.

superclassNameId

The name of the superclass.


CMDBClassNameID *classNameId,

ARNameType *classId,


CMDBClassNameId *superclassNameId,


CMDBAuditInfoStruct auditInfo,






indexList

The list of indexes defined for the class.

auditInfo


characList

A list of characteristics for this class. Specify NULL for this parameter if you do not want to associate characteristics with this class.

1: Used to specify if this is a singleton class. This characteristic is an integer value where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a singleton class (CMDB_CLASS_CHARAC_SINGLETON).

2: This property does not allow you to create instances for this abstract class (CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the attribute, you cannot create instances for it. All the attributes are propagated to the subclasses.




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.



Functions � 121


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


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.



int CMDBGetListClass(

Inputarguments

control


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.


ARNameType namespaceName,

CMDBClassNameId *classNameIdRelation,

CMDBClassNameId *superclassName,

ARPropList *characQueryList,

ARBoolean getHiddenClasses,

CMDBClassNameIdList *classNameIdList,




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


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.



int CMDBSetClass(



CMDBClassNameId *newclassNameId,



CMDBAuditInfoStruct *auditInfo,




Functions � 123


Inputarguments

control


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


characList

A list of characteristics for this class. Specify NULL for this parameter if you do not want to associate characteristics with this class.

1: Used to specify if this is a singleton class. This characteristic is an integer value, where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a singleton class (CMDB_CLASS_CHARAC_SINGLETON).

2: This property does not allow you to create instances for this abstract class (CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the class, you cannot create instances for it. All the attributes are propagated to the subclasses.






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.



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.




Functions � 125


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 Creates a CI or relationship instance in the OBJSTR:Class.



int CMDBCreateInstance(

Inputarguments

control


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.



ARNameType datasetId,

CMDBAttributeValueList *attributeValueList,

ARNameType instanceId,




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


CMDBDeleteInstance

Description Deletes the instance of the class.



int CMDBDeleteInstance(







Functions � 127


Inputarguments

control


classNameId

The name of the class that holds the instance to delete.

datasetId


instanceId

The unique identifier for the instance (system-generated).

deleteOption

0: Allows you to delete only the specified instance when the instance can be retrieved (CMDB_DERIVED_DELOPTION_NONE).

1: Allows you to delete the instance even when the instance cannot be retrieved (CMDB_DERIVED_DELOPTION_FORCE). Errors will be ignored for instances that do not exist.





CMDBGetInstance

Description Retrieves information about the instance.



int CMDBGetInstance(

Inputarguments

control


classNameId


datasetId


getMask

The identifier for specifying the dataset type.

0: Based on the datasetId being passed, instances are retrieved from either the overlay or the original dataset.

1: Allows you to retrieve instances from the current dataset only.




usigned int getMask,


ARNameList *attributeGetList,



Functions � 129


instanceId

The unique identifier for the instance to retrieve.

attributeGetList

The list of attributes to retrieve.

Return values attributeValueList

The list of attribute ID and value pairs for the instance.

status


CMDBGetListInstance

Description Retrieves a list of instances. You can limit the instance list to entries that match particular conditions by specifying the qualifier parameter.



int CMDBGetListInstance(




usigned int getMask,

CMDBQualifierStruct *qualifier,


CMDBSortList *sortList,

unsigned int firstRetrieve,

unsigned int maxRetrieve,

ARNameList *instanceIdList,

CMDBAttributeValueListList *attributeValueListList,

unsigned int *numMatches,




Inputarguments

control


classNameId


datasetId


getMask



1: Allows you to retreive instances from the current dataset only.

qualifier

A query that determines the set of entries to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations.

attributeGetList

A list of attribute names to retrieve.

sortList

The sort order for the retrieved data.

firstRetrieve

The first entry to retrieve. CMDB_START_WITH_FIRST_ENTRY represents the first entry to retrieve and is the default value if the value is not set.

maxRetrieve

The maximum number of entries to retrieve. Use this parameter to limit the amount of data returned if the qualification does not narrow the list. Specify CMDB_NO_MAX_LIST_RETRIEVE to assign no maximum.

Functions � 131


Return values instanceIdList

The list of instance IDs that match the criteria.

attributeValueListList

A list of the attribute value list.

numMatches

The total number of entries that match the qualification criteria. This value does not represent the number of entries returned unless the number of matching entries is less than or equal to the maxRetrieve value.

status


CMDBGetMultipleInstances

Description Retrieves multiple instances.



int CMDBGetMultipleInstances(

Inputarguments

control





unsigned int getMask,

ARNameList *instanceIds,


ARBooleanList *existList,

CMDBAttributeValueListList *attributeValueListList,




classNameId

The name of the class to retrieve. It is a two-part structure that contains the namespace and the classname.

datasetId


getMask


0: Based on the datasetId being passed, a list of instances are retrieved from either the overlay or the original dataset.

1: Allows you to retreive a list of instances from the current dataset only.

instanceIds

A list of instance IDs to retrieve.

attributeGetList

A list of attributes to retrieve.


A list of flags and corresponding Boolean values indicating whether the attribute list exists. The value TRUE indicates that the attribute list exists; FALSE indicates that the attribute list does not exist.

attributeValueListList

The list of attributeID and value pairs for instances to retrieve.

status


Functions � 133


CMDBGetInstanceBLOB

Description Retrieves the attachment, or binary large object (BLOB), stored for the attachment subclasses. The BLOB is placed in a file.



int CMDBGetInstanceBLOB(

Inputarguments

control


classNameId


datasetId


getMask










ARLocStruct *loc,




instanceId

The unique identifier for the instance.

attributeName

The name of the attribute that contains the attachment.

Return values loc

The location where the BLOB is stored.

status


CMDBGraphQuery

Description Searches related instances.



int CMDBGraphQuery(


CMDBClassNameId *startClassNameId,



ARNameType startExtensionId,

ARNameType startInstanceId,

int numLevels,

int direction,

ARBoolean noMatchProceed,

ARBoolean onMatchProceed,

CMDBGraphList *queryGraph,

CMDBGetObjectList *objects,

CMDBGetRelationList *relations,


Functions � 135


Inputarguments

control


startClassNameId

The name of the starting node class.

datasetId


getMask




startExtensionId

The extension ID of the starting CI node. This is required if the query graph contains the same class of CI more than once and needs to distinguish one from another.

startInstanceId

The ID of the starting node.

numLevels

The number of levels to traverse the specified queryGraph. The value A-1 specifies the graph query to traverse to the end of the graph.

direction

The direction in which the graph is to traverse.

CMDB_RELATIONSHIP_DIRECTION_OUT (0):

The node to be queried is on the right side of the relationship.

CMDB_RELATIONSHIP_DIRECTION_IN (1):

The node to be queried is on the left side of the relationship.



noMatchProceedT (1):

When the node returned for a given relationship instance does not match the criteria specified, proceed to the next relationship. Notice that, in this case, no relationship information will be returned because the returned components might not be connected, due to skipping the non-matching nodes.

F (0):

When the node returned for a given relationship instance does not match the criteria specified, do not proceed any further.

onMatchProceedT (1):

When the node returned for a given relationship instance matches the criteria specified, proceed to the next relationship.

F (0):

When the node returned for a given relationship instance matches the criteria specified, do not proceed any further.

queryGraph

The details of the information indicating the path that needs to be queried to return the desired CIs and relationships.

Return values objects

List of one or more CI instances matching the specified criteria. The starting node is not included.

relations

List of relationship instances matching the specified criteria that connects the CIs returned.

status


Functions � 137


CMDBSetInstance

Description Sets a CI or relationship instance in the OBJSTR:Class.



int CMDBSetInstance(

Inputarguments

control


classNameId


datasetId


instanceId

The unique identifier for the instance (system-generated).

attributeValueList

A list of one or more attribute value pairs (specified in any order) that identifies the data for the new attribute. You must specify values for all required subclasses that do not have defined defaults.









Values must be of the data type defined for the subclasses or have a data type of 0. NULL values can be specified for optional subclasses only. An error is generated if a subclasses does not exist or the user specified by the control parameter does not have write permission for a subclasses.



Bulk entry transaction functions

The bulk entry transaction functions invoke the bulk entry API functions. The C API bulk entry transaction functions include:

! CMDBBeginBulkEntryTransaction (page 139)

! CMDBEndBulkEntryTransaction (page 140)

CMDBBeginBulkEntryTransaction

Description Indicates that subsequent API functions are part of the bulk transaction. Any API calls that arrive after this function call are placed in a queue. Data model functions are not part of the bulk transaction.



int CMDBBeginBulkEntryTransaction(

Inputargument

control


Return value status




Functions � 139


CMDBEndBulkEntryTransaction

Description This function commits or rolls back the bulk transaction, depending on the action type. For an action type of SEND, the API call will be executed as part of the transaction. For an action type of CANCEL, the transaction will be canceled.



int CMDBEndBulkEntryTransaction(

Inputarguments

control


actionType

The type of action. Action type can be SEND or CANCEL.

Return values bulkEntryReturnList

Returns the status of the entry calls.

status



unsigned int actionType,

ARBulkEntryReturnList *bulkEntryReturnList,




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 Initializes the C API session. This function must be called before any C API calls are made.



int CMDBInitialization(

Inputarguments

control






Functions � 141


CMDBSystemInit

Description Performs server- and network-specific initialization operations for internal use by BMC.



int CMDBSystemInit(

Return values propList

A list of properties that need to be initialized.

status


CMDBSynchMetaData

Description Creates AR System forms from the data model definitions that hold instance data, and workflow, which enforces class hierarchy and data integrity.



int CMDBSynchMetaData(

ARPropList *propList,



ARNameType pendingId,

CMDBClassNameIdList *classNameIdList,




Inputarguments

control


pendingId

The ID of the object to be synchronized with the system.

Return values classNameIDList

The list of classes that are successfully synchronized with the system.

status


CMDBGetServerPort

Description Retrieves information about the server port.



int CMDBGetServerPort(

Inputarguments

control


Return values tcpPort

Retrieves the CMDB server TCP port information.


int *tcpPort,

int *rpcPort,


Functions � 143


rpcPort

Retrieves the CMDB server RPC port information.

status


CMDBSetServerPort

Description Sets the specified server port.



int CMDBSetServerPort(

Inputarguments

control


tcpPort

The TCP port number that your program will use to communicate with the AR System server. If you do not specify this parameter or provide 0 for the port number, your program will use the port number supplied by the portmapper. This parameter is overridden by the ARTCPPORT environment variable.

rpcPort

The RPC port number for the CMDB server. Specify 390697 to use the admin server. The default RPC port number is set to 390696.


int *tcpPort,

int *rpcPort,






CMDBTermination

Description Performs environment-specific cleanup routines and disconnects from the specified session. All API programs that interact with the C API session should call this function upon completing work in a given session.



int CMDBTermination(

Inputarguments

control






Functions � 145


User interface component functions

The user interface (UI) component functions work with components, such as tool tips, icons, and labelized strings. The C API includes the following user interface (UI) functions:

! CMDBGetCMDBUIComponents (page 146)

! CMDBRunQualificationForCI (page 147)

! CMDBExpandParametersForCI (page 148)

CMDBGetCMDBUIComponents

Description Retrieves a list of various UI components for a specified class.



int CMDBGetCMDBUIComponents(

Inputarguments

control

The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, locale, and server subclasses are required.

inputInfo

The qualification for the user interface component. You can specify information such as locale, classId, and tags to get the required UI component data. If there are no qualifications specified, all existing UI components will be returned.

instanceId

The unique identifier used to get component information for a specific instance.


CMDBUIComponentInfo *inputInfo,


CMDBUIComponentResultList *outputInfo,




Return Values outputInfo

The CMDBUIComponents result set for the specified qualifications.

status


CMDBRunQualificationForCI

Description Performs validation on a list of attributes for a specified CI. The CMDBRunQualificationForCI function takes qualification parameters in both structured and encoded modes.



int CMDBRunQualificationForCI(

Inputarguments

control


qualifier

A query that determines the set of CIs to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations.

attValueList

The list of attributes to validate.

Return Values passed

A Boolean value that specifies whether the qualification passed.



CMDBAttributeValueList *attValueList,

ARBoolean* passed,


Functions � 147


status


CMDBExpandParametersForCI

Description Accepts an unexpanded string that contains parameters and substitutes values from the attribute value list provided in the CMDBAttributeValueList structure.



int CMDBQualificationForCI(

Inputarguments

control


paramString

The string that contains the unexpanded parameters.

attValueList

The list of attribute values that will be used to expand the parameters.

Return Values expandedStr

The string that contains the expanded parameters.

status



char *paramString,

CMDBAttributeValueList *attValueList,

char **expandedStr,




Import and Export functions

The export and import functions enable you to export or import CMDB data. 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 Exports the specified class definitions from the specified server. This function is deprecated in the 2.0 release of the BMC Atrium CMDB.



int CMDBExport(

Inputarguments

control


exportItemList

The list of items to export.


CMDBExportItemList *exportItemList,

unsigned int exportFormat,

char *directoryPath,


Functions � 149


exportFormat

The format of the export. The default export format is set to CMDB_EXPORT_FORMAT_XML.

directoryPath

The directory in which the exported file is to be stored.



CMDBExportDef

Description Exports a list of specified class definitions.



int CMDBExportDef(

Inputarguments

control


exportItemList

A list of zero or more classes or attributes to export.

Return values exportBuf

The exported buffer which contains the class definitions in XML format.


CMDBExportItemList *exportItemList,

char *exportBuf,




status


CMDBExportData

Description Exports the specified class data for a specific qualification.



int CMDBExportData(

Inputarguments

control


qualifier

A query that determines the set of classes or attributes to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations.

attributeGetList

The list of attributes names to retrieve.

sortList

A list of zero or more fields that identifies the sort order for the exported data. Specify a NULL value for this parameter to use no specific sort order.


ARQualifierStruct *qualifier,





char *exportBuf,


Functions � 151


firstRetrieve

The first instance to retrieve. A value of 0 (CMDB_START_WITH_FIRST_INSTANCE)represents the first entry and is the default value if no value is set.

maxRetrieve

The maximum number of instances to retrieve. Use this parameter to limit the instances returned in the query if the qualification does not sufficiently narrow the list. Specify 0 (CMDB_NO_MAX_LIST_RETRIEVE) to assign no maximum instances.

Return values exportBuf

The exported buffer, which contains the class data in an XML format.

status


CMDBImport

Description Imports the specified class definitions to the specified server. Use this function to copy structure definitions from one server to another. This function is deprecated in the 2.0 release of the BMC Atrium CMDB.



int CMDBImport(

Inputarguments

control



CMDBImportItemList *importItemList,

char *directoryPath,




importItemList

A list of zero or more items to import.

directoryPath

The directory where the contents of the exported file are available for importing.



CMDBImportDef

Description Imports a list of specified class definitions.



int CMDBImportDef(

Inputarguments

control


importItemList

A list of zero or more items to import. Specify NULL for this parameter to import all definitions in the import buffer.

importOption

A value indicating whether to replace class definitions being imported if they already exist. If an import item already exists, the function generates an error.


CMDBXMLImportItemList *importItemList,

unsigned int importOption,

char *importBuf,


Functions � 153


1: Generate an error if an item to import already exists

CMDB_DEF_IMPORT_OPT_CREATE.

2: Overwrite if an item to import already exists

CMDB_DEF_IMPORT_OPT_OVERWRITE.

importBuf

The import buffer that contains the class definitions to import in XML format.



CMDBImportData

Description Imports the specified instance data.



int CMDBImportData(

Inputarguments

control


importOption

A value indicating the options available for handling duplicates found during the importing of instance data. These options are mutually exclusive.

1: Generate an error

(CMDB_DATA_IMPORT_OPT_ERROR_FOR_DUP).


unsigned int importOption,

char *importBuf,




2: Create an instance with a new instance ID if the instance ID already exists

(CMDB_DATA_IMPORT_OPT_NEWID_FOR_DUP).

3: Update the existing instance if the instance ID specified already exists

(CMDB_DATA_IMPORT_OPT_MERGE_FOR_DUP).

4: Create a new instance ID for all the imported instances, including those instances that are not duplicates.

(CMDB_DATA_IMPORT_OPT_NEWID_FOR_ALL).

importBuf

The import buffer, which contains the class data to import in XML format.



Utility functions

The utility functions enable you to use CMDB utilities such as export, import, and generate globally unique identifiers (GUIDs). The C API includes the following utility functions:

! CMDBCreateGuid (page 155)

! CMDBGetVersions (page 156)

CMDBCreateGuid

Description Creates a globally unique identifier.



int CMDBCreateGuid(

ARGuid guid,


Functions � 155


Return values guid

The unique identifier (system-generated).

status


CMDBGetVersions

Description Retrieves the version information for any BMC Atrium CMDB component that is installed.


Synopsis #include "ar.h"#include "arextern.h"

int CMDBGetVersions(

Inputarguments

control


appIdList

A list of application IDs for which the version information is required. Specify a NULL value in this argument to get version information of all the existing applications.


A list of TRUE or FALSE values. Each value in this list denotes whether the corresponding application IDs in the supplied appIdList exists.

versionInfoList

A list of BMC Atrium CMDB version structures.


ARNameList *appIdList

ARBooleanList *existList

CMDBVersionInfoList *versionInfoList




status


Free functions

The free functions release the memory allocated to a specified function. 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


FreeCMDBVersionInfoList

Description Releases the memory space allocated to the CMDBVersionInfoList structure.


Synopsis #include "ar.h"#include "arfree.h"#include "cmdbfree.h"

FreeCMDBVersionInfoList(

Inputarguments

value

A pointer to the CMDBVersionInfoList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct

A flag indicating if the top-level structure is to be released. The value TRUE indicates to release the allocated memory for the top-level structure; FALSE indicates to free only the contents of the structure.

FreeCMDBClassNameIdList

Description Releases the memory space allocated to the CMDBClassNameIdList structure.



FreeCMDBClassNameIdList(

Inputarguments

value

A pointer to the CMDBClassNameIdList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

CMDBVersionInfoList *value,

ARBoolean freestruct)

CMDBClassNameIdList *value,




freeStruct


FreeCMDBAttributeLimit

Description Releases the memory space allocated to the CMDBAttributeLimit structure.



FreeCMDBAttributeLimit(

Inputarguments

value

A pointer to the CMDBAttributeLimit structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBAttributeLimitStruct

Description Releases the memory space allocated to the CMDBAttributeLimitStruct structure.



FreeCMDBAttributeLimitStruct(

CMDBAttributeLimit *value,


CMDBAttributeLimit *value,


Functions � 159


Inputarguments

value

A pointer to the CMDBAttributeLimitStruct structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBAttributeLimitList

Description Releases the memory space allocated to the CMDBAttributeLimitList structure.



FreeCMDBAttributeLimitList(

Inputarguments

value

A pointer to the CMDBAttributeLimitList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


CMDBAttributeLimitList *value,




FreeCMDBIndexList

Description Releases the memory space allocated to the CMDBIndexList structure.



FreeCMDBIndexList(

Inputarguments

value

A pointer to the CMDBIndexList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBExportItemStruct

Description Releases the memory space allocated to the CMDBExportItemStruct structure.



FreeCMDBExportItemStruct(

Inputarguments

value

A pointer to the CMDBExportItemStruct structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

CMDBIndexList *value,


CMDBExportItemStruct *value,


Functions � 161


freeStruct


FreeCMDBExportItemList

Description Releases the memory space allocated to the CMDBExportItemList structure.



FreeCMDBExportItemList(

Inputarguments

value

A pointer to the CMDBExportItemList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBImportItemList

Description Releases the memory space allocated to the CMDBImportItemList structure.



FreeCMDBImportItemList(

CMDBExportItemList *value,


CMDBImportItemList *value,




Inputarguments

value

A pointer to the CMDBImportItemList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBAttributeGetStruct

Description Releases the memory space allocated to the CMDBAttributeGetStruct structure.



FreeCMDBAttributeGetStruct(

Inputarguments

value

A pointer to the CMDBAttributeGetStruct structure that you want to free. The system does not perform an operation if the structure is a list with zero items or if you specify NULL for this parameter.

freeStruct

A flag indicating whether you need to free the top-level structure. If you allocated memory for the top-level structure, specify 1 (TRUE) to free both the structure and its contents. If you used a stack variable for the top-level structure, specify 0 (FALSE) to free only the contents of the structure.

CMDBAttributeGetStruct *value,


Functions � 163


FreeCMDBGraphAdjacentStruct

Description Releases the memory space allocated to the CMDBGraphAdjacentStruct structure.



FreeCMDBGraphAdjacentStruct(

Inputarguments

value

A pointer to the CMDBGraphAdjacentStruct structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBGraphAdjacentList

Description Releases the memory space allocated to the CMDBGraphAdjacentList structure.



FreeCMDBGraphAdjacentList(

CMDBGraphAdjacentStruct *value,


CMDBGraphAdjacentList *value,




Inputarguments

value

A pointer to the CMDBGraphAdjacentList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBGraphStruct

Description Releases the memory space allocated to the CMDBGraphStruct structure.



FreeCMDBGraphStruct(

Inputarguments

value

A pointer to the CMDBGraphStruct structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


CMDBGraphStruct *value,


Functions � 165


FreeCMDBGraphList

Description Releases the memory space allocated to the CMDBGraphList structure.



FreeCMDBGraphList(

Inputarguments

value

A pointer to the CMDBGraphList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBClassTypeInfo

Description Releases the memory space allocated to the CMDBClassTypeInfo structure.



FreeCMDBClassTypeInfo(

Inputarguments

value

A pointer to the CMDBClassTypeInfo structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

CMDBGraphList *value,


CMDBClassTypeInfo *value,




freeStruct


FreeCMDBQualifierStruct

Description Releases the memory space allocated to the CMDBQualifierStruct structure.



FreeCMDBQualifierStruct(

Inputarguments

value

A pointer to the CMDBQualifierStruct structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBGetRelationList

Description Releases the memory space allocated to the CMDBGetRelationList structure.



FreeCMDBGetRelationList(

CMDBQualifierStruct *value,


CMDBGetRelationList *value,


Functions � 167


Inputarguments

value

A pointer to the CMDBGetRelationList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBGetObjectList

Description Releases the memory space allocated to the CMDBGetObjectList structure.



FreeCMDBGetObjectList(

Inputarguments

value

A pointer to the CMDBGetObjectList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


CMDBGetObjectList *value,




FreeCMDBAttributeValueList

Description Releases the memory space allocated to the CMDBAttributeValueList structure.



FreeCMDBAttributeValueList(

Inputarguments

value

A pointer to the CMDBAttributeValueList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBAttributeValueListList

Description Releases the memory space allocated to the CMDBAttributeValueListList structure.



FreeCMDBAttributeValueListList(

CMDBAttributeValueList *value,


CMDBAttributeValueListList *value,


Functions � 169


Inputarguments

value

A pointer to the CMDBAttributeValueListList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


FreeCMDBSortList

Description Releases the memory space allocated to the CMDBSortList structure.



FreeCMDBSortList(

Inputarguments

value

A pointer to the CMDBSortList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


CMDBSortList *value,




FreeCMDBREJobRunInfoList

Description Releases the memory space allocated to the CMDBREJobRunInfoList structure.



FreeCMDBREJobRunInfoList(

Inputarguments

value

A pointer to the CMDBREJobRunInfoList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.

freeStruct


CMDBREJobRunInfoList *value,


Functions � 171


Reconciliation Engine functions

The Reconciliation Engine functions manipulate Reconciliation Engine jobs. 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. Before starting a job, make sure the job is defined and exists in an Active state. If no job for the specified job name exists, or the job is not Active, the CMDBStartJobRun function returns an error. Only one instance of the same job can be executed at a given time.



int CMDBStartJobRun(

Inputarguments

control


jobName

The name of the reconciliation job.


ARNameType jobName,

CMDBClassQualList *classQualList,

CMDBREDatasetList *datasetList

ARNameType jobRunId,




classQualList

The list of class qualifications.

datasetList

The list of Reconciliation Engine dataset pair.

Return values jobRunId

A unique job identifier.

status


CMDBGetJobRun

Description Gets information about the currently running reconciliation job and retrieves a job log.



int CMDBGetJobRun(

Inputarguments

control


jobRunId




ARREJobRunInfoStruct *jobRunInfo,

char **jobRunLog


Functions � 173


Return values jobRunInfo

The job run information to retrieve.

jobRunLog

The job run log to retrieve.

status


CMDBGetListJobRun

Description Get a list of running Reconciliation Engine jobs. The job list will be retrieved based on the qualification passed to the function.



int CMDBGetListJobRun(

Inputarguments

control


jobQualifier

A query that determines the set of entries to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations. The following qualifiers are currently supported:

Run Status*, Run Start Time, Run End Time, Job Instance ID*, Job Run ID, and Submitter.


CMDBQualifierStruct *jobQualifier,

ARREJobRunInfoList *jobRunInfoList,





Return values jobRunInfoList

The list of running jobs that match the qualification criteria.

numMatches

The total number of jobs that match the qualification criteria.

status


CMDBCancelJobRun

Description Cancels a currently running Reconciliation Engine job. Depending on the system resources, Reconciliation Engine might cancel a job with a certain delay.



int CMDBCancelJobRun(

Inputarguments

control


jobRunId







Functions � 175


Federation functions

The federation functions manipulate federated data for an instance. The C API functions for federation include:

! CMDBGetRelatedFederatedInContext (page 176)

! CMDBActivateFederatedInContext (page 177)

CMDBGetRelatedFederatedInContext

Description Returns related FederatedInterface instances for a specific CI (context).



int CMDBGetRelatedFederatedInContext(

Inputarguments

control


classNameId

The class name of the specified instance for which federated instances are to be retrieved.

datasetId

The dataset ID of the instance to retrieve.






ARNameList *instanceIdList,

CMDBAttributeValueListList *attrValueListList,

ARStatusList *status



instanceId

The instance ID of the specific instance for which federated instances are to be retrieved.

attributeGetList

The list of attribute names to retrieve.


The list of instance GUIDs.

attrValueListList

The list of attribute value list.

status


CMDBActivateFederatedInContext

Description Expands the FederatedInterface instance for a specific CI and federated interface. Depending on a flag you specify when you call this function, your federated instance might either be only expanded, or expanded and launched.



int CMDBActivateFederatedInContext(





ARNameType federatedInstanceId,

unsigned int activateOption,

CMDBFederatedActivateInfo *federatedInfo,

ARStatusList *status

Functions � 177


control


classNameId

The class name of the specified CI for which the federated instance is to be expanded or launched.

datasetId

The unique identifier for the dataset. The data in the return values are based on the dataset ID specified.

instanceId

The instance ID of the specified instance for which the federated instance is to be expanded or launched.

federatedInstanceId

The instance ID of the federated instance that is to be expanded or launched.

activateOption

The mask number that indicates if the federated instance is to be launched and expanded.

CMDB_FEDERATION_ACTIVATION_NONE 0:

Activate none.

CMDB_FEDERATION_ACTIVATION_EXPAND 1 << 0:

Only activate, no launch.

CMDB_FEDERATION_ACTIVATION_LAUNCH 1 << 1:

Activate and launch.

Return values federatedInfo

The expanded federated instance information. This parameter is returned only if you specify a value of 1in the activateOption parameter.

status




Audit functions

The audit functions retrieve audit data for a class. 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. The audit option must be set for the attribute’s characteristic to get the audit data.



int CMDBGetCopyAuditData(

control





ARTimestamp auditTimestamp,






CMDBAuditValueListList *auditValueListList,



Functions � 179


classNameId

The class name (class name and namespace combination) of the specified CI instance for which a copy of the audit data is to be retrieved.

instanceId

The instance ID of the specified CI instance for which a copy of the audit data is to be retrieved.

auditTimestamp

The data and time information for the instance. The CI instances with the data and time greater than or equal to the auditTimestamp will be retrieved. If auditTimestamp is 0, then all the audit data is retrieved.

qualifier

A query that determines the set of CI instances to retrieve. The qualification can include one or more attributes and any combination of conditional, relational, and arithmetic (numeric data types only) operations.

attributeGetList

A list of attribute names for which the audit data is to be retrieved.

sortList

The sort order for the attributes.

firstRetrieve

The first instance to retrieve for the qualification. CMDB_START_WITH_FIRST_ENTRY represents the first entry and is the default value if the value is not set.

maxRetrieve

The maximum number of entries to retrieve for the qualification. Use this parameter to limit the amount of data returned if the query does not narrow the list. Specify CMDB_NO_MAX_LIST_RETRIEVE to assign no maximum.

Return values auditValueListList

The list of values for the specified attributes. If the audit option at the CI class-level is disabled, an error is returned.

numMatches

The number of CI instance entries that matched the specified qualification.



status


CMDBGetLogAuditData

Description Retrieves the audit log for the specified CI instance. For you to retrieve the audit log, the AuditLog option must be set at the class-level.



int CMDBGetLogAuditData(

control


classNameId

The class name (class name and namespace combination) of the specified CI instance for which the audit log is to be retrieved.

instanceId

The instance ID of the specified CI instance for which the audit log is to be retrieved.

Return values auditLog

The audit log information for the specified instance.

status





ARTextString *auditLog,


Functions � 181


Data structures

The C API data structures are categorized by function types, such as class functions and attribute functions. The data structures categories include Class, Attributes, General purpose, Graph Query, Export and Import, and Reconciliation Engine structures.

Class structures

Class structures are data structures for CI and relationship definitions (data model). 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.

typedef struct CMDBClassTypeInfo{ unsigned int classType; union { CMDBClassRelationship relationshipInfo; } u;} CMDBClassTypeInfo;

The CMDBClassTypeInfo structure consists of the following elements:

classType An integer value identifying the type for a class.

1—The class type is regular. (CMDB_CLASS_TYPE_REGULAR).

2—The class type is relationship. (CMDB_CLASS_TYPE_RELATIONSHIP).

relationshipInfo If the class type specified in the classType parameter is relationship, then the relationship information is retrieved.



CMDBClassRelationship

The CMDBClassRelationship structure is used to hold the relationship information of the CI classes.

typedef struct CMDBClassRelationship{ CMDBClassNameID relClassNames[2]; ARNameType roleNames[2]; unsigned int cardinality; ARBoolean isRole2WeakReference; CMDBWeakPropagatedAttrsList weakPropagatedAttrsList; ARBoolean cascadeDelete;

} CMDBClassRelationship;

The CMDBClassRelationship structure consists of the following elements:

relClassNames[2] The names of the two classes that are a part of the relationship.

roleNames[2] The role names for the two classes that are a part of the relationship.

cardinality An integer identifying the cardinality of the relationship between the related classes:

1—One-to-one, one instance of a class is associated with a single instance of another class (CMDB_CLASS_RELATIONSHIP_CARDINALITY_1).

2—Many-to-one, one or more instances of a class are associated with one instance of another class (CMDB_CLASS_RELATIONSHIP_CARDINALITY_MANY_1).

3—One-to-many, one instance of a class is associated with one or more instances of another class (CMDB_CLASS_RELATIONSHIP_CARDINALITY_1_MANY).

4—Many-to-many, many instances of a class are associated with many instances of another class (CMDB_CLASS_RELATIONSHIP_CARDINALITY_MANY_MANY).

isRole2WeakReference A Boolean value indicating whether role 2 is a weak reference:

TRUE—The role 2 class is a weak reference. Role 2 is a weak entity and it uses role 1’s primary key as part of its own key. If the value is TRUE, cardinality must be one-to-one or many-to-many.

FALSE—The role 2 class is not a weak reference.

Data structures � 183


CMDBIndexList

The CMDBIndexList structure is used to hold index information for the class.

typedef struct CMDBIndexList{ unsigned int numItems; CMDBIndexStruct *indexList;} CMDBIndexList;

The CMDBIndexList structure consists of the following elements:

weakPropagatedAttrsList If the value of isRole2WeakReference is TRUE, indicates the list of attributes that are propagated from the role 1 class to the role 2 class.

cascadeDelete A Boolean value indicating the type of delete allowed between the related classes:

TRUE—A cascade delete is allowed. Deleting an instance in one class also deletes the instance in the related class.

FALSE—A cascade delete is not allowed.

Note: This item is applicable only for one-to-one and one-to-many relationships.

numItems An integer value indicating the number of CMDBIndexStruct items in the list.

indexList The set of zero or more CMDBIndexStruct items defined for the class. Each index can include from 1 to 16 attributes (limited by AR_MAX_INDEX_subclasses). Diary attributes and character attributes larger than 255 bytes cannot be indexed.



CMDBIndexStruct

The CMDBIndexStruct structure is used to hold the attributes to index.

typedef struct CMDBIndexStruct{ unsigned int numAttributes; ARNameType attributeName[AR_MAX_INDEX_subclasses]; ARBoolean unique; ARBoolean isPrimaryKey;

ARNameType indexName;} CMDBIndexStruct;

The CMDBIndexStruct structure consists of the following elements:

numAttributes An integer value indicating the number of attributes to index.

attributeName The names of attributes to index.

unique A Boolean value indicating if the index key must be unique:

TRUE—The index key is unique.

FALSE—The index key is not unique.

isPrimaryKey A Boolean value indicating whether to make this index a primary key index:

TRUE—The index key is a primary key index.

FALSE—The index key is not a primary key index.

indexName The name of the index.



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.

typedef struct CMDBAttributeGetStruct{ unsigned int type; union { ARNameList attributeNameList; } u;} CMDBAttributeGetStruct;

The CMDBAttributeGetStruct structure consists of the following elements:

type An integer value indicating the type of attributes to retrieve.

1—Retrieve all attributes in attributeNameList (CMDB_GET_ATTR_CUSTOM_LIST).

2—Retrieve all attributes except hidden attributes (CMDB_GET_ATTR_NONHIDDEN).

3—Retrieve all attributes (CMDB_GET_ATTR_ALL).

attributeNameList The name of the attribute list.



CMDBAttributeLimitList

The CMDBAttributeLimitList structure is used to hold a list of data limit definitions for attributes.

typedef struct CMDBAttributeLimitList{ unsigned int numItems; CMDBAttributeLimit *limitList;} CMDBAttributeLimitList;

The CMDBAttributeLimitList structure consists of the following elements:

CMDBAttributeLimit

The CMDBAttributeLimit structure is used to hold the data limit definitions for an attribute list of any data type.

typedef struct CMDBAttributeLimit{ unsigned int dataType; union { struct { int rangeLow; int rangeHigh; } integerLimits; struct { int maxLength; char *format; unsigned int menuStyle; ARNameType charMenu; char *pattern; unsigned int qbeMatchOperation; } charLimits; struct { double rangeLow; double rangeHigh; int precision; } realLimits; struct { char *rangeLow;

numItems An integer value indicating the number of CMDBAttributeLimit items in the list.

limitList The list of attribute limit items that hold the limit definitions for the attribute.



char *rangeHigh; int precision; } decimalLimits; struct { int minDate; int maxDate; } dateLimits; struct { unsigned int listStyle; union { ARNameList regularList; AREnumItemList customList; } u; } enumLimits; struct { char *rangeLow; char *rangeHigh; int precision;

ARCurrencyDetailList functionalCurrencies; ARCurrencyDetailList allowableCurrencies; } currencyLimits; struct { unsigned long maxSize; ARNameType attachmentPoolName; } attachLimits; } u;}CMDBAttributeLimit;

The CMDBAttributeLimit structure consists of the following element:

dataType An integer value indicating the data type of the value being passed. The following table describes the possible values.

0 CMDB_ATTR_DATA_TYPE_NULL Specifies a NULL value.

1 CMDB_ATTR_DATA_TYPE_KEYWORD An integer identifying the particular keyword (defined in cmdb.h).

2 CMDB_ATTR_DATA_TYPE_INTEGER A 32-bit signed integer value.

3 CMDB_ATTR_DATA_TYPE_REAL A 64-bit floating-point value.



4 CMDB_ATTR_DATA_TYPE_CHAR A null-terminated string that requires freeing allocated space. A NULL pointer of this type is equivalent to CMDB_ATTR_DATA_TYPE_NULL.

5 CMDB_ATTR_DATA_TYPE_DIARY A null-terminated string that requires freeing allocated space. A NULL pointer of this type is equivalent to CMDB_ATTR_DATA_TYPE_NULL.

6 CMDB_ATTR_DATA_TYPE_ENUM A set of integer values (beginning with zero) that represent possible selection values as an indexed list. You must specify an attribute limit by using ARNameList to define string values for each selection.

7 CMDB_ATTR_DATA_TYPE_TIME A UNIX-style date and time stamp (number of seconds since midnight January 1, 1970).

10 CMDB_ATTR_DATA_TYPE_DECIMAL A fixed-point decimal attribute. Values must be specified in C locale, for example, 1234.56.

11 CMDB_ATTR_DATA_TYPE_ATTACH An attachment attribute.

12 CMDB_ATTR_DATA_TYPE_CURRENCY A currency attribute.

13 CMDB_ATTR_DATA_TYPE_DATE A Julian date number (number of days since January 1, 4713 BC).

14 CMDB_ATTR_DATA_TYPE_TIME_OF_DAY The number of seconds since 12:00 a.m. of the current day.

37 CMDB_ATTR_DATA_TYPE_ATTACH_POOL A pool for grouping attachments.



Defining integer limits

The integerLimits structure is used to hold data limit definitions for the integer data type. It consists of the following elements:

Defining character limits

The charLimits structure is used to hold data limit definitions for the character data type. It consists of the following elements:

Defining real limits

The realLimits structure is used to hold data limit definitions for the real data type. It consists of the following elements:

Defining decimal limits

The decimalLimits structure is used to hold data limit definitions for the decimal data type. It consists of the following elements:

rangeLow The low range of the custom characteristic for the integer data type.

rangeHigh The high range of the custom characteristic for the integer data type.

maxLength The maximum length of the custom characteristic for the character data type.

format Used for character list data, specified as L<n>, where n is the number of items in the list. L4, for example, indicates a list of a maximum of 4 items, with each item separated by a semicolon (;). NULL indicates a list is not used.

rangelow The low range of the custom characteristic for the real data type.

rangeHigh The high range of the custom characteristic for the real data type.

precision The number of integers allowed for the real data type.

rangelow The low range of the custom characteristic for the decimal data type.

rangeHigh The high range of the custom characteristic for the decimal data type.

precision The number of integers allowed for the decimal data type.



Defining date limits

The dateLimits structure is used to hold data limit definitions for the date data type. It consists of the following elements:

Defining enum limits

The enumLimits structure is used to hold data limit definitions for the enum data type. It consists of the following element:

Defining currency limits

The currencyLimits structure is used to hold data limit definitions for the currency data type. It consists of the following elements:

Defining attachment limits

The attachLimits structure is used to hold data limit definitions for the attachment data type. It consists of the following elements:

minDate The minimum limit for the date data type.

maxDate The maximum limit for the date data type.

regularList A name list of possible selection values for the enum data type.

rangelow The low range of the custom characteristic for the currency data type.

rangeHigh The high range of the custom characteristic for the currency data type.

precision The number of integers allowed to the right of the decimal point for the currency data type.

functionalCurrencies Default list of functional currencies when new currency attributes are created.

allowableCurrencies Default list of allowable currencies when new currency attributes are created.

maxSize The maximum size in bytes of an attachment data type. A value of 0 (zero) represents an unlimited size.

attachmentPoolName The name of the attachment pool attribute this attachment attribute is associated with.



CMDBAttributNameId

The CMDBAttributeNameId structure is used to hold the namespace name and the class name information for a class.

typedef struct CMDBAttributeNameId{ ARNameType namespaceName; ARNameType className; ARNameType attributeName;} CMDBAttributeNameId;

The CMDBAttributeNameId structure consists of the following elements:

CMDBAttributeValueList

The CMDBAttributeValueList structure holds a list of values for an attribute.

typedef struct CMDBAttributeValueList{ unsigned int numItems; CMDBAttributeValueStruct *attributeValueList;} CMDBAttributeValueList;

The CMDBAttributeValueList structure consists of the following elements:

namespaceName The namespace name for the class.

className The name of the class.

attributeName The name of the attribute.

numItems An integer value indicating the number of CMDBAttributeValueStruct items in the list.

attributeValueList A list of CMDBAttributeValueStruct items.



CMDBAttributeValueListList

The CMDBAttributeValueListList structure holds a list of values for an attributes list.

typedef struct CMDBAttributeValueListList{ unsigned int numItems; CMDBAttributeValueList *attributeValueListList;} CMDBAttributeValueListList;

The CMDBAttributeValueListList structure consists of the following elements:

CMDBAttributeValueStruct

The CMDBAttributeValueStruct structure is used to hold values for attributes.

typedef struct CMDBAttributeValueStruct{ ARNameType attributeName; ARValueStruct attributeValue;} CMDBAttributeValueStruct;

The CMDBAttributeValueStruct structure consists of the following elements:

numItems An integer value indicating the number of CMDBAttributeValueList items in the list.

attributeValueListList A list of CMDBAttributeValueList items.

attributeName The name of the attribute.

attributeValue The value of the attribute.



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.

The specified source and target attributes must already exist on the role one and role two classes. This list describes a mapping of which attribute values from the role one class will be propagated to the role two class.

typedef struct CMDBWeakPropagatedAttrs{ ARNameType sourceAttributeName; ARNameType targetAttributeName;} CMDBWeakPropagatedAttrs;

The CMDBWeakPropagatedAttrs structure consists of the following elements:

CMDBWeakPropagatedAttrsList

The CMDBWeakPropagatedAttrsList structure is used to hold a list of CMDBWeakPropagatedAttrs structures.

typedef struct CMDBWeakPropagatedAttrsList{ unsigned int numItems; CMDBWeakPropagatedAttrs *attrsList;

} CMDBWeakPropagatedAttrsList;

The CMDBWeakPropagatedAttrsList structure consists of the following elements:

sourceAttributeName The name of the attribute on the role one class.

targetAttributeName The name of the attribute on the role two class.

numItems An integer value indicating the number of CMDBWeakPropagatedAttrs items in the list.

attrsList The list of attributes to propagate from the role one class to the role two class.



CMDBSortList

The CMDBSortList structure is used to hold a list of attributes to sort.

typedef struct CMDBSortList{ unsigned int numItems; CMDBSortStruct *sortList;} CMDBSortList;

The CMDBSortList structure consists of the following elements:

CMDBSortStruct

The CMDBSortStruct structure is used to hold the attribute to sort.

typedef struct CMDBSortStruct{ ARNameType attributeName; unsigned int sortOrder;} CMDBSortStruct;

The CMDBSortStruct structure consists of the following elements:

numItems An integer value indicating the number of CMDBSortStruct items in the list.

sortList A list of CMDBSortStruct items.

attributeName The name of the attribute to sort.

sortOrder An integer value indicating sort order.

1—Sort attributes in ascending order (CMDB_SORT_ASCENDING).

2—Sort attributes in descending order (CMDB_SORT_DESCENDING).



Instance structures

Instance structures are data structures for instance data. 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.

typedef struct CMDBClassNameId{ ARNameType namespaceName; ARNameType className;} CMDBClassNameId;

The CMDBClassNameId structure consists of the following elements:

CMDBClassNameIdList

The CMDBClassNameIdList structure is used to hold a list of CMDBClassNameId structures.

typedef struct CMDBClassNameIdList{ unsigned int numItems; CMDBClassNameId *classNameIdList;} CMDBClassNameIdList;

The CMDBClassNameIDList structure consists of the following elements:

namespaceName The namespace name of the class.


numItems An integer value indicating the number of CMDBClassNameIditems in the list.

classNameIdList The list of class names.



CMDBQualifierStruct

The CMDBQualifierStruct structure is used to hold the qualifier string based on the qualifier type that is provided.

typedef struct CMDBQualifierStruct{ unsigned int qualifierType; union { char *qualifierString; ARQualifierStruct qualifierStruct; } u;} CMDBQualifierStruct;

The CMDBQualifierStruct structure consists of the following elements:

qualifierType An integer value indicating the type of qualifier.

1—The qualifier is a string (CMDB_QUALIFIER_TYPE_STRING).

2—The qualifier is a structure (CMDB_QUALIFIER_TYPE_STRUCT).

qualifierString The qualification in string format. The qualification string can include one or more attributes and any combination of conditional, relational, and arithmetic (numeric data types only) operations.

qualifierStruct The qualification in structure format.



General purpose structures

General purpose structures are structures for miscellaneous uses. 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 CMDBVersionInfo{ ARNameType applicationId; ARNameType applicationName; unsigned int majorVer; unsigned int minorVer; unsigned int maintenanceVer; unsigned int patchNum;} CMDBVersionInfo;

The CMDBVersionInfo structure consists of the following elements:

CMDBVersionInfoList

The CMDBVersionInfoList structure is used to hold a list of version information elements for the CMDB component.

typedef struct CMDBVersionInfoList{ unsigned int numItems; CMDBVersionInfo *versionInfoList;} CMDBVersionInfoList;

applicationId An ID for the application.

applicationName The name for the application.

majorVer The major part (preceding the dot) of the version number information.

minorVer The minor part (succeeding the dot) of the version number information.

maintenanceVer The maintenance version number.

patchNum The patch number.



The CMDBVersionInfoList structure consists of the following elements:

Export and import structures

Export/Import structures are used for export and import functions. 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.

typedef struct CMDBItemTypeClass{ CMDBClassNameId classNameId;}CMDBItemTypeClass;

The CMDBItemTypeClass structure consists of the following elements:

numItems The number of items in the list.

versionInfoList A list of version information.

classNameId The ID for the class.



CMDBItemTypeAttribute

The CMDBItemTypeAttribute data structure is used to hold a list of attribute information.

typedef struct CMDBItemTypeAttribute{ CMDBClassNameId classNameId; ARNameList attribNameList;}CMDBItemTypeAttribute;

The CMDBItemTypeAttribute structure consists of the following elements:

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.0 release of the BMC Atrium CMDB.

typedef CMDBExportItem{ unsigned int itemType; union { CMDBItemTypeClass classItem; CMDBItemTypeAttribute attributeItem; }}CMDBExportItem;

The CMDBExportItem structure consists of the following elements:

classNameId The ID of the class name.

attributeNameList The list of attribute names.

itemType The type of item to export.

0—No item to export

(CMDB_ITEM_TYPE_NONE).

1—Export class

(CMDB_ITEM_TYPE_CLASS).

2—Export attribute

(CMDB_ITEM_TYPE_ATTRIBUTE).

classItem The class items to import, if the itemType is CMDB_ITEM_TYPE_CLASS.

attributeItem The attribute items to import, if the itemType is CMDB_ITEM_TYPE_ATTRIBUTE.



CMDBExportItemList

The CMDBExportItemList data structure is used to hold a list of CMDBExportItemStruct structures. This data structure is deprecated in the 2.0 release of the BMC Atrium CMDB.

typedef struct CMDBExportItemList{ unsigned int numItems; CMDBExportItemStruct *exportItemList;} CMDBExportItemList;

The CMDBExportItemList structure consists of the following elements:

CMDBXMLExportItemList

The CMDBXMLExportItemList data structure is used to hold a list of items to export.

typedef struct CMDBXMLExportItemList

unsigned int numItems; CMDBXMLExportItemStruct *exportItemList;}CMDBXMLExportItemList;

The CMDBXMLExportItemList structure consists of the following elements:

CMDBExportItemStruct

The CMDBExportItemStruct data structure is used to hold a single item to export. This data structure is deprecated in the 2.0 release of the BMC Atrium CMDB.

typedef struct CMDBExportItemStruct{ unsigned int itemType; CMDBClassNameId classNameId; union { char *qualifier; unsigned long exportOption; } u;} CMDBExportItemStruct;

numItems An integer value indicating the number of CMDBExportItemStruct items in the list.

exportItemList The list of items to export.

numItems An integer value indicating the number of CMDBXMLExportItem items in the list.

exportItemList A structure that holds the list of items to export.



The CMDBExportItemStruct structure consists of the following elements:

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.0 release of the BMC Atrium CMDB.

typedef CMDBImportItem{ unsigned int itemType; union { CMDBItemTypeClass classItem; CMDBItemTypeAttribute attributeItem; }}CMDBImportItem;

itemType An integer value indicating the type of information to export.

1—Export (CMDB_ITEM_TYPE_META_DATA).

2—Export instance data. (CMDB_ITEM_TYPE_INSTANCE_DATA).

classNameId The namespace name and the class name of the class that contains the items to export.

qualifier A query that determines the set of entries to export. The qualification can include one or more attributes and any combination of conditional, relational, and arithmetic (numeric data types only) operations.

This item is applicable only if CMDB_ITEM_TYPE_INSTANCE_DATA is set.

exportOption An integer value indicating the type of classes to export. To use more than one export option, add the value for each option. For example, 3 indicates the class and superclasses will be exported.

1—Export the class only (CMDB_EXPORT_OPTION_CLASS_ONLY).

2—Export superclasses (CMDB_EXPORT_OPTION_SUPER_CLASSES).

4—Export subclasses (CMDB_EXPORT_OPTION_SUB_CLASSES).

Note: This item is applicable only if CMDB_ITEM_TYPE_META_DATA is set.



The CMDBImportItem structure consists of the following elements:

CMDBImportItemList

The CMDBImportItemList data structure is used to hold a list of items to import. This data structure is deprecated in the 2.0 release of the BMC Atrium CMDB.

typedef struct CMDBImportItemList{ unsigned int numItems; CMDBImportItemStruct *importItemList;} CMDBImportItemList;

The CMDBImportItemList structure consists of the following elements:

CMDBXMLImportItemList

The CMDBXMLImportItemList data structure is used to hold a list of XML items to import.

typedef struct CMDBXMLImportItemList

unsigned int numItems; CMDBXMLImportItemStruct *importItemList;}CMDBXMLImportItemList;

itemType The type of item to import.

0—No item to import

(CMDB_ITEM_TYPE_NONE).

1—Import class

(CMDB_ITEM_TYPE_CLASS).

2—Import attribute

(CMDB_ITEM_TYPE_ATTRIBUTE).

classItem The class item to import.

attributeItem The attribute item to import.

numItems An integer value indicating the number of CMDBImportItemStruct items in the list.

importItemList A structure that holds the list of items to import. A NULL value indicates that all items in the specified directory will be imported.



The CMDBXMLImportItemList structure consists of the following elements:

CMDBImportItemStruct

The CMDBImportItemStruct data structure is used to hold the items to import. This data structure is deprecated in the 2.0 release of the BMC Atrium CMDB.

typedef struct CMDBImportItemStruct{ unsigned int itemType; CMDBClassNameId classNameId; unsigned long importOption;} CMDBImportItemStruct;

The CMDBImportItemStruct structure consists of the following elements:

numItems An integer value indicating the number of CMDBXMLImportItem items in the list.

exportItemList A structure that holds the list of XML items to import.

itemType An integer value indicating the type of information to import.

1—Import (CMDB_ITEM_TYPE_META_DATA).

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.



importOption An integer value indicating how the import of instances is handled if any duplicates are found during the import. These option values are mutually exclusive.

1—Generate an error (AR_MERGE_ENTRY_DUP_ERROR).

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

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

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

5—Create an entry with a new ID (AR_MERGE_ENTRY_NEW_ID).

These constants are the same as used by the ARMergeEntry function in the CMDB C API. For more information, see the CMDB ar.h file.

Note: This item is applicable only if CMDB_ITEM_TYPE_META_DATA is set.



Graph query structures

Graph query structures are data structures used in graph queries. 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.

typedef struct CMDBGetObjectList{ unsigned int numItems; CMDBGetObjectStruct *objectList;} CMDBGetObjectList;

The CMDBGetObjectList structure consists of the following elements:

CMDBGetObjectStruct

The CMDBGetObjectStruct data structure is used to hold a CI instance.

typedef struct CMDBGetObjectStruct{ CMDBClassNameId classNameId; ARNameType instanceId; CMDBAttributeValueList attributeValueList;} CMDBGetObjectStruct;

numItems An integer value indicating the number of CMDBGetObjectStruct items in the list.

objectList The list of CI instances.



The CMDBGetObjectStruct structure consists of the following elements:

CMDBGetRelationList

The CMDBGetRelationList data structure is used to hold a list of relationships.

typedef struct CMDBGetRelationList{ unsigned int numItems; CMDBGetRelationStruct *relationList;} CMDBGetRelationList;

The CMDBGetRelationList structure consists of the following elements:

CMDBGetRelationStruct

The CMDBGetRelationStruct data structure is used to hold a single relationship.

typedef struct CMDBGetRelationStruct{ CMDBClassNameId classNameId; ARNameType instanceId; ARNameType roleNames[2]; CMDBClassNameId relatedClassNames[2]; ARNameType relatedClassIds[2]; ARNameType relatedInstanceIds[2]; CMDBAttributeValueList attributeValueList;} CMDBGetRelationStruct;

The CMDBGetRelationStruct structure consists of the following elements:

classNameId The class name ID for the class.

instanceId The instance ID of the object.

attributeValueList The list of attribute values.

numItems An integer value indicating the number of CMDBGetRelationStruct items in the list.

relationList The list of relationships.

classNameId The class name ID of the relationship class.

instanceId The instance ID of the related class.

roleNames[2] The role names for the two classes that make up the relationship.

relatedClassNames[2] The names of the two classes that make up the relationship.



CMDBGraphAdjacentList

The CMDBGraphAdjacentList data structure is used to hold a list of adjacent nodes in CMDBGraphAdjacentStruct.

typedef struct CMDBGraphAdjacentList{ unsigned int numItems; CMDBGraphAdjacentStruct *adjacents;} CMDBGraphAdjacentList;

The CMDBGraphAdjacentList structure consists of the following elements:

CMDBGraphAdjacentStruct

The CMDBGraphAdjacentStruct data structure is used to hold an adjacent node.

typedef struct CMDBGraphAdjacentStruct{ CMDBClassNameId relClassNameId; CMDBQualifierStruct relQual; CMDBAttributeGetStruct relGetAttribute; CMDBClassNameId objClassNameId; ARNameType extensionId; CMDBQualifierStruct objQual; CMDBAttributeGetStruct objGetAttribute;} CMDBGraphAdjacentStruct;

The CMDBGraphAdjacentStruct structure consists of the following elements:

relatedClassIds[2] The class IDs of the two classes that make up the relationship.

relatedInstanceIds[2] The instance IDs of the two classes that make up the relationship.

attributeValueList The list of relationship attribute values.

numItems An integer value indicating the number of CMDBGraphAdjacentStruct items in the list.

adjacents The list of adjacent nodes.

relClassNamesNameId The name of the class that makes up the relationship.

relQual The qualification string that qualifies the relationship. This item can be NULL.

relGetAttribute The related attribute to retrieve from the relationship.

objClassNameId The object class name.



CMDBGraphList

The CMDBGraphList data structure is used to define the query graph list in the CMDBGraphQuery function.

typedef struct CMDBGraphList{ unsigned int numItems; CMDBGraphStruct *graph;} CMDBGraphList;

The CMDBGraphList structure consists of the following elements:

CMDBGraphStruct

The CMDBGraphStruct data structure is used to hold each graph node in the query graph.

typedef struct CMDBGraphStruct { CMDBClassNameId classNameId; ARNameType extensionId; CMDBGraphAdjacentList adjacentList;} CMDBGraphStruct;

The CMDBGraphStruct structure consists of the following elements:

extensionId The extension ID of the object. This item can contain an empty string.

objQual The qualification of the object. This item can be NULL.

objGetAttribute The object attribute to retrieve.

numItems An integer value indicating the number of CMDBGraphStruct items in the list.

graph The graph structure.

classNameId The name of the class for the object (node).

extensionId The extension ID of the node.

adjacentList The list of adjacent objects (nodes).



User interface components structures

The user interface (UI) component structures are data structures used in UI component functions. 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.

typedef struct CMDBUIComponentInfo{ ARNameType classId; ARLocaleType locale; unsigned int componentType; char *tag1; char *tag2; char *tag3; char *tag4; char *tag5; char *encodedQual;} CMDBUIComponentInfo;

The CMDBUIComponentInfo structure consists of the following elements:

classId An integer value indicating the class ID for the UI component.

locale The name of the locale specific to the component. If no locale is specified in this subclasses, the default locale will be used.



CMDBUIComponentResult

The CMDBUIComponentResult data structure is used to hold the component query result.

typedef struct CMDBUIComponentResult{ ARNameType instanceId; CMDBUIComponentIno componentInfo; char *dataString; ARAttachStruct *attachVal; } CMDBUIComponentResult;

The CMDBUIComponentResult structure consists of the following elements:

componentType The integer value indicating the component type.

0—No component information to retrieve (CMDB_COMPONENT_TYPE_NONE).

1—The icon type component to retrieve (CMDB_COMPONENT_TYPE_ICON).

2—The localized label type component to retrieve (CMDB_COMPONENT_TYPE_LOCALIZED_LABEL).

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

(CMDB_COMPONENT_TYPE_LINE).

tag1 Information tag used to filter a specific component type.





encodedQual The encoded qualifier for the UI component query.

instanceId An integer value indicating the class ID of the UI component class.

componentInfo Contains the component information for the specific instance.

dataString Contains the component data string.

attachVal Contains the attachment for the component.



CMDBUIComponentResultList

The CMDBUIComponentResultList data structure is used to hold the component query result.

typedef struct CMDBUIComponentResultList{ unsigned int numItems; CMDBUIComponentResult *componentResList;} CMDBUIComponentResultList;

The CMDBUIComponentResultList structure consists of the following elements:

Reconciliation Engine structures

Reconciliation Engine structures are data structures used in Reconciliation Engine queries. 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.

typedef struct CMDBREJobRunInfoList{ unsigned int numItems; CMDBREJobRunInfo *jobRunList;} CMDBREJobRunInfoList;

numItems An integer value indicating the number of CMDBUIComponent items in the list.

componentResultList Contains a list of UI components.



The CMDBREJobRunInfoList structure consists of the following elements:

CMDBREJobRunInfo

The CMDBREJobRunInfo data structure is used to hold information about a currently running Reconciliation Engine job.

typedef struct CMDBREJobRunInfo{ ARNameType jobRunId; ARNameType jobInstanceId; ARNameType jobName; ARTimestamp startTime; ARTimestamp endTime; unsigned int jobState;

} CMDBREJobRunInfo;

The CMDBREJobRunInfo structure consists of the following elements:

CMDBREClassQualStruct

The CMDBREClassQualStruct data structure is used to hold information about the class qualification.

typedef struct CMDREBClassQualStruct{ ARNameType classId; CMDBQualifierStruct *qual; }CMDBREClassQualStruct;

numItems An integer value indicating the number of CMDBREJobRunInfo items in the list.

jobRunList The list of Reconciliation Engine jobs to execute.

jobRunId The Reconciliation Engine job run ID.

jobInstanceId The instance ID of the Reconciliation Engine job.

jobName The name of the Reconciliation Engine job.

startTime The start time of the job.

endTime The end time of the job.

jobStatus The current status of the Reconciliation Engine job.



The CMDBREClassQualStruct structure consists of the following elements:

CMDBREClassQualList

The CMDBREClassQualList data structure is used to hold a list of CMDBREClassQualStruct structures.

typedef struct CMDBREClassQuaList{ unsigned int numItems; CMDBREClassQualStruct *classQualList;}CMDBREClassQuaList;

The CMDBREClassQualList structure consists of the following elements:

CMDBREDatasetPair

The CMDBREDatasetPair data structure is used to hold information about the datasets to use in the reconciliation job.

typedef Struct CMDBREDatasetPair{ARNameType workingDataset;ARNameType dataset;

}CMDBREDatasetPair;

The CMDBREDatasetPair structure consists of the following elements:

classId The ID of the class.

qual The qualification for the class. If the qualification contains a null value, all the instances in the class will be reconciled.

numItems An integer value indicating the number of CMDBREClassQualStruct structure items in the list.

classQualList A list of CMDBClassQualStruct structures.

workingDataset The dataset name of the working dataset. If this field contains a Null, the dataset for the reconciliation job will be replaced with workingDataset before reconciliation.

dataset The dataset for the reconciliation job. If the workingDataset field in the structure contains a Null, the dataset specified in this field will be used.



CMDBREDatasetList

The CMDBREDatasetList data structure is used to hold a list of CMDBREDatasetPair structures.

typedef Struct CMDBREDatasetList{Unsigned int numItems;CMDBREDatasetPair* datasetList;

}CMDBREDatasetList;

The CMDBREDatasetList structure consists of the following elements:

Federation structures

Federation structures are data structures used in federation functions. 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.

typedef struct CMDBFederatedARInfo{

unsigned int arAccessType; ARNameType server; ARNameType form; ARNameType view; char *qualifier; char *url;} CMDBFederatedARInfo;

numItems An integer value indicating the number of CMDBREDatasetPair items in the list.

datasetList A list of CMDBREDatasetPair items.



The CMDBFederatedARInfo structure consists of the following elements:

CMDBFederatedActivateInfo

The CMDBFederatedActivateInfo data structure is used to hold the federated instance data activation information to retrieve.

typedef struct CMDBFederatedActivateInfo{ unsigned int actionType; unsigned int accessType; union {

CMDBFederatedARInfo arInfo;char *accessString;

} u;} CMDBFederatedActivateInfo;

arAccessType The access type for the AR System.

0—Retrieve AR System URL

(CMDB_FEDERATED_ACCESS_TYPE_AR_URL).1—Retrieve AR System Process(CMDB_FEDERATED_ACCESS_TYPE_AR_PROCESS).

server The AR System server name.

form The AR System form name.

view The AR System view name.

qualifier The qualifier string for accessing the AR System.

url Contains a URL to access the AR System form depending on whether the default webpath is specified on the AR System server.



The CMDBFederatedActivateInfo structure consists of the following elements:

actionType The action to perform.

0—Activate none.

(CMDB_FEDERATION_ACTIVATION_NONE).

1<<0—Return the expanded federated interface data.

(CMDB_FEDERATION_ACTIVATION_EXPAND).

1<<0—Expand and launch the federated interface.

(CMDB_FEDERATION_ACTIVATION_LAUNCH).

accessType The type of access required.

0—Access an AR System form for the federated interface

(CMDB_FEDERATED_ACCESS_TYPE_AR).1—Access a URL for the federated interface(CMDB_FEDERATED_ACCESS_TYPE_URL).2—Use a web service for the federated interface(CMDB_FEDERATED_ACCESS_TYPE_WEBSERVICE).3—Start a process for the federated interface(CMDB_FEDERATED_ACCESS_TYPE_PROCESS).4—Access a manual launch link information for the federated interface(CMDB_FEDERATED_ACCESS_TYPE_MANUAL).5—Access a data store for the federated interface

(CMDB_FEDERATED_ACCESS_TYPE_DATA_STORE).

arInfo Contains information related to the AR System form.

accessString Based on the accessType subclasses, contains the URL link, process command, or other information.



Audit structures

Audit structures are data structures used in audit functions. 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.

typedef struct CMDBAuditValueList{

unsigned int operation; ARAccessNameType changedBy;ARTimestamp auditTimestamp;ARNameList attrNameChangeList;CMDBAuditValueList *attrAuditValueList;

} CMDBAuditValueList;

The CMDBAuditValueList structure consists of the following elements:

operation The type of audit operation performed.

0—No audit operation performed.

(CMDB_AUDIT_OPERATION_NONE).

1—The modify operation performed

(CMDB_AUDIT_OPERATION_SET).

2—The create operation performed

(CMDB_AUDIT_OPERATION_CREATE).

3—The delete operation performed

(CMDB_AUDIT_OPERATION_DELETE).

4—The merge operation performed

(CMDB_AUDIT_OPERATION_MERGE).

changedBy The user who performed the audit operation.

auditTimestamp The date and time when the audit operation was performed.

attrNameChangeList The list of attribute names that changed in the audit operation.

attrAuditValueList The list of attribute values that changed for the specified attributes.



CMDBAuditValueListList

The CMDBAuditValueListList data structure is used to hold a list of audit values list to retrieve.

typedef struct CMDBAuditValueListList{

unsigned int numItems; CMDBAuditValueList *attrAuditValueList;

} CMDBAuditValueListList;

The CMDBAuditValueListList structure consists of the following elements:

CMDBAuditInfoStruct

The CMDBAuditInfoStruct data structure is used to hold the audit information to set audit options for the class.

typedef struct CMDBAuditInfoStruct{

unsigned int type; CMDBQualifierStruct qual;union {

ARNameType logForm; } u;} CMDBAuditInfoStruct;

The CMDBAuditInfoStruct structure consists of the following elements:

numItems An integer value indicating the number of CMDBAuditValueList structure items in the list.

attrAuditValueList The list of audit value list.

type The type of audit option to set.

0—None

No auditing option set.

1—Copy

Create a copy of an instance when an attribute is modified.

2—Log

Store the information for the modified attributes in a log.

qual The qualification to retrieve the audit information for the class.

logForm The name of the AR System form for the Log audit option.


Chapter

6
Web services API operations and data structures
This chapter provides reference information for the web services API operations and data structures.


! Operations (page 222)

! Data structures (page 262)

Web services API operations and data structures � 221


Operations

The web services operations are categorized by the type of functions these operations perform. The operation categories include instance, data model, reconciliation object, and session.

Note: In the web services API function descriptions, the usage of the term specified for a given parameter denotes that the parameter is listed under the Synopsis heading of the API function.

Instance data operations

The instance data operations act on CI or relationship instances. 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


GetInstances

Description Retrieves a list of instances. You can limit the retrieved instance result-set by specifying a qualification.


Synopsis <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"/>


</element>

Inputarguments

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 instances are to be retrieved. It is a two-part structure that contains the namespace and the class name.

Operations � 223


query

A qualification that determines the set of instances to retrieve. The qualification can include one or more attributes and any combination of conditional, relational, and arithmetic operations.

attributes

A list of attribute names to retrieve.

firstRetrieve

The first instance to retrieve. CMDB_START_WITH_FIRST_ENTRY represents the first entry and is the default value if the value is not set.

maxRetrieve

The maximum number of entries to retrieve. Use this parameter to limit the amount of data returned if the query does not narrow the list. Specify CMDB_NO_MAX_LIST_RETRIEVE to assign no maximum.

sortOrder

The sort order for the retrieved data.

aDatasetId


aGetMask


GET_MASK_NONE: Based on the datasetId being passed, instances are retrieved from either the overlay or the original dataset.

DATASET_MODE_CURRENT: Allows you to retreive instances from the current dataset only.

Return values instanceInfo

The list of instances that match the criteria, each with a list of attributes and values.

status

A list of zero or more notes, warnings, or errors generated from a call of this operation.



SetInstance

Description Sets a CI or relationship instance in the class form.


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


</element><element name="StatusOutput"><complexType>

<sequence><element name="status" type="impl:StatusList"/>


</element>

Inputarguments

loginInfo


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


Operations � 225


aDatasetId


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.



CreateInstance

Description Creates a CI or relationship instance in the class form.


Synopsis <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"/>


</element>



<element name="CreateInstanceOutput"><complexType>

<sequence><element name="instanceId" type="xsd:string"/><element name="status" type="impl:StatusList"/>


</element>

Inputarguments

loginInfo


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


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


Operations � 227


DeleteInstance

Description Deletes an instance of a class.


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



</element>

Inputarguments

loginInfo


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




aDatasetId


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.



CreateRelationInstance

Description Creates relationship instances for the specified CIs.


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


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

Inputarguments

loginInfo


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.



attributes

The list of attributes values for the relationship class.

Return Values instanceId

The instance ID of the relationship instance that is created.

status


GraphQuery

Description Queries related instances for the specified CI.


Synopsis <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"/>


</element>

Operations � 231


<element name="GraphQueryOutput"><complexType>

<sequence><element name="objects" type="impl:ObjectQueryInfoList"/><element name="relations"

type="impl:RelationQueryInfoList"/><element name="status" type="impl:StatusList"/>


</element>

Inputarguments

loginInfo


startClassNameId

The name of the starting node class in the CI graph.

startExtensionId

The extension ID of the starting node CI. This is required if the query graph contains more than one instance of the same class and needs to distinguish one from another. For example, 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.

startInstanceId

The ID of the starting node in the CI graph.

numLevels

The number of levels to traverse the specified queryGraph. The value A-1 specifies the graph query to traverse to the end of the graph.

direction

The direction in which the graph is to traverse.

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.



noMatchProceedT (1):

When the node returned for a given relationship instance does not match the criteria specified, proceed to the next relationship. Notice that, in this case, no relationship information will be returned because the returned components might not be connected, due to skipping the non-matching nodes.

F (0):

When the node returned for a given relationship instance does not match the criteria specified, do not proceed any further.

onMatchProceedT (1):

When the node returned for a given relationship instance matches the criteria specified, proceed to the next relationship.

F (0):

When the node returned for a given relationship instance matches the criteria specified, do not proceed any further.

graph

The details of the information indicating the path that needs to be queried to return the desired CIs and relationships.

aGetMask


GET_MASK_NONE: Based on the datasetId being passed, instances are retrieved from either the overlay or the original dataset.

DATASET_MODE_CURRENT: Allows you to retreive instances from the current dataset only.

aDatasetId


Return values objects

List of one or more CI instances matching the specified criteria. The starting node is not included.

Operations � 233


relations

List of relationship instances matching the specified criteria that links the CIs returned.

status


Data model operations

The data model operations act on classes and their attributes in the data model. 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)



GetClass

Description Retrieves the class information.


Synopsis <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"/>


</element><element name="GetClassOutput"><complexType>

<sequence><element name="classInfo" type="impl:ClassInfoOut"/><element name="status" type="impl:StatusList"/>


</element>

Inputarguments

loginInfo


classNameIDThe class which is to be retrieved. It is a two-part structure that contains the namespace and the class name.

Return values classInfo

Information about the class.

status


Operations � 235


SetClass

Sets the properties for a specified class.


Synopsis <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"/>





</element>

Inputarguments

loginInfo


classNameId

The class that is to be set. It is a two-part structure that contains the namespace and the class name.

newclassNameId

The new name of the class.

classInfo

Information about the class.





CreateClass

Creates a class with core attributes.


Synopsis <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"/>





</element>

Inputarguments

loginInfo


Operations � 237


classNameId

The name of the class to create. It is a two-part structure that contains the namespace and classname in the <namespace>:<classname> format. The name of the class must be unique.

superClassNameId

The superclass of class being created. Specify NULL for this parameter if there is no superclass.

classId

The unique identifier for the class. It can be provided by the user. If it is not provided by the user, it will be automatically generated by the system.

classInfo

The information about the class, such as the type of class to create. The information contained in this definition depends on the type of class you specify.


A list of zero or more notes, warnings, or errors generated from a call to this operation.

ListClasses

Description Retrieves information about relationship classes for a specified class. The classes that are retrieved will have the class that is specified in the relatedClass parameter as part of the relationship.


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


</wsdl:operation><wsdl:message name="ListClassesRequest"><wsdl:part element="tns:ListClassesInput" name="inargs"/>

</wsdl:message>



<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:element><xsd:element name="ListClassesOutput"><xsd:complexType>

<xsd:sequence><xsd:element name="classList" type="tns:ClassNameIdList"/><xsd:element name="status" type="tns:StatusList"/>


</xsd:element>

Inputarguments

loginInfo


namespace

The name of the namespace. Namespaces are a way of partitioning your data model to create logical groups of classes. The Class Manager namespaces are implemented using a prefix-based naming convention on classes.

relatedClass

Retrieves the relationship classes that have a class specified in this parameter as part of the relationship.

superClass

The superclass of the class to retrieve. Retrieves the classes that are derived from the superclass.

propInfo

The list property information of the class to retrieve.

getHidden

Retrieves the hidden classes.

Operations � 239


Return values classList

A list of class names that match the specified criteria.

status


DeleteClass

Description Deletes a specified class. Also deletes the associated attributes of the class.


Synopsis <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"/>





</element>

Inputarguments

loginInfo




classNameID

The name of the class to delete.

option

A value indicating the action to take if the specified class contains instances, has subclasses, or is a member of a relationship class.

OPTION_NONE: Delete the class only if the class contains no instances and has no subclasses or dependent relationships.

OPTION_WITH_DATA: Delete the class only if the class has no subclasses or dependent relationships. This applies only to regular classes.

OPTION_ALL_DEPENDENCIES: Delete the class including all the subclasses and dependent relationship classes that are associated with it. All the dependencies for the specified class are deleted. This option overrides the CMDB_CLASS_DATA_DELETE option.



GetAttributes

Description Retrieves information about a list of attributes


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


</complexType></element><element name="GetAttributesOutput"><complexType>

<sequence><element name="attributeInfoList"

type="impl:AttributeInfoList"/><element name="status" type="impl:StatusList"/>


</element>

Inputarguments

loginInfo


classNameId

The class for which the attributes are to be retrieved. It is a two-part structure that contains the namespace and the classname.

attributeNames

The names of the attributes to retrieve.

Return values attributeInfoListThe information about the list of attributes.

status


CreateAttribute

Description Creates an attribute for the specified instance.


Synopsis <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"/>



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





</element>

Inputarguments

loginInfo


classNameId

The name of the class for which the attribute is to be created. It is a two-part structure that contains the namespace and the classname.

attributeName

The name of the attribute to create. The name of all attributes must be unique within the class.

attributeIdThe ID of the attribute to create.

fieldId

The AR System field ID of the attribute to create. The IDs of all attributes must be unique within the class. Specify 0 for this parameter if you want the system to generate the ID.

Operations � 243


attributeInfo


Return values statusA list of zero or more notes, warnings, or errors generated from a call to this operation.

SetAttribute

Description Sets an attribute for the specified instance.


Synopsis <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"/>





</element>



Inputarguments

loginInfo


classNameId

The class for which the attribute is to be set. It is a two-part structure that contains the namespace and the classname.

attributeName

The name of the attribute to set.

newAttributeName

The new name of the attribute.

attributeInfo

The value limits for the attribute and other properties specific to the attribute’s type. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute you are setting. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the attribute limits and properties.



Delete Attribute

Description Deletes the attribute with the specified name.


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


<element name="DeleteAttribute"><complexType>

<sequence><element name="loginInfo" type="impl:LoginInfo"/><element name="classNameId" type="impl:ClassNameId"/><element name="attributeName" type="xsd:string"/>





</element>

Inputarguments

loginInfo


classNameID

The name of the class from which to delete the attribute.

attributeName

The name of the attribute to delete.





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 Starts a job.


Synopsis <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"/>


</element>

Operations � 247


Inputarguments

loginInfo


jobName

The name of the job to start.

qualifierList

The list of class qualifications.

datasetList

The list of Reconciliation Engine dataset pair.

Return values jobId

The ID of the job.

status


GetJobRun

Description Retrieves information about a currently running job.


Synopsis <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"/>


</element>



<element name="GetJobRunOutput"><complexType>

<sequence><element name="jobRunInfo" type="impl:JobRunInfo"/><element name="jobLog" type="xsd:string"/><element name="status" type="impl:StatusList"/>


</element>

Inputarguments

loginInfo


jobId

The ID of the job.

Return values jobRunInfo

The information about the currently running job.

jobLog

The log for the currently running job.

status


Operations � 249


GetListJobRun

Description Retrieves information about a list of currently running jobs.


Synopsis <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"/>


</element><element name="GetListJobRunOutput"><complexType>

<sequence><element name="jobRunInfo" type="impl:JobRunInfoList"/><element name="status" type="impl:StatusList"/>


</element>

Inputargument

loginInfo


qualifier

A query that determines the set of jobs to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations.

Return Values jobRunInfo

The information about the currently running jobs.



status


CancelJobRun

Description Stops a currently running job.


Synopsis <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"/>





</element>

Inputarguments

loginInfo


jobId

The ID of the job.

Operations � 251




Federation operations

The federation functions manipulate the federated data for an instance. 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, your federated instance might either be only expanded or expanded and launched.


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



<xsd:element name="FederatedActivateInfoOutput"><xsd:complexType>

<xsd:sequence><xsd:element name="federatedActivateInfo"

type="tns:FederatedActivateInfo"/><xsd:element name="status" type="tns:StatusList"/>


</xsd:element>

Inputarguments

loginInfo


classNameId

The class name of the specified CI for which the federated instance is to be expanded or launched.

aDatasetId


instanceId

The instance ID of the specified instance for which the federated instance is to be expanded or launched.

federatedInstanceId

The instance ID of the federated instance that is to be expanded or launched.

activateOption

The mask number that indicates if the federated instance is to be launched and expanded.

ACTIVATION_NONE:

No specific operation to be performed.

ACTIVATION_EXPAND:

Only expand the federated interface.

ACTIVATION_LAUNCH:

Expand and launch the federated interface.

Operations � 253


Return values federatedActivateInfo

The expanded federated instance information. This parameter is returned only if you specify a value of 1in the activateOption parameter.

status


GetRelatedFederatedInContext

Description Returns related FederatedInterface instances for a specific CI (context).


Synopsis <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:element>



Inputarguments

loginInfo


classNameId

The class name of the specified instance for which federated instances are to be retrieved.

instanceId

The Instance ID of the specific instance for which federated instances are to be retrieved.

attributeNames

The list of attribute names to retrieve.


The list of instance GUIDs.

status


Operations � 255


Audit operations

The audit functions manipulate the audit option for the classes and attributes. 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. The audit option must be set for the attribute’s characteristic to get the audit data.


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


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


</xsd:complexType></xsd:element>



<xsd:element name="GetCopyAuditDataOutput"><xsd:complexType>

<xsd:sequence><xsd:element name="auditValueListList"

type="tns:AuditValueListList"/><xsd:element name="status" type="tns:StatusList"/>


</xsd:element>

Inputarguments

loginInfo


classNameId

The class name (class name and namespace combination) of the specified CI instance for which a copy of the audit data is to be retrieved.

instanceId

The instance ID of the specified CI instance for which a copy of the audit data is to be retrieved.

datasetIdThe unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.

query

A query that determines the set of CI instances to retrieve. The qualification can include one or more attributes and any combination of conditional, relational, and arithmetic (numeric data types only) operations.

attributes

A list of attribute names for which the audit data is to be retrieved.

Return values auditValueListList

The list of values for the specified attributes. If the audit option at the CI class-level is disabled then, an error is returned.

status


Operations � 257


User interface component operations

The user interface (UI) component operations work with components, such as tool tips, icons, and labelized strings. The web services API includes the following user interface (UI) operations:

! GetUIComponents (page 258)

GetUIComponents

Description Retrieves a list of various UI components for a specified class.


Synopsis <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:element><xsd:element name="GetUIComponentsOutput"><xsd:complexType>

<xsd:sequence><xsd:element name="uiComponentResultList"

type="tns:UIComponentResultList"/><xsd:element name="status" type="tns:StatusList"/>


</xsd:element>



Inputarguments

loginInfo


componentInfo

The qualification for the user interface component. You can specify information such as locale, classId, and tags to get the required UI component data. If there are no qualifications specified, all existing UI components will be returned.

datasetId


instanceId

The unique identifier used to get component information for a specific instance.

Return Values uiComponentResultList

The CMDBUIComponents result set for the specified qualifications.

status


Operations � 259


Utility operations

The utility operations enable you to use CMDB utilities such as get version information of the BMC Atrium CMDB application. The web services API includes the following utility operations:

! GetVersions (page 260)

GetVersions

Description Retrieves the version information for any BMC Atrium CMDB component that is installed.


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


</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:element>

Inputarguments

loginInfo




appIdList

A list of application IDs for which the version information is required. Specify a NULL value in this argument to get version information of all the existing applications.

Return values versionInfoList

A list of BMC Atrium CMDB version structures.

status


Operations � 261


Data structures

The web services data structures are used as parameters for web services operations. The data structure categories include Instance, Graph query, Class, and Reconciliation Engine structures.

Instance structures

Instance structures are data structures for the instance data. Instance structures include:

! LoginInfo (page 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.

<complexType name="LoginInfo"><sequence>

<element name="userId" type="xsd:string"/><element name="password" type="xsd:string"/><element name="lang" type="xsd:string"/>


The LoginInfo structure consists of the following elements:

userId The login ID for the user.

password The password for the user.

lang The language to use for the current session of the application.



ClassNameIdList

The ClassNameIdList data structure is used to hold a list of ClassNameID structures.

<xsd:complexType name="ClassNameIdList"><xsd:sequence>

<xsd:element maxOccurs="unbounded" minOccurs="0"name="items" type="tns:ClassNameId"/>


The ClassNameIdList structure consists of the following element:

ClassNameId

The ClassNameId data structure is used to hold a class.

<complexType name="ClassNameId"><sequence>

<element name="namespaceName" type="xsd:string"/><element name="className" type="xsd:string"/>


The ClassNameId structure consists of the following elements:

ArrayOf_String

The ArrayOf_String data structure is used to hold a list of string values.

<complexType name="ArrayOf_String"><sequence>

<element maxOccurs="unbounded" minOccurs="0" name="items"type="xsd:string"/>


The ArrayOf_String structure consists of the following element:

ClassNameId The list of class name IDs.

namespaceName The namespace name for the class.


items The value of the attribute.



SortOrderList

The SortOrderList data structure is used to hold a list of attributes on which to sort.

<complexType name="SortOrderList"><sequence>

<element maxOccurs="unbounded" minOccurs="0" name="items"type="impl:SortOrder"/>


The SortOrderList structure consists of the following element:

SortOrder

The SortOrder data structure is used to hold a list of attributes on which to sort along with the sort type.

<xsd:complexType name="SortOrder"><xsd:sequence>

<xsd:element name="attributeName" type="xsd:string"/><xsd:element name="sortOrder" type="tns:SortOrderType"/>


The SortOrder structure consists of the following elements:

InstanceInfoList

The InstanceInfoList data structure is used to hold a list of InstanceInfo structures.

<complexType name="InstanceInfoList"><sequence>

<element maxOccurs="unbounded" minOccurs="0" name="items"type="impl:InstanceInfo"/>


items A list of SortOder structure items.

attributeName The name of the attribute to sort.

sortOder The sort order for the list of attributes.

ASCENDING—The attributes will be sorted in ascending order of the list.

DESCENDING—The attributes will be sorted in descending order of the list.



The InstanceInfoList structure consists of the following element:

InstanceInfo

The InstanceInfo data structure is used to hold instance values.

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

StatusList

The StatusList data structure is used to hold a list of status information for an operation.

<complexType name="StatusList"><sequence>

<element maxOccurs="unbounded" minOccurs="0" name="items"type="impl:Status"/>


The StatusList structure consists of the following element:

Status

The Status data structure is used to hold the status information for an operation.

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


items A list of InstanceInfo structure items.

instanceId The ID of the instance.

instanceAttributes The attributes of the instance.

items The status value of the operation.



The Status structure consists of the following elements:

statusType The type of status message for the operation.

OK—Operation successful. Status might contain one or more informational messages.

WARNING—Operation successful, but some problems encountered. Status contains one or more warning messages and might also contain information messages.

ERROR—Operation failed. Status contains one or more error messages and might also contain warning or informational messages.

FATAL—Operation failed.

BAD_STATUS—Invalid status parameter. Operaion cancelled.

PROMPT—Status for the active link action.

ACCESSIBLE—Status message for client accessibility.

messageNum An integer value indicating the message number.

messageText The description for the status message.

appendedText Additional information for the status message.



Graph query structures

Graph query structures are data structures used in graph queries. 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"/>


The GraphList structure consists of the following element:

Graph

The Graph data structure is used to hold the query graph information.

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

items A list of Graph structure items.



The Graph structure consists of the following elements:

GraphAdjacencyList

The GraphAdjacencyList data structure is used to hold a list of graph adjacency items.

<xsd:complexType name="GraphAdjancencyList"><xsd:sequence>

<xsd:element maxOccurs="unbounded" minOccurs="0"name="items" type="tns:GraphAdjancency"/>


The GraphAdjacencyList structure consists of the following element:\

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


classNameId The name of the class for the object (node).

extensionId The extension ID of the node.

adjacencyList The list of adjacent objects (nodes).

items A list of GraphAdjancency structure items.



The GraphAdjacency structure consists of the following elements:

ObjectQueryInfoList

The ObjectQueryInfoList data structure is used to hold a list of CI instances.

<complexType name="ObjectQueryInfoList"><sequence>

<element maxOccurs="unbounded" minOccurs="0" name="items"type="impl:ObjectQueryInfo"/>


The ObjectQueryInfoList structure consists of the following element:

extensionId The extension ID of the object. This item can contain an empty string.

objectClassName The object class name.

objectAttributeNames The object attribute to retrieve.

objectAttributeType The type of object attributes to retrieve.

NONE—Retreive no attributes in the query.

NOHIDDEN—Retreive all non-hidden attributes.ALL—Retreive all the attributes.

objectQuery The qualification for the object. This item can be NULL.

relationClassNames The name of the class that makes up the relationship.

relationAttributeNames The related attribute to retrieve from the relationship.

relationAttributeType The related attribute type.

relationQuery The qualification string that qualifies the relationship. This item can be NULL.

items A list of ObjectQueryInfo items.



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:

RelationQueryInfoList

The RelationQueryInfoList data structure is used to hold a list of relationships.

<complexType name="RelationQueryInfoList"><sequence>

<element maxOccurs="unbounded" minOccurs="0" name="items"type="impl:RelationQueryInfo"/>


The RelationQueryInfoList structure consists of the following element:

classNameId The class name ID for the class.

items A list of RelationQueryInfo items.



RelationQueryInfo

The RelationQueryInfo data structure is used to hold relationship information.

<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 The role name for the parent instance in a relationship.

instanceRole2 The role name of the child instance in a relationship.

role1ClassName The class name of the parent class.

role2ClassName The class name of the child class.

role1ClassId The class ID of the parent class.

role2ClassId The class ID of the child class.

role1InstanceId The instance ID of the parent class.

role2InstanceId The instance ID of the child class.



Class Structures

Class structures are data structures for class and relationship definitions. 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.

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


The ClassInfoIn structure consists of the following elements:

relationshipInfo The relationship information of the class.

indexList The index list for the class.

properties The role names for the two classes that make up the relationship.

customCharacList The names of the two classes that make up the relationship.



ClassInfoOut

The ClassInfoOut data structure is used to retrieve class information.

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

ClassRelationship

The ClassRelationship data structure is used to hold relationship information for CI classes.

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

superClassNameId The name of the superclass.


classType The type of class.

relClassNames1 The name of the parent class that is a part of the relationship.

relClassNames2 The name of the child class that is a part of the relationship.

roleNames1 The role name of the parent class that is a part of the relationship.



roleNames2 The role name of the parent class that is a part of the relationship.

cardinality An integer identifying the cardinality of the relationship between the related classes:

NONE—Undefined cardinality for a relationship.

ONE_ONE—One-to-one. One instance of a class is associated with a single instance of another class.

MANY_ONE—Many-to-one. One or more instances of a class are associated with one instance of another class.

ONE_MANY—One-to-many. One instance of a class is associated with one or more instances of another class.

MANY_MANY—Many-to-many. Many instances of a class are associated with many instances of another class.

cascadeDelete A Boolean value indicating the type of delete allowed between the related classes:

TRUE—A cascade delete is allowed. Deleting an instance in one class also deletes the instance in the related class.

FALSE—A cascade delete is not allowed.

Note: This item is applicable only for one-to-one and one-to-many relationships.

isRole2WeakReference A Boolean value indicating whether role 2 is a weak reference:

TRUE—The role 2 class is a weak reference. Role 2 is a weak entity and it uses role 1’s primary key as part of its own key. If the value is TRUE, cardinality must be one-to-one or many-to-many.

FALSE—The role 2 class is not a weak reference.

weakPropagatedAttrsList If the value of isRole2WeakReference is TRUE, indicates the list of attributes that are propagated from the role 1 class to the role 2 class.



ClassProperties

The ClassProperties data structure is used to hold properties for a CI 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"/>


The AttributeInfoList structure consists of the following element:

isAbstract A value indicating whether the class is an abstract class.

NO—A regular class

REGULAR—A regular abstract classWITH_DATA_REPLICATION—A data replication abstract class

hiddenPerms A value indicating the groups or roles that cannot view the class form in the ObjectList form of the applica-tion. The class will be only available through the work-flow once this parameter is set for a group or role.

visiblePerms A value indicating the groups or roles that can view the class form both—in the ObjectList form of the appli-cation and the workflow.

categorizationSubclass A Boolean value indicating whether the class is a cate-gorization class.

TRUE—This is a categorization class. In categorization classes the data is stored in the parent class.

FALSE—This is not a categorization class.

description The description text for the class.

isFinal A Boolean value indicating whether the class is a Final class.

TRUE—This is a Final class. You cannot create a subclass for a Final type class.

FALSE—The class is not a final class.



IndexList

The IndexList structure is used to hold index information for the class.

<xsd:complexType name="IndexList"><xsd:sequence>

<xsd:element maxOccurs="unbounded" minOccurs="0"name="items" type="tns:IndexInfo"/>


The IndexList structure consists of the following elements:

IndexInfo

The IndexInfo structure is used to hold the attributes to index.

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


</xsd:complexType>

The IndexInfo structure consists of the following elements:

isSingleton A Boolean value indicating whether the class is a single-ton class.

formName The form name for the class.

author The name of the author for the class.

auditInfo The structure that holds the audit information for the class.

Items An integer value indicating the number of IndexStruct items in the list.

indexName The name of the index.

unique A Boolean value indicating whether the index key must be unique:

TRUE—The index key is unique.

FALSE—The index key is not unique.



PropInfoList

The PropInfoList structure is used to hold a list of PropInfo structures.

<xsd:complexType name="PropInfoList"><xsd:sequence>

<xsd:element maxOccurs="unbounded" minOccurs="0"name="items" type="tns:PropInfo"/>


The PropInfoList structure consists of the following elements:

PropInfo

The PropInfo structure is used to hold common display properties for the class.

<xsd:complexType name="PropInfo"><xsd:sequence>

<xsd:element name="tag" type="xsd:int"/><xsd:element name="value" type="tns:Value"/>


The PropInfo structure consists of the following elements:

isPrimaryKey A Boolean value indicating whether the index is a primary key index:

TRUE—The index key is a primary key index.

FALSE—The index key is not a primary key index.

attributeNames The names of attributes to index.

Items A list of PropInfo structure items.

tag An integer value indicating the particular display property.

value The value for the property, which can be of any supported data type (see Value data structure.)



Attribute structures

Attribute structures are data structures for attribute definitions. 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.

<complexType name="AttributeInfoList"><sequence>

<element maxOccurs="unbounded" minOccurs="0" name="items"type="impl:AttributeInfoOut"/>


The AttributeInfoList structure consists of the following element:

items A list of AttributeInfoOut items.



AttributeValueList

The AttributeValueList data structure is used to hold a list of attribute information.

<complexType name="AttributeValueList"><sequence>

<element maxOccurs="unbounded" minOccurs="0" name="items"type="impl:AttributeValue"/>


The AttributeValueList structure consists of the following element:

AttributeValue

The AttributeValue data structure is used to hold a list of values for an attribute.

<xsd:complexType name="AttributeValue"><xsd:sequence>

<xsd:element name="name" type="xsd:string"/><xsd:element name="value" nillable="true" type="tns:Value"/>


The AttributeValueList structure consists of the following elements:

AttributeInfoIn

The AttributeInfoIn data structure is used to set 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"/>


items A list of AttributeValue structure items.

name The name of the attribute.

value The value for the attribute.



The AttributeInfoIn structure consists of the following elements:

value The value of the attribute.

entryMode The entry mode for the attribute.

DISPLAY_ONLY—Data for the attribute is display only. This attribute cannot be modified.

NONE—No specific entry mode defined for the attribute.OPTIONALENTRY—Data entry for the attribute is optional. This attribute can be left blank.REQUIREDENTRY—Data entry for the attribute is required. This attribute cannot be left blank.SYSTEM—A system-generated value will be used for this attribute.

createMode The create mode for the attribute.

OPEN—Allow any user to create an attribute.

PROTECTED—Allow restricted users to create an attribute.

attrLimit The AttributeLimit structure defining the limit for the attribute.

changePerms A value indicating the change permissions for the at-tribute.

isHidden A Boolean value indicating whether the attribute is hid-den.

TRUE—The attribute is hidden in the class form.

FALSE—The attribute is not hidden in the class form.

viewPerms A value indicating the view permissions for the attribute.

customCharacList A structure indicating the custom properties for the at-tribute.



AttributeLimit

The AttributeLimit structure is used to hold the data limit definitions for an attribute list of any 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 An AttachmentLimit structure indicating the data limit value for an attachment data type.

attachPoolLimit An AttachPoolLimit structure indicating the data limit for an attach pool data type.

charLimit A CharLimit structure indicating the data limit for a char data type.

currencyLimit A CurrencyLimit structure indicating the data limit for a currency data type.

dateLimit A DateLimit structure indicating the data limit for a date data type.

diaryLimit A DiaryLimit structure indicating the data limit for a diary data type.

enumLimit An EnumLimit structure indicating the data limit for an enumeration.

intLimit An IntLimit structure indicating the data limit for an integer field.

realLimit A RealLimit structure indicating the data limit for a real data type.



AttachmentLimit

The AttachmentLimit structure is used to hold data limit definitions for the attachment data type.

<xsd:complexType name="AttachmentLimit"><xsd:sequence>

<xsd:element name="attachmentPoolName" type="xsd:string"/><xsd:element name="maxSize" type="xsd:long"/>


The AttachmentLimit structure consists of the following elements:

The AttachPoolLimit structure consists of the following elements:

CharLimit

The CharLimit structure is used to hold data limit definitions for the character data type.

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


timeLimit A TimeLimit structure indicating the data limit for a time data type.

timeOfDayLimit A TimeOfDayLimit structure indicating the data limit for a time of day data type.

attachmentPoolName The name of the attachment pool for the attachment attribute.

maxSize The maximum size in bytes of an attachment data type. A value of 0 (zero) represents an unlimited size.

attachPoolName A unique name for the attachment pool.

maxSize An integer value indicating the maximum size limit for the attachment.



The AttachPoolLimit structure consists of the following elements:

CurrencyLimit

The CurrencyLimit structure is used to hold data limit definitions for the currency data type.

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


charMenu Sets the name of the AR System character menu attached to the char limit attribute

format Used for character list data, specified as L<n>, where n is the number of items in the list. L4, for example, indicates a list of a maximum of 4 items, with each item separated by a semicolon (;). NULL indicates a list is not used.

FTSOption Specifies whether the attached field is indexed for full text search (FTS).

0—Not full text search indexed.1—Full text search indexed.

maxCharLength An integer value indicating the maximum size limit for the char attribute.

menuStyle Specifies a style for the menu.

1—Overwrite the existing value.

2—Append to the existing value.

The menyStyle field is applicable only if a menu is attached.

pattern The AR System pattern specification for the field that is attached to this attribute.

QBEOption Indicates an integer value for the query match type.

1—Anywhere in the string.

2—In the leading characters of the string.

3—The same as the string



The CurrencyLimit structure consists of the following elements:

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


The DateLimit structure consists of the following elements:

EnumLimit

The EnumLimit structure is used to hold data limit definitions for the enum 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>

allowableType Default list of allowable currencies when new currency attributes are created.

functionalType Default list of functional currencies when new currency attributes are created.

highRange The high range of the custom characteristic for the currency data type.

lowRange The low range of the custom characteristic for the currency data type.

precision The number of integers allowed to the right of the decimal point for the currency data type.

minDate The minimum value for the date data type.

maxDate The maximum value for the date data type.



The EnumLimit structure consists of the following elements:

IntLimit

The intLimit structure is used to hold data limit definitions for the integer data type.

<xsd:complexType name="IntLimit"><xsd:sequence>

<xsd:element name="highRange" type="xsd:int"/><xsd:element name="lowRange" type="xsd:int"/>


The IntLimit structure consists of the following elements:

RealLimit

The RealLimit structure is used to hold data limit definitions for the real data type.

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


The RealLimit structure consists of the following elements:

listStyle This enumeration type is not currently supported.

regularEnumItems An ordered list of enumerations.

customEnumItems An unordered list of enumeration.

highRange The high range of the custom characteristic for the integer data type.

lowRange The low range of the custom characteristic for the integer data type.

highRange The high range of the custom characteristic for the real data type.

lowRange The low range of the custom characteristic for the real data type.

precision The number of digits allowed to the right of the decimal point for the real data type.



AttributeLimitList

The AttributeLimitList structure is used to hold a list of data limit definitions for an attribute list of any data type.

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

Utility structures

Utility structures are structures used in utility operations, such as for retrieving version information of the BMC Atrium CMDB application. 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"/>


The VersionInfoList structure consists of the following element:

Items A list of AttributeLimit items.

Items A list of VersionInfo structure items.



VersionInfo

The VersionInfo structure is used to hold version information for the BMC Atrium CMDB components.

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


The VersionInfo structure consists of the following elements:

applicationId An ID for the application.

applicationName The name for the application.

maintenanceVer The maintenance version number.

majorVer The major part (preceding the dot) of the version number information.

minorVer The minor part (succeeding the dot) of the version number information.

patchNum The patch number.

isExist A Boolean value indicating whether the specified version of a component exists.

TRUE—The specified version exists.

FALSE—The specified version does not exit.



User interface component structures

The user interface (UI) component structures are data structures used in UI component operations. 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.

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


The UIComponentInfo structure consists of the following elements:

classId An integer value indicating the class ID for the UI component.

componentType The integer value indicating the component type.

COMPONENT_TYPE_ICON—The icon type component to retrieve.

COMPONENT_TYPE_LINE—The user interface graphical line information to retrieve (This option is currently not being used.)

COMPONENT_TYPE_LOCALIZED_LABEL—The localized label type component to retrieve.

COMPONENT_TYPE_NONE—No component information to retrieve.

COMPONENT_TYPE_TOOLTIP—The tooltip type component to retrieve.

encodedQual The encoded qualifier for the UI component query.



UIComponentResultList

The UIComponentResultList data structure is used to hold UI component information.

<xsd:complexType name="UIComponentResultList"><xsd:sequence>

<xsd:element maxOccurs="unbounded" minOccurs="0"name="items" type="tns:UIComponentResult"/>


The UIComponentResultList structure consists of the following element:

UIComponentResult

The UIComponentResult data structure is used to hold the component query result.

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


locale The name of the locale specific to the component. If no locale is specified in this subclasses, the default locale will be used.






Items A list of CMDBUIComponentResult structure items.



The UIComponentResult structure consists of the following elements:

Reconciliation Engine structures

Reconciliation Engine structures are data structures for reconciliation jobs. 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.

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


The JobRunInfo structure consists of the following elements:

attachVal Contains the attachment for the component.

componentInfo Contains the component information for the specific instance.

dataString Contains the component data string.

instanceId An integer value indicating the class ID of the UI component class.

jobStartTime The start time for the job.

jobEndTime The end time for the job.

jobInstanceId The instance ID for the job.

jobName The name of the job.

jobRunId The run ID for the job.



JobRunInfoList

The JobRunInfoList data structure is used to retrieve information of all running jobs.

<complexType name="JobRunInfoList"><sequence><element maxOccurs="unbounded" minOccurs="0" name="items"

type="impl:JobRunInfo"/></sequence>

</complexType>

The JobRunInfoList structure consists of the following element:

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


The ClassQualifierList structure consists of the following element:

ClassQualifier

The ClassQualifier data structure is used to hold information about the class qualification.

<xsd:complexType name="ClassQualifier"><xsd:sequence>

<xsd:element name="qualifierString" type="xsd:string"/><xsd:element name="classId" type="xsd:string"/>


The ClassQualifier structure consists of the following elements:

items A list of information about the jobs.

Items A list of ClassQualifier structure items.

qualifierString The qualification for the class. If the qualification contains a Null value, all the instances in the class will be reconciled.




DatasetPairList

The DatasetPairList data structure is used to hold a list of DatasetPair structures.

<xsd:complexType name="DatasetPairList"><xsd:sequence>

<xsd:element maxOccurs="unbounded" minOccurs="0"name="items" type="tns:DatasetPair"/>


The DatasetPairList structure consists of the following element:

DatasetPair

The DatasetPair data structure is used to hold information about the datasets to use in the reconciliation job.

<xsd:complexType name="DatasetPair"><xsd:sequence>

<xsd:element name="dataset" type="xsd:string"/><xsd:element name="workingDataset" type="xsd:string"/>


The DatasetPair structure consists of the following elements:

Items A list of DatasetPair items.

dataset The dataset for the reconciliation job. If the workingDataset field in the structure contains a Null, the dataset specified in this field will be used.

workingDataset The dataset name of the working dataset. If this field contains a Null, the dataset for the reconciliation job will be replaced with workingDataset before reconciliation.



Federation structures

Federation structures are data structures used in federation operations. 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.

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


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.

ACCESS_TYPE_URL—Access a URL for the federated interface.ACCESS_TYPE_WEBSERVICE—Use a web service for the federated interface.ACCESS_TYPE_PROCESS—Start a process for the federated interface.ACCESS_TYPE_MANUAL—Access a manual launch link information for the federated interface.ACCESS_TYPE_DATA_STORE—Access a data store for the federated interface.

actionType The action to perform.

ACTIVATION_LAUNCH—Expand and launch the federated interface.

ACTIVATION_DATA_RETURN—Return the expanded federated interface data.



FederatedARInfo

The FederatedARInfo data structure is used to hold the AR System related federated interface information to retrieve.

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


The FederatedARInfo structure consists of the following elements:

accessString Based on the accessType subclasses, contains the URL link, process command, or other information.

arInfo Contains information related to the AR System form.

accessType The access type for the AR System.

ACCESS_TYPE_AR_URL—Retrieve AR System URL.

ACCESS_TYPE_AR_PROCESS—Retrieve AR System Process.

form The AR System form name.

qualifier The qualifier string for accessing the AR System.

server The AR System server name.

url Contains a URL to access the AR System form depending on whether the default web path is specified on the AR System server.



Audit structures

Audit structures are data structures used in audit operations. 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.

<xsd:complexType name="AuditValueListList"><xsd:sequence>

<xsd:element maxOccurs="unbounded" minOccurs="0"name="items" type="tns:AuditValueList"/>


The AuditValueListList structure consists of the following element:

AuditValueList

The AuditValueList data structure is used to hold a list of audit values to retrieve.

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


The AuditValueList structure consists of the following elements:

Items A list of AuditValueListList structures.

attributeList The list of attribute names that changed in the audit operation.

auditDate The date and time when the audit operation was performed.



AuditInfo

The AuditInfo data structure is used to hold the audit information to set audit options for the class.

<xsd:complexType name="AuditInfo"><xsd:sequence>

<xsd:element name="auditType" type="tns:AuditType"/><xsd:element name="qualifierString" type="xsd:string"/>


The AuditInfo structure consists of the following elements:

changedBy The user who performed the audit operation.

operation The type of audit operation performed.

AUDIT_OP_SET—The modify operation performed.

AUDIT_OP_CREATE—The create operation performed.

AUDIT_OP_DELETE—The delete operation performed.

AUDIT_OP_MERGE—The merge operation performed.

auditType The type of audit option to set.

Copy—Create a copy of an instance when an attribute is modified.

Log—Store the information for the modified attributes in a log.

None—No auditing option set.

qualifierString The qualification to retrieve the audit information for the class.


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.


! 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 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 Message type Error message

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


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


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


120011 Error 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)

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





120018 Error (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 non-relationship 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.





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





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





120032 Error 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 final class are correct.

120033 Error The parameters for the singleton class are invalid. (CMDB_ERROR_INVALID_SINGLETON_CLASS)

Description

The parameter value you specified for the singleton class does not match with the class definition.

Solution

Make sure that the parameters for the singleton class are correct.

120034 Warning The specified export item type is invalid. (CMDB_WARN_INVALID_EXPORT_ITEM_TYPE)

Description

The item type you are attempting to export is invalid.

Solution

The export item should be either of type CMDB-ITEM-TYPE-META-DATA (1) or CMDB-INSTANCE-DATA (2).

120035 Error The permission list must be a list of group IDs separated by semicolons. (CMDB_ERROR_PERMISSION_LIST_INVALID)

Description

You are attempting to separate a list of group IDs using an invalid character.

Solution

Use semicolons to separate the groups IDs in the permission list.





120036 Error The specified query graph does not have a starting node. (CMDB_ERROR_QUERY_GRAPH_HAS_NO_STARTNODE)

Description

You omitted the starting node parameter in a graph query.

Solution

Make sure you specify the starting node information in the graph query.

120037 Error A specified node is ambiguous. (CMDB_ERROR_QUERY_GRAPH_HAS_AMBIGUOUS_NODE)

Description

There is more than one node with the same name for the query graph.

Solution

Use an extension ID to distinguish between nodes within the same class and namespace.

120038 Error Creating more than one instance in a singleton class is not allowed. (CMDB_ERROR_INVALID_SINGLETON_CLASS_INST_OPERATION)

Description

You can create only one instance from a singleton class.

Solution

Do not create more than one instance from a singleton class.

120039 Error The operation violates the cardinality constraint of the relationship. (CMDB_ERROR_RELATION_CARDINALITY_CHECK)

Description

The operation you are performing violates the cardinality constraint of the relationship.

Solution

Using the CI Relationship Viewer, make sure that the operation does not violate the cardinality constraint.





120040 Error The relationship endpoint instance does not exist. (CMDB_ERROR_RELATION_END_PT_DOES_NOT_EXIST)

Description

You are attempting to create a relationship for a CI instance that does not exist.

Solution

Make sure that the instance exists.

120041 Error Required attributes are not allowed in categorization classes. (CMDB_ERROR_CATSUBCLASS_REQD_ATTR_NOT_ALLOWED)

Description

You are specifying the entry mode option as Required for the categorization class. This option is not allowed.

Solution

Change the entry mode to Optional.

120042 Error Because the relationship superclass is a weak relationship, this class must also be a weak relationship. (CMDB_ERROR_SUBCLASS_MUST_BE_RS_WEAK_REFERENCE)

Description

You cannot derive a regular relationship subclass from a weak relationship superclass.

Solution

Define this class to be of type weak relationship.

120043 Error Invalid cardinality for the weak relationship. (CMDB_ERROR_INVALID_CARDINALITY_FOR_WEAK_REFERENCE)

Description

You are attempting to specify an incorrect cardinality for a weak relationship.

Solution

The cardinality for a weak relationship must be either one-to-many or one-to-one.





120044 Error The weak instance is already associated with another lead instance.

(CMDB_ERROR_WEAK_INSTANCE_ALREADY_ASSOCIATED)

Description

You are attempting to specify more than one lead instance for a weak instance.

Solution

Unassociate the weak instance before trying to associate it with another lead instance.

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

Define the weak class of the weak relationship to be non-abstract.

120046 Error Setting lead class reference values is not allowed. (CMDB_ERROR_SETTING_LEAD_CLASS_REF_DISALLOWED)

Description

You cannot modify the attributes propagated from the lead class.

Solution

Do not attempt to modify propagated read-only attributes values.

120048 Error You cannot set a primary key characteristic on an attribute. (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.

Solution

You must set the primary key characteristic by way of an index.





120049 Error The primary key must be a unique index. (CMDB_ERROR_PRIMARY_KEY_ISNT_UNIQUE)

Description

The attribute you are attempting to set as primary key contains duplicate values.

Solution

Specify a unique index as the primary key.

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

Specify only one primary key per class.

120051 Error The weak class for the weak relationship class cannot be a categorization class. (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.

Solution

Define the weak class to be a non-categorization class.

120053 Error The class cannot be deleted because this class has instance data. (CMDB_ERROR_DELETE_CLASS_FAILED_DATA_EXISTS)

Description

You are attempting to delete a class that contains data.

Solution

To delete a class that contains data, specify Delete With Data as the delete option.





120054 Error The class cannot be deleted because there are class dependencies on this class. (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.

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. This option will delete the classes even if they contain data.

120055 Warning This class is a derived class of the class being deleted. (CMDB_WARN_DELETE_CLASS_FAILED_DEP_REG_CLASS)

Description

This is a warning that the class being deleted had a derived class.

120056 Warning An endpoint for this relationship class is the 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.

120057 Warning This class is a weak class of the relationship class being deleted. (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.

120058 Error The source attribute on the lead class for attribute propagation does not exist. (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.

Solution

Make sure that the source attribute exists in the lead class.





120059 Error The target attribute on the weak class for attribute propagation does not exist. (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

Make sure that the target attribute exists in the weak class.

120060 Error The data types for the source and target attributes do not match. (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.

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

Solution

Specify a target attribute for the weak class that is not a derived from its superclass.

120062 Error Permissions for a categorization class must be the same as the permissions for the superclass. (CMDB_ERROR_CATGORIZATION_SUB_PERM_LIST_INVALID)

Description

The categorization class permissions must match the permissions of its superclass.

Solution

Make sure that the categorization class permissions match its superclass.





120063 Error Instances cannot be deleted from this form.

(CMDB_ERROR_INSTANCE_DELETE_ON_FORM_DISALLOWED)

Description

You cannot delete an instance from the regular subclass form.

Solution

Delete the instance using the join form of the class.

120064 Error The system failed to create a unique identifier.

(CMDB_ERROR_CREATE_GUID_FAILED)

Description

The system was unable to generate a unique identifier.

Solution

If required, restart your process to generate the GUID.

120065 Warning Specified attachment pool does not exist. (CMDB_WARN_NO_SUCH_ATTACHMENT_POOL)

Description

You are attempting to specify an attachment pool that does not exist.

Solution

Create the attachment pool.

120067 Error An entry in the import item list is invalid. (CMDB_ERROR_IMPORT_ITEM_ITEM)

Description

An item in the specified import directory is not available.

Solution

Make sure that the item exists in the specified directory.

120068 Error Data type does not match the data type defined for this attribute.

(CMDB_ERROR_MISMATCHING_ATTR_DATATYPE)

Description

The value you specified for the attribute does not match the attribute definition.

Solution

Specify appropriate values that match the attribute data type definition.





120069 Error Attribute value does not fall within the limits defined for this attribute.

(CMDB_ERROR_ATTRIBUTE_VALUE_OUT_OF_LIMITS)

Description

The attribute value you specified is not within the defined range for the attribute.

Solution

Make sure that the attribute value is within the defined range.

120070 Error Index list is invalid. (CMDB_ERROR_INVALID_INDEX_LIST)

Description

You specified an invalid index list.

Solution

Make sure that the index properties that are specified in the error message, are valid.

120071 Error Setting the form name class characteristic is not allowed. (CMDB_ERROR_SETTING_FORM_NAME_CHARAC_DISALLOWED)

Description

The Form Name characteristic is an invalid option for the class.

Solution

You cannot set the form name class characteristic.

120072 Error The data type for the class characteristic value is invalid.

(CMDB_ERROR_INVALID_DATATYPE_FOR_CLASS_CHARAC)

Description

The value you specified for class characteristic subclasses does not match its datatype.

Solution

Specify a valid value for the class characteristic.

120073 Error The namespace name is too long. Must be 70 characters or less. (CMDB_ERROR_NAMESPACE_NAME_TOO_LONG)

Description

The namespace name you specified cannot exceed its character limit.

Solution

Specify a namespace name that is 70 characters or less.





120074 Error The class name is too long. Must be 80 characters or less. (CMDB_ERROR_CLASS_NAME_TOO_LONG)

Description

The classname you specified cannot exceed its character limit.

Solution

Specify a class name that is 80 characters or less.

120075 Error The subclass namespace must match the superclass namespace. (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.

120076 Error No value supplied for a required attribute. (CMDB_ERROR_REQUIRED_ATTRIBUTE_VALUE_MISSING)

Description

You did not specify a value for a required attribute.

Solution

Specify a value for the required attribute.

120077 Error Modifying the namespace name after class creation is not allowed. (CMDB_ERROR_MODIFY_NAMESPACE_NAME_IS_DISALLOWED)

Description

You cannot modify the namespace name after the class is created.

Solution

If required, delete this class and create a new one.

120078 Error The supplied character is not allowed in the name. (CMDB_ERROR_CHARACTER_DISALLOWED_IN_NAME)

Description

You specified invalid characters for the name.

Solution

Create a name containing the following valid characters: alphanumeric, underscore (_), or period (.)





120079 Error The attribute name is too long. Must be 80 characters or less. (CMDB_ERROR_ATTRIBUTE_NAME_TOO_LONG)

Description

The attribute name you specified cannot exceed its character limit.

Solution

Specify an attribute name that is 80 characters or less.

120080 Error Invalid value for the entry mode. (CMDB_ERROR_INVALID_ATTRIBUTE_ENTRY_MODE)

Description

You specified an invalid value for the entry mode subclasses.

Solution

Specify one of the valid values: 0-None, 1-Required, 2-Optional, 3-System, or 4-Display_Only.

120081 Error The subclasses ID is not unique within the class or within the class hierarchy. (CMDB_ERROR_ATTR_subclasses_ID_NOT_UNIQUE)

Description

The subclasses ID you specified is already in use within the specified class hierarchy.

Solution

Specify a different subclasses ID.

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 one of the valid values: 0-None, 1-View_Perms, 2-Change_Perms, 3-Hidden, 4-Primary_Key, 5-Propogated_Owner, 6-Create_Mode, 7-Audit_Option, or 8-Namespace.





120083 Error Setting the primary key attribute characteristic is not allowed. (CMDB_ERROR_SETTING_PRIMARY_KEY_CHARAC_DISALLOWED)

Description

The primary key characteristic is an invalid option for the attribute.

Solution

You cannot set the primary key attribute characteristic.

120084 Error Setting the propagated owner attribute characteristic is not allowed. (CMDB_ERROR_SETTING_PROP_OWNER_CHARAC_DISALLOWED)

Description

The propagated owner characteristic is an invalid option for the attribute.

Solution

You cannot set the propagated owner attribute characteristic.

120085 Error The namespace for the relationship end point class does not match the namespace of the relationship class. (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.

Solution

Specify a CI instance from the same namespace as the relationship class.

120086 Error Enum name is invalid. (CMDB_ERROR_ENUM_NAME_INVALID)

Description

The enum name you specified is invalid.

Solution

Specify a valid enum name.

120087 Error Attribute ID is not unique within the class or within the class hierarchy. (CMDB_ERROR_ATTRIBUTE_ID_NOT_UNIQUE)

Description

You specified an attribute ID that is not unique within the class hierarchy.

Solution

Specify a unique attribute ID within the class hierarchy.





120088 Error Invalid data type for the attribute limit structure. (CMDB_ERROR_INVALID_ATTR_LIMIT_DATA_TYPE)

Description

You specified an invalid value for the attribute limit structure.

Solution

The data type for the attribute limit structure must either match the data type of the attribute or be NULL.

120089 Error You do not have access to the class. (CMDB_ERROR_NO_ACCESS_TO_CLASS)

Description

You do not have permissions to access the class.

Solution


120090 Error You do not have access to the attribute. (CMDB_ERROR_NO_ACCESS_TO_ATTRIBUTE)

Description

You do not have permission to the access the attribute.

Solution


120092 Error The dataset ID and Reconciliation Identity combination is not unique. (CMDB_ERROR_DATASET_ID_RECON_ID_NOT_UNIQUE)

Description

The combination of reconciliation ID and dataset ID is not unique.

Solution

Change one of these values to make the combination unique.

120094 Error The direction provided for graph query is not valid. (CMDB_ERROR_QUERY_GRAPH_INVALID_DIRECTION)

Description

You specified an invalid direction value for the graph query.

Solution

Specify one of the valid values: 0-Direction_Out, or 1-Direction_In.





120095 Error Current object store API version is deprecated. (CMDB_ERROR_CURRENT_API_IS_DEPRECATED)

Description

You are attempting to use an API call that is now deprecated.

Solution

Upgrade to the current version of the CMDB API.

120096 Warning Instances skipped during import. (CMDB_WARN_IMPORT_INST_SKIPPED)

Description

This is a warning that certain instances were not imported during the import activity.

120097 Information Instance import summary. (CMDB_INFO_IMPORT_INST_SUMMARY)

Description

This message signifies that the instance import summary follows.

120098 Error The deleteOption value specified is invalid.

CMDB_ERROR_INVALID_DELETE_OPTION)

Description

You specified an invalid delete option for the class.

Solution

Specify one of the valid values: CMDB_DELETE_CLASS_OPTION_NONE, CMDB_DELETE_CLASS_OPTION_WITH_DATA, or CMDB_DELETE_CLASS_OPTION_ALL_DEPENDENCIES.

120099 Error The metadata status 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.





120100 Error One of the endpoints specified for the relationship has an invalid class ID. (CMDB_ERROR_INVALID_REL_ENDPOINT_CLASS_ID)

Description

You specified an invalid class ID for one of the CI instances in the relationship.

Solution

Specify a valid class ID for the instance.

120101 Error Internal system error. (CMDB_ERROR_ACCESS_TLS_BLOCK_FAILED)

Description

Access to thread local storage block failed.

Solution


120102 Error A version string in the SHARE:Application_Properties form is invalid. (CMDB_ERROR_UNRECOGNIZED_VERSION_PATCH_STRING)

Description

The version string for the CMDB patch is invalid.

Solution

Replace the patch string with a valid version string.

120103 Error Cascade Delete cannot be enabled for the relationship because its cardinality is invalid for cascade deletes. (CMDB_ERROR_INVALID_CASCADE_DELETE_VALUE)

Description

You specified an invalid cascade delete option for the relationship.

Solution

Specify a cardinality of one-to-many or one-to-one for the relationship.

120104 Error Reconciliation job cannot be started.

(CMDBRE_ERROR_START_JOB_RUN_FAILED)Description

An internal error has caused your reconciliation job to fail.

Solution

Contact BMC technical support for help.





120105 Error Failed to cancel reconciliation job.

(CMDBRE_ERROR_CANCEL_JOB_RUN_FAILED)Description

An internal error has caused an unsuccessful cancellation of your reconciliation job.

Solution

Contact BMC technical support for help.

120107 Error Failed to cancel a job not running.

(CMDBRE_ERROR_JOB_NOT_RUNNING)

Description

You are attempting to cancel a job that is not running.

Solution

Before you cancel a job, make sure that the job is running.

120108 Error Failed to find the specified job.

(CMDBRE_ERROR_JOB_LOOKUP)Description

The job you are referring to does not exist.

Solution

Make sure that the associated job ID is correct.

120109 Error Failed to start an inactive job.(CMDBRE_ERROR_INACTIVE_JOB_START)

Description

You are attempting to start an inactive job.

Solution

A job must be in an active state before you start the it.

120110 Error Job does not exist.

(CMDBRE_ERROR_JOB_NOT_EXIST)

Description

The job you are referring to does not exist.

Solution

Make sure that the job exists.





120111 Error Failed to start a job, which is already running.

(CMDBRE_ERROR_JOB_ALREADY_RUN)Description

You cannot start a job that is already running.

Solution

Please wait until the currently running job is completed.

120113 Error Number of IDs and Values does not match.

(CMDB_ERROR_ENUM_ID_VALUE_LEN_MISMATCH)

Description

The number of IDs and their values you specified do not match.

Solution

Make sure that the number of IDs and the values match.

120114 Error Invalid Enum ID.

(CMDB_ERROR_ENUM_ID_INVALID)Description

You have specified an invalid Enum ID.

Solution

Make sure that the Enum ID is valid.

120116 Error The session ID in the supplied control structure is invalid.(CMDB_ERROR_INVALID_AUDIT_COPY_TYPE)Description

The session ID that you specified for the login information is invalid.

Solution

Make sure that the control structure is correct and your API session is properly initialized.

120117 Error (CMDB_ERROR_INVALID_AUDIT_LOG_TYPE)

Description

If you specified the Copy audit option for your derived class, its superclasses cannot contain the Log audit option setting.

Solution

Make sure that the superclass and subclasses have the same audit option settings.





120120 Error Invalid dataset ID reference by the instance.

(CMDB_ERROR_INVALID_DATASET_ID)Description

The dataset ID you specified for the instance is invalid.

Solution

Perform the Set, Create, Delete operations. If the DatasetId attribute value is given in the attribute value list, make sure that the ID is the same as the DatasetId passed as parameter to the API call.

120121 Error The dataset ID does not exist.

(CMDB_ERROR_NO_SUCH_DATASET)Description

The dataset ID you specified does not exist.

Solution

Make sure that the If instance for the dataset ID you specified exists in the BMC.CORE:BMC_Dataset class. If the problem persists, restart the AR System server.

120122 Error The source dataset ID is missing.

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

120123 Error An internal error occurred.

(CMDB_ERROR_DATASET_UNDERLAY_INTERNAL_ERROR)

Description

The specified class ID and reconciliation ID for the underlay dataset do not exist.

Solution

Make sure the specified class ID and reconciliation ID exist.





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

Solution

Make sure that the access for the dataset is not set to read-only or writable by the client type.

120125 Warning Federated data corruption.

(CMDB_WARNING_DATASET_CACHE_LOADING)Description

An internal error occurred when accessing federated data.

SolutionContact your CMDB system administrator.

120126 Error Federation foreign key expansion failed.

(CMDB_WARNING_FOREIGN_KEY_EXPAND_FAILED)Description

An error occurred when attempting to expand a federated link.

Solution

Make sure that the federated foreign key link has the appropriate BMC_FederatedKeyLink class name.

120127 Error The session ID in the supplied control structure is invalid.

(CMDB_ERROR_BULK_TRAN_API_SESSION_ID_BAD)

Description

The API session information that you specified in the bulk transaction function is incorrect.

Solution

Make sure that the control structure is correct and that your API session is properly initialized.





120128 Error Cannot start another bulk transaction because a bulk transaction has already been started.

(CMDB_ERROR_BULK_TRAN_ALREADY_BEGUN)Description

You cannot start more than one bulk transaction function at a time.

Solution

Make sure no other bulk transaction function is in progress.

120129 Error The attempted operation cannot be performed because the bulk transaction has not started.

(CMDB_ERROR_BULK_TRAN_NOT_BEGUN)Description

You are attempting to perform a bulk transaction operation before starting a bulk transaction session.

Solution

The attempted operation can only be performed once a bulk transaction session is started.

120130 Error Failed to promote class, which has abstract superclass.

(CMDB_ERROR_SUPERCLASS_OF_TYPE_ABSTRACT)Description

You are attempting to promote a class that is derived from an abstract class.

Solution

You cannot promote a class that is derived from an abstract class.

120131 Error Federation launch failed.(CMDB_ERROR_FEDLINK_LAUNCH_FAILED)

Description

The federation link that you are attempting to launch failed.

Solution






120132 Error Superclass not found.

(CMDB_ERROR_SUPER_CLASS_NOT_FOUND)Description

The superclass you specified is not found.

Solution

Make sure that the specified superclass exists.

120133 Error The CMDB RPC port specified is invalid.

(CMDB_ERROR_RPC_SOCKET_RANGE)

Description

The RPC port that you specified for the BMC Atrium CMDB is invalid.

Solution

Specify a valid CMDB RPC port number. Valid port numbers include: 0, 390696, or 390697 (Admin thread).

120134 Error Failed to parse the qualification.

(CMDB_ERROR_FAILED_TO_RUN_QUALIFICATION)Description

The application failed to parse the specific qualification.

Solution

Correct the qualification based on the error message description provided.

120136 Error The requested object was not found in the import buffer. (CMDB_WARNING_REQUESTED_IMPORT_OBJECT_NOT_FOUND)

Description

The import item list object (class or attribute) that you requested does not exist in the .xml (import) file.

Solution

Make sure that the requested import object (class or attribute) exists in the .xml (import) file.





120137 Error Cannot import instance because the instance ID already exists.

(CMDB_ERROR_INSTANCE_ID_ALREADY_EXISTS)

Description

The instance ID you specified already exists.

Solution

Make sure you specify a unique instance ID for the instance or select an import option other than 1.

120138 Error Invalid import data option.

(CMDB_ERROR_INVALID_DATA_IMPORT_OPTION)

Description

The import option value you specified is incorrect.

Solution

Make sure you select the correct import option.

120139 Error The CoreDatasetId specified already exists.

(CMDB_ERROR_DUPLICATE_DATASET_ID)

Description

The CoreDatasetId you specified already exists.

Solution

Specify a different CoreDatasetId.

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.

Solution

Delete the specified attribute from the superclass.





120141 Error Can’t set MarkAsDeleted to ‘No’ on the relationship instance because one or both of the relationship endpoints are MarkAsDeleted. (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. (MarkAsDeleted)

Solution

Make sure you set MarkAsDeleted to No on both endpoints of the relationship before setting MarkAsDeleted to No on the relationship instance.

120142 Error Audit type Copy is not set for this class.

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

Solution

You cannot retrieve Copy audit data from a class whose audit type is set to a value other than Copy.

120145 Error Class ID and qualification information exceeded the limit of 4096 bytes.

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

Solution

Divide the classQualList information into more than one API calls.





CMDB Console active link error messages

Table 7-2 provides the error message details for CMDB Console messages that are generated by active links.

Table 7-2: CMDB Console active link error messages


13002 Error Qualification for the Where clause not defined.

Description

You cannot leave the attribute, operator, and value fields empty when specifying a qualification for the instance search.

Solution

Make sure you specify the required fields for the qualification.

13003 Error Qualification for the search operation not defined.

Description

You cannot search instances unless you specify the Where clause qualification, such as the attribute, operator, and value for the search.

Solution

Make sure you specify the Where clause qualification for the instance search.

13010 Error Search name not defined.

Description

You are attempting to save a search without specifying a search name for it.

Solution

Make sure you specify a name for the search that you want to save.

13015 Error Auditing not enabled for any class.

Description

The Audit option is not enabled for any class in the CDM. To view audit history, at least one class must be audit enabled.

Solution

Contact your CMDB system administrator to make sure the Audit option for classes is enabled both at the class and attribute level.

CMDB Console active link error messages � 327


13200 Error Instance not selected for viewing audit history.

Description

You did not select the instance for which the audit history is to be displayed. You can view audit history for only one instance at a given time.

Solution

Make sure you select an instance for the viewing the audit history.

13201 Error Instances not selected for the comparison.

Description

You did not select the instances that you want to compare. You must select only two instances at a given time for the comparison.

Solution

Make sure you select two instances for the comparison.

13202 Error A saved search with the specified name already exists.

Description

The name you specified for the search is already in use.

Solution

Make sure you specify a unique name for saving the search.

13203 Error A Public saved search with the specified name already exists.

Description

The name you specified for the Public search is already in use.

Solution

Make sure you specify a unique name for saving the Public search.

13204 Error You do not have access to any audited entry for this instance.

Description

You are attempting to view the audit history of the instance. You do not have access permissions to perform this operation.

Solution






13205 Warning There is no audited entry for this instance.

Description

The instance for which you want to view audit history has no data.

Solution

Make sure there is data for the specific instance.

20152 Warning OBJSTR:OnCancel_Cancel_Close/Undisplay

Close operation canceled. No changes were saved.

Description

Your changes were not saved.

Solution

To save your changes before closing a form, use the Cancel button.

44000 Error OBJSTR:Help_OpenHelpFile

Online Help has not been installed.

Description

You have not installed the BMC Atrium CMDB 2.0 Help.

Solution

To install the online Help, see the Installation and Configuration Guide.

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.

Solution

Make sure you specify ID values for the custom selection field.

125000 Error OBJSTR:AttributeDef_OnLoseFocus_subclassesID

Invalid subclasses ID.

The field ID you specified for the attribute is greater than the maximum value of a 32-bit signed integer data type.

Solution

Make sure that the field ID is less than or equal to 2147483647.





125002 Error OBJSTR:AttributeDef_OnSelect_CharacteristicsTab01

Please specify Data Type.

Description

You did not specify a data type for a field on the Characteristics Tab.

Solution

Make sure you specify a data type for the field.



Description

You did not specify the data type for a field on the Characteristics tab.

Solution

Specify a data type for the Characteristics tab.



Description


Solution




Description


Solution




Description


Solution






125006 Error OBJSTR:ClassDef_Attrib_AddSearchBtns_CheckForClassAndNamespace_Msg

Namespace and Class Name must be entered before you can add or search attributes.

Description

You did not specify a namespace and classname for the attribute.

Solution

Make sure that you specify a namespace and classname.

125007 Error OBJSTR:ClassDef_ChkDuplicateClass02

There is already an existing class with class name $490001100$ in the namespace $400109900$.

Description

The class name you specified is not unique within the class namespace.

Solution

Specify a different name for your class.

125008 Error OBJSTR:ClassDef_ChkSuperclassIsNotFinalClass02

Invalid superclass. Class $400103900$ is a final class and cannot be used as a superclass.

Description

You are attempting to derive a subclass from a final class.

Solution

You cannot derive a subclass from a final class.

125009 Error OBJSTR:ClassDef_OnSaveChkReqsubclasses

Namespace and Class Name are required subclasses.

Description

You did not specify the classname and namespace attributes for the subclass.

Solution

Make sure you specify the classname and namespace attributes.





125010 Error OBJSTR:ClassDef_OnSaveChkReqsubclassesForRelationship

Class 1, Class 2, Role 1, Role 2, and Association Enforcement are required subclasses for relationship classes.

Description

You did not specify the required attributes for the relationship class.

Solution

Make sure you specify these values before saving.

125012 Error OBJSTR:IdxCon-AttribAlreadyExist

This attribute is already part of the Index.

Description

You are attempting to specify an attribute for the index that is already in use.

Solution

Specify a different attribute.

125013 Error OBJSTR:IdxCon-GainFocusProperty_tbl

Please enter the Index Name first.

Description

You must specify a name for the index before you create it.

Solution

Specify an index name.

125014 Error OBJSTR:IdxCon-IndexNameLooseFocus01a

There is already an index by the name of: $400111200$. Please use a different name.

Description

You are attempting to specify an attribute for the index that is already in use.

Solution

Specify a different attribute.





125028 Error OBJSTR:WRdlg-cmdMapWeakRel01

Please select an Attribute from Class 1 and Class 2.

Description

You did not specify the attribute that you want to propagate in the weak relationship.

Solution

You must specify an attribute from Class 1 and Class 2.

125029 Error OBJSTR:WRdlg-cmdMapWeakRel02

Invalid data type mismatch. You can only map Attributes with the same data type.

Description

The data types of the attributes you specified do not match.

Solution

Make sure that the data types of the attributes match.

125030 Information OBJSTR:AttributeDef_SaveChanges

Attribute '$400009700$' has been saved.

Description

The attribute number specified in the message is saved.

125036 Error AL: OBJSTR:ClassDef_OnSave_ValidateCategSubClass

You must specify a superclass when creating a categorization class.

Description

You are attempting to create a categorization class without specifying its superclass.

Solution

Make sure that you specify a superclass for the categorization class.





CMDB Console filter error messages

Table 7-3 provides the error message details for the CMDB Console messages that are generated by filters.

Table 7-3: CMDB Console filter error messages


20163 Error OBJSTR:Lookup Association Name5

No entry found in SHARE:AssociationType with associationTypeId = $500000041$.

Description

The association type you specified is not found.

Solution

Make sure that the association type exists.

20279 Error BSM:AUD_AssocEnforce1-1Relationship 2

The relationship $490005100$ between $490021100$ and $490021101$ is defined as 1 to 1, and there is already an association of type $490005100$ between this $490021101$ and another $490021100$, or between this $490021100$ and another $490021101$.

Description

You are attempting to create a relationship for an instance that is already related to another instance.

Solution

Make sure that the instance name is correct. If you need to create more than one relationship for the specified instance, make sure you specify a many-to-one or one-to-many cardinality for it.

20280 Error BSM:AUD_AssocEnforce1-ManyRelationship 2

The relationship $490005100$ between $490021100$ and $490021101$ is defined as “1 to Many”, and there is already an association of type $490005100$ between this $490021101$ and another $490021100$.Description


Solution




20281 Error BSM:AUD_AssocEnforceMany-1Relationship 2

The relationship $490005100$ between $490021100$ and $490021101$ is defined as “Many to 1,” and there is already an association of type $490005100$ between this $490021100$ and another $490021101$.

Description


Solution


20366 Error OBJSTR:Lookup Localized String5

No entry found in SHARE:MenuItem_LT with Developer Name = $300132000$.

Description

The localized string for the menu item is not found.

Solution


20369 Error OBJSTR:Lookup Form Name5

No entry found in SHARE:Object with Form Name = $-5$.

Description

The form name you specified is not found.

Solution


50030 Error OBJSTR:Instance_CheckAbstractClassNoInstantiate

Invalid instance related operation on this abstract class.

Description

You cannot derive an instance from an abstract class.

Solution

Make sure that the superclass name you specified for the instance is correct.



CMDB Console filter error messages � 335


50038 Error 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 that the class name you specified for the singleton class is correct.

50040 Error OBJSTR:Instance_CheckRelationshipEndpoint<endpoint number>

The role <number> instance does not exist. The Class ID and Instance ID combination was not found. Class ID: $490008100$, Instance ID: $490008000$.

Description

The instance ID specified in the role <number> for the specified class is not found.

Solution

Make sure that the Instance ID for the specified Class ID exists.

50044 Error OBJSTR:Instance_RelWeakRef:<class name>:<step number>

Weak relationship instance cannot be created. Weak instance is already associated to another lead instance.

Description

You cannot assign the specified instance as a weak instance more than once. This instance is already a part of another weak relationship.

Solution

Make sure that the instance name you specified for the weak instance is correct.

50046 Error OBJSTR:Instance_RelWeakRef:BMC:<class name>:<step number>

Modifications to the lead class references values are not allowed.

Description

You are attempting to modify the reference values of the lead class in a weak relationship.

Solution

Make sure you do not modify the reference values for the lead class.





50063 Error OBJSTR:Instance_CheckDeleteOp

Instances cannot be deleted from this form.

Description

You cannot delete an instance from the instance base form.

Solution

Make sure you are using the join form to delete the instance.

125016 Error OBJSTR:AttributeDef_CheckForDupsubclassesID_Msg

Duplicate subclasses ID $400004800$ for attribute $400009700$.

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

Description

The field name you specified for the attribute is already in use in the class.

Solution

Make sure you specify a different field name.

125017 Error OBJSTR:AttributeDef_CheckRequiredsubclasses

Data Type and Attribute Name must be specified.

Description

Data type and attribute name are required fields for the subclass.

Solution

Make sure you specify values for these required fields.





125018 Error OBJSTR:AttributeDef_CheckReservedsubclassesID

Invalid subclasses ID for attribute $400009700$. Subclasses IDs below 100 are reserved for Core subclasses.

Description

The ID you specified for the subclass is a reserved value.

Solution

Make sure that the ID you specify is not a system-reserved value. For more information about reserved values, see the cmdb.h header file.

125019 Error OBJSTR:AttributeDef_CheckSelectionDefaltValue

Invalid Default Value for selection subclasses.

Description

The default value you specified for the subclass is invalid.

Solution

Make sure that you specify a default value from the list of approved values.

125020 Error OBJSTR:Class_ChkDuplicateClass02

There is already an existing class with class name $490001100$ in the namespace $400109900$. Please specify a different class name.

Description

The class name and namespace combination that you specified for the class is not unique.

Solution

Make sure that the class name is unique within the specified namespace.

125021 Error OBJSTR:Class-ChkAbstractFinal

This is an invalid combination of the Abstract and Final subclasses.

Description

You are attempting to derive a subclass as an abstract and final class.

Solution

Make sure you specify only one class type for the subclass.





125025 Error OBJSTR:Instance_Enforce1-1Relationship02

The relationship between $400126800$ and $400126900$ is defined as 1 to 1, and there is already a relationship instance between $400126800$ and $400126900$.

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.

125026 Error OBJSTR:Instance_Enforce1-ManyRelationship02

The relationship between $400126800$ and $400126900$ is defined as “1 to Many,” and there is already a relationship instance between $400126800$ and $400126900$.

Description


Solution


125027 Error OBJSTR:Instance_EnforceMany-1Relationship02

The relationship between $400126800$ and $400126900$ is defined as “Many to 1,” and there is already a relationship instance between $400126900$ and $400126800$.

Description


Solution


125033 Error OBJSTR:AttributeDef_CheckSpaceInName02

Spaces are not allowed in the Attribute Name Field.

Description

You are attempting to create an attribute name that has a blank character.

Solution

Make sure you create attribute name fields with no space or wildcard characters.





125034 Error OBJSTR:Class_CheckSpaceInName02

Spaces are not allowed in the Class Name Field.

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.

Description

You are attempting to create a superclass field that has a blank character.

Solution

Make sure you create superclass fields with no space or wildcard characters.




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.


! Events from AR System to CI Relationship Viewer (page 342)

! Events from CI Relationship Viewer to AR (page 344)

CI Relationship Viewer events � 341


Events from AR System to CI Relationship Viewer

You send an event to the CI Relationship Viewer with the PERFORM-ACTION-SEND-EVENT Run Process command. Sending events from the AR System forms enables you to programmatically manipulate the CI Relationship Viewer settings. 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. For more information about the Run Process workflow action, see BMC Remedy Action Request System 7.0 Workflow Objects.

CIRV_SET_FILTERChanges the filter for displaying the relationship information. The CI Relationship Viewer displays relationship information based on this filter.

Event Data: <filter name>

An example of Event Data for the CIRV_SET_FILTER event is All. When you specify All in Eventa Data, the default filter will be used.

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

Event Type: CIRV_SET_CUSTOM_FILTEREvent Data: <Namespace>|<Classes>|<Relationships>|<Statuses>|<Direction>|<NumLevels>

The following code shows an example Event Data for the CIRV_SET_CUSTOM_FILTER event:

BMC.CORE|BMC_ComputerSystem BMC_DiskDrive|BMC_Dependency BMC_Component|Active|0|5

342 �Appendix A—CI Relationship Viewer events


CIRV_SHOWDisplays a new relationship map with the details specified in Event Data. This is useful to change the graph that is displayed in the CI Relationship Viewer when it is initialized.

Event Type: CIRV_SHOWEvent Data: <namespace>:<class name>#<dataset id>.<instance id>

The following code shows an example Event Data for the CIRV_SHOW event.

Example:BMC.CORE:BMC_Computer_System#sim_dataset.AS0050560C63F28d6HQQYFQGAAKQAA

CIRV_SET_AS_ROOTSets the currently selected CI node as the root.

Event Type: CIRV_SET_AS_ROOTEvent Data: none

CIRV_SELECT_CISelects the given CI in the relationship diagram.

Event Type: CIRV_SELECT_CIEvent Data: <instance id>

An example of Event Data for the CIRV_SELECT_CI event is AS0050560C63F28d6HQQYFQGAAKQAA.

CIRV_REFRESHRefreshes the graphical representation with updated data from the BMC Atrium CMDB. The root CI remains the same as before, but the selection, if any, will be reset.

Event Type: CIRV_REFRESHEvent Data: none

CIRV_LAYOUTChanges the layout of the graphical representation. If the layout style TreeLayout is passed to the view, then the layout changes to Tree view. If RadialLayout is passed, it changes to Radial view.

Event Type: CIRV_LAYOUTEvent Data: <layout style>

An example of Event Data for the CIRV_LAYOUT event is TreeLayout.

Events from AR System to CI Relationship Viewer � 343


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. The AR System form can capture these events to use its data. When you send an event to the AR System form, you send the data in the $EVENTDATA$ variable and the event type in the $EVENTTYPE$ variable.

The following section lists the various events and the corresponding event data sent by the CI Relationship Viewer.

SELECTED_CIWhen you select a CI in the CI Relationship Viewer, a CI event is sent to the AR System to notify the container form.

Event Type: SELECTED_CIEvent data: <instance id>

An example of Event Data for the SELECTED_CI event is AS0050560C63F28d6HQQYFQGAAKQAA, which is the instance ID of the selected CI.

CIRV_NOTIFY_ARThis is a special type of event used by context menu items. 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, when that menu item is selected in the CI Relationship Viewer.

Both Event Type and Event Data are set to menu item ID for this event. The AR System form can use this data to perform any task.

Event Type: <menu item ID>Event Data: <menu item ID>

344 �Appendix A—CI Relationship Viewer events

Appendix

B
Finding related CIs using graph queries
The BMC Atrium CMDB provides C, Java, and web services APIs that allow programmatic manipulation of class and instance data. These APIs include a graph query function that lets you “walk” the graph of CIs and relationships in the CMDB, 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, then explains how the graph query works, using two examples.


! 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, the concepts and strategies discussed here are the same for it as they are for the C API. To apply these concepts and strategies to a graph query with the Java API, see the Java documentation installed in the sdk/doc/javadoc/cmdbapi/ subdirectory of your BMC Atrium CMDB installation directory.

For more information about the web services graph query operation, see Chapter 6, “Web services API operations and data structures.”

Finding related CIs using graph queries � 345


Representing graphs

There are two standard ways to represent a graph 1: as a collection of adjacency lists or as an adjacency matrix. The adjacency-list representation is usually preferred, because it provides a compact way to represent sparse graphs—those for which is much less than . An adjacency-matrix representation might be preferred, however, when the graph is dense: is close to . The representation used by the CMDBGraphQuery input query graph is an adjacency list.

The adjacency-list representation of a graph consists of an array of lists, one for each vertex in . For each , the adjacency list

contains pointers to all the vertices v such that there is an edge . That is, consists of all the vertices adjacent to in . The

vertices in each adjacency list are typically stored in an arbitrary order. Figure B-1 (b) is an adjacency-list representation in an arbitrary order of the undirected2 graph in Figure B-1 (a).

Figure B-1: Undirected graph and its equivalent adjacency list

1 stands for vertices, stands for edges.2In an undirected graph , the edge set consists of unordered pairsof vertices, rather than ordered pairs. That is, an edge is a set , where

and . In an undirected graph, self-loops are forbidden, and so ev-ery edge consists of exactly two distinct vertices.

G V E,( )=

V E

E V 2

E

V 2

G V E,( )=

Adj V V u V∈Adj u[ ]u v,( ) E∈ Adj u[ ] u G

G V E,( )= Eu v,{ }

u v V∈, u v≠

346 �Appendix B—Finding related CIs using graph queries


Similarly, Figure B-2 (b) is an adjacency-list representation of the directed graph in Figure B-2 (a). In the CMDB, all relationships are directional, so our query graph is a directed graph. In this graph, each relationship instance is like an edge and each CI instance is like a vertex.

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. To accommodate this range, it uses an adjacency-list data structure to represent the input query graph.

For a description of the CMDBGraphQuery function, see “CMDBGraphQuery” on page 135.

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. In the graph, CI instances are circular nodes and relationship instances are the lines connecting them.

The CMDBGraphQuery API function � 347


Figure B-3: Graph of data to use with example queries



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, which is defined as a relationship with A:A instances on both ends. You want to walk outward to the last level, so the value of the numLevels argument will be -1. There’s no qualification on the instances of A:rAA or A:A. For return data, you are retrieving all of the attributes on the relationship instances and the CI instances.

Graphically, the query you want to walk is illustrated in Figure B-4. Notice that for the same query, the graph can be represented either as (a) or (b). In representation (a), the class A:A appears twice. To distinguish one instance of A:A from the other, an extensionId is needed. In this example, one of the instances is assigned the arbitrary extensionId of two.

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). Figure B-6 on page 351 shows the data structures of the queryGraph argument for Figure B-4 (b).



Figure B-5: queryGraph data structures for Figure B-4 (a)



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.



Figure B-7: Path walked and nodes returned by Query Example 1



The expected data to be returned is:

! Seven CI instances of A:A with instance IDs 2, 3, 8, 4, 5, 6, and 7.

! Eight relationship instances of A:rAA with instance IDs 1, 2, 3, 4, 5, 9, 6, and 7.

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, which is defined as a relationship with an A:A instance on the left and an A:B instance on the right. 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. You want to walk outward to the last level, so the value of the numLevels argument will be -1. There’s no qualification on the instances of any of the CI or relationship classes. For return data, you are retrieving all of the attributes on the relationship instances and the CI instances.

Graphically, the query you want to walk is illustrated in Figure B-7. As with Example 1, the graph for this query can be represented either as (a) or (b). In representation (a), the class A:A appears twice. To distinguish one instance of A:A from the other, an extensionId is needed. In this example, one of the instances is assigned the arbitrary extensionId of two.

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). Figure B-10 on page 355 shows the data structures of the queryGraph argument for Figure B-8 (b).



Figure B-9: queryGraph data structures for Figure B-8 (a)



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.



Figure B-11: Path walked and nodes returned by Query Example 2



The expected data to be returned is:

! Six CIs. Three are instances of A:A with instance IDs 8, 5, and 9. Three are instances of A:B with instance IDs 1, 3, and 2.

! Six relationships. Three are instances of A:rAB with instance IDs 1, 3, and 2. Three are instances of A:rBA with instance IDs 1, 2, and 3.


Glossary

abstract classA class that has attributes but of which no instances can be created. An abstract class exists for the purpose of creating an organizational layer without a database join. See also data replication.

accountAn entity or party whose data is represented in the BMC Atrium CMDB, and to whom specific levels of permission can be granted. Specifying instance permission by account enables the BMC Atrium CMDB to support multitenancy.

activityAn individual reconciliation task that can be grouped together in a defined sequence to form a reconciliation job. You cannot run an activity by itself; only as part of a job. See also Comparison activity, Copy Dataset activity, Delete Dataset activity, Execute Job activity, Identification activity, Merge activity, Purge Dataset activity, Rename Dataset activity.

attributeA property or characteristic of a class, such as the IP address of a computer system. An attribute equates to a column on a database table or a field on an AR System form.

attribute permissionPermission to view or change the value in the attribute for any instance, assuming valid instance permissions.

attribute substitutionA method of data federation in context that uses placeholders to represent attributes from a linked class. Launching the link triggers the respective attribute values to be substituted for the placeholders.

auditA logging of attribute values and other information for purposes of tracking the history of changes to instance data. An audit is triggered when the value of one or more specified attributes changes or when the instance is created or deleted.

base classA class that has no superclass.

Business Service Management (BSM)The concept of prioritizing IT efforts to supports the overall goals of the business.

Glossary � 359


cardinalityThe 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 deleteTo 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)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 classA 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.

CDMSee Common Data Model (CDM).

childSee destination.

CISee configuration item (CI).

CI classA class that defines a type of configuration item (CI), such as a computer system or software application.

CI Relationship ViewerA component of the BMC Atrium CMDB that graphically displays the relationships between CIs. It can also be embedded in other AR System-based applications.

CI Relationship Viewer eventA 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.

CIMSee Common Information Model (CIM).

classMetadata 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 ManagerA 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 permissionsPermission to view instances of a class in the BMC Atrium CMDB interface or access them with AR System workflow.

CMDBSee Configuration Management Database (CMDB).

CMDB ConsoleThe main user interface of the BMC Atrium CMDB, accessible from both web and BMC Remedy User clients.

CMDB Console UserAn application role. Members can perform searches from the CMDB Console and view federation definitions.

360 �Glossary


CMDB Console AdminAn application role. Members can perform searches from the CMDB Console, view, create, and modify federation definitions, and perform CMDB Console administrative tasks.

CMDB Data ChangeAn application role. Members can view, create, and modify instances if they have row-level security.

CMDB Data Change AllAn application role. Members can view, create, and modify instances independent of row-level security.

CMDB Data ViewAn application role. Members can view instances if they have row-level security.

CMDB Definitions AdminAn application role. Members can view, create, modify, and delete classes.

CMDB Definitions ViewerAn application role. Members can view class definitions.

CMDB Extended DataRelated data linked to or from the BMC Atrium CMDB.

CMDB RE Definitions AdminAn application role. Members can view, create, modify, and delete reconciliation definitions and can start and cancel jobs.

CMDB RE Manual IdentificationAn application role. Members can identify instances manually.

CMDB RE UserAn application role. Members can view reconciliation definitions and can start and cancel jobs.

cmdbdriverA utility that executes BMC Atrium CMDB C API functions from a command line, prompting for parameters.

Common Data Model (CDM)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)A definition of management information developed by the Distributed Management Task Force (DMTF) that facilitates the exchange of management information between systems.

Comparison activityA Reconciliation Engine activity that compares identified instances between two datasets, either producing a report that shows the differences or executing workflow.

configuration dataData about your IT environment, consisting of CIs and relationships.

configuration item (CI)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)A database that stores information about your IT configuration, including both CIs and relationships.

Glossary � 361


consumerAn application that works with data in the BMC Atrium CMDB. It might view the data or modify it. See also provider.

Copy Dataset activityA Reconciliation Engine activity that copies instances from one dataset to another.

CTISee Categories, Types, and Items (CTI).

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

datasetA 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 PrecedenceA pairing of a dataset with a Precedence group. Each Merge activity references a collection of these, called a Dataset Merge Precedence set.

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

Definitive Software Library (DSL)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 activityA 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.

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

discoveryThe act of scanning your environment for configuration data.

discovery applicationAn application that scans your environment for configuration data and can act as a provider to the BMC Atrium CMDB.

Distributed Management Task Force (DMTF)An organization appointed to facilitate the exchange of management information by promoting the initiation of industry standards and interoperability.

DMTFSee Distributed Management Task Force (DMTF).

DSLSee Definitive Software Library (DSL).

362 �Glossary


Enterprise Integration EngineThe 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.

eventA 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 ruleA rule that specifies an attribute to be excluded from participation in a Comparison activity.

Execute Job activityA Reconciliation Engine activity that executes a job.

extensionA logical set of classes and attributes, usually in its own namespace, that is not part of the Common Data Model (CDM).

extension loaderThe cmdbExtLoader program, which is used for installing data model extensions and importing other BMC Atrium CMDB data and metadata.

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

federated interfaceAn instance of the BMC_FederatedInterface class that specifies how to access a particular type of federated data. See also federated link.

federated linkThe connection between a class or CI and a federated interface.

federated productA product that holds federated data. It can be linked to more than one federated interface.

federationThe act of linking CIs in the BMC Atrium CMDB to external data.

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

filterA set of criteria for restricting the information displayed by the CI Relationship Viewer. This is different from an AR System filter.

final classA class that cannot have subclasses.

foreign key substitutionA 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


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

GUIDA 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 deleteThe act of removing an instance from the BMC Atrium CMDB.

Identification activityA Reconciliation Engine activity that matches instances from two or more datasets and assigns them the same identity, meaning that they represent the same real-life object.

Identification groupA 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 ruleA rule used when identifying instances between datasets. When two instances match the qualification for the rule, they are assigned the same reconciliation ID.

identitySee reconciliation ID.

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

instanceAn 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 IDA GUID that the BMC Atrium CMDB applies to each instance to uniquely identify it.

instance permissionsThe right to view or modify a specific instance. These permissions are called row-level security and write security, respectively.

ITILThe Information Technology Infrastructure Library (ITIL) is an internationally accepted set of best practices for management of IT services developed by the British government

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


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

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

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

parentSee source.

Precedence groupThe definition of an overall precedence value for a dataset. It can optionally contain precedence values for specific classes and attributes within the dataset.

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

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

providerAn application, often a discovery application, that loads bulk data into the BMC Atrium CMDB. See also consumer.

provisioningThe process of providing access to resources, such as printers, telephones, and such, and to information, such as permissions, databases, and so on.

publishTo make an event available so that instances of it can be written to the CMDB:Events form.

Purge Dataset activityA Reconciliation Engine activity that removes instances that have been marked as deleted from one or more datasets.

QualificationA Boolean statement that is evaluated to determine whether an instance should be included in an activity.

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

reconciliationThe 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


reconciliation definitionAn entity defined in the Reconciliation Manager such as a job, activity, or group.

Reconciliation EngineThe component of the BMC Atrium CMDB that reconciles data from different datasets.

reconciliation IDA GUID that the Reconciliation Engine assigns to instances in different datasets that represent the same real-life object.

Reconciliation ManagerThe component of the BMC Atrium CMDB that you can use to manage reconciliation definitions.

regular classA class that stores its instance data in its own AR System form. See also abstract class, categorization class.

related informationInformation about a CI that does not qualify as attributes of the CI, and should therefore not be stored in a Configuration Management Database (CMDB).

relationshipA connection between two CIs such as a dependency or membership. It is an instance of a relationship class. See also configuration item (CI).

relationship classA class that defines a type of relationship between CIs, such as a dependency or membership.

relationship filterSee filter.

Rename Dataset activityA reconciliation activity that renames a dataset without changing its ID, preserving references to the dataset from any reconciliation definitions.

roleA designation that grants permissions to more than one AR System group.

row-level securityThe permission required to view a specific instance. See also write security.

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

rulesetA group of rules.

service level agreementA contract between a service provider and a purchaser that defines the level of service.

singleton classAn optional class characteristic that restricts the class to holding only one instance.

snapshotA 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 deleteThe act of marking an instance as deleted from the BMC Atrium CMDB by setting the MarkAsDeleted attribute to Yes.

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

366 �Glossary


subclassA class that is derived from another class, which is called its superclass. The subclass inherits all the attributes of its superclass and any superclasses above it in the hierarchy, and can also participate in relationships defined for all superclasses.

superclassA class from which other classes, called subclasses, are derived.

synchronizationThe automatic process of creating AR System forms and workflow to represent a class that has just been created or modified. The class is not available until synchronization completes.

weak referenceSee weak relationship.

weak relationshipAn optional characteristic for relationship classes, signifying that the members of a relationship form a composite object that can be reconciled as one. The child member is considered the weak member of a weak relationship, existing as part of the parent member.

Windows Management Instrumentation (WMI)Microsoft's application of the Web-Based Enterprise Management initiative for an industry standard for accessing management information.

WMISee Windows Management Instrumentation (WMI).

workflowAR System objects such as active links, escalations, and filters that perform actions against data.

Workflow Execution groupA set of Workflow Execution rules. Each Comparison activity can optionally reference one Workflow Execution group.

Workflow Execution ruleA rule used when comparing instances between datasets. When a compared instance matches the qualification for the rule, specified AR System workflow is executed against the instance or the instance against which it is compared.

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

write securityThe permission required along with row-level security to modify or delete a specific instance.

Glossary � 367


368 �Glossary

Index

AActivateFederatedInContext operation 252activating federated instances 177, 216, 293active link error messages 327adjacency items, storing for graphs 268adjacency lists, representing graphs as 346adjacency matrixes, representing graphs as 346adjacent nodes, storing 208API logging 88AR System

CI Relationship Viewer and 70creating forms 142storing related federation data 215, 294transferring data

from CI Relationship Viewer 344to CI Relationship Viewer 342

architecture, CMDB API 16AROS string, replaced in object names 33ArrayOf_String structure 263attachLimits structure 191attachment limits, defining 191AttachmentLimit structure 282AttributeInfoIn structure 279AttributeInfoList structure 278AttributeLimit structure 281AttributeLimitList structure 286attributes

C API data structures 186creating 40, 96, 100, 242data structures 186

attributes (continued)deleting 103, 119, 240, 245expanding CI parameters 148exporting definitions with cmdbdriver 64installing extensions with cmdbExtLoader 61managing 95retrieving 104, 107, 241setting 111, 113, 244storing

attachment limits 282character limits 282currency limits 283data limits 281, 286date limits 284definitions 186enum limits 284index information 185, 276information 200information to retrieve 278information to set 279integer limits 285lists of values 279real data limits 285retrieval information 186sort information 195, 264sort information by type 264sources for propagation 194targets for propagation 194values 192, 193, 279

validating CI 147web services API data structures 278

Index � 369


AttributeValue structure 279AttributeValueList structure 279audience for this guide 10AuditInfo structure 296audits

data structures 218, 295functions 179operations 256retrieving CI instance logs 181retrieving modified CI instances 179, 256storing

class options 219, 296value lists 218, 219, 295

AuditValueList structure 295AuditValueListList structure 295

BBLOBs, retrieving instance 134BMC Atrium CMDB

accessing classes 87cmdbdriver program 50documents available for 10error messages

C API 298Console active link 327Console filter 334

exporting data 149importing data 149importing data with EIE 86installing extensions 63migrating data between servers 53programming 38programs

header files 32structure 38

storing version information 198, 286, 287tools 49–89utilities 49–89, 155, 260

bulk entriesbeginning transactions 139committing transactions 140ending transactions 140invoking API calls 139rolling back transactions 140transaction functions 139

CC API data structures

about 182attribute

about 186attachLimits 191charLimits 190CMDBAttributeGetStruct 186CMDBAttributeLimit 187CMDBAttributeNameId 192CMDBSortList 195CMDBSortStruct 195CMDBWeakPropagatedAttrs 194CMDBWeakPropagatedAttrsList 194currencyLimits 191dateLimits 191decimalLimits 190enumLimits 191integerLimits 190realLimits 190

auditabout 218CMDBAuditInfoStruct 219CMDBAuditValueList 218CMDBAuditValueListList 219

classabout 182CMDBClassRelationship 183CMDBClassTypeInfo 182CMDBIndexList 184CMDBIndexStruct 185

federationabout 215CMDBFederatedActivateInfo 216CMDBFederatedARInfo 215

general purposeabout 198CMDBClassNameId 196CMDBClassNameIdList 196CMDBQualifierStruct 197CMDBVersionInfo 198CMDBVersionInfoList 198

370 � Index


graph queryabout 206CMDBGetObjectList 206CMDBGetObjectStruct 206CMDBGetRelationList 207CMDBGetRelationStruct 207CMDBGraphAdjacentList 208CMDBGraphAdjacentStruct 208CMDBGraphList 209CMDBGraphStruct 209

import and exportabout 199CMDBExportItem 200CMDBExportItemList 201CMDBExportItemStruct 201CMDBImportItem 202CMDBImportItemList 203CMDBImportItemStruct 204CMDBItemTypeAttribute 200CMDBItemTypeClass 199CMDBXMLExportItemList 201CMDBXMLImportItemList 203

instanceabout 196CMDBAttributeValueList 192CMDBAttributeValueListList 193CMDBAttributeValueStruct 193

Reconciliation Engineabout 212CMDBREClassQualList 214CMDBREClassQualStruct 213CMDBREDatasetList 215CMDBREDatasetPair 214CMDBREJobRunInfo 213CMDBREJobRunInfoList 212

user interface componentabout 210CMDBUIComponentInfo 210CMDBUIComponentResult 211CMDBUIComponentResultList 212

C API functionsabout 95audit

about 179CMDBGetCopyAuditData 179

C API functions (continued)audit (continued)

CMDBGetLogAuditData 181bulk entry transaction

about 139CMDBBeginBulkEntryTransaction 139CMDBEndBulkEntryTransaction 140

data model managementabout 95CMDBCreateAttribute 96CMDBCreateClass 116CMDBCreateMultipleAttribute 100CMDBDeleteAttribute 103CMDBDeleteClass 119CMDBGetAttribute 104CMDBGetClass 120CMDBGetListClass 122CMDBGetMultipleAttribute 107CMDBSetAttribute 111CMDBSetClass 123CMDBSetMultipleAttribute 113

environmentabout 141CMDBGetServerPort 143CMDBInitialization 141CMDBSetServerPort 144CMDBSynchMetaData 142CMDBSystemInit 142CMDBTermination 145

federationabout 176CMDBActivateFederatedInContext 177CMDBGetRelatedFederatedInContext 1

76free

about 157FreeCMDBAttributeGetStruct 163FreeCMDBAttributeLimit 159FreeCMDBAttributeLimitList 160FreeCMDBAttributeLimitStruct 159FreeCMDBAttributeValueList 169FreeCMDBAttributeValueListList 169FreeCMDBClassNameIdList 158FreeCMDBClassTypeInfo 166

Index � 371


C API functions (continued)free (continued)

FreeCMDBExportItemList 162FreeCMDBExportItemStruct 161FreeCMDBGetObjectList 168FreeCMDBGetRelationList 167FreeCMDBGraphAdjacentList 164FreeCMDBGraphAdjacentStruct 164FreeCMDBGraphList 166FreeCMDBGraphStruct 165FreeCMDBImportItemList 162FreeCMDBIndexList 161FreeCMDBQualifierStruct 167FreeCMDBREJobRunInfoList 171FreeCMDBSortList 170FreeCMDBVersionInfoList 158

import and exportabout 149CMDBExport 149CMDBExportData 151CMDBExportDef 150CMDBImport 152CMDBImportData 154CMDBImportDef 153

instance managementabout 126CMDBCreateInstance 126CMDBDeleteInstance 127CMDBGetInstance 129CMDBGetInstanceBLOB 134CMDBGetListInstance 130CMDBGetMultipleInstances 132CMDBGraphQuery 135, 347CMDBSetInstance 138

Reconciliation Engineabout 172CMDBCancelJobRun 175CMDBGetJobRun 173CMDBGetListJobRun 174CMDBStartJobRun 172

user interface componentabout 146CMDBExpandParametersForCI 148CMDBGetCMDBUIComponents 146CMDBRunQualificationForCI 147

C API functions (continued)utility

about 155CMDBCreateGuid 155CMDBGetVersions 156

C API sessionsinitializing 141terminating 145

C APIsabout 17compilers 29components 17data structures 182driver source code 24error messages 298function calls 17function definitions 94functions 95header files 24installing package 24library files 25library links 30

callsC API function 17data structure changes 35debugging with data structure contents 89debugging with log information 88invoking bulk entry API 139

canceling reconciliation jobs 175, 251CancelJobRun operation 251character limits, defining 190CharLimit structure 282charLimits structure 190CI instances. See instancesCI Relationship Viewer

about 70AR System and 70configuring 77creating context menus 78creating definitions 82creating events 84embedding in AR System forms 73events

CIRV_LAYOUT 343CIRV_NOTIFY_AR 344

372 � Index


CI Relationship Viewer (continued)events (continued)

CIRV_REFRESH 343CIRV_SELECT_CI 343CIRV_SET_AS_ROOT 343CIRV_SET_CUSTOM_FILTER 342CIRV_SET_FILTER 342CIRV_SHOW 343SELECTED_CI 344

filters 77launching 71, 75opening 71, 75transferring data with events

from AR System 342to AR System 344

CIRV_LAYOUT event 343CIRV_NOTIFY_AR event 344CIRV_REFRESH event 343CIRV_SELECT_CI event 343CIRV_SET_AS_ROOT event 343CIRV_SET_CUSTOM_FILTER event 342CIRV_SET_FILTER event 342CIRV_SHOW event 343class forms

creating instances in 226setting instances in 225

classesaccessing BMC Atrium CMDB directly 87C API data structures 182configuration item

about 38creating 38creating attributes 40creating instances 42

creatingattributes 40with cmdbdriver program 50with core attributes 116, 237

data structures 182deleting 119, 240exporting

data with cmdbdriver 55definitions 149, 150definitions with cmdbdriver 55, 64qualified 151

classes (continued)importing

data 154data with cmdbdriver 57definitions 152, 153definitions with cmdbdriver 57

installing extensions with cmdbExtLoader 61managing 95relationship

about 44creating 44retrieving 238

retrieving 120, 122, 235retrieving list of UI components 146, 258setting properties 123, 236storing

attribute index information 185audit options 219CI definitions 182CI properties 275CI relationship information 273class names 192display properties 277display property structures 277index information 184, 276information to retrieve 273information to set 272names 196, 199, 263namespace names 192, 196, 263qualification information 291relationship definitions 182relationship information 183type information 182

web services API data structures 272ClassInfoIn structure 272ClassInfoOut structure 273ClassNameId structure 263ClassNameIdList structure 263ClassProperties structure 275ClassQualifier structure 291ClassQualifierList structure 291ClassRelationship structure 273CMDB APIs

about 16architecture 16

Index � 373


CMDB APIs (continued)C APIs 17call changes 35data structure changes 35function changes 34Java APIs 19logging option 88migrating to 33objects, deprecated 33objects, renamed 33parameter changes 34programming 20programs, when to write 20sample source code 32terminology changes 21web services APIs 18

CMDB Consoleactive link errors 327API programming and 20filter errors 334

CMDB. See BMC Atrium CMDBCMDBActivateFederatedInContext function 177CMDBAttributeGetStruct structure 186CMDBAttributeLimit structure 187CMDBAttributeNameId structure 192CMDBAttributeValueList structure 192CMDBAttributeValueListList structure 193CMDBAttributeValueStruct structure 193CMDBAuditInfoStruct structure 219CMDBAuditValueList structure 218CMDBAuditValueListList structure 219CMDBBeginBulkEntryTransaction function 139CMDBCancelJobRun function 175CMDBClassNameId structure 196CMDBClassNameIdList structure 196CMDBClassRelationship structure 183CMDBClassTypeInfo structure 182CMDBCreateAttribute function 96CMDBCreateClass function 116CMDBCreateGuid function 155CMDBCreateInstance function 126CMDBCreateMultipleAttribute function 100CMDBDeleteAttribute function 103CMDBDeleteClass function 119CMDBDeleteInstance function 127

cmdbdriver programabout 50exporting

class data 55class definitions 55instance data 56subclass definitions 55

importingclass data 57class definitions 57instance data 58

starting 54using from command line 50using on UNIX 52

CMDBEndBulkEntryTransaction function 140CMDBExpandParametersForCI function 148CMDBExport function 149CMDBExportData function 151CMDBExportDef function 150CMDBExportItem structure 200CMDBExportItemList structure 201CMDBExportItemStruct structure 201cmdbExtLoader program

about 61file structure 62starting 69

CMDBFederatedActivateInfo structure 216CMDBFederatedARInfo structure 215CMDBGetAttribute function 104CMDBGetClass function 120CMDBGetCMDBUIComponents function 146CMDBGetCopyAuditData function 179CMDBGetInstance function 129CMDBGetInstanceBLOB function 134CMDBGetJobRun function 173CMDBGetListClass function 122CMDBGetListInstance function 130CMDBGetListJobRun function 174CMDBGetLogAuditData function 181CMDBGetMultipleAttribute function 107CMDBGetMultipleInstances function 132CMDBGetObjectList structure 206CMDBGetObjectStruct structure 206CMDBGetRelatedFederatedInContext

function 176

374 � Index


CMDBGetRelationList structure 207CMDBGetRelationStruct structure 207CMDBGetServerPort function 143CMDBGetVersions function 156CMDBGraphAdjacentList structure 208CMDBGraphAdjacentStruct structure 208CMDBGraphList structure 209CMDBGraphQuery function 135, 347CMDBGraphStruct structure 209CMDBImport function 152CMDBImportData function 154CMDBImportDef function 153CMDBImportItem structure 202CMDBImportItemList structure 203CMDBImportItemStruct structure 204CMDBIndexList structure 184CMDBIndexStruct structure 185CMDBInitialization function 141CMDBItemTypeAttribute structure 200CMDBItemTypeClass structure 199CMDBQualifierStruct structure 197CMDBREClassQualList structure 214CMDBREClassQualStruct structure 213CMDBREDatasetList structure 215CMDBREDatasetPair structure 214CMDBREJobRunInfo structure 213CMDBREJobRunInfoList structure 212CMDBRunQualificationForCI function 147CMDBSetAttribute function 111CMDBSetClass function 123CMDBSetInstance function 138CMDBSetMultipleAttribute function 113CMDBSetServerPort function 144CMDBSortList structure 195CMDBSortStruct structure 195CMDBStartJobRun functions 172CMDBSynchMetaData function 142CMDBSystemInit function 142CMDBTermination function 145CMDBUIComponentInfo structure 210CMDBUIComponentResult structure 211CMDBUIComponentResultList structure 212CMDBVersionInfo structure 198CMDBVersionInfoList structure 198CMDBWeakPropagatedAttrs structure 194

CMDBWeakPropagatedAttrsList structure 194CMDBXMLExportItemList structure 201CMDBXMLImportItemList structure 203commands, cmdbdriver program 50committing bulk entry transactions 140compilers, C APIs 29components

C API 17web services API 19

configuration itemsSee also instancesclasses 38creating instances 42querying instances 47viewing relationships 70

context menus, creating 78CreateAttribute operation 242CreateClass operation 237CreateInstance operation 226CreateRelationInstance operation 229creating

AR System forms 142attributes 96, 100, 242CI classes 38CI Relationship Viewer

context menus 78definitions 82events 84

classes 116, 237classes with cmdbdriver program 50forms 142globally unique IDs 155installation activity file 67instances

CI 42, 126in class forms 226relationship 126with cmdbdriver program 50

instances relationship 229package.xml file 64relationship classes 44

currency limits, defining 191CurrencyLimit structure 283currencyLimits structure 191

Index � 375


Ddata

importing with EIE 86limits, defining 191

data modelsmanagement functions, C API 95managing 95operations, web services API 234

data structuresC API

about 182attribute 186audit 218class 182export 199federation 215general purpose 198graph query 206import 199instance 196Reconciliation Engine 212user interface component 210

CMDB API, changed 35printing contents 89web services API

about 262attribute 278audit 295class 272federation 293graph 267instance 262job 290user interface component 288utility 286

DatasetPair structure 292DatasetPairList structure 292DateLimit structure 284dateLimits structure 191debugging

calls with data structure contents 89calls with log information 88

debugging APIs 88decimal limits, defining 190decimalLimits structure 190

definingattachment limits 191character limits 190currency limits 191date limits 191decimal limits 190enum limits 191integer limits 190query graph lists 209real limits 190

definitionscreating CI Relationship Viewer 82exporting

attribute with cmdbdriver 64class 149, 150class with cmdbdriver 55, 64subclass with cmdbdriver 55

importingclass 152, 153class with cmdbdriver 57

storingattribute 186CI 182relationship 182

Delete Attribute operation 245DeleteClass operation 240DeleteInstance operation 228deleting

attributes 103, 245classes 119, 240instances 127, 228

deprecated CMDB API objects 33display properties, storing for classes 277documents, available for CMDB 10

EEIE, importing data with 86Enterprise Integration Engine. See EIEenum limits, defining 191EnumLimit structure 284enumLimits structure 191environment functions 141error messages

C API 298Console active link 327

376 � Index


error messages (continued)Console filter 334

eventscreating CI Relationship Viewer 84transferring from

AR System to CI Relationship Viewer 342CI Relationship Viewer to AR System 344

ExecuteJobRun operation 247expanding federated instances 177, 252exporting

attribute definitions with cmdbdriver 64C API data structures 199C API functions 149class

data with cmdbdriver 55data, qualified 151definitions 149, 150definitions with cmdbdriver 55, 64

CMDB data 149instance data with cmdbdriver 56storing data for 199subclass definitions with cmdbdriver 55

Ffeatures

Java API 19Web services API 18

FederatedActivateInfo structure 293FederatedARInfo structure 294federation

data structures 215, 293expanding instances 177, 252functions 176launching instances 177, 252operations 252retrieving instances 176, 254storing AR system data 215, 294storing instance activation data 216, 293

filtersCI Relationship Viewer 77error messages 334

forms, creating 142free functions 157FreeCMDBAttributeGetStruct function 163FreeCMDBAttributeLimit function 159

FreeCMDBAttributeLimitList function 160FreeCMDBAttributeLimitStruct function 159FreeCMDBAttributeValueList function 169FreeCMDBAttributeValueListList function 169FreeCMDBClassNameIdList function 158FreeCMDBClassTypeInfo function 166FreeCMDBExportItemList function 162FreeCMDBExportItemStruct function 161FreeCMDBGetObjectList function 168FreeCMDBGetRelationList function 167FreeCMDBGraphAdjacentList function 164FreeCMDBGraphAdjacentStruct function 164FreeCMDBGraphList function 166FreeCMDBGraphStruct function 165FreeCMDBImportItemList function 162FreeCMDBIndexList function 161FreeCMDBQualifierStruct function 167FreeCMDBREJobRunInfoList function 171FreeCMDBSortList function 170FreeCMDBVersionInfoList function 158functions

C APIaudit 179bulk entry transaction 139calls 17data model management 95environment 141federation 176free 157import and export 149instance management 126Reconciliation Engine 172user interface component 146utility 155

CMDB API, changed 34web services API 222

Ggeneral purpose data structures 198GetAttributes operation 241GetClass operation 235GetCopyAuditData operation 256GetInstances operation 223GetJobRun operation 248GetListJobRun operation 250

Index � 377


GetRelatedFederatedInContext operation 254GetUIComponents operation 258GetVersions operation 260Graph structure 267GraphAdjacency structure 268GraphAdjacencyList structure 268GraphList structure 267GraphQuery operation 231graphs

adjacency lists, collections of 346adjacency matrixes 346query data structures

C API 206web services API 267

representing 346storing adjacency items 268

Hheader files

C API 24CMDB program 32

Iicon, New 10IDs, creating globally unique 155import and export functions 149importing

C API data structures 199C API functions 149class

data 154data with cmdbdriver 57definitions 152, 153definitions with cmdbdriver 57

CMDB data 149data with EIE 86instance data with cmdbdriver 58storing data for 199

IndexInfo structure 276IndexList structure 276initializing

networks 142servers 142

installation activity file, creating 67installing

attribute extensions with cmdbExtLoader 61C API package 24class extensions with cmdbExtLoader 61CMDB extensions 63

InstanceInfo structure 265InstanceInfoList structure 264instances

See also configuration items and relationshipsC API management functions 126C API structures 196creating

CI 126configuration item 42in class forms 226relationship 126with cmdbdriver program 50

data operations 222data structures 262deleting 127, 228expanding CI parameters 148expanding federated 177, 252exporting data with cmdbdriver 56importing data with cmdbdriver 58launching federated 177management functions 126managing 126querying 47, 231retrieving

audit logs 181BLOBs 134CI audit data 179, 256federated 176list of 130, 223multiple 132single 129

retrieving federated 254searching for related 135setting CI 138setting in class forms 225setting relationship 138storing

CI 206data 196list of values 264relationship 207

378 � Index


instances (continued)storing (continued)

values 265structures 196viewing relationships 70web services API data structures 262web services API operations 222

integer limits, defining 190integerLimits attribute structure 190IntLimit structure 285

JJava APIs

about 19environment components 31features 19program requirements 31

JobRunInfo structure 290JobRunInfoList structure 291jobs. See reconciliation jobs

Kknown issues, migrating CMDB data 61

Llaunching

CI Relationship Viewer 71, 75federated instances 177, 252

libraryfiles, C API 25links, C API 30

limits, definingattachment 191character 190currency 191date 191decimal 190enum 191integer 190real 190

linking libraries, C API 30ListClasses operation 238log files, BMC Atrium CMDB 88logging option for API calls 88login information, storing 262

LoginInfo structure 262

Mmanaging

attributes 95classes 95data models 95instances 126reconciliation jobs 172

matrixes, representing graphs as 346memory, releasing 157menus, creating context 78migrating

CMDB data between servers 53known issues 61to BMC Atrium CMDB 2.0 API 33

Nnames

storing class 192, 196, 263storing namespace 192, 196, 263

networks, initializing 142New icon 10

OObjectQueryInfo structure 270ObjectQueryInfoList structure 269objects

deprecated from CMDB API 33renamed in CMDB API 33

opening, CI Relationship Viewer 71, 75operations, web services API

about 222audit 256data model 234federation 252reconciliation job 247storing status 265user interface component 258utility 260

OS string, replaced in object names 33

Index � 379


Ppackage.xml file, creating 64parameters

changed CMDB API 34expanding CI 148

portsretrieving 143setting 144

print.c file 89printing

data structure contents 89print.c file 89

programscmdbdriver program 50cmdbExtLoader 61

propagating attribute values 194PropInfo structure 277PropInfoList structure 277

Qqualifications, storing strings 197querying

C API graph query data structures 206instances 47instances related to CIs 231storing

CIs for 270graph list definitions for 209graph nodes for 209graphs for 267list of CIs for 269list of relationships for 270relationships for 271

Rreal data limits, defining 190RealLimit structure 285realLimits attribute structure 190Reconciliation Engine

C API data structures 212C API functions 172managing jobs 172

reconciliation jobscanceling 175, 251data structures 290

reconciliation jobs (continued)operations 247retrieving

data for running 173list of running 174, 250logs for running 173single running 248

starting 172, 247storing

all running 291datasets 214, 215, 292qualifications 213, 214running 212, 213single 290

RelationQueryInfo structure 271RelationQueryInfoList structure 270relationship instances, creating 229relationships

See also instancesclasses 44querying instances 47viewing 70

releasing memory 157renamed CMDB API objects 33retrieving

attributes 104, 107, 241audit data 179, 256audit logs 181classes 120, 122, 235federated instances 176, 254instance BLOBs 134instances 129, 130, 132, 223ports 143reconciliation jobs 173, 174, 248, 250relationship classes 238server ports 143UI component lists 146, 258version of CMDB components 156, 260

Ssamples

C API driver programs 24CMDB API source code 32

searching for instances 135SELECTED_CI event 344

380 � Index


server portsretrieving 143setting 144

serversinitializing 142retrieving ports 143setting ports 144

sessionsinitializing C API 141terminating C API 145

SetAttribute operation 244SetClass operation 236SetInstance operation 225setting

attributes 111, 113, 244class properties 123, 236instances 138instances in class forms 225ports 144server ports 144

sorting attributes 264sorting attributes by type 264SortOrder structure 264SortOrderList structure 264source code

C API driver 24sample CMDB API 32

SQL views 87starting

bulk entry transactions 139cmdbdriver program 54cmdbExtLoader program 69reconciliation jobs 172, 247

Status structure 265status, storing 265StatusList structure 265storing

adjacent nodes 208AR System federated data 215, 294attributes

attachment limits 282character limits 282currency limits 283data limits 281, 286date limits 284

storing (continued)attributes (continued)

definitions 186enum limits 284index information 185, 276information 200, 278, 279integer limits 285real data limits 285retrieval information 186sort information 195, 264sort information by type 264values 192, 193, 279

audit options 219, 296audit value lists 218, 219, 295CI definitions 182CI instances 206CIs to query 269, 270classes

CI properties 275CI relationship information 273data 182display properties 277display property structures 277index information 184, 276information to retrieve 273information to set 272names 192, 196, 199, 263namespace names 192, 196, 263qualification information 291type information 182

export data 199federated instance activation data 216, 293graph adjacency items 268graph nodes 209import data 199instance data 196instance values 264, 265items to export 200, 201items to import 202, 203, 204login information 262operation statuses 265qualification strings 197query graph list definitions 209query graphs 267reconciliation job datasets 214, 215, 292

Index � 381


storing (continued)reconciliation job qualifications 213, 214reconciliation jobs 290, 291relationships

definitions 182information 183instances 207to query 270, 271

running reconciliation jobs 212, 213source attributes 194strings 263target attributes 194UI component information 289UI component query results 211, 212, 289UI components to retrieve 210, 288versions of CMDB components 198, 286, 287XML items to export 201XML items to import 203

strings, storing 263structures. See data structuressubclasses, exporting definitions 55

Tterminating C API sessions 145terminology

changes 21CMDB and API 21

tools, CMDB 49–89

UUI components. See user interface componentsUIComponentInfo structure 288UIComponentResult structure 289UIComponentResultList structure 289user interface components

data structures 210functions 146operations 258retrieving list of 146, 258storing

information 289query results 211, 212, 289to retrieve 210, 288

web services API data structures 288user login information, storing 262

utilitiesCMDB 49–89, 155, 260functions 155operations 260web services API data structures 286

Vvalidating attributes, CI 147VersionInfo structure 287VersionInfoList structure 286versions, retrieving CMDB component 156, 260viewing

configuration item relationships 70instance relationships 70

views, SQL 87

Wweb services API data structures

attributeabout 278AttachmentLimit 282AttributeInfoIn 279AttributeInfoList 278AttributeLimit 281AttributeLimitList 286AttributeValue 279AttributeValueList 279CharLimit 282CurrencyLimit 283DateLimit 284EnumLimit 284IntLimit 285RealLimit 285

auditabout 295AuditInfo 296AuditValueList 295AuditValueListList 295

classabout 272ClassInfoIn 272ClassInfoOut 273ClassProperties 275ClassRelationship 273IndexInfo 276

382 � Index


web services API data structures (continued)class (continued)

IndexList 276PropInfo 277PropInfoList 277

federationabout 293FederatedActivateInfo 293FederatedARInfo 294

graphabout 267Graph 267GraphAdjacency 268GraphAdjacencyList 268GraphList 267ObjectQueryInfo 270ObjectQueryInfoList 269RelationQueryInfo 271RelationQueryInfoList 270

instanceabout 262ArrayOf_String 263ClassNameId 263ClassNameIdList 263InstanceInfo 265InstanceInfoList 264LoginInfo 262SortOrder 264SortOrderList 264Status 265StatusList 265

jobabout 290ClassQualifier 291ClassQualifierList 291DatasetPair 292DatasetPairList 292JobRunInfo 290JobRunInfoList 291

user interface componentabout 288UIComponentInfo 288UIComponentResult 289UIComponentResultList 289

web services API data structures (continued)utility

about 286VersionInfo 287VersionInfoList 286

web services API operationsaudit

about 256GetCopyAuditData 256

data modelabout 234CreateAttribute 242CreateClass 237Delete Attribute 245DeleteClass 240GetAttributes 241GetClass 235ListClasses 238SetAttribute 244SetClass 236

federationabout 252ActivateFederatedInContext 252GetRelatedFederatedInContext 254

instance dataabout 222CreateInstance 226CreateRelationInstance 229DeleteInstance 228GetInstances 223GraphQuery 231SetInstance 225

reconciliation jobabout 247CancelJobRun 251ExecuteJobRun 247GetJobRun 248GetListJobRun 250

user interface componentabout 258GetUIComponents 258

utilityabout 260GetVersions 260

Index � 383


web services APIsabout 18components 19data structures 262features 18functions 222operations 222

384 � Index

*64742**64742**64742**64742*

*64742*

CMDB2.0.1_DevelopersReferenceGuide

Documents

Transcript of CMDB2.0.1_DevelopersReferenceGuide